contrib/src/gizmos/multicell.txt

   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