---

NSWhoseSpecifier Class Reference

Overview

NSWhoseSpecifier specifies every object in a collection (or every element in a container) that matches the condition defined by a single Boolean expression or multiple Boolean expressions connected by logical operators. NSWhoseSpecifier is unique among object specifiers in that its top-level container is typically not the application object but an evaluated object specifier involved in the tested-for condition. An NSWhoseSpecifier object encapsulates a “test” object for defining this condition. A test object is instantiated from a subclass of the abstract NSScriptWhoseTest class, whose one declared method is isTrue. See "Boolean Expressions and Logical Operations" in NSScriptObjectSpecifier and the descriptions in NSComparisonMethods and NSScriptingComparisonMethods for more information.

The set of elements specified by an NSWhoseSpecifier object can be a subset of those that pass the NSWhoseSpecifier object's test. This subset is specified by the various sub-element properties of the NSWhoseSpecifier object . Consider as an example the specifier paragraphs where color of third word is blue. This would be represented by an NSWhoseSpecifier object that uses a test specifier and another object specifier to identify a subset of the objects with the specified property. That is, the specifier’s property is paragraphs; the test specifier is an index specifier with property words and index 3; and the qualifier is a key value qualifier for key color and value [NSColor blueColor]. The test object specifier (word at index 3) is evaluated for each object (paragraph) using that object as the container; the resulting objects (if any) are tested with the qualifier (color blue).

NSWhoseSpecifier is part of Cocoa’s built-in script handling. You don’t normally subclass it.

Tasks

Initializing a Whose Specifier

• – initWithContainerClassDescription:containerSpecifier:key:test:

Accessing Information About a Whose Specifier

• – endSubelementIdentifier
• – endSubelementIndex
• – setEndSubelementIdentifier:
• – setEndSubelementIndex:
• – setStartSubelementIdentifier:
• – setStartSubelementIndex:
• – setTest:
• – startSubelementIdentifier
• – startSubelementIndex
• – test

Instance Methods

endSubelementIdentifier

Returns the end sub-element identifier for the receiver.

- (NSWhoseSubelementIdentifier)endSubelementIdentifier

Return Value

The end sub-element identifier for the receiver, or NSNoSubelement if there is none.

Availability

• Available in Mac OS X v10.0 and later.

Declared In

NSScriptObjectSpecifiers.h

endSubelementIndex

Returns the index position of the last sub-element within the range of objects being tested that passes the receiver's test.

- (NSInteger)endSubelementIndex

Return Value

The index position of the last sub-element within the range of objects being tested that passes the receiver's test.

Availability

• Available in Mac OS X v10.0 and later.

Declared In

NSScriptObjectSpecifiers.h

initWithContainerClassDescription:containerSpecifier:key:test:

Returns an NSWhoseSpecifier object initialized with the given attributes.

- (id)initWithContainerClassDescription:(NSScriptClassDescription *)classDescription containerSpecifier:(NSScriptObjectSpecifier *)specifier key:(NSString *)property test:(NSScriptWhoseTest *)test

Parameters

classDescription

Class description for the receiver's container object.

specifier

An object specifier for the receiver's container object.

property

The key for the property for which to test.

test

The test condition.

Return Value

An NSWhoseSpecifier object initialized with the given attributes.

Discussion

Invokes the super class’s initWithContainerClassDescription:containerSpecifier:key: and sets the whose test condition to test.

Availability

• Available in Mac OS X v10.0 and later.

Declared In

NSScriptObjectSpecifiers.h

setEndSubelementIdentifier:

Sets the end sub-element identifier for the specifier to the value of a given sub-element.

- (void)setEndSubelementIdentifier:(NSWhoseSubelementIdentifier)subelement

Parameters

subelement

The end sub-element for the receiver.

Availability

• Available in Mac OS X v10.0 and later.

Declared In

NSScriptObjectSpecifiers.h

setEndSubelementIndex:

