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