Class: SC.PickerPane


Extends SC.PalettePane.

Display a non-modal pane that automatically repositions around a view so as to remain visible.

An SC.PickerPane repositions around the view to which it is anchored as the browser window is resized so as to ensure the pane's content remains visible. A picker pane is useful for displaying supplementary information and does not block the user's interaction with other UI elements. Picker panes typically provide a better user experience than modal panels.

An SC.PickerPane repositions itself according to the optional preferMatrix argument passed in the .popup() method call. The preferMatrix either specifies an offset-based arrangement behavior or a position-based arrangement behavior depending on the preferType argument in the .popup() call.

The simplest way to create and display a picker pane:

SC.PickerPane.create({
  layout: { width: 400, height: 200 },
  contentView: SC.View.extend({})
}).popup(someView);

This displays the SC.PickerPane anchored to someView.

Positioning

Picker pane positioning can be classified into two broad categories: offset-based and position-based.

Offset-based

When preferType is unspecified, SC.PICKER_MENU or SC.PICKER_FIXED, then the preferMatrix array describes the offset that is used to position the pane below the anchor. The offset is described by an array of three values, defaulting to [1, 4, 3]. The first value controls the x offset and the second value the y offset. The third value can be 0 (right) or 3 (bottom), controlling whether the origin of the pane is further offset by the width (in the case of 0) or the height (in the case of 3) of the anchor.

Position-based

When preferType is SC.PICKER_POINTER or SC.PICKER_MENU_POINTER, then the preferMatrix specifies the sides in the order in which you want the SC.PickerPane to try to arrange itself around the view to which it is anchored. The fifth element in the preferMatrix specifies which side the SC.PickerPane should display on when there isn't enough space around any of the preferred sides.

Anchor sides are defined by their index in SC.POINTER_LAYOUT, where right is 0, left is 1, top is 2, and bottom is 3.

For example, the preferMatrix of [3, 0, 1, 2, 2] says: "Display below the anchor (3); if there isn't enough space then display to the right of the anchor (0). If there isn't enough space either below or to the right of the anchor, then appear to the left (1), unless there is also no space on the left, in which case display above the anchor (2)."

Position Rules

When invoking .popup() you can optionally specify a picker position rule with the preferType argument.

If no preferType is specified, the picker pane is displayed just below the anchor. The pane will reposition automatically for optimal visibility, ensuring the top-left corner is visible.

These position rules have the following behaviors:

SC.PICKER_MENU

Positioning is offset-based, with preferMatrix defaulting to [1, 4, 3]. Furthermore, a minimum left and right padding to window, of 7px and 8px, respectively, is enforced.

SC.PICKER_FIXED

Positioning is offset-based, with preferMatrix defaulting to [1, 4, 3] and skipping fitPositionToScreen.

SC.PICKER_POINTER

Positioning is position-based, with preferMatrix defaulting to [0, 1, 2, 3, 2], i.e. right > left > top > bottom; fallback to top.

SC.PICKER_MENU_POINTER

Positioning is position-based, with preferMatrix defaulting to [3, 0, 1, 2, 3], i.e. bottom, right, left, top; fallback to bottom.

Examples

Examples for applying popular customized picker position rules:

default:

SC.PickerPane.create({
  layout: { width: 400, height: 200 },
  contentView: SC.View.extend({})
}).popup(anchor);
SC.PickerPane.create({
  layout: { width: 400, height: 200 },
  contentView: SC.View.extend({})
}).popup(anchor, SC.PICKER_MENU);
SC.PickerPane.create({
  layout: { width: 400, height: 200 },
  contentView: SC.View.extend({})
}).popup(anchor, SC.PICKER_MENU, [2, 6, 0]);

fixed below the anchor with default preferMatrix of [1, 4, 3]:

SC.PickerPane.create({
  layout: { width: 400, height: 200 },
  contentView: SC.View.extend({})
}).popup(anchor, SC.PICKER_FIXED);

fixed on the right side of anchor with preferMatrix of [-22,-17, 0]:

SC.PickerPane.create({
  layout: { width: 400, height: 200 },
  contentView: SC.View.extend({})
}).popup(anchor, SC.PICKER_FIXED, [-22,-17, 0]);

pointer with default preferMatrix of [0, 1, 2, 3, 2]:

SC.PickerPane.create({
  layout: { width: 400, height: 200 },
  contentView: SC.View.extend({})
}).popup(anchor, SC.PICKER_POINTER);

Positioning: right (0) > left (1) > top (2) > bottom (3). Fallback to top (2).

pointer with custom preferMatrix of [3, 0, 1, 2, 2]:

SC.PickerPane.create({
  layout: { width: 400, height: 200 },
  contentView: SC.View.extend({})
}).popup(anchor, SC.PICKER_POINTER, [3, 0, 1, 2, 2]);

Positioning: bottom (3) > right (0) > left (1) > top (2). Fallback to top (2).

SC.PickerPane.create({
  layout: { width: 400, height: 200 },
  contentView: SC.View.extend({})
}).popup(anchor, SC.PICKER_MENU_POINTER);

Positioning: bottom (3) > right (0) > left (1) > top (2). Fallback to bottom (3).

Defined in: picker.js

Since:
SproutCore 1.0

Field Summary

