CGrid

Heritage

Description

Usage

Enums

Adjust

Placement

Policy

Protected Data Members

Public Methods

Destructor and Initializer Methods

Inherited Drawing Methods

Clipping Methods

Placement Policy Methods

Visibility Methods

Snapping Methods

Removal Functions

Placement Methods

Cell Get Operations

Inherited Sizing Methods

Sizing (Varies Among Grid Types)

Mouse Event Methods (All Inherited)

Suspension Methods

Protected Methods

Constructor Methods

Other Methods

Heritage

Subclasses: CFixedGrid, CVariableGrid

Description

A CGrid in its abstract sense is simply an area of the screen that has been divided into rows and columns. These are the only assumptions made at the CGrid level. Each view object contained in the grid is placed inside an individual grid cell. A cell is a rectangular location comprised of the intersection of a certain row with a certain column. Objects inserted into cells can either be clipped to their cells or simply placed inside. If the objects are not clipped and are too big to fit into their cells they overlap from cell to cell. An object can be placed inside a cell relative to its top left, top right, bottom left, or bottom right corner.

When rows and columns are being counted in a grid, the top-most row and the left-most column are both counted as zero (0); thus, counting proceeds from zero.

Depending on its attributes, a grid can have the following characteristics:

• The lines in the grid and/or the entire grid can be either visible or invisible.

• Objects in the grid can be snapped into a cell as the user moves/resized them.

• Objects can be clipped to their cells.

• Cells can be resized to enclose the largest object.

• An item inserted into a grid snaps to a certain corner of its cell and can be centered within the cell.

• The grid can be sized either by adding and removing cells or by sizing the cells.

Usage

For any view created using a grid as its enclosure, you must call one of the placement methods to indicate the cell in which it belongs.

Enums

Adjust

Placement

Policy

Protected Data Members

Public Methods

virtual ~CGrid(void);

The destructor. It cleans up after the grid and deletes any views nested within it.

BOOLEAN IGrid(BOOLEAN isClipping 	= FALSE,
	PLACEMENT thePlacement 	= TOPLEFT,
	BOOLEAN isGridVisible 	= FALSE,
	POLICY theSizingPolicy	= ADJUSTCellSize,
	BOOLEAN isVisible 	= TRUE,
	GLUETYPE theGlue 	= NULLSTICKY);

The initializer. The isClipping parameter takes a BOOLEAN value indicating whether the items placed in the grid are clipped to their cells. By default, clipping is turned off. thePlacement specifies the orientation for placing items in their cells-in the top left corner by default. isGridVisible sets whether the lines of the grid are visible or not. theSizingPolicy takes a value indicating one of the two different sizing policies for grids: ADJUSTCellSize (the default) or ADJUSTCellNumber. The isVisible parameter sets the visibility state for the entire grid object (as opposed to isGridVisible, which pertains to the horizontal and vertical lines within the grid). Finally, this initializer takes a glue type.

virtual void DoDraw(
	const CRect& theClippingRegion = MAXRect);

A method that is inherited from the CSubview level. Its behavior is the same as that of CSubview's DoDraw. It takes care of any drawing the grid must do and draws all of the its subviews, ensuring that all of the subviews are clipped to the grid. theClippingRegion is the part of the grid that needs to be refreshed and is in global, window-relative coordinates; if it is set to MAXRect, the entire object is drawn.

virtual void Draw(const CRect& theClippingRegion);

Takes care of any drawing the grid must do. theClippingRegion is the part of the grid that needs to be refreshed.

virtual void SetClipping(BOOLEAN isClipping);

Sets the state of the ItIsClipping data member to TRUE or FALSE, which determines whether items in the grid clip to their cells.

virtual BOOLEAN IsClipping(void);

Returns TRUE or FALSE, indicating whether the objects contained in the grid are clipped to their cells.

virtual void SetPlacement(PLACEMENT thePlacement);

Sets the placement policy for the grid; that is, which of the four cell corners is to be used as the orientation for placing an item inside a cell.

