Namespace: SC

All SproutCore methods and functions are defined inside of this namespace. You generally should not add new properties to this namespace as it may be overwritten by future versions of SproutCore.

You can also use the shorthand "SC" instead of "SproutCore".

SproutCore-runtime is a framework that provides core functions for SproutCore including cross-platform functions, support for property observing and objects. It's focus is on small size and performance. You can use this in place of or along-side other cross-platform libraries such as jQuery or Prototype.

Defined in: core.js

Field Summary

Class Methods

Field Detail

SC.ALIGN_BOTTOM
Indicates that the content should be aligned to the bottom.
Defined in: core.js.
SC.ALIGN_BOTTOM_LEFT
Indicates that the content should be aligned to the bottom and left.
Defined in: core.js.
SC.ALIGN_BOTTOM_RIGHT
Indicates that the content should be aligned to the bottom and right.
Defined in: core.js.
SC.ALIGN_CENTER
Indicates that the content should be aligned to the center.
Defined in: core.js.
SC.ALIGN_DEFAULT
Indicates that the content does not specify its own alignment.
Defined in: core.js.
SC.ALIGN_JUSTIFY String

Defined in: flowed_layout.js.
SC.ALIGN_LEFT
Indicates that the content should be aligned to the left.
Defined in: core.js.
SC.ALIGN_MIDDLE
Indicates that the content should be aligned to the middle.
Defined in: core.js.
SC.ALIGN_RIGHT
Indicates that the content should be aligned to the right.
Defined in: core.js.
SC.ALIGN_TOP
Indicates that the content should be aligned to the top.
Defined in: core.js.
SC.ALIGN_TOP_LEFT
Indicates that the content should be aligned to the top and left.
Defined in: core.js.
SC.ALIGN_TOP_RIGHT
Indicates that the content should be aligned to the top and right.
Defined in: core.js.
SC.allowsBackspaceToPreviousPage Boolean

If set to NO, then pressing backspace will NOT navigate to the previous page in the browser history, which is the default behavior in most browsers.

Usually it is best to leave this property set to NO in order to prevent the user from inadvertently losing data by pressing the backspace key.


Defined in: core.js.
Default value:
NO
SC.ANCHOR_BOTTOM Hash
Layout properties to anchoe view to the bottom.
Defined in: toolbar.js.
Default value:
`{ bottom: 0 }`
SC.ANCHOR_BOTTOM_RIGHT Hash
Layout properties to anchor a view to the bottom right.
Defined in: toolbar.js.
Default value:
`{ top: 0, right: 0 }`
SC.ANCHOR_CENTER

Layout properties to center. Note that you must also specify a width and height for this to work.


Defined in: layout.js.
SC.ANCHOR_LEFT Hash
Layout properties needed to anchor a view to the left.
Defined in: toolbar.js.
Default value:
`{ left: 0 }`
SC.ANCHOR_RIGHT Hash
Layout properties to anchor a view to the right.
Defined in: toolbar.js.
Default value:
`{ right: 0 }`
SC.ANCHOR_TOP Hash
Layout properties needed to anchor a view to the top.
Defined in: toolbar.js.
Default value:
`{ top: 0 }`
SC.AUTO_CONTROL_SIZE String

Option for controls to automatically calculate their size (should be default on controls that use renderers).


Defined in: control.js.
SC.BENCHMARK_BINDING_NOTIFICATIONS Boolean

Performance parameter. This will benchmark the time spent firing each binding.


Defined in: binding.js.
SC.BENCHMARK_BINDING_SETUP Boolean

Performance parameter. This will benchmark the time spend configuring each binding.


Defined in: binding.js.
SC.BEST_FIT String

Stretch/shrink the shape to fit the frame while maintaining aspect ratio, such that the longest dimension will just fit within the frame


Defined in: inner_frame.js.
SC.BEST_FIT_DOWN_ONLY String

Shrink the shape to fit the frame while maintaining aspect ratio, such that the longest dimension will just fit within the frame. Do not stretch the shape if the shape's width is less than the frame's width.


Defined in: inner_frame.js.
SC.BLANK_IMAGE_DATAURL
URL to a transparent GIF. Used for spriting.
Defined in: image.js.
SC.bodyOverflowArbitrator

SC.bodyOverflowArbitrator is a central object responsible for controlling the overflow on the body element.

Use it from views that would otherwise set the body overflow style directly; call requestHidden to ask for the body to have overflow:hidden, and call requestVisible to ask for the body to be visible.

Call withdrawRequest to register that you no longer have any interest in the body overflow setting. Don't forget to do this, or your object could be affecting the body overflow long after it's no longer relevant.

When calling requestHidden, requestVisible, and withdrawRequest, pass your object as the first argument so that its request can be associated with its GUID.

When calling requestHidden or requestVisible, you may optionally pass true as a second argument to signify that your desire for hidden or visible overflow is important. An important visible-request will override any other, but an important hidden-request will override a normal visible-request. A normal visible-request will in turn override a normal hidden-request.


Defined in: body_overflow.js.
SC.BOTTOM_LOCATION String

Defined in: tab.js.
SC.BRANCH_CLOSED Number
Used for contentIndexDisclosureState(). Indicates closed branch node.
Defined in: collection_content.js.
SC.BRANCH_OPEN Number
Used for contentIndexDisclosureState(). Indicates open branch node.
Defined in: collection_content.js.
Read Only
SC.BROWSER
The list of browsers that are automatically identified.
Defined in: browser.js.
SC.BUTTON1_STATUS String
Passed to delegate when alert pane is dismissed by pressing button 1
Defined in: alert.js.
Default value:
'button1'
SC.BUTTON2_STATUS String
Passed to delegate when alert pane is dismissed by pressing button 2
Defined in: alert.js.
Default value:
'button2'
SC.BUTTON3_STATUS String
Passed to delegate when alert pane is dismissed by pressing button 3
Defined in: alert.js.
Default value:
'button3'
SC.cachedVersionOf

Returns a wrapped copy of your function that caches its results according to its arguments. This function itself is cached, so the function you receive when you pass in a particular function will always be the same function.

How was does this function handle its own caching? Using itself, of course! :-D