Fields borrowed from SC.PalettePane:
modalPane
Fields borrowed from SC.PanelPane:
acceptsKeyPane, ariaDescribedBy, ariaLabel, ariaLabelledBy, ariaRole, contentView, isPanelPane
Fields borrowed from SC.Pane:
currentWindowSize, firstResponder, isKeyPane, isMainPane, isPane, isPaneAttached, page, rootResponder, touchZ, wantsTouchIntercept, zIndex
Fields borrowed from SC.View:
acceptsFirstResponder, acceptsMultitouch, ariaHidden, attributeBindings, backgroundColor, childViewLayout, childViewLayoutOptions, childViews, childViewsNeedLayout, classNameBindings, concatenatedProperties, createdByParent, enabledState, firstKeyView, hasLayout, hasTouch, hasVisibility, isBuildingIn, isBuildingOut, isChildViewLayoutLive, isEnabled, isKeyResponder, isTextSelectable, isView, isVisible, lastKeyView, layerLocationNeedsUpdate, layerNeedsUpdate, layout, nextKeyView, 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

Instance Methods

Field Detail

classNames Array
Default value:
['sc-picker']
See:
SC.View#classNames
displayProperties Array
Default value:
['pointerPos']
See:
SC.View#displayProperties
SC.PickerPane.HUGE_MENU_WINDOW_PADDING
Deprecated: Version 1.10. Use SC.PickerPane.HUGE_MENU_WINDOW_PADDING.
SC.PickerPane.HUGE_PICKER_MENU_EXTRA_RIGHT_OFFSET
SC.PickerPane.HUGE_PICKER_MENU_POINTER_OFFSET
isAnchored Boolean
Default value:
YES
isModal Boolean
Default value:
YES
SC.PickerPane.LARGE_MENU_WINDOW_PADDING
Deprecated: Version 1.10. Use SC.PickerPane.LARGE_MENU_WINDOW_PADDING.
SC.PickerPane.LARGE_PICKER_MENU_EXTRA_RIGHT_OFFSET
SC.PickerPane.LARGE_PICKER_MENU_POINTER_OFFSET
Deprecated: Version 1.10. Use SC.PickerPane.WINDOW_PADDING.
SC.PickerPane.PICKER_EXTRA_RIGHT_OFFSET
SC.PickerPane.PICKER_POINTER_OFFSET
pointerOffset Array
default/custom offset of pointer for picker-pointer or pointer-menu
Default value:
null
preferMatrix String
default/custom offset or position pref matrix for specific preferType
Default value:
null
preferType String
popular customized picker position rule
Default value:
null
SC.PickerPane.REGULAR_MENU_WINDOW_PADDING
Deprecated: Version 1.10. Use SC.PickerPane.REGULAR_MENU_WINDOW_PADDING.
SC.PickerPane.REGULAR_PICKER_MENU_EXTRA_RIGHT_OFFSET
SC.PickerPane.REGULAR_PICKER_MENU_POINTER_OFFSET
removeAction String

The name of the action you want triggered when the user clicks off the picker pane that is to be removed.

This property is used in conjunction with the removeTarget property to execute a method when the user clicks off the picker pane.

If you do not set a target, then clicking off the picker pane will cause the responder chain to search for a view that implements the action you name here, if one was provided.

Note that this property is optional. If no explicit value is provided then the picker pane will perform the default action which is to simply remove itself.

Default value:
null
removeTarget Object

The target object to invoke the remove action on when the user clicks off the picker that is to be removed.

If you set this target, the action will be called on the target object directly when the user clicks off the picker. If you leave this property set to null, then the button will search the responder chain for a view that implements the action when the button is pressed instead.

Default value:
null
renderDelegateName String
Default value:
'pickerRenderDelegate'
repositionOnWindowResize Boolean

Disable repositioning as the window or size changes. It stays in the original popup position.

Default value:
NO
SC.PickerPane.SMALL_MENU_WINDOW_PADDING
Deprecated: Version 1.10. Use SC.PickerPane.SMALL_MENU_WINDOW_PADDING.
SC.PickerPane.SMALL_PICKER_MENU_EXTRA_RIGHT_OFFSET
SC.PickerPane.SMALL_PICKER_MENU_POINTER_OFFSET
SC.PickerPane.TINY_MENU_WINDOW_PADDING
Deprecated: Version 1.10. Use SC.PickerPane.TINY_MENU_WINDOW_PADDING.
SC.PickerPane.TINY_PICKER_MENU_EXTRA_RIGHT_OFFSET
SC.PickerPane.TINY_PICKER_MENU_POINTER_OFFSET
SC.PickerPane.WINDOW_PADDING

Instance Method Detail

Deprecated:

Version 1.10. Use windowPadding instead. default offset of extra-right pointer for picker-pointer or pointer-menu

extraRightOffset()
popup(anchorViewOrElement, preferType, preferMatrix, pointerOffset)
Displays a new picker pane.
Parameters:
anchorViewOrElement SC.View|HTMLElement
view or element to anchor to
preferType String Optional
apply picker position rule
preferMatrix Array Optional
apply custom offset or position pref matrix for specific preferType
pointerOffset Number Optional
Returns:
SC.PickerPane
receiver
remove()
windowSizeDidChange(oldSize, newSize)
Invoked by the root responder. Re-position picker whenever the window resizes.
Parameters:
oldSize
newSize
Documentation generated by JsDoc Toolkit 2.4.0 on Sun Oct 27 2013 19:58:51 GMT-0600 (CST)