Class: SC.Pane


Extends SC.ResponderContext, SC.View.

A Pane is like a regular view except that it does not need to live within a parent view. You usually use a Pane to form the root of a view hierarchy in your application, such as your main application view or for floating palettes, popups, menus, etc.

Usually you will not work directly with the SC.Pane class, but with one of its subclasses such as SC.MainPane, SC.Panel, or SC.PopupPane.

Showing a Pane

To make a pane visible, you need to add it to your HTML document. The simplest way to do this is to call the append() method:

myPane = SC.Pane.create();
myPane.append(); // adds the pane to the document

This will insert your pane into the end of your HTML document body, causing it to display on screen. It will also register your pane with the SC.RootResponder for the document so you can start to receive keyboard, mouse, and touch events.

If you need more specific control for where you pane appears in the document, you can use several other insertion methods such as appendTo(), prependTo(), before() and after(). These methods all take a an element to indicate where in your HTML document you would like you pane to be inserted.

Once a pane is inserted into the document, it will be sized and positioned according to the layout you have specified. It will then automatically resize with the window if needed, relaying resize notifications to children as well.

Hiding a Pane

When you are finished with a pane, you can hide the pane by calling the remove() method. This method will actually remove the Pane from the document body, as well as deregistering it from the RootResponder so that it no longer receives events.

The isVisibleInWindow method will also change to NO for the Pane and all of its childViews and the views will no longer have their updateDisplay methods called.

You can readd a pane to the document again any time in the future by using any of the insertion methods defined in the previous section.

Receiving Events

Your pane and its child views will automatically receive any mouse or touch events as long as it is on the screen. To receive keyboard events, however, you must focus the keyboard on your pane by calling makeKeyPane() on the pane itself. This will cause the RootResponder to route keyboard events to your pane. The pane, in turn, will route those events to its current keyView, if there is any.

Note that all SC.Views (anything that implements SC.ClassicResponder, really) will be notified when it is about or gain or lose keyboard focus. These notifications are sent both when the view is made keyView of a particular pane and when the pane is made keyPane for the entire application.

You can prevent your Pane from becoming key by setting the acceptsKeyPane to NO on the pane. This is useful when creating palettes and other popups that should not steal keyboard control from another view.

Defined in: pane.js

Since:
SproutCore 1.0

Field Summary

Instance Methods

Field Detail

acceptsKeyPane Boolean

If YES, this pane can become the key pane. You may want to set this to NO for certain types of panes. For example, a palette may never want to become key. The default value is YES.

currentWindowSize Rect
Last known window size.
Defined in: layout.js.
firstResponder

The first responder. This is the first view that should receive action events. Whenever you click on a view, it will usually become firstResponder.

isKeyPane Boolean
This is set to YES when your pane is currently the target of key events.
isMainPane Boolean

Returns YES whenever the pane has been set as the main pane for the application.

isPane Boolean
Returns YES for easy detection of when you reached the pane.
page
Set to the current page when the pane is instantiated from a page object.
rootResponder

The rootResponder for this pane. Whenever you add a pane to a document, this property will be set to the rootResponder that is now forwarding events to the pane.

touchZ
The amount over the pane's z-index that the touch intercept should be.
wantsTouchIntercept

If YES, a touch intercept pane will be added above this pane when on touch platforms.

zIndex

The Z-Index of the pane. Currently, you have to match this in CSS. TODO: ALLOW THIS TO AUTOMATICALLY SET THE Z-INDEX OF THE PANE (as an option). ACTUAL TODO: Remove this because z-index is evil.

Instance Method Detail

append(rootResponder)

Inserts the pane at the end of the document. This will also add the pane to the rootResponder.

Parameters:
rootResponder SC.RootResponder
Returns:
SC.Pane
receiver
appendTo(elem)
Inserts the pane into the DOM.
Parameters:
elem DOMElement|jQuery|String
the element to append the pane's layer to. This is passed to `jQuery()`, so any value supported by `jQuery()` will work.
Returns:
SC.Pane
receiver
becomeKeyPane()

