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,SC.POSITION_BOTTOM]. The first value controls the x offset and the second value the y offset. The third value can be SC.POSITION_RIGHT (0) or SC.POSITION_BOTTOM (3), controlling whether the origin of the pane is further offset by the width (in the case of SC.POSITION_RIGHT) or the height (in the case of SC.POSITION_BOTTOM) 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.

The sides may be one of: SC.POSITION_RIGHT (i.e. 0) - to the right of the anchor SC.POSITION_LEFT (i.e. 1)- to the left of the anchor SC.POSITION_TOP (i.e. 2) - above the anchor SC.POSITION_BOTTOM (i.e. 3) - below the anchor

For example, the preferMatrix of,

[SC.POSITION_BOTTOM, SC.POSITION_RIGHT, SC.POSITION_LEFT, SC.POSITION_TOP, SC.POSITION_TOP],

indicates: Display below the anchor (SC.POSITION_BOTTOM); if there isn't enough space then display to the right of the anchor (SC.POSITION_RIGHT). If there isn't enough space either below or to the right of the anchor, then appear to the left (SC.POSITION_LEFT), unless there is also no space on the left, in which case display above the anchor (SC.POSITION_TOP).

Note: The position constants are simply the integers 0 to 3, so a short form of the example above would read,

[3, 0, 1, 2, 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,SC.POSITION_BOTTOM]. 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,SC.POSITION_BOTTOM] and skipping fitPositionToScreen.

SC.PICKER_POINTER

Positioning is position-based, with preferMatrix defaulting to [SC.POSITION_RIGHT,SC.POSITION_LEFT,SC.POSITION_TOP,SC.POSITION_BOTTOM,SC.POSITION_TOP] or [0, 1, 2, 3, 2] for short, i.e. right > left > top > bottom; fallback to top.

SC.PICKER_MENU_POINTER

Positioning is position-based, with preferMatrix defaulting to [SC.POSITION_BOTTOM,SC.POSITION_RIGHT,SC.POSITION_LEFT,SC.POSITION_TOP,SC.POSITION_BOTTOM] or [3, 0, 1, 2, 3] for short, 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, SC.POSITION_RIGHT]);

fixed below the anchor with default preferMatrix of [1, 4,SC.POSITION_BOTTOM]:

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,SC.POSITION_RIGHT]:

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

pointer with default preferMatrix of [SC.POSITION_RIGHT,SC.POSITION_LEFT,SC.POSITION_TOP,SC.POSITION_BOTTOM,SC.POSITION_TOP] or [0, 1, 2, 3, 2]:

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

Positioning: SC.POSITION_RIGHT (0) > SC.POSITION_LEFT (1) > SC.POSITION_TOP (2) > SC.POSITION_BOTTOM (3). Fallback to SC.POSITION_TOP (2).

pointer with custom preferMatrix of [SC.POSITION_BOTTOM,SC.POSITION_RIGHT,SC.POSITION_LEFT,SC.POSITION_TOP,SC.POSITION_TOP] or [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: SC.POSITION_BOTTOM (3) > SC.POSITION_RIGHT (0) > SC.POSITION_LEFT (1) > SC.POSITION_TOP (2). Fallback to SC.POSITION_TOP (2).

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

Positioning: SC.POSITION_BOTTOM (3) > SC.POSITION_RIGHT (0) > SC.POSITION_LEFT (1) > SC.POSITION_TOP (2). Fallback to SC.POSITION_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, autoMixins, backgroundColor, childViewLayout, childViewLayoutOptions, childViews, childViewsNeedLayout, classNameBindings, 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, 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.DraggablePaneSupport:
isDraggablePane

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

The offset of the pane from its target when positioned with preferType of SC.PICKER_POINTER or SC.PICKER_MENU_POINTER.

When using SC.PICKER_POINTER or SC.PICKER_MENU_POINTER as the preferType, the pane will include a pointer element (ex. a small triangle on the side of the pane). This also means that the pane will be offset by an additional distance in order to make space for the pointer. The offset distance of each side is specified by pointerOffset.

Therefore, if you are using a custom picker pane style or you would just like to change the default offsets, you should specify your own value like so:

pointerOffset: [*right offset*, *left offset*, *top offset*, *bottom offset*]

For example,

// If the pane is to the right of the target, offset 15px further right for a left-side pointer.
// If the pane is to the left of the target, offset -15px further left for a right-side pointer.
// If the pane is above the target, offset -30px up for a bottom pointer.
// If the pane is below the target, offset 20px down for a top pointer.
pointerOffset: [15, -15, -30, 20]
Default value:
preferType == SC.PICKER_POINTER ? SC.PickerPane.PICKER_POINTER_OFFSET (i.e. [9, -9, -18, 18])
preferMatrix Array

The configuration value for the current type of picker pane.

This dual-purpose property controls the positioning of the pane depending on what the value of preferType is.

Offset based use of preferMatrix

For preferType of SC.PICKER_MENU or SC.PICKER_FIXED, preferMatrix determines the x and y offset of the pane from either the right or bottom side of the anchor. In this case, the preferMatrix should be an array of,

[*x offset*, *y offset*, *offset position*]

For example, to position the pane 10px directly below the anchor, we would use,

preferMatrix: [0, 10, SC.POSITION_BOTTOM]

To position the pane 10px down and 5px right of the anchor's right side, we would use,

preferMatrix: [5, 10, SC.POSITION_RIGHT]

Position based use of preferMatrix

For preferType of SC.PICKER_POINTER or SC.PICKER_MENU_POINTER, preferMatrix determines the side of the anchor to appear on in order of preference. In this case, the preferMatrix should be an array of,

[*preferred side*, *nd preferred side*, *rd preferred side*, *th preferred side*, *fallback side if none fit*]

Note that if the pane can't fit within the window bounds (including windowPadding) on any of the sides, then the last side is used as a fallback.

Default value:
preferType == SC.PICKER_MENU || preferType == SC.PICKER_FIXED ? [1, 4, SC.POSITION_BOTTOM] (i.e. [1, 4, 3])
preferType String

The type of picker pane.

Picker panes can behave and appear in slightly differing ways depending on the value of preferType. By default, with no preferType specified, the pane will appear directly below the anchor element with its left side aligned to the anchor's left side.

However, if you wish to position the pane by a specified offset to the right or below the anchor using the values of preferMatrix as an offset configuration, you can set preferType to one of SC.PICKER_MENU or SC.PICKER_FIXED. These two picker types both use the preferMatrix to adjust the position of the pane below or to the right of the anchor.

The difference is that SC.PICKER_MENU also uses the windowPadding value to ensure that the pane doesn't go outside the bounds of the visible window.

If you wish to position the pane on whichever side it will best fit and include a pointer, then you can use one of SC.PICKER_POINTER or SC.PICKER_MENU_POINTER for preferType. With this setting the pane will use the values of preferMatrix to indicate the preferred side of the anchor for the picker to appear.

The difference between these two is that SC.PICKER_MENU_POINTER prefers to position below the anchor by default and SC.PICKER_POINTER prefers to position to the right of the anchor by default. As well, the SC.PICKER_MENU_POINTER type will resize itself if its height extends outside the visible window (which is useful for long menus that can scroll).

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()
viewDidResize()
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 Fri Nov 28 2014 17:58:15 GMT+0100 (CET)