Mac Developer Library

Developer

AppKit Framework Reference NSRuleEditor Class Reference

Options
Deployment Target:

On This Page
Language:

NSRuleEditor

Import Statement


Swift

import AppKit

Objective-C

@import AppKit;

Availability


Available in OS X v10.5 and later.

An NSRuleEditor object is a view that allows the user to visually create and configure a list of options which are expressed by the rule editor as a predicate (see Predicate Programming Guide). The view has a delegate which offers a tree of choices to the view. The choices are presented by the view to the user as a row of popup buttons, static text fields, and custom views. Each row in the list represents a particular path down the tree of choices.

NSRuleEditor exposes one binding, rows. You can bind rows to an ordered collection (such as an instance of NSMutableArray). Each object in the collection should have the following properties:

@"rowType"

An integer representing the type of the row (NSRuleEditorRowType).

@"subrows"

An ordered to-many relation (such as an instance of NSMutableArray) containing the directly nested subrows for the given row.

@"displayValues"

An ordered to-many relation containing the display values for the row.

@"criteria"

An ordered to-many relation containing the criteria for the row.

  • delegate delegate Property

    The rule editor’s delegate.

    Declaration

    Swift

    unowned(unsafe) var delegate: NSRuleEditorDelegate?

    Objective-C

    @property(assign) id< NSRuleEditorDelegate > delegate

    Import Statement

    Objective-C

    @import AppKit;

    Swift

    import AppKit

    Availability

    Available in OS X v10.5 and later.

  • editable editable Property

    A Boolean value that determines whether the rule editor is editable.

    Declaration

    Swift

    var editable: Bool

    Objective-C

    @property(getter=isEditable) BOOL editable

    Discussion

    The default is YEStrue.

    Import Statement

    Objective-C

    @import AppKit;

    Swift

    import AppKit

    Availability

    Available in OS X v10.10 and later.

  • The rule editor’s nesting mode.

    Declaration

    Swift

    var nestingMode: NSRuleEditorNestingMode

    Objective-C

    @property NSRuleEditorNestingMode nestingMode

    Discussion

    You typically set the nesting mode at view creation time and do not subsequently modify it. The default is NSRuleEditorNestingModeCompound. For a list of valid modes, see Nesting Modes.

    Import Statement

    Objective-C

    @import AppKit;

    Swift

    import AppKit

    Availability

    Available in OS X v10.5 and later.

  • A Boolean value that indicates whether all the rows can be removed.

    Declaration

    Swift

    var canRemoveAllRows: Bool

    Objective-C

    @property BOOL canRemoveAllRows

    Import Statement

    Objective-C

    @import AppKit;

    Swift

    import AppKit

    Availability

    Available in OS X v10.5 and later.

  • rowHeight rowHeight Property

    The rule editor’s row height.

    Declaration

    Swift

    var rowHeight: CGFloat

    Objective-C

    @property CGFloat rowHeight

    Import Statement

    Objective-C

    @import AppKit;

    Swift

    import AppKit

    Availability

    Available in OS X v10.5 and later.

  • The formatting dictionary for the rule editor.

    Declaration

    Swift

    var formattingDictionary: [NSObject : AnyObject]?

    Objective-C

    @property(copy) NSDictionary *formattingDictionary

    Discussion

    If you assign a new the formatting dictionary to this property, it sets the current to formatting strings file name to nil.

    Import Statement

    Objective-C

    @import AppKit;

    Swift

    import AppKit

    Availability

    Available in OS X v10.5 and later.

  • The name of the rule editor’s strings file.

    Declaration

    Swift

    var formattingStringsFilename: String?

    Objective-C

    @property(copy) NSString *formattingStringsFilename

    Discussion

    The NSRuleEditor class looks for a strings file with the given name in the main bundle and (if appropriate) the bundle containing the nib file from which it was loaded. If it finds a strings file resource with the given name, NSRuleEditor loads it and sets it as the formatting dictionary for the receiver. You can obtain the resulting dictionary using the formattingDictionary property].

    If you assign a new dictionary to the formattingDictionary property, it sets the current to formatting strings file name to nil.

    Import Statement

    Objective-C

    @import AppKit;

    Swift

    import AppKit

    Availability

    Available in OS X v10.5 and later.

  • Instructs the receiver to refetch criteria from its delegate.

    Declaration

    Swift

    func reloadCriteria()

    Objective-C

    - (void)reloadCriteria

    Discussion

    You can use this method to indicate that the available criteria may have changed and should be refetched from the delegate and the popups recalculated. If any item in a given row is “orphaned” (that is, is no longer reported as a child of its previous parent), its criteria and display values are set to valid choices.

    Import Statement

    Objective-C

    @import AppKit;

    Swift

    import AppKit

    Availability

    Available in OS X v10.5 and later.

  • Modifies the row at a given index to contain the given items and values.

    Declaration

    Swift

    func setCriteria(_ criteria: [AnyObject], andDisplayValues values: [AnyObject], forRowAtIndex rowIndex: Int)

    Objective-C

    - (void)setCriteria:(NSArray *)criteria andDisplayValues:(NSArray *)values forRowAtIndex:(NSInteger)rowIndex

    Parameters

    criteria

    The array of criteria for the row at rowIndex. Pass an empty array to force the receiver to query its delegate. This value must not be nil.

    values

    The array of values for the row at rowIndex. Pass an empty array to force the receiver to query its delegate. This value must not be nil.

    rowIndex

    The index of a row in the receiver.

    Discussion

    It is your responsibility to ensure that each item in the array is a child of the previous item, and that the first item is a root item for the row type. If the last item has child items, then the items array will be extended by querying the delegate for child items until a childless item is reached. If values contains fewer objects than the (possibly extended) criteria array, then the delegate is queried to construct the remaining display values. If you want the delegate to be queried for all the criteria or all the display values, pass empty arrays; do not pass nil.

    Import Statement

    Objective-C

    @import AppKit;

    Swift

    import AppKit

    Availability

    Available in OS X v10.5 and later.

  • Returns the currently chosen items for a given row.

    Declaration

    Swift

    func criteriaForRow(_ row: Int) -> [AnyObject]

    Objective-C

    - (NSArray *)criteriaForRow:(NSInteger)row

    Parameters

    row

    The index of a row in the receiver.

    Return Value

    The currently chosen items for row row.

    Discussion

    The items returned are the same as those returned by calling the delegate’s ruleEditor:child:forCriterion:withRowType: method once for each item in the row.

    Import Statement

    Objective-C

    @import AppKit;

    Swift

    import AppKit

    Availability

    Available in OS X v10.5 and later.

  • Returns the chosen values for a given row.

    Declaration

    Swift

    func displayValuesForRow(_ row: Int) -> [AnyObject]

    Objective-C

    - (NSArray *)displayValuesForRow:(NSInteger)row

    Parameters

    row

    The index of a row in the receiver.

    Return Value

    The chosen values (strings, views, or menu items) for row row.

    Discussion

    The values returned are the same as those returned from the delegate’s ruleEditor:displayValueForCriterion:inRow: method.

    Import Statement

    Objective-C

    @import AppKit;

    Swift

    import AppKit

    Availability

    Available in OS X v10.5 and later.

  • The number of rows in the rule editor. (read-only)

    Declaration

    Swift

    var numberOfRows: Int { get }

    Objective-C

    @property(readonly) NSInteger numberOfRows

    Import Statement

    Objective-C

    @import AppKit;

    Swift

    import AppKit

    Availability

    Available in OS X v10.5 and later.

  • Returns the index of the parent of a given row.

    Declaration

    Swift

    func parentRowForRow(_ rowIndex: Int) -> Int

    Objective-C

    - (NSInteger)parentRowForRow:(NSInteger)rowIndex

    Parameters

    rowIndex

    The index of a row in the receiver.

    Return Value

    The index of the parent of the row at rowIndex. If the row at rowIndex is a root row, returns -1.

    Import Statement

    Objective-C

    @import AppKit;

    Swift

    import AppKit

    Availability

    Available in OS X v10.5 and later.

  • Returns the index of the row containing a given value.

    Declaration

    Swift

    func rowForDisplayValue(_ displayValue: AnyObject) -> Int

    Objective-C

    - (NSInteger)rowForDisplayValue:(id)displayValue

    Parameters

    displayValue

    The display value (string, view, or menu item) of an item in the receiver. This value must not be nil.

    Return Value

    The index of the row containing displayValue, or NSNotFound.

    Discussion

    This method searches each row via pointer equality for the given display value, which may be present as an alternative in a popup menu for that row.

    Import Statement

    Objective-C

    @import AppKit;

    Swift

    import AppKit

    Availability

    Available in OS X v10.5 and later.

  • Returns the type of a given row.

    Declaration

    Swift

    func rowTypeForRow(_ rowIndex: Int) -> NSRuleEditorRowType

    Objective-C

    - (NSRuleEditorRowType)rowTypeForRow:(NSInteger)rowIndex

    Parameters

    rowIndex

    The index of a row in the receiver.

    Return Value

    The type of the row at rowIndex.

    Import Statement

    Objective-C

    @import AppKit;

    Swift

    import AppKit

    Availability

    Available in OS X v10.5 and later.

  • Returns the immediate subrows of a given row.

    Declaration

    Swift

    func subrowIndexesForRow(_ rowIndex: Int) -> NSIndexSet

    Objective-C

    - (NSIndexSet *)subrowIndexesForRow:(NSInteger)rowIndex

    Parameters

    rowIndex

    The index of a row in the receiver, or -1 to get the top-level rows.

    Return Value

    The immediate subrows of the row at rowIndex.

    Discussion

    Rows are numbered starting at 0.

    Import Statement

    Objective-C

    @import AppKit;

    Swift

    import AppKit

    Availability

    Available in OS X v10.5 and later.

  • The indexes of the rule editor’s selected rows. (read-only)

    Declaration

    Swift

    @NSCopying var selectedRowIndexes: NSIndexSet { get }

    Objective-C

    @property(readonly, copy) NSIndexSet *selectedRowIndexes

    Import Statement

    Objective-C

    @import AppKit;

    Swift

    import AppKit

    Availability

    Available in OS X v10.5 and later.

  • Sets in the receiver the indexes of rows that are selected.

    Declaration

    Swift

    func selectRowIndexes(_ indexes: NSIndexSet, byExtendingSelection extend: Bool)

    Objective-C

    - (void)selectRowIndexes:(NSIndexSet *)indexes byExtendingSelection:(BOOL)extend

    Parameters

    indexes

    The indexes of rows in the receiver to select.

    extend

    If NOfalse, the selected rows are specified by indexes. If YEStrue, the rows indicated by indexes are added to the collection of already selected rows, providing multiple selection.

    Import Statement

    Objective-C

    @import AppKit;

    Swift

    import AppKit

    Availability

    Available in OS X v10.5 and later.

  • Adds a row to the receiver.

    Declaration

    Swift

    func addRow(_ sender: AnyObject?)

    Objective-C

    - (void)addRow:(id)sender

    Parameters

    sender

    Typically the object that sent the message.

    Import Statement

    Objective-C

    @import AppKit;

    Swift

    import AppKit

    Availability

    Available in OS X v10.5 and later.

  • Adds a new row of a given type at a given location.

    Declaration

    Swift

    func insertRowAtIndex(_ rowIndex: Int, withType rowType: NSRuleEditorRowType, asSubrowOfRow parentRow: Int, animate shouldAnimate: Bool)

    Objective-C

    - (void)insertRowAtIndex:(NSInteger)rowIndex withType:(NSRuleEditorRowType)rowType asSubrowOfRow:(NSInteger)parentRow animate:(BOOL)shouldAnimate

    Parameters

    rowIndex

    The index at which the new row should be inserted. rowIndex must be greater than parentRow, and much specify a row that does not fall amongst the children of some other parent.

    rowType

    The type of the new row.

    parentRow

    The index of the row of which the new row is a child. Pass -1 to indicate that the new row should be a root row.

    shouldAnimate

    YEStrue if creation of the new row should be animated, otherwise NOfalse.

    Special Considerations

    Import Statement

    Objective-C

    @import AppKit;

    Swift

    import AppKit

    Availability

    Available in OS X v10.5 and later.

  • Removes the row at a given index.

    Declaration

    Swift

    func removeRowAtIndex(_ rowIndex: Int)

    Objective-C

    - (void)removeRowAtIndex:(NSInteger)rowIndex

    Parameters

    rowIndex

    The index of a row in the receiver.

    Discussion

    Any subrows of the deleted row are adopted by the parent of the deleted row, or are made root rows.

    Import Statement

    Objective-C

    @import AppKit;

    Swift

    import AppKit

    Availability

    Available in OS X v10.5 and later.

  • Removes the rows at given indexes.

    Declaration

    Swift

    func removeRowsAtIndexes(_ rowIndexes: NSIndexSet, includeSubrows includeSubrows: Bool)

    Objective-C

    - (void)removeRowsAtIndexes:(NSIndexSet *)rowIndexes includeSubrows:(BOOL)includeSubrows

    Parameters

    rowIndexes

    Indexes of one or more rows in the receiver.

    includeSubrows

    If YEStrue, then sub-rows of deleted rows are also deleted; if NOfalse, then each sub-row is adopted by its first non-deleted ancestor, or becomes a root row.

    Import Statement

    Objective-C

    @import AppKit;

    Swift

    import AppKit

    Availability

    Available in OS X v10.5 and later.

  • predicate predicate Property

    The rule editor’s predicate. (read-only)

    Declaration

    Swift

    var predicate: NSPredicate? { get }

    Objective-C

    @property(readonly, strong) NSPredicate *predicate

    Discussion

    If the delegate implements NSRuleEditor, this property contains the rule editor’s predicate. If the delegate does not implement NSRuleEditor, or if the delegate does not return enough parts to construct a full predicate, this property contains nil.

    Import Statement

    Objective-C

    @import AppKit;

    Swift

    import AppKit

    Availability

    Available in OS X v10.5 and later.

  • Instructs the receiver to regenerate its predicate by invoking the corresponding delegate method.

    Declaration

    Swift

    func reloadPredicate()

    Objective-C

    - (void)reloadPredicate

    Discussion

    You typically invoke this method because something has changed (for example, a view's value).

    Import Statement

    Objective-C

    @import AppKit;

    Swift

    import AppKit

    Availability

    Available in OS X v10.5 and later.

  • Returns the predicate for a given row.

    Declaration

    Swift

    func predicateForRow(_ row: Int) -> NSPredicate?

    Objective-C

    - (NSPredicate *)predicateForRow:(NSInteger)row

    Parameters

    row

    The index of a row in the receiver.

    Return Value

    The predicate for the row at row.

    Discussion

    You should rarely have a need to call this directly, but you can override this method in a subclass to perform specialized predicate handling for certain criteria or display values.

    Import Statement

    Objective-C

    @import AppKit;

    Swift

    import AppKit

    Availability

    Available in OS X v10.5 and later.

  • rowClass rowClass Property

    The class used to create a new row in the “rows” binding.

    Declaration

    Swift

    var rowClass: AnyClass

    Objective-C

    @property(assign) Class rowClass

    Discussion

    The default is NSMutableDictionary.

    Import Statement

    Objective-C

    @import AppKit;

    Swift

    import AppKit

    Availability

    Available in OS X v10.5 and later.

  • The key path for the row type.

    Declaration

    Swift

    var rowTypeKeyPath: String

    Objective-C

    @property(copy) NSString *rowTypeKeyPath

    Discussion

    The key path is used to get the row type in the “rows” binding. The corresponding property should be a number that specifies an NSRuleEditorRowType value (see “Row Types”).

    The default value is @"rowType".

    Import Statement

    Objective-C

    @import AppKit;

    Swift

    import AppKit

    Availability

    Available in OS X v10.5 and later.

  • The key path for the subrows.

    Declaration

    Swift

    var subrowsKeyPath: String

    Objective-C

    @property(copy) NSString *subrowsKeyPath

    Discussion

    The key path is used to get the nested rows in the “rows” binding. The corresponding property should be an ordered to-many relationship containing additional bound row objects.

    The default value is @"subrows".

    Import Statement

    Objective-C

    @import AppKit;

    Swift

    import AppKit

    Availability

    Available in OS X v10.5 and later.

  • The criteria key path.

    Declaration

    Swift

    var criteriaKeyPath: String

    Objective-C

    @property(copy) NSString *criteriaKeyPath

    Discussion

    The key path is used to get the criteria for a row in the "rows" binding. The criteria objects are the objects returned by calling the delegate’s ruleEditor:child:forCriterion:withRowType: method once for every child in the specified row. The corresponding property is an ordered to-many relationship.

    The default value is @"criteria".

    Import Statement

    Objective-C

    @import AppKit;

    Swift

    import AppKit

    Availability

    Available in OS X v10.5 and later.

  • The display values key path.

    Declaration

    Swift

    var displayValuesKeyPath: String

    Objective-C

    @property(copy) NSString *displayValuesKeyPath

    Discussion

    The key path is used to get the display values for a row in the "rows" binding. The display values are the objects returned by calling the delegate’s ruleEditor:displayValueForCriterion:inRow: method for the specified row. The corresponding property is an ordered to-many relationship.

    The default is @"displayValues".

    Import Statement

    Objective-C

    @import AppKit;

    Swift

    import AppKit

    Availability

    Available in OS X v10.5 and later.

  • Overrides the NSView implementation.

    Declaration

    Objective-C

    - (void)viewDidMoveToWindow

    Special Considerations

    If you override this method in a subclass, you must invoke super’s implementation.

Data Types

  • Specifies a type for nesting modes.

    Declaration

    Swift

    enum NSRuleEditorNestingMode : UInt { case Single case List case Compound case Simple }

    Objective-C

    typedef NSUInteger NSRuleEditorNestingMode;

    Discussion

    See Nesting Modes for possible values.

    Import Statement

    Objective-C

    @import AppKit;

    Swift

    import AppKit

    Availability

    Available in OS X v10.5 and later.

  • Specifies a type for row types.

    Declaration

    Swift

    enum NSRuleEditorRowType : UInt { case Simple case Compound }

    Objective-C

    typedef NSUInteger NSRuleEditorRowType;

    Discussion

    See Row Types for possible values.

    Import Statement

    Objective-C

    @import AppKit;

    Swift

    import AppKit

    Availability

    Available in OS X v10.5 and later.

  • These constants specify the nesting mode for the rule editor.

    Declaration

    Swift

    enum NSRuleEditorNestingMode : UInt { case Single case List case Compound case Simple }

    Objective-C

    enum { NSRuleEditorNestingModeSingle, NSRuleEditorNestingModeList, NSRuleEditorNestingModeCompound, NSRuleEditorNestingModeSimple };

    Constants

    • Single

      NSRuleEditorNestingModeSingle

      Only a single row is allowed.

      Plus/minus buttons are not shown.

      Available in OS X v10.5 and later.

    • List

      NSRuleEditorNestingModeList

      Allows a single list, with no nesting and no compound rows.

      Available in OS X v10.5 and later.

    • Compound

      NSRuleEditorNestingModeCompound

      Unlimited nesting and compound rows.

      This is the default.

      Available in OS X v10.5 and later.

    • Simple

      NSRuleEditorNestingModeSimple

      One compound row at the top with subrows beneath it, and no further nesting allowed.

      Available in OS X v10.5 and later.

  • Specify the type of a rule editor row.

    Declaration

    Swift

    enum NSRuleEditorRowType : UInt { case Simple case Compound }

    Objective-C

    enum { NSRuleEditorRowTypeSimple, NSRuleEditorRowTypeCompound };

    Constants

    • Simple

      NSRuleEditorRowTypeSimple

      Specifies a simple row.

      Available in OS X v10.5 and later.

    • Compound

      NSRuleEditorRowTypeCompound

      Specifies a compound row.

      Available in OS X v10.5 and later.

  • These strings are used as keys to the dictionary returned from the delegate’s ruleEditor:predicatePartsForCriterion:withDisplayValue:inRow: optional method. To construct a valid predicate, the union of the dictionaries for each item in the row must contain the required parts.

    Declaration

    Swift

    let NSRuleEditorPredicateLeftExpression: String let NSRuleEditorPredicateRightExpression: String let NSRuleEditorPredicateComparisonModifier: String let NSRuleEditorPredicateOptions: String let NSRuleEditorPredicateOperatorType: String let NSRuleEditorPredicateCustomSelector: String let NSRuleEditorPredicateCompoundType: String

    Objective-C

    APPKIT_EXTERN NSString * const NSRuleEditorPredicateLeftExpression; APPKIT_EXTERN NSString * const NSRuleEditorPredicateRightExpression; APPKIT_EXTERN NSString * const NSRuleEditorPredicateComparisonModifier; APPKIT_EXTERN NSString * const NSRuleEditorPredicateOptions; APPKIT_EXTERN NSString * const NSRuleEditorPredicateOperatorType; APPKIT_EXTERN NSString * const NSRuleEditorPredicateCustomSelector; APPKIT_EXTERN NSString * const NSRuleEditorPredicateCompoundType;

    Constants

    • NSRuleEditorPredicateLeftExpression

      NSRuleEditorPredicateLeftExpression

      The corresponding value is an NSExpression object representing the left expression in the predicate.

      This value is required for a non-nil comparison predicate.

      Available in OS X v10.5 and later.

    • NSRuleEditorPredicateRightExpression

      NSRuleEditorPredicateRightExpression

      The corresponding value is an NSExpression object representing the right expression in the predicate.

      This value is required for a non-nil comparison predicate.

      Available in OS X v10.5 and later.

    • NSRuleEditorPredicateComparisonModifier

      NSRuleEditorPredicateComparisonModifier

      The corresponding value is an NSNumber object representing a NSComparisonPredicateModifier constant the of the predicate.

      This value is optional—if not specified, NSDirectPredicateModifier is assumed.

      Available in OS X v10.5 and later.

    • NSRuleEditorPredicateOptions

      NSRuleEditorPredicateOptions

      The corresponding value is an NSNumber object representing a NSComparisonPredicate_Optionsbitfield.

      If no value is specified, 0 (no options) is assumed.

      Available in OS X v10.5 and later.

    • NSRuleEditorPredicateOperatorType

      NSRuleEditorPredicateOperatorType

      The corresponding value is an NSNumber object representing a NSPredicateOperatorType constant.

      This value is required for a non-nil comparison predicate.

      Available in OS X v10.5 and later.

    • NSRuleEditorPredicateCustomSelector

      NSRuleEditorPredicateCustomSelector

      The corresponding value is an NSString object representing a custom selector.

      If specified, this overrides the operator type, options, and comparison modifier.

      Available in OS X v10.5 and later.

    • NSRuleEditorPredicateCompoundType

      NSRuleEditorPredicateCompoundType

      The corresponding value is an NSNumber object representing a Compound Predicate Types constant.

      If specified, the other keys are ignored and the predicate for the row will be an NSCompoundPredicate predicate whose subpredicates are the predicates of the subrows of the given row.

      Available in OS X v10.5 and later.