Make the pane receive key events. Until you call this method, the keyView set for this pane will not receive key events.

Returns:
SC.Pane
receiver
blurMainTo(pane)

Invoked when the view is about to lose its mainPane status. The default implementation will also remove the pane from the document since you can't have more than one mainPane in the document at a time.

Parameters:
pane SC.Pane
Returns:
void
blurTo(pane)

Invoked when the the pane is about to lose its focused pane status. Override to implement your own custom handling

Parameters:
pane SC.Pane
the pane that will receive focus next
Returns:
void
computeParentDimensions(frame)
The parent dimensions are always the last known window size.
Defined in: layout.js.
Parameters:
frame
Returns:
Rect
current window size
didBecomeKeyPaneFrom(pane)

Called just after the keyPane focus has changed to the receiver. Notifies the keyView of its new status. The keyView should use this method to update its display and actually set focus on itself at the browser level if needed.

Parameters:
pane SC.Pane
Returns:
SC.Pane
receiver
didBecomeKeyResponderFrom(responder)
Parameters:
responder
didLoseKeyPaneTo(pane)

Called just after the pane has lost its keyPane status. Notifies the current keyView of the change. The keyView can use this method to do any final cleanup and changes its own display value if needed.

Parameters:
pane SC.Pane
Returns:
SC.Pane
receiver
focusFrom(pane)

Invoked when the pane is about to become the focused pane. Override to implement your own custom handling.

Parameters:
pane SC.Pane
the pane that currently have focus
Returns:
void
focusMainFrom(pane)

Invokes when the view is about to become the new mainPane. The default implementation simply updates the isMainPane property. In your subclass, you should make sure your pane has been added to the document before trying to make it the mainPane. See SC.MainPane for more information.

Parameters:
pane SC.Pane
Returns:
void
hasTouchIntercept()
Returns YES if wantsTouchIntercept and this is a touch platform.
insert(fn)

Inserts the current pane into the page. The actual DOM insertion is done by a function passed into insert, which receives the layer as a parameter. This function is responsible for making sure a layer exists, is not already attached, and for calling paneDidAttach when done.

pane = SC.Pane.create();
pane.insert(function(layer) {
  jQuery(layer).insertBefore("#otherElement");
});
Parameters:
fn Function
function which performs the actual DOM manipulation necessary in order to insert the pane's layer into the DOM.
Returns:
SC.Pane
receiver
Deprecated: Version 1.11. Use `isAttached` instead.
isPaneAttached()
makeFirstResponder(view, evt, evt)

Makes the passed view (or any object that implements SC.Responder) into the new firstResponder for this pane. This will cause the current first responder to lose its responder status and possibly keyResponder status as well.

Parameters:
view SC.View
evt Event
that cause this to become first responder
evt
Returns:
SC.Pane
receiver
nextResponder()
Pane's never have a next responder.
Deprecated: Version 1.10
paneDidAttach()

