Toggling command items

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,

1. Add the command-enabling handler function and response table macro to your window class (as shown in Handling command-enablingmessages).
2. Define the handler function.
3. 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

1. Add a new command identifier to your application, such as CM_TOGGLEHINTS.
2. Add a new menu, such as Options, with the menu item Fly-over Hints.
3. Optionally add a new button to your button bar.
4. Add a function to handle the CM_TOGGLEHINTS event and actually turn the hints on and off.
5. Add a command-enabling function to check and uncheck the command items.

The code would look something like this:

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);
}

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.

See Also

• Application and module objects overview
• Changing menu item text
• Enabling and disabling command items
• Gadget and gadget window objects
• Handling command-enabling messages
• TCommandEnabler class