Library ui_lib: Class AppBase

All Classes, All Libraries

Index: A | B | C | D | E | F | G | H | I | J | K | L | M | N | O | P | Q | R | S | T | U | V | W | X | Y | Z

Every application contains an AppBase object. The AppBase object is the top object in an application's UI hierarchy ; all the FlexFrames, FlexDialogs, and other windows in an application are children of the application's AppBase object. Additionally, AppBase objects have member functions that applications can override to know when to build and destroy the application UI. It also contains mechanisms and API for manipulating user interface concepts such as the keyboard focus, pen grab, and active window. As is the case with all UI components, the AppBase member functions must be invoked on an application's first (main) thread.

This is an abstract class and cannot be directly instantiated.

#include <ui/appbase.h>

• Class Data and Methods
  • Inherited Data and Methods
• Ancestors
• Descendants
• Descriptions of Class Data and Methods

Class Data and Methods

Back to the top of AppBase

Ancestors

• FlexContainer
  • FlexComponent

Back to the top of AppBase

Descendants

• ShellAppBase

Back to the top of AppBase

Class constructor - the default constructor sets the state to AS_UNLOADED. There is no associated WindowManager (so many of the functions like SetFocus() will not work) until after Init() is invoked.

Prototype:

    AppBase();

Back to the top of AppBase

~AppBase();

Class destructor.

Prototype:

    ~AppBase();

Back to the top of AppBase

enum AppState;

AppState is an enumerated type that describes the current state of the application.

AS_UNLOADED

The state when the application is not currently loaded

AS_BACKGROUND

The state when the application has been loaded via ApplicationCache::Goto(), perhaps in response to an alarm, but has never been brought to the foreground.

AS_CACHED

The application has been brought to the foreground, but is no longer the foreground application.

AS_ACTIVE

The application is the active application (the one that receives user input when no sysmodal dialogs are onscreen).

AS_EXITING

The application is exiting, and will be unloaded the next time the thread goes idle unless it is sent to one of the other states via ApplicationCache::Goto() or SwitchTo().

Declared as:

    enum AppState {
        AS_UNLOADED,
        AS_BACKGROUND,
        AS_CACHED,
        AS_ACTIVE,
        AS_EXITING
    };

Back to the top of AppBase

Result AddFocusChangeListener(FocusChangeListenerInterface& listener);

Called to register a listener that is notified whenever the focus changes under this application.

Parameters:

in listener

Listener object to register.

See also: RemoveFocusChangeListener(), SetFocus(), GetFocus()

Prototype:

    Result AddFocusChangeListener(FocusChangeListenerInterface& listener);

Back to the top of AppBase

Result AddInkListener(InkListenerInterface& listener);

AddInkListener is called to register objects to be notified when the user begins drawing ink. For example, menus tend to close themselves when either a mouse event or ink drawing begins, so open menus often override this member function.

Parameters:

in listener

The listener to register for ink events.

See also: RemoveInkListener()

Prototype:

    Result AddInkListener(InkListenerInterface& listener);

Back to the top of AppBase

Result AddTargetChangeListener(TargetChangeListenerInterface& listener);

AddTargetChangeListener is called to register a listener that is notified whenever the target changes under this application.

Parameters:

in listener

Listener object to register.

See also: RemoveTargetChangeListener(), SetTarget(), GetTarget()

Prototype:

    Result AddTargetChangeListener(TargetChangeListenerInterface& listener);

Back to the top of AppBase

Result AddWindowListener(WindowListenerInterface& listener);

AddWindowListener is called to register a listener to receive window events for this application (WINDOW_CLOSED, WINDOW_OPENED, WINDOW_TO_FRONT, WINDOW_TO_BACK).

Note that AppBase is not really a subclass of FlexWindow(), so the source field for these WindowEvent objects will be NULL. Listeners can always get a pointer to the AppBase by invoking AppBase::GetAppBase().

Parameters:

in listener

Listener object to register.

See also: RemoveWindowListener()

Prototype:

    Result AddWindowListener(WindowListenerInterface& listener);

Back to the top of AppBase

void Exit(void);

