The check widget is derived from the widget object and comes in two types, checkboxes and radio buttons.
- 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
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.