simgear/canvas/layout/LayoutItem.hxx

   1 ///@file
   2 /// Basic element for layouting canvas elements.
   3 //
   4 // Copyright (C) 2014  Thomas Geymayer <tomgey@gmail.com>
   5 //
   6 // This library is free software; you can redistribute it and/or
   7 // modify it under the terms of the GNU Library General Public
   8 // License as published by the Free Software Foundation; either
   9 // version 2 of the License, or (at your option) any later version.
  10 //
  11 // This library is distributed in the hope that it will be useful,
  12 // but WITHOUT ANY WARRANTY; without even the implied warranty of
  13 // MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE.  See the GNU
  14 // Library General Public License for more details.
  15 //
  16 // You should have received a copy of the GNU Library General Public
  17 // License along with this library; if not, write to the Free Software
  18 // Foundation, Inc., 51 Franklin St, Fifth Floor, Boston, MA  02110-1301, USA
  19
  20 #ifndef SG_CANVAS_LAYOUT_ITEM_HXX_
  21 #define SG_CANVAS_LAYOUT_ITEM_HXX_
  22
  23 #include <simgear/canvas/canvas_fwd.hxx>
  24 #include <simgear/math/SGMath.hxx>
  25 #include <simgear/math/SGRect.hxx>
  26 #include <simgear/misc/stdint.hxx>
  27 #include <simgear/structure/SGWeakReferenced.hxx>
  28 #include <simgear/structure/SGSharedPtr.hxx>
  29
  30 namespace simgear
  31 {
  32 namespace canvas
  33 {
  34   class LayoutItem;
  35   typedef SGSharedPtr<LayoutItem> LayoutItemRef;
  36   typedef SGWeakPtr<LayoutItem> LayoutItemWeakRef;
  37
  38   /**
  39    * Holds the four margins for a rectangle.
  40    */
  41   struct Margins
  42   {
  43     int l, t, r, b;
  44
  45     /**
  46      * Set all margins to the same value @a m.
  47      */
  48     explicit Margins(int m = 0);
  49
  50     /**
  51      * Set horizontal and vertical margins to the same values @a h and @a v
  52      * respectively.
  53      *
  54      * @param h Horizontal margins
  55      * @param v Vertical margins
  56      */
  57     Margins(int h, int v);
  58
  59     /**
  60      * Set the margins to the given values.
  61      */
  62     Margins(int left, int top, int right, int bottom);
  63
  64     /**
  65      * Get the total horizontal margin (sum of left and right margin).
  66      */
  67     int horiz() const;
  68
  69     /**
  70      * Get the total vertical margin (sum of top and bottom margin).
  71      */
  72     int vert() const;
  73
  74     /**
  75      * Get total horizontal and vertical margin as vector.
  76      */
  77     SGVec2i size() const;
  78
  79     /**
  80      * Returns true if all margins are 0.
  81      */
  82     bool isNull() const;
  83   };
  84
  85   /**
  86    * Base class for all layouting elements. Specializations either implement a
  87    * layouting algorithm or a widget.
  88    */
  89   class LayoutItem:
  90     public virtual SGVirtualWeakReferenced
  91   {
  92     public:
  93
  94       /** Maximum item size (indicating no limit) */
  95       static const SGVec2i MAX_SIZE;
  96
  97       LayoutItem();
  98       virtual ~LayoutItem();
  99
 100       /**
 101        * Set the margins to use by the layout system around the item.
 102        *
 103        * The margins define the size of the clear area around an item. It
 104        * increases the size hints and reduces the size of the geometry()
 105        * available to child layouts and widgets.
 106        *
 107        * @see Margins
 108        */
 109       void setContentsMargins(const Margins& margins);
 110
 111       /**
 112        * Set the individual margins.
 113        *
 114        * @see setContentsMargins(const Margins&)
 115        */
 116       void setContentsMargins(int left, int top, int right, int bottom);
 117
 118       /**
 119        * Set all margins to the same value.
 120        *
 121        * @see setContentsMargins(const Margins&)
 122        */
 123       void setContentsMargin(int margin);
 124
 125       /**
 126        * Get the currently used margins.
 127        *
 128        * @see setContentsMargins(const Margins&)
 129        * @see Margins
 130        */
 131       Margins getContentsMargins() const;
 132
 133       /**
 134        * Get the area available to the contents.
 135        *
 136        * This is equal to the geometry() reduced by the sizes of the margins.
 137        *
 138        * @see setContentsMargins(const Margins&)
 139        * @see geometry()
 140        */
 141       SGRecti contentsRect() const;
 142
 143       /**
 144        * Get the preferred size of this item.
 145        */
 146       SGVec2i sizeHint() const;
 147
 148       /**
 149        * Get the minimum amount of the space this item requires.
 150        */
 151       SGVec2i minimumSize() const;
 152
 153       /**
 154        * Get the maximum amount of space this item can use.
 155        */
 156       SGVec2i maximumSize() const;
 157
 158       /**
 159        * Returns true if this items preferred and minimum height depend on its
 160        * width.
 161        *
 162        * The default implementation returns false. Reimplement for items
 163        * providing height for width.
 164        *
 165        * @see heightForWidth()
 166        * @see minimumHeightForWidth()
 167        */
 168       virtual bool hasHeightForWidth() const;
 169
 170       /**
 171        * Returns the preferred height for the given width @a w.
 172        *
 173        * Reimplement heightForWidthImpl() for items providing height for width.
 174        *
 175        * @see hasHeightForWidth()
 176        */
 177       int heightForWidth(int w) const;
 178
 179       /**
 180        * Returns the minimum height for the given width @a w.
 181        *
 182        * Reimplement minimumHeightForWidthImpl() for items providing height for
 183        * width.
 184        *
 185        * @see hasHeightForWidth()
 186        */
 187       int minimumHeightForWidth(int w) const;
 188
 189       virtual void setVisible(bool visible);
 190       virtual bool isVisible() const;
 191
 192       bool isExplicitlyHidden() const;
 193
 194       void show() { setVisible(true); }
 195       void hide() { setVisible(false); }
 196
 197       /**
 198        * Mark all cached data as invalid and require it to be recalculated.
 199        */
 200       virtual void invalidate();
 201
 202       /**
 203        * Mark all cached data of parent item as invalid (if the parent is set).
 204        */
 205       void invalidateParent();
 206
 207       /**
 208        * Apply any changes not applied yet.
 209        */
 210       void update();
 211
 212       /**
 213        * Set position and size of this element. For layouts this triggers a
 214        * recalculation of the layout.
 215        */
 216       virtual void setGeometry(const SGRecti& geom);
 217
 218       /**
 219        * Get position and size of this element.
 220        */
 221       virtual SGRecti geometry() const;
 222
 223       /**
 224        * Set the canvas this item is attached to.
 225        */
 226       virtual void setCanvas(const CanvasWeakPtr& canvas);
 227
 228       /**
 229        * Get the canvas this item is attached to.
 230        */
 231       CanvasPtr getCanvas() const;
 232
 233       /**
 234        * Set the parent layout item (usually this is a layout).
 235        */
 236       void setParent(const LayoutItemWeakRef& parent);
 237
 238       /**
 239        * Get the parent layout.
 240        */
 241       LayoutItemRef getParent() const;
 242
 243       /// Called before item is removed from a layout
 244       virtual void onRemove() {}
 245
 246     protected:
 247
 248       friend class Canvas;
 249
 250       enum Flags
 251       {
 252         SIZE_HINT_DIRTY = 1,
 253         MINIMUM_SIZE_DIRTY = SIZE_HINT_DIRTY << 1,
 254         MAXIMUM_SIZE_DIRTY = MINIMUM_SIZE_DIRTY << 1,
 255         SIZE_INFO_DIRTY = SIZE_HINT_DIRTY
 256                         | MINIMUM_SIZE_DIRTY
 257                         | MAXIMUM_SIZE_DIRTY,
 258         EXPLICITLY_HIDDEN = MAXIMUM_SIZE_DIRTY << 1,
 259         VISIBLE = EXPLICITLY_HIDDEN << 1,
 260         LAYOUT_DIRTY = VISIBLE << 1,
 261         LAST_FLAG = LAYOUT_DIRTY
 262       };
 263
 264       CanvasWeakPtr     _canvas;
 265       LayoutItemWeakRef _parent;
 266
 267       SGRecti           _geometry;
 268       Margins           _margins;
 269
 270       mutable uint32_t  _flags;
 271       mutable SGVec2i   _size_hint,
 272                         _min_size,
 273                         _max_size;
 274
 275       virtual SGVec2i sizeHintImpl() const;
 276       virtual SGVec2i minimumSizeImpl() const;
 277       virtual SGVec2i maximumSizeImpl() const;
 278
 279       /**
 280        * Returns the preferred height for the given width @a w.
 281        *
 282        * The default implementation returns -1, indicating that the preferred
 283        * height is independent of the given width.
 284        *
 285        * Reimplement this function for items supporting height for width.
 286        *
 287        * @note Do not take margins into account, as this is already handled
 288        *       before calling this function.
 289        *
 290        * @see hasHeightForWidth()
 291        */
 292       virtual int heightForWidthImpl(int w) const;
 293
 294       /**
 295        * Returns the minimum height for the given width @a w.
 296        *
 297        * The default implementation returns -1, indicating that the minimum
 298        * height is independent of the given width.
 299        *
 300        * Reimplement this function for items supporting height for width.
 301        *
 302        * @note Do not take margins into account, as this is already handled
 303        *       before calling this function.
 304        *
 305        * @see hasHeightForWidth()
 306        */
 307       virtual int minimumHeightForWidthImpl(int w) const;
 308
 309       /**
 310        * @return whether the visibility has changed.
 311        */
 312       void setVisibleInternal(bool visible);
 313
 314       virtual void contentsRectChanged(const SGRecti& rect) {};
 315
 316       virtual void visibilityChanged(bool visible) {}
 317
 318       /**
 319        * Allow calling the protected setVisibleImpl from derived classes
 320        */
 321       static void callSetVisibleInternal(LayoutItem* item, bool visible);
 322
 323   };
 324
 325 } // namespace canvas
 326 } // namespace simgear
 327
 328 #endif /* SG_CANVAS_LAYOUT_ITEM_HXX_ */