Wx::App

From WxPerl wiki

The Wx::App class represents the application itself. It is used to:

• set and get application-wide properties;
• implement the windowing system message or event loop;
• initiate application processing via #OnInit;
• allow default processing of events not handled by other objects in the application.

Every wxPerl program needs to include a class that is derived from Wx::App, and to create one object of that class, and to call that object's #MainLoop method.

The Wx::App-derived class should not override the #new constructor. Instead, it must provide a #OnInit method (which will usually create the application's main window and so on). The class may provide an #OnExit method to clean up anything initialized in #OnInit.

Contents 1 Example 2 Constructor 2.1 new 3 Methods 3.1 GetInstance 3.2 GetTopWindow 3.3 IsActive 3.4 IsMainLoopRunning 3.5 MainLoop 3.6 OnExit 3.7 OnInit 3.8 SetTopWindow 3.9 Yield 4 Little-used Methods 4.1 Dispatch 4.2 ExitMainLoop 4.3 GetAppName 4.4 GetClassName 4.5 GetExitOnFrameDelete 4.6 GetUseBestVisual 4.7 GetVendorName 4.8 Pending 4.9 SetAppName 4.10 SetClassName 4.11 SetExitOnFrameDelete 4.12 SetInstance 4.13 SetUseBestVisual 4.14 SetVendorName 5 Unimplemented Methods 6 See Also

Example

This is a typical Wx::App class.

It overrides #OnInit to initialize the application. Generally, this simply involves createing a top-level window (frame). And usually, the best way to do that is with a custom frame class that is derived from Wx::Frame.

package MyExampleApp;
use base 'Wx::App';      # Must inherit from Wx::App

# Must override OnInit
sub OnInit
{
    my $self = shift;

    # Create a top-level window
    my $frame = MyExampleFrame->new;

    # Show it
    $frame->Show(1);

    # Indicate success
    return 1;
}

The main program will simply instantiate this class and call its #MainLoop method:

package main;
my $app = MyExampleApp->new;
$app->MainLoop;

Constructor

new

$app = Wx::App->new;

This is the constructor. It accepts no option. You should not override the constructor. Instead, override the #OnInit method to do any needed initialization.

Methods

GetInstance

$app = Wx::App::GetInstance();

Returns the global application object; the Wx::App-drived object that is running the message loop. Note that this is a global (class) function, not a method.

GetTopWindow

$frame = $app->GetTopWindow;

Returns a reference to the top window frame.

IsActive

$what = $app->IsActive;

Returns true if the application is active, i.e. if one of its windows is currently in the foreground. If this function returns false and you need to attract users attention to the application, you may use wxTopLevelWindow::RequestUserAttention to do it.

IsMainLoopRunning

$bool = $app->IsMainLoopRunning;

Returns true if the main event loop is currently running, i.e. if the application is inside #OnRun.

This can be useful to test whether the events can be dispatched. For example, if this function returns false, non-blocking sockets cannot be used because the events from them would never be processed.

MainLoop

$retval = $app->MainLoop;

Invoke this on creation of the application.

Returns 0 under X; returns the wParam of the WM_QUIT message under Windows.

OnExit

sub OnExit {...}

You may define an OnExit method in your Wx::App-derived class, and it will be called upon exit from the message loop (that is, when the application exits).

This method is invoked after all application windows and controls are destroyed; it is not called at all if #OnInit fails.

OnInit

sub OnInit {...}

Your application I<must> provide this method. Typically, this method will simply create a top-level Wx::Frame object (that is, a main window), but you can do any other needed initialization here.

This method should return a true value if it succeeds. If it returns a false value, the application will exit immediately.

SetTopWindow

$app->SetTopWindow($window);

Sets the 'top' window. You can call this from within #OnInit to let wxWidgets know which is the main window.

You don't have to set the top window; it is only a convenience so that (for example) certain dialogs without parents can use a specific window as the top window. If no top window is specified by the application, wxPerl just uses the first frame or dialog in its top-level window list, when it needs to use the top window.

Yield

$app->Yield;

Yields control to pending messages in the windowing system. This is useful if a time-consuming process is underway. Without an occasional Yield(), the application will not respond to events, and will appear to be locked.

Beware that yielding may allow the user to perform actions (such as pressing buttons, selecting menu actions) that are not compatible with the current task. Take care not to let your application get into a confused state.

Little-used Methods

Dispatch

$app->Dispatch();

Dispatches the next event in the windowing system event queue.

This can be used for programming event loops:

while ($app->Pending)
{
    $app->Dispatch;
}

ExitMainLoop

Exits the app's main message loop. This should normally be done by closing the top window (frame).

GetAppName

$name = $app->GetAppName;

Returns whatever was set by #SetAppName, or the class name of $app, if SetAppName has not been called.

GetClassName

$name = $class->GetClassName;

Returns whatever was set by #SetClassName, or the empty string if SetClassName has not been called.

GetExitOnFrameDelete

$bool = $app->GetExitOnFrameDelete;

Returns true if the application will exit when the top-level window is deleted, false otherwise.

GetUseBestVisual

$bool = $app->GetUseBestVisual;

Returns true if the application will use the best visual on systems that support different visuals, false otherwise.

GetVendorName

$string = $app->GetVendorName;

Returns whatever was set by #SetVendorName, or the empty string if SetVendorName has not been called.

Pending

$bool = $app->Pending;

Returns true if unprocessed events are in the window system event queue.

SetAppName

$app->SetAppName($name);

Sets a name to be returned by #GetAppName.

SetClassName

$class->SetClassName($name);

Sets a name to be returned by #GetClassName.

SetExitOnFrameDelete

$app->SetExitOnFrameDelete($flag);

Specifies whether the application will exit when the top-level frame (window) is deleted. If $flag is true, it will. If $flag is false, the application will continue to run.

SetInstance

$app->SetInstance($new_app);

Sets a new global application object. Calling this method is probaby a Very Bad Idea unless you really Know What You Are Doing.

SetUseBestVisual

$app->SetUseBestVisual($flag, $forceTrueColor);

Allows the programmer to specify whether the application will use the best visual on systems that support several visual on the same display. This is typically the case under Solaris and IRIX, where the default visual is only 8-bit whereas certain applications are supposed to run in TrueColour mode.

If $forceTrueColour is true then the application will try to force using a TrueColour visual and abort the app if none is found.

Note that this function has to be called in the constructor of the wxApp instance and won't have any effect when called later on.

This function currently only has effect under GTK.

SetVendorName

$app->SetVendorName($vendor);

Sets the application's vendor name, to be returned by #GetVendorName.

Unimplemented Methods

The following wxWidgets methods do not exist in wxPerl's implementation of Wx::App, usually because Perl provides much better ways of doing these things.

• argc -- Use @ARGV instead.
• argv -- Use @ARGV instead.
• CreateLogTarget
• CreateTraits
• FilterEvent
• GetTraits
• OnAssertFailure
• OnCmdLineError
• OnCmdLineHelp
• OnCmdLineParsed
• OnExceptionInMainLoop
• OnFatalException
• OnInitCmdLine
• OnRun -- I think overriding this method does nothing.
• OnUnhandledException
• ProcessMessage

See Also

wxApp overview:

C++-oriented documentation