MOViewListView


Abstract

A MOViewListView is a vertical list of views that can be individually collapsed or expanded.

Discussion

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.



Methods

setUsesAnimation:((BOOL))
Sets whether animation is used for collapsing and expanding.
setUsesAnimation:
Returns whether animation is used for collapsing and expanding.
usesAnimation
Returns whether animation is used for collapsing and expanding.
initWithFrame:
Initializes an instance.
numberOfViewListViewItems
Returns the number of MOViewListViewItems the receiver has.
viewListViewItems
Returns the receiver's array of MOViewListViewItems.
viewListViewItemAtIndex:
Returns the MOViewListViewItem at the given index.
insertViewListViewItem:atIndex:
Inserts a new MOViewListViewItem into the receiver.
removeViewListViewItemAtIndex:
Removes a MOViewListViewItem from the receiver.
addViewListViewItem:
Adds a new MOViewListViewItem into the receiver.
indexOfStackedView:
Returns the index of the given view.
insertStackedView:atIndex:withLabel:
Inserts the given view into the receiver.
addStackedView:withLabel:
Adds the given view into the receiver.
collapseStackedViewAtIndex:animate:
Collapses the view at the given index.
expandStackedViewAtIndex:animate:
Expands the view at the given index.
toggleStackedViewAtIndex:animate:
Toggles the collapsed state of the view at the given index.
collapseStackedViewAtIndex:
Collapses the view at the given index.
expandStackedViewAtIndex:
Expands the view at the given index.
toggleStackedViewAtIndex:
Toggles the collapsed state of the view at the given index.
setDelegate:
Sets the receiver's delegate.
delegate
Returns the receiver's delegate.
setControlSize:
Sets the receiver's control size.
controlSize
Returns the receiver's control size.
labelFont
Returns the receiver's label font.
labelHeight
Returns the receiver's label height.
labelBarAppearance
Returns the receiver's label bar appearance.
setLabelBarAppearance:
Sets the receiver's label bar appearance.
viewListLabelViewClass
Returns the MOViewListLabelView subclass used for labels in this instance.
setViewListLabelViewClass:
Sets the MOViewListLabelView subclass used for labels in this instance.
backgroundColor
Returns the receiver's background color.
setBackgroundColor:
Sets the receiver's background color.
frameForLabelBarAtIndex:
Returns the frame for an item's label bar.
frameForDisclosureControlAtIndex:
Returns the frame for an item's disclosure control.
frameForLabelTextAtIndex:
Returns the frame for an item's label text.
disableLayout
Disables relayout of the subviews.
enableLayout
Enables relayout of the subviews.
isLayoutDisabled
Returns whether the receiver will pend any necessary layout.
sizeToFit
Does any needed layout and makes sure the receiver is the right size.
invalidateLayoutStartingWithStackedViewAtIndex:
Invalidates layout of subviews and recevier.
setNeedsDisplayForLabelBarAtIndex:
Invalidates the display of the label for the item at the given index.
shouldExpandViewListViewItem:
Consults the delegate to determine if the given item can expand.
shouldCollapseViewListViewItem:
Consults the delegate to determine if the given item can collapse.
dragImageForItem:event:dragImageOffset:
Returns the image to use for dragging a view list view item/subview.
setDropItemIndex:dropOperation:
Method to allow delegate to reposition a drop.

addStackedView:withLabel:

