NSRuleEditor Class Reference
| Inherits from | |
| Conforms to | |
| Framework | /System/Library/Frameworks/AppKit.framework |
| Availability | Available in OS X v10.5 and later. |
| Declared in | NSRuleEditor.h |
Overview
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.
Tasks
Configuring a Rule Editor
-
– delegate -
– setDelegate: -
– isEditable -
– setEditable: -
– nestingMode -
– setNestingMode: -
– canRemoveAllRows -
– setCanRemoveAllRows: -
– rowHeight -
– setRowHeight:
Working with Formatting
-
– formattingDictionary -
– setFormattingDictionary: -
– formattingStringsFilename -
– setFormattingStringsFilename:
Providing Data
-
– reloadCriteria -
– setCriteria:andDisplayValues:forRowAtIndex: -
– criteriaForRow: -
– displayValuesForRow:
Obtaining Row Information
Working with the Selection
Manipulating Rows
-
– addRow: -
– insertRowAtIndex:withType:asSubrowOfRow:animate: -
– removeRowAtIndex: -
– removeRowsAtIndexes:includeSubrows:
Working with Predicates
Supporting Bindings
-
– rowClass -
– setRowClass: -
– rowTypeKeyPath -
– setRowTypeKeyPath: -
– subrowsKeyPath -
– setSubrowsKeyPath: -
– criteriaKeyPath -
– setCriteriaKeyPath: -
– displayValuesKeyPath -
– setDisplayValuesKeyPath:
Overriding ViewDidMoveToWindow
Instance Methods
addRow:
Adds a row to the receiver.
Parameters
- sender
Typically the object that sent the message.
Availability
- Available in OS X v10.5 and later.
Declared In
NSRuleEditor.hcanRemoveAllRows
Returns a Boolean value that indicates whether all the rows can be removed.
Return Value
YES if all the rows can be removed, otherwise NO.
Availability
- Available in OS X v10.5 and later.
See Also
Declared In
NSRuleEditor.hcriteriaForRow:
Returns the currently chosen items for a given 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 from the delegate method “Configuring a Rule Editor.”
Availability
- Available in OS X v10.5 and later.
Declared In
NSRuleEditor.hcriteriaKeyPath
Returns the criteria key path.
Return Value
The criteria key path.
Discussion
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 “Configuring a Rule Editor.” The corresponding property should be an ordered to-many relationship.
Availability
- Available in OS X v10.5 and later.
See Also
Declared In
NSRuleEditor.hdelegate
Returns the receiver’s delegate.
Return Value
The receiver’s delegate.
Availability
- Available in OS X v10.5 and later.
See Also
Declared In
NSRuleEditor.hdisplayValuesForRow:
Returns the chosen values for a given 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 method “Working with Formatting.”
Availability
- Available in OS X v10.5 and later.
Declared In
NSRuleEditor.hdisplayValuesKeyPath
Returns the display values key path.
Return Value
The display values key path.
Discussion
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 “Working with Formatting.” The corresponding property should be an ordered to-many relationship.
Availability
- Available in OS X v10.5 and later.
See Also
Declared In
NSRuleEditor.hformattingDictionary
Returns the formatting dictionary for the receiver.
Return Value
The formatting dictionary for the receiver.
Availability
- Available in OS X v10.5 and later.
See Also
Declared In
NSRuleEditor.hformattingStringsFilename
Returns the name of the strings file for the receiver.
Return Value
The name of the strings file for the receiver.
Availability
- Available in OS X v10.5 and later.
See Also
Declared In
NSRuleEditor.hinsertRowAtIndex:withType:asSubrowOfRow:animate:
Adds a new row of a given type at a given location.
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
-1to indicate that the new row should be a root row.- shouldAnimate
YESif creation of the new row should be animated, otherwiseNO.
Special Considerations
Availability
- Available in OS X v10.5 and later.
Declared In
NSRuleEditor.hisEditable
Returns a Boolean value that indicates whether the receiver is editable.
Return Value
YES if the receiver is editable, otherwise NO.
Discussion
The default is YES.
Availability
- Available in OS X v10.5 and later.
See Also
Declared In
NSRuleEditor.hnestingMode
Returns the nesting mode for the receiver.
Return Value
The nesting mode for the receiver.
Availability
- Available in OS X v10.5 and later.
See Also
Declared In
NSRuleEditor.hnumberOfRows
Returns the number of rows in the receiver.
Return Value
The number of rows in the receiver.
Availability
- Available in OS X v10.5 and later.
Declared In
NSRuleEditor.hparentRowForRow:
Returns the index of the parent of a given row.
Parameters
- rowIndex
The index of a row in the receiver.
Important: Raises an
NSRangeExceptionif rowIndex is less than0or greater than or equal to the number of rows.
Return Value
The index of the parent of the row at rowIndex. If the row at rowIndex is a root row, returns -1.
Availability
- Available in OS X v10.5 and later.
Declared In
NSRuleEditor.hpredicate
Returns the predicate for the receiver.
Return Value
If the delegate implements NSRuleEditor, the predicate for the receiver. If the delegate does implement NSRuleEditor, or if the delegate does not return enough parts to construct a full predicate, returns nil.
Availability
- Available in OS X v10.5 and later.
Declared In
NSRuleEditor.hpredicateForRow:
Returns the predicate for a given 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.
Availability
- Available in OS X v10.5 and later.
Declared In
NSRuleEditor.hreloadCriteria
Instructs the receiver to refetch criteria from its delegate.
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.
Availability
- Available in OS X v10.5 and later.
Declared In
NSRuleEditor.hreloadPredicate
Instructs the receiver to regenerate its predicate by invoking the corresponding delegate method.
Discussion
You typically invoke this method because something has changed (for example, a view's value).
Availability
- Available in OS X v10.5 and later.
Declared In
NSRuleEditor.hremoveRowAtIndex:
Removes the row at a given index.
Parameters
- rowIndex
The index of a row in the receiver.
Important: Raises an
NSRangeExceptionif rowIndex is less than0or greater than or equal to the number of rows.
Discussion
Any subrows of the deleted row are adopted by the parent of the deleted row, or are made root rows.
Availability
- Available in OS X v10.5 and later.
Declared In
NSRuleEditor.hremoveRowsAtIndexes:includeSubrows:
Removes the rows at given indexes.
Parameters
- rowIndexes
Indexes of one or more rows in the receiver.
Important: Raises an
NSRangeExceptionif any index in rowIndexes is less than0or greater than or equal to the number of rows.- includeSubrows
If
YES, then sub-rows of deleted rows are also deleted; ifNO, then each sub-row is adopted by its first non-deleted ancestor, or becomes a root row.
Availability
- Available in OS X v10.5 and later.
Declared In
NSRuleEditor.hrowClass
Returns the class used to create a new row in the “rows” binding.
Return Value
The class used to create a new row in the "rows" binding.
Discussion
By default, this is NSMutableDictionary.
Availability
- Available in OS X v10.5 and later.
See Also
Declared In
NSRuleEditor.hrowForDisplayValue:
Returns the index of the row containing a given value.
Parameters
- displayValue
The display value (string, view, or menu item) of an item in the receiver. This value must not be
nil.Important: Raises
NSInvalidArgumentExceptionif displayValue isnil.
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.
Availability
- Available in OS X v10.5 and later.
Declared In
NSRuleEditor.hrowHeight
Returns the row height for the receiver.
Return Value
The row height for the receiver.
Availability
- Available in OS X v10.5 and later.
See Also
Declared In
NSRuleEditor.hrowTypeForRow:
Returns the type of a given row.
Parameters
- rowIndex
The index of a row in the receiver.
Important: Raises an
NSRangeExceptionif rowIndex is less than0or greater than or equal to the number of rows.
Return Value
The type of the row at rowIndex.
Availability
- Available in OS X v10.5 and later.
Declared In
NSRuleEditor.hrowTypeKeyPath
Returns the key path for the row type.
Return Value
The key path for the row type.
Discussion
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”).
Availability
- Available in OS X v10.5 and later.
See Also
Declared In
NSRuleEditor.hselectedRowIndexes
Returns the indexes of the receiver’s selected rows.
Return Value
The indexes of the receiver’s selected rows.
Availability
- Available in OS X v10.5 and later.
Declared In
NSRuleEditor.hselectRowIndexes:byExtendingSelection:
Sets in the receiver the indexes of rows that are selected.
Parameters
- indexes
The indexes of rows in the receiver to select.
Important: Raises an
NSRangeExceptionif any index in rowIndexes is less than0or greater than or equal to the number of rows.- extend
If
NO, the selected rows are specified by indexes. IfYES, the rows indicated by indexes are added to the collection of already selected rows, providing multiple selection.
Availability
- Available in OS X v10.5 and later.
Declared In
NSRuleEditor.hsetCanRemoveAllRows:
Sets whether all the rows can be removed.
Parameters
- val
YESif all the rows can be removed, otherwiseNO.
Availability
- Available in OS X v10.5 and later.
See Also
Declared In
NSRuleEditor.hsetCriteria:andDisplayValues:forRowAtIndex:
Modifies the row at a given index to contain the given items and values.
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.Important: Raises an
NSInvalidArgumentExceptionif criteria isnil.- 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.Important: Raises an
NSInvalidArgumentExceptionif values isnil.- rowIndex
The index of a row in the receiver.
Important: Raises an
NSRangeExceptionif rowIndex is equal to or larger than the number of rows, or less than0.
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.
Availability
- Available in OS X v10.5 and later.
Declared In
NSRuleEditor.hsetCriteriaKeyPath:
Sets the criteria key path.
Parameters
- keyPath
The criteria key path.
Discussion
The criteria key path is described in criteriaKeyPath.
Availability
- Available in OS X v10.5 and later.
See Also
Declared In
NSRuleEditor.hsetDelegate:
Sets the receiver’s delegate.
Parameters
- delegate
The delegate for the receiver.
Availability
- Available in OS X v10.5 and later.
See Also
Declared In
NSRuleEditor.hsetDisplayValuesKeyPath:
Sets the display values key path.
Parameters
- keyPath
The display values key path.
Discussion
The display values key path is described in displayValuesKeyPath.
Availability
- Available in OS X v10.5 and later.
See Also
Declared In
NSRuleEditor.hsetEditable:
Sets whether the receiver is editable.
Parameters
- editable
YESif the receiver is editable, otherwiseNO.
Availability
- Available in OS X v10.5 and later.
See Also
Declared In
NSRuleEditor.hsetFormattingDictionary:
Sets the formatting dictionary for the receiver.
Parameters
- dictionary
The formatting dictionary for the receiver.
Discussion
If you set the formatting dictionary with this method, it sets the current to formatting strings file name nil (see formattingStringsFilename).
Availability
- Available in OS X v10.5 and later.
See Also
Declared In
NSRuleEditor.hsetFormattingStringsFilename:
Sets the name of the strings file used for formatting.
Parameters
- stringsFilename
The name of the strings file for the receiver.
Discussion
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).
Availability
- Available in OS X v10.5 and later.
See Also
Declared In
NSRuleEditor.hsetNestingMode:
Sets the nesting mode for the receiver.
Parameters
- mode
The nesting mode for the receiver.
Discussion
You typically set the nesting mode at view creation time and do not subsequently modify it. The default is NSRuleEditorNestingModeCompound.
Availability
- Available in OS X v10.5 and later.
See Also
Declared In
NSRuleEditor.hsetRowClass:
Sets the class to use to create a new row in the "rows” binding.
Parameters
- rowClass
The class to use to create a new row in the "rows” binding.
Availability
- Available in OS X v10.5 and later.
See Also
Declared In
NSRuleEditor.hsetRowHeight:
Sets the row height for the receiver.
Parameters
- height
The row height for the receiver.
Availability
- Available in OS X v10.5 and later.
See Also
Declared In
NSRuleEditor.hsetRowTypeKeyPath:
Sets the key path for the row type.
Parameters
- keyPath
The key path for the row type.
Discussion
The row type key path is described in rowTypeKeyPath.
Availability
- Available in OS X v10.5 and later.
See Also
Declared In
NSRuleEditor.hsetSubrowsKeyPath:
Set the key path for the subrows.
Parameters
- keyPath
The key path for the subrows.
Discussion
The subrows key path is described in subrowsKeyPath.
Availability
- Available in OS X v10.5 and later.
See Also
Declared In
NSRuleEditor.hsubrowIndexesForRow:
Returns the immediate subrows of a given row.
Parameters
- rowIndex
The index of a row in the receiver, or
-1to get the top-level rows.Important: Raises an
NSRangeExceptionif rowIndex is less than-1or greater than or equal to the number of rows.
Return Value
The immediate subrows of the row at rowIndex.
Discussion
Rows are numbered starting at 0.
Availability
- Available in OS X v10.5 and later.
Declared In
NSRuleEditor.hsubrowsKeyPath
The key path for the subrows.
Return Value
The key path for the subrows.
Discussion
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.
Availability
- Available in OS X v10.5 and later.
See Also
Declared In
NSRuleEditor.hConstants
NSRuleEditorNestingMode
Specifies a type for nesting modes.
typedef NSUInteger NSRuleEditorNestingMode;
Discussion
See “Nesting Modes” for possible values.
Availability
- Available in OS X v10.5 and later.
Declared In
NSRuleEditor.hNesting Modes
These constants specify the nesting mode for the rule editor.
enum {
NSRuleEditorNestingModeSingle,
NSRuleEditorNestingModeList,
NSRuleEditorNestingModeCompound,
NSRuleEditorNestingModeSimple
};
Constants
NSRuleEditorNestingModeSingleOnly a single row is allowed.
Plus/minus buttons are not shown.
Available in OS X v10.5 and later.
Declared in
NSRuleEditor.h.NSRuleEditorNestingModeListAllows a single list, with no nesting and no compound rows.
Available in OS X v10.5 and later.
Declared in
NSRuleEditor.h.NSRuleEditorNestingModeCompoundUnlimited nesting and compound rows.
This is the default.
Available in OS X v10.5 and later.
Declared in
NSRuleEditor.h.NSRuleEditorNestingModeSimpleOne compound row at the top with subrows beneath it, and no further nesting allowed.
Available in OS X v10.5 and later.
Declared in
NSRuleEditor.h.
Declared In
NSRuleEditor.hNSRuleEditorRowType
Specifies a type for row types.
typedef NSUInteger NSRuleEditorRowType;
Discussion
See “Row Types” for possible values.
Availability
- Available in OS X v10.5 and later.
Declared In
NSRuleEditor.hRow Types
Specify the type of a rule editor row.
enum {
NSRuleEditorRowTypeSimple,
NSRuleEditorRowTypeCompound
};
Constants
NSRuleEditorRowTypeSimpleSpecifies a simple row.
Available in OS X v10.5 and later.
Declared in
NSRuleEditor.h.NSRuleEditorRowTypeCompoundSpecifies a compound row.
Available in OS X v10.5 and later.
Declared in
NSRuleEditor.h.
Declared In
NSRuleEditor.hPredicate Part Keys
These strings are used as keys to the dictionary returned from the optional delegate method NSRuleEditor. 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;
Constants
NSRuleEditorPredicateLeftExpressionThe corresponding value is an
NSExpressionobject representing the left expression in the predicate.This value is required for a non-
nilcomparison predicate.Available in OS X v10.5 and later.
Declared in
NSRuleEditor.h.NSRuleEditorPredicateRightExpressionThe corresponding value is an
NSExpressionobject representing the right expression in the predicate.This value is required for a non-
nilcomparison predicate.Available in OS X v10.5 and later.
Declared in
NSRuleEditor.h.NSRuleEditorPredicateComparisonModifierThe corresponding value is an
NSNumberobject representing aNSComparisonPredicateModifierconstant the of the predicate.This value is optional—if not specified,
NSDirectPredicateModifieris assumed.Available in OS X v10.5 and later.
Declared in
NSRuleEditor.h.NSRuleEditorPredicateOptionsThe corresponding value is an
NSNumberobject representing aNSComparisonPredicate_Optionsbitfield.If no value is specified,
0(no options) is assumed.Available in OS X v10.5 and later.
Declared in
NSRuleEditor.h.NSRuleEditorPredicateOperatorTypeThe corresponding value is an
NSNumberobject representing aNSPredicateOperatorTypeconstant.This value is required for a non-
nilcomparison predicate.Available in OS X v10.5 and later.
Declared in
NSRuleEditor.h.NSRuleEditorPredicateCustomSelectorThe corresponding value is an
NSStringobject representing a custom selector.If specified, this overrides the operator type, options, and comparison modifier.
Available in OS X v10.5 and later.
Declared in
NSRuleEditor.h.NSRuleEditorPredicateCompoundTypeThe corresponding value is an
NSNumberobject representing aCompound Predicate Typesconstant.If specified, the other keys are ignored and the predicate for the row will be an
NSCompoundPredicatepredicate whose subpredicates are the predicates of the subrows of the given row.Available in OS X v10.5 and later.
Declared in
NSRuleEditor.h.
Declared In
NSRuleEditor.hNotifications
NSRuleEditorRowsDidChangeNotification
The object is the rule editor; there is no userInfo object.
Availability
- Available in OS X v10.5 and later.
Declared In
NSRuleEditor.h© 2009 Apple Inc. All Rights Reserved. (Last updated: 2009-10-07)