Class: SC.Object


Extends SC.Observable.

Root object for the SproutCore framework. SC.Object is the root class for most classes defined by SproutCore. It builds on top of the native object support provided by JavaScript to provide support for class-like inheritance, automatic bindings, properties observers, and more.

Most of the classes you define in your application should inherit from SC.Object or one of its subclasses. If you are writing objects of your own, you should read this documentation to learn some of the details of how SC.Object's behave and how they differ from other frameworks.

About SproutCore Classes

JavaScript is not a class-based language. Instead it uses a type of inheritance inspired by self called "prototypical" inheritance. ...

Using SproutCore objects with other JavaScript object.

You can create a SproutCore object just like any other object... obj = new SC.Object();

Defined in: object.js

Since:
SproutCore 1.0

Field Summary

Class Methods

Instance Methods

Field Detail

concatenatedProperties Array

The properties named in this array will be concatenated in subclasses instead of replaced. This allows you to name special properties that should contain any values you specify plus values specified by parents.

It is used by SproutCore and is available for your use, though you should limit the number of properties you include in this list as it adds a slight overhead to new class and instance creation.

SC.Object.isClass Boolean
Walk like a duck. You can use this to quickly test classes.
isDestroyed Boolean
This is set to YES once this object has been destroyed.
isObject Boolean
Walk like a duck. Always YES since this is an object and not a class.
nextProperty String

The property key on +object+ that contains the object represented by the next node in the chain.


Defined in: property_chain.js.
object Object
The object represented by this node in the chain.
Defined in: property_chain.js.
property String

The key on the previous object in the chain that contains the object represented by this node in the chain.


Defined in: property_chain.js.
SC.Object.subclasses SC.Set

Set of subclasses that extend from this class. You can observe this array if you want to be notified when the object is extended.

SC.Object.superclass SC.Object

Points to the superclass for this class. You can use this to trace a class hierarchy.

target Object

The target object. This is the object passed to createChain(), and the object which contains the +toInvalidate+ property that will be invalidated if +property+ changes.


Defined in: property_chain.js.
toInvalidate String
The property of +target+ to invalidate when +property+ changes.
Defined in: property_chain.js.

Class Method Detail

create(props)

Creates a new instance of the class.

Unlike most frameworks, you do not pass parameters to the init function for an object. Instead, you pass a hash of additional properties you want to have assigned to the object when it is first created. This is functionally like creating an anonymous subclass of the receiver and then instantiating it, but more efficient.

You can use create() like you would a normal constructor in a class-based system, or you can use it to create highly customized singleton objects such as controllers or app-level objects. This is often more efficient than creating subclasses and then instantiating them.

You can pass any hash of properties to this method, including mixins.

Parameters:
props Hash
optional hash of method or properties to add to the instance.
Returns:
SC.Object
new instance of the receiver class.
design(attrs)

This method works just like extend() except that it will also preserve the passed attributes.

Parameters:
attrs Hash
Attributes to add to view
Returns:
Class
SC.Object subclass to create
extend(props)

Creates a new subclass of the receiver, adding any passed properties to the instance definition of the new class. You should use this method when you plan to create several objects based on a class with similar properties.

Init:

If you define an init() method, it will be called when you create instances of your new class. Since SproutCore uses the init() method to do important setup, you must be sure to always call sc_super() somewhere in your init() to allow the normal setup to proceed.

Parameters:
props Hash
the methods of properties you want to add
Returns:
Class
A new object class
hasSubclass(scClass)

Returns YES if the passed object is a subclass of the receiver. This is the inverse of subclassOf() which you call on the class you want to test.

Parameters:
scClass Class
class to compare
Returns:
Boolean
kindOf(scClass)

Returns YES if the receiver is the passed class or is a subclass of the passed class. Unlike subclassOf(), this method will return YES if you pass the receiver itself, since class is a kind of itself. See also subclassOf().

Example:

ClassA = SC.Object.extend();
  ClassB = ClassA.extend();

  ClassB.kindOf(ClassA) => YES
  ClassA.kindOf(ClassA) => YES
Parameters:
scClass Class
class to compare
Returns:
Boolean
mixin(props)

Adds the passed properties to the object's class definition. You can pass as many hashes as you want, including Mixins, and they will be added in the order they are passed.

This is a shorthand for calling SC.mixin(MyClass, props...);

Parameters:
props Hash
the properties you want to add.
Returns:
Object
receiver
reopen(props)
Parameters:
props
subclassOf(scClass)

