interface/gbsizer.h

   1 /////////////////////////////////////////////////////////////////////////////
   2 // Name:        gbsizer.h
   3 // Purpose:     documentation for wxGBPosition class
   4 // Author:      wxWidgets team
   5 // RCS-ID:      $Id$
   6 // Licence:     wxWindows license
   7 /////////////////////////////////////////////////////////////////////////////
   8
   9 /**
  10     @class wxGBPosition
  11     @wxheader{gbsizer.h}
  12
  13     This class represents the position of an item in a virtual grid of
  14     rows and columns managed by a wxGridBagSizer.
  15
  16     @library{wxcore}
  17     @category{FIXME}
  18 */
  19 class wxGBPosition
  20 {
  21 public:
  22     //@{
  23     /**
  24         Construct a new wxGBPosition, optionally setting the row and column.
  25         The default is (0,0).
  26     */
  27     wxGBPosition();
  28         wxGBPosition(int row, int col);
  29     //@}
  30
  31     /**
  32         Get the current column value.
  33     */
  34     int GetCol();
  35
  36     /**
  37         Get the current row value.
  38     */
  39     int GetRow();
  40
  41     /**
  42         Set a new column value.
  43     */
  44     void SetCol(int col);
  45
  46     /**
  47         Set a new row value.
  48     */
  49     void SetRow(int row);
  50
  51     /**
  52         Is the wxGBPosition valid?  (An invalid wxGBPosition is (-1,-1). )
  53     */
  54     bool operator!(const wxGBPosition& p);
  55
  56     /**
  57         Compare equality of two wxGBPositions.
  58     */
  59     bool operator operator==(const wxGBPosition& p);
  60 };
  61
  62
  63 /**
  64     @class wxGridBagSizer
  65     @wxheader{gbsizer.h}
  66
  67     A wxSizer that can lay out items in a virtual grid
  68     like a wxFlexGridSizer but in this case
  69     explicit positioning of the items is allowed using
  70     wxGBPosition, and items can optionally span
  71     more than one row and/or column using wxGBSpan.
  72
  73     @library{wxcore}
  74     @category{winlayout}
  75 */
  76 class wxGridBagSizer : public wxFlexGridSizer
  77 {
  78 public:
  79     /**
  80         Constructor, with optional parameters to specify the gap between the
  81         rows and columns.
  82     */
  83     wxGridBagSizer(int vgap = 0, int hgap = 0);
  84
  85     //@{
  86     /**
  87         The Add methods return a valid pointer if the item was successfully placed at
  88         the
  89         given position, @NULL if something was already there.
  90     */
  91     wxSizerItem* Add(wxWindow* window, const wxGBPosition& pos,
  92                      const wxGBSpan& span = wxDefaultSpan,
  93                      int flag = 0,
  94                      int border = 0,
  95                      wxObject* userData = @NULL);
  96         wxSizerItem* Add(wxSizer* sizer, const wxGBPosition& pos,
  97                          const wxGBSpan& span = wxDefaultSpan,
  98                          int flag = 0,
  99                          int border = 0,
 100                          wxObject* userData = @NULL);
 101         wxSizerItem* Add(int width, int height,
 102                          const wxGBPosition& pos,
 103                          const wxGBSpan& span = wxDefaultSpan,
 104                          int flag = 0,
 105                          int border = 0,
 106                          wxObject* userData = @NULL);
 107         wxSizerItem* Add(wxGBSizerItem* item);
 108     //@}
 109
 110     /**
 111         Called when the managed size of the sizer is needed or when layout
 112         needs done.
 113     */
 114     wxSize CalcMin();
 115
 116     //@{
 117     /**
 118         Look at all items and see if any intersect (or would overlap) the given
 119         item. Returns @true if so, @false if there would be no overlap. If an
 120         excludeItem is given then it will not be checked for intersection, for
 121         example it may be the item we are checking the position of.
 122     */
 123     bool CheckForIntersection(wxGBSizerItem* item,
 124                               wxGBSizerItem* excludeItem = @NULL);
 125         bool CheckForIntersection(const wxGBPosition& pos,
 126                                   const wxGBSpan& span,
 127                                   wxGBSizerItem* excludeItem = @NULL);
 128     //@}
 129
 130     //@{
 131     /**
 132         Find the sizer item for the given window or subsizer, returns @NULL if
 133         not found. (non-recursive)
 134     */
 135     wxGBSizerItem* FindItem(wxWindow* window);
 136         wxGBSizerItem* FindItem(wxSizer* sizer);
 137     //@}
 138
 139     /**
 140         Return the sizer item located at the point given in pt, or @NULL if
 141         there is no item at that point. The (x,y) coordinates in pt correspond
 142         to the client coordinates of the window using the sizer for
 143         layout. (non-recursive)
 144     */
 145     wxGBSizerItem* FindItemAtPoint(const wxPoint& pt);
 146
 147     /**
 148         Return the sizer item for the given grid cell, or @NULL if there is no
 149         item at that position. (non-recursive)
 150     */
 151     wxGBSizerItem* FindItemAtPosition(const wxGBPosition& pos);
 152
 153     /**
 154         Return the sizer item that has a matching user data (it only compares
 155         pointer values) or @NULL if not found. (non-recursive)
 156     */
 157     wxGBSizerItem* FindItemWithData(const wxObject* userData);
 158
 159     /**
 160         Get the size of the specified cell, including hgap and vgap. Only
 161         valid after a Layout.
 162     */
 163     wxSize GetCellSize(int row, int col);
 164
 165     /**
 166         Get the size used for cells in the grid with no item.
 167     */
 168     wxSize GetEmptyCellSize();
 169
 170     //@{
 171     /**
 172         Get the grid position of the specified item.
 173     */
 174     wxGBPosition GetItemPosition(wxWindow* window);
 175         wxGBPosition GetItemPosition(wxSizer* sizer);
 176         wxGBPosition GetItemPosition(size_t index);
 177     //@}
 178
 179     //@{
 180     /**
 181         Get the row/col spanning of the specified item
 182     */
 183     wxGBSpan GetItemSpan(wxWindow* window);
 184         wxGBSpan GetItemSpan(wxSizer* sizer);
 185         wxGBSpan GetItemSpan(size_t index);
 186     //@}
 187
 188     /**
 189         Called when the managed size of the sizer is needed or when layout
 190         needs done.
 191     */
 192     void RecalcSizes();
 193
 194     /**
 195         Set the size used for cells in the grid with no item.
 196     */
 197     void SetEmptyCellSize(const wxSize& sz);
 198
 199     //@{
 200     /**
 201         Set the grid position of the specified item. Returns @true on success.
 202         If the move is not allowed (because an item is already there) then
 203         @false is returned.
 204     */
 205     bool SetItemPosition(wxWindow* window, const wxGBPosition& pos);
 206         bool SetItemPosition(wxSizer* sizer, const wxGBPosition& pos);
 207         bool SetItemPosition(size_t index, const wxGBPosition& pos);
 208     //@}
 209
 210     //@{
 211     /**
 212         Set the row/col spanning of the specified item. Returns @true on
 213         success. If the move is not allowed (because an item is already there)
 214         then @false is returned.
 215     */
 216     bool SetItemSpan(wxWindow* window, const wxGBSpan& span);
 217         bool SetItemSpan(wxSizer* sizer, const wxGBSpan& span);
 218         bool SetItemSpan(size_t index, const wxGBSpan& span);
 219     //@}
 220 };
 221
 222
 223 /**
 224     @class wxGBSizerItem
 225     @wxheader{gbsizer.h}
 226
 227     The wxGBSizerItem class is used by the
 228     wxGridBagSizer for tracking the items in the
 229     sizer. It adds grid position and spanning information to the normal
 230     wxSizerItem by adding
 231     wxGBPosition and wxGBSpan
 232     attrbibutes. Most of the time you will not need to use a
 233     wxGBSizerItem directly in your code, but there are a couple of cases
 234     where it is handy.
 235
 236     @library{wxcore}
 237     @category{FIXME}
 238 */
 239 class wxGBSizerItem : public wxSizerItem
 240 {
 241 public:
 242     //@{
 243     /**
 244         Construct a sizer item for tracking a subsizer.
 245     */
 246     wxGBSizerItem(int width, int height, const wxGBPosition& pos,
 247                   const wxGBSpan& span, int flag,
 248                   int border, wxObject* userData);
 249         wxGBSizerItem(wxWindow* window, const wxGBPosition& pos,
 250                       const wxGBSpan& span,
 251                       int flag, int border,
 252                       wxObject* userData);
 253         wxGBSizerItem(wxSizer* sizer, const wxGBPosition& pos,
 254                       const wxGBSpan& span,
 255                       int flag, int border,
 256                       wxObject* userData);
 257     //@}
 258
 259     /**
 260         Get the row and column of the endpoint of this item
 261     */
 262     void GetEndPos(int& row, int& col);
 263
 264     //@{
 265     /**
 266         Get the grid position of the item.
 267     */
 268     wxGBPosition GetPos();
 269         void GetPos(int& row, int& col);
 270     //@}
 271
 272     //@{
 273     /**
 274         Get the row and column spanning of the item.
 275     */
 276     wxGBSpan GetSpan();
 277         void GetSpan(int& rowspan, int& colspan);
 278     //@}
 279
 280     //@{
 281     /**
 282         Returns @true if the given pos/span would intersect with this item.
 283     */
 284     bool Intersects(const wxGBSizerItem& other);
 285         bool Intersects(const wxGBPosition& pos,
 286                         const wxGBSpan& span);
 287     //@}
 288
 289     /**
 290         If the item is already a member of a sizer then first ensure that
 291         there is no other item that would intersect with this one at the new
 292         position, then set the new position. Returns @true if the change is
 293         successful and after the next Layout the item will be moved.
 294     */
 295     bool SetPos(const wxGBPosition& pos);
 296
 297     /**
 298         If the item is already a member of a sizer then first ensure that
 299         there is no other item that would intersect with this one with its new
 300         spanning size, then set the new spanning. Returns @true if the change
 301         is successful and after the next Layout the item will be resized.
 302     */
 303     bool SetSpan(const wxGBSpan& span);
 304 };
 305
 306
 307 /**
 308     @class wxGBSpan
 309     @wxheader{gbsizer.h}
 310
 311     This class is used to hold the row and column spanning attributes of
 312     items in a wxGridBagSizer.
 313
 314     @library{wxcore}
 315     @category{FIXME}
 316 */
 317 class wxGBSpan
 318 {
 319 public:
 320     //@{
 321     /**
 322         Construct a new wxGBSpan, optionally setting the rowspan and colspan.
 323         The default is (1,1).  (Meaning that the item occupies one cell in
 324         each direction.
 325     */
 326     wxGBSpan();
 327         wxGBSpan(int rowspan, int colspan);
 328     //@}
 329
 330     /**
 331         Get the current colspan value.
 332     */
 333     int GetColspan();
 334
 335     /**
 336         Get the current rowspan value.
 337     */
 338     int GetRowspan();
 339
 340     /**
 341         Set a new colspan value.
 342     */
 343     void SetColspan(int colspan);
 344
 345     /**
 346         Set a new rowspan value.
 347     */
 348     void SetRowspan(int rowspan);
 349
 350     /**
 351         Is the wxGBSpan valid?  (An invalid wxGBSpan is (-1,-1). )
 352     */
 353     bool operator!(const wxGBSpan& o);
 354
 355     /**
 356         Compare equality of two wxGBSpans.
 357     */
 358     bool operator operator==(const wxGBSpan& o);
 359 };