CollectionView

NAME

DESCRIPTION

Item Collection

The list of items is stored in the instvar coll. This collection is specified in the constructor and can additionally be set with the method SetCollection. It is checked whether all items in the collection are instances of the class VObject. If objects are added to the collection later, then the client itself has to ensure that they are "kind of" VObject.
The CollectionView registers itself as an observer of the instvar coll which enables it to recalculate the layout whenever the collection changes.
Any type of Collection may be used. But if it is heavily modified and execution speed is important, then it is recommended to use an instance of the class OrdCollection because CollectionView very often accesses items in the collection by index.
The destructor of CollectionView always destroys the collection and the contained items. If the items are to be reused, then either single items or the whole collection should be saved before deleting the CollectionView.

Layout

The items of a CollectionView are arranged in columns and rows and the available space for an item is referred to as cell. The layout is determined by the flags eCVExpandCols and eCVExpandRows (see enum CollViewOptions) as well as the instvar cols and the instvar rows which all can be specified in the constructor. Three main types of layouts are possible:

1. number of columns is fixed; CollectionView grows vertically
        - either set the flag eCVExpandRows
        - or set the instvar rows to 0

2. number of rows is fixed; CollectionView grows horizontally
        - either set the flag eCVExpandCols
        - or set the instvar cols to 0

3. square layout; CollectionView grows both horizontally and vertically
        - either set the flags eCVExpandCols and eCVExpandRows
        - or set both the instvar cols and the instvar rows to 0

        1       4
        2       5
        3       6

Selecting Items

Single items can be selected with the left mouse button. While the mouse button is pressed and moved the method DoOnItem is continuously called. It forwards the message to the currently selected item, by default. When the mouse button is released the method DoSelect is called. The default implementation informs the next event handlers via the method Control about which item has been selected and whether a single or double click has been used.
The instvar selection stores the column and row numbers of the selected items. Clients may actively modify the current selection through the method SetSelection or the method SetNoSelection.

classes are rarely derived from CollectionView.
class CollectionView is often reused directly.
class CollectionView contains 36 methods.

owner of class:

nobody.

baseclasses:

View

subclasses:

Menu, MenuBar

flags:

CollViewOptions

INSTANCE VARIABLES

coll (protected Collection *)

contains the items displayed by the CollectionView. The objects in coll must be instances of the class VObject. coll is specified in the constructor and can be set through the method SetCollection as well. coll is returned by the method GetCollection. The destructor always destroys coll and all contained items whereas the method SetCollection allows to control whether to free the old collection.
The CollectionView registers itself as an observer of coll and automatically reformats its layout whenever coll is modified. See method DoObserve and method PrintOnWhenObserved.

cols (protected short)

contains the number of columns of the layout. cols is specified in the constructor. If the initial value is <= 0 or the flag eCVExpandCols (see enum CollViewOptions) is set, then cols is computed by the method Update, otherwise the number of columns is fixed.
See also instvar rows.

defaultItem (protected VObject *)

is the item returned by the method GetItem if there is no object at the specified cell. By default, it is an instance of the class VObject (!), but it can be set with the method SetDefaultItem.
The defaultItem is only important when the CollectionView has empty cells. If the layout consists of more than one column and more than one row, then the number of items in the instvar coll may be less than the number of available cells. In this case GetItem returns the defaultItem for the empty cells. If an item in such a layout is selected the client has to check whether it is the defaultItem.
Notice:

gap (protected Point)

is the thickness of the border around single items. In other words, the space between two items is twice the gap. The default value is zero but it can be modified with the method SetGap.

menu (protected Menu *)

is the popup menu of the CollectionView. By default, the menu is NULL and the method GetMenu returns the menu of the next handler. A specific menu can be set with the method SetMenu.

minExtent (protected Point)

contains the minimum size of a single cell. The default value is zero but it can be set with the method SetMinExtent. The actual extent of cells within a row or column is calculated by the method Update and depends on the minimum sizes of the VObjects in that row or column.

rows (protected short)

contains the number of rows of the layout. rows is specified in the constructor. If the initial value is <= 0 or the flag eCVExpandRows (see enum CollViewOptions) is set, then rows is computed by the method Update, otherwise the number of rows is fixed.
See also instvar cols.

selection (protected Rectangle)

contains the currently selected cells. selection is accessible through the method GetSelection. The respective components of the Rectangle do not contain geometrical information but are interpreted this way:

        origin.x    column number of first selected cell
        origin.y    row number of first selected cell
        extent.x    number of columns selected to the right
        extent.y    number of rows selected to the bottom

Whether there is a selection at all can be checked with GetSelection().IsEmpty(). Selected items can be accessed by passing the column and row number to the method GetItem.
If the left mouse button is pressed (see method DoLeftButtonDownCommand), then always only one cell can be selected. With the method SetSelection a client can select several cells concurrently. The method SetNoSelection clears the current selection.
See also method DoSelect.

xPos (protected short *)

is an array containing the horizontal position of each column. These values are calculated by the method Update and are used together with the instvar yPos for layout management, drawing the grid and finding items.

yPos (protected short *)

is an array containing the vertical position of each row. See instvar xPos.

INSTANCE METHOD LIST

client interface

CollectionView
GetCollection
SetCollection
SetDefaultItem

drawing

Draw
DrawGrid

implementation

~CollectionView

layout

GetMinSize
SetGap
SetMinExtent
SetOrigin
Update

mapping

GetItem
InvalidateItemRect
ItemPos
ItemRect
PointToItem

menus

DoCreateMenu
GetMenu
SetMenu

miscellaneous

Parts
PrintOn
PrintOnWhenObserved
ReadFrom

scrolling

ConstrainScroll
DoKeyCommand

selection

DoLeftButtonDownCommand
DoOnItem
DoSelect
DoSelect2
GetSelection
SetNoSelection
SetSelection

updating

DoObserve
Modified

CATEGORIES

Standard Views

FILES

declaration:

CollView.h

KNOWN PROBLEMS

The method DoLeftButtonDownCommand creates instances of the class CellSelector that does not allow to select more than one cell concurrently though the implementation of CollectionView would allow this.
Other problems: see method DoSelect, method Draw and method ReadFrom.  

HISTORY

Index

NAME

DESCRIPTION

INSTANCE VARIABLES

INSTANCE METHOD LIST

CATEGORIES

FILES

KNOWN PROBLEMS

HISTORY