Returns YES if the receiver is a subclass of the named class. If the receiver is the class passed, this will return NO since the class is not a subclass of itself. See also kindOf().

Example:

ClassA = SC.Object.extend();
  ClassB = ClassA.extend();

  ClassB.subclassOf(ClassA) => YES
  ClassA.subclassOf(ClassA) => NO
Parameters:
scClass Class
class to compare
Returns:
Boolean

Instance Method Detail

activate(newObject)

Registers this segment of the chain with the object it represents.

This should be called with the object represented by the previous node in the chain as the first parameter. If no previous object is provided, it will assume it is the root node in the chain and treat the target as the previous object.


Defined in: property_chain.js.
Parameters:
newObject Object Optional
The object in the chain to hook to.
Deprecated: v1.11 - use init instead.
awake()
deactivate()

Removes this segment of the chain from the object it represents. This is usually called when the object represented by the previous segment in the chain changes.


Defined in: property_chain.js.
destroy()

Call this method when you are finished with an object to teardown its contents. Because JavaScript is garbage collected, you do not usually need to call this method. However, you may choose to do so for certain objects, especially views, in order to let them reclaim memory they consume immediately.

If you would like to perform additional cleanup when an object is finished, you may override this method. Be sure to call sc_super().

Returns:
SC.Object
receiver
emitDesign()
Patch SC.Object to respond to design
Defined in: object.js.
encodeDesign(coder)

Patch SC.Object to respond to encodeDesign(). This will proxy to the paired designer, if there is one. If there is no paired designer, returns NO.


Defined in: object.js.
Parameters:
coder
init()

This method is invoked automatically whenever a new object is instantiated. You can override this method as you like to setup your new object.

Within your object, be sure to call sc_super() to ensure that the built-in init method is also called or your observers and computed properties may not be configured.

Although the default init() method returns the receiver, the return value is ignored.

instanceOf(scClass)

returns YES if the receiver is an instance of the named class. See also kindOf().

Example

var ClassA = SC.Object.extend();
  var ClassB = SC.Object.extend();

  var instA = ClassA.create();
  var instB = ClassB.create();

  instA.instanceOf(ClassA) => YES
  instB.instanceOf(ClassA) => NO
Parameters:
scClass Class
the class
Returns:
Boolean
invokeLast(method)

Invokes the passed method once at the end of the current run of the run loop, before any other methods (including new events) are processed. This is useful for situations where you know you need to update something, but due to the way the run loop works, you can't actually do the update until the run loop has completed.

A simple example is setting the selection on a collection controller to a newly created object. Because the collection controller won't have its content collection updated until later in the run loop, setting the selection immediately will have no effect. In this situation, you could do this instead:

// Creates a new MyRecord object and sets the selection of the
  // myRecord collection controller to the new object.
  createObjectAction: function (sender, evt) {
    // create a new record and add it to the store
    var obj = MyRecord.newRecord();

    // update the collection controller's selection
    MyApp.myRecordCollectionController.invokeLast( function () {
      this.set('selection', [obj]);
    });
  }

Note that in development mode only, the object and method that call this method will be recorded, for help in debugging scheduled code.

Parameters:
method Function|String
method or method name
Returns:
SC.Object
receiver
invokeLater(method, interval)

Invokes the named method after the specified period of time. This uses SC.Timer, which works properly with the Run Loop.

Any additional arguments given to invokeOnce will be passed to the method.

For example,

var obj = SC.Object.create({
  myMethod: function(a, b, c) {
    alert('a: %@, b: %@, c: %@'.fmt(a, b, c));
  }
});

obj.invokeLater('myMethod', 200, 'x', 'y', 'z');

// After 200 ms, alerts "a: x, b: y, c: z"

Defined in: object.js.
Parameters:
method
{String} method name to perform.
interval
{Number} period from current time to schedule.
Returns:
SC.Timer
scheduled timer.
invokeNext(method)

Invokes the passed target/method pair once at the beginning of the next run of the run loop, before any other methods (including events) are processed. Use this to defer painting to make views more responsive or to ensure that the layer has been updated before using it.

If you call this with the same target/method pair multiple times it will only invoke the pair only once at the beginning of the next runloop.

Note that in development mode only, the object and method that call this method will be recorded, for help in debugging scheduled code.

Parameters:
method Function|String
method or method name
Returns:
SC.Object
receiver
invokeOnce(method)

Invokes the passed method or method name one time during the runloop. You can use this method to schedule methods that need to execute but may be too expensive to execute more than once, such as methods that update the DOM.

