NSObject+Model documentation

Authors

Generated by builder

Contents -

  1. Software documentation for the NSDate(ETModelAdditions) category
  2. Software documentation for the NSNumber(ETModelAdditions) category
  3. Software documentation for the NSObject(ETModelAdditions) category
  4. Software documentation for the NSString(ETModelAdditions) category
  5. NSObject+Model constants

Software documentation for the NSDate(ETModelAdditions) category

NSDate(ETModelAdditions)

Declared in:
NSObject+Model.h

@group Model and Metamodel

Method summary

isCommonObjectValue 

- (BOOL) isCommonObjectValue;

Returns YES.


Software documentation for the NSNumber(ETModelAdditions) category

NSNumber(ETModelAdditions)

Declared in:
NSObject+Model.h

@group Model and Metamodel

Method summary

isCommonObjectValue 

- (BOOL) isCommonObjectValue;

Returns YES.


Software documentation for the NSObject(ETModelAdditions) category

NSObject(ETModelAdditions)

Declared in:
NSObject+Model.h
Conforms to:
ETPropertyValueCoding

@group Model and Metamodel

Method summary

mutableClass 

+ (Class) mutableClass;

@taskunit Collection and Mutability

Returns a mutable counterpart class or Nil if such a class does not exist.

Returns a mutable counterpart class or Nil if such a class does not exist.


newBasicEntityDescription 

+ (ETEntityDescription*) newBasicEntityDescription;
Subclasses must NOT override this method.

Returns a new minimal self-description without any property descriptions.

This entity description uses the class name as its name and the parent is set to the superclass name.
The parent will be resolved once when the description is added to the repository.

You must never use this method to retrieve an entity description, but only a ETModelDescriptionRepository instance to do so.

The returned object is not autoreleased.

See also -newEntityDescription .


newEntityDescription 

+ (ETEntityDescription*) newEntityDescription;
An empty method provided for subclasses to override.

Returns a new self-description (aka metamodel).

You must never use this method to retrieve an entity description, but only retrieves it through a ETModelDescriptionRepository instance.

This method can be invoked at runtime by a repository to automatically collect the entity descriptions and make them available in this repository.

You can implement this method to describe your subclasses more precisely than -basicNewEntityDescription .
You must never call [super newEntityDescription] in the implementation.
You must not return an autoreleased object.

For example:

ETEntityDescription *desc = [self newBasicEntityDescription];

// For subclasses that don't override -newEntityDescription, we must not add the 
// property descriptions that we will inherit through the parent (the 
// 'MyClassName' entity description).
if ([[desc name] isEqual: [MyClass className]] == NO) return desc;

ETPropertyDescription *city = [ETPropertyDescription descriptionWithName: @"city" type: (id)@"NSString"];
ETPropertyDescription *country = [ETPropertyDescription descriptionWithName: @"country" type: (id)@"NSString"];

[desc setPropertyDescriptions: A(city, country)];

[desc setAbstract: YES];

return desc;

If you want set the parent explicitly, replace -newBasicEntityDescription with:

ETEntityDescription *desc = [ETEntityDescription descriptionWithName: [self className]];

// Will be resolved when the entity description is put in the repository
[desc setParent: NSStringFromClass([self superclass])];

objectWithObjectValue: 

+ (id) objectWithObjectValue: (id)object;
Description forthcoming.

objectWithStringValue: 

+ (id) objectWithStringValue: (NSString*)string;
Description forthcoming.

addObserver: 

- (void) addObserver: (id)anObserver;

Sets up the given object to observe each receiver key paths returned by -observableKeyPaths .

The observer will receive NSKeyValueObservingOptionOld and NSKeyValueObservingOptionNew in the change dictionary.


basicValueForKey: 

- (id) basicValueForKey: (NSString*)key;

@taskunit Key Value Coding

Returns the value identified by key as NSObject does, even if -valueForKey: is overriden. This method allows to use basic KVC access (through ivars and accessors) from -valueForProperty: or other methods in subclasses, when a custom KVC strategy is implemented in subclasses for -valueForKey: .

