interface/wx/gbsizer.h

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