A user can select a button by clicking it with the mouse or by pressing the spacebar when the button has the keyboard focus. In most cases, a button changes its appearance when selected.

A button is always owned by another window, usually a dialog window or an application's client window. It posts messages or sends notification messages to its owner when a user selects the button. The owner window receives messages from a button and can send messages to the button to alter its position, appearance, and enabled or disabled state.

To use a button in a dialog window, your application specifies the control in a dialog template in the application's resource-definition file. The application processes button messages in the dialog-window procedure. This is not supported on Motif.

Understanding Button Types

There are four (three for Motif) main types of buttons, which determine how the button looks and behaves:

• Push buttons
• Radio buttons
• Check boxes
• Three-state check boxes

A radio button, check box, or three-state check box control an operation; a push button initiates an operation. For example, you might set printing options (such as paper size, print quality, and printer type) in a print-command dialog window containing an array of radio buttons and check boxes. After setting the options, you select a push button to notify an application that printing should begin (or be canceled). Then the application queries the state of each check box and radio button to determine the printing parameters.

The following sections discuss the different types of buttons in more detail.

Creating a Push Button

A push button is a rectangular window that contains a text string. Typically, an application uses a push button to let the user start or stop an operation. A push button represents an action that is initiated when a user selects it. You can label it with text, graphics, or both. When a user selects a push button, the action occurs immediately if there is a handler for the generated command event.

Use the IPushButton class to create and maintain the push button window. By default, a push button generates an application ICommandEvent. You can change the default style by changing the window style value to generate a help event or a system command event. Using system command events is not recommended for portable applications. You cannot set colors for push buttons on the WIndows operating system

Refer to the reference documentation for a list of the styles provided for IPushButton and for the IPushButton derived class, IGraphicPushButton.

The Hello World version 4 application defines three push buttons (Left, Center, and Right) in the ahellow4.cpp file.

The command events generated by pressing the Left, Center, and Right push buttons are handled by the AHelloWindow::command member function. Note, the command events are the same as those used for the corresponding menu items. Therefore, the command function processing is the same whether you press the push button or select the item on the menu bar.

The following figure shows the Hello World version 4 push buttons:

Creating a Radio Button

A radio button is a window with text displayed to the right of a small circular indicator. Use radio buttons to display a set of choices from which the user can select one. Each time the user selects a radio button, that button's state toggles between selected and unselected. This state remains until the next time the user selects the button. An application typically uses radio buttons in groups.

A group of radio buttons contains at least two radio buttons. Within a group, usually one button is selected by default. The user can move the selection to another button by using the cursor keys; however, only one button can be selected at a time. Radio buttons are appropriate if an exclusive choice is required from a fixed list of options. For example, applications often use radio buttons to let users select the screen foreground and background colors.

The IRadioButton class lets you create and manage the radio button window. The ISelectHandler class processes the selection of a radio button. You add the handler to either the radio button or its owner window by calling the handler's handleEventsFor function.

See Adding Events and Event Handlers for information about event handlers.

The following example creates a group of radio buttons.

1. The text associated with each radio button is defined in the resource file as string text, as follows:

   STRINGTABLE
     BEGIN
       STR_BLACK,  "Black"
       STR_WHITE,  "White"
       STR_BLUE,   "Blue"
       STR_RED,    "Red"
       STR_YELLOW, "Yellow"
     END
   
   

2. Declare the radio buttons in the .hpp file as follows:

   /***********************************************************/
   /* Command handler class declaration                       */
   /***********************************************************/
   class MyCommandHandler : public ICommandHandler {
    
   public:
     MyCommandHandler(AppWindow *mainWindow);
    
   protected:
     virtual bool command(ICommandEvent& cmdEvent);
    
   private:
      AppWindow *appWindow;
    
   };
    
   /***********************************************************/
   /* Select handler class declaration                        */
   /***********************************************************/
   class MySelectHandler: public ISelectHandler
    {
     public:
           MySelectHandler(IStaticText *info);
     protected:
           selected(IControlEvent& evt);
     private:
      bool fProcess;
      IStaticText *sttxt;
     }; 
    
   /***********************************************************/
   /* AppWindow declaration                                   */
   /***********************************************************/
   class AppWindow : public IFrameWindow
    {
     public:
       AppWindow( unsigned long windowId);
       ~AppWindow();
       AppWindow & enableButton();
       AppWindow & disableButton();
      private:
    
       ITitle            * title;
       ICanvas           * canvas1;
       IGroupBox         * groupBox;
       IStaticText       * staticText;
       IRadioButton      * white;
       IRadioButton      * black;
       IRadioButton      * blue;
       IRadioButton      * red;
       IRadioButton      * yellow;
       MySelectHandler   * selectHandler;
       MyCommandHandler  * commandHandler;
    
      };
   

