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);

menu 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_MENU);

menu on the right side of anchor with custom preferMatrix of [2,6,0]:

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).

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

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).

Field Summary

Instance Methods

• popup
• remove
• windowSizeDidChange

Field Detail

Default Value:

null

See:

SC.View#classNames

Default Value:

['sc-picker']

See:

SC.View#displayProperties

Default Value:

['preferType','pointerPos','pointerPosY']

Default Value:

0

Default Value:

YES

Default Value:

YES

Default Value:

null

Default Value:

'perfectRight'

Default Value:

0

Default Value:

0

Default Value:

null

Default Value:

null

Default Value:

null

Default Value:

null

Default Value:

'pickerRenderDelegate'

Default Value:

NO

Instance Method Detail

Parameters:

SC.View|HTMLElement anchorViewOrElement

view or element to anchor to

String preferType Optional

apply picker position rule

Array preferMatrix Optional

apply custom offset or position pref matrix for specific preferType

Number pointerOffset Optional

Returns:

SC.PickerPane receiver

Parameters:

oldSize

newSize