Developer

API Reference

AEECLSID_CheckWidget

Brew Release
Brew MP 1.0.2
See Also
Model Events Border Events Widget Events AEECLSID_StaticWidget ISHELL_CreateInstance
Description

The check widget is derived from the widget object and comes in two types, checkboxes and radio buttons.
- Checkboxes
  • A checkbox is used to indicate the on or off state of a given interface element. For
  • example, a wireless dating application might use checkboxes to collect personal
  • interests from prospective daters, each indicating whether or not the person is "into"
  • the given interest, like so

  •    What types of things do you like to do on a date?  Select all that apply
          [ ] Walks in the moonlight 
          [ ] Dinners by candlelight
          [x] Write BUIW code
          [x] Watch Monty Python movies
    

- Radio buttons
  • Radio buttons allow the user to select one item from a group of choices. For
  • example, an application that determines whether or not you qualify for passage
  • across an old, decrepit and very scary bridge that crosses a murky ravine
  • might ask a series of multiple choice questions with answers organized as groups
  • of radio buttons, like so

  •       What... is your quest?
              (o) To seek a pot of gold
              ( ) To get across this bridge
              ( ) To meet a friend
    
          What... is your favorite color?
              ( ) Blue
              ( ) Red
              (o) Blue
              ( ) No preference
    


By default, checkboxes are drawn as a square box at the origin of the widget's bounding rectangle with two modifications based on the checkbox's current state. If the checkbox has been selected, a checkmark is drawn within the bounding rectangle, and if the checkbox currently has focus, it will draw an external border around the outside to draw attention.
Radio buttons are drawn as a circle at the orgin of the widget's bounding rectangle and vary in a manner that is similar to checkboxes.
The default images used to represent each of the states associated with a checkbox or radio button are stored as resources in the 'widgets.mif' file. One resource is used to represent various portions of the widget and has 3 frames associated with it: the check mark, the inactive border, and the active border. These images may be overriden using the PROP_IMAGESTRIP property to specify a new bitmap to be used as the image frames.
Alternatively, an industrious developer could use the widget's support of border properties to create an distinctive appearance. For example, a developer could set PROP_IMAGE_NFRAMES to 1 (through IWidget_SetNFrames), which would only apply an extra image an image when the widget is checked. They could then set the widget background to a teal gradient and give the widget a shadow for a 3D effect using the Border Properties. As an extra note, ensure that if you are using a number of frames greater than one that your 'border' images are transparent if you wish to also use the corresponding widget background properties, otherwise the changes will not be seen because the images are opaque by default.
Checkboxes and radio buttons are attached to value models, which store the widget's state (on or off) as a boolean value. Applications can identify and assign a specific value model to each widget at the time it is created, or can choose instead to use a default IValueModel implementation managed by the check widget class.
Radio buttons may additionally be attached to a model that will manage the association of a group of radio buttons -- though this model does not manage values. Instead, the model functions as a notifier, ending EVT_MDL_GROUP_ITEMACTIVE events to each listening radio button as the user changes the current selection. The widgets in a radio button group should, therefore, be created to all share the same managing model.
Both check and radio widgets handle a common set of events. Along with those listed below, checkboxes and radio buttons also support Border Events.
Event                 Description
-----                 ------------------------------------------------------------
EVT_WDG_ENABLETOUCH   
EVT_WDG_SETFOCUS
EVT_KEY
EVT_WDG_CANTAKETOUCH
EVT_WDG_SETPROPERTY
        PROP_IMAGESTRIP
        PROP_IMAGE_NFRAMES
        PROP_SELECTED
        PROP_EX
        PROPEX_WIDGETTC_PRESSED
EVT_WDG_GETPROPERTY
        PROP_SELECTED
        PROP_EX
        PROPEX_WIDGETELEMINFO


Properties:

Property                Description
--------                ------------------------------------------------------------
PROP_IMAGESTRIP         Specifies the Bitmap image resource that will represent the three (or fewer)
                        different frames for the check or radio widget.  If this property is not
                        set, it will default to IDB_CHECKSTRIP or IDB_RADIOSTRIP.
                            IWidget_SetPropImageStrip

PROP_IMAGE_NFRAMES      Specifies the number of frames that the image resource set with 
                        PROP_IMAGESTRIP contains. The valid values for this property are zero one 
                        two or three and they represent the following.
                        0 - No imagestrip will be used by the widget, although it will retain its
                           reference to the previously loaded image strip should one be loaded prior
                           to setting this property.
                        1 - The widget will treat the image strip as it was exactly one frame, which
                           will be used as the check mark for the checkbox or radio button.
                        2 - The widget will treat the image strip as two tiles.  The first tile
                           specifies the image that will be used as a checkmark.  The second
                           represents a border.
                        3 - The widget will treat the image strip as normal with three tiles.  The
                           three tiles will be (in order): the check mark, the inactive border, the
                           active border.

PROP_SELECTED           This property is handled exactly as detailed in Border Events; however, it is noted here
                        because it can be used to both set and retrieve the selection state of the widget as an
                        alternative means to accessing the value model.
                            IWidget_SetSelected
                            IWidget_GetSelected

PROP_EX                 This is the property that is used to set or retrieve any of the extended properties specified
                        below.
                            IWidget_SetPropertyEx
                            IWidget_GetPropertyEx

PROPEX_WIDGETTC_PRESSED This property is used to simulate a click on the check or radio widget.
                        This property is forwarded to the attached touch controller (should one
                        exist)


Required Model: IValueModel
The checkbox and radio button widgets rely on a value model that can represent its data as a boolean value reflecting the current selection state of the widget.
A default model is created and assigned to the widget when the widget is created with ISHELL_CreateInstance. The client can replace the widget's model at any time with the method IWidget_SetModel, as long as the supplied model interface is of the type that the widget expects.
Instantiaion
The Check Widget is instantiated by passing AEECLSID_CheckWidget into ISHELL_CreateInstance. The radio widget is similarly created by passing AEECLSID_RadioWidget into ISHELL_CreateInstance.
Cleanup
Both the checkbox and radio button widgets are reference-counted. When you are done with your reference to one of these widgets, you should Release that reference. Any widget-specific cleanup will be handled for you when all references are released.
Default Interface Name
Comment
It is very important to note that the text that usually accompanies a checkbox or radio button is NOT part of the checkbox or radio widget. Applications must separately create a static text widget and position that widget alongside the checkbox or radio button in order to create the appearance of a button followed by text. For example, an application may choose to create a container, then create a checkbox and static text widget within that container to group the objects together.
  • Follow