Sets the index position of the last sub-element within the range of objects being tested that pass the specifier’s test.

- (void)setEndSubelementIndex:(NSInteger)index

Parameters

index

The index position of the end sub-element.

Discussion

Used only if the end sub-element identifier is NSIndexSubelement.

Availability

• Available in Mac OS X v10.0 and later.

Declared In

NSScriptObjectSpecifiers.h

setStartSubelementIdentifier:

Sets the start sub-element identifier for the specifier.

- (void)setStartSubelementIdentifier:(NSWhoseSubelementIdentifier)subelement

Parameters

subelement

The start sub-element for the receiver.

Availability

• Available in Mac OS X v10.0 and later.

Declared In

NSScriptObjectSpecifiers.h

setStartSubelementIndex:

Sets the index position of the first sub-element within the range of objects being tested that passes the specifier’s test.

- (void)setStartSubelementIndex:(NSInteger)index

Parameters

index

The index position of the start sub-element.

Discussion

Used only if the start sub-element identifier is NSIndexSubelement.

Availability

• Available in Mac OS X v10.0 and later.

Declared In

NSScriptObjectSpecifiers.h

setTest:

Sets the test object that is encapsulated by the receiver.

- (void)setTest:(NSScriptWhoseTest *)test

Parameters

test

The test object for the receiver.

Availability

• Available in Mac OS X v10.0 and later.

Declared In

NSScriptObjectSpecifiers.h

startSubelementIdentifier

Returns the start sub-element identifier for the receiver.

- (NSWhoseSubelementIdentifier)startSubelementIdentifier

Return Value

The start sub-element identifier for the receiver.

Availability

• Available in Mac OS X v10.0 and later.

Declared In

NSScriptObjectSpecifiers.h

startSubelementIndex

Returns the index position of the first sub-element within the range of objects being tested that pass the receiver's test.

- (NSInteger)startSubelementIndex

Return Value

The index position of the first sub-element within the range of objects being tested that pass the receiver's test.

Availability

• Available in Mac OS X v10.0 and later.

Declared In

NSScriptObjectSpecifiers.h

test

Returns the test object encapsulated by the receiver.

- (NSScriptWhoseTest *)test

Return Value

The test object encapsulated by the receiver.

Availability

• Available in Mac OS X v10.0 and later.

Declared In

NSScriptObjectSpecifiers.h

Constants

NSWhoseSubelementIdentifier

NSWhoseSpecifier uses these constants to specify sub-elements within the collection of objects being tested that pass the specifier’s test.

typedef enum {
   NSIndexSubelement  = 0,
   NSEverySubelement  = 1,
   NSMiddleSubelement = 2,
   NSRandomSubelement = 3,
   NSNoSubelement     = 4
} NSWhoseSubelementIdentifier;

Constants

NSIndexSubelement

An element at a given index that meets the specifier test.

Available in Mac OS X v10.0 and later.

Declared in NSScriptObjectSpecifiers.h.

NSEverySubelement

Every element that meets the specifier test.

Available in Mac OS X v10.0 and later.

Declared in NSScriptObjectSpecifiers.h.

NSMiddleSubelement

The middle element that meets the specifier test.

Available in Mac OS X v10.0 and later.

Declared in NSScriptObjectSpecifiers.h.

NSRandomSubelement

Any element that meets the specifier test.

Available in Mac OS X v10.0 and later.

Declared in NSScriptObjectSpecifiers.h.

NSNoSubelement

No sub-element met the specifier test. Valid only for specifying the end sub-element.; that is, there is no end, so consider all elements.

Available in Mac OS X v10.0 and later.

Declared in NSScriptObjectSpecifiers.h.

Discussion

These constants are used by startSubelementIdentifier, setStartSubelementIdentifier:, endSubelementIdentifier, and setEndSubelementIdentifier:.

Availability

• Available in Mac OS X v10.0 and later.

Declared In

NSScriptObjectSpecifiers.h

---