Note that in development mode only, the object and method that call this method will be recorded, for help in debugging scheduled code.

Parameters:
method Function|String
method or method name
Returns:
SC.Object
receiver
invokeOnceLater(method, interval)

A convenience method which makes it easy to coalesce invocations to ensure that the method is only called once after the given period of time. This is useful if you need to schedule a call from multiple places, but only want it to run at most once.

Any additional arguments given to invokeOnceLater will be passed to the method.

For example,

var obj = SC.Object.create({
  myMethod: function(a, b, c) {
    alert('a: %@, b: %@, c: %@'.fmt(a, b, c));
  }
});

obj.invokeOnceLater('myMethod', 200, 'x', 'y', 'z');

// After 200 ms, alerts "a: x, b: y, c: z"

Defined in: object.js.
Parameters:
method Function|String
reference or method name
interval Number
invokeWith(pathName, target, method)

Lookup the named property path and then invoke the passed function, passing the resulting value to the function.

This method is a useful way to handle deferred loading of properties. If you want to defer loading a property, you can override this method. When the method is called, passing a deferred property, you can load the property before invoking the callback method.

You can even swap out the receiver object.

The callback method should have the signature:

function callback(objectAtPath, sourceObject) { ... }

You may pass either a function itself or a target/method pair.


Defined in: object.js.
Parameters:
pathName String
target Object
target or method
method Function|String
Returns:
SC.Object
receiver
kindOf(scClass)

Returns true if the receiver is an instance of the named class or any subclass of the named class. See also instanceOf().

Example

var ClassA = SC.Object.extend();
  var ClassB = SC.Object.extend();

  var instA = ClassA.create();
  var instB = ClassB.create();

  instA.kindOf(ClassA) => YES
  instB.kindOf(ClassA) => YES
Parameters:
scClass Class
the class
Returns:
Boolean
mixin(ext)

You can call this method on an object to mixin one or more hashes of properties on the receiver object. In addition to simply copying properties, this method will also prepare the properties for use in bindings, computed properties, etc.

If you plan to use this method, you should call it before you call the inherited init method from SC.Object or else your instance may not function properly.

Example:

// dynamically apply a mixin specified in an object property
  var MyClass = SC.Object.extend({
     extraMixin: null,

     init: function () {
       this.mixin(this.extraMixin);
       sc_super();
     }
  });

  var ExampleMixin = { foo: "bar" };

  var instance = MyClass.create({ extraMixin: ExampleMixin });

  instance.get('foo') => "bar"
Parameters:
ext Hash
a hash to copy. Only one.
Returns:
Object
receiver
notifyPropertyDidChange()
Invalidates the +toInvalidate+ property of the +target+ object.
Defined in: property_chain.js.
respondsTo(methodName)
Returns YES if the named value is an executable function.
Parameters:
methodName String
the property name to check
Returns:
Boolean
Deprecated:

v1.11 - use sc_super() (with build tools) or arguments.callee.base.apply(this, arguments) instead.

EXPERIMENTAL: You can use this to invoke a superclass implementation in any method. This does not work in Safari 2 or earlier. If you need to target these methods, you should use one of the alternatives below:

  • With Build Tools: sc_super();
  • Without Build Tools: arguments.callee.base.apply(this, arguments);

Example

All of the following methods will call the superclass implementation of your method:

SC.Object.create({

    // DOES NOT WORK IN SAFARI 2 OR EARLIER
    method1: function () {
      this.superclass();
    },

    // REQUIRES SC-BUILD TOOLS
    method2: function () {
      sc_super();
    },

    // WORKS ANYTIME
    method3: function () {
      arguments.callee.base.apply(this, arguments);
    }
  });
superclass(args)
Parameters:
args *args
any arguments you want to pass along.
Returns:
Object
return value from super
toString()
Returns a string representation of the chain segment.
Defined in: property_chain.js.
Returns:
String
tryToPerform(methodName, arg1, arg2)

Attempts to invoke the named method, passing the included two arguments. Returns NO if the method is either not implemented or if the handler returns NO (indicating that it did not handle the event). This method is invoked to deliver actions from menu items and to deliver events. You can override this method to provide additional handling if you prefer.

Parameters:
methodName String
arg1 Object
arg2 Object
Returns:
Boolean
YES if handled, NO if not handled
Documentation generated by JsDoc Toolkit 2.4.0 on Wed Apr 08 2015 10:02:21 GMT-0600 (CST)