Use this only on functions without side effects you depend on, and only on functions whose outputs depend entirely on their arguments and on nothing else external to them that could change.


Defined in: string_metric_optimization.js.
SC.CAPTURE_BACKSPACE_KEY
Set to NO to leave the backspace key under the control of the browser.
Defined in: root_responder.js.
Read Only
SC.CLASS_PREFIX

The list of browser specific object prefixes, these are matched to the browser engine.


Defined in: browser.js.
SC.COMBO_STYLES
a list of styles that get expanded into multiple properties, add more as you discover them
Defined in: render_context.js.
SC.CONTEXT_MENU_ENABLED
Default property to disable or enable by default the contextMenu
Defined in: view.js.
SC.controllersController
in suppressMain mode all controllers files register with this array controller
Defined in: controllers.js.
Read Only
SC.CSS_PREFIX

The list of browser specific CSS prefixes, these are matched to the browser engine.


Defined in: browser.js.
SC.CSS_TRANSFORM_NAMES
Map to CSS Transforms
Defined in: layout_style.js.
SC.data Object

Reads or writes data from a global cache. You can use this facility to store information about an object without actually adding properties to the object itself. This is needed especially when working with DOM, which can leak easily in IE.

To read data, simply pass in the reference element (used as a key) and the name of the value to read. To write, also include the data.

You can also just pass an object to retrieve the entire cache.


Defined in: core.js.
SC.DATETIME_COMPAREDATE_TIMEZONE_ERROR Error

Standard error thrown when trying to compare two dates in different timezones.


Defined in: datetime.js.
SC.DATETIME_ISO8601 String
Standard ISO8601 date format
Defined in: datetime.js.
Default value:
'%Y-%m-%dT%H:%M:%S%Z'
SC.designController
(Document Your Controller Here)
Defined in: design.js.
SC.Designer
Default namespace for designer-specific classes
Defined in: core.js.
SC.DesignerDropTarget
This View is used by Greenhouse when application is in design mode
Defined in: designer_drop_target.js.
SC.designsController

(Document Your Controller Here)

this controller is used by Greenhouse to list all of the views in a page files


Defined in: designs.js.
SC.device

The device object allows you to check device specific properties such as orientation and if the device is offline, as well as observe when they change state.

Orientation

When a touch device changes orientation, the orientation property will be set accordingly which you can observe

Offline support

In order to build a good offline-capable web application, you need to know when your app has gone offline so you can for instance queue your server requests for a later time or provide a specific UI/message.

Similarly, you also need to know when your application has returned to an 'online' state again, so that you can re-synchronize with the server or do anything else that might be needed.

By observing the 'isOffline' property you can be notified when this state changes. Note that this property is only connected to the navigator.onLine property, which is available on most modern browsers.


Defined in: device.js.
Read Only
SC.DEVICE
The list of devices that are automatically identified.
Defined in: browser.js.
Read Only
SC.DOM_PREFIX

The list of browser specific DOM prefixes, these are matched to the browser engine.


Defined in: browser.js.
SC.DRAG_ANY

Defined in: drag.js.
SC.DRAG_AUTOSCROLL_ZONE_THICKNESS

Defined in: drag.js.
SC.DRAG_COPY

Defined in: drag.js.
SC.DRAG_DATA

Defined in: drag.js.
SC.DRAG_LINK

Defined in: drag.js.
SC.DRAG_MOVE

Defined in: drag.js.
SC.DRAG_NONE

Defined in: drag.js.
SC.DRAG_REORDER

Special drag operation passed to delegate if the collection view proposes to perform a reorder event.


Defined in: collection.js.
SC.DROP_AFTER Number

Indicates that the collection view expects to accept a drop AFTER the specified item. This is treated just like SC.DROP_BEFORE is most views except for tree lists.


Defined in: core.js.
SC.DROP_ANY Number

Indicates that the collection view want's to know which operations would be allowed for either drop operation.


Defined in: core.js.
SC.DROP_BEFORE Number

Indicates that the collection view expects to accept a drop BEFORE the specified item.


Defined in: core.js.
SC.DROP_ON Number

Indicates that the collection view expects to accept a drop ON the specified item.


Defined in: core.js.
SC.EMPTY_PLACEHOLDER String
Default placeholder for empty values in bindings.
Defined in: binding.js.
SC.EMPTY_STATE_NAME
The default name given to an empty state
Defined in: empty_state.js.
Read Only
SC.ENGINE
The list of browser engines that are automatically identified.
Defined in: browser.js.
SC.EXIT_STATE
Constants used during the state transition process
Defined in: statechart.js.
SC.FILL String
Stretch/shrink the shape to fill the frame
Defined in: inner_frame.js.
SC.FILL_PROPORTIONALLY String

Stretch/shrink the shape to fill the frame while maintaining aspect ratio, such that the shortest dimension will just fit within the frame and the longest dimension will overflow and be cropped.


Defined in: inner_frame.js.
SC.FIXED_SIZE

Prevents the view from getting resized when the SplitView is resized, or the user resizes or moves an adjacent child view.


Defined in: split.js.
SC.FOCUS_ALL_CONTROLS Boolean

If true, then all SproutCore controls can be focused when the user presses the tab key. Otherwise, only SC.TextFieldView's will be focused.


Defined in: core.js.
Default value:
false
SC.FormsEditMode
Handles propagation of a property isEditing to all child views.
Defined in: edit_mode.js.
SC.FROM_THEME
Tells the property (when fetched with themed()) to get its value from the renderer (if any).
Defined in: view.js.
SC.FROZEN_ERROR Error
Standard Error that should be raised when you try to modify a frozen object.
Defined in: freezable.js.
SC.FULL_HEIGHT
Layout properties to take up the full height of a parent view.
Defined in: layout.js.
SC.FULL_WIDTH
Layout properties to take up the full width of a parent view.
Defined in: layout.js.
SC.Handlebars

Prepares the Handlebars templating library for use inside SproutCore's view system.

The SC.Handlebars object is the standard Handlebars library, extended to use SproutCore's get() method instead of direct property access, which allows computed properties to be used inside templates.

To use SC.Handlebars, call SC.Handlebars.compile(). This will return a function that you can call multiple times, with a context object as the first parameter:

