Mac Developer Library

Developer

AppKit Framework Reference NSPredicateEditorRowTemplate Class Reference

Options
Deployment Target:

On This Page
Language:

NSPredicateEditorRowTemplate

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):

predicateWithSubpredicates:

Inheritance


Conforms To


Import Statement


Swift

import AppKit

Objective-C

@import AppKit;

Availability


Available in OS X v10.5 and later.
  • Initializes and returns a “pop-up-pop-up-pop-up”-style row template.

    Declaration

    Swift

    init!(leftExpressions leftExpressions: [AnyObject]!, rightExpressions rightExpressions: [AnyObject]!, modifier modifier: NSComparisonPredicateModifier, operators operators: [AnyObject]!, options options: Int)

    Objective-C

    - (instancetype)initWithLeftExpressions:(NSArray *)leftExpressions rightExpressions:(NSArray *)rightExpressions modifier:(NSComparisonPredicateModifier)modifier operators:(NSArray *)operators options:(NSUInteger)options

    Parameters

    leftExpressions

    An array of NSExpression objects that represent the left hand side of a predicate.

    rightExpressions

    An array of NSExpression objects that represent the right hand side of a predicate.

    modifier

    A modifier for the predicate (see NSComparisonPredicateModifier for possible values).

    operators

    An array of NSNumber objects specifying the operator type (see NSPredicateOperatorType for possible values).

    options

    Options for the predicate (see NSComparisonPredicate_Options for 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.

    Import Statement

    Objective-C

    @import AppKit;

    Swift

    import AppKit

    Availability

    Available in OS X v10.5 and later.

  • Initializes and returns a “pop-up-pop-up-view”-style row template.

    Declaration

    Swift

    init!(leftExpressions leftExpressions: [AnyObject]!, rightExpressionAttributeType attributeType: NSAttributeType, modifier modifier: NSComparisonPredicateModifier, operators operators: [AnyObject]!, options options: Int)

    Objective-C

    - (instancetype)initWithLeftExpressions:(NSArray *)leftExpressions rightExpressionAttributeType:(NSAttributeType)attributeType modifier:(NSComparisonPredicateModifier)modifier operators:(NSArray *)operators options:(NSUInteger)options

    Parameters

    leftExpressions

    An array of NSExpression objects 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 NSComparisonPredicateModifier for possible values).

    operators

    An array of NSNumber objects specifying the operator type (see NSPredicateOperatorType for possible values).

    options

    Options for the predicate (see NSComparisonPredicate_Options for 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.

    Import Statement

    Objective-C

    @import AppKit;

    Swift

    import AppKit

    Availability

    Available in OS X v10.5 and later.

  • Initializes and returns a row template suitable for displaying compound predicates.

    Declaration

    Swift

    init!(compoundTypes compoundTypes: [AnyObject]!)

    Objective-C

    - (instancetype)initWithCompoundTypes:(NSArray *)compoundTypes

    Parameters

    compoundTypes

    An array of NSNumber objects specifying compound predicate types. See Compound_Predicate_Types for 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.

    Import Statement

    Objective-C

    @import AppKit;

    Swift

    import AppKit

    Availability

    Available in OS X v10.5 and later.

  • Returns an array of predicate templates for the given attribute key paths for a given entity.

    Declaration

    Swift

    class func templatesWithAttributeKeyPaths(_ keyPaths: [AnyObject]!, inEntityDescription entityDescription: NSEntityDescription!) -> [AnyObject]!

    Objective-C

    + (NSArray *)templatesWithAttributeKeyPaths:(NSArray *)keyPaths inEntityDescription:(NSEntityDescription *)entityDescription

    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:.

    Import Statement

    Objective-C

    @import AppKit;

    Swift

    import AppKit

    Availability

    Available in OS X v10.5 and later.

  • Returns a positive number if the receiver can represent a given predicate, and 0 if it cannot.

    Declaration

    Swift

    func matchForPredicate(_ predicate: NSPredicate!) -> Double

    Objective-C

    - (double)matchForPredicate:(NSPredicate *)predicate

    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.

    Import Statement

    Objective-C

    @import AppKit;

    Swift

    import AppKit

    Availability

    Available in OS X v10.5 and later.

  • Returns the views for the receiver.

    Declaration

    Swift

    var templateViews: [AnyObject]! { get }

    Objective-C

    @property(readonly, copy) NSArray *templateViews

    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.

    Import Statement

    Objective-C

    @import AppKit;

    Swift

    import AppKit

    Availability

    Available in OS X v10.5 and later.

  • Sets the value of the views according to the given predicate.

    Declaration

    Swift

    func setPredicate(_ predicate: NSPredicate!)

    Objective-C

    - (void)setPredicate:(NSPredicate *)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.

    Import Statement

    Objective-C

    @import AppKit;

    Swift

    import AppKit

    Availability

    Available in OS X v10.5 and later.

  • Returns the subpredicates that should be made sub-rows of a given predicate.

    Declaration

    Swift

    func displayableSubpredicatesOfPredicate(_ predicate: NSPredicate!) -> [AnyObject]?

    Objective-C

    - (NSArray *)displayableSubpredicatesOfPredicate:(NSPredicate *)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.

    Import Statement

    Objective-C

    @import AppKit;

    Swift

    import AppKit

    Availability

    Available in OS X v10.5 and later.

  • Returns the predicate represented by the receiver’s views' values and the given sub-predicates.

    Declaration

    Swift

    func predicateWithSubpredicates(_ subpredicates: [AnyObject]!) -> NSPredicate!

    Objective-C

    - (NSPredicate *)predicateWithSubpredicates:(NSArray *)subpredicates

    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.

    Import Statement

    Objective-C

    @import AppKit;

    Swift

    import AppKit

    Availability

    Available in OS X v10.5 and later.

  • Returns the left hand expressions for the receiver.

    Declaration

    Swift

    var leftExpressions: [AnyObject]! { get }

    Objective-C

    @property(readonly, copy) NSArray *leftExpressions

    Return Value

    The left hand expressions for the receiver

    Import Statement

    Objective-C

    @import AppKit;

    Swift

    import AppKit

    Availability

    Available in OS X v10.5 and later.

  • Returns the right hand expressions for the receiver.

    Declaration

    Swift

    var rightExpressions: [AnyObject]! { get }

    Objective-C

    @property(readonly, copy) NSArray *rightExpressions

    Return Value

    The right hand expressions for the receiver

    Import Statement

    Objective-C

    @import AppKit;

    Swift

    import AppKit

    Availability

    Available in OS X v10.5 and later.

  • Returns the compound predicate types for the receiver.

    Declaration

    Swift

    var compoundTypes: [AnyObject]! { get }

    Objective-C

    @property(readonly, copy) NSArray *compoundTypes

    Return Value

    An array of NSNumber objects specifying compound predicate types. See Compound_Predicate_Types for possible values.

    Import Statement

    Objective-C

    @import AppKit;

    Swift

    import AppKit

    Availability

    Available in OS X v10.5 and later.

  • Returns the comparison predicate modifier for the receiver.

    Declaration

    Swift

    var modifier: NSComparisonPredicateModifier { get }

    Objective-C

    @property(readonly) NSComparisonPredicateModifier modifier

    Return Value

    The comparison predicate modifier for the receiver.

    Import Statement

    Objective-C

    @import AppKit;

    Swift

    import AppKit

    Availability

    Available in OS X v10.5 and later.

  • Returns the array of operators for the receiver.

    Declaration

    Swift

    var operators: [AnyObject]! { get }

    Objective-C

    @property(readonly, copy) NSArray *operators

    Return Value

    The array of operators for the receiver.

    Import Statement

    Objective-C

    @import AppKit;

    Swift

    import AppKit

    Availability

    Available in OS X v10.5 and later.

  • Returns the comparison predicate options for the receiver.

    Declaration

    Swift

    var options: Int { get }

    Objective-C

    @property(readonly) NSUInteger options

    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:).

    Import Statement

    Objective-C

    @import AppKit;

    Swift

    import AppKit

    Availability

    Available in OS X v10.5 and later.

  • Returns the attribute type of the receiver’s right expression.

    Declaration

    Swift

    var rightExpressionAttributeType: NSAttributeType { get }

    Objective-C

    @property(readonly) NSAttributeType rightExpressionAttributeType

    Return Value

    The attribute type of the receiver’s right expression.

    Import Statement

    Objective-C

    @import AppKit;

    Swift

    import AppKit

    Availability

    Available in OS X v10.5 and later.