Home

PegTable

Examples Index

Members Styles Signals (none)

Overview Derived from class PegWindow The PegTable class provides a container for displaying a matrix of KwikPeg objects derived from the PegThing base class. HTML programmers will recognize similarities to tables defined using that text markup language. Each table is divided into rows and columns which intersect to create cells. The number of rows and columns is defined when the PegTable object is created. By default the height of each row and the width of each column is 0 pixels. You can adjust any row height or column width once the table has been constructed. Row heights and columns widths can also be determined automatically as objects are added to the cells of the table. The cells of a table can be separated by gridlines. The default width of a gridline is the width of a window frame border. Hence, the gridline width will be 5 pixels, unless the frame border width has been altered by your KwikPeg Library configuration. The gridline width for a specific table can be adjusted dynamically using its member function SetGridWidth(). Padding can be added around a child object in its cell. The default padding is zero pixels. The cell padding width for a specific table can be adjusted dynamically using its member function SetCellPadding(). The cell padding width applies to all cells in the table. Child objects, called cell clients, are added to the table using the table's SetCellClient() member function. Any KwikPeg object derived from the PegThing base class can be a table cell client. An object added to the table can span multiple rows and/or columns, providing great flexibility in the final appearance of the table. When an object is added to the table, the row height and column width of the cell can be forced to change, if necessary, to adapt the cell to accommodate the object. This same row/column adjustment can be forced when an object that spans multiple rows/columns is added to the table. When constructing child objects for display in the table, your application will not control the object's screen position. That is determined by the location of the table window and the position within the table of the cell(s) containing the object. However, you must establish the object's dimensions before adding the object to the table. The table's row heights and column widths are determined by the dimensions of the child objects and their rowspan and columnspan attributes. After the table has been fully initialized and all cells populated, the Layout() member function should be called before the table is displayed. This function calculates the correct overall table size and positions each child object to fit within its specified table cells. In the simplest case, the height (width) of a row (column) will be the largest of either the maximum height (width) of all cell clients in that row (column) or the height (width) specified by you for that row (column). It can be helpful to understand the sizing algorithm used to adjust the width of rows or columns to accommodate a multicell object. Take a simple example in which one object spans three columns within one row. A column is considered of zero width if none of its cells has a cell client. If the spanning object exceeds the available width of the spanned columns, the zero width spanned column(s) will be grown as required to hold the object. If no zero width columns are spanned, all of the spanned columns are expanded to hold the object. In either case, the extra width needed to hold the object is distributed proportionately to each of the modified columns. A similar sizing strategy is applied for rowspanning objects. Once the size of all rows and columns is known, each child object is drawn centered horizontally and vertically within its cell or multicell rectangle. To build and display a table, proceed as follows: Construct the PegTable object, defining the maximum number of rows and columns for the table. Set row heights for any rows which you wish to be a specific minimum height. Set column widths for any columns which you wish to be a specific minimum width. Call the SetCellClient() function to install one or more cell clients into specific cells in the table. Call the table member function Layout() to compute the table dimensions. Add the table to a parent window or to the KwikPeg Presentation Manager's PegPresentationManager window. The PegTable class sizes the table so that all cells are displayed within its client area. To display a large table, add the PegTable object to another window which has scrolling enabled. The table can then be panned up, down, left or right within its parent's window. Notifications (signals) generated by the table's cell clients are passed unchanged to the table's parent. Hence, a window containing a PegTable object will receive event messages from the table's child objects just as though the objects were actual children of the parent window.

See Also

PegSpreadSheet

Styles

The PegTable class supports the following style flags:

The PegTable class also supports the following styles to position cell clients (objects) within table cells. These flags apply only when used with the SetCellClient function.

	Top of page

Members

Constructors:

	PegTable(SIGNED iLeft, SIGNED iTop,
	SIGNED iRows, SIGNED iCols)

This constructor creates a PegTable object with its top left corner located at (iLeft,iTop). The table will have iRows rows and iCols columns.

Public Functions:

	virtual void Draw(void)

The PegTable class overrides the Draw() function to draw the table in two stages. First the table gridlines are drawn, if needed. Then the table's mClip variable is modified to identify a pseudo "client area" for the first table cell and the cell client is drawn. The process is repeated until all cell clients have been drawn in their respective cells.

	virtual void DrawChildren(void)

The PegTable class overrides the DrawChildren() function to prevent child objects from drawing outside the cell area allocated to each cell client.

	virtual void DrawGrid(void)

This function draws the table gridlines.

	PegThing *GetCellClient(
	SIGNED iRow, SIGNED iCol)

This function returns a pointer to the cell client, a PegThing object, located at the indicated cell position. It returns NULL if no cell client is assigned to that cell.

	SIGNED GetCellPadding(void)
	{return miCellPad;}

