Switch Widget
The Switch widget is identical to the Switch Control (an on-off switch that is not customizable) in iPhone, and presents two mutually exclusive choices or states.
The Switch widget displays the current state. You must slide the control to select the other value.
Following are the real-time use cases of Switch widget:
- Remember password: You can use a switch 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 slide the Switch if you want the browser to remember your password.
- Configuring settings: Switch is extensively used in configuring settings in a device. For instance, selecting features like auto-rotate, and airplane mode.
- Enable/disable functionalities: To enable or disable various functionalities in applications such as permissions for location, access camera, and access internet.
- Filters: Switches are used in applying filters. For instance, in social networking apps, you can choose the subjects of your choice such as nature, technology, health, etc, and your feed would primarily consist of the selected subjects.
- Coupons/Credits: Applying Coupons/Credits in shopping websites.
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 Switch widget see the Switch topic in the Quantum Visualizer User Guide.
The Switch widget capabilities can be broadly categorized into the following:
- Layout
- Internationalization
- Data Management
- User Input Handling
- Animations
- UI Appearance
- Enabling RTL
- Miscellaneous
- Configurations Common To All Widgets
Layout
| Properties | Description |
|---|---|
| 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. |
Internationalization
| Properties | Description |
|---|---|
| Left Text i18n Key | Specifies the key to be used for internationalization of the string specified in the leftSideText property. |
| Right Text i18n Key | Specifies the key to be used for internationalization of the string specified in the rightSideText property. |
Data Management
| Methods | Description |
|---|---|
| clone | When this method is used on a container widget, then all the widgets inside the container are cloned. |
User Input Handling
| Events | Description |
|---|---|
| onScrollWidgetPosition | This event callback is invoked by the platform when the widget location position gets changed on scrolling. |
| onSlide | An event callback that is invoked by the platform when there is a change in the default selected value. |
| onTouchEnd | An event callback is invoked by the platform when the user touch is released from the touch surface. |
| onTouchStart | An event callback is invoked by the platform when the user touches the touch surface. |
| onTouchMove | An event callback is invoked by the platform when the touch moves on the touch surface continuously until movement ends. |
| Methods | Description |
|---|---|
| addGestureRecognizer | This API allows you to set a gesture recognizer for a specified gesture for a specified widget. |
Animations
| Methods | Description |
|---|---|
| animate | Applies an animation to the widget. |
| Properties | Description |
|---|---|
| widgetSwipeMove | Used to enable and configure the left or right swipe actions for a widget. |
UI Appearance
| Properties | Description |
|---|---|
| blur | You can enable or disable a blur-effect for a widget(for example, a FlexContainer) |
| HeaderSkin | Specifies the skin to be applied to the header of the switch. |
| nativeThumbLook | Provides the native thumb look of the Switch. |
| opacity | Specifies the opacity of the widget. |
| skin | Specifies a background skin for Switch widget. |
| SwitchColor | Specifies the foreground color( sliding bar) to the Switch. |
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. |
| enableHapticFeedback | Allows you to enable or disable haptic feedback on the Switch widget. |
| Header | Specifies the header text to the switch. |
| leftSideText | Specifies the text to be displayed on the left portion of the Switch. |
| rightSideText | Specifies the text to be displayed on the right portion of the Switch. |
| selectedIndex | Accessible only from code and it specifies the option of the Switch that must be shown as selected when rendered. |
Configurations Common To All Widgets
| Properties | Description |
|---|---|
| accessibilityConfig | Enables you to control accessibility behavior and alternative text for the widget. |
| enable | Allows you to make a widget visible but not actionable. |
| enableCache | Enables you to improve the performance of Positional Dimension Animations. |
| isVisible | Controls the visibility of a widget on the form. |
| parent | Helps you access the parent of the widget. |
Switch Widget Basics
NOTE: The Switch Widget is supported on iOS and Android.
You can use a Switch Widget to present a user two simple, diametrically opposed choices that determine the state or choice of something.
Creating a Switch Widget Using a Constructor: kony.ui.Switch
var myswitch = new kony.ui.Switch(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, the configuration properties are ignored.
Example
//The below function is the callback function for onSliderCallback event.
function onSliderCallbck(swtch) {
/*write your logic here*/
}
//Defining the properties for Switch.
var swtchBasic = {
id: "swtch",
info: {
key: "switch"
},
leftSideText: "on",
rightSideText: "off",
skin: "swchSkin",
selectedIndex: 0,
isVisible: true,
onSlide: onSliderCallbck
};
var swtchLayout = {
margin: [5, 5, 5, 5],
marginInPixel: false,
widgetAlignment: constants.WIDGET_ALIGN_TOP_LEFT,
containerWeight: 99
};
//Creating the Switch.
var swtch = new kony.ui.Switch(swtchBasic, swtchLayout, {})
//Reading the id of the Switch
alert("Switch id is ::" + swtch.id);Customizing Appearances
You can customize the appearance of Switch widget. Most of the dimensions of Switch widget were previously unchangeable and even if users provided a different set of values, the values were not considered. Instead, the Switch widget is rendered with the set of configured values. Now, however, you can the dimensions of the Switch with new properties and new skins that have been introduced.
You can only customize Switch widgets in the Desktop Web platform.
How it Works
The following set of properties and skins are exposed so that you can customize the Switch widget. You can set the default values for those newly exposed values in the Switch section of the Property window as a platform-specific property.
Properties Exposed
- thumbWidth: Enables you to set the width of the knob that is placed on top of the track of the switch. The value can either be in Dp, px, or %. It is a Read+Write property.
- thumbHeight: Enables you to set the height of the knob that is placed on top of the track of the switch. The value can either be in Dp, px, or %. It is a Read+Write property.
- trackWidth : Enables you to set the width of the base of the switch. The value can either be in Dp, px, or %. It is a Read+Write property.
- trackHeight: Enables you to set the height of the base of the switch. The value can either be in Dp, px, or %. It is a Read+Write property.
Skins
You can use the existing normal skin for the track of the Switch and then expose another similar skin type tab for thumb in the Property window. You can set the four properties mentioned earlier in the Switch tab, where the properties will be present as a platform-specific property.
- Track skin: Existing default skin.
- Thumb skin : Replicates the normal skin.
- Switch icon: You can use the background image option to set an image on both the track and the thumb with the options of left and right image.
- Switch label: Similar to the four properties mentioned earlier, the value of thumbText property is Set Text for Thumb. You can leave this empty if the label is not required. You can change the text on the thumb on toggle, if required.
Alignment
The Switch is middle -left aligned with respect to the FlexContainer.
Note: If the width or height of the track/thumb exceeds the flex properties, the Switch widget is shown with the exceeded dimensions. The Switch widget is not clipped in this case.
IDE/Codegen Requirements
- Addition to Switch tab in Project window: There is one check box for custom switch under the Desktop Web platform option. Once you select that option, all the four properties ( thumbHeight, thumbWidth, trackHeight, and trackWidth) appear with the default values auto-populated. You then have to set all the four values according to the requirement. (for example, custom CSS option). In addition, another property (thumbText) appears.
- New additions to the existing skin ( to be used for the track of the switch): N/A
- Addition of a new skin for thumb similar to normal skin: N/A
Backward Compatibility
- If an existing project is upgraded, then the Switch remains the same unless you set the four properties (trackWidth, trackHeight, thumbWidth, thumbHeight) by selecting the custom CSS check box in the Switch tab of the Property window.
- Custom switch only appears when all the four properties are set, otherwise the conventional switch is rendered.
Default Behavior
- If you do not set the value of some of the four properties (atleast one should be set to enable custom switch render), default values are populated for those properties.
- If you are creating a Switch dynamically, you must create both the skins and specify them dynamically. Otherwise, for the skin, default values are applied respectively to both track and thumb.
- The properties that you specify have more priority than the ones that are specified in skins, by default.
Important Considerations
The following are the important considerations for the Switch widget:
- For a good user experience, use a predictable pair of values so that the users do not have to slide the Switch to know the other value.
- You can also consider using the Switch Widget to change the state of other UI elements in the view. Depending upon the choice that the user makes, changes in the UI must take place.
For example, in an Airline application booking screen, based on the Switch Widget selection as "One Way" or "Round Trip", the required UI elements must change. - One color or two colors in iPhone specific forked skin are supported only on iOS 5.0 and above. These properties are not respected in versions older than iOS 5.0.
- Following are the changes and behavior of the Switch Widget in iOS7 and above:
- Right background color has no effect.
- Size of the switch is fixed as 51 x 31 px. The hExpand property has no effect.
- The properties leftSideText and rightSideText have no effect.
- If the skin is not applied, you will get the look and feel of a native Switch. If the skin is applied, you will not get the native look.
- Following are the limitations of Switch Widget in Android platform:
- The height of the Switch Widget cannot be changed. The height remains the same as that of the native Android Switch Widget.
- You cannot set images to the leftSideText and rightSideText of the track and to the thumb as well.
- The width of the Switch Widget wraps to the length of the both 'leftSideText' and 'rightSideText'. However, if the text is too long then the widget gets moved out of the screen boundaries. This is the native Android behavior.
- The leftSideText and rightSideText are not supported in all OS versions. If the native switch widget in the apps-> settings supports text then Koyn Switch also supports the Text display.
- The leftSideColor and rightSideColor are being supported from API Level 16 (OS 4.1).
- The hExpand property is not supported in the Android platform.
- The paddings are applied on the entire Switch Widget but not on the text being displayed.
- Android platform does not support skin properties such as Shadow and Tint Color.
- If the border is applied, then the thumb covers the top and bottom side border. This is the native Android behavior.
- You must set the target SDK to OS 4.0 or higher as the Switch Widget is being supported from OS 4.0 or higher versions.
- In OS versions below 4.0, you cannot create the Switch Widget because exceptions could result.
- In OS 5.0 and above , if ThumbColor is customized, then you must set leftSideText and rightSideText as well. The ideal recommendation is to configure all the colors of the skin.
- Font size is not supported. This is the native Android behavior.
- When you set or update the leftSideText or rightSideText, the canges will be relected when you revisit the form.