NSPredicateEditorRowTemplate Class Reference
| Inherits from | |
| Conforms to | |
| Framework | /System/Library/Frameworks/AppKit.framework |
| Availability | Available in OS X v10.5 and later. |
| Declared in | NSPredicateEditorRowTemplate.h |
| Companion guides | |
Overview
NSPredicateEditorRowTemplate describes available predicates and how to display them.
You can create instances of NSPredicateEditorRowTemplate programmatically or in Interface Builder. By default, a non-compound row template has three views: a popup (or static text field) on the left, a popup or static text field for operators, and either a popup or other view on the right. You can subclass NSPredicateEditorRowTemplate to create a row template with different numbers or types of views.
NSPredicateEditorRowTemplate is a concrete class, but it has five primitive methods which are called by NSPredicateEditor: templateViews, matchForPredicate:, setPredicate:, displayableSubpredicatesOfPredicate:, and predicateWithSubpredicates:. NSPredicateEditorRowTemplate implements all of them, but you can override them for custom templates. The primitive methods are used by an instance of NSPredicateEditor as follows.
First, an instance of NSPredicateEditor is created, and some row templates are set on it—either through a nib file or programmatically. The first thing predicate editor does is ask each of the templates for their views, using templateViews.
After setting up the predicate editor, you typically send it a setObjectValue: message to restore a saved predicate. NSPredicateEditor needs to determine which of its templates should display each predicate in the predicate tree. It does this by sending each of its row templates a matchForPredicate: message and choosing the one that returns the highest value.
After finding the best match for a predicate, NSPredicateEditor copies that template to get fresh views, inserts them into the proper row, and then sets the predicate on the template using setPredicate:. Within that method, the NSPredicateEditorRowTemplate object must set its views' values to represent that predicate.
NSPredicateEditorRowTemplate next asks the template for the “displayable sub-predicates” of the predicate by sending a displayableSubpredicatesOfPredicate: message. If a template represents a predicate in its entirety, or if the predicate has no subpredicates, it can return nil for this. Otherwise, it should return a list of predicates to be made into sub-rows of that template's row. The whole process repeats for each sub-predicate.
At this point, the user sees the predicate that was saved. If the user then makes some changes to the views of the templates, this causes NSPredicateEditor to recompute its predicate by asking each of the templates to return the predicate represented by the new view values, passing in the subpredicates represented by the sub-rows (an empty array if there are none, or nil if they aren't supported by that predicate type):
Tasks
Initializing a Template
-
– initWithLeftExpressions:rightExpressions:modifier:operators:options: -
– initWithLeftExpressions:rightExpressionAttributeType:modifier:operators:options: -
– initWithCompoundTypes:
Core Data Integration
Primitive Methods
-
– matchForPredicate: -
– templateViews -
– setPredicate: -
– displayableSubpredicatesOfPredicate: -
– predicateWithSubpredicates:
Information About a Row Template
Class Methods
templatesWithAttributeKeyPaths:inEntityDescription:
Returns an array of predicate templates for the given attribute key paths for a given entity.
Parameters
- keyPaths
An array of attribute key paths originating at entityDescription. The key paths may cross relationships but must terminate in attributes.
- entityDescription
A Core Data entity description.
Return Value
An array of predicate templates for keyPaths originating at entityDescription.
Discussion
This method determines which key paths in the entity description can use the same views (that is, share the same attribute type). For each of these groups, it instantiates individual templates via initWithLeftExpressions:rightExpressions:modifier:operators:options:.
Availability
- Available in OS X v10.5 and later.
Declared In
NSPredicateEditorRowTemplate.hInstance Methods
compoundTypes
Returns the compound predicate types for the receiver.
Return Value
An array of NSNumber objects specifying compound predicate types. See Compound_Predicate_Types for possible values.
Availability
- Available in OS X v10.5 and later.
Declared In
NSPredicateEditorRowTemplate.hdisplayableSubpredicatesOfPredicate:
Returns the subpredicates that should be made sub-rows of a given predicate.
Parameters
- predicate
A predicate object.
Return Value
The subpredicates that should be made sub-rows of predicate. For compound predicates (instances of NSCompoundPredicate), the array of subpredicates; for other types of predicate, returns nil. If a template represents a predicate in its entirety, or if the predicate has no subpredicates, returns nil.
Discussion
You can override this method to create custom templates that handle complicated compound predicates.
Availability
- Available in OS X v10.5 and later.
Declared In
NSPredicateEditorRowTemplate.hinitWithCompoundTypes:
Initializes and returns a row template suitable for displaying compound predicates.
Parameters
- compoundTypes
An array of
NSNumberobjects specifying compound predicate types. SeeCompound_Predicate_Typesfor possible values.
Return Value
A row template initialized for displaying compound predicates of the types specified by compoundTypes.
Discussion
NSPredicateEditor contains such a template by default.
Availability
- Available in OS X v10.5 and later.
Declared In
NSPredicateEditorRowTemplate.hinitWithLeftExpressions:rightExpressionAttributeType:modifier:operators:options:
Initializes and returns a “pop-up-pop-up-view”-style row template.
Parameters
- leftExpressions
An array of
NSExpressionobjects that represent the left hand side of a predicate.- attributeType
An attribute type for the right hand side of a predicate. This value dictates the type of view created, and how the control’s object value is coerced before putting it into a predicate.
- modifier
A modifier for the predicate (see
NSComparisonPredicateModifierfor possible values).- operators
An array of
NSNumberobjects specifying the operator type (seeNSPredicateOperatorTypefor possible values).- options
Options for the predicate (see
NSComparisonPredicate_Optionsfor possible values).
Return Value
A row template initialized using the given arguments.
Discussion
The type of attributeType dictates the type of view created. For example, NSDateAttributeType will create an NSDatePicker object, NSInteger64AttributeType will create a short text field, and NSStringAttributeType will produce a longer text field. You can resize the views as you want.
Predicates do not automatically coerce types for you. For example, comparing a number to a string will raise an exception. Therefore, the attribute type is also needed to determine how the control's object value must be coerced before putting it into a predicate.
Availability
- Available in OS X v10.5 and later.
Declared In
NSPredicateEditorRowTemplate.hinitWithLeftExpressions:rightExpressions:modifier:operators:options:
Initializes and returns a “pop-up-pop-up-pop-up”-style row template.
Parameters
- leftExpressions
An array of
NSExpressionobjects that represent the left hand side of a predicate.- rightExpressions
An array of
NSExpressionobjects that represent the right hand side of a predicate.- modifier
A modifier for the predicate (see
NSComparisonPredicateModifierfor possible values).- operators
An array of
NSNumberobjects specifying the operator type (seeNSPredicateOperatorTypefor possible values).- options
Options for the predicate (see
NSComparisonPredicate_Optionsfor possible values).
Return Value
A row template of the “pop-up-pop-up-pop-up”-form, with the left and right popups representing the left and right expression arrays leftExpressions and rightExpressions, and the center popup representing the operators.
Availability
- Available in OS X v10.5 and later.
Declared In
NSPredicateEditorRowTemplate.hleftExpressions
Returns the left hand expressions for the receiver.
Return Value
The left hand expressions for the receiver
Availability
- Available in OS X v10.5 and later.
Declared In
NSPredicateEditorRowTemplate.hmatchForPredicate:
Returns a positive number if the receiver can represent a given predicate, and 0 if it cannot.
Return Value
A positive number if the template can represent predicate, and 0 if it cannot.
Discussion
By default, returns values in the range 0 to 1.
The highest match among all the templates determines which template is responsible for displaying the predicate. You can override this to determine which predicates your custom template handles.
Availability
- Available in OS X v10.5 and later.
Declared In
NSPredicateEditorRowTemplate.hmodifier
Returns the comparison predicate modifier for the receiver.
Return Value
The comparison predicate modifier for the receiver.
Availability
- Available in OS X v10.5 and later.
Declared In
NSPredicateEditorRowTemplate.hoperators
Returns the array of operators for the receiver.
Return Value
The array of operators for the receiver.
Availability
- Available in OS X v10.5 and later.
Declared In
NSPredicateEditorRowTemplate.hoptions
Returns the comparison predicate options for the receiver.
Return Value
The comparison predicate options for the receiver. See NSComparisonPredicate_Options for possible values. Returns 0 if this does not apply (for example, for a compound template initialized with initWithCompoundTypes:).
Availability
- Available in OS X v10.5 and later.
Declared In
NSPredicateEditorRowTemplate.hpredicateWithSubpredicates:
Returns the predicate represented by the receiver’s views' values and the given sub-predicates.
Parameters
- subpredicates
An array of predicates.
Return Value
The predicate represented by the values of the template's views and the given subpredicates. You can override this method to return the predicate represented by your custom views.
Discussion
This method is only called if matchForPredicate: returned a positive value for the receiver.
You can override this method to return the predicate represented by a custom view.
Availability
- Available in OS X v10.5 and later.
Declared In
NSPredicateEditorRowTemplate.hrightExpressionAttributeType
Returns the attribute type of the receiver’s right expression.
Return Value
The attribute type of the receiver’s right expression.
Availability
- Available in OS X v10.5 and later.
Declared In
NSPredicateEditorRowTemplate.hrightExpressions
Returns the right hand expressions for the receiver.
Return Value
The right hand expressions for the receiver
Availability
- Available in OS X v10.5 and later.
Declared In
NSPredicateEditorRowTemplate.hsetPredicate:
Sets the value of the views according to the given predicate.
Parameters
- predicate
The predicate value for the receiver.
Discussion
This method is only called if matchForPredicate: returned a positive value for the receiver.
You can override this to set the values of custom views.
Availability
- Available in OS X v10.5 and later.
Declared In
NSPredicateEditorRowTemplate.htemplateViews
Returns the views for the receiver.
Return Value
The views for the receiver.
Discussion
Instances of NSPopUpButton are treated specially by NSPredicateEditor; their menu items are merged into a single popup button, and matching menu item titles are combined. In this way, a single tree is built from the separate templates.
Availability
- Available in OS X v10.5 and later.
Declared In
NSPredicateEditorRowTemplate.h© 2007 Apple Inc. All Rights Reserved. (Last updated: 2007-01-12)