3. Declare the buttons in the .cpp file as follows:

   AppWindow :: AppWindow( unsigned long windowId)
      : IFrameWindow(windowId,
                     defaultStyle() |
                     menuBar)
       {
    
     //*********************************************************
     // Create Title
     //*********************************************************
     title = new ITitle(this,ID_RADIO_TITLE);
    
     //*********************************************************
     // Create Canvas
     //*********************************************************
     canvas1 = new ICanvas(ID_CANVAS, this, this);
     moveSizeTo(IRectangle(10,10,650,540));
    
     setClient(canvas1);
    
     IWindow * pParent= canvas1;
     IWindow * pOwner = canvas1;
    
    
     //*********************************************************
     // Create Status Area
     //*********************************************************
     sttxt = new IStaticText(ID_TEXT,
                             canvas1,
                             canvas1,
                             IRectangle(20,425,470,450));
     sttxt->setText(ID_STAT_TITLE);
    
    
     //*********************************************************
     // Create Group Box
     //*********************************************************
     groupBox = new IGroupBox(ID_GROUPBOX,
                             canvas1,
                             canvas1,
                             IRectangle( 90,10,610,400));
     groupBox->setText("Color Selection");
    
     //*********************************************************
     // Create Radio Buttons
     //*********************************************************
     white = new IRadioButton(WND_WHITEBT, pParent, pOwner, IRectangle(100,300,250,360));
     white->setText(STR_WHITE);
    
     black = new IRadioButton(WND_BLACKBT, pParent, pOwner, IRectangle(100,230,250,290));
     black->setText(STR_BLACK);
    
     blue = new IRadioButton(WND_BLUEBT, pParent, pOwner, IRectangle(100,160,250,220));
     blue->setText(STR_BLUE);
    
     red = new IRadioButton(WND_REDBT, pParent, pOwner, IRectangle(100,90,250,150));
     red->setText(STR_RED);
    
     yellow = new IRadioButton(WND_YELLOWBT, pParent, pOwner, IRectangle(100,20,250,80));
     yellow->setText(STR_YELLOW);
    
    
     //*********************************************************
     // Set the group style of the controls
     //*********************************************************
     white->enableGroup().enableTabStop();
    
     //*********************************************************
     // Select white as the default button
     //*********************************************************
     white->select();
    
     //*********************************************************
     // Set the select handler to handle events
     //*********************************************************
     selectHandler = new MySelectHandler(sttxt);
     selectHandler->handleEventsFor(white);
     selectHandler->handleEventsFor(black);
     selectHandler->handleEventsFor(blue);
     selectHandler->handleEventsFor(red);
     selectHandler->handleEventsFor(yellow);
    
     //*********************************************************
     // Set the command handler to handle menu events
     //*********************************************************
     commandHandler = new MyCommandHandler(this);
     commandHandler->handleEventsFor(this);
    
     setFocus().show();
   }
   

4. Process selection events in the select handler routines as follows:

   /***********************************************************/
   /* MyWindow Select Event Handler                           */
   /***********************************************************/
   MySelectHandler::MySelectHandler(IStaticText *info)
      :ISelectHandler(),
       staticText(info)
   {
   }
    
   /***********************************************************/
   /* Set static text when radio button selected.             */
   /***********************************************************/
   bool MySelectHandler::selected(IControlEvent& evt)
   {
    
     bool fprocess = false;
     switch(evt.controlId())
     {
     case WND_BLACKBT:
          staticText->setText("Black is the currently selected color");
          fProcess=false;
          break;
    
     case WND_WHITEBT:
          staticText->setText("White is the currently selected color");
          fProcess=false;
          break;
    
     case WND_REDBT:
          staticText->setText("Red is the currently selected color");
          fProcess=false;
          break;
    
     case WND_BLUEBT:
          staticText->setText("Blue is the currently selected color");
          fProcess=false;
          break;
    
     case WND_YELLOWBT:
          staticText->setText("Yellow is the currently selected color");
          fProcess=false;
          break;
     }
     return fProcess = false;
   }  
   
   

5. Process menu events in the command handler routines as follows:

   /*************************************************************/
   /* Enable the radio button                                   */
   /*************************************************************/
   AppWindow & AppWindow::enableButton()
   {
     blue->enable();
     return (*this);
   }
    
   /*************************************************************/
   /* Disable the radio button                                  */
   /*************************************************************/
   AppWindow & AppWindow::disableButton()
   {
    
      blue->disable();
      return (*this);
   }
    
   /*************************************************************/
   /* Construct the command handler                             */
   /*************************************************************/
   MyCommandHandler::MyCommandHandler(AppWindow *mainWindow)
   {
     appWindow = mainWindow;
   }
    
   /*************************************************************/
   /* MyWindow command event handler                            */
   /*************************************************************/
   bool MyCommandHandler :: command(ICommandEvent& cmdevt)
    {
      switch (cmdevt.commandId())
      {
         case ID_DISABLE_BLUE_BTN:
           appWindow->disableButton();
             break;
         case ID_ENABLE_BLUE_BTN:
           appWindow->enableButton();
             break;
         return true;
      }
      return false;
   }
   