Exit() is invoked by the ApplicationCache when an application is being unloaded, to give the application an opportunity to destroy the UI built via SetAppContext() and, generally, to clean up and prepare for unloading. The default handler for Exit() frees up all the children of the AppBase object, and sets a flag so the application will exit the next time the thread goes idle.

Exit() can be overridden to provide app-specific behavior (such as freeing EventListeners and LayoutManagers, and other associated non-UI objects), but the baseclass handler should always be invoked, otherwise the app will remain loaded.

An application can also override this function and return without calling the base class, and in that case the application will not exit. This is useful when writing an application that should always be resident - applications that only wish to temporarily prevent unloading should invoke ApplicationCache::PreventUnloading().

Applications can also invoke Exit() on their own AppBase object, to force the application to unload - this is typically useful if an error occurs while starting up the app.

See also: SetAppContext()

Prototype:

    virtual void Exit(void);

Back to the top of AppBase

Result FlushInput(void);

Sets an internal flag so that all input messages that are currently on the application thread's MessageQueue will be ignored. Input messages that arrive *after* FlushInput() is called will be processed normally.

Return value: SUCCESS if input is being flushed, else FAILURE if input could not be flushed due to lack of memory.

Prototype:

    static Result FlushInput(void);

Back to the top of AppBase

AppBase *GetAppBase(void);

GetAppBase returns a pointer to the appbase for the current thread, or NULL if there is no appbase for this thread

Return value: Pointer to an AppBase object, or NULL.

See also: Thread::GetAppBase()

Prototype:

    static AppBase *GetAppBase(void);

Back to the top of AppBase

TCHAR *GetAppContext(void);

Returns a pointer to a context string that describes the current state of an app. When the app is reloaded and brought to the foreground, this string is passed to the SetAppContext() handler. The idea is that if the app is unloaded and reloaded, given the context string it should be able to return to the same state from the user's perspective.

Return value: A pointer to a string describing the current context. This is freed by the caller if non-NULL. If the application always displays the same UI (like an About box or a system status box), then this need not be subclassed -- the default handler returns NULL.

See also: SetAppContext()

Prototype:

    virtual TCHAR *GetAppContext(void);

Back to the top of AppBase

uint32 GetDesiredStackSize(void) const;

Invoked when an application is being loaded. It is overridden by the application if it wants a non-standard stack size (a very simple application may want a smaller stack than normal, while a very complex application may need a deeper stack).

Return value: Stack size in bytes

See also: Thread::Start()

Prototype:

    virtual uint32 GetDesiredStackSize(void) const;

Back to the top of AppBase

FlexComponent *GetFocus(void);

Called to find out which object currently has the focus.

The "focus" is the object that will receive all incoming keyboard input.

Return value: The object that has the focus.

See also: SetFocus()

Prototype:

    static FlexComponent *GetFocus(void);

Back to the top of AppBase

AppState GetState(void) const;

Returns the current state of the application.

Return value: AppState (the state of the application).

See also: SetState(), AppState

Prototype:

    AppState GetState(void) const;

Back to the top of AppBase

Thread *GetThread(void) const;

Returns a pointer to the thread associated with this application (the thread that is dispatching events from the MessageQueue associated with this application).

Return value: Pointer to the thread associated with this application.

See also: GetMessageQueue()

Prototype:

    Thread *GetThread(void) const;

Back to the top of AppBase

FlexComponent *GetTarget(void);

Called to find out which object currently has the target. The default is NULL, and this routine will return NULL unless a target is explicitly set via SetTarget().

The target is used on devices that support clipboards - the target is the object that will receive cut/copy/paste requests.

Return value: The object that has the target.

See also: SetTarget()

Prototype:

    static FlexComponent *GetTarget(void);

Back to the top of AppBase

const TCHAR *GetUAL(void) const;

Returns a pointer to the UAL for this application. This is a string that uniquely identifies this application and can be passed to various ApplicationCache API to switch to/from this application.

Return value: Pointer to the UAL string for this application. The pointer is guaranteed to be valid for the life of this application.

Prototype:

    const TCHAR *GetUAL(void) const;

Back to the top of AppBase

Boolean HandleUndispatchedMessage(Message *msg);

