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 Kony application using Kony Visualizer, but can also be added from code. For general information on using widgets in Visualizer, see Designing an Application in the Kony Visualizer User Guide.
For general information on the SegmentedUI widget, refer the Segment2 topic in the Kony Visualizer 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 Kony Visualizer.
The SegmentedUI widget capabilities can be broadly categorized into the following:
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. |
Methods | Description |
---|---|
animate | Applies an animation to the widget. |
animateRows | Associates animations with a specific row and its elements. |
setAnimations | Associates animations to the rows at each operation. |
resetSwipeMove | This method is used to reset the widget swipe to its initial state. |
Events | Description |
---|---|
onRowDisplay | Overwrites the rows that are affected because of an operation on rows. |
Properties | Description |
---|---|
animateFocusChanges | This property is used to bring the row specified in the selectedRowIndex property to the visible region. |
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. |
Methods | Description |
---|---|
addAll | Enables you to add new data to the segment. |
addDataAt | Enables you to add one row of data at a given ind ex or with in a section. |
addSectionAt | Enables you to add one section with rows to the segment. |
getFirstVisibleRow | Returns a JavaScript object containing the first visible row section index and row index. |
getLastVisibleRow | Returns a JavaScript object containing the last visible row's section index and row index. |
removeAll | Enables you to remove all the existing rows and sections in a segment. |
removeAt | Enables you to remove the row at the given index or a row with in a section. |
removeSectionAt | Allows you to remove a section at the given index within a segment. |
setData | Allows you to set new data to the segment. |
setDataAt | Allows you to set data or modify an existing data of a row or within a section. |
setSectionAt | Allows you to set or modify a section with rows to the segment. |
Properties | Description |
---|---|
metaInfo | Allows to capture row level attributes. |
stopRerenderOnSetDataAt | Allows only the modified content of a row to be updated when setDataAt method is used. |
Properties | Description |
---|---|
pullToRefreshI18NKey | Specifies the i18N key for "pull to refresh" title. |
pushToRefreshI18NKey | Specifies the i18N key for "push to refresh" title. |
releaseToPullRefreshI18NKey | Specifies the i18N key for "release to refresh" title that appears for pull to refresh. |
releaseToPushRefreshI18NKey | Specifies the i18N key for "release to refresh" title that appears for push for refresh. |
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. |
orientation | Specifies how you can stack the widgets within the SegmentedUI. |
right | Determines the lower right corner of the widget and is measured from the right bounds of the parent container. |
rowHeight | Specifies the height of the row of a SegmentedUI. |
rowWidth | Specifies the width of the row of a SegmentedUI. |
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. |
Events | Description |
---|---|
doLayout | Invoked for every widget when the widget position and dimensions are computed. |
Properties | Description |
---|---|
retainScrolledPage | Enables you to retain the page of the Segment widget after the widget has been reloaded in iOS platform. |
needPageIndicator | A Page Indicator is a succession of docs centered below the SegmentedUI widget. |
pageOnDotImage | Specifies the image to indicate that the page is currently being viewed. |
pageOffDotImage | Specifies the image to indicate that the pages that are not been currently viewed. |
Properties | Description |
---|---|
defaultSelection | Specifies if the first clickable element (Image or Label) of the segment is selected by default. |
retainSelection | Specifies if the segment should retain the selection made even when the user navigates out of the form and revisits the form. |
selectedRowIndex | Indicates the currently selected row in single select or multi select modes in the SegmentedUI. |
selectedRowIndices | Specifies an array of indexes which indicates the selected rows. |
selectedRowItems | Returns the data of the selected rows in the segmentedUI. |
selectionBehavior | Specifies if the segment can support single or multiple selection. |
selectionBehaviorConfig | Enabled if you select either singleselect or multiselect. |
Properties | Description |
---|---|
alternateRowSkin | Specifies the skin that is applied to every alternate even numbered row in the segment. |
blockedUISkin | Specifies the skin that must be used to block the interface until the action in progress (for example, a service call) is completed. |
Specifies the border to the SegmentedUI. | |
displayType | Specifies the display type of segmentPageView, either in PivotView or FlipView. |
Specifies the indicator type as rowSelect, rowClick, or none. | |
opacity | Specifies the opacity of the widget. |
pageSkin | Specifies the skin for page indicator. |
pressedSkin | Specifies the skin to indicate that the row of the segment is pressed or clicked. |
progressIndicatorColor | Specifies the color of the progress indicator as white or grey. |
pullToRefreshSkin | Specifies the skin to be applied to the pull to refresh title. |
pushToRefreshSkin | Specifies the skin to be applied to the push to refresh title. |
rowFocusSkin | Specifies the skin that must be applied when user selects the row. |
rowSkin | Specifies the skin that must be applied for each row. |
sectionHeaderSkin | Specifies the skin to be applied to the Section Header. |
separatorColor | Specifies the color of the separator between row of segmentedUI. |
separatorRequired | Specifies if the segment should display the separator between the rows of the SegmentedUI. |
separatorThickness | Specifies the thickness of the separator in pixels. |
showProgressIndicator | Specifies if the progress indicator must be displayed. |
viewType | You can use this property to select the view type of a segment. |
viewConfig | You can use this property to select the view type of a segment. |
widgetSkin | Specifies the skin to be applied to the entire SegmentedUI. |
Methods | Description |
---|---|
addGestureRecognizer | Allows you to set a gesture recognizer for a specified gesture for a specified widget. |
removeGestureRecognizer | Allows you to remove the specified gesture recognizer for the specified widget. |
Events | Description |
---|---|
onDragCompleted | Invoked when the drag and drop of a row in the Segment is complete. |
onReachingBeginning | Called when scrolling reaches the beginning of the SegmentedUI widget. |
onReachingEnd | Called when scrolling reaches the end of the SegmentedUI widget. |
onRowClick | Triggered when the user click any row of the SegmentedUI. |
onSwipe | Triggered when you swipe a row in a segment. |
onScrollStart | Indicates that scroll container started scrolling. |
onScrollTouchReleased | Indicates that user scrolling touch on the display is released. |
onScrolling | Indicates that segment scrolling is in progress. |
onScrollEnd | Indicates that segment scrolling has come to an end. |
onScrollWidgetPosition | Callback is invoked by the platform when the widget location position gets changed on scrolling. |
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. |
Methods | Description |
---|---|
clearSearch | This method clears the filtered results of the Segment widget. |
getBadge | Enables you to read the badge value (if any) attached to the specified widget. |
getUpdatedSearchResults | This method is used to return the filtered list after applying search on Segment. |
searchText | This method provides a method to search the data given inside the Segment widget. |
setBadge | Enables you to set the badge value to the given widget at the upper, right corner of the widget. |
Properties | Description |
---|---|
autogrowMode Property (Deprecated) | Used to set the height of a widget dynamically based on the derived height of the widget’s content, or from the child widget’s contents. |
bounces | Specifies whether the scroll view bounces past the edge of the content and back again. |
contentInsetAdjustmentType | On scroll view, this property automatically adds the required SegmentedUI insets to the scroll view. |
contextMenu | A context menu is a menu that appears upon clicking a widget. |
contentOffsetMeasured | Returns the current coordinates of the top left corner of the scrollable region in the segment. |
cursorType | Specifies the type of the mouse pointer used. |
dockSectionHeaders | Enables you to dock or place the section header at the top of the segment while scrolling the section content. |
editStyle | Specifies the editing style to be applied to the rows in the SegmentedUI. |
enableDictionary | Specifies if dictionary must be enabled for easy navigation. |
enableHapticFeedback | Allows you to enable or disable haptic feedback on the Segment widget. |
enableReordering | Allows you enable or disable reordering the rows in a Segment. |
groupCells | Specifies if all the rows in the segment should grouped using a rounded corner background and border. |
isMaster | Specifies whether the container is a master container. |
rowTemplate | Indicates the common template to be used for each row while creating the row and filling the data. |
sectionHeaderTemplate | Specifies the common template to be used for each section while creating the section header and filling the data. |
screenLevelWidget (deprecated) | This property specifies whether the widget should occupy the whole container or not. |
scrollsToTop | This property enables you to scroll the Segment to top on tapping a device’s status bar. |
searchBy | Indicates the identifier of the widget placed inside the row of the SegmentedUI. |
searchCriteria | Specifies the search criteria to be applied when searching has been enabled on the SegmentedUI. |
showScrollbars | Specifies if the scrollbars must be visible all the time. |
Events | Description |
---|---|
onDidFinishDataLoading | Triggered when data is finished loading in the segmentedUI using the setData method. |
onEditing | Triggered when a user indicates his desire to edit the row (delete or insert). |
Properties | Description |
---|---|
accessibilityConfig | Enables you to control accessibility behavior and alternative text for the widget. |
enableCache | Enables you to improve the performance of Positional Dimension Animations. |
id | A unique identifier of Segment 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. |
Methods | Description |
---|---|
convertPointFromWidget | Enables you to convert the coordinate system from a widget to a point (receiver's coordinate system). |
convertPointToWidget | Enables you to convert the coordinate system from a point (receiver's coordinate system) to a widget. |
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 |
---|---|
preOnclickJS | Allows the developer to execute custom javascript function before the onClick callback of the widget is invoked. |
postOnclickJS | Allows the developer to execute custom javascript function after the onClick callback of the widget is invoked. |
A SegmentedUI can contain Box , Button, Calendar, Canvas, Image, Label, RichText, Phone, Slider, Switch, TextArea, and TextBox widgets. In addition, the following widgets are supported only on the Desktop Web Platform:
Note: For ComboBox, 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 not supported for Windows Phone 8 and 8.1. It is only supported in Windows10.
The data returned when selectedItem is called on the SegmentedUI widget when the row has the following widgets:
Widget Name | Properties | Description | |||
---|---|---|---|---|---|
CheckBoxGroup | selectedKeys, selectedKeyValues | An array of key value pairs with the keys as mentioned. | |||
RadioButtonGroup | selectedKey, selectedKeyValue | ||||
ComboBox | selectedKey, selectedKeyValue | ||||
TextBox | text | ||||
TextArea | text | ||||
Calendar | dataComponents | An array of the date components |
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.
var seg = new kony.ui.SegmentedUI2 (basicConf, layoutConf, pspConf)
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 kony.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 kony.ui.SegmentedUI.
var seg1= new kony.ui.SegmentedUI (basicConf, layoutConf, pspConf)
The following are the important considerations for the segment widget:
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.
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.
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.
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.
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.
Platform Availability
Limitations
Android
This section provides a brief introduction to the new row animation features in the following topics.
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.
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.
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.
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.
To support SegmentedUI row animations, the Kony Visualizer API includes the following elements.
The SegmentedUI widget enables you to create templates to increase the re-usability of your efforts.
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:
Positional Properties | Dimensional Properties |
---|---|
left | minWidth |
right | maxWidth |
top | minHeight |
bottom | maxHeight |
centerX | |
centerY |
SegmentedUI sections are used to differentiate or group a set of rows.
The section templates are used:
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 Kony Visualizer. For more information about section headers refer Kony Visualizer User Guide.
To create a segment template at the application-level, follow these steps:
- Enter a Name for the template.
- Click Finish. A new form is created.
- Drag and drop an HBox or a Scrollable Box onto the form.
Note: Only HBox and Scrollable box are supported on the form. You can put other widgets within these widgets.
- Drag and drop the required widgets onto the HBox/Scrollable Box. Set the properties of these widgets. For more information, see Kony Widget User Guide.
- A segment template is created.
For more information on setting a Section Header template for a segment, click here.
You can define only one template for each segment using the above process.
To use section template in an application, follow these steps:
Note: The development activities for desktop web should happen in web_<formname> only. Although the newly created form, remains accessible in the desktop forms.
prem | Copyright © 2012 Kony, Inc. All rights reserved. |
prem | Copyright © 2012 Kony, Inc. All rights reserved. |