Returns the value identified by key as NSObject does, even if -valueForKey: is overriden. This method allows to use basic KVC access (through ivars and accessors) from -valueForProperty: or other methods in subclasses, when a custom KVC strategy is implemented in subclasses for -valueForKey: .


descriptionWithOptions: 

- (NSString*) descriptionWithOptions: (NSMutableDictionary*)options;

Returns a description generated based on the given options.

Might describe a tree or graph structure if a traversal key is provided to recursively invoke -descriptionsWithOptions: on each object node. To do so, put ETDescriptionOptionTraversalKey with a valid KVC key in the options. You can also set a max depth with ETDescriptionOptionMaxDepth to limit the description size or end a graph traversal.

You can collect key path values on each object node by specifying an array of key paths with ETDescriptionOptionValuesForKeyPaths.

The description format is roughly: depth based indentation + object short description + keyPath1: value1, keyPath2: value2 etc.

By default, -description is used to print both object short description and key path values.

For customizing the object short description, put kETDescriptionOptionShortDescriptionSelector with a custom selector string in the options (-description is then used as fallback).
If you override -description to call -descriptionWithOptions: , you must provide a valid kETDescriptionOptionShortDescriptionSelector to prevent an endless loop (for example, just use -primitiveDescription).

For presenting each key path on a new line, put kETDescriptionOptionPropertyIndent with a tab string in the options.

Here is an example based on EtoileUI that dumps an item tree structure:

// ObjC code
ETLog(@"\n%@\n", [browserItem descriptionWithOptions: [NSMutableDictionary dictionaryWithObjectsAndKeys: 
	A(@"frame", @"autoresizingMask"), kETDescriptionOptionValuesForKeyPaths,
	@"items", kETDescriptionOptionTraversalKey, nil]]);

// Console Output
<ETLayoutItemGroup: 0x9e7b268> { frame: {x = 0; y = 0; width = 600; height = 300}, autoresizingMask: 18 }
	<ETLayoutItemGroup: 0x9fbea48> { frame: {x = 0; y = 0; width = 1150; height = 53}, autoresizingMask: 2 }
		<ETLayoutItem: 0x9f29240> { frame: {x = 12; y = 12; width = 100; height = 22}, autoresizingMask: 0 }
		<ETLayoutItem: 0x9e6fcf0> { frame: {x = 124; y = 12; width = 100; height = 24}, autoresizingMask: 0 }
	<ETLayoutItemGroup: 0x9fac170> { frame: {x = 0; y = 0; width = 1150; height = 482}, autoresizingMask: 18 }
		<ETLayoutItemGroup: 0x9fb2870> { frame: {x = 0; y = 0; width = 50; height = 50}, autoresizingMask: 0 }

options must not be nil, otherwise raises an NSInvalidArgumentException.

You can override this method in subclasses, although it is not advised to. The options dictionary can be changed arbitrarily in a new implementation.


displayName 

- (NSString*) displayName;

@taskunit Basic Properties

Returns the receiver description. Subclasses can override this method to return a more appropriate display name.

Returns the receiver description. Subclasses can override this method to return a more appropriate display name.


insertionKeyForCollection: 

- (id) insertionKeyForCollection: (id<ETKeyedCollection>)aCollection;
An empty method provided for subclasses to override.

Returns a key for inserting the receiver into the given keyed collection.

By default, returns a key built by incrementing the integer value in the 'Unknown <number>' pattern, until it provides a key not yet in use in the collection argument.

This key is retrieved by a collection in reply to -insertObjects:atIndexes:hints: of ETCollectionMutation protocol. You can return different keys depending on the type of collection. This parameter is usually the mutated collection itself.


isCollection 

- (BOOL) isCollection;
Subclasses must NOT override this method.

Returns YES if the receiver is declared as a collection by conforming to ETCollection protocol, otherwise returns NO.

You must never override this method in your collection classes, you only need to adopt ETCollection protocol.


isCommonObjectValue 

- (BOOL) isCommonObjectValue;

