multicell.txt

Wxpython Implemented on Windows CE, Source code

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.