This has been deprecated and may cause issues when used. Please use didAppendToDocument instead, which is not defined by SC.Pane (i.e. you don't need to call sc_super when implementing didAppendToDocument in direct subclasses of SC.Pane).

performKeyEquivalent(keystring, evt)

Defined in: keyboard.js.
Parameters:
keystring
evt
prependTo(elem)
Inserts the pane's layer as the first child of the passed element.
Defined in: manipulation.js.
Parameters:
elem DOMElement|jQuery|String
the element to prepend the pane's layer to. This is passed to `jQuery()`, so any value supported by `jQuery()` will work.
Returns:
SC.Pane
receiver
recomputeDependentProperties()

This method is called after the pane is attached and before child views are notified that they were appended to the document. Override this method to recompute properties that depend on the pane's existence in the document but must be run prior to child view notification.

remove()

Removes the pane from the document.

This will not destroy the pane's layer or destroy the pane itself.

Returns:
SC.Pane
receiver
removeFromParent()
This method has no effect in the pane. Instead use remove().
Defined in: manipulation.js.
Returns:
void
resignKeyPane()

Remove the pane view status from the pane. This will simply set the keyPane on the rootResponder to null.

Returns:
SC.Pane
receiver
sendEvent(action, evt, target, untilResponder)

Attempts to send the specified event up the responder chain for this pane. This method is used by the RootResponder to correctly delegate mouse, touch and keyboard events. You can also use it to send your own events to the pane's responders, though you will usually not do this.

A responder chain is a linked list of responders - mostly views - which are each sequentially given an opportunity to handle the event. The responder chain begins with the event's target view, and proceeds up the chain of parentViews (via the customizable nextResponder property) until it reaches the pane and its defaultResponder. You can specify the target responder; by default, it is the pane's current firstResponder (see SC.View keyboard event documentation for more on the first responder).

Beginning with the target, each responder is given the chance to handle the named event. In order to handle an event, a responder must implement a method with the name of the event. For example, to handle the mouseDown event, expose a mouseDown method. If a responder handles a method, then the event will stop bubbling up the responder chain. (If your responder exposes a handler method but you do not always want to handle that method, you can signal that the method should continue bubbling up the responder chain by returning NO from your handler.)

In some rare cases, you may want to only alert part of the responder chain. For example, SC.ScrollView uses this to capture a touch to give the user a moment to begin scrolling on otherwise-tappable controls. To accomplish this, pass a view (or responder) as the untilResponder argument. If the responder chain includes this view, it will break the chain there and not proceed. (Note that the untilResponder object will not be given a chance to respond to the event.)

Parameters:
action String
The name of the event (i.e. method name) to invoke.
evt SC.Event
The optional event object.
target SC.Responder
The responder chain's first member. If not specified, will use the pane's current firstResponder instead.
untilResponder SC.Responder
If specified, the responder chain will break when this object is reached, preventing it and subsequent responders from receiving the event.
Returns:
Object
object that handled the event
setBodyOverflowIfNeeded(force)

Changes the body overflow according to whether minWidth or minHeight are present in the layout hash. If there are no minimums, nothing is done unless true is passed as the first argument. If so, then overflow:hidden; will be used.

It's possible to call this manually and pass YES to remove overflow if setting layout to a hash without minWidth and minHeight, but it's probably not a good idea to do so unless you're doing it from the main pane. There's only one body tag, after all, and if this is called from multiple different panes, the panes could fight over whether it gets an overflow if care isn't taken!


Defined in: layout.js.
Parameters:
force Boolean Optional, Default: false
force a style to be set even if there are no minimums.
Returns:
void
unsetBodyOverflowIfNeeded()
Stops controlling the body overflow according to the needs of this pane.
Defined in: layout.js.
Returns:
void
willBecomeKeyPaneFrom(pane)

Called just before the pane becomes keyPane. Notifies the current keyView that it is about to gain focus. The keyView can use this opportunity to prepare itself, possibly stealing any value it might need to steal from the current key view.

Parameters:
pane SC.Pane
Returns:
SC.Pane
receiver
willLoseKeyPaneTo(pane)

Called just before the pane loses it's keyPane status. This will notify the current keyView, if there is one, that it is about to lose focus, giving it one last opportunity to save its state.

Parameters:
pane SC.Pane
Returns:
SC.Pane
receiver
windowSizeDidChange(oldSize, newSize)

Invoked by the root responder whenever the window resizes. This should simply begin the process of notifying children that the view size has changed, if needed.


Defined in: layout.js.
Parameters:
oldSize Rect
the old window size
newSize Rect
the new window size
Returns:
SC.Pane
receiver
Documentation generated by JsDoc Toolkit 2.4.0 on Wed Apr 08 2015 10:02:21 GMT-0600 (CST)