var template = SC.Handlebars.compile("my {{cool}} template");
var result = template({
  cool: "awesome"
});

console.log(result); // prints "my awesome template"

Note that you won't usually need to use SC.Handlebars yourself. Instead, use SC.TemplateView, which takes care of integration into the view layer for you.


Defined in: handlebars.js.
SC.HOLD_BEHAVIOR String

Defined in: button.js.
SC.HORIZONTAL_ORIENTATION String

Defined in: core.js.
SC.HUGE_CONTROL_SIZE String
Option for HUGE control size.
Defined in: control.js.
SC.JUMBO_CONTROL_SIZE String
Option for HUGE control size.
Defined in: control.js.
SC.LARGE_CONTROL_SIZE String
Option for large control size.
Defined in: control.js.
SC.LAYOUT_AUTO
Layout property for width, height
Defined in: layout.js.
SC.LAYOUT_HORIZONTAL
Select a horizontal layout for various views.
Defined in: layout.js.
SC.LAYOUT_VERTICAL
Select a vertical layout for various views.
Defined in: layout.js.
Read Only
SC.LayoutState

States that the view's layout can be set to if its animation is cancelled.

START

The previous layout of the view before calling animate.

For example,

myView.set('layout', { left: 0, top: 0, width: 100, bottom: 0 });
myView.animate('left', 300, { duration: 1.5 });

// later..
myView.cancelAnimation(SC.LayoutState.START);

myView.get('layout'); // => { left: 0, top: 0, width: 100, bottom: 0 }

CURRENT

The current layout of the view while it is animating.

For example,

myView.set('layout', { left: 0, top: 0, width: 100, bottom: 0 });
myView.animate('left', 300, { duration: 1.5 });

// later..
myView.cancelAnimation(SC.LayoutState.CURRENT);
myView.get('layout'); // => { left: 150, top: 0, width: 100, bottom: 0 }

END

The final layout of the view if the animation completed.

For example,

myView.set('layout', { left: 0, top: 0, width: 100, bottom: 0 });
myView.animate('left', 300, { duration: 1.5 });

// later..
myView.cancelAnimation(SC.LayoutState.END);
myView.get('layout'); // => { left: 300, top: 0, width: 100, bottom: 0 }

Defined in: animation.js.
SC.LEAF_NODE Number
Used for contentIndexDisclosureState(). Indicates leaf node.
Defined in: collection_content.js.
SC.LINE

This View is used by Greenhouse when application is in design mode This is a Drawing View: If you want to draw a new shape you can pass in the information: For a Line:

{
  +shape: SC.LINE,
  +start: {x: 0, y: 0},
  +end: {x: 100, y: 100},
  ?style: {
    ?width: 5,
    ?color: 'orange' | '#FFA500' | 'rgb(255,165,0)' | 'rgba(255,165,0,1)'
    ?transparency: 0.2
  }
}

For a Rectangle:

{
  +shape: SC.RECT,
  +start: {x: 0, y: 0},
  +size: {width: 100, height: 100},
  ?type: SC.FILL | SC.STROKE
  ?style: {
    ?width: 5,
    ?color: 'orange' | '#FFA500' | 'rgb(255,165,0)' | 'rgba(255,165,0,1)'
    ?transparency: 0.2
  }
}

For a Circle:

{
  +shape: SC.CIRCLE,
  +center: {x: 0, y: 0},
  +radius: 20,
  ?type: SC.FILL | SC.STROKE
  ?style: {
    ?width: 5,
    ?color: 'orange' | '#FFA500' | 'rgb(255,165,0)' | 'rgba(255,165,0,1)'
    ?transparency: 0.2
  }
}

For a Polygon:

{
  +shape: SC.POLY
  +path: [
    +{x: 0, y: 0},
    +{x: 10, y: 10},
    ?{x: 0, y: 50}
  ],
  ?type: SC.FILL | SC.STROKE
  ?style: {
    ?width: 5,
    ?color: 'orange' | '#FFA500' | 'rgb(255,165,0)' | 'rgba(255,165,0,1)'
    ?transparency: 0.2
  }
}

Defined in: drawing.js.
Author: Evin Grano.
Since:
SproutCore 1.0
SC.LIST_ITEM_ACTION_CANCEL

Defined in: list_item.js.
SC.LIST_ITEM_ACTION_EJECT

Defined in: list_item.js.
SC.LIST_ITEM_ACTION_REFRESH

Defined in: list_item.js.
SC.Locale

The Locale defined information about a specific locale, including date and number formatting conventions, and localization strings. You can define various locales by adding them to the SC.locales hash, keyed by language and/or country code.

On page load, the default locale will be chosen based on the current languages and saved at SC.Locale.current. This locale is used for localization, etc.

Creating a new locale

You can create a locale by simply extending the SC.Locale class and adding it to the locales hash:

SC.Locale.locales['en'] = SC.Locale.extend({ .. config .. }) ;

Alternatively, you could choose to base your locale on another locale by extending that locale:

SC.Locale.locales['en-US'] = SC.Locale.locales['en'].extend({ ... }) ;

Note that if you do not define your own strings property, then your locale will inherit any strings added to the parent locale. Otherwise you must implement your own strings instead.


Defined in: locale.js.
Since:
SproutCore 1.0
SC.LOG_BINDINGS Boolean

Debug parameter you can turn on. This will log all bindings that fire to the console. This should be disabled in production code. Note that you can also enable this from the console or temporarily.


Defined in: binding.js.
SC.LOG_OBSERVERS Boolean

Set to YES to have all observing activity logged to the console.

This is only available in debug mode.


Defined in: observable.js.
SC.LOGGER_LOG_DEBUG String

If {@link SC.Logger.debug} falls back onto {@link SC.Logger.log}, this will be prepended to the output.


Defined in: logger.js.
SC.LOGGER_LOG_DELIMITER String
If SC.Logger.format is true, this delimiter will be put between arguments.
Defined in: logger.js.
SC.LOGGER_LOG_ERROR String

If {@link SC.Logger.error} falls back onto {@link SC.Logger.log}, this will be prepended to the output.


Defined in: logger.js.
SC.LOGGER_LOG_GROUP_HEADER String

