 |
OWLNext 7.0
Borland's Object Windows Library for the modern age
|
|
OWLNext 7.0
Borland's Object Windows Library for the modern age
|
Base class for an extensible interface for auto enabling/disabling of commands (menu items, tool bar buttons, ...) More...
#include <owl/window.h>
Public Types | |
| enum | TCommandState { Unchecked , Checked , Indeterminate } |
| Enumeration describing the 3-states or availability of a command. More... | |
Public Member Functions | |
| TCommandEnabler (uint id, HWND hWndReceiver=0) | |
| Constructs the TCommandEnabler object with the specified command ID. | |
| uint | GetId () const |
| Retrieves the id of the command. | |
| virtual void | Enable (bool enable=true) |
| Enables or disables the command sender. | |
| virtual void | SetText (LPCTSTR text)=0 |
| Changes the text associated with a command sender; for example, text associated with a menu item or text on a button. | |
| void | SetText (const tstring &s) |
| virtual void | SetCheck (int check)=0 |
| Changes the check state of the command sender to either unchecked, checked, or indeterminate. | |
| void | SetCheck (bool isChecked) |
| Overload; allows you to pass a bool safely. | |
| bool | SendsCommand () const |
| Returns true if this command enabler sends a command message. | |
| bool | GetHandled () |
| Return true if the command enabler has been handled. | |
| bool | IsReceiver (HWND hReceiver) |
| Returns true if receiver is the same as the message responder originally set up in the constructor. | |
| HWND | GetReceiver () const |
| Returns the handle of the window that this enabler was destined for. | |
| void | SetReceiver (HWND hReceiver) |
| Sets the receiver for the enabler. | |
Protected Types | |
| enum | TCommandStatus { WasHandled = 1 , NonSender = 2 } |
| Enumeration describing whether the associated command has been enabled or disabled, and whether the command generates WM_COMMAND messages. More... | |
Protected Member Functions | |
| void | SetHandled () |
| Marks that the enabler has been handled. | |
Protected Attributes | |
| uint | Flags |
| TCommandStatus flags Is TCommandStatus::WasHandled if the command enabler has been handled. | |
| DECLARE_CASTABLE | |
Base class for an extensible interface for auto enabling/disabling of commands (menu items, tool bar buttons, ...)
An abstract base class used for automatic enabling and disabling of commands, TCommandEnabler is a class from which you can derive other classes, each one having its own command enabler.
For example, TButtonGadgetEnabler is a derived class that's a command enabler for button gadgets, and TMenuItemEnabler is a derived class that's a command enabler for menu items. Although your derived classes are likely to use only the functions Enable, SetCheck, and GetHandled, all of TCommandEnabler's functions are described so that you can better understand how ObjectWindows uses command processing. The following paragraphs explain the dynamics of command processing.
Handling command messages
Commands are messages of the windows WM_COMMAND type that have associated command identifiers (for example, CM_FILEMENU). When the user selects an item from a menu or a toolbar, when a control sends a notification message to its parent window, or when an accelerator keystroke is translated, a WM_COMMAND message is sent to a window.
Responding to command messages
A command is handled differently depending on which type of command a window receives. Menu items and accelerator commands are handled by adding a command entry to a message response table using the EV_COMMAND macro. The entry requires two arguments:
Child ID notifications, messages that a child window sends to its parent window, are handling by using one of the notification macros defined in the header file windowev.h. It is also possible to handle a child ID notification at the child window by adding an entry to the child's message response table using the EV_NOTIFY_AT_CHILD macro. This entry requires the following arguments:
TWindow command processing
One of the classes designed to handle command processing, TWindow performs basic command processing according to these steps:
TWindow also handles Child ID notifications at the child window level.
TFrameWindow command processing
TFrameWindow provides specialized command processing by overriding its member function EvCommand and sending the command down the command chain (that is, the chain of windows from the focus window back up to the frame itself, the original receiver of the command message).
If no window in the command chain handles the command, TFrameWindow delegates the command to the application object. Although this last step is theoretically performed by the frame window, it is actually done by TWindow's member function, DefaultProcessing().
Invoking EvCommand
When TFrameWindow sends a command down the command chain, it does not directly dispatch the command; instead, it invokes the window's EvCommand member function. This procedure gives the windows in the command chain the flexibility to handle a command by overriding the member function EvCommand instead of being limited to handling only the commands requested by the EV_COMMAND macro.
Handling command enable messages
Most applications expend considerable energy updating menu items and tool bar buttons to provide the necessary feedback indicating that a command has been enabled. In order to simplify this procedure, ObjectWindows lets the event handler that is going to handle the command make the decision about whether or not to enable or disable a command.
Although the WM_COMMAND_ENABLE message is sent down the same command chain as the WM_COMMAND event; exactly when the WM_COMMAND_ENABLE message is sent depends on the type of command enabling that needs to be processed.
Command enabling for menu items
TFrameWindow performs this type of command enabling when it receives a WM_INITMENUPOPUP message. It sends this message before a menu list appears. ObjectWindows then identifies the menu commands using the command IDs and sends requests for the commands to be enabled.
Note that because Object Windows actively maintains toolbars and menu items, any changes made to the variables involved in the command enabling functions are implemented dynamically and not just when a window is activated.
Command enabling for toolbar buttons
This type of command enabling is performed during idle processing (in the IdleAction function). The Default Message-Processing Flowchart that accompanies TWindow::DefaultProcessing is a graphical illustration of this process.
Creating specialized command enablers
Associated with the WM_COMMAND_ENABLE message is an object of the TCommandEnabler type. This family of command enablers includes specialized command enablers for menu items and toolbar buttons.
As you can see from TCommandEnabler's class declaration, you can do considerably more than simply enable or disable a command using the command enabler. For example, you have the ability to change the text associated with the command as well as the state of the command.
Using the EV_COMMAND_ENABLE macro
You can use the EV_COMMAND_ENABLE macro to handle WM_COMMAND_ENABLE messages. Just as you do with the EV_COMMAND macro, you specify the command identifier that you want to handle and the member function you want to invoke to handle the message.
Automatically enabling and disabling commands
ObjectWindows simplifies enabling and disabling of commands by automatically disabling commands for which there are no associated handlers. TFrameWindow's member function EvCommandEnable performs this operation, which involves completing a two-pass algorithm:
Because of this implicit command enabling or disabling, you do not need to (and actually should not) do explicit command enabling unless you want to change the command text, change the command state, or conditionally enable or disable the command.
If you handle commands indirectly by overriding the member function EvCommand instead of using the EV_COMMAND macro to add a response table entry, then ObjectWindows will not be aware that you are handling the command. Consequently, the command may be automatically disabled. Should this occur, the appropriate action to take is to also override the member function EvCommandEnable and explicitly enable the command.
|
protected |
Constructs the TCommandEnabler object with the specified command ID.
Sets the message responder (hWndReceiver) to zero.
Definition at line 288 of file window.cpp.
References Flags.
Enables or disables the command sender.
When Enable is called, it sets the Handled flag.
Reimplemented in owl::TMenuItemEnabler, and owl::TControlEnabler.
Definition at line 301 of file window.cpp.
References Flags, and WasHandled.
|
inline |
Return true if the command enabler has been handled.
Definition at line 1711 of file window.h.
References Flags, and WasHandled.
|
inline |
|
inline |
|
inline |
Changes the check state of the command sender to either unchecked, checked, or indeterminate.
This state applies to buttons, such as those used for tool bars, or to control bar gadgets. Pass a TCommandState enum
Implemented in owl::TControlEnabler, owl::TMenuItemEnabler, and owl::TTooltipEnabler.
|
inlineprotected |
Marks that the enabler has been handled.
Definition at line 1744 of file window.h.
References Flags, and WasHandled.
Changes the text associated with a command sender; for example, text associated with a menu item or text on a button.
Implemented in owl::TControlEnabler, owl::TMenuItemEnabler, owl::TTooltipEnabler, owl::TControlEnabler, and owl::TMenuItemEnabler.
|
protected |
TCommandStatus flags Is TCommandStatus::WasHandled if the command enabler has been handled.
1.10.0