2 /// Basic element for layouting canvas elements.
4 // Copyright (C) 2014 Thomas Geymayer <tomgey@gmail.com>
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.
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.
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
20 #ifndef SG_CANVAS_LAYOUT_ITEM_HXX_
21 #define SG_CANVAS_LAYOUT_ITEM_HXX_
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>
35 typedef SGSharedPtr<LayoutItem> LayoutItemRef;
36 typedef SGWeakPtr<LayoutItem> LayoutItemWeakRef;
39 * Holds the four margins for a rectangle.
46 * Set all margins to the same value @a m.
48 explicit Margins(int m = 0);
51 * Set horizontal and vertical margins to the same values @a h and @a v
54 * @param h Horizontal margins
55 * @param v Vertical margins
57 Margins(int h, int v);
60 * Set the margins to the given values.
62 Margins(int left, int top, int right, int bottom);
65 * Get the total horizontal margin (sum of left and right margin).
70 * Get the total vertical margin (sum of top and bottom margin).
75 * Get total horizontal and vertical margin as vector.
80 * Returns true if all margins are 0.
86 * Flags for LayoutItem alignment inside {@link Layout Layouts}.
88 * @note You can only use one horizontal and one vertical flag at the same.
92 #define ALIGN_ENUM_MAPPING(key, val, comment) key = val, /*!< comment */
93 # include "AlignFlag_values.hxx"
94 #undef ALIGN_ENUM_MAPPING
98 * Base class for all layouting elements. Specializations either implement a
99 * layouting algorithm or a widget.
102 public virtual SGVirtualWeakReferenced
106 /** Maximum item size (indicating no limit) */
107 static const SGVec2i MAX_SIZE;
110 virtual ~LayoutItem();
113 * Set the margins to use by the layout system around the item.
115 * The margins define the size of the clear area around an item. It
116 * increases the size hints and reduces the size of the geometry()
117 * available to child layouts and widgets.
121 void setContentsMargins(const Margins& margins);
124 * Set the individual margins.
126 * @see setContentsMargins(const Margins&)
128 void setContentsMargins(int left, int top, int right, int bottom);
131 * Set all margins to the same value.
133 * @see setContentsMargins(const Margins&)
135 void setContentsMargin(int margin);
138 * Get the currently used margins.
140 * @see setContentsMargins(const Margins&)
143 Margins getContentsMargins() const;
146 * Get the area available to the contents.
148 * This is equal to the geometry() reduced by the sizes of the margins.
150 * @see setContentsMargins(const Margins&)
153 SGRecti contentsRect() const;
156 * Get the preferred size of this item.
158 SGVec2i sizeHint() const;
161 * Get the minimum amount of the space this item requires.
163 SGVec2i minimumSize() const;
166 * Get the maximum amount of space this item can use.
168 SGVec2i maximumSize() const;
171 * Returns true if this items preferred and minimum height depend on its
174 * The default implementation returns false. Reimplement for items
175 * providing height for width.
177 * @see heightForWidth()
178 * @see minimumHeightForWidth()
180 virtual bool hasHeightForWidth() const;
183 * Returns the preferred height for the given width @a w.
185 * Reimplement heightForWidthImpl() for items providing height for width.
187 * @see hasHeightForWidth()
189 int heightForWidth(int w) const;
192 * Returns the minimum height for the given width @a w.
194 * Reimplement minimumHeightForWidthImpl() for items providing height for
197 * @see hasHeightForWidth()
199 int minimumHeightForWidth(int w) const;
202 * Set alignment of item within {@link Layout Layouts}.
204 * @param alignment Bitwise combination of vertical and horizontal
208 void setAlignment(uint8_t alignment);
211 * Get all alignment flags.
215 uint8_t alignment() const;
217 virtual void setVisible(bool visible);
218 virtual bool isVisible() const;
220 bool isExplicitlyHidden() const;
222 void show() { setVisible(true); }
223 void hide() { setVisible(false); }
226 * Mark all cached data as invalid and require it to be recalculated.
228 virtual void invalidate();
231 * Mark all cached data of parent item as invalid (if the parent is set).
233 void invalidateParent();
236 * Apply any changes not applied yet.
241 * Set position and size of this element. For layouts this triggers a
242 * recalculation of the layout.
244 virtual void setGeometry(const SGRecti& geom);
247 * Get position and size of this element.
249 virtual SGRecti geometry() const;
252 * Get the actual geometry of this item given the rectangle \a geom
253 * taking into account the alignment flags and size hints.
255 * @param geom Area available to this item.
256 * @return The resulting geometry for this item.
258 * @see setAlignment()
263 virtual SGRecti alignmentRect(const SGRecti& geom) const;
266 * Set the canvas this item is attached to.
268 virtual void setCanvas(const CanvasWeakPtr& canvas);
271 * Get the canvas this item is attached to.
273 CanvasPtr getCanvas() const;
276 * Set the parent layout item (usually this is a layout).
278 void setParent(const LayoutItemWeakRef& parent);
281 * Get the parent layout.
283 LayoutItemRef getParent() const;
285 /// Called before item is removed from a layout
286 virtual void onRemove() {}
295 MINIMUM_SIZE_DIRTY = SIZE_HINT_DIRTY << 1,
296 MAXIMUM_SIZE_DIRTY = MINIMUM_SIZE_DIRTY << 1,
297 SIZE_INFO_DIRTY = SIZE_HINT_DIRTY
299 | MAXIMUM_SIZE_DIRTY,
300 EXPLICITLY_HIDDEN = MAXIMUM_SIZE_DIRTY << 1,
301 VISIBLE = EXPLICITLY_HIDDEN << 1,
302 LAYOUT_DIRTY = VISIBLE << 1,
303 LAST_FLAG = LAYOUT_DIRTY
306 CanvasWeakPtr _canvas;
307 LayoutItemWeakRef _parent;
313 mutable uint32_t _flags;
314 mutable SGVec2i _size_hint,
318 virtual SGVec2i sizeHintImpl() const;
319 virtual SGVec2i minimumSizeImpl() const;
320 virtual SGVec2i maximumSizeImpl() const;
323 * Returns the preferred height for the given width @a w.
325 * The default implementation returns -1, indicating that the preferred
326 * height is independent of the given width.
328 * Reimplement this function for items supporting height for width.
330 * @note Do not take margins into account, as this is already handled
331 * before calling this function.
333 * @see hasHeightForWidth()
335 virtual int heightForWidthImpl(int w) const;
338 * Returns the minimum height for the given width @a w.
340 * The default implementation returns -1, indicating that the minimum
341 * height is independent of the given width.
343 * Reimplement this function for items supporting height for width.
345 * @note Do not take margins into account, as this is already handled
346 * before calling this function.
348 * @see hasHeightForWidth()
350 virtual int minimumHeightForWidthImpl(int w) const;
353 * @return whether the visibility has changed.
355 void setVisibleInternal(bool visible);
357 virtual void contentsRectChanged(const SGRecti& rect) {};
359 virtual void visibilityChanged(bool visible) {}
362 * Allow calling the protected setVisibleImpl from derived classes
364 static void callSetVisibleInternal(LayoutItem* item, bool visible);
368 } // namespace canvas
369 } // namespace simgear
371 #endif /* SG_CANVAS_LAYOUT_ITEM_HXX_ */