[wxWidgets.git] / contrib / src / gizmos / multicell.txt

These two classes make it easier to lay objects out on a screen.  The
first class is the wxMultiCellCanvas, which uses the wxFlexGridSizer
control, so it is subject to the same limitations of that control.  Among
them is the fact that if the window is resized smaller than the control,
then some of the objects will be obscured by the window edge.

The second class is the wxMultiCellSizer, which is significantly more
powerful than the wxMultiCell Canvas.  This control supports resizing of
objects on the fly, objects spanning cells, etc.

Use the wxMultiCellCanvas when you have a simple layout which won't resize
and doesn't have any unusual requirements.  Use the wxMultiCellSizer when
your needs are greater


wxMultiCellCanvas
=================

The wxMultiCellCanvas class allows you to add objects to a wxFlexGridSizer
by specifying a row and a column location.  When all objects have been
added, you need to call a member function CalculateConstraints(), which
will insert the objects into the wxFlexGridSizer.  If there are empty
cells the canvas will insert empty wxStaticText objects as placeholders.

Upon creation of the canvas the size of the canvas needs to be specified.
Attempting to insert a cell outside those limits will cause an assertion
error.

When adding cells, the cell locations are specified as a row,column
location, both being zero-based.  0,0 is the upper left corner of the
canvas.


wxMultiCellSizer
================

The wxMultiCellSizer class manages a collection of child windows in a way
similar to that of data stored in a spreadsheet.  A multicell canvas is a
two-dimensional array of cells with an origin of (0,0) in the upper-left
corner.  Windows are added to a multicell sizer by first creating a
wxMultiCellItemHandle object which specifies a starting cell and,
optionally, a number of contiguous columns, rows, or a combination
thereof, and then adding it to the sizer.

This class bases the initial cell sizes on the minimum sizes returned by
each child window of the sizer.  You can override the minimum sizes
provided by the wxWindows Class Library by doing either of the following:

 o Specifying the size when creating the wxMultiCellItemHandle object
 o Creating a derived class and implementing a CalcMin function

The wxMultiCellItemHandle must be passed the row and column of the item,
at a minimum.  Optionally, more information can be passed:

 int                    row             Row position, zero based
 int                    column          Column position, zero based
 int                    height          Number of rows this cell will occupy, default is 1
 int                    width           Number of columns this cell will occupy, default is 1

                                        Note that if the height or width is greater than one that
                                        dimension is assumed to be resizable because it is spanning
                                        multiple cells.

 wxSize                 minSize         Minimum size of the object.
 wxResizable            Style           Is this object resizable, and if so, how.  Allowable styles are:
                                                wxNOT_RESIZABLE
                                                wxHORIZENTAL_RESIZABLE
                                                wxVERTICAL_RESIZABLE
                                                wxRESIZABLE
 wxSize                 weight          If this is a resizable object, the weight applied to the specific dimension.
                                        This is useful if you have several resizable rows and/or columns, and you want
                                        one to get more of the available space than the others.
 int                    align           This is a wxAlignment value, it is an integer so you can 'or multiple
                                        values together.  The acceptable values are:
                                                wxALIGN_NOT
                                                wxALIGN_CENTER_HORIZONTAL
                                                wxALIGN_CENTRE_HORIZONTAL
                                                wxALIGN_LEFT
                                                wxALIGN_TOP
                                                wxALIGN_RIGHT
                                                wxALIGN_BOTTOM
                                                wxALIGN_CENTER_VERTICAL
                                                wxALIGN_CENTRE_VERTICAL
                                                wxALIGN_CENTER
                                                wxALIGN_CENTRE
                        Note that some combinations of these make no sense, for example wxALIGN_LEFT | wxALIGN_RIGHT.
                        See the definition of wxAlignment for more information


Other functions are:

void    RecalcSizes()           Should not be called by the user, needed by the wxSizer class
wxSize  CalcMin()               Should not be called by the user, needed by the wxSizer class
bool    SetDefaultCellSize      Set the default cell size of an empty cell
bool    SetColumnWidth          Set the width of a column, optionally specifying it as resizable
bool    SetRowHeight            Set the height of a row, optionally specifying it as resizable

Sometimes it can be very confusing to determine the relationship between rows, columns, and
which ones are resizable or not.  Three functions are supplied to make this easier:

bool    EnableGridLines(wxWindow *win); Call this to either enable or disable the grid lines.
                                        Pass the window the sizer is on, or NULL to disable.
                                        Currently the window is not used, but it may be in the
                                        future.
bool    SetGridPen(wxPen *pen);         Set the pen color, the default pen color is red
void    OnPaint(wxDC& dc);              Call this from an OnPaint function associated with the
                                        window the sizer is attached to.  See the example program
                                        mtest.cpp for specific details on how to do this.


Files                   Description
=====                   ===========
docs.txt                This file

// wxMultiCellCanvas and wxMultiCellSizer
makefile                Makefile for the MingW32 compiler
multicell.cpp           Class source code file
multicell.h             Class header file

//Sample
mtest.cpp               Example program, demonstrates both classes
mtest.rc
mtest.gif
makefile

