]> git.saurik.com Git - wxWidgets.git/blame - contrib/src/gizmos/multicell.txt
Some more tests and mouse events for wxCanvas.
[wxWidgets.git] / contrib / src / gizmos / multicell.txt
CommitLineData
58580a7e
JS
1These two classes make it easier to lay objects out on a screen. The
2first class is the wxMultiCellCanvas, which uses the wxFlexGridSizer
3control, so it is subject to the same limitations of that control. Among
4them is the fact that if the window is resized smaller than the control,
5then some of the objects will be obscured by the window edge.
6
7The second class is the wxMultiCellSizer, which is significantly more
8powerful than the wxMultiCell Canvas. This control supports resizing of
9objects on the fly, objects spanning cells, etc.
10
11Use the wxMultiCellCanvas when you have a simple layout which won't resize
12and doesn't have any unusual requirements. Use the wxMultiCellSizer when
13your needs are greater
14
15
16wxMultiCellCanvas
17=================
18
19The wxMultiCellCanvas class allows you to add objects to a wxFlexGridSizer
20by specifying a row and a column location. When all objects have been
21added, you need to call a member function CalculateConstraints(), which
22will insert the objects into the wxFlexGridSizer. If there are empty
23cells the canvas will insert empty wxStaticText objects as placeholders.
24
25Upon creation of the canvas the size of the canvas needs to be specified.
26Attempting to insert a cell outside those limits will cause an assertion
27error.
28
29When adding cells, the cell locations are specified as a row,column
30location, both being zero-based. 0,0 is the upper left corner of the
31canvas.
32
33
34wxMultiCellSizer
35================
36
37The wxMultiCellSizer class manages a collection of child windows in a way
38similar to that of data stored in a spreadsheet. A multicell canvas is a
39two-dimensional array of cells with an origin of (0,0) in the upper-left
40corner. Windows are added to a multicell sizer by first creating a
41wxMultiCellItemHandle object which specifies a starting cell and,
42optionally, a number of contiguous columns, rows, or a combination
43thereof, and then adding it to the sizer.
44
45This class bases the initial cell sizes on the minimum sizes returned by
46each child window of the sizer. You can override the minimum sizes
47provided 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
52The wxMultiCellItemHandle must be passed the row and column of the item,
53at 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
90Other functions are:
91
92void RecalcSizes() Should not be called by the user, needed by the wxSizer class
93wxSize CalcMin() Should not be called by the user, needed by the wxSizer class
94bool SetDefaultCellSize Set the default cell size of an empty cell
95bool SetColumnWidth Set the width of a column, optionally specifying it as resizable
96bool SetRowHeight Set the height of a row, optionally specifying it as resizable
97
98Sometimes it can be very confusing to determine the relationship between rows, columns, and
99which ones are resizable or not. Three functions are supplied to make this easier:
100
101bool 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.
105bool SetGridPen(wxPen *pen); Set the pen color, the default pen color is red
106void 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
111Files Description
112===== ===========
113docs.txt This file
114
115// wxMultiCellCanvas and wxMultiCellSizer
116makefile Makefile for the MingW32 compiler
117multicell.cpp Class source code file
118multicell.h Class header file
119
120//Sample
121mtest.cpp Example program, demonstrates both classes
122mtest.rc
123mtest.gif
124makefile
125
126Acknowledgments
127===============
128This was inspired by the gbsizer class written by Alex Andruschak, and the IMultiCellCanvas
129class in the IBM Class Libraries in the VisualeAge C++ compilers.
130