CheckBoxGroup Widget
The CheckBoxGroup widget allows you to make one or more selections from a group of check boxes. If you select a check box, a check mark appears inside the check box to indicate the selection.
Few real-time scenarios using the CheckBoxGroup widget are as follows:
-
Examinations: Checkboxes are widely used in tests that consist of multiple-choice questions. Students can select a single option or multiple options.
-
Remember password: You can use a checkbox for a binary yes or no choice. For instance, consider a login page, you are given a choice to select the remember me? option. You can select the checkbox if you want the browser to remember your password.
-
Terms of service agreement: The terms of service agreement while installing an application, employs a checkbox. The user must select the terms of agreement to proceed with installing the application.
-
Configure settings: Configuring various settings in a device like selecting or deselecting airplane mode or auto-rotate.
-
Provide feedback: CheckboxGroup widget is useful when you provide feedback on the services received. You can select an appropriate checkbox from the range of options provided. Options could be good, average, and bad.
-
Filters: Checkboxes are used in applying filters. For instance, in a social network app, users can choose the subjects of their choice such as nature, technology, health, etc. Then the feed of the user can be customized as per their interests.
-
Coupons: Applying coupons in shopping websites employ checkboxes.
Widgets are normally added to your application using Quantum Visualizer, but can also be added from code. For general information on using widgets in Quantum Visualizer, see Designing an Application in the Visualizer User Guide.
For general information on the CheckBoxGroup widget see the CheckBoxGroup topic in the Quantum Visualizer User Guide.
The CheckBoxGroup widget capabilities can be broadly categorized into the following:
- Layout
- UI Appearance
- Animations
- Data Management
- State Configurations
- 3D Touch
- User Input Handling
- Enabling RTL
- Miscellaneous
- Configurations common to all widgets
Layout
| Events | Description |
|---|---|
| doLayout | Invoked for every widget when the widget position and dimensions are computed. |
| Properties | Description |
|---|---|
| anchorPoint | Specifies the anchor point of the widget bounds rectangle using the widget's coordinate space. |
| bottom | Determines the bottom edge of the widget and is measured from the bottom bounds of the parent container. |
| centerX | Determines the center of a widget measured from the left bounds of the parent container. |
| centerY | Determines the center of a widget measured from the top bounds of the parent container. |
| height | Determines the height of the widget and measured along the y-axis. |
| left | Determines the lower left corner edge of the widget and is measured from the left bounds of the parent container. |
| maxHeight | Specifies the maximum height of the widget and is applicable only when the height property is not specified. |
| maxWidth | Specifies the maximum width of the widget and is applicable only when the width property is not specified. |
| minHeight | Specifies the minimum height of the widget and is applicable only when the height property is not specified. |
| minWidth | Specifies the minimum width of the widget and is applicable only when the width property is not specified. |
| padding | Defines the space between the content of the widget and the widget boundaries. |
| paddingInPixel | Indicates if the padding is to be applied in pixels or in percentage. |
| right | Determines the lower right corner of the widget and is measured from the right bounds of the parent container. |
| top | Determines the top edge of the widget and measured from the top bounds of the parent container. |
| width | Determines the width of the widget and is measured along the x-axis. |
| zIndex | Specifies the stack order of a widget. |
UI Appearance
| Properties | Description |
|---|---|
| backgroundColor | Specifies the background color of the widget in hex format. |
| backgroundColorMultiStepGradient | Specifies the multi-step gradient color for the background of the widget. |
| backgroundColorTwoStepGradient | Specifies the two-step gradient color for the background of the widget. |
| backgroundImage | Sets the image for the background of the widget. |
| borderColor | Specifies the border color of the widget. |
| borderColorGradient | Specifies the multi-step gradient color for the border of the widget. |
| borderStyle | Specifies the border style for the widget. |
| borderWidth | Specifies the width of the border for the widget in pixels. |
| cornerRadius | Specifies the radius of the border for the widget. |
| disabledStateSkinProperties | Specifies the skin properties that define the look and feel of the widget, when the widget is disabled or blocked. |
| focusStateSkinProperties | Specifies the skin properties that define the look and feel of the widget, when the widget is in focus. |
| fontColor | Specifies the font color of the widget. |
| fontFamily | Specifies the font family for the font of the widget. |
| fontSize | Specifies the font size for the widget in percentage (%) units. |
| fontStyle | Specifies the font style for the widget. |
| fontWeight | Specifies the weight for the font of the widget. |
| hoverStateSkinProperties | Specifies the skin properties that define the look and feel of the widget, when the cursor hovers on the widget. |
| pressedStateSkinProperties | Specifies the skin properties that define the look and feel of the widget, when the widget is pressed or clicked. |
| shadowColor | Specifies the color for the shadow of the widget. |
| shadowOffset | This property specifies the current coordinates of the shadow region in the widget. |
| shadowRadius | Specifies the radius for the blur value of the shadow. |
| textShadowColor | Specifies the color for the text shadow of the widget. |
| textShadowOffset | This property specifies the current coordinates of the text shadow region in the widget. |
| textShadowRadius | Specifies the radius for the blur value of the text shadow. |
| blur | You can enable or disable a blur-effect for a widget |
| focusSkin | Specifies the look and feel of the CheckBox when in focus. |
| hoverSkin | Specifies the look and feel of a widget when the cursor hovers on the widget. |
| itemOrientation | Specifies the arrangement of items inside the CheckBoxGroup widget. |
| opacity | Specifies the opacity of the widget. |
| skin | Specifies the look and feel of the CheckBox when not in focus. |
| shadowDepth | Defines the depth of the shadow effect applied to the CheckBoxGroup Widget. |
| shadowType | Sets a type of the shadow effect to apply to the CheckBoxGroup Widget. |
| wheelBackgroundColor | Specifies the background color for the wheel that is displayed when you click the CheckBox. |
Animations
| Methods | Description |
|---|---|
| animate | Applies an animation to the widget. |
| Properties | Description |
|---|---|
| transform | Contains an animation transformation that can be used to animate the widget. |
| widgetSwipeMove | Used to enable and configure the left or right swipe actions for a widget. |
Data Management
| Methods | Description |
|---|---|
| clone | When this method is used on a container widget, then all the widgets inside the container are cloned. |
| Properties | Description |
|---|---|
| masterData | Specifies the set of values that must be displayed for the user to make a selection from the available choices. |
| masterDataMap | Specifies the set of values from which you can make one or more selections. |
State Configurations
| Properties | Description |
|---|---|
| focusTickedImage | Specifies the image to be displayed when you make a selection on non-touch devices. |
| focusUnTickedImage | Specifies the image to be displayed when you clear a selection on non-touch devices. |
| selectedKeys | If you create a CheckBox with multiple values, you can choose to show specific values as selected when the CheckBox is rendered. |
| selectedKeyValues | Returns the array of selected key-value pairs. |
| tickedImage | Specifies the image to be displayed when you make a selection. |
| unTickedImage | Specifies the image to be displayed when a selection is cleared. |
| Events | Description |
|---|---|
| onSelection | Invoked by the platform when an item is selected or deselected. |
3D Touch
| Methods | Description |
|---|---|
| registerForPeekandPop | Registers a widget to enable 3D Touch peek and pop gestures. |
| setOnPeek | Sets and overrides the existing onPeekCallback for the widget. |
| setOnPop | Overrides the existing onPopCallback for the widget. |
| unregisterForPeekandPop | Unregisters a widget from 3D Touch peek and pop gestures. |
User Input Handling
| Events | Description |
|---|---|
| onScrollWidgetPosition | Invoked by the platform when the widget location position gets changed on scrolling. |
| onTouchEnd | Invoked by the platform when the user touch is released from the touch surface. |
| onTouchMove | Invoked by the platform when the touch moves on the touch surface continuously until movement ends. |
| onTouchStart | Invoked by the platform when the user touches the touch surface. |
| Methods | Description |
|---|---|
| removeGestureRecognizer | Allows you to remove the specified gesture recognizer for the specified widget. |
| setGestureRecognizer | Allows you to set a gesture recognizer for a specified gesture for a specified widget. |
Enabling RTL
| Properties | Description |
|---|---|
| retainContentAlignment | Helps to retain the content alignment of the widget while applying RTL. |
| retainFlexPositionProperties | Helps to retain the left, right and padding properties while applying RTL. |
| retainFlowHorizontalAlignment | Enables you to change the horizontal flow of the widget from left to right. |
Miscellaneous
| Properties | Description |
|---|---|
| cursorType | Specifies the type of the mouse pointer used. |
| groupCells | Specifies if the group cells style must be applied. |
| toolTip | Specifies the hint text when the cursor hovers over a widget, without clicking it. |
| viewType | Specifies the view type of the CheckBox. |
| Methods | Description |
|---|---|
| getBadge | Enables you to read the badge value (if any) attached to the specified widget. |
| setBadge | Enables you to set the badge value to the given widget at the upper, right corner of the widget. |
Configurations common to all widgets
| Properties | Description |
|---|---|
| accessibilityConfig | Enables you to control accessibility behavior and alternative text for the widget. |
| blur | Enables you to make the widget look unfocused. |
| enable | Allows you to make a widget visible but not actionable. |
| enableCache | Enables you to improve the performance of Positional Dimension Animations. |
| id | id is a unique identifier of CheckBox consisting of alpha numeric characters. |
| info | A custom JSObject with the key value pairs that a developer can use to store the context with the widget. |
| isVisible | Controls the visibility of a widget on the form. |
| parent | Helps you access the parent of the widget. |
| Methods | Description |
|---|---|
| convertPointFromWidget | Allows you to convert the coordinate system from a widget to a point (receiver's coordinate system). |
| convertPointToWidget | Using the convertPointToWidget method, you can modify the co-ordinate system. |
| removeFromParent | Allows you to remove a child widget from a parent widget. |
| setEnabled | Specifies the widget that must be enabled or disabled. |
| setFocus | Specifies the widget on which there must be focus. |
| setVisibility | Use this method to set the visibility of the widget. |
| Events | Description |
|---|---|
| postOnclickJS | Allows the developer to execute custom javascript function after the onSelection callback of the CheckBox is invoked. |
| preOnclickJS | Allows the developer to execute custom javascript function before the onSelection callback of the CheckBox is invoked. |
CheckBox Widget Basics
NOTE: To provide only a single selection option to the user, use a ComboBox widget or a RadioButtonGroup widget.
Creating a CheckBox Using a Constructor: kony.ui.CheckBoxGroup
var checkBox = new kony.ui.CheckBoxGroup(basicConf, layoutConf, pspConf);
- basicConf is an object with basic properties.
- layoutConf is an object with layout properties.
- pspConf is an object with platform specific properties.
NOTE: The configuration properties should be passed only in the respective configuration objects otherwise they are ignored.
Example
/*Defining the properties for CheckBox with focusSkin:"chkFocusSkin",
skin should be created with the same name through IDE or code.*/
var chkBasic = {
id: "checkBox",
isVisible: true,
skin: "chkSkin",
focusSkin: "chkFocusSkin"
};
var chkLayout = {
containerWeight: 100
};
//Creating the CheckBox.
var checkBox = new kony.ui.CheckBoxGroup(chkBasic, chkLayout, {});
//Reading the focusSkin of CheckBox
alert("CheckBox focusSkin is ::" + checkBox.focusSkin);Customizing Appearance
You can customize the appearance of the CheckBoxGroup widget using the following properties:
- widgetAlignment: Specifies the alignment of the widget.
- margin: Defines the space around a widget.
- padding: Defines the space between the content of the widget and the widget boundaries.
- skin: Used to specify the skin.
- focusSkin: Used to specify the focus skin.
Important Considerations
The following are the important considerations for the CheckBoxGroup widget.
All Platforms
- CheckBoxGroup widget is always a group widget.
- Limit the number of choices in the widget. If you need to display several choices (above 15 choices), consider using a ListBox widget.
iPhone
- You cannot apply skins in the on-off switch view.
- When the viewType is set as CHECKBOX_VIEW_TYPE_ONSCREENWHEEL, the skin supports only backgroundcolor and style as one color.
- Multistep Gradient is not supported when groupCells property is set to true.