App_t Class Reference

Application base class. More...

#include <UTApp.h>

Inheritance diagram for App_t:
MessageLoop_t Thread_t BTreeNode_t< MessageLoop_t, MessageLoop_t * > LinkedListNode_t< Thread_t >

List of all members.

Public Member Functions

 App_t (int app_name_string_resource_id)
virtual ~App_t ()
virtual void Start (int32 stack_size=0)
virtual void SetTimeout (int32 timeout_ms)
void MessageMightHaveTakenALongTime ()
void SetMDIMode (bool enable_mdi, window_show_mode_t mode=eWINSHOWMODE_maximized, const Rect_t &normal_mode_mdi_frame=Rect_t(0, 0, 0, 0))
bool MDIMode ()
Rect_t NormalModeMDIFrame ()
window_show_mode_t MDIWindowMode ()
void SetAppMenu (Menu_t *menu)
Menu_tAppMenu ()
MessageDestination_t< Message_tQuitRequestReceiver ()
virtual void QuitRequested ()
virtual void CloseAllWindowsRequested (bool app_quit_requested)
bool RunningInMain ()
virtual bool IsQuitInProgress ()
virtual void CancelQuit ()

Static Public Member Functions

static App_tApp ()
static Resource_tAppResources ()
static void GetAppName (String_t *name)

Protected Member Functions

virtual void Main ()
virtual void SetMessageAvailEvent ()

Detailed Description

Non-core library: UTgui

Application base class which runs in the main thread context and can own one or more root level windows. Before beginning implementation of an application, see GUI Design for a detailed discussion of the GUI model used and provided by the UTgui library.

When the last window has been closed, the application should usually exit unless there is another means for the user to restore access to the user interface, for example a deskbar / taskbar icon.

An application subclass for an application using resources should generally include, as a member variable accessible using an inline function, a resource object for itself. Because an application object should be created and deleted in main, usually as a local variable in main, the resource will likewise be created and deleted at a safe time. Most applications should use resources for language localization. Because the resource class is thread-safe once it has been instantiated, application code need not deal with locking the resources.

Definition at line 50 of file UTApp.h.

Constructor & Destructor Documentation

App_t::App_t ( int  app_name_string_resource_id  ) 

Application constructor. The model should generally be a user preference. Since the model cannot be changed dynamically, if the user changes the preferred model, the application should inform the user by way of a modal dialog that quitting and restarting the application is required for the change to take effect. The application's thread base class will be registered as the main thread.

virtual App_t::~App_t (  )  [virtual]


Member Function Documentation

virtual void App_t::Start ( int32  stack_size = 0  )  [virtual]

Starts the application running. Start will not return until the application is ready to exit, since the applicaton runs in the main thread. Start must be called from the main thread.

Reimplemented from MessageLoop_t.

virtual void App_t::SetTimeout ( int32  timeout_ms  )  [virtual]

App_t does not support timeouts, so overrides MessageLoop_t::SetTimeout to report an error.

Reimplemented from MessageLoop_t.

void App_t::MessageMightHaveTakenALongTime (  ) 

To ensure performance the debug builds assert that the application's main loop must return to its idle state at least every 400 ms when not running in a debugger. Because up to 10 UT messages may be dispatched at a time though, running, sleeping, or blocking for more than 40 ms can end up causing an assertion failure. Usually, this indicates a design flaw, where the application thread is performing work that should have been delegated to a worker thread. In the rare case that this is expected and acceptable, calling this function after a message of expected long duration has been dispatched will prevent the assertion failure from occurring.

App_t * App_t::App (  )  [inline, static]

Returns a pointer to the singleton application object.

Definition at line 268 of file UTApp.h.

Resource_t * App_t::AppResources (  )  [inline, static]

Returns a resource object representing the application.

Definition at line 275 of file UTApp.h.

static void App_t::GetAppName ( String_t name  )  [static]

Obtains the application name, language localized using the current locale and the resource ID specified in the App_t constructor.

void App_t::SetMDIMode ( bool  enable_mdi,
window_show_mode_t  mode = eWINSHOWMODE_maximized,
const Rect_t normal_mode_mdi_frame = Rect_t(0, 0, 0, 0) 

Sets the app into MDI or non-MDI mode. On Linux or MacOS, this does nothing since Linux does not support MDI mode while MacOS supports only MDI mode. An application menu must have been created when this function is called. If the normal mode frame is 0,0,0,0 then the frame will be set to the screen dimensions, slightly recessed. In the absence of a user preference from a previous run, 0,0,0,0 should be used.

bool App_t::MDIMode (  ) 

Returns whether the application is running in MDI mode or not.

Rect_t App_t::NormalModeMDIFrame (  ) 

Returns the normal mode MDI frame, but the application must be in MDI mode or an assertion failure will occur. If the MDI frame is maximized, returns the frame if the MDI frame window had been in normal mode.

window_show_mode_t App_t::MDIWindowMode (  ) 

Returns whether the MDI window is in normal, minimized, or maximized mode. The application must be in MDI mode or an assertion failure will occur.

void App_t::SetAppMenu ( Menu_t menu  ) 

Sets the application menu, which is combined with the focus window menu if it has one to create the window menu(s). If the application already had a menu, it will be deleted.

Menu_t * App_t::AppMenu (  )  [inline]

Returns a pointer to the application menu.

Definition at line 282 of file UTApp.h.

MessageDestination_t<Message_t> App_t::QuitRequestReceiver (  ) 

Returns the message receiver to which application quit request messages should be sent.

virtual void App_t::QuitRequested (  )  [virtual]

Called when a quit request has been received. The default implementation calls QuitRequested in all windows, then calls MessageLoop_t::QuitRequested to make the same request for all tasks. If any window or task responds with eQUIT_denied, the message loop will not quit. If any window or task responds with eQUIT_deferred it is considering whether to quit, and a response will be provided later.

Derived classes must always call MessageLoop_t::QuitRequested in order to actually make the message loop quit. This would be done after all derived class considerations have determined that it is now time to quit. Derived class considerations would be things like requesting all windows to quit before other types of tasks receive the same request.

Reimplemented from MessageLoop_t.

virtual void App_t::CloseAllWindowsRequested ( bool  app_quit_requested  )  [virtual]

Called when the windows menu "close all windows" item is selected. The default implementation requests to close all windows in most to least recently used order. If a different order needs to be implemented, this function can be overridden.

bool App_t::RunningInMain (  )  [inline]

Returns true if the application object is currently running inside its Main function.

Definition at line 289 of file UTApp.h.

virtual bool App_t::IsQuitInProgress (  )  [virtual]

Indicates whether the application is quitting, or has a deferred quit decision pending. Derived classes may override this function to indicate that quit is in progress even if App_t::QuitRequested has not been called. In that case, the derived class's quit state machine must call App_t::QuitRequested eventually when the derived class decides it is time to quit.

Reimplemented from MessageLoop_t.

virtual void App_t::CancelQuit (  )  [virtual]

Cancels any quit and/or close all windows request which may be in progress.

Reimplemented from MessageLoop_t.

virtual void App_t::Main (  )  [protected, virtual]

Message loop thread entry point. This message loop runs in the main thread (having been registered using Thread_t::RegisterMainThread), so Start will call Main directly and not return until Main does.

Reimplemented from MessageLoop_t.

virtual void App_t::SetMessageAvailEvent (  )  [protected, virtual]

Notifies the message loop that a message has been queued.

Reimplemented from MessageLoop_t.

The documentation for this class was generated from the following file:

Generated on Tue Dec 14 22:35:06 2010 for UT library by  doxygen 1.6.1