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 licence
   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         Compare inequality of two wxGBPositions.
  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(wxGBSizerItem* item);
  97
  98     /**
  99         Adds a spacer to the given position.
 100         @a width and @a height specify the dimension of the spacer to be added.
 101
 102         @return A valid pointer if the spacer was successfully placed at the
 103                  given position, or @NULL if something was already there.
 104     */
 105     wxSizerItem* Add(int width, int height, const wxGBPosition& pos,
 106                      const wxGBSpan& span = wxDefaultSpan,
 107                      int flag = 0, int border = 0, wxObject* userData = NULL);
 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         @a excludeItem is given then it will not be checked for intersection,
 121         for 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, const wxGBSpan& span,
 126                               wxGBSizerItem* excludeItem = NULL);
 127     //@}
 128
 129     //@{
 130     /**
 131         Find the sizer item for the given window or subsizer, returns @NULL if
 132         not found. (non-recursive)
 133     */
 134     wxGBSizerItem* FindItem(wxWindow* window);
 135     wxGBSizerItem* FindItem(wxSizer* sizer);
 136     //@}
 137
 138     /**
 139         Return the sizer item located at the point given in pt, or @NULL if
 140         there is no item at that point. The (x,y) coordinates in @a pt
 141         correspond to the client coordinates of the window using the sizer for
 142         layout. (non-recursive)
 143     */
 144     wxGBSizerItem* FindItemAtPoint(const wxPoint& pt);
 145
 146     /**
 147         Return the sizer item for the given grid cell, or @NULL if there is no
 148         item at that position. (non-recursive)
 149     */
 150     wxGBSizerItem* FindItemAtPosition(const wxGBPosition& pos);
 151
 152     /**
 153         Return the sizer item that has a matching user data (it only compares
 154         pointer values) or @NULL if not found. (non-recursive)
 155     */
 156     wxGBSizerItem* FindItemWithData(const wxObject* userData);
 157
 158     /**
 159         Get the size of the specified cell, including hgap and vgap. Only valid
 160         after window layout has been performed.
 161     */
 162     wxSize GetCellSize(int row, int col) const;
 163
 164     /**
 165         Get the size used for cells in the grid with no item.
 166     */
 167     wxSize GetEmptyCellSize() const;
 168
 169     //@{
 170     /**
 171         Get the grid position of the specified item.
 172     */
 173     wxGBPosition GetItemPosition(wxWindow* window);
 174     wxGBPosition GetItemPosition(wxSizer* sizer);
 175     wxGBPosition GetItemPosition(size_t index);
 176     //@}
 177
 178     //@{
 179     /**
 180         Get the row/col spanning of the specified item.
 181     */
 182     wxGBSpan GetItemSpan(wxWindow* window);
 183     wxGBSpan GetItemSpan(wxSizer* sizer);
 184     wxGBSpan GetItemSpan(size_t index);
 185     //@}
 186
 187     /**
 188         Called when the managed size of the sizer is needed or when layout
 189         needs done.
 190     */
 191     void RecalcSizes();
 192
 193     /**
 194         Set the size used for cells in the grid with no item.
 195     */
 196     void SetEmptyCellSize(const wxSize& sz);
 197
 198     //@{
 199     /**
 200         Set the grid position of the specified item. Returns @true on success.
 201         If the move is not allowed (because an item is already there) then
 202         @false is returned.
 203     */
 204     bool SetItemPosition(wxWindow* window, const wxGBPosition& pos);
 205     bool SetItemPosition(wxSizer* sizer, const wxGBPosition& pos);
 206     bool SetItemPosition(size_t index, const wxGBPosition& pos);
 207     //@}
 208
 209     //@{
 210     /**
 211         Set the row/col spanning of the specified item. Returns @true on
 212         success. If the move is not allowed (because an item is already there)
 213         then @false is returned.
 214     */
 215     bool SetItemSpan(wxWindow* window, const wxGBSpan& span);
 216     bool SetItemSpan(wxSizer* sizer, const wxGBSpan& span);
 217     bool SetItemSpan(size_t index, const wxGBSpan& span);
 218     //@}
 219 };
 220
 221
 222
 223 /**
 224     @class wxGBSizerItem
 225
 226     The wxGBSizerItem class is used by the wxGridBagSizer for tracking the
 227     items in the sizer. It adds grid position and spanning information to the
 228     normal wxSizerItem by adding wxGBPosition and wxGBSpan attributes. Most of
 229     the time you will not need to use a wxGBSizerItem directly in your code,
 230     but there are a couple of cases where it is handy.
 231
 232     @library{wxcore}
 233     @category{winlayout}
 234 */
 235 class wxGBSizerItem : public wxSizerItem
 236 {
 237 public:
 238     /**
 239         Construct a sizer item for tracking a spacer.
 240     */
 241     wxGBSizerItem(int width, int height, const wxGBPosition& pos,
 242                   const wxGBSpan& span=wxDefaultSpan, int flag=0, int border=0,
 243                   wxObject* userData=NULL);
 244     /**
 245         Construct a sizer item for tracking a window.
 246     */
 247     wxGBSizerItem(wxWindow* window, const wxGBPosition& pos,
 248                   const wxGBSpan& span=wxDefaultSpan, int flag=0, int border=0,
 249                   wxObject* userData=NULL);
 250     /**
 251         Construct a sizer item for tracking a subsizer.
 252     */
 253     wxGBSizerItem(wxSizer* sizer, const wxGBPosition& pos,
 254                   const wxGBSpan& span=wxDefaultSpan, int flag=0, int border=0,
 255                   wxObject* userData=NULL);
 256
 257     /**
 258         Get the row and column of the endpoint of this item.
 259     */
 260     void GetEndPos(int& row, int& col);
 261
 262     //@{
 263     /**
 264         Get the grid position of the item.
 265     */
 266     wxGBPosition GetPos() const;
 267     void GetPos(int& row, int& col) const;
 268     //@}
 269
 270     //@{
 271     /**
 272         Get the row and column spanning of the item.
 273     */
 274     wxGBSpan GetSpan() const;
 275     void GetSpan(int& rowspan, int& colspan) const;
 276     //@}
 277
 278     /**
 279         Returns @true if this item and the @a other item intersect.
 280     */
 281     bool Intersects(const wxGBSizerItem& other);
 282     /**
 283         Returns @true if the given pos/span would intersect with this item.
 284     */
 285     bool Intersects(const wxGBPosition& pos, const wxGBSpan& span);
 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 at the new
 290         position, then set the new position. Returns @true if the change is
 291         successful and after the next Layout the item will be moved.
 292     */
 293     bool SetPos(const wxGBPosition& pos);
 294
 295     /**
 296         If the item is already a member of a sizer then first ensure that there
 297         is no other item that would intersect with this one with its new
 298         spanning size, then set the new spanning. Returns @true if the change
 299         is successful and after the next Layout the item will be resized.
 300     */
 301     bool SetSpan(const wxGBSpan& span);
 302
 303
 304     wxGridBagSizer* GetGBSizer() const;
 305     void SetGBSizer(wxGridBagSizer* sizer);
 306 };
 307
 308
 309
 310 /**
 311     @class wxGBSpan
 312
 313     This class is used to hold the row and column spanning attributes of items
 314     in a wxGridBagSizer.
 315
 316     @library{wxcore}
 317     @category{winlayout}
 318 */
 319 class wxGBSpan
 320 {
 321 public:
 322     /**
 323         Default constructor, setting the rowspan and colspan to (1,1) meaning
 324         that the item occupies one cell in each direction.
 325     */
 326     wxGBSpan();
 327     /**
 328         Construct a new wxGBSpan, setting the @a rowspan and @a colspan.
 329     */
 330     wxGBSpan(int rowspan, int colspan);
 331
 332     /**
 333         Get the current colspan value.
 334     */
 335     int GetColspan() const;
 336
 337     /**
 338         Get the current rowspan value.
 339     */
 340     int GetRowspan() const;
 341
 342     /**
 343         Set a new colspan value.
 344     */
 345     void SetColspan(int colspan);
 346
 347     /**
 348         Set a new rowspan value.
 349     */
 350     void SetRowspan(int rowspan);
 351
 352     /**
 353         Compare inequality of two wxGBSpans.
 354     */
 355     bool operator!=(const wxGBSpan& o) const;
 356
 357     /**
 358         Compare equality of two wxGBSpans.
 359     */
 360     bool operator==(const wxGBSpan& o) const;
 361 };
 362
 363
 364 const wxGBSpan wxDefaultSpan;