A MOViewListView is a vertical list of views that can be individually collapsed or expanded.
A MOViewListView has a list of "stacked views" that it keeps arranged in a vertical stack. The appearance and behavior is similar to similar UI seen in PB, in some Microsoft apps, in the Jaguar Finder's Info window, and in Okito Composer among others. A MOViewListView is generally intended to live in a scroll view with a vertical scroller. Sizing behavior is interesting. The width of the MOViewListView determines the width of its subviews, but the combined height of the subviews and labels determines the height of the MOViewListView. Thus, subviews of a MOViewListView are generally expected to be able to take on any width, but are free to be a specific height and as tall as they need to be. The MOViewListView watches for changes in the frame of its subviews and will adapt itself as needed if any of the views change height.
MOViewListView uses instances of MOViewListViewItem to manage its subviews. Each MOViewListViewItem has a view and a label (and some other incidental attributes.) MOViewListViewItem is similar in function to NSTabViewItem. In particular one interesting use of MOViewListViewItem is to allow the subviews of a MOViewListView to be loaded lazily only when needed. MOViewListViewItems can be created with no view initially and added to the MOViewListView. The MOViewListView's delegate can then implement -viewListView:willExpandViewListViewItem: to load the view if necessary and set it into the MOViewListViewItem. That way as long as an item is collapsed and has never been expanded, its view will not be loaded.
MOViewListView has a lot of configurability with respect to its appearance. It implements the standard Cocoa -controlSize/-setControlSize: methods and adapts the appearance of its label bars accordingly. All the colors used for drawing the view (its background and labels) are also configurable. In addition, a convenience API is provided that sets all the colors to several preset schemes (some of which mimic the appearance of this type of view used in PB and Finder.)
MOViewListView can animate when collapsing or expanding subviews. There is specific API for expanding and collapsing that takes a flag to indicate whether to animate. There is also API that does not take that flag and those APIs animate or not depending on a user preference. The preference for animation is enabled by default. +usesAnimation and +setUsesAnimation: can be used to query and control this preference.
By default MOViewListView adapts to any changes that require relayout of its subviews immediately as changes are made. There is API for disabling/enabling this. If you plan to make a whole series of changes, you may want to disable relayout before you begin and re-enable it when you are done to prevent unnecessary work during the changes.
addStackedView:withLabel: |
- ( MOViewListViewItem *) addStackedView: (NSView *) view withLabel: (NSString *) label;
Adds the given view into the receiver. This simply calls [self insertStackedView:view atIndex:[self numberOfViewListViewItems] withLabel:label]. The new item is returned.
- view
- The view.
- label
- The label for the new view.
addViewListViewItem: |
- ( void ) addViewListViewItem: (MOViewListViewItem *) item;
Adds a new MOViewListViewItem into the receiver. This simply calls [self insertViewListViewItem:item atIndex:[self numberOfViewListViewItems]].
- item
- The new item.
backgroundColor |
- ( NSColor *) backgroundColor;
Returns the receiver's background color. If the background color is nil, then no background is drawn. If the background color is not nil and is opaque (has alpha 1.0), then the view is opaque, otherwise it is not. The default background color is [NSColor controlColor].
collapseStackedViewAtIndex: |
- ( void ) collapseStackedViewAtIndex: (int ) index;
Collapses the view at the given index. This calls [self collapseStackedViewAtIndex:index animate:[[self class] usesAnimation]].
- index
- The index.
collapseStackedViewAtIndex:animate: |
- ( void ) collapseStackedViewAtIndex: (int ) index animate: (BOOL ) animateFlag;
Collapses the view at the given index. This is the primitive for collpasing. The animateFlag indicates whether to animate the collpasing.
- index
- The index.
- animateFlag
- Whether to animate.
controlSize |
- ( NSControlSize ) controlSize;
Returns the receiver's control size.
delegate |
- ( id ) delegate;
Returns the receiver's delegate.
disableLayout |
- ( void ) disableLayout;
Disables relayout of the subviews. This method can be used to turn off immediate relayout of subviews in response to changes made to the views or the receiver's settings. Use -enableLayout to turn it back on (and to cause any needed relayout to be done). Multiple calls to this must be balanced with the same number of calls to -enableLayout (in other words, calls to this API stack).
dragImageForItem:event:dragImageOffset: |
- ( NSImage *) dragImageForItem: (MOViewListViewItem *) dragItem event: (NSEvent *) dragEvent dragImageOffset: (NSPointPointer ) dragImageOffsetPtr;
Returns the image to use for dragging a view list view item/subview. MOViewListView will create a default image, but subclasses can override if they need to do something different. This method will be called with dragImageOffset set to NSZeroPoint, but it can be modified to re-position the returned image. A dragImageOffset of NSZeroPoint will cause the image to be centered under the mouse.
- dragItem
- The MOViewListViewItem that will be dragged.
- dragEvent
- The event that started the drag.
- dragImageOffsetPtr
- A pointer to a point that can be filled in to provide an image offset.
enableLayout |
- ( void ) enableLayout;
Enables relayout of the subviews. This method can be used to turn back on immediate relayout of subviews in response to changes made to the views or the receiver's settings after a previous call to -disableLayout. If any relayout is needed, then this method will cause it to happen. Multiple calls to -disableLayout must be balanced with the same number of calls to -enableLayout (in other words, calls to this API stack).
expandStackedViewAtIndex: |
- ( void ) expandStackedViewAtIndex: (int ) index;
Expands the view at the given index. This calls [self expandStackedViewAtIndex:index animate:[[self class] usesAnimation]].
- index
- The index.
expandStackedViewAtIndex:animate: |
- ( void ) expandStackedViewAtIndex: (int ) index animate: (BOOL ) animateFlag;
Expands the view at the given index. This is the primitive for expanding. The animateFlag indicates whether to animate the expanding.
- index
- The index.
- animateFlag
- Whether to animate.
frameForDisclosureControlAtIndex: |
- ( NSRect ) frameForDisclosureControlAtIndex: (int ) index;
Returns the frame for the disclosure control of the item with the given index.
- index
- The index.
frameForLabelBarAtIndex: |
- ( NSRect ) frameForLabelBarAtIndex: (int ) index;
Returns the frame for the label bar of the item with the given index.
- index
- The index.
frameForLabelTextAtIndex: |
- ( NSRect ) frameForLabelTextAtIndex: (int ) index;
Returns the frame for the label text of the item with the given index. Note that this rect is the whole area of the bar available for the label text. It goes all the way to the end of the bar regardless of the length of the actual label.
- index
- The index.
indexOfStackedView: |
- ( int ) indexOfStackedView: (NSView *) view;
Returns the index of the given view. This looks through the receiver's items for one that has the given view and returns the index of the item. If the view is not owned by any of the receiver's items, this returns -1.
- view
- The view.
initWithFrame: |
- ( id ) initWithFrame: (NSRect ) frame;
Designated Initializer. Initializes the receiver with the given frame. This method calls the MOViewSizing method MO_setTakesMinSizeFromClipView:YES to ensure it always fills its clip view.
- frame
- The frame rectangle for the view.
insertStackedView:atIndex:withLabel: |
- ( MOViewListViewItem *) insertStackedView: (NSView *) view atIndex: (int ) index withLabel: (NSString *) label;
Inserts the given view into the receiver. This simply creates a new item and calls [self insertViewListViewItem:newItem atIndex:index]. The new item is returned.
- view
- The view.
- index
- The index.
- label
- The label for the new view.
insertViewListViewItem:atIndex: |
- ( void ) insertViewListViewItem: (MOViewListViewItem *) item atIndex: (int ) index;
Inserts a new MOViewListViewItem into the receiver. The new item is inserted at the given index and will initially be collapsed. This method is the primitive for inserting a new item. All other add/insert methods eventually call this one. This method calls -setViewListView:self on the new item.
- item
- The new item.
- index
- The index.
invalidateLayoutStartingWithStackedViewAtIndex: |
- ( void ) invalidateLayoutStartingWithStackedViewAtIndex: (int ) index;
Invalidates layout of subviews and recevier. If layout is not disabled, the new layout will be calculated immediately (by calling -sizeToFit). Otherwise, the new layout will be done once layout is re-enabled. MOViewListView calls this itself whenever changes are made that affect the layout. It should usually not be necessary to invoke this method directly.
- index
- The index.
isLayoutDisabled |
- ( BOOL ) isLayoutDisabled;
Returns whether the receiver will pend any necessary layout. This basically returns whether -disableLayout has been called more times than -enableLayout.
labelBarAppearance |
- ( MOViewListViewLabelBarAppearance ) labelBarAppearance;
Returns the receiver's label bar appearance.
- scheme
- The appearance type constant.
labelFont |
- ( NSFont *) labelFont;
Returns the receiver's label font. MOViewListView uses the system font. The size is determined by the controlSize.
labelHeight |
- ( float ) labelHeight;
Returns the receiver's label height. MOViewListView calculates this from the labelFont.
numberOfViewListViewItems |
- ( int ) numberOfViewListViewItems;
Returns the number of MOViewListViewItems the receiver has. This is basically the number of labels/subviews (although not all the managed views are technically subviews at a given time).
removeViewListViewItemAtIndex: |
- ( void ) removeViewListViewItemAtIndex: (int ) index;
Removes a MOViewListViewItem from the receiver. The item at the given index is removed. This method is the primitive for removed an item. This method calls -setViewListView:nil on the new item.
- index
- The index.
setBackgroundColor: |
- ( void ) setBackgroundColor: (NSColor *) color;
Sets the receiver's background color. If the background color is nil, then no background is drawn. If the background color is not nil and is opaque (has alpha 1.0), then the view is opaque, otherwise it is not.
- color
- The background color.
setControlSize: |
- ( void ) setControlSize: (NSControlSize ) size;
Sets the receiver's control size.
- size
- The control size.
setDelegate: |
- ( void ) setDelegate: (id ) delegate;
Sets the receiver's delegate.
- delegate
- The delegate.
setDropItemIndex:dropOperation: |
- ( void ) setDropItemIndex: (int ) itemIndex dropOperation: (MOViewListViewDropOperation ) op;
Method to allow delegate to reposition a drop. To be used from viewListView:validateDrop:proposedItemIndex:proposedDropOperation: if you wish to "re-target" the proposed drop. To specify a drop on the second item, one would specify itemIndex=1, and op=MOViewListViewDropOnItem. To specify a drop after the last item, one would specify row=[[viewListView viewListViewItems] count], and op=MOViewListViewDropBeforeItem.
- itemIndex
- The item index.
- op
- The drop operation.
setLabelBarAppearance: |
- ( void ) setLabelBarAppearance: (MOViewListViewLabelBarAppearance ) labelBarAppearance;
Sets the receiver's label bar appearance.
- scheme
- The appearance type constant.
setNeedsDisplayForLabelBarAtIndex: |
- ( void ) setNeedsDisplayForLabelBarAtIndex: (int ) index;
Invalidates the display of the label for the item at the given index. MOViewListViewItem's -setLabel: calls this to make sure the new label will be shown.
- index
- The index.
setUsesAnimation: |
+ ( BOOL ) usesAnimation;
Returns whether animation is used for collapsing and expanding. This does not apply to the API that takes a specific flag indicating whether to animate. It applies to user-initiated collapsing or expanding and to use of the API with no specific animation flag. The setting is fetched from NSUserDefaults with the key MOViewListViewUsesAnimation. The default setting is YES.
setUsesAnimation:((BOOL)) |
+ ( void ) setUsesAnimation: (BOOL ) flag;
Sets whether animation is used for collapsing and expanding. This does not apply to the API that takes a specific flag indicating whether to animate. It applies to user-initiated collapsing or expanding and to use of the API with no specific animation flag. The setting is stored in NSUserDefaults with the key MOViewListViewUsesAnimation. The default setting is YES.
- flag
- Whether to animate.
setViewListLabelViewClass: |
- ( void ) setViewListLabelViewClass: (Class ) theClass;
Sets the MOViewListLabelView subclass used for labels in this instance. By default MOViewListView uses MOViewListLabelViews to implement its labels, but this method can be used to supply a substitue class (which should be a subclass of MOViewListLabelView.) Calling this method with a new class will replace all existing label views for the receiver with new instances of the new class.
- theClass
- The class.
shouldCollapseViewListViewItem: |
- ( BOOL ) shouldCollapseViewListViewItem: (MOViewListViewItem *) item;
Consults the delegate to determine if the given item can collapse. MOViewListLabelView uses this method during mouse tracking to ask whether it is OK to collapse. MOViewListView returns the delegate's answer if the delegate implements viewListView:shouldCollapseViewListViewItem:, otherwise it returns YES.
- item
- The item that wants to collapse.
shouldExpandViewListViewItem: |
- ( BOOL ) shouldExpandViewListViewItem: (MOViewListViewItem *) item;
Consults the delegate to determine if the given item can expand. MOViewListLabelView uses this method during mouse tracking to ask whether it is OK to expand. MOViewListView returns the delegate's answer if the delegate implements viewListView:shouldExpandViewListViewItem:, otherwise it returns YES.
- item
- The item that wants to expand.
sizeToFit |
- ( void ) sizeToFit;
Does any needed layout and makes sure the receiver is the right size. If layout is disabled, this does nothing. Otherwise this does any necessary resizing of height of the stack view to fit all the subviews and labels currently visible, and it resizes widths of and repositions subviews to fit in the stack view. (ie height is calculated bottom-up, width is enforced top-down.)
toggleStackedViewAtIndex: |
- ( void ) toggleStackedViewAtIndex: (int ) index;
Toggles the collapsed state of the view at the given index. This calls [self toggleStackedViewAtIndex:index animate:[[self class] usesAnimation]].
- index
- The index.
toggleStackedViewAtIndex:animate: |
- ( void ) toggleStackedViewAtIndex: (int ) index animate: (BOOL ) animateFlag;
Toggles the collapsed state of the view at the given index. The animateFlag indicates whether to animate.
- index
- The index.
- animateFlag
- Whether to animate.
usesAnimation |
+ ( BOOL ) usesAnimation;
Returns whether animation is used for collapsing and expanding. This does not apply to the API that takes a specific flag indicating whether to animate. It applies to user-initiated collapsing or expanding and to use of the API with no specific animation flag. The setting is fetched from NSUserDefaults with the key MOViewListViewUsesAnimation. The default setting is YES.
viewListLabelViewClass |
- ( Class ) viewListLabelViewClass;
Returns the MOViewListLabelView subclass used for labels in this instance. By default this returns [MOViewListLabelView class], but you can use -setViewListLabelViewClass: to substitue a custom subclass.
viewListViewItemAtIndex: |
- ( MOViewListViewItem *) viewListViewItemAtIndex: (int ) index;
Returns the MOViewListViewItem at the given index.
- index
- The index.
viewListViewItems |
- ( NSArray *) viewListViewItems;
Returns the receiver's array of MOViewListViewItems.
(Last Updated 3/20/2005)