Inherits from | |
Conforms to | |
Framework | /System/Library/Frameworks/AppKit.framework |
Availability | Available in Mac OS X v10.5 and later. |
Declared in | NSRuleEditor.h |
Companion guides |
An NSRuleEditor
object is a view that allows the user to create and configure a list of options. 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:
An integer representing the type of the row (NSRuleEditorRowType
).
An ordered to-many relation (such as an instance of NSMutableArray
) containing the directly nested subrows for the given row.
An ordered to-many relation containing the display values for the row.
An ordered to-many relation containing the criteria for the row.
– delegate
– setDelegate:
– isEditable
– setEditable:
– nestingMode
– setNestingMode:
– canRemoveAllRows
– setCanRemoveAllRows:
– rowHeight
– setRowHeight:
– formattingDictionary
– setFormattingDictionary:
– formattingStringsFilename
– setFormattingStringsFilename:
– reloadCriteria
– setCriteria:andDisplayValues:forRowAtIndex:
– criteriaForRow:
– ruleEditor:child:forCriterion:withRowType:
delegate method
– displayValuesForRow:
– ruleEditor:displayValueForCriterion:inRow:
delegate method
– ruleEditor:numberOfChildrenForCriterion:withRowType:
delegate method
– ruleEditor:predicatePartsForCriterion:withDisplayValue:inRow:
delegate method
– addRow:
– insertRowAtIndex:withType:asSubrowOfRow:animate:
– removeRowAtIndex:
– removeRowsAtIndexes:includeSubrows:
– ruleEditorRowsDidChange:
delegate method
Note that there is a subclass of NSRuleEditor
, NSPredicateEditor
, that is designed to facilitate creation of predicates.
NSRuleEditor
is key-value coding and key-value observing compliant for the keys described in this section. If you override any of these methods, you must ensure that you invoke the relevant change notification methods to maintain key-value observing compliance. For more information, see Key-Value Coding Programming Guide and Key-Value Observing Programming Guide. For more about Cocoa bindings, see Cocoa Bindings Programming Topics.
– rowClass
– setRowClass:
– rowTypeKeyPath
– setRowTypeKeyPath:
– subrowsKeyPath
– setSubrowsKeyPath:
– criteriaKeyPath
– setCriteriaKeyPath:
– displayValuesKeyPath
– setDisplayValuesKeyPath:
Adds a row to the receiver.
- (void)addRow:(id)sender
Typically the object that sent the message.
NSRuleEditor.h
Returns a Boolean value that indicates whether all the rows can be removed.
- (BOOL)canRemoveAllRows
YES
if all the rows can be removed, otherwise NO
.
NSRuleEditor.h
Returns the currently chosen items for a given row.
- (NSArray *)criteriaForRow:(NSInteger)row
The index of a row in the receiver.
The currently chosen items for row row.
The items returned are the same as those returned from the delegate method ruleEditor:child:forCriterion:withRowType:.
NSRuleEditor.h
Returns the criteria key path.
- (NSString *)criteriaKeyPath
The criteria key path.
The default value is @"criteria"
.
The key path is used to get the criteria for a row in the "rows" binding. The criteria objects are what the delegate returns from ruleEditor:child:forCriterion:withRowType:. The corresponding property should be an ordered to-many relationship.
NSRuleEditor.h
Returns the receiver’s delegate.
- (id)delegate
The receiver’s delegate.
NSRuleEditor.h
Returns the chosen values for a given row.
- (NSArray *)displayValuesForRow:(NSInteger)row
The index of a row in the receiver.
The chosen values (strings, views, or menu items) for row row.
The values returned are the same as those returned from the delegate method ruleEditor:displayValueForCriterion:inRow:.
NSRuleEditor.h
Returns the display values key path.
- (NSString *)displayValuesKeyPath
The display values key path.
The default is @"displayValues"
.
The key path is used to get the display values for a row in the "rows" binding. The display values are what the delegate returns from ruleEditor:displayValueForCriterion:inRow:. The corresponding property should be an ordered to-many relationship.
NSRuleEditor.h
Returns the formatting dictionary for the receiver.
- (NSDictionary *)formattingDictionary
The formatting dictionary for the receiver.
NSRuleEditor.h
Returns the name of the strings file for the receiver.
- (NSString *)formattingStringsFilename
The name of the strings file for the receiver.
NSRuleEditor.h
Adds a new row of a given type at a given location.
- (void)insertRowAtIndex:(NSInteger)rowIndex withType:(NSRuleEditorRowType)rowType asSubrowOfRow:(NSInteger)parentRow animate:(BOOL)shouldAnimate
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.
The type of the new row.
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.
YES
if creation of the new row should be animated, otherwise NO
.
Important: If parentRow is greater than or equal to rowIndex, or if rowIndex would fall amongst the children of some other parent, or if the nesting mode forbids this configuration, an NSInvalidArgumentException
is raised.
NSRuleEditor.h
Returns a Boolean value that indicates whether the receiver is editable.
- (BOOL)isEditable
YES
if the receiver is editable, otherwise NO
.
The default is YES
.
NSRuleEditor.h
Returns the nesting mode for the receiver.
- (NSRuleEditorNestingMode)nestingMode
The nesting mode for the receiver.
NSRuleEditor.h
Returns the number of rows in the receiver.
- (NSInteger)numberOfRows
The number of rows in the receiver.
NSRuleEditor.h
Returns the index of the parent of a given row.
- (NSInteger)parentRowForRow:(NSInteger)rowIndex
The index of a row in the receiver.
Important: Raises an NSRangeException
if rowIndex is less than 0
or greater than or equal to the number of rows.
The index of the parent of the row at rowIndex. If the row at rowIndex is a root row, returns -1
.
NSRuleEditor.h
Returns the predicate for the receiver.
- (NSPredicate *)predicate
If the delegate implements ruleEditor:predicatePartsForCriterion:withDisplayValue:inRow:, the predicate for the receiver. If the delegate does implement ruleEditor:predicatePartsForCriterion:withDisplayValue:inRow:, or if the delegate does not return enough parts to construct a full predicate, returns nil
.
NSRuleEditor.h
Returns the predicate for a given row.
- (NSPredicate *)predicateForRow:(NSInteger)row
The index of a row in the receiver.
The predicate for the row at row.
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.
NSRuleEditor.h
Instructs the receiver to refetch criteria from its delegate.
- (void)reloadCriteria
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.
NSRuleEditor.h
Instructs the receiver to regenerate its predicate by invoking the corresponding delegate method.
- (void)reloadPredicate
You typically invoke this method because something has changed (for example, a view's value).
NSRuleEditor.h
Removes the row at a given index.
- (void)removeRowAtIndex:(NSInteger)rowIndex
The index of a row in the receiver.
Important: Raises an NSRangeException
if rowIndex is less than 0
or greater than or equal to the number of rows.
Any subrows of the deleted row are adopted by the parent of the deleted row, or are made root rows.
NSRuleEditor.h
Removes the rows at given indexes.
- (void)removeRowsAtIndexes:(NSIndexSet *)rowIndexes includeSubrows:(BOOL)includeSubrows
Indexes of one or more rows in the receiver.
Important: Raises an NSRangeException
if any index in rowIndexes is less than 0
or greater than or equal to the number of rows.
If YES
, then sub-rows of deleted rows are also deleted; if NO
, then each sub-row is adopted by its first non-deleted ancestor, or becomes a root row.
NSRuleEditor.h
Returns the class used to create a new row in the “rows” binding.
- (Class)rowClass
The class used to create a new row in the "rows" binding.
By default, this is NSMutableDictionary
.
NSRuleEditor.h
Returns the index of the row containing a given value.
- (NSInteger)rowForDisplayValue:(id)displayValue
The display value (string, view, or menu item) of an item in the receiver. This value must not be nil
.
Important: Raises NSInvalidArgumentException
if displayValue is nil
.
The index of the row containing displayValue, or NSNotFound
.
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.
NSRuleEditor.h
Returns the row height for the receiver.
- (CGFloat)rowHeight
The row height for the receiver.
NSRuleEditor.h
Returns the type of a given row.
- (NSRuleEditorRowType)rowTypeForRow:(NSInteger)rowIndex
The index of a row in the receiver.
Important: Raises an NSRangeException
if rowIndex is less than 0
or greater than or equal to the number of rows.
The type of the row at rowIndex.
NSRuleEditor.h
Returns the key path for the row type.
- (NSString *)rowTypeKeyPath
The key path for the row type.
The default value is @"rowType"
.
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”
).
NSRuleEditor.h
Returns the indexes of the receiver’s selected rows.
- (NSIndexSet *)selectedRowIndexes
The indexes of the receiver’s selected rows.
NSRuleEditor.h
Sets in the receiver the indexes of rows that are selected.
- (void)selectRowIndexes:(NSIndexSet *)indexes byExtendingSelection:(BOOL)extend
The indexes of rows in the receiver to select.
Important: Raises an NSRangeException
if any index in rowIndexes is less than 0
or greater than or equal to the number of rows.
If NO
, the selected rows are specified by indexes. If YES
, the rows indicated by indexes are added to the collection of already selected rows, providing multiple selection.
NSRuleEditor.h
Sets whether all the rows can be removed.
- (void)setCanRemoveAllRows:(BOOL)val
YES
if all the rows can be removed, otherwise NO
.
NSRuleEditor.h
Modifies the row at a given index to contain the given items and values.
- (void)setCriteria:(NSArray *)criteria andDisplayValues:(NSArray *)values forRowAtIndex:(NSInteger)rowIndex
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
.
Important: Raises an NSInvalidArgumentException
if criteria is nil
.
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
.
Important: Raises an NSInvalidArgumentException
if values is nil
.
The index of a row in the receiver.
Important: Raises an NSRangeException
if rowIndex is equal to or larger than the number of rows, or less than 0
.
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
.
NSRuleEditor.h
Sets the criteria key path.
- (void)setCriteriaKeyPath:(NSString *)keyPath
The criteria key path.
The criteria key path is described in criteriaKeyPath
.
NSRuleEditor.h
Sets the receiver’s delegate.
- (void)setDelegate:(id)delegate
The delegate for the receiver.
NSRuleEditor.h
Sets the display values key path.
- (void)setDisplayValuesKeyPath:(NSString *)keyPath
The display values key path.
The display values key path is described in displayValuesKeyPath
.
NSRuleEditor.h
Sets whether the receiver is editable.
- (void)setEditable:(BOOL)editable
YES
if the receiver is editable, otherwise NO
.
NSRuleEditor.h
Sets the formatting dictionary for the receiver.
- (void)setFormattingDictionary:(NSDictionary *)dictionary
The formatting dictionary for the receiver.
If you set the formatting dictionary with this method, it sets the current to formatting strings file name nil
(see formattingStringsFilename
).
NSRuleEditor.h
Sets the name of the strings file used for formatting.
- (void)setFormattingStringsFilename:(NSString *)stringsFilename
The name of the strings file for the receiver.
NSRuleEditor
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 formattingDictionary
].
If you set the formatting dictionary with setFormattingDictionary:
, it sets the current to formatting strings file name nil
(see formattingStringsFilename
).
NSRuleEditor.h
Sets the nesting mode for the receiver.
- (void)setNestingMode:(NSRuleEditorNestingMode)mode
The nesting mode for the receiver.
You typically set the nesting mode at view creation time and do not subsequently modify it. The default is NSRuleEditorNestingModeCompound
.
NSRuleEditor.h
Sets the class to use to create a new row in the "rows” binding.
- (void)setRowClass:(Class)rowClass
The class to use to create a new row in the "rows” binding.
NSRuleEditor.h
Sets the row height for the receiver.
- (void)setRowHeight:(CGFloat)height
The row height for the receiver.
NSRuleEditor.h
Sets the key path for the row type.
- (void)setRowTypeKeyPath:(NSString *)keyPath
The key path for the row type.
The row type key path is described in rowTypeKeyPath
.
NSRuleEditor.h
Set the key path for the subrows.
- (void)setSubrowsKeyPath:(NSString *)keyPath
The key path for the subrows.
The subrows key path is described in subrowsKeyPath
.
NSRuleEditor.h
Returns the immediate subrows of a given row.
- (NSIndexSet *)subrowIndexesForRow:(NSInteger)rowIndex
The index of a row in the receiver, or -1
to get the top-level rows.
Important: Raises an NSRangeException
if rowIndex is less than -1
or greater than or equal to the number of rows.
The immediate subrows of the row at rowIndex.
Rows are numbered starting at 0
.
NSRuleEditor.h
The key path for the subrows.
- (NSString *)subrowsKeyPath
The key path for the subrows.
The default value is @"subrows"
.
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.
NSRuleEditor.h
Overrides the NSView
implementation.
- (void)viewDidMoveToWindow
If you override this method in a subclass, you must invoke super’s implementation.
Returns the child of a given item at a given index.
- (id)ruleEditor:(NSRuleEditor *)editor child:(NSInteger)index forCriterion:(id)criterion withRowType:(NSRuleEditorRowType)rowType
The rule editor that sent the message.
The index of the requested child criterion. This value must be in the range from 0
up to (but not including) the number of children, as reported by the delegate in ruleEditor:numberOfChildrenForCriterion:withRowType:.
The parent of the requested child, or nil
if the rule editor is requesting a root criterion.
The type of the row.
An object representing the requested child (or root) criterion. This object is used by the delegate to represent that position in the tree, and is passed as a parameter in subsequent calls to the delegate.
The delegate must implement this method.
NSRuleEditor.h
Returns the value for a given criterion.
- (id)ruleEditor:(NSRuleEditor *)editor displayValueForCriterion:(id)criterion inRow:(NSInteger)row
The rule editor that sent the message.
The criterion for which the value is required.
The row number of criterion.
The value for criterion.
The value should be an instance of NSString
, NSView
, or NSMenuItem
. If the value is an NSView
or NSMenuItem
, you must ensure it is unique for every invocation of this method; that is, do not return a particular instance of NSView
or NSMenuItem
more than once.
The delegate must implement this method.
NSRuleEditor.h
Returns the number of child items of a given criterion or row type.
- (NSInteger)ruleEditor:(NSRuleEditor *)editor numberOfChildrenForCriterion:(id)criterion withRowType:(NSRuleEditorRowType)rowType
The rule editor that sent the message.
The criterion for which the number of children is required.
The type of row of criterion.
The number of child items of criterion. If criterion is nil
, return the number of root criteria for the row type rowType.
The delegate must implement this method.
NSRuleEditor.h
Returns a dictionary representing the parts of the predicate determined by the given criterion and value.
- (NSDictionary *)ruleEditor:(NSRuleEditor *)editor predicatePartsForCriterion:(id)criterion withDisplayValue:(id)value inRow:(NSInteger)row
The rule editor that sent the message.
The criterion for which the predicate parts are required.
The row number of criterion.
A dictionary representing the parts of the predicate determined by the given criterion and value. The keys of the dictionary should be the string constants specified in “Predicate Part Keys”
with corresponding appropriate values.
Implementation of this method is optional.
NSRuleEditor.h
Notifies the receiver that a rule editor’s rows changed.
- (void)ruleEditorRowsDidChange:(NSNotification *)notification
A NSRuleEditorRowsDidChangeNotification
notification.
If this method is implemented, NSRuleEditor
automatically registers its delegate to receive NSRuleEditorRowsDidChangeNotification
notifications to this method.
NSRuleEditor.h
Specifies a type for nesting modes.
typedef NSUInteger NSRuleEditorNestingMode;
See “Nesting Modes” for possible values.
NSRuleEditor.h
These constants specify the nesting mode for the rule editor.
enum { NSRuleEditorNestingModeSingle, NSRuleEditorNestingModeList, NSRuleEditorNestingModeCompound, NSRuleEditorNestingModeSimple };
NSRuleEditorNestingModeSingle
Only a single row is allowed.
Plus/minus buttons are not shown.
Available in Mac OS X v10.5 and later.
Declared in NSRuleEditor.h
.
NSRuleEditorNestingModeList
Allows a single list, with no nesting and no compound rows.
Available in Mac OS X v10.5 and later.
Declared in NSRuleEditor.h
.
NSRuleEditorNestingModeCompound
Unlimited nesting and compound rows.
This is the default.
Available in Mac OS X v10.5 and later.
Declared in NSRuleEditor.h
.
NSRuleEditorNestingModeSimple
One compound row at the top with subrows beneath it, and no further nesting allowed.
Available in Mac OS X v10.5 and later.
Declared in NSRuleEditor.h
.
NSRuleEditor.h
Specifies a type for row types.
typedef NSUInteger NSRuleEditorRowType;
See “Row Types” for possible values.
NSRuleEditor.h
Specify the type of a rule editor row.
enum { NSRuleEditorRowTypeSimple, NSRuleEditorRowTypeCompound };
NSRuleEditorRowTypeSimple
Specifies a simple row.
Available in Mac OS X v10.5 and later.
Declared in NSRuleEditor.h
.
NSRuleEditorRowTypeCompound
Specifies a compound row.
Available in Mac OS X v10.5 and later.
Declared in NSRuleEditor.h
.
NSRuleEditor.h
These strings are used as keys to the dictionary returned from the optional delegate method ruleEditor:predicatePartsForCriterion:withDisplayValue:inRow:. To construct a valid predicate, the union of the dictionaries for each item in the row must contain the required parts.
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;
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 Mac OS X v10.5 and later.
Declared in NSRuleEditor.h
.
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 Mac OS X v10.5 and later.
Declared in NSRuleEditor.h
.
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 Mac OS X v10.5 and later.
Declared in NSRuleEditor.h
.
NSRuleEditorPredicateOptions
The corresponding value is an NSNumber
object representing a NSComparisonPredicateOptions
bitfield.
If no value is specified, 0
(no options) is assumed.
Available in Mac OS X v10.5 and later.
Declared in NSRuleEditor.h
.
NSRuleEditorPredicateOperatorType
The corresponding value is an NSNumber
object representing a NSPredicateOperatorType
constant.
This value is required for a non-nil
comparison predicate.
Available in Mac OS X v10.5 and later.
Declared in NSRuleEditor.h
.
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 Mac OS X v10.5 and later.
Declared in NSRuleEditor.h
.
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 Mac OS X v10.5 and later.
Declared in NSRuleEditor.h
.
NSRuleEditor.h
This notification is posted to the default notification center whenever the view's rows change.
The object is the rule editor; there is no userInfo
object.
NSRuleEditor.h
© 2008 Apple Inc. All Rights Reserved. (Last updated: 2008-02-08)