Returns YES when the receiver is an object which can be passed to -setObjectValue: or returned by -objectValue . Some common object values like string and number can be displayed and edited transparently (in an NSCell instance to take an example). If you define additional common object values, you usually have to write related formatters. Returns NO by default. Subclasses can override this method to specify an object can be accepted and used a common object value.


isGroup 

- (BOOL) isGroup;
An empty method provided for subclasses to override.

Returns YES if the receiver is declared as a group, otherwise returns NO.

This method returns NO by default. You can override it to return YES if you want to declare your subclass instances as groups.

A group is specialized model object which is a composite and can behave like a mutable collection. A basic collection object (like NSMutableArray, NSMutableDictionary, NSMutableSet) must never be declared as a group.
COGroup in CoreObject or ETLayoutItemGroup in EtoileUI are typical examples.

A group should conform to ETCollectionMutation protocol.


isMutable 

- (BOOL) isMutable;
An empty method provided for subclasses to override.

Returns YES if the receiver is declared as mutable, otherwise returns NO.

This method returns NO by default. You can override it to return YES if you want to declare your subclass instances as mutable objects (which are collections most of time).

If you adopts ETCollectionMutation in a subclass, you don't need to override this method to declare your collection objects as mutable.


isMutableCollection 

- (BOOL) isMutableCollection;
Subclasses must NOT override this method.

Returns YES if the receiver is declared as a collection by conforming to ETCollectionMutation protocol, otherwise returns NO.

You must never override this method in your collection classes, you only need to adopt ETCollectionMutation protocol.


isNumber 

- (BOOL) isNumber;

Returns YES if the receiver is an NSNumber instance, otherwise returns NO.


isPrimitiveCollection 

- (BOOL) isPrimitiveCollection;
Subclasses must NOT override this method.

Returns YES if the receiver is a low-level collection such as NSArray, NSet, etc., otherwise returns NO.

For a model object such as ETLayoutItemGroup that conforms to ETCollection protocol, would return NO.


isString 

- (BOOL) isString;

Returns YES if the receiver is an NSString instance, otherwise returns NO.


objectValue 

- (id) objectValue;
Description forthcoming.

observableKeyPaths 

- (NSSet*) observableKeyPaths;
An empty method provided for subclasses to override.

@taskunit KVO Syntactic Sugar (Unstable API)

Returns an empty set.
Overrides to return the receiver key paths to be observed when an observer is set up with -addObserver: .

The returned set content must not change during the whole object lifetime, otherwise -removeObserver: will crash randomly.

Returns an empty set.
Overrides to return the receiver key paths to be observed when an observer is set up with -addObserver: .

The returned set content must not change during the whole object lifetime, otherwise -removeObserver: will crash randomly.


primitiveDescription 

- (NSString*) primitiveDescription;
Subclasses must NOT override this method.

Returns the description as NSObject would. This method returns the same value as -description if the latter method isn't overriden in your subclasses, otherwise it returns the value that -description would return if you haven't overriden it. Useful to get consistent short descriptions on all instances and can be used to provide custom description built with other short descriptions.


propertyNames 

- (NSArray*) propertyNames;

Returns both the property names bound to the object entity description and the basic property names. +ETModelDescriptionRepository mainRepository] is used to look up the entity description.

To be exposed through Property Value Coding, the receiver properties must be listed among the returned properties. Can be overriden to return property names bound to entity descriptions that don't belong to the main repository, or filter some properties out. In the overriden method, you should usually return -basicPropertyNames along the property description names. For a NSObject subclass not bound to an entity description, the property names related to the closest superclass bound to an entity description are returned through a recursive lookup in -entityDescriptionForClass: . See -basicPropertyNames , -valueForProperty: and -setValue:forProperty: . See also -[ETPropertyValueCoding propertyNames].


removeObserver: 

- (void) removeObserver: (id)anObserver;

Removes the observer that was observing the receiver key paths returned by -observableKeyPaths .


requiresKeyValueCodingForAccessingProperties 

- (BOOL) requiresKeyValueCodingForAccessingProperties;