If {@link SC.Logger.group} falls back onto {@link SC.Logger.log}, this will be prepended to the output.


Defined in: logger.js.
SC.LOGGER_LOG_GROUP_INDENTATION String

If the reporter does not support group(), then we’ll add our own indentation to our output. This constant represents one level of indentation.


Defined in: logger.js.
SC.LOGGER_LOG_INFO String

If {@link SC.Logger.info} falls back onto {@link SC.Logger.log}, this will be prepended to the output.


Defined in: logger.js.
SC.LOGGER_LOG_WARN String

If {@link SC.Logger.warn} falls back onto {@link SC.Logger.log}, this will be prepended to the output.


Defined in: logger.js.
SC.LOGGER_RECORDED_LOG_TIMESTAMP_PREFIX String

When reporting recorded log messages, the timestamp is included with this prefix.


Defined in: logger.js.
SC.MIXED_STATE String
Indicates a value has a mixed state of both on and off.
Defined in: pane.js.
SC.MODE_APPEND
set update mode on context to append content
Defined in: render_context.js.
SC.MODE_PREPEND
set update mode on context to prepend content
Defined in: render_context.js.
SC.MODE_REPLACE
set update mode on context to replace content (preferred)
Defined in: render_context.js.
SC.MOVES_AUTOMATIC_CHILD

Tells the SplitThumb to automatically choose which child of the SplitView to move in response to touch or mouse events in an SC.SplitThumb.


Defined in: split_thumb.js.
SC.MOVES_CHILD

Tells the SplitThumb to move the child of the SplitView that is either the SplitThumb or a parent of it.


Defined in: split_thumb.js.
SC.MOVES_NEXT_CHILD

Tells the SplitThumb to move the child of the SplitVie that comes after the child that is either the SplitThumb or a parent of it.


Defined in: split_thumb.js.
SC.MOVES_PREVIOUS_CHILD

Tells the SplitThumb to move the child of the SplitView that preceeds the child that is either the SplitThumb or a parent of it.


Defined in: split_thumb.js.
SC.MULTIPLE_PLACEHOLDER String
Default placeholder for multiple values in bindings.
Defined in: binding.js.
SC.NON_PIXEL_PROPERTIES
list of numeric properties that should not have 'px' appended
Defined in: render_context.js.
SC.NULL_PLACEHOLDER String
Default placeholder for null values in bindings.
Defined in: binding.js.
SC.ObjectCoder

Generic base class to encode a view hierarchy. ViewCoders are used to collect the properties that may be included in a view design and then to serialize that design to a JavaScript string that can be evaled.

To encode a view with a ViewCoder, simply call SC.ViewCoder.encode(view). Most of the time, however, you will not initiate coding directly but instead work with the coder while designing an SC.DesignerView subclass.

Using a Coder

When you are passed an instance of a coder, you can simply write attributes into the coder using one of the many encoding methods defined on the view. Encoding methods are defined for most primitive view types.

coder.string("firstName" , "Charles").string('lastName', 'Jolley');

Defined in: object.js.
Read Only
SC.OS
The list of operating systems that are automatically identified.
Defined in: browser.js.
SC.PageDesignController

An instance of this controller is created for every page where designers are involved. The Designer's themselves will register with the controller so that you can hook to the controller to manage the views and their editors.

Among other things, this controller implements global selection support for the designers.


Defined in: page_design.js.
Since:
SproutCore 1.0
SC.pageFilesController
in `suppressMain` mode all page files register with this array controller
Defined in: page_files.js.
SC.pageItemView

This View is used by Greenhouse when application is in design mode Used for displaying page items


Defined in: page_item_view.js.
Author: Mike Ball.
SC.PARSE_COLOR_RGBRE
regular expression for parsing color: rgb, hex
Defined in: colors.js.
SC.PICKER_FIXED String

Defined in: picker.js.
SC.PICKER_MENU String

Defined in: picker.js.
SC.PICKER_MENU_POINTER String

Defined in: picker.js.
SC.PICKER_POINTER String

Defined in: picker.js.
SC.POSITION_BOTTOM
Indicates that the content should be positioned below.
Defined in: core.js.
SC.POSITION_LEFT
Indicates that the content should be positioned to the left.
Defined in: core.js.
SC.POSITION_RIGHT
Indicates that the content should be positioned to the right.
Defined in: core.js.
SC.POSITION_TOP
Indicates that the content should be positioned above.
Defined in: core.js.
SC.PUSH_BEHAVIOR String

Defined in: button.js.
SC.REGULAR_CONTROL_SIZE String
Option for standard control size.
Defined in: control.js.
SC.removeData Object

Removes data from the global cache. This is used throughout the framework to hold data without creating memory leaks.

You can remove either a single item on the cache or all of the cached data for an object.


Defined in: core.js.
SC.RESIZE_AUTOMATIC

Allows the view to be resized when the SplitView is resized or due to the user resizing or moving an adjacent child view.


Defined in: split.js.
SC.RESIZE_MANUAL

Prevents the view from getting resized when the SplitView is resized (unless the SplitView has resized all other views), but allows it to be resized when the user resizes or moves an adjacent child view.


Defined in: split.js.
SC.ROOT_STATE_NAME
The default name given to a statechart's root state
Defined in: statechart.js.
SC.RootDesignerHighLightView

This View is used by Greenhouse when application is in design mode It darkens the area around the rootDesigner


Defined in: high_light.js.
SC.SCALE_NONE String

Defined in: inner_frame.js.
SC.SCANNER_INT_ERROR Error
Standard error thrown by `SC.Scanner` when you pass a value not an integer.
Defined in: datetime.js.
SC.SCANNER_OUT_OF_BOUNDS_ERROR Error
Standard error thrown by `SC.Scanner` when it runs out of bounds
Defined in: datetime.js.
SC.SCANNER_SCAN_ARRAY_ERROR Error

Standard error thrown by SC.Scanner when it can any kind a string in the matching array.


Defined in: datetime.js.
SC.SCANNER_SKIP_ERROR Error
Standard error thrown by `SC.SCanner` when it cannot find a string to skip.
Defined in: datetime.js.
SC.SelectionHandlesView

