Class: SC.SegmentedView

Extends SC.Control, SC.View.

SegmentedView is a special type of button that can display multiple segments. Each segment has a value assigned to it. When the user clicks on the segment, the value of that segment will become the new value of the control.

You can also optionally configure a target/action that will fire whenever the user clicks on an item. This will give your code an opportunity to take some action depending on the new value. (of course, you can always bind to the value as well, which is generally the preferred approach.)

Defining Your Segments

You define your segments by providing a items array, much like you provide to a RadioView. Your items array can be as simple as an array of strings or as complex as full model objects. Based on how you configure your itemKey properties, the segmented view will read the properties it needs from the array and construct the button.

You can define the following properties on objects you pass in:

itemTitleKey - the title of the button
itemValueKey - the value of the button
itemWidthKey - the preferred width. if omitted, it autodetects
itemIconKey - an icon
itemActionKey - an optional action to fire when pressed
itemTargetKey - an optional target for the action
itemLayerIdKey - an optional target for the action
segmentViewClass - class to be used for creating segments

Defined in: segmented.js

Since:: SproutCore 1.0

Field Summary

Fields borrowed from SC.View:: acceptsFirstResponder, acceptsMultitouch, ariaHidden, ariaRole, attributeBindings, autoMixins, backgroundColor, childViewLayout, childViewLayoutOptions, childViews, childViewsNeedLayout, classNameBindings, classNames, concatenatedProperties, createdByParent, designMode, enabledState, firstKeyView, hasLayout, hasTouch, hasVisibility, isBuildingIn, isBuildingOut, isChildViewLayoutLive, isEnabled, isFixedHeight, isFixedPosition, isFixedSize, isFixedWidth, isKeyResponder, isTextSelectable, isView, isVisible, lastKeyView, layerLocationNeedsUpdate, layerNeedsUpdate, layout, modeAdjust, nextKeyView, page, pane, parentView, previousKeyView, shouldInheritCursor, shouldInheritEnabled, tagName, themeName, toolTip, touchBoundary, transitionAdjust, transitionAdjustOptions, transitionHide, transitionHideOptions, transitionIn, transitionInOptions, transitionOut, transitionOutOptions, transitionShow, transitionShowOptions, useStaticLayout
Fields borrowed from SC.Responder:: hasFirstResponder, isFirstResponder, responderContext
Fields borrowed from SC.Object:: isDestroyed, isObject, nextProperty, object, property, target, toInvalidate
Fields borrowed from SC.Observable:: isObservable
Fields borrowed from SC.Control:: controlSize, errorLabel, fieldKey, fieldLabel, isActive, isControl, isSelected

Instance Methods

Field Detail

align String

Aligns the segments of the segmented view within its frame horizontally. Possible values:

SC.ALIGN_LEFT
SC.ALIGN_RIGHT
SC.ALIGN_CENTER

Default value:: SC.ALIGN_CENTER

allowsEmptySelection Boolean

If YES, clicking a selected button again will deselect it, setting the segmented views value to null.

Default value:: NO

allowsMultipleSelection Boolean

If YES, then clicking on a tab will not deselect the other segments, it will simply add or remove it from the selection.

Default value:: NO

displayProperties Array

Default value:: ['align']
See:: SC.View#displayProperties

itemActionKey String

The key that contains the action for this item. If defined, then selecting this item will fire the action in addition to changing the value. See also itemTargetKey.

Default value:: null

itemIconKey String

The key that contains the icon for each item. If omitted, no icons will be displayed.

Default value:: null

itemIsEnabledKey String

A key that determines if this item in particular is enabled. Note if the control in general is not enabled, no items will be enabled, even if the item's enabled property returns YES.

Default value:: null

itemKeyEquivalentKey String

The key that contains the key equivalent for each item. If defined then pressing that key equivalent will be like selecting the tab. Also, pressing the Alt or Option key for 3 seconds will display the key equivalent in the tab.

Default value:: null

itemLayerIdKey String

The key that contains the layerId for each item.

items Array

The array of items to display. This may be a simple array of strings, objects or SC.Objects. If you pass objects or SC.Objects, you must also set the various itemKey properties to tell the SegmentedView how to extract the information it needs.

Note: only SC.Object items support key-value coding and therefore may be observed by the view for changes to titles, values, icons, widths, isEnabled values & tooltips.

Default value:: null

itemTargetKey String

The key that contains the target for this item. If this and itemActionKey are defined, then this will be the target of the action fired.

Default value:: null

itemTitleKey String

The key that contains the title for each item.

Default value:: null

itemValueKey String

The key that contains the value for each item.

Default value:: null

itemWidthKey String

The key that contains the desired width for each item. If omitted, the width will autosize.

Default value:: null

layoutDirection String

Change the layout direction to make this a vertical set of tabs instead of horizontal ones. Possible values:

SC.LAYOUT_HORIZONTAL
SC.LAYOUT_VERTICAL

Default value:: SC.LAYOUT_HORIZONTAL

localize Boolean

Default value:: YES

overflowIcon String

The icon to use for the overflow segment if it appears.

Default value:: null

overflowTitle String

The title to use for the overflow segment if it appears.

NOTE: This will not be HTML escaped and must never be assigned to user inserted text!

Default value:: '»'

overflowToolTip String

The toolTip to use for the overflow segment if it appears.

Default value:: 'More…'

renderDelegateName String

Default value:: 'segmentedRenderDelegate'

segmentViewClass SC.View

The view class used when creating segments.

Default value:: SC.SegmentView

selectSegmentWhenTriggeringAction Boolean

If YES, it will set the segment value even if an action is defined.

Default value:: NO

shouldAutoResize Boolean

Set to YES if you would like your SegmentedView to size itself based on its visible segments. Useful if you're using SegmentedView in a flowed context (for example if its parent view has childViewLayout:SC.View.HORIZONTAL_STACK``).

The view will not auto-resize unless you define an initial value for the layout property which will be auto-resized (i.e. width when in the default horizontal orientation). This is to prevent the view from inappropriately adding width to a flexible ({ left: 0, right: 0 }) layout.

Has no effect if shouldHandleOverflow is NO.

Default value:: NO

shouldHandleOverflow Boolean

If YES, overflowing items are placed into a menu and an overflow segment is added to popup that menu.

Default value:: YES

theme String

Default value:: 'square'
See:: SC.ButtonView#theme

value Object | Array

The value of the segmented view.

The SegmentedView's value will always be the value of the currently selected button or buttons. Setting this value will change the selected button or buttons.

If you set this value to something that has no matching button, then no buttons will be selected.

Note: if allowsMultipleSelection is set to true, then the value must be an Array.

Default value:: null

Instance Method Detail

indexForClientPosition(x, y)

Return the index of the segment view that is the target of the mouse click.

Parameters:
x
y

overflowSegmentDim()

Return the dimension (height or width depending on the layout direction) over the overflow segment.

segmentDimensions()

Return the dimensions (either heights or widths depending on the layout direction) of the DOM elements of the segments. This will be measured by the view to determine which segments should be overflowed.

It ignores the last segment (the overflow segment).

shouldHandleOverflowDidChange()

Documentation generated by JsDoc Toolkit 2.4.0 on Wed Apr 08 2015 10:02:21 GMT-0600 (CST)