Acknowledgments
===============
This was inspired by the gbsizer class written by Alex Andruschak, and the IMultiCellCanvas
class in the IBM Class Libraries in the VisualeAge C++ compilers.
Commit	Line	Data
58580a7e JS	1	These two classes make it easier to lay objects out on a screen. The
	2	first class is the wxMultiCellCanvas, which uses the wxFlexGridSizer
	3	control, so it is subject to the same limitations of that control. Among
	4	them is the fact that if the window is resized smaller than the control,
	5	then some of the objects will be obscured by the window edge.
	6
	7	The second class is the wxMultiCellSizer, which is significantly more
	8	powerful than the wxMultiCell Canvas. This control supports resizing of
	9	objects on the fly, objects spanning cells, etc.
	10
	11	Use the wxMultiCellCanvas when you have a simple layout which won't resize
	12	and doesn't have any unusual requirements. Use the wxMultiCellSizer when
	13	your needs are greater
	14
	15
	16	wxMultiCellCanvas
	17	=================
	18
	19	The wxMultiCellCanvas class allows you to add objects to a wxFlexGridSizer
	20	by specifying a row and a column location. When all objects have been
	21	added, you need to call a member function CalculateConstraints(), which
	22	will insert the objects into the wxFlexGridSizer. If there are empty
	23	cells the canvas will insert empty wxStaticText objects as placeholders.
	24
	25	Upon creation of the canvas the size of the canvas needs to be specified.
	26	Attempting to insert a cell outside those limits will cause an assertion
	27	error.
	28
	29	When adding cells, the cell locations are specified as a row,column
	30	location, both being zero-based. 0,0 is the upper left corner of the
	31	canvas.
	32
	33
	34	wxMultiCellSizer
	35	================
	36
	37	The wxMultiCellSizer class manages a collection of child windows in a way
	38	similar to that of data stored in a spreadsheet. A multicell canvas is a
	39	two-dimensional array of cells with an origin of (0,0) in the upper-left
	40	corner. Windows are added to a multicell sizer by first creating a
	41	wxMultiCellItemHandle object which specifies a starting cell and,
	42	optionally, a number of contiguous columns, rows, or a combination
	43	thereof, and then adding it to the sizer.
	44
	45	This class bases the initial cell sizes on the minimum sizes returned by
	46	each child window of the sizer. You can override the minimum sizes
	47	provided by the wxWindows Class Library by doing either of the following:
	48
	49	o Specifying the size when creating the wxMultiCellItemHandle object
	50	o Creating a derived class and implementing a CalcMin function
	51
	52	The wxMultiCellItemHandle must be passed the row and column of the item,
	53	at a minimum. Optionally, more information can be passed:
	54
	55	int row Row position, zero based
	56	int column Column position, zero based
	57	int height Number of rows this cell will occupy, default is 1
	58	int width Number of columns this cell will occupy, default is 1
	59
	60	Note that if the height or width is greater than one that
	61	dimension is assumed to be resizable because it is spanning
	62	multiple cells.
	63
	64	wxSize minSize Minimum size of the object.
65	wxResizable Style Is this object resizable, and if so, how. Allowable styles are:
66	wxNOT_RESIZABLE
67	wxHORIZENTAL_RESIZABLE
68	wxVERTICAL_RESIZABLE
69	wxRESIZABLE
70	wxSize weight If this is a resizable object, the weight applied to the specific dimension.
71	This is useful if you have several resizable rows and/or columns, and you want
72	one to get more of the available space than the others.
73	int align This is a wxAlignment value, it is an integer so you can 'or multiple
74	values together. The acceptable values are:
75	wxALIGN_NOT
76	wxALIGN_CENTER_HORIZONTAL
77	wxALIGN_CENTRE_HORIZONTAL
78	wxALIGN_LEFT
79	wxALIGN_TOP
80	wxALIGN_RIGHT
81	wxALIGN_BOTTOM
82	wxALIGN_CENTER_VERTICAL
83	wxALIGN_CENTRE_VERTICAL
84	wxALIGN_CENTER
85	wxALIGN_CENTRE
86	Note that some combinations of these make no sense, for example wxALIGN_LEFT \| wxALIGN_RIGHT.
87	See the definition of wxAlignment for more information
88
89
90	Other functions are:
91
92	void RecalcSizes() Should not be called by the user, needed by the wxSizer class
93	wxSize CalcMin() Should not be called by the user, needed by the wxSizer class
94	bool SetDefaultCellSize Set the default cell size of an empty cell
95	bool SetColumnWidth Set the width of a column, optionally specifying it as resizable
96	bool SetRowHeight Set the height of a row, optionally specifying it as resizable
97
98	Sometimes it can be very confusing to determine the relationship between rows, columns, and
99	which ones are resizable or not. Three functions are supplied to make this easier:
100
101	bool EnableGridLines(wxWindow *win); Call this to either enable or disable the grid lines.
102	Pass the window the sizer is on, or NULL to disable.
103	Currently the window is not used, but it may be in the
104	future.
105	bool SetGridPen(wxPen *pen); Set the pen color, the default pen color is red
106	void OnPaint(wxDC& dc); Call this from an OnPaint function associated with the
107	window the sizer is attached to. See the example program
108	mtest.cpp for specific details on how to do this.
109
110
111	Files Description
112	===== ===========
113	docs.txt This file
114
115	// wxMultiCellCanvas and wxMultiCellSizer
116	makefile Makefile for the MingW32 compiler
117	multicell.cpp Class source code file
118	multicell.h Class header file
119
120	//Sample
121	mtest.cpp Example program, demonstrates both classes
122	mtest.rc
123	mtest.gif
124	makefile
125
126	Acknowledgments
127	===============
128	This was inspired by the gbsizer class written by Alex Andruschak, and the IMultiCellCanvas
129	class in the IBM Class Libraries in the VisualeAge C++ compilers.
130