@taskunit Property Value Coding

Returns NO.

See -[ETPropertyValueCoding requiresKeyValueCodingForAccessingProperties].

Returns NO.

See -[ETPropertyValueCoding requiresKeyValueCodingForAccessingProperties].


setBasicValue: forKey: 

- (void) setBasicValue: (id)value forKey: (NSString*)key;

Sets the value identified by key as NSObject does, even if -setValue:forKey: is overriden. This method allows to use basic KVC access (through ivars and accessors) from -setValue:forProperty: or other methods in subclasses, when a custom KVC strategy is implemented in subclasses for -setValue:forKey: .


setValue: forProperty: 

- (BOOL) setValue: (id)value forProperty: (NSString*)key;

See -[ETPropertyValueCoding setValue:forProperty:].


setValue: forPropertyPath: 

- (BOOL) setValue: (id)aValue forPropertyPath: (NSString*)aPropertyPath;
Description forthcoming.

stringValue 

- (NSString*) stringValue;
An empty method provided for subclasses to override.

Returns the description of the receiver by default.

Subclasses can override this method to return a string representation that encodes some basic infos about the receiver. This string representation can then be edited, validated by -validateValue:forKey:error: and used to instantiate another object by passing it to +objectWithStringValue: .


stringValueWithOptions: 

- (NSString*) stringValueWithOptions: (NSDictionary*)outputOptions;

Returns -stringValue by default.

Subclasses can override this method to return a custom string representation based on the given rendering options. Like -stringValue , it should encode some basic infos about the receiver but the method is typically used to introduce variations in the output format. For example to handle pretty printing and special formatting rules.

Not all output options have to be handled, you can safely ignore options which you aren't interested in.

The resulting string representation must remain editable, validatable by -validateValue:forKey:error: and usable to instantiate another object by passing it to +objectWithStringValue: .


typeForKey: 

- (NSString*) typeForKey: (NSString*)key;
Description forthcoming.

valueForProperty: 

- (id) valueForProperty: (NSString*)key;

See -[ETPropertyValueCoding valueForProperty:].


valueForPropertyPath: 

- (id) valueForPropertyPath: (NSString*)aPropertyPath;
Description forthcoming.

Software documentation for the NSString(ETModelAdditions) category

NSString(ETModelAdditions)

Declared in:
NSObject+Model.h

@group Model and Metamodel

Method summary

isCommonObjectValue 

- (BOOL) isCommonObjectValue;

Returns YES.


NSObject+Model constants

ETCollectionDidUpdateNotification

NSString* const ETCollectionDidUpdateNotification;

Posts this notification to let other objects know about collection mutation in your model object.

For example, EtoileUI uses this notification to reload the UI transparently. See -[ETLayoutItemGroup setRepresentedObject:].


kETDescriptionOptionMaxDepth

NSString* const kETDescriptionOptionMaxDepth;

Integer number object to indicate the depth at which -descriptionWithOptions: should stop to traverse collections with kETDescriptionOptionTraversalKey.

Default value is 20.


kETDescriptionOptionPropertyIndent

NSString* const kETDescriptionOptionPropertyIndent;

String used as the base indentation for properties in -descriptionWithOptions: .

For an empty string, all properties are output on the same line.
For other indentation e.g. a tab, each property is output on a distinct line.

Default value is an empty string.


kETDescriptionOptionShortDescriptionSelector

NSString* const kETDescriptionOptionShortDescriptionSelector;

Selector string to indicate which method should be called to print a short object description.

If the receiver doesn't respond to this selector, then -description is used.

Default value is 'description'.


kETDescriptionOptionTraversalKey

NSString* const kETDescriptionOptionTraversalKey;

Key-Value-Coding key to indicate a value to be treated as a recursive collection. Each element will be sent -descriptionWithOptions: to report every descendant description.

Default value is nil.


kETDescriptionOptionValuesForKeyPaths

NSString* const kETDescriptionOptionValuesForKeyPaths;

An array of key paths to indicate the values -descriptionWithOptions: should report.

Default value is nil.