Adds the given view into the receiver.
- ( 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.

Parameter Descriptions
view
The view.
label
The label for the new view.
method result
The MOViewListViewItem that was created.

addViewListViewItem:

Adds a new MOViewListViewItem into the receiver.
- ( void ) addViewListViewItem:
        (MOViewListViewItem *) item;

Adds a new MOViewListViewItem into the receiver. This simply calls [self insertViewListViewItem:item atIndex:[self numberOfViewListViewItems]].

Parameter Descriptions
item
The new item.

backgroundColor

Returns the receiver's background color.
- ( 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].

method result
The background color.

collapseStackedViewAtIndex:

Collapses the view at the given index.
- ( void ) collapseStackedViewAtIndex:
        (int ) index;

Collapses the view at the given index. This calls [self collapseStackedViewAtIndex:index animate:[[self class] usesAnimation]].

Parameter Descriptions
index
The index.

collapseStackedViewAtIndex:animate:

Collapses the view at the given index.
- ( 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.

Parameter Descriptions
index
The index.
animateFlag
Whether to animate.

controlSize

Returns the receiver's control size.
- ( NSControlSize ) controlSize;

Returns the receiver's control size.

method result
The control size.

delegate

Returns the receiver's delegate.
- ( id ) delegate;

Returns the receiver's delegate.

method result
The delegate.

disableLayout

Disables relayout of the subviews.
- ( 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:

Returns the image to use for dragging a view list view item/subview.
- ( 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.

Parameter Descriptions
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.
method result
The image to use for the drag.

enableLayout

Enables relayout of the subviews.
- ( 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:

Expands the view at the given index.
- ( void ) expandStackedViewAtIndex:
        (int ) index;

Expands the view at the given index. This calls [self expandStackedViewAtIndex:index animate:[[self class] usesAnimation]].

Parameter Descriptions
index
The index.

expandStackedViewAtIndex:animate:

Expands the view at the given index.
- ( 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.

Parameter Descriptions
index
The index.
animateFlag
Whether to animate.

frameForDisclosureControlAtIndex:

Returns the frame for an item's disclosure control.
- ( NSRect ) frameForDisclosureControlAtIndex:
        (int ) index;

Returns the frame for the disclosure control of the item with the given index.

Parameter Descriptions
index
The index.
method result
The frame for an item's disclosure control.

frameForLabelBarAtIndex:

Returns the frame for an item's label bar.
- ( NSRect ) frameForLabelBarAtIndex:
        (int ) index;

Returns the frame for the label bar of the item with the given index.

Parameter Descriptions
index
The index.
method result
The frame for an item's label bar.

frameForLabelTextAtIndex:

Returns the frame for an item's label text.
- ( 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.

Parameter Descriptions
index
The index.
method result
The frame for an item's label text.

indexOfStackedView:

Returns the index of the given view.
- ( 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.

Parameter Descriptions
view
The view.
method result
The index, or -1 if the given view is not managed by the receiver.

initWithFrame:

Initializes an instance.
- ( 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.

Parameter Descriptions
frame
The frame rectangle for the view.
method result
The initialized instance.

insertStackedView:atIndex:withLabel:

Inserts the given view into the receiver.
- ( 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.

Parameter Descriptions
view
The view.
index
The index.
label
The label for the new view.
method result
The MOViewListViewItem that was created.

insertViewListViewItem:atIndex:

Inserts a new MOViewListViewItem into the receiver.
- ( 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.

Parameter Descriptions
item
The new item.
index
The index.

invalidateLayoutStartingWithStackedViewAtIndex:

Invalidates layout of subviews and recevier.
- ( 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.

Parameter Descriptions
index
The index.

isLayoutDisabled

Returns whether the receiver will pend any necessary layout.
- ( BOOL ) isLayoutDisabled;

Returns whether the receiver will pend any necessary layout. This basically returns whether -disableLayout has been called more times than -enableLayout.

method result
Whether the receiver will pend any necessary layout.

labelBarAppearance

Returns the receiver's label bar appearance.
- ( MOViewListViewLabelBarAppearance ) labelBarAppearance;

Returns the receiver's label bar appearance.

Parameter Descriptions
scheme
The appearance type constant.

labelFont

Returns the receiver's label font.
- ( NSFont *) labelFont;

Returns the receiver's label font. MOViewListView uses the system font. The size is determined by the controlSize.

method result
The font.

labelHeight

Returns the receiver's label height.
- ( float ) labelHeight;

Returns the receiver's label height. MOViewListView calculates this from the labelFont.

method result
The height of label bars.

numberOfViewListViewItems

Returns the number of MOViewListViewItems the receiver has.
- ( 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).

method result
The number of items.

removeViewListViewItemAtIndex:

Removes a MOViewListViewItem from the receiver.
- ( 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.

Parameter Descriptions
index
The index.

setBackgroundColor:

Sets the receiver's background color.
- ( 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.

Parameter Descriptions
color
The background color.

setControlSize:

Sets the receiver's control size.
- ( void ) setControlSize:
        (NSControlSize ) size;

Sets the receiver's control size.

Parameter Descriptions
size
The control size.

setDelegate:

Sets the receiver's delegate.
- ( void ) setDelegate:
        (id ) delegate;

Sets the receiver's delegate.

Parameter Descriptions
delegate
The delegate.

setDropItemIndex:dropOperation:

Method to allow delegate to reposition a drop.
- ( 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.

Parameter Descriptions
itemIndex
The item index.
op
The drop operation.

setLabelBarAppearance:

Sets the receiver's label bar appearance.
- ( void ) setLabelBarAppearance:
        (MOViewListViewLabelBarAppearance ) labelBarAppearance;

Sets the receiver's label bar appearance.

Parameter Descriptions
scheme
The appearance type constant.

setNeedsDisplayForLabelBarAtIndex:

Invalidates the display of the label for the item at the given index.
- ( 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.

Parameter Descriptions
index
The index.

setUsesAnimation:

Returns whether animation is used for collapsing and expanding.
See Also:
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.

method result
Whether to animate.

setUsesAnimation:((BOOL))

Sets whether animation is used for collapsing and expanding.
+ ( 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.

Parameter Descriptions
flag
Whether to animate.

setViewListLabelViewClass:

Sets the MOViewListLabelView subclass used for labels in this instance.
- ( 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.

Parameter Descriptions
theClass
The class.

shouldCollapseViewListViewItem:

Consults the delegate to determine if the given item can collapse.
- ( 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.

Parameter Descriptions
item
The item that wants to collapse.
method result
Whether the item should be allowed to collapse.

shouldExpandViewListViewItem:

Consults the delegate to determine if the given item can expand.
- ( 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.

Parameter Descriptions
item
The item that wants to expand.
method result
Whether the item should be allowed to expand.

sizeToFit

Does any needed layout and makes sure the receiver is the right size.
- ( 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:

Toggles the collapsed state of the view at the given index.
- ( void ) toggleStackedViewAtIndex:
        (int ) index;

Toggles the collapsed state of the view at the given index. This calls [self toggleStackedViewAtIndex:index animate:[[self class] usesAnimation]].

Parameter Descriptions
index
The index.

toggleStackedViewAtIndex:animate:

Toggles the collapsed state of the view at the given index.
- ( void ) toggleStackedViewAtIndex:
        (int ) index animate:
        (BOOL ) animateFlag;

Toggles the collapsed state of the view at the given index. The animateFlag indicates whether to animate.

Parameter Descriptions
index
The index.
animateFlag
Whether to animate.

usesAnimation

Returns whether animation is used for collapsing and expanding.
See Also:
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.


viewListLabelViewClass

Returns the MOViewListLabelView subclass used for labels in this instance.
- ( 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.

method result
The class.

viewListViewItemAtIndex:

Returns the MOViewListViewItem at the given index.
- ( MOViewListViewItem *) viewListViewItemAtIndex:
        (int ) index;

Returns the MOViewListViewItem at the given index.

Parameter Descriptions
index
The index.
method result
The item.

viewListViewItems

Returns the receiver's array of MOViewListViewItems.
- ( NSArray *) viewListViewItems;

Returns the receiver's array of MOViewListViewItems.

method result
The array of items.

(Last Updated 3/20/2005)