This View is used by Greenhouse when application is in design mode This view draws selection handles for a given designer. It will also forward any mouse events to the underlying designer.


Defined in: selection_handles.js.
SC.SelectViewMenu
Binds a menu view to an owning SC.SelectView, and checks selected items.
Defined in: select_view_menu.js.
SC.SMALL_CONTROL_SIZE String
Option for small control size.
Defined in: control.js.
SC.SNAP_ZONE

Defined in: snap_lines.js.
Author:

Mike Ball

Add this Mixin to any View and it gives you an API to draw snap lines for all the child views

.
SC.Statechart
A Statechart class.
Defined in: statechart.js.
SC.STRINGS Hash
Known loc strings
Defined in: core.js.
SC.SWIPE_ANY String

Defined in: swipe_gesture.js.
SC.SWIPE_DOWN String

Defined in: swipe_gesture.js.
SC.SWIPE_HORIZONTAL String

Defined in: swipe_gesture.js.
SC.SWIPE_LEFT String

Defined in: swipe_gesture.js.
SC.SWIPE_RIGHT String

Defined in: swipe_gesture.js.
SC.SWIPE_UP String

Defined in: swipe_gesture.js.
SC.SWIPE_VERTICAL String

Defined in: swipe_gesture.js.
SC.TABBING_ONLY_INSIDE_DOCUMENT

Default property to disable or enable if the focus can jump to the address bar or not.


Defined in: view.js.
SC.TableDelegate
A delegate for table resize operations.
Defined in: table_delegate.js.
SC.Task

Represents a single task which can be run by a task queue. Note that tasks are actually allowed to add themselves back onto the queue if they did not/ might not finish.


Defined in: task.js.
SC.TaskQueue

Runs a set of tasks. Most importantly, has a runWhenIdle option that allows it to run when no user input is occurring. This allows, for instance, preloading bundles while not blocking user interaction.


Defined in: task_queue.js.
SC.TestSuite

Adds a new module of unit tests to verify that the passed object implements the SC.Array interface. To generate, call the ArrayTests array with a test descriptor. Any properties you pass will be applied to the ArrayTests descendant created by the create method.

You should pass at least a newObject() method, which should return a new instance of the object you want to have tested. You can also implement the destroyObject() method, which should destroy a passed object.

SC.ArrayTests.generate("Array", {
  newObject:  function() { return []; }
});

newObject must accept an optional array indicating the number of items that should be in the array. You should initialize the the item with that many items. The actual objects you add are up to you.

Unit tests themselves can be added by calling the define() method. The function you pass will be invoked whenever the ArrayTests are generated. The parameter passed will be the instance of ArrayTests you should work with.

