You are here: Creating a Switch Widget Using a Constructor: voltmx.ui.Switch

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 Volt MX Iris, but can also be added from code. For general information on using widgets in Volt MX Iris, see Designing an Application in the Iris User Guide.

For general information on the Switch widget see the Switch topic in the Volt MX Iris 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

Internationalization

Data Management

User Input Handling

Animations

UI Appearance

Enabling RTL

Miscellaneous

Configurations Common To All Widgets

Switch Widget Basics

Note: The Switch Widget is supported on iOS, Android, and SPA.

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: voltmx.ui.Switch

var myswitch = new voltmx.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 voltmx.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.