This function returns the current cell padding width.

	SIGNED GetColumns(void)
	{return miCols;}

This inline function returns the number of columns in the table.

	SIGNED GetGridWidth(void)
	{return miGridWidth;}

This function returns the current width of a table gridline.

	BOOL GetRowCol(PegThing *pChild,
	SIGNED *pRow, SIGNED *pCol)

This function returns TRUE if the PegThing object referenced by pChild is a cell client, else FALSE.

If the PegThing object is a cell client, this function updates *pRow and *pCol to indicate the row and column position of the cell containing the object. If the cell client spans multiple cells, the upper left cell is used to identify the location of the cell client.

	SIGNED GetRows(void)
	{return miRows;}

This inline function returns the number of rows in the table.

	virtual void Layout(void)

This function computes the table's dimensions as described in the overview.

Call this function after the table's cell clients have been modified but before the table is drawn. Note that it is acceptable to modify cell clients after the table has been drawn, as long as this function is called after the modifications have been made.

Note that table row heights and column widths are never decreased. They may be increased if a new cell client which is added to the table is larger than the cell client(s) which it replaces.

	void Reconfigure(
	SIGNED iRows, SIGNED iCols,
	SIGNED iGridWidth, SIGNED iCellPadding)

This function recalculates row and column widths based on current entries. This function should be called after changing the cell clients.

	PegThing *RemoveCellClient(
	SIGNED iRow, SIGNED iCol)

This function removes the cell client from the indicated cell position. The cell client, a PegThing object, is not deleted. The table cell remains in place but no longer has any content for display.

The function returns a pointer to the removed PegThing object. The function returns NULL if the cell has no cell client (never assigned or already removed) or if the cell coordinates are invalid.

You can use this function to remove one cell client before installing another, thereby dynamically switching cell content.

	virtual void SetCellClient(
	SIGNED iRow, SIGNED iCol,
	PegThing *Child,
	SIGNED iRowSpan = 1,
	SIGNED iColSpan = 1,
	WORD wStyle = TCF_HCENTER | TCF_VCENTER)

This function is used to populate the cells of a table with cell clients. The KwikPeg object referenced by Child can be any object derived from the PegThing base class, including buttons, strings, prompts, textboxes, bitmaps, groups or even other windows.

The cell client is assigned to the cell at row iRow, column iCol. If the object spans multiple cells, the upper left cell is used to identify the cell location.

The default value for the rowspan and columnspan of a cell client is 1. Hence, unless otherwise specified, the cell client will occupy one table cell. If the RowSpan (ColSpan) parameter is >1, the cell client will span the number of rows (columns) specified by the parameter.

The wStyle parameter specifies the horizontal and vertical alignment of the cell client within the bounding cell(s). The default style centers the object vertically and horizontally within the bounding cell. If you specify the TCF_FORCEFIT style, the table will automatically adjust the row heights and column widths of the cell(s) occupied by the cell client to ensure that the unmodified object will fit within the region bounded by those cells.

The cell alignment TCF_xxxxxx styles operate only on the placement of the object within its bounding cell(s). The cell style flags do not affect the object. For example, a PegPrompt object has a series of styles that allow for left, center and right justification of its text. These text justification style flags are independent of the cell style flags. For example, you can right justify the text within the PegPrompt object while left justifying the object within its cell.

	virtual void SetCellPadding(SIGNED iPad)
	{miCellPad = iPad;}

This function sets the cell padding width to iPad pixels. The indicated cell padding will be added around each cell client in the table.

	virtual void SetColWidth(
	SIGNED iCol, SIGNED iWidth,
	BOOL bForce = FALSE)

This function sets the minimum width of column iCol to iWidth pixels. The initial width of all table columns is zero pixels.

By default, the column width cannot be decreased. However, if the bForce parameter is set to TRUE, the column width will unconditionally be set to iWidth pixels.

	void SetGridWidth(SIGNED iWidth = PEG_FRAME_WIDTH)

This function sets the width of a table gridline to iWidth pixels. If the gridline width is set to zero, the table will be drawn without gridlines. By default, a table is drawn with gridlines of the width specified by your KwikPeg configuration.

	virtual void SetRowHeight(
	SIGNED iRow, SIGNED iHeight,
	BOOL bForce = FALSE)

This function sets the minimum height of row iRow to iHeight pixels. The initial height of all table rows is zero pixels.

By default, the row height cannot be decreased. However, if the bForce parameter is set to TRUE, the row height will unconditionally be set to iHeight pixels.

	Top of page

Examples

The following example illustrates a PegTable object whose cells are populated with different types of cell clients.

Top of page

Home

Index

Copyright © 2000-2003