SC.ArrayTests.define(function(T) {
  T.module("length");

  test("verify length", function() {
    var ary = T.newObject();
    equals(ary.get('length'), 0, 'should have 0 initial length');
  });
}

Defined in: base.js.
SC.TINY_CONTROL_SIZE String
Option for tiny control size
Defined in: control.js.
SC.TO_LEFT String

Defined in: navigation.js.
SC.TO_RIGHT String

Defined in: navigation.js.
SC.TOGGLE_BEHAVIOR String

Defined in: button.js.
SC.TOGGLE_OFF_BEHAVIOR String

Defined in: button.js.
SC.TOGGLE_ON_BEHAVIOR String

Defined in: button.js.
SC.TOP_LOCATION String

Defined in: tab.js.
SC.TOP_TOOLBAR_LOCATION String

Defined in: tab.js.
SC.UNSUPPORTED
A constant indicating an unsupported method, property or other.
Defined in: platform.js.
SC.userDefaults
global user defaults.
Defined in: user_defaults.js.
SC.VERTICAL_ORIENTATION String

Defined in: core.js.
SC.WELL_CONTAINER_PADDING Number

Defined in: well.js.
Default value:
15
SC.ZERO_POINT
A Point at {0,0}
Defined in: rect.js.
SC.ZERO_RANGE
A zero length range at zero.
Defined in: range.js.

Class Method Detail

$error(description, label, code, c)
Shorthand form of the SC.Error.desc method.
Defined in: error.js.
Parameters:
description
{String} human readable description of the error
label
{String} human readable name of the item with the error
code
{Number} an error code to use for testing.
c
Returns:
SC.Error
new error instance.
bestStringMetricsForMaxWidth(string, maxWidth, exampleElement, classNames, ignoreEscape)

This function is similar to SC.metricsForString, but takes an extra argument after the string and before the exampleElement. That extra argument is maxWidth, which is the maximum allowable width in which the string can be displayed. This function will find the narrowest width (within maxWidth) that keeps the text at the same number of lines it would've normally wrapped to had it simply been put in a container of width maxWidth.

If you have text that's 900 pixels wide on a single line, but pass maxWidth as 800, the metrics that will be returned will specify a height of two lines' worth of text, but a width of only around 450 pixels. The width this function determines will cause the text to be split as evenly as possible over both lines.

If your text is 1500 pixels wide and maxWidth is 800, the width you'll get back will be approximately 750 pixels, because the 1500 horizontal pixels of text will still fit within two lines.

If your text grows beyond 1600 horizontal pixels, it'll wrap to three lines. Suppose you have 1700 pixels of text. This much text would require three lines at 800px per line, but this function will return you a width of approximately 1700/3 pixels, in order to fill out the third line of text so it isn't just ~100px long.

A binary search is used to find the optimimum width. There's no way to ask the browser this question, so the answer must be searched for. Understandably, this can cause a lot of measurements, which are NOT cheap.

Therefore, very aggressive caching is used in order to get out of having to perform the search. The final optimimum width is a result of all the following values:

  • The string itself
  • The styles on the exampleElement
  • The classNames passed in
  • Whether ignoreEscape is YES or NO

The caching goes against all of these in order to remember results. Note that maxWidth, though an argument, isn't one of them; this means that the optimal width will be searched for only once per distinct number of lines of text for a given string and styling. However, due to the fact that a passed exampleElement can have different styles a subsequent time it's passed in (but still remains the same object with the same GUID, etc), caching will not be enabled unless you either pass in a style string instead of an element, or unless your element has cacheableForMetrics: YES as a key on it. In most situations, the styles on an element won't change from call to call, so this is purely defensive and for arguably infrequent benefit, but it's good insurance. If you set the cacheableForMetrics key to YES on your exampleElement, caching will kick in, and repeated calls to this function will cease to have any appreciable amortized cost.

The caching works by detecting and constructing known intervals of width for each number of lines required by widths in those intervals. As soon as you get a result from this function, it remembers that any width between the width it returned and the maxWidth you gave it will return that same result. This also applies to maxWidths greater than the with you passed in, up until the width at which the text can fit inside maxWidth with one fewer line break. However, at this point, the function can't know how MUCH larger maxWidth can get before getting to the next widest setting. A simple check can be done at this point to determine if the existing cached result can be used: if the height of the string at the new maxWidth is the same as the cached height, then we know the string didn't fit onto one fewer line, so return the cached value. If we did this check, we could return very quickly after only one string measurement, but EACH time we increase the maxWidth we'll have to do a new string measurement to check that we didn't end up with horizontal room for one fewer line. Because of this, instead of doing the check, the function will perform its binary search to go all the way UP to the minimum maxWidth at which one fewer line can be used to fit the text. After caching this value, all subsequent calls to the function will result in no string measurements as long as all the maxWidths are within the interval determined to lead to the cached result. So, the second call can in some cases be more expensive than it needs to be, but this saves A LOT of expense on all subsequent calls. The less often one calls metricsForString, the happier one's life is.

The amount of time this function will take ranges from 0 to maybe 35ms on an old, slow machine, and, when used for window resizing, you'll see 35, 20, 0, 0, 0, ..., 0, 0, 35, 0, 0, 0, ..., 0, 0, 35, 0, 0, 0, ..., 0, 0, 0, 35, 0, 0, 0, ... After resizing through all the different caching intervals, the function will always execute quickly... under 1ms nearly always. The expensive calls are when a caching interval is crossed and a new cached set of metrics for the new number of lines of text must be calculated. And in reality, the number of sub-millisecond function calls will be much greater relative to the number of expensive calls, because window resizing just works like that.


Defined in: string_metric_optimization.js.
Parameters:
string String
The text whose width you wish to optimize within your maximum width preference.
maxWidth Number
The maximum width the text is allowed to span, period. Can have "px" afterwards. Need not be a whole number. It will be stripped of "px", and/or rounded up to the nearest integer, if necessary.
exampleElement Element/String
The element whose styles will be used to measure the width and height of the string. You can pass a string of CSSText here if you wish, just as with SC.metricsForString.
classNames String Optional
Optional. Any class names you wish to also put on the measurement element.
ignoreEscape Boolean Optional
Optional. If true, HTML in your string will not be escaped. If false or omitted, any HTML characters will be escaped for the measurement. If it's omitted where it should be true for correct results, the metrics returned will usually be much bigger than otherwise required.
binding(path, root)

Shorthand method to define a binding. This is the same as calling:

SC.binding(path) = SC.Binding.from(path)


Defined in: binding.js.
Parameters:
path
root
cacheSlotFor(your-arguments)

Supply any number of arguments of any type, and this function will return you a hash associated with all those arguments. Call it twice with the same arguments in the same order, and the hash is the same. This is great for getting out of calculations whose answers depend on many different variables.


Defined in: string_metric_optimization.js.
Parameters:
your-arguments anything
Any set of arguments whatsoever. If the FIRST argument is an array (including Arguments arrays), all other arguments will be ignored and the array will be treated as if its values at its numerical indices were passed in themselves as individual arguments.
Returns:
Hash
A cached workspace mapped to the ordered *n*-tuple of arguments passed into it.
centerX(innerFrame, outerFrame)
Returns the point that will center the frame X within the passed frame.
Defined in: utils.js.
Parameters:
innerFrame
outerFrame
centerY(innerFrame, outerFrame)
Return the point that will center the frame Y within the passed frame.
Defined in: utils.js.
Parameters:
innerFrame
outerFrame
cloneRange(r)
Returns a clone of the range.
Defined in: range.js.
Parameters:
r
cloneRect(r)

Duplicates the passed rect.

This is faster than Object.clone().


Defined in: rect.js.
Parameters:
r
{Rect} The rect to clone.
Returns:
Rect
The cloned rect
convertHexToHsv(hex)
Returns hsv color from hex value
Defined in: colors.js.
Parameters:
hex
convertHsvToHex(h, s, v)
Returns hex color from hsv value
Defined in: colors.js.
Parameters:
h
s
v
DateFormatter(date, f)

SC.DateFormatter is used with String.fmt to format dates with a format string. For example:

"My date: %{date:yyyy} %{date:MM} %{date:dd}".fmt(myDate, SC.DateFormatter)

You can use almost any of the Unicode Technical Standard #35 (draft 10) formatting strings. See:

http://unicode.org/reports/tr35/tr35-10.html#Date_Format_Patterns

Note that you can only put one (yyyy, MM, dd) per token, but you can put as many tokens as you'd like.


Defined in: date_formatter.js.
Parameters:
date
f
download(path)

Starts a download of the file at the named path.

Use this method when you want to cause a file to be downloaded to a users desktop instead of having it display in the web browser. Note that your server must return a header indicating that the file is intended for download also.


Defined in: misc.js.
Parameters:
path
expandColor(color)

Defined in: colors.js.
Parameters:
color
extend()
Alternative to mixin. Provided for compatibility with jQuery.
getStyle(oElm, strCssRule)

Defined in: misc.js.
Parameters:
oElm
strCssRule
hashesForLocale(languageCode, propertyName, hashes)

This special helper will store the propertyName / hashes pair you pass in the locale matching the language code. If a locale is not defined from the language code you specify, then one will be created for you with the english locale as the parent.


Defined in: locale.js.
Parameters:
languageCode String
propertyName String
hashes Hash
Returns:
void
heightForString(str, width, style, classNames, ignoreEscape)

Given a string and a fixed width, calculates the height of that block of text using a style string, a set of class names, or both.


Defined in: string_measurement.js.
Parameters:
str
{String} The text to calculate
width
{Number} The fixed width to assume the text will fill
style
{String} A CSS style declaration. E.g., 'font-weight: bold'
classNames
{Array} An array of class names that may affect the style
ignoreEscape
{Boolean} To NOT html escape the string.
Returns:
Number
The height of the text given the passed parameters
instanceOf(scObject, scClass)

Same as the instance method, but lets you check instanceOf without having to first check if instanceOf exists as a method.


Defined in: object.js.
Parameters:
scObject Object
the object to check instance of
scClass Class
the class
Returns:
Boolean
if object1 is instance of class
intersectRanges(r1, r2)
Returns the intersection of the two ranges or SC.RANGE_NOT_FOUND
Defined in: range.js.
Parameters:
r1
r2
intersectRects(r1, r2)
Returns the insersection between two rectangles.
Defined in: rect.js.
Parameters:
r1
{Rect} The first rect
r2
{Rect} the second rect
Returns:
Rect
the intersection rect. width || height will be 0 if they do not interset.
isPercentage(val)
Return true if the number is between 0 and 1
Defined in: utils.js.
Parameters:
val
kindOf(scObject, scClass)

Same as the instance method, but lets you check kindOf without having to first check if kindOf exists as a method.


Defined in: object.js.
Parameters:
scObject Object
object to check kind of
scClass Class
the class to check
Returns:
Boolean
if object is an instance of class or subclass
mapDisplayNames(obj, level, path, seenHash, seenArray)

Defined in: core.js.
Parameters:
obj
level
path
seenHash
seenArray
maxRange(range)
Returns the first value outside of the range.
Defined in: range.js.
Parameters:
range
maxX(frame)
Return the right edge of the frame.
Defined in: utils.js.
Parameters:
frame
maxY(frame)
Return the bottom edge of the frame
Defined in: utils.js.
Parameters:
frame
measureString(string, ignoreEscape)

Measures a string in the prepared environment.

An easier and simpler alternative (but less efficient for bulk measuring) is metricsForString.


Defined in: string_measurement.js.
Parameters:
string
{String} The string to measure.
ignoreEscape
{Boolean} To NOT html escape the string.
methodForLocale(languageCode, propertyName, method)
Just like SC.hashesForLocale, but for methods.
Defined in: locale.js.
Parameters:
languageCode String
propertyName String
method Function
Returns:
void
metricsFor(languageCode, metrics)
Just like SC.stringsFor, but for metrics.
Defined in: locale.js.
Parameters:
languageCode String
metrics Hash
Returns:
Object
receiver
metricsForString(string, exampleElement, classNames, ignoreEscape)

Given a string and an example element or style string, and an optional set of class names, calculates the width and height of that block of text.

To constrain the width, set max-width on the exampleElement or in the style string.


Defined in: string_measurement.js.
Parameters:
string
{String} The string to measure.
exampleElement
The example element to grab styles from, or the style string to use.
classNames
{String} (Optional) Class names to add to the test element.
ignoreEscape
{Boolean} To NOT html escape the string.
midX(frame)
Return the midpoint of the frame.
Defined in: utils.js.
Parameters:
frame
midY(frame)
Return the midpoint of the frame
Defined in: utils.js.
Parameters:
frame
minRange(range)
Returns first value of the range.
Defined in: range.js.
Parameters:
range
minX(frame)
Return the left edge of the frame
Defined in: utils.js.
Parameters:
frame
minY(frame)
Return the top edge of the frame
Defined in: utils.js.
Parameters:
frame
mixin(target, properties)

Adds properties to a target object.

Takes the root object and adds the attributes for any additional arguments passed.

Parameters:
target Object
the target object to extend
properties Object
one or more objects with properties to copy.
Returns:
Object
the target object.
normalizeURL(url)

Takes a URL of any type and normalizes it into a fully qualified URL with hostname. For example:

"some/path" => "http://localhost:4020/some/path"
"/some/path" => "http://localhost:4020/some/path"
"http://localhost:4020/some/path" => "http://localhost:4020/some/path"

Defined in: utils.js.
Parameters:
url
{String} the URL
Returns:
String
the normalized URL
offset(elem, relativeToFlag)

The offset of an element.

This function returns the left and top offset of an element with respect to either the document, the viewport or the element's parent element. In standard SproutCore applications, the coordinates of the viewport are equivalent to the document, but a HTML5 application that wishes to use this component of SproutCore might need to properly distinguish between the two.

For a useful discussion on the concepts of offsets and coordinates, see: http://www.quirksmode.org/mobile/viewports.html.


Defined in: utils.js.
Parameters:
elem DOMElement|jQuery|String
the element to find the offset of. This is passed to `jQuery()`, so any value supported by `jQuery()` will work.
relativeToFlag String
flag to determine which relative element to determine offset by. One of either: 'document', 'viewport' or 'parent' (default: 'document').
Returns:
Object
the offset of the element as an Object (ie. Hash) in the form { x: value, y: value }.
ok(ret)
Returns NO if the passed value is an error object or false.
Defined in: error.js.
Parameters:
ret Object
object value
Returns:
Boolean
outlet(path, root)

Generates a computed property that will look up the passed property path the first time you try to get the value. Use this whenever you want to define an outlet that points to another view or object. The root object used for the path will be the receiver.


Defined in: view.js.
Parameters:
path
root
parseColor(string)

Defined in: colors.js.
Parameters:
string
pointInElement(point, elem, includeFlag, relativeToFlag)

Determines if the given point is within the given element.

The test rect will include the element's padding and can be configured to optionally include the border or border and margin.


Defined in: misc.js.
Parameters:
point Object
the point as an Object (ie. Hash) in the form { x: value, y: value }.
elem DOMElement|jQuery|String
the element to test inclusion within. This is passed to `jQuery()`, so any value supported by `jQuery()` will work.
includeFlag String
flag to determine the dimensions of the element to test within. One of either: 'padding', 'border' or 'margin' (default: 'border').
relativeToFlag String
flag to determine which relative element to determine offset by. One of either: 'document', 'viewport' or 'parent' (default: 'document').
Returns:
Boolean
YES if the point is within the element; NO otherwise
pointInRect(point, f)
Check if the given point is inside the rect.
Defined in: rect.js.
Parameters:
point
f
prepareStringMeasurement(exampleElement, classNames)

Sets up a string measuring environment.

You may want to use this, in conjunction with teardownStringMeasurement and measureString, instead of metricsForString, if you will be measuring many strings with the same settings. It would be a lot more efficient, as it would only prepare and teardown once instead of several times.


Defined in: string_measurement.js.
Parameters:
exampleElement
The example element to grab styles from, or the style string to use.
classNames
{String} (Optional) Class names to add to the test element.
propertyFromRenderDelegate(propertyName, def)

Generates a computed property that will look up the specified property from the view's render delegate, if present. You may specify a default value to return if there is no such property or is no render delegate.

The generated property is read+write, so it may be overridden.


Defined in: theming.js.
Parameters:
propertyName String
The name of the property to get from the render delegate..
def Value
The default value to use if the property is not present.
rangesEqual(r1, r2)

Returns true if the two passed ranges are equal. A null value is treated like RANGE_NOT_FOUND.


Defined in: range.js.
Parameters:
r1
r2
rectsEqual(r1, r2, delta)
Return true if the two frames match. You can also pass only points or sizes.
Defined in: rect.js.
Parameters:
r1
{Rect} the first rect
r2
{Rect} the second rect
delta
{Float} an optional delta that allows for rects that do not match exactly. Defaults to 0.1
Returns:
Boolean
true if rects match
run(callback, target, if)

Executes a passed function in the context of a run loop. If called outside a runloop, starts and ends one. If called inside an existing runloop, is simply executes the function unless you force it to create a nested runloop.

If an exception is thrown during execution, we give an error catcher the opportunity to handle it before allowing the exception to bubble again.


Defined in: run_loop.js.
Parameters:
callback Function
callback to execute
target Object
context for callback
if Boolean
YES, starts/ends a new runloop even if one is already running
scaleRect(rect, scale, originX, originY)
Returns a copy of the passed rect, scaled by the specified scale, centered on the specified origin.
Defined in: rect.js.
Parameters:
rect Rect
The rectangle to scale.
scale Number|Array|Hash
The scale (or [scaleX, scaleY], or { x: scaleX, y: scaleY}) to apply. Defaults to 1.
originX Number
The horizontal scale origin. Defaults to 0.5 (center).
originY Number
The vertical scale origin. Defaults to 0.5 (center).
Returns:
Rect
The scaled rect.
setupBodyClassNames()

Defined in: loader.js.
stringFromLayout(layout)

Returns a string representation of the layout hash.

Layouts can contain the following keys: - left: the left edge - top: the top edge - right: the right edge - bottom: the bottom edge - height: the height - width: the width - centerX: an offset from center X - centerY: an offset from center Y - minWidth: a minimum width - minHeight: a minimum height - maxWidth: a maximum width - maxHeight: a maximum height - rotateX - rotateY - rotateZ - scale


Defined in: string_measurement.js.
Parameters:
layout
{Hash} The layout hash to stringify.
Returns:
String
A string representation of the layout hash.
stringFromRect(r)
Returns a string representation of the rect as {x, y, width, height}.
Defined in: rect.js.
Parameters:
r
{Rect} The rect to stringify.
Returns:
String
A string representation of the rect.
stringsFor(lang, strings)

This is a simplified handler for installing a bunch of strings. This ignores the language name and simply applies the passed strings hash.


Defined in: core.js.
Parameters:
lang String
the language the strings are for
strings Hash
hash of strings
Returns:
SC
The receiver, useful for chaining calls to the same object.
subtractRanges(r1, r2)
Returns the difference of the two ranges or SC.RANGE_NOT_FOUND
Defined in: range.js.
Parameters:
r1
r2
supplement(target, properties)

Adds properties to a target object. Unlike SC.mixin, however, if the target already has a value for a property, it will not be overwritten.

Takes the root object and adds the attributes for any additional arguments passed.

Parameters:
target Object
the target object to extend
properties Object
one or more objects with properties to copy.
Returns:
Object
the target object.
switchScale()

Switch the scale of your app. Useful when visualizing apps not designed for iphone.


Defined in: misc.js.
teardownStringMeasurement()

Tears down the string measurement environment. Usually, this doesn't have to be called, but there are too many what ifs: for example, what if the measurement environment has a bright green background and is over 10,000px wide? Guess what: it will become visible on the screen.

So, generally, we tear the measurement environment down so that it doesn't cause issue. However, we keep the DOM element for efficiency.


Defined in: string_measurement.js.
throw(description, label, code, c)
Shorthand form of the SC.Error.throw method.
Defined in: error.js.
Parameters:
description
{String} human readable description of the error
label
{String} human readable name of the item with the error
code
{Number} an error code to use for testing.
c
Returns:
SC.Error
new error instance.
toColorPart(number)

Defined in: colors.js.
Parameters:
number
uniJapaneseConvert(str)

Defined in: misc.js.
Parameters:
str
unionRanges(r1, r2)

Returns the union of two ranges. If one range is null, the other range will be returned.


Defined in: range.js.
Parameters:
r1
r2
unionRects(r1, r2)
Returns the union between two rectangles
Defined in: rect.js.
Parameters:
r1
{Rect} The first rect
r2
{Rect} The second rect
Returns:
Rect
The union rect.
val(obj)

Returns the value of an object. If the passed object is an error, returns the value associated with the error; otherwise returns the receiver itself.


Defined in: error.js.
Parameters:
obj Object
the object
Returns:
Object
value
valueInRange(value, range)
Returns true if the passed index is in the specified range
Defined in: range.js.
Parameters:
value
range
viewFor(element)

Returns the SC.View instance managing the given element.

If no instance is found, returns null.


Defined in: core.js.
Parameters:
element DOMElement
The element to check.
Returns:
SC.View
The view managing the element or null if none found.
Deprecated:

Use SC.offset instead.

SC.offset() is more accurate, more flexible in the value for the element parameter and easier to understand.

viewportOffset(el)

Defined in: utils.js.
Parameters:
el
The DOM element
Returns:
Point
A hash with x, y offsets.
Documentation generated by JsDoc Toolkit 2.4.0 on Wed Apr 08 2015 10:02:20 GMT-0600 (CST)