virtual PLACEMENT GetPlacement(void) const;

Returns the current placement policy of the grid-top left, top right, bottom left, or bottom right.

virtual void ShowGrid(void);

Reveals the row and column lines of the grid.

virtual void HideGrid(void);

Makes the row and column lines of the grid invisible.

virtual BOOLEAN IsGridVisible(void);

Returns a BOOLEAN value indicating whether the row and column lines of the grid are visible.

virtual BOOLEAN DrawsVertical(void) const;

Returns TRUE if the grid draws vertical grid lines, FALSE if not.

virtual BOOLEAN DrawsHorizontal(void) const;

Returns TRUE if the grid draws horizontal grid lines, FALSE if not.

virtual void SetVerticalDrawing(BOOLEAN theSetting);

Requests that the grid draw or not draw vertical grid lines, as specified by theSetting.

virtual void SetHorizontalDrawing(
	BOOLEAN theSetting);

Requests that the grid draw or not draw horizontal grid lines, as specified by theSetting.

virtual void SetSnapping(BOOLEAN IsSnapping);

Turns on the snapping functionality. Setting snapping causes the behavior of the objects being dragged to snap to the closest cell.

virtual BOOLEAN IsSnapping(void) const;

Returns the state of snapping for the grid.

virtual CView* Remove(int theRow, int theColumn);

Removes an item from the grid when you give it a row number and a column number for the item. It returns a pointer to the view that was removed; if no view is found in the given row and column coordinate, this method returns NULL.

virtual BOOLEAN Remove(const CView* theView);

Removes the specified view, theView, from the grid and returns a BOOLEAN value of TRUE if it is successful.

void RemoveSubview(const CView *theView);

Removes a view, theView, from the grid's list of views.

virtual void Insert(CView* theView, int theRow, 
	int theColumn);

Inserts the designated view into the given row and column of the grid. It takes a pointer to the view that is to be inserted, a row number, and a column number. The coordinates of the view are adjusted so that it can be placed into the cell.

virtual void Insert(CView* theView);

Takes a pointer to a view, examines the view's coordinates, and calculates the row and column of the grid into which it fits best.

virtual CView* Replace(CView* theView, int theRow, int theColumn);

Takes a pointer to a view and places it inside the cell that is located at the given row and column, removing any object already occupying the cell and returning a pointer to the removed object.

virtual CView* Replace(CView* theView);

Takes a pointer to a view, examines the view's coordinates, and calculates the row and column of the grid into which it fits best. It removes any object that is already occupying the cell and returns a pointer to the removed object.

virtual CView* GetContents(int theRow, int theCol) const;

Gets the contents of the cell (a view) located at the given row and column and returns a pointer to the view. If the cell has no contents, this method returns NULL.

virtual CView* GetContents(CPoint theLocation) const;

Gets the contents of the cell (a view) at theLocation, a coordinate that is local to the grid. This method returns a pointer to the view. If the cell has no contents, this method returns NULL.

virtual int GetNumRows(void) const;

Returns the number of rows in the grid.

virtual int GetNumCols(void) const;

Returns the number of columns in the grid.

virtual void GetPosition(const CView* theView, 
	int *theRow, int *theCol) const;

Gets the position of a certain view. It takes a pointer to that view (location) and it takes two pointers to some integers that are filled in by GetPosition, the row and the column. After this method is called, the row and the column designated by the integers will contain the location of that view, if the view happens to be in the grid. If the view is not contained in the grid, then the row and the column are set to -1.

virtual void GetPosition(const CRect& theView,
	int *theRow, int *theCol) const;

Gets the grid position of a certain region. You pass it a rectangular area (set of coordinates) relative to the grid and ask it which row and column this rectangular area belongs to.

virtual CRect GetCellSize(int theRow, int theCol) const = NULL;

Gets the size of the cell located at the given row and column. It returns a CRect, which consists of that cell's coordinates, which are local to the grid.

