You can use command-item toggling to provide the users of your applications visual cues about what functions are enabled, various application states, and so on.
Anything that can be presented in a Boolean fashion, such as on and off, in and out, and so on, can be represented by command-item toggling.
Two different types of toggling are implemented in ObjectWindows, but both are implemented the same way.
- You can turn check marks beside menu items on and off.
- You can check and uncheck button gadgets to make the gadget stand out when it is off and be recessed and grayed when it is on.
There is also a third, indeterminate state, the meaning of which is up to you. It usually indicates a situation where the criteria for being enabled or disabled are mixed. For example, many word processors have control bar buttons that indicate the current text format, such as a button with a B on it to indicate bold text. This button is unchecked when the current text format is not bold and checked when the format is bold. But if a block of text contains text, some of which is bold and some not, the button is placed in its indeterminate state.
A variation of toggling button gadgets is to enable or disable an exclusive button gadget. Exclusive button gadgets work just like radio buttons. In a group of exclusive button gadgets only one button gadget can be on at a time. Enabling another button gadget in the group disables the previously enabled button gadget.
To toggle a command item,
- Add the command-enabling handler function and response table macro to your window class (as shown in Handling command-enablingmessages)."
-# Define the handler function.
-# Inside the handler function, call the TCommandEnabker::SetCheck()
member function of the command-enabling object passed into the handler
function. SetCheck takes a single int parameter. Call SetCheck with one of the
enumerated values defined in TCommandEnabler: Checked, Unchecked, or
Indeterminate.
\note If you are turning on a check mark for a menu item and setting the text
for that menu item in the same function, you must call TCommandEnabler::SetText()
before you call SetCheck. Reversing this order removes the check
mark.
A common use for toggling command items is to let the user of your application
specify if some feature should be active. For example, suppose your application
provides both a menu item and a control bar button to access the CmFileSave
function. Many applications provide fly-over hints, short descriptions that
appear in the status bar when the pointer moves over a menu item or button
gadget. You might want to let the user turn these hints off. To provide this
option to the user, you can
-# Add a new command identifier to your application, such as CM_TOGGLEHINTS.
-# Add a new menu, such as Options, with the menu item Fly-over Hints.
-# Optionally add a new button to your button bar.
-# Add a function to handle the CM_TOGGLEHINTS event and actually turn the hints
on and off.
-# Add a command-enabling function to check and uncheck the command items.
The code would look something like this:
@code
class TMyDecFrame : public TDecoratedFrame
{
public:
TMyDecFrame(TWindow *parent = 0, char *title = 0, TWindow* client)
:
TDecoratedFrame(parent, title, client), hintMode (true) {}
// Cb must be set by the application object
// during the InitMainWindow function.
TControlBar* Cb;
protected:
// hintMode indicates whether the hints are currently on or off.
bool HintMode;
// This is the function that actually turns the hints on and off.
void CmToggleHints();
// This is the command-enabling handler function.
void
CeToggleHints(TCommandEnabler& commandEnabler);
DECLARE_RESPONSE_TABLE(TMyDecFrame);
};
DEFINE_RESPONSE_TABLE(TMyDecFrame)
EV_COMMAND(CM_TOGGLEHINTS, CmToggleHints),
EV_COMMAND_ENABLE(CM_TOGGLEHINTS, CeToggleHints),
END_RESPONSE_TABLE;
void
TMyDecFrame::CmToggleHints()
{
if(HintMode)
Cb->SetHintMode(TGadgetWindow::EnterHints);
else
Cb->SetHintMode(TGadgetWindow::NoHints);
HintMode = !HintMode;
}
void
TMyDecFrame::CeToggleHints(TCommandEnabler& ce)
{
ce.SetChecked(HintMode);
}
\endcode
The control bar is set up by the application object in its InitMainWindow
function. (The code for this is not shown here.) For a working example of
command item toggling, see the example EXAMPLES\\OWL\\OWLAPPS\\MDIFILE.
@section seealso See Also
- \ref applicationandmoduleobjectsoverview "Application and module objects overview"
- \ref changingmenuitemtext "Changing menu item text"
- \ref enablinganddisablingcommanditems "Enabling and disabling command items"
- \ref gadgetandgadgetwindowobjectsoverview "Gadget and gadget window objects"
- \ref handlingcommandenablingmessages "Handling command-enabling messages"
1.10.0