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

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

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

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

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

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

Transition-In Special Handling

This view has special behavior when used with SC.View's transitionIn plugin support. If the plugin defines layoutProperties of either scale or rotate, then the picker will adjust its transform origin X & Y position to appear to scale or rotate out of the anchor. The result is a very nice effect that picker panes appear to pop out of their anchors. To see it in effect, simply set the transitionIn property of the pane to one of SC.View.SCALE_IN or SC.View.POP_IN.

Defined in: picker.js

Since:

SproutCore 1.0

Field Summary

Instance Methods

• extraRightOffset() Deprecated
• popup(anchorViewOrElement, preferType, preferMatrix, pointerOffset)
• remove()
• viewDidResize()
• windowSizeDidChange(oldSize, newSize)

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

// 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]

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

preferMatrix: [0, 10, SC.POSITION_BOTTOM]

preferMatrix: [5, 10, SC.POSITION_RIGHT]

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