virtual int GetRow(UNITS theVerticalLocation)
	const = NULL;

Gets a row of the grid. It takes a vertical location in coordinates relative to the grid and returns an integer indicating what row contains theVerticalLocation. If theVerticalLocation is not in a row, this method returns a -1.

virtual int GetCol(UNITS theHorizontalLocation)
	const = NULL;

Gets a column of the grid. It takes a horizontal location in coordinates relative to the grid. It returns an integer indicating which column contains theHorizontalLocation. If theHorizontalLocation is not in a column, this method returns a -1.

virtual BOOLEAN Validate(int theRow, int theCol);

Takes a row and column and returns TRUE or FALSE, depending on whether the given row and column contains a valid grid cell. Validate checks the row and column to verify that they are valid in the grid. This method is called internally whenever a new item is being inserted into the grid. This method can be overridden. One possibility is to override Validate so that it creates a valid row and column to accommodate the inserted object if it does not find them and returns TRUE.

virtual void Size(const CRect& theNewSize);

Sizes the grid according to the coordinates of theNewSize. The sizing of the grid varies according to the sizing policy that has been set. If the sizing policy, which set by SetSizingPolicy, is ADJUSTCellSize, sizing events are handled by resizing the cells and not by changing the number of cells. If the sizing policy is ADJUSTCellNumber, sizing events are handled by adding or removing cells and not changing the size of the existing cells.

The reset region can be in a different location and have completely different dimensions-a new width or a new height. The coordinates of the region, theNewSize, are relative to the enclosure-like the coordinates of the region that is passed in when a view is instantiated.

virtual void SizeCell(UNITS theCellWidth, 
	UNITS theCellHeight) = 0;

Resizes each cell of the grid according to the given width and height, which has the effect of enlarging or reducing the size of the entire grid.

virtual void SetNumCells(int theNumberOfColumns,
	int theNumberOfRows, 
	BOOLEAN theGridWillResize = TRUE);

If theGridWillResize is TRUE, SetNumCells enlarges or reduces the size of the entire grid by giving it the specified number of columns and rows.

If theGridWillResize is FALSE, the overall size of the grid does not change. In this case, the sizes of the cells are adjusted to fit theNumberOfRows and theNumberOfColumns.

virtual void AdjustCells(ADJUST theAdjustment);

Takes the typedef ADJUST, which can have a value of either MAXIMIZE or MINIMIZE. MAXIMIZE goes through all of the objects contained in the grid, finds the largest one, and makes all of the grid cells that size. MINIMIZE goes through all of the objects contained in the grid, finds the smallest one, and makes all of the grid cells that size.

virtual UNITS GetWidth(int theColumn = 0) 
	const = NULL;

Returns the width, in logical units, of the specified column; the left-most column takes the number zero (0).

virtual UNITS GetHeight(int theRow = 0) const = NULL;

Returns the height, in logical units, of the specified row; the top-most row takes the number zero (0).

virtual POLICY GetSizingPolicy(void) const;

Gets the sizing policy for the grid; that is, whether cell size is adjusted as the grid is made larger/smaller or whether cell size remains constant while cells are added or removed.

virtual void SetSizingPolicy(POLICY thePolicy);

Sets the sizing policy for the grid; that is, whether cell size will be adjusted as the grid is made larger/smaller or whether cell size will remain constant while cells are added or removed. This method takes a value of either ADJUSTCellSize or ADJUSTCellNumber.

virtual void SetPlacementOffset(const CPoint& theNewPlacementOffset);

Sets the placement offset, which is used in conjunction with the placement policy to place items, as shown here:

virtual CPoint GetPlacementOffset(void);

Returns the placement offset.

Mouse events are passed directly to the view at the location where the event occurs. Each of the following methods has a theButton argument that specifies which mouse button is used and can have the values 0 (left), 1 (middle), or 2 (right). By default, neither the Shift key nor the Control key is used in conjunction with the mouse button.

