Rogue Wave banner
Previous fileTop of DocumentContentsIndex pageNext file
Stingray Foundation Library User's Guide
Rogue Wave web site:  Home Page  |  Main Documentation Page

12.7 User Interface Updating

The Stingray Foundation Library classes include facilities for keeping an application's user interface consistent with the state of the application. For example, an application may have a toolbar and provide a menu option for showing and hiding the menu. While the toolbar is showing, the menu should be checked. While the toolbar is hidden, the menu should be unchecked. This section describes how the SFL User Interface Updating mechanism works, and how to use the mechanism to create a consistent user interface.

12.7.1 User Interface Updating Essentials

SFL's User Interface Updating mechanism has several components, including CUIUpdateGenerator, the IEventRouter interface, CUIUpdateAdapter, and an interface named IIdleHandler.

The UIUpdating mechanism works like this. Any class wishing to implement User Interface updating handles idle-time processing by plugging in its own idle-time processing interface while processing the WM_CREATE message. You'll see the specific calls for doing that shortly. The class performing User Interface updating also inherits from a class named CUIUpdateGenerator, which has a member function named GenerateUIUpdates(). The class performing User Interface updating handles idle-time processing by calling GenerateUIUpdates(). GenerateUIUpdates() goes through the menu, toolbars, and status bars that have been registered in to the User Interface Updating mechanism, creating a wrapper class for each User Interface item (menu, tool bar button, and status pane). The User Interface mechanism generates a WM_UIUPDATE message and routes the event, where the class performing User Interface updating may modify the element that handles it.

Classes wanting to receive UIUpdating events inherit from CUIUpdateAdapter, which redirects the UI updating logic to a handler function. The handler function takes each incoming User Interface element and massages it in a way appropriate for the current state of the application. For example, if the toolbar is already showing, you may want to put a check mark on the Toolbar toggling menu option. When the toolbar is hidden, you may wish to remove that check mark. Figure 15 shows the User Interface Updating mechanism in action.

Figure 15: The SFL User Interface Updating mechanism in action

Figure 16 illustrates the architecture of SFL's User Interface Updating mechanism.

Figure 16: SFL's User Interface Updating architecture

The best way to examine SFL's User Interface Updating mechanism is to examine a class that uses the User Interface Mechanism. Example 122 shows an entire class with User Interface Updating applied.

Example 122: A C++ class with User Interface Updating applied

This listing illustrates a main window frame with User Interface Updating applied. Notice how the class derives from IEventRouterImpl, IIdleHandler, -CEventRouterMap, CCommandAdapter, CUIUpdateAdapter, and CUIUpdateGenerator.

Deriving from IIdleHandler adds idle processing capability to the class. The class registers itself as an idle-time processor during window creation by getting the module's message loop and calling AddIdleHandler(). AddIdleHandler() comes in through inheritance from the message loop. Notice the class also disconnects the idle handler during OnFinalMessage().

Deriving from CUIUpdateAdapter brings in the virtual function OnUIUpdate(), which the class overrides by checking the user element ID and handling the menu item appropriately (either by setting the text, enabling the control, setting or a check box.

The idle time processing generates WM_UIUPDATE messages for every toolbar item, every status bar pane, and every menu item. These are handled in the -OnUIUpdate() handler.



Previous fileTop of DocumentContentsNo linkNext file

Copyright © Rogue Wave Software, Inc. All Rights Reserved.

The Rogue Wave name and logo, and Stingray, are registered trademarks of Rogue Wave Software. All other trademarks are the property of their respective owners.
Provide feedback to Rogue Wave about its documentation.