Invoked by the message dispatch loop when a message is retrieved from the app's MessageQueue, but the message type was unknown to the default handler. This can be overridden to provide handling of custom message types, in the same way that MessageQueue::DispatchMessage() is overridden.

Parameters:

in msg

The most recent message to have been pulled from the queue.

See also: MessageQueue::DispatchMessage()

Prototype:

    virtual Boolean HandleUndispatchedMessage(Message *msg);

Back to the top of AppBase

void Idle(void);

Invoked when the application is idle (there are no more messages in the message queue).

Applications can override this to perform operations at idle time (such as updating status bars).

Prototype:

    virtual void Idle(void);    

Back to the top of AppBase

void Lower(void);

Invoked by the ApplicationCache when another application has been brought to the foreground (made this one inactive). This can be subclassed by applications if they are interested in tracking when they are the active app, with the caveat that Lower() is not invoked synchronously with another app becoming active.

See also: Raise()

Prototype:

    virtual void Lower(void);

Back to the top of AppBase

void ProcessFocusChangeEvent(FocusChangeEvent& e);

ProcessFocusChangeEvent is called to dispatch a FocusChangeEvent to any registered listeners when the focus changes.

This is not invoked synchronously with the call to SetFocus, as giving an object the focus (such as a window) may then cause another object to get the focus immediately thereafter. To avoid a flood of spurious updates, we enqueue a message and notify the listeners after the set focus calls have returned.

Parameters:

in e

The FocusChangeEvent.

Prototype:

    virtual void ProcessFocusChangeEvent(FocusChangeEvent& e);

Back to the top of AppBase

void ProcessInkEvent(InkEvent& e);

ProcessInkEvent() is invoked by the AppBase when the user begins and finishes drawing ink under an application.

Parameters:

in e

An InkEvent that describes the action that has just occurred.

Prototype:

    virtual void ProcessInkEvent(InkEvent& e);

Back to the top of AppBase

void ProcessTargetChangeEvent(TargetChangeEvent& e);

Called to dispatch a TargetChangeEvent to any registered listeners when the focus changes.

This is not invoked synchronously with the call to SetTarget, as giving an object the focus (such as a window) may then cause another object to get the focus immediately thereafter. To avoid a flood of spurious updates, we enqueue a message and notify the listeners after the set focus calls have returned.

Parameters:

in e

The TargetChangeEvent.

Prototype:

    virtual void ProcessTargetChangeEvent(TargetChangeEvent& e);

Back to the top of AppBase

void ProcessWindowEvent(WindowEvent &e);

Invoked to generate window events to notify the application (and any listeners) when the appbase object has become active, closed, etc.

Parameters:

in e

WindowEvent to pass to listeners.

Prototype:

    virtual void ProcessWindowEvent(WindowEvent &e);

Back to the top of AppBase

void Raise(void);

Invoked by the ApplicationCache when this application has come to the foreground. This can be subclassed by applications if they are interested in tracking when they are the active app, with the caveat that Raise() and Lower() are not invoked synchronously with another app becoming active/inactive.

See also: Lower()

Prototype:

    virtual void Raise(void);

Back to the top of AppBase

void RemoveFocusChangeListener(FocusChangeListenerInterface& listener);

Called to unregister a listener that was registered using AddFocusChangeListener().

Parameters:

in listener

Listener object to unregister.

Prototype:

    void RemoveFocusChangeListener(FocusChangeListenerInterface& listener);

Back to the top of AppBase

void RemoveInkListener(InkListenerInterface& listener);

Called to unregister objects that were previously registered to receive InkEvents via AddInkListener().

Parameters:

in listener

Listener object to unregister.

Prototype:

    void RemoveInkListener(InkListenerInterface& listener);

Back to the top of AppBase

void RemoveTargetChangeListener(TargetChangeListenerInterface& listener);

Called to unregister a listener that was registered using AddTargetChangeListener().

Parameters:

in listener

Listener object to unregister

Prototype:

    void RemoveTargetChangeListener(TargetChangeListenerInterface& listener);        

Back to the top of AppBase

void RemoveWindowListener(WindowListenerInterface& listener);

Called to unregister a listener that was previously registered via AddWindowListener().

Parameters:

in listener

Listener object to unregister.

Prototype:

    void RemoveWindowListener(WindowListenerInterface& listener);

Back to the top of AppBase

void SetAppContext(const TCHAR *context) ;

Used to restore an application to a certain state. It could also potentially be used to execute tasks in other applications (such as look up an entry in the address book application). If the application always displays the same UI, the passed context may be ignored.

Here's a basic summary of when SetAppContext() will be invoked:

1) You will *always* get a SetAppContext() call when your app is loaded, either case 2 or case 3 below.

2) If your app was loaded via AppliationCache::SwitchTo(), SetAppContext() is invoked with the last saved context. Subsequent calls to SwitchTo() will not cause new SetAppContext() calls.

3) If your app was loaded via ApplicationCache::Goto(), the string passed to Goto() is passed to your app. Every call to Goto() will result in a new SetAppContext() invocation on your app. In addition, if your app is *loaded* via Goto() (as opposed to having Goto() invoked on it while it is already running), the first time it is brought to the foreground via ApplicationCache::SwitchTo(), it will get another SetAppContext() call as described in case #2.

4) Once an app has processed an Exit() call by allowing the base AppBase::Exit() to execute, it is treated as being unloaded, so the next SwitchTo() call will cause a new SetAppContext() invocation.

AppBase::Exit() will free up any FlexComponent objects that are children of the AppBase object. Any other dynamically created objects that are not children of the AppBase object (such as LayoutManagers, or UI objects that are not added to the AppBase linkage) must be manually freed by the application itself in its Exit() handler.

Parameters:

in context

The new context that the application should display (freed by the caller when handler returns). NULL will be passed if no context has been stored for this application (for example, if this is the first time the app has been launched).

Prototype:

    virtual void SetAppContext(const TCHAR *context) = 0;

Back to the top of AppBase

FlexComponent *SetFocus(FlexComponent *focusObj);

Called to give a UI object the focus, which means that the object will now receive all keyboard events received by this application. This is generally called by the UI as a result of a new window being brought to the foreground, or due to the user clicking on a new object, but this can also be called by applications.

FlexComponent::ProcessFocusEvent() is invoked on both the new and old focused objects, to notify them that they have gained or lost the focus. If the new object is not focusable for some reason (perhaps because there is a modal dialog on screen or because the object itself is not focusable) then this call is ignored.

Parameters:

in focusObj

The object that should now get the focus. If NULL is passed, the focus will be set to NULL, which means that incoming keyboard events will be ignored until the next SetFocus() call.

See also: GetFocus(), AddFocusChangeListener()

Prototype:

    static FlexComponent *SetFocus(FlexComponent *focusObj);

Back to the top of AppBase

void SetState(AppState state);

Sets the current AppState, which can be fetched via GetState(). Setting the AppState incorrectly can cause strange application behavior (premature exiting, extra invocations of SetAppContext(), etc.), so SetState() is typically not invoked by applications.

Parameters:

in state

The new AppState of the app.

Prototype:

    void SetState(AppState state);

Back to the top of AppBase

FlexComponent *SetTarget(FlexComponent *targetObj);

Called to give a FlexComponent the target. This causes any global clipboard menus to operate on this object. Typically, applications give the target to their "main" document object.

If you have called SetTarget() to give the target to a FlexComponent, you must give the target to some other component (or set it to NULL) before freeing your FlexComponent.

Parameters:

in targetObj

The object that should now get the target. This can be NULL, in which case the clipboard menus will be inactive.

See also: GetTarget(), AddTargetChangeListener()

Prototype:

    static FlexComponent *SetTarget(FlexComponent *targetObj);

Back to the top of AppBase

Result UpdateDisplay(void);

Called to update the image of the application's UI on the hardware display. Typically, all drawing operations happen to off-screen bitmaps, and these bitmaps are displayed on the hardware only when the application goes idle. Applications that want to update the hardware display immediately can call this function.

Note that the application will not update the screen until the geometry is valid. Applications may need to invoke AppBase::Validate() before calling this routine if they have performed operations (such as adding, removing, and resizing FlexComponent objects) that require a geometry update.

Return value: FAILURE if the display could not be updated for some reason (lack of RAM, app not visible, geometry not valid).

Prototype:

    static Result UpdateDisplay(void);

Back to the top of AppBase