The following figure shows the radio buttons created with the preceding code example:

Creating a Check Box

Check boxes are similar to radio buttons, except that they can offer multiple-choice selection, as well as individual choice.

When a user selects the choice, a check mark symbol (&check.) appears in the check box to indicate that the choice is selected.

When a user selects the choice, the check box is filled in to indicate that the choice is selected.

By selecting the choice again, the user deselects the check box. Use a check box to set a choice in a group of choices that are not mutually exclusive.

Check boxes also toggle application features on or off. For example, a word processing application might use a check box to let the user turn word wrapping on or off.

The ICheckBox class lets you create and maintain a check box. The selection of a check box is processed by using the ISelectHandler class. You add the handler to either the check box or its owner window.

The following example shows you how to create a check box.

1. Create a check box by first making a declaration in the .hpp file, as follows:

   /***********************************************************/
   /* Set canvas class declaration                            */
   /***********************************************************/
   class MySet : public ISetCanvas
   {
     public:
       MySet(unsigned long winId, IWindow* pParent);
    
     private:
       ICheckBox   check1;
       ICheckBox   check2;
       ICheckBox   check3;
   };
   
    
   /***********************************************************/
   /* Application Window declaration                          */
   /***********************************************************/
   class AppWindow : public IFrameWindow
    {
     public:
       AppWindow( unsigned long windowId);
       ~AppWindow();
    
     private:
       ITitle             title;
       MySet            * pSetCv;
       IMultiCellCanvas   canvas;
    };
   

2. Construct the frame window:

   /*************************************************************/
   /* Window Constructor                                        */
   /*************************************************************/
    
   AppWindow :: AppWindow( unsigned long windowId)
      : IFrameWindow(windowId,
                     defaultStyle()),
        title(this,PSZ_OBJECT,PSZ_VIEW),
        canvas(ID_CANVAS, this, this)
   {
    
   setClient(&canvas);
    
   //*********************************************************
   // Create Canvas
   //*********************************************************
   pSetCv = new MySet(ID_SET, &canvas);
   canvas.addToCell(pSetCv, 2, 2);
    
   }
   
   

3. Construct the check boxes as shown here:

   /***********************************************************/
   /* MySet constructor                                       */
   /***********************************************************/
   MySet :: MySet(unsigned long winId, IWindow* pParent)
    : ISetCanvas(winId, pParent, pParent),
      check1(ID_BOX1, this, this, IRectangle(),
                          ICheckBox::classDefaultStyle |
                          IWindow::group),
      check2(ID_BOX2, this, this),
      check3(ID_BOX3, this, this)
   {
      check1.setText(PSZ_BOX1);
      check2.setText(PSZ_BOX2);
      check3.setText(PSZ_BOX3);
      setBorderText(IResourceId(PSZ_GROUP));
   }
   
   

The following figure shows the check boxes created using the preceding example:

Creating a Three-State Check Box

Three-state check boxes are similar to check boxes, except that they can be displayed in halftone as well as selected and unselected. An application might use the halftone state to indicate that, currently, the check box is not selectable. This control is not supported on Motif. The selection of a three-state check box is processed by using the ISelectHandler class and adding the handler to either the three-state check box or its owner window.

If a three-state check box is selected, it can be either checked or halftoned. You have to use a combination of the isSelected and isHalftone member functions to determine the state of a three-state check box. The following table shows the state of the three-state check box and its relation to the isSelected and isHalftone member functions.

The following example shows how to create a three-state check box:

I3StateCheckBox three(ID_THREE, &canvas, &canvas,
                      IRectangle(100,220,250,280));
three.setText("3 State");

three.selectHalftone();

if (three.isSelected())  {      // Determine state of the button
   if (three.isHalftone())  {
      // is halftone
   } else {
      // is checked
   }  /* end if */
} else {
   // is not selected
}  /* end if */

Clipboard
Controls

Adding Events and Event Handlers
Using List and Slider Controls

IClipboard
IOutlineBox
IGroupBox
IStaticText
IEntryField
IMultiLineEdit
IPushButton
IRadioButton
ICheckBox
IBaseListBox
IBaseComboBox
IBaseSpinButton