virtual void MouseDouble(CPoint theLocation,
	short theButton 	= 0,
	BOOLEAN isShiftKey 	= FALSE, 
	BOOLEAN isControlKey 	= FALSE);

When the user double clicks a mouse button over a grid containing local coordinate theLocation, the grid receives and handles this event.

virtual void MouseDown(CPoint theLocation,
	short theButton 	= 0,
	BOOLEAN isShiftKey	= FALSE, 
	BOOLEAN isControlKey	= FALSE);

When the user presses down a mouse button over a grid containing local coordinate theLocation, the grid receives and handles this event.

virtual void MouseMove(CPoint theLocation,
	short theButton 	= 0,
	BOOLEAN isShiftKey	= FALSE, 
	BOOLEAN isControlKey	= FALSE);

When the user moves the mouse over a grid containing local coordinate theLocation, the grid receives and handles this event, whether the mouse button is down or not.

virtual void MouseUp(CPoint theLocation,
	short theButton 	= 0,
	BOOLEAN isShiftKey	= FALSE, 
	BOOLEAN isControlKey	= FALSE);

When the user releases a mouse button over a grid containing local coordinate theLocation, the grid receives and handles this event. This event is not necessarily preceded by a MouseDown or MouseMove event because those button actions may have taken place outside the grid.

virtual CView* FindEventTarget(const CPoint& theLocation) const;

A method that is called to find the target of a mouse event within a subview. This virtual method is defined to return the deepest subview at the global coordinates of theLocation. CGrid overrides this method in order to trap all events regardless of the subviews it contains or to change the event targeting algorithm. For example, a list box contains many subviews (text items). When you click on a text item inside a grid, the event does not go to the view. Instead, the grid traps the event by returning this (itself) as the target for the mouse events received. Then, it treats the mouse events as necessary, without sending them on to its subviews.

virtual CView* FindHitView(const CPoint& theLocation) const;

Overrides the CView method of the same name, which returns the actual view that should receive mouse events. It returns the grid's wire frame if the grid is being sized or dragged.

void Suspend(void);

Suspends updates to the grid. You should use this member function to avoid needless updates when making more than one modification to a grid.

void Resume(void);

Resume updates to the grid. You should call DoDraw to make sure that the grid's on-screen representation is current.

BOOLEAN IsSuspended(void) const;

Returns TRUE if the grid is suspended, FALSE otherwise.

virtual void PlaceView(CView* theView, int theRow, int theCol);

Takes a view and the row and column to which the view belongs and ensures that this view has been placed correctly within the cell. This method is called internally when a view is inserted or replaced.

virtual void DoPlaceView(void);

Iterates through the objects contained in the grid, calling PlaceView for each one. This method is called internally when a grid is sized or moved.

virtual void DoClear(void);

Deletes all cells.

CGrid(CSubview* theEnclosure, const CRect& theRegion);

A constructor. theEnclosure is a pointer to the subview that will contain the grid. theRegion is a coordinate location, local to the enclosure, that is used to place the grid.

CGrid(const CGrid& theGrid);

A copy constructor that duplicates the attributes, but not the contents, of a grid. That is, it copies the grid but does not do a deep copy of the objects it contains.

CGrid& operator=(const CGrid& theGrid);

An assignment operator that duplicates the attributes, but not the contents, of a grid. That is, it copies the grid but does not make a deep copy of the objects it contains.

void SetDragPoint(const CPoint& theLocation);

When an object is being dragged within a grid, sets the point where the object was first grabbed in order to implement grid-snapping.

void ResetCell(CView* theView, int theNewRow=-1, 
	int theNewCol=-1);

When an object is moved to a new cell within a grid, resets the cell to ensure it has the coordinates of its new location.

CView* GetHitItem(CPoint theLocation) const;

An internal method that is used for snapping. Given a certain location that is local to the grid's coordinates, it returns the item at that grid location. This method is similar to methods for finding subviews at the CSubview level.