You are here: SegmentedUI Widget > SegmentedUI Widget Basics > Templates > SegmentedUI Basics

SegmentedUI Widget

The Segment widget is a UI component commonly used to display lists or pages of data. Segment widget is a container that provides the capability to define a row template that repeats for every row or page of the specific segment.

You can use the Segment widget to display data from services, group services together, use templates to create the layout of each row, perform actions such as animations and form navigation when users click on a record, and more. These features have been explained in detail here:

Data Handling: Display data from various services in the Segment. For example, if you have a service that contains the data of all the employees in an organization, you can display it in your application by using a Segment widget.

Group Data: Group data into different sections by using Segment widgets. For example, after you have retrieved all employees’ data from the service mentioned earlier, you can categorize employees based on their respective departments by using another Segment widget.

Define Templates: Create templates to define reusable structure for Segment widgets. Templates help you to attain a consistent look-and-feel for the rows and sections of a Segment widget.

Animations: Add animation effect to the rows of a Segment widget in order to perform a specific task. One of the main uses of this capability is to enable the option that allows users to delete a Segment row, by swiping the row from right to left.

Row Click events: Assign a variety of actions to Segment widgets, which are performed when users click on a Segment row. Actions such as animations, form navigation, and more, can be applied to any row in a Segment. For example, if you have a Segment that contains the list of all employees in an organization, you can click on any row to move to another form where the details of the specific employee are displayed.

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 SegmentedUI widget, refer the Segment2 topic in the Volt MX Iris User Guide.

Note: For a more hands-on approach on the functionality of Segment widget, import and preview the Segment Widget Feature sample app by using Volt MX Iris.

The SegmentedUI widget capabilities can be broadly categorized into the following:

• 3D Touch
• Animations
• Data Management
• Internationalization
• Layout
• Paging
• UI Appearance
• User Input Handling
• State Configurations
• Enabling RTL
• Miscellaneous
• Configurations Common to all Widgets

3D Touch

Animations

Data Management

Internationalization

Layout

Paging

State Configurations

UI Appearance

User Input Handling

Enabling RTL

Miscellaneous

Configurations Common to All widgets

SegmentedUI Widget Basics

A SegmentedUI can contain Button, Calendar, Image, Label, RichText, Phone, Slider, Switch, TextArea, and TextBox widgets. In addition, the following widgets are supported only on the Desktop Web Platform:

• CheckBoxGroup
• RadioButtonGroup

Note: For RadioButton and CheckBox widgets masterData should be provided only if the masterDataMap set to the widget initially is different for a particular row.

Note: Textbox widget in Segment is only supported in Windows10.

The data returned when selectedItem is called on the SegmentedUI widget when the row has the following widgets:

Each of the above widgets is allowed to have its own skin and control. This gives the flexibility to design a segment with separate interconnected widgets and expose their properties for mapping.

When a SegmentedUI template is created based on the input data, the segment is repeated in the Segmented UI.

Creating a SegmentedUI by using a constructor: voltmx.ui.SegmentedUI2

var seg = new voltmx.ui.SegmentedUI2 (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 properties for a Segment
var basicConf = {
    id: "segId",
    isVisible: true,
    widgetSkin: "widSkin",
    rowSkin: "rowSkn",
    rowFocusSkin: "rowFSkn",
    alternateRowSkin: "altSkin",
    sectionHeaderSkin: "secHSkin",
    widgetDataMap: {
        widgetId1: "dataid1",
        widgetId2: "dataId2",
        widgetId3: "dataId3",
        widgetId4: "secDataId1",
        widgetId5: "secDataId2"
    },
    rowTemplate: box1
};

var layoutConf = {
    padding: [5, 5, 5, 5],
    margin: [5, 5, 5, 5],
    containerWeight: 100
};

var pspConf = {
    border: constants.SEGUI_BORDER_TOP_ONLY,
    defaultSelection: true
};

//Creating the Segment
var segment = new voltmx.ui.SegmentedUI2(basicConf, layoutConf, pspConf);

//Reading the alternateRowSkin of the SegmentedUI	
alert("SegmentedUI alternateRowSkin:" + segment.alternateRowSkin);

For backward compatibility with support for all deprecated properties and behaviors, use the constructor voltmx.ui.SegmentedUI.

var seg1= new voltmx.ui.SegmentedUI (basicConf, layoutConf, pspConf)

Important Considerations

The following are the important considerations for the segment widget:

• Segment occupies memory from two perspectives:

  • Amount of data required from number of rows. For example, if you set data for 100 rows, memory for all the 100 records will be in memory.
  • View hierarchy (Box and other supported widgets) in each segment row. If the View hierarchy is complex, the memory usage is high.

  Note: On iPhone, Android, and Windows platforms, if your segment has large data sets (more than 20 records with each record having more than 15 widgets), set the segment as a Screen Level Widget.

• Images in segment are not scaled and are rendered with autosize property set to false. If the image requires lesser space than the allocated space, the image is center aligned.
• You cannot add any elements to the widgets dynamically. However, if you want to hide any elements, do not provide any data for that element.
• In the Windows platform, the sections inside the Segment pageview are not supported.

• In the Desktopweb and SPA platforms, when you create a segment with table view that has a significant amount of data and multiple rows with a fixed height, the platform internally applies optimization logic at segment level. The optimization helps in loading a few rows initially, and then the remaining rows are sequentially loaded while scrolling.

  If the segment height suffices to contain all the rows of the segment, then the platform loads all the rows at once.

  Note: If you try scrolling too fast, you may experience jerky scrolling. If the rows contain images, they may take time to load based on the image file size.

• You can dynamically change the skin of the widgets in the segment using the Segment Alternate Methods.
• A SegmentedUI cannot be placed directly in a ScrollBox. It can be placed in a ScrollBox with orientation as Vertical and only then you can place a SegmentedUI on a ScrollBox.

• The height of the segmentedUI is determined by the content of the widget. If you set the screenLevelWidget as true, then the height of the segmentedUI widget is the form height excluding headers and footers.

  Important: The screenLevelWidget property is deprecated for FlexForm. You can achieve the behavior of the screenLevelWidget property using the height property. This property only applicable for box layout.

• Whenever a segmentedUI is set as screenLevelWidget there is a reduction in load time of the segmentedUI but scrolling speed reduces. This is because the SegmentedUI loads few rows at the load time and the rest of the rows are loaded as user scrolls through the widget. This is recommended option when you have huge number of records.
• When a segmentedUI is not set as screenLevelWidget, load time of segmentedUI increases because all the rows are loaded at the beginning, but scrolling speed improves.

Note: In general Android SDK does not support the bounce-back feature (rubber band effect). But there are some OEM’s which extended the Android SDK to support bounce-back like samsung devices. So to summarize this is a device specific feature rather than an Android SDK feature.

Adding a ListBox Widget inside a Segment

You can add a ListBox widget inside a Segment by using the onSelection event.

Note: By default, a ListBox contains some masterData. If you want to change the data for a particular ListBox row, you must update the required details in the Segment data.

onSelection Event

This is an event callback that is invoked by the platform when you select or deselect an item.

Syntax

onSelection(widget)

The onSelection event callback accepts an additional parameter (context) when a ListBox is placed in a Segment row or section template. The syntax for the context parameter is as follows:

onSelection(widget,context)

Parameters

widget [widgetref]

Handle to the widget instance that raised the event.

Context [Object]

This is an optional parameter. It is applicable only when you place a ListBox in a Segment rowTemplate or sectionTemplate. The Context Object argument has the following parameters:

• rowIndex [Number]: Optional. This is the index of the row that contains the ListBox. It is not available if you place the ListBox in a section header.

• sectionIndex [Number]: This is the index of the section row that contains the ListBox.

• widgetInfo [widgetref]: This is the handle to the parent widget instance (Segment) that contains the ListBox.

Platform Availability

• iOS
• Android
• Windows10
• SPA
• Desktop Web

Limitations

• Android

  • While updating the masterData of a particular ListBox row with a different value, you must set the respective values for both selectedKey and selectedKeyValue.

Row Animation

This section provides a brief introduction to the new row animation features in the following topics.

• Available Animations
• Row Animations and Flex Layout Properties
• Row Height Animation
• Row Animation Events

Available Animations

In Segment rows, you can move (translate), rotate, or scale child widgets. For example, you can display a rotating logo or a hand icon that simulates waving by moving back and forth.

Also, your app can slide interface controls into a row from off screen. Or it can simulate the hands of an analog clock moving onscreen.

Row Animations and Flex Layout Properties

With the row animation capabilities, users can programmaticaly update the Flex layout properties of widgets in the Segment’s row. Specifically, event handlers and widget methods can change the following properties.

• top
• left
• right
• bottom
• width
• height
• centerX
• centerY
• zIndex

The values above are set relative to the location of the row that contains them, not the Segment widget. For example, setting the top property to zero means that the top of the child widget is aligned with the top of the row that contains it. This means that whenever your code updates the child widget’s x position or scale, it is relative to the row’s width. Likewise, whenever your app changes the y position or scale of a widget within a row, it does so relative to the row’s height.

Even though you set the Flex layout properties of child widgets relative to their containing row, you can still specify a position for the child widget that is outside the bounds of the clipping rectangle of the row or page. So you can have some widgets outside the visible area of the row and slide them into the viewable rectangle when a particular event occurs, such as a button click.

In addition, you can also set the width and height values of child widgets in such a way as to place them outside the viewable area. As with the Flex layout position properties, you can alter the width and height values in the event handlers for events such as button clicks.

Please note that animating the position or size of widgets only applies to the child widgets within a row, not to the row itself.

Row Animation Events

The Segment widget now provides events that are specific to row animations. For example, suppose that your app enables a swipe gesture in the rows of a Segment widget. Imagine that the user of your app has just swiped across a row and your app has made visible changes to the row. If the user then swipes or touches in a different row, whatever was happening in the first row should probably be canceled. The row the user swiped should return to its original position and condition.

In this example, the row that the user first swiped receives an event telling it that the user has touched or swiped something else. Therefore, it knows that the action in progress should not be completed and it restores the row to its original state.

Essentially, with the SegmentedUI row events, a row being updated can react when properly when the user scrolls the SegmentUI widget or touches something in another row.

As of version 7.0, the Segment widget also supports animation in its doLayout event. Specifically, the doLayout event now received the context information it needs to perform animation updates.

Row Animation API Elements

To support SegmentedUI row animations, the Volt MX Iris API includes the following elements.

• voltmx.ui.createAnimation Function
• voltmx.ui.makeAffineTransform Function

SegmentedUI Templates

The SegmentedUI widget enables you to create templates to increase the re-usability of your efforts.

What is a Template for SegmentedUI

SegmentedUI template enables you to define a template for section headers. Only one template can be used for each segment. This is primarily useful for developers to achieve common look and feel of section headers along with few widgets added as part of section header of a segment.

On iOS platform, when a FlexContainer is used as a template for SegmentedUI, the below properties are not applicable:

Where to use a SegmentedUI (section) Template

SegmentedUI sections are used to differentiate or group a set of rows.

The section templates are used:

• To have uniform look and feel of the section headers.
• To achieve the behavior of having widgets such as an Image and a label for all the section headers of the segment.
• To perform an action on the event of an onclick of an item or a widget in the section header.

Creating a Template for SegmentedUI

When you want the same information to be displayed across all the Section Headers of a Segment in the application, you have a provision to add a Segment Template using Volt MX Iris. For more information about section headers refer VoltMX Iris User Guide.

To create a segment template at the application-level, follow these steps:

1. Go to Applications View.
2. Expand the application for which you want to create the SegmentTemplate.
3. Navigate to templates > segments, right-click mobile/desktop/tablet and select New Segment Template. The Create a New Segment window appears.

1. Enter a Name for the template.
2. Click Finish. A new form is created.
3. Drag and drop an FlexContainer/FlexScrollContainer onto the form.

Note: Only HBox and Scrollable box are supported on the form. You can put other widgets within these widgets.

1. Drag and drop the required widgets onto the FlexContainer/FlexScrollContainer. Set the properties of these widgets.
2. A segment template is created.

For more information on setting a Section Header template for a segment, click here.

Using SegmentedUI Section Template

You can define only one template for each segment using the above process.

To use section template in an application, follow these steps:

1. Go to Applications view.
2. Expand the application for which you want to use section template.
3. Navigate to forms > mobile/tablet/desktop , right-click and select New Form. The Create a New Form window appears.
4. Enter a name for the Form and click Finish. A new Form is created.
5. If you are building for desktop, select the Form in desktop and right-click on the Form. Select Fork. The Platform Selection window appears.
6. Select Desktop_web and click OK. The form is now forked for Desktop_web and new window appears as web_.

Note: The development activities for desktop web should happen in web_ only. Although the newly created form, remains accessible in the desktop forms.

1. Drag-drop a SegmentedUI on the Form and add widgets to the segment as required. Click Save.
2. To set the template to a segment, select the segment and go to Properties window.
3. Select sectionHeaderTemplate and Select/Search Segment Template window appears. Select the template, which you want to set to the segment.
4. Click OK.