(svn r28004) -Update from Eints:
[openttd.git] / src / widget_type.h
blob163d45800e5c10de2dbbddf2a64e151bbd866f73
1 /* $Id$ */
3 /*
4 * This file is part of OpenTTD.
5 * OpenTTD is free software; you can redistribute it and/or modify it under the terms of the GNU General Public License as published by the Free Software Foundation, version 2.
6 * OpenTTD is distributed in the hope that it will be useful, but WITHOUT ANY WARRANTY; without even the implied warranty of MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE.
7 * See the GNU General Public License for more details. You should have received a copy of the GNU General Public License along with OpenTTD. If not, see <http://www.gnu.org/licenses/>.
8 */
10 /** @file widget_type.h Definitions about widgets. */
12 #ifndef WIDGET_TYPE_H
13 #define WIDGET_TYPE_H
15 #include "core/alloc_type.hpp"
16 #include "core/bitmath_func.hpp"
17 #include "core/math_func.hpp"
18 #include "strings_type.h"
19 #include "gfx_type.h"
20 #include "window_type.h"
22 static const int WIDGET_LIST_END = -1; ///< indicate the end of widgets' list for vararg functions
24 /** Bits of the #WWT_MATRIX widget data. */
25 enum MatrixWidgetValues {
26 /* Number of column bits of the WWT_MATRIX widget data. */
27 MAT_COL_START = 0, ///< Lowest bit of the number of columns.
28 MAT_COL_BITS = 8, ///< Number of bits for the number of columns in the matrix.
30 /* Number of row bits of the WWT_MATRIX widget data. */
31 MAT_ROW_START = 8, ///< Lowest bit of the number of rows.
32 MAT_ROW_BITS = 8, ///< Number of bits for the number of rows in the matrix.
35 /** Values for an arrow widget */
36 enum ArrowWidgetValues {
37 AWV_DECREASE, ///< Arrow to the left or in case of RTL to the right
38 AWV_INCREASE, ///< Arrow to the right or in case of RTL to the left
39 AWV_LEFT, ///< Force the arrow to the left
40 AWV_RIGHT, ///< Force the arrow to the right
43 /**
44 * Window widget types, nested widget types, and nested widget part types.
46 enum WidgetType {
47 /* Window widget types. */
48 WWT_EMPTY, ///< Empty widget, place holder to reserve space in widget array
50 WWT_PANEL, ///< Simple depressed panel
51 WWT_INSET, ///< Pressed (inset) panel, most commonly used as combo box _text_ area
52 WWT_IMGBTN, ///< (Toggle) Button with image
53 WWT_IMGBTN_2, ///< (Toggle) Button with diff image when clicked
54 WWT_ARROWBTN, ///< (Toggle) Button with an arrow
55 WWT_TEXTBTN, ///< (Toggle) Button with text
56 WWT_TEXTBTN_2, ///< (Toggle) Button with diff text when clicked
57 WWT_LABEL, ///< Centered label
58 WWT_TEXT, ///< Pure simple text
59 WWT_MATRIX, ///< Grid of rows and columns. @see MatrixWidgetValues
60 WWT_FRAME, ///< Frame
61 WWT_CAPTION, ///< Window caption (window title between closebox and stickybox)
63 WWT_DEBUGBOX, ///< NewGRF debug box (at top-right of a window, between WWT_CAPTION and WWT_SHADEBOX)
64 WWT_SHADEBOX, ///< Shade box (at top-right of a window, between WWT_DEBUGBOX and WWT_DEFSIZEBOX)
65 WWT_DEFSIZEBOX, ///< Default window size box (at top-right of a window, between WWT_SHADEBOX and WWT_STICKYBOX)
66 WWT_STICKYBOX, ///< Sticky box (at top-right of a window, after WWT_DEFSIZEBOX)
68 WWT_RESIZEBOX, ///< Resize box (normally at bottom-right of a window)
69 WWT_CLOSEBOX, ///< Close box (at top-left of a window)
70 WWT_DROPDOWN, ///< Drop down list
71 WWT_EDITBOX, ///< a textbox for typing
72 WWT_LAST, ///< Last Item. use WIDGETS_END to fill up padding!!
74 /* Nested widget types. */
75 NWID_HORIZONTAL, ///< Horizontal container.
76 NWID_HORIZONTAL_LTR, ///< Horizontal container that doesn't change the order of the widgets for RTL languages.
77 NWID_VERTICAL, ///< Vertical container.
78 NWID_MATRIX, ///< Matrix container.
79 NWID_SPACER, ///< Invisible widget that takes some space.
80 NWID_SELECTION, ///< Stacked widgets, only one visible at a time (eg in a panel with tabs).
81 NWID_VIEWPORT, ///< Nested widget containing a viewport.
82 NWID_BUTTON_DROPDOWN, ///< Button with a drop-down.
83 NWID_HSCROLLBAR, ///< Horizontal scrollbar
84 NWID_VSCROLLBAR, ///< Vertical scrollbar
86 /* Nested widget part types. */
87 WPT_RESIZE, ///< Widget part for specifying resizing.
88 WPT_MINSIZE, ///< Widget part for specifying minimal size.
89 WPT_MINTEXTLINES, ///< Widget part for specifying minimal number of lines of text.
90 WPT_FILL, ///< Widget part for specifying fill.
91 WPT_DATATIP, ///< Widget part for specifying data and tooltip.
92 WPT_PADDING, ///< Widget part for specifying a padding.
93 WPT_PIPSPACE, ///< Widget part for specifying pre/inter/post space for containers.
94 WPT_ENDCONTAINER, ///< Widget part to denote end of a container.
95 WPT_FUNCTION, ///< Widget part for calling a user function.
96 WPT_SCROLLBAR, ///< Widget part for attaching a scrollbar.
98 /* Pushable window widget types. */
99 WWT_MASK = 0x7F,
101 WWB_PUSHBUTTON = 1 << 7,
103 WWT_PUSHBTN = WWT_PANEL | WWB_PUSHBUTTON, ///< Normal push-button (no toggle button) with custom drawing
104 WWT_PUSHTXTBTN = WWT_TEXTBTN | WWB_PUSHBUTTON, ///< Normal push-button (no toggle button) with text caption
105 WWT_PUSHIMGBTN = WWT_IMGBTN | WWB_PUSHBUTTON, ///< Normal push-button (no toggle button) with image caption
106 WWT_PUSHARROWBTN = WWT_ARROWBTN | WWB_PUSHBUTTON, ///< Normal push-button (no toggle button) with arrow caption
107 NWID_PUSHBUTTON_DROPDOWN = NWID_BUTTON_DROPDOWN | WWB_PUSHBUTTON,
110 /** Different forms of sizing nested widgets, using NWidgetBase::AssignSizePosition() */
111 enum SizingType {
112 ST_SMALLEST, ///< Initialize nested widget tree to smallest size. Also updates \e current_x and \e current_y.
113 ST_RESIZE, ///< Resize the nested widget tree.
116 /* Forward declarations. */
117 class NWidgetCore;
118 class Scrollbar;
121 * Baseclass for nested widgets.
122 * @invariant After initialization, \f$current\_x = smallest\_x + n * resize\_x, for n \geq 0\f$.
123 * @invariant After initialization, \f$current\_y = smallest\_y + m * resize\_y, for m \geq 0\f$.
124 * @ingroup NestedWidgets
126 class NWidgetBase : public ZeroedMemoryAllocator {
127 public:
128 NWidgetBase(WidgetType tp);
130 virtual void SetupSmallestSize(Window *w, bool init_array) = 0;
131 virtual void AssignSizePosition(SizingType sizing, uint x, uint y, uint given_width, uint given_height, bool rtl) = 0;
133 virtual void FillNestedArray(NWidgetBase **array, uint length) = 0;
135 virtual NWidgetCore *GetWidgetFromPos(int x, int y) = 0;
136 virtual NWidgetBase *GetWidgetOfType(WidgetType tp);
138 virtual bool IsHighlighted() const { return false; }
139 virtual TextColour GetHighlightColour() const { return TC_INVALID; }
140 virtual void SetHighlighted(TextColour highlight_colour) {}
143 * Set additional space (padding) around the widget.
144 * @param top Amount of additional space above the widget.
145 * @param right Amount of additional space right of the widget.
146 * @param bottom Amount of additional space below the widget.
147 * @param left Amount of additional space left of the widget.
149 inline void SetPadding(uint8 top, uint8 right, uint8 bottom, uint8 left)
151 this->padding_top = top;
152 this->padding_right = right;
153 this->padding_bottom = bottom;
154 this->padding_left = left;
157 inline uint GetHorizontalStepSize(SizingType sizing) const;
158 inline uint GetVerticalStepSize(SizingType sizing) const;
160 virtual void Draw(const Window *w) = 0;
161 virtual void SetDirty(const Window *w) const;
163 WidgetType type; ///< Type of the widget / nested widget.
164 uint fill_x; ///< Horizontal fill stepsize (from initial size, \c 0 means not resizable).
165 uint fill_y; ///< Vertical fill stepsize (from initial size, \c 0 means not resizable).
166 uint resize_x; ///< Horizontal resize step (\c 0 means not resizable).
167 uint resize_y; ///< Vertical resize step (\c 0 means not resizable).
168 /* Size of the widget in the smallest window possible.
169 * Computed by #SetupSmallestSize() followed by #AssignSizePosition().
171 uint smallest_x; ///< Smallest horizontal size of the widget in a filled window.
172 uint smallest_y; ///< Smallest vertical size of the widget in a filled window.
173 /* Current widget size (that is, after resizing). */
174 uint current_x; ///< Current horizontal size (after resizing).
175 uint current_y; ///< Current vertical size (after resizing).
177 uint pos_x; ///< Horizontal position of top-left corner of the widget in the window.
178 uint pos_y; ///< Vertical position of top-left corner of the widget in the window.
180 NWidgetBase *next; ///< Pointer to next widget in container. Managed by parent container widget.
181 NWidgetBase *prev; ///< Pointer to previous widget in container. Managed by parent container widget.
183 uint8 padding_top; ///< Paddings added to the top of the widget. Managed by parent container widget.
184 uint8 padding_right; ///< Paddings added to the right of the widget. Managed by parent container widget. (parent container may swap this with padding_left for RTL)
185 uint8 padding_bottom; ///< Paddings added to the bottom of the widget. Managed by parent container widget.
186 uint8 padding_left; ///< Paddings added to the left of the widget. Managed by parent container widget. (parent container may swap this with padding_right for RTL)
188 protected:
189 inline void StoreSizePosition(SizingType sizing, uint x, uint y, uint given_width, uint given_height);
193 * Get the horizontal sizing step.
194 * @param sizing Type of resize being performed.
196 inline uint NWidgetBase::GetHorizontalStepSize(SizingType sizing) const
198 return (sizing == ST_RESIZE) ? this->resize_x : this->fill_x;
202 * Get the vertical sizing step.
203 * @param sizing Type of resize being performed.
205 inline uint NWidgetBase::GetVerticalStepSize(SizingType sizing) const
207 return (sizing == ST_RESIZE) ? this->resize_y : this->fill_y;
211 * Store size and position.
212 * @param sizing Type of resizing to perform.
213 * @param x Horizontal offset of the widget relative to the left edge of the window.
214 * @param y Vertical offset of the widget relative to the top edge of the window.
215 * @param given_width Width allocated to the widget.
216 * @param given_height Height allocated to the widget.
218 inline void NWidgetBase::StoreSizePosition(SizingType sizing, uint x, uint y, uint given_width, uint given_height)
220 this->pos_x = x;
221 this->pos_y = y;
222 if (sizing == ST_SMALLEST) {
223 this->smallest_x = given_width;
224 this->smallest_y = given_height;
226 this->current_x = given_width;
227 this->current_y = given_height;
232 * Base class for a resizable nested widget.
233 * @ingroup NestedWidgets
235 class NWidgetResizeBase : public NWidgetBase {
236 public:
237 NWidgetResizeBase(WidgetType tp, uint fill_x, uint fill_y);
239 void SetMinimalSize(uint min_x, uint min_y);
240 void SetMinimalTextLines(uint8 min_lines, uint8 spacing, FontSize size);
241 void SetFill(uint fill_x, uint fill_y);
242 void SetResize(uint resize_x, uint resize_y);
244 void AssignSizePosition(SizingType sizing, uint x, uint y, uint given_width, uint given_height, bool rtl);
246 uint min_x; ///< Minimal horizontal size of only this widget.
247 uint min_y; ///< Minimal vertical size of only this widget.
250 /** Nested widget flags that affect display and interaction withe 'real' widgets. */
251 enum NWidgetDisplay {
252 /* Generic. */
253 NDB_LOWERED = 0, ///< Widget is lowered (pressed down) bit.
254 NDB_DISABLED = 1, ///< Widget is disabled (greyed out) bit.
255 /* Viewport widget. */
256 NDB_NO_TRANSPARENCY = 2, ///< Viewport is never transparent.
257 NDB_SHADE_GREY = 3, ///< Shade viewport to grey-scale.
258 NDB_SHADE_DIMMED = 4, ///< Display dimmed colours in the viewport.
259 /* Button dropdown widget. */
260 NDB_DROPDOWN_ACTIVE = 5, ///< Dropdown menu of the button dropdown widget is active. @see #NWID_BUTTON_DRPDOWN
261 /* Scrollbar widget. */
262 NDB_SCROLLBAR_UP = 6, ///< Up-button is lowered bit.
263 NDB_SCROLLBAR_DOWN = 7, ///< Down-button is lowered bit.
264 /* Generic. */
265 NDB_HIGHLIGHT = 8, ///< Highlight of widget is on.
267 ND_LOWERED = 1 << NDB_LOWERED, ///< Bit value of the lowered flag.
268 ND_DISABLED = 1 << NDB_DISABLED, ///< Bit value of the disabled flag.
269 ND_HIGHLIGHT = 1 << NDB_HIGHLIGHT, ///< Bit value of the highlight flag.
270 ND_NO_TRANSPARENCY = 1 << NDB_NO_TRANSPARENCY, ///< Bit value of the 'no transparency' flag.
271 ND_SHADE_GREY = 1 << NDB_SHADE_GREY, ///< Bit value of the 'shade to grey' flag.
272 ND_SHADE_DIMMED = 1 << NDB_SHADE_DIMMED, ///< Bit value of the 'dimmed colours' flag.
273 ND_DROPDOWN_ACTIVE = 1 << NDB_DROPDOWN_ACTIVE, ///< Bit value of the 'dropdown active' flag.
274 ND_SCROLLBAR_UP = 1 << NDB_SCROLLBAR_UP, ///< Bit value of the 'scrollbar up' flag.
275 ND_SCROLLBAR_DOWN = 1 << NDB_SCROLLBAR_DOWN, ///< Bit value of the 'scrollbar down' flag.
276 ND_SCROLLBAR_BTN = ND_SCROLLBAR_UP | ND_SCROLLBAR_DOWN, ///< Bit value of the 'scrollbar up' or 'scrollbar down' flag.
278 DECLARE_ENUM_AS_BIT_SET(NWidgetDisplay)
281 * Base class for a 'real' widget.
282 * @ingroup NestedWidgets
284 class NWidgetCore : public NWidgetResizeBase {
285 public:
286 NWidgetCore(WidgetType tp, Colours colour, uint fill_x, uint fill_y, uint32 widget_data, StringID tool_tip);
288 void SetIndex(int index);
289 void SetDataTip(uint32 widget_data, StringID tool_tip);
291 inline void SetLowered(bool lowered);
292 inline bool IsLowered() const;
293 inline void SetDisabled(bool disabled);
294 inline bool IsDisabled() const;
296 /* virtual */ void FillNestedArray(NWidgetBase **array, uint length);
297 /* virtual */ NWidgetCore *GetWidgetFromPos(int x, int y);
298 /* virtual */ bool IsHighlighted() const;
299 /* virtual */ TextColour GetHighlightColour() const;
300 /* virtual */ void SetHighlighted(TextColour highlight_colour);
302 NWidgetDisplay disp_flags; ///< Flags that affect display and interaction with the widget.
303 Colours colour; ///< Colour of this widget.
304 int index; ///< Index of the nested widget in the widget array of the window (\c -1 means 'not used').
305 uint32 widget_data; ///< Data of the widget. @see Widget::data
306 StringID tool_tip; ///< Tooltip of the widget. @see Widget::tootips
307 int scrollbar_index; ///< Index of an attached scrollbar.
308 TextColour highlight_colour; ///< Colour of highlight.
312 * Highlight the widget or not.
313 * @param highlight_colour Widget must be highlighted (blink).
315 inline void NWidgetCore::SetHighlighted(TextColour highlight_colour)
317 this->disp_flags = highlight_colour != TC_INVALID ? SETBITS(this->disp_flags, ND_HIGHLIGHT) : CLRBITS(this->disp_flags, ND_HIGHLIGHT);
318 this->highlight_colour = highlight_colour;
321 /** Return whether the widget is highlighted. */
322 inline bool NWidgetCore::IsHighlighted() const
324 return HasBit(this->disp_flags, NDB_HIGHLIGHT);
327 /** Return the colour of the highlight. */
328 inline TextColour NWidgetCore::GetHighlightColour() const
330 return this->highlight_colour;
334 * Lower or raise the widget.
335 * @param lowered Widget must be lowered (drawn pressed down).
337 inline void NWidgetCore::SetLowered(bool lowered)
339 this->disp_flags = lowered ? SETBITS(this->disp_flags, ND_LOWERED) : CLRBITS(this->disp_flags, ND_LOWERED);
342 /** Return whether the widget is lowered. */
343 inline bool NWidgetCore::IsLowered() const
345 return HasBit(this->disp_flags, NDB_LOWERED);
349 * Disable (grey-out) or enable the widget.
350 * @param disabled Widget must be disabled.
352 inline void NWidgetCore::SetDisabled(bool disabled)
354 this->disp_flags = disabled ? SETBITS(this->disp_flags, ND_DISABLED) : CLRBITS(this->disp_flags, ND_DISABLED);
357 /** Return whether the widget is disabled. */
358 inline bool NWidgetCore::IsDisabled() const
360 return HasBit(this->disp_flags, NDB_DISABLED);
365 * Baseclass for container widgets.
366 * @ingroup NestedWidgets
368 class NWidgetContainer : public NWidgetBase {
369 public:
370 NWidgetContainer(WidgetType tp);
371 ~NWidgetContainer();
373 void Add(NWidgetBase *wid);
374 /* virtual */ void FillNestedArray(NWidgetBase **array, uint length);
376 /** Return whether the container is empty. */
377 inline bool IsEmpty() { return head == NULL; }
379 /* virtual */ NWidgetBase *GetWidgetOfType(WidgetType tp);
381 protected:
382 NWidgetBase *head; ///< Pointer to first widget in container.
383 NWidgetBase *tail; ///< Pointer to last widget in container.
386 /** Display planes with zero size for #NWidgetStacked. */
387 enum StackedZeroSizePlanes {
388 SZSP_VERTICAL = INT_MAX / 2, ///< Display plane with zero size horizontally, and filling and resizing vertically.
389 SZSP_HORIZONTAL, ///< Display plane with zero size vertically, and filling and resizing horizontally.
390 SZSP_NONE, ///< Display plane with zero size in both directions (none filling and resizing).
392 SZSP_BEGIN = SZSP_VERTICAL, ///< First zero-size plane.
396 * Stacked widgets, widgets all occupying the same space in the window.
397 * #NWID_SELECTION allows for selecting one of several panels (planes) to tbe displayed. All planes must have the same size.
398 * Since all planes are also initialized, switching between different planes can be done while the window is displayed.
400 * There are also a number of special planes (defined in #StackedZeroSizePlanes) that have zero size in one direction (and are stretchable in
401 * the other direction) or have zero size in both directions. They are used to make all child planes of the widget disappear.
402 * Unlike switching between the regular display planes (that all have the same size), switching from or to one of the zero-sized planes means that
403 * a #Windows::ReInit() is needed to re-initialize the window since its size changes.
405 class NWidgetStacked : public NWidgetContainer {
406 public:
407 NWidgetStacked();
409 void SetIndex(int index);
411 void SetupSmallestSize(Window *w, bool init_array);
412 void AssignSizePosition(SizingType sizing, uint x, uint y, uint given_width, uint given_height, bool rtl);
413 /* virtual */ void FillNestedArray(NWidgetBase **array, uint length);
415 /* virtual */ void Draw(const Window *w);
416 /* virtual */ NWidgetCore *GetWidgetFromPos(int x, int y);
418 void SetDisplayedPlane(int plane);
420 int shown_plane; ///< Plane being displayed (for #NWID_SELECTION only).
421 int index; ///< If non-negative, index in the #Window::nested_array.
424 /** Nested widget container flags, */
425 enum NWidContainerFlags {
426 NCB_EQUALSIZE = 0, ///< Containers should keep all their (resizing) children equally large.
428 NC_NONE = 0, ///< All flags cleared.
429 NC_EQUALSIZE = 1 << NCB_EQUALSIZE, ///< Value of the #NCB_EQUALSIZE flag.
431 DECLARE_ENUM_AS_BIT_SET(NWidContainerFlags)
433 /** Container with pre/inter/post child space. */
434 class NWidgetPIPContainer : public NWidgetContainer {
435 public:
436 NWidgetPIPContainer(WidgetType tp, NWidContainerFlags flags = NC_NONE);
438 void SetPIP(uint8 pip_pre, uint8 pip_inter, uint8 pip_post);
440 /* virtual */ void Draw(const Window *w);
441 /* virtual */ NWidgetCore *GetWidgetFromPos(int x, int y);
443 protected:
444 NWidContainerFlags flags; ///< Flags of the container.
445 uint8 pip_pre; ///< Amount of space before first widget.
446 uint8 pip_inter; ///< Amount of space between widgets.
447 uint8 pip_post; ///< Amount of space after last widget.
451 * Horizontal container.
452 * @ingroup NestedWidgets
454 class NWidgetHorizontal : public NWidgetPIPContainer {
455 public:
456 NWidgetHorizontal(NWidContainerFlags flags = NC_NONE);
458 void SetupSmallestSize(Window *w, bool init_array);
459 void AssignSizePosition(SizingType sizing, uint x, uint y, uint given_width, uint given_height, bool rtl);
463 * Horizontal container that doesn't change the direction of the widgets for RTL languages.
464 * @ingroup NestedWidgets
466 class NWidgetHorizontalLTR : public NWidgetHorizontal {
467 public:
468 NWidgetHorizontalLTR(NWidContainerFlags flags = NC_NONE);
470 void AssignSizePosition(SizingType sizing, uint x, uint y, uint given_width, uint given_height, bool rtl);
474 * Vertical container.
475 * @ingroup NestedWidgets
477 class NWidgetVertical : public NWidgetPIPContainer {
478 public:
479 NWidgetVertical(NWidContainerFlags flags = NC_NONE);
481 void SetupSmallestSize(Window *w, bool init_array);
482 void AssignSizePosition(SizingType sizing, uint x, uint y, uint given_width, uint given_height, bool rtl);
486 * Matrix container with implicitly equal sized (virtual) sub-widgets.
487 * This widget must have exactly one sub-widget. After that this sub-widget
488 * is used to draw all of the data within the matrix piece by piece.
489 * DrawWidget and OnClick calls will be done to that sub-widget, where the
490 * 16 high bits are used to encode the index into the matrix.
491 * @ingroup NestedWidgets
493 class NWidgetMatrix : public NWidgetPIPContainer {
494 public:
495 NWidgetMatrix();
497 void SetIndex(int index);
498 void SetColour(Colours colour);
499 void SetClicked(int clicked);
500 void SetCount(int count);
501 void SetScrollbar(Scrollbar *sb);
503 void SetupSmallestSize(Window *w, bool init_array);
504 void AssignSizePosition(SizingType sizing, uint x, uint y, uint given_width, uint given_height, bool rtl);
505 /* virtual */ void FillNestedArray(NWidgetBase **array, uint length);
507 /* virtual */ NWidgetCore *GetWidgetFromPos(int x, int y);
508 /* virtual */ void Draw(const Window *w);
509 protected:
510 int index; ///< If non-negative, index in the #Window::nested_array.
511 Colours colour; ///< Colour of this widget.
512 int clicked; ///< The currently clicked widget.
513 int count; ///< Amount of valid widgets.
514 Scrollbar *sb; ///< The scrollbar we're associated with.
515 private:
516 int widget_w; ///< The width of the child widget including inter spacing.
517 int widget_h; ///< The height of the child widget including inter spacing.
518 int widgets_x; ///< The number of visible widgets in horizontal direction.
519 int widgets_y; ///< The number of visible widgets in vertical direction.
521 void GetScrollOffsets(int &start_x, int &start_y, int &base_offs_x, int &base_offs_y);
526 * Spacer widget.
527 * @ingroup NestedWidgets
529 class NWidgetSpacer : public NWidgetResizeBase {
530 public:
531 NWidgetSpacer(int length, int height);
533 void SetupSmallestSize(Window *w, bool init_array);
534 /* virtual */ void FillNestedArray(NWidgetBase **array, uint length);
536 /* virtual */ void Draw(const Window *w);
537 /* virtual */ void SetDirty(const Window *w) const;
538 /* virtual */ NWidgetCore *GetWidgetFromPos(int x, int y);
542 * Nested widget with a child.
543 * @ingroup NestedWidgets
545 class NWidgetBackground : public NWidgetCore {
546 public:
547 NWidgetBackground(WidgetType tp, Colours colour, int index, NWidgetPIPContainer *child = NULL);
548 ~NWidgetBackground();
550 void Add(NWidgetBase *nwid);
551 void SetPIP(uint8 pip_pre, uint8 pip_inter, uint8 pip_post);
553 void SetupSmallestSize(Window *w, bool init_array);
554 void AssignSizePosition(SizingType sizing, uint x, uint y, uint given_width, uint given_height, bool rtl);
556 /* virtual */ void FillNestedArray(NWidgetBase **array, uint length);
558 /* virtual */ void Draw(const Window *w);
559 /* virtual */ NWidgetCore *GetWidgetFromPos(int x, int y);
560 /* virtual */ NWidgetBase *GetWidgetOfType(WidgetType tp);
562 private:
563 NWidgetPIPContainer *child; ///< Child widget.
567 * Nested widget to display a viewport in a window.
568 * After initializing the nested widget tree, call #InitializeViewport(). After changing the window size,
569 * call #UpdateViewportCoordinates() eg from Window::OnResize().
570 * If the #display_flags field contains the #ND_NO_TRANSPARENCY bit, the viewport will disable transparency.
571 * Shading to grey-scale is controlled with the #ND_SHADE_GREY bit (used for B&W news papers), the #ND_SHADE_DIMMED gives dimmed colours (for colour news papers).
572 * @todo Class derives from #NWidgetCore, but does not use #colour, #widget_data, or #tool_tip.
573 * @ingroup NestedWidgets
575 class NWidgetViewport : public NWidgetCore {
576 public:
577 NWidgetViewport(int index);
579 /* virtual */ void SetupSmallestSize(Window *w, bool init_array);
580 /* virtual */ void Draw(const Window *w);
582 void InitializeViewport(Window *w, uint32 follow_flags, ZoomLevel zoom);
583 void UpdateViewportCoordinates(Window *w);
587 * Scrollbar data structure
589 class Scrollbar {
590 private:
591 const bool is_vertical; ///< Scrollbar has vertical orientation.
592 uint16 count; ///< Number of elements in the list.
593 uint16 cap; ///< Number of visible elements of the scroll bar.
594 uint16 pos; ///< Index of first visible item of the list.
595 uint16 stepsize; ///< Distance to scroll, when pressing the buttons or using the wheel.
597 public:
598 /** Stepping sizes when scrolling */
599 enum ScrollbarStepping {
600 SS_RAW, ///< Step in single units.
601 SS_SMALL, ///< Step in #stepsize units.
602 SS_BIG, ///< Step in #cap units.
605 Scrollbar(bool is_vertical) : is_vertical(is_vertical), stepsize(1)
610 * Gets the number of elements in the list
611 * @return the number of elements
613 inline uint16 GetCount() const
615 return this->count;
619 * Gets the number of visible elements of the scrollbar
620 * @return the number of visible elements
622 inline uint16 GetCapacity() const
624 return this->cap;
628 * Gets the position of the first visible element in the list
629 * @return the position of the element
631 inline uint16 GetPosition() const
633 return this->pos;
637 * Checks whether given current item is visible in the list
638 * @param item to check
639 * @return true iff the item is visible
641 inline bool IsVisible(uint16 item) const
643 return IsInsideBS(item, this->GetPosition(), this->GetCapacity());
647 * Is the scrollbar vertical or not?
648 * @return True iff the scrollbar is vertical.
650 inline bool IsVertical() const
652 return this->is_vertical;
656 * Set the distance to scroll when using the buttons or the wheel.
657 * @param stepsize Scrolling speed.
659 void SetStepSize(uint16 stepsize)
661 assert(stepsize > 0);
662 this->stepsize = stepsize;
666 * Sets the number of elements in the list
667 * @param num the number of elements in the list
668 * @note updates the position if needed
670 void SetCount(int num)
672 assert(num >= 0);
673 assert(num <= MAX_UVALUE(uint16));
675 this->count = num;
676 num -= this->cap;
677 if (num < 0) num = 0;
678 if (num < this->pos) this->pos = num;
682 * Set the capacity of visible elements.
683 * @param capacity the new capacity
684 * @note updates the position if needed
686 void SetCapacity(int capacity)
688 assert(capacity > 0);
689 assert(capacity <= MAX_UVALUE(uint16));
691 this->cap = capacity;
692 if (this->cap + this->pos > this->count) this->pos = max(0, this->count - this->cap);
695 void SetCapacityFromWidget(Window *w, int widget, int padding = 0);
698 * Sets the position of the first visible element
699 * @param position the position of the element
701 void SetPosition(int position)
703 assert(position >= 0);
704 assert(this->count <= this->cap ? (position == 0) : (position + this->cap <= this->count));
705 this->pos = position;
709 * Updates the position of the first visible element by the given amount.
710 * If the position would be too low or high it will be clamped appropriately
711 * @param difference the amount of change requested
712 * @param unit The stepping unit of \a difference
714 void UpdatePosition(int difference, ScrollbarStepping unit = SS_SMALL)
716 if (difference == 0) return;
717 switch (unit) {
718 case SS_SMALL: difference *= this->stepsize; break;
719 case SS_BIG: difference *= this->cap; break;
720 default: break;
722 this->SetPosition(Clamp(this->pos + difference, 0, max(this->count - this->cap, 0)));
726 * Scroll towards the given position; if the item is visible nothing
727 * happens, otherwise it will be shown either at the bottom or top of
728 * the window depending on where in the list it was.
729 * @param position the position to scroll towards.
731 void ScrollTowards(int position)
733 if (position < this->GetPosition()) {
734 /* scroll up to the item */
735 this->SetPosition(position);
736 } else if (position >= this->GetPosition() + this->GetCapacity()) {
737 /* scroll down so that the item is at the bottom */
738 this->SetPosition(position - this->GetCapacity() + 1);
742 int GetScrolledRowFromWidget(int clickpos, const Window * const w, int widget, int padding = 0, int line_height = -1) const;
746 * Nested widget to display and control a scrollbar in a window.
747 * Also assign the scrollbar to other widgets using #SetScrollbar() to make the mousewheel work.
748 * @ingroup NestedWidgets
750 class NWidgetScrollbar : public NWidgetCore, public Scrollbar {
751 public:
752 NWidgetScrollbar(WidgetType tp, Colours colour, int index);
754 /* virtual */ void SetupSmallestSize(Window *w, bool init_array);
755 /* virtual */ void Draw(const Window *w);
757 static void InvalidateDimensionCache();
758 static Dimension GetVerticalDimension();
759 static Dimension GetHorizontalDimension();
761 private:
762 static Dimension vertical_dimension; ///< Cached size of vertical scrollbar button.
763 static Dimension horizontal_dimension; ///< Cached size of horizontal scrollbar button.
767 * Leaf widget.
768 * @ingroup NestedWidgets
770 class NWidgetLeaf : public NWidgetCore {
771 public:
772 NWidgetLeaf(WidgetType tp, Colours colour, int index, uint32 data, StringID tip);
774 /* virtual */ void SetupSmallestSize(Window *w, bool init_array);
775 /* virtual */ void Draw(const Window *w);
777 bool ButtonHit(const Point &pt);
779 static void InvalidateDimensionCache();
781 static Dimension dropdown_dimension; ///< Cached size of a dropdown widget.
782 static Dimension resizebox_dimension; ///< Cached size of a resizebox widget.
783 static Dimension closebox_dimension; ///< Cached size of a closebox widget.
784 private:
785 static Dimension shadebox_dimension; ///< Cached size of a shadebox widget.
786 static Dimension debugbox_dimension; ///< Cached size of a debugbox widget.
787 static Dimension defsizebox_dimension; ///< Cached size of a defsizebox widget.
788 static Dimension stickybox_dimension; ///< Cached size of a stickybox widget.
792 * Return the biggest possible size of a nested widget.
793 * @param base Base size of the widget.
794 * @param max_space Available space for the widget.
795 * @param step Stepsize of the widget.
796 * @return Biggest possible size of the widget, assuming that \a base may only be incremented by \a step size steps.
798 static inline uint ComputeMaxSize(uint base, uint max_space, uint step)
800 if (base >= max_space || step == 0) return base;
801 if (step == 1) return max_space;
802 uint increment = max_space - base;
803 increment -= increment % step;
804 return base + increment;
808 * @defgroup NestedWidgetParts Hierarchical widget parts
809 * To make nested widgets easier to enter, nested widget parts have been created. They allow the tree to be defined in a flat array of parts.
811 * - Leaf widgets start with a #NWidget(WidgetType tp, Colours col, int16 idx) part.
812 * Next, specify its properties with one or more of
813 * - #SetMinimalSize Define the minimal size of the widget.
814 * - #SetFill Define how the widget may grow to make it nicely.
815 * - #SetDataTip Define the data and the tooltip of the widget.
816 * - #SetResize Define how the widget may resize.
817 * - #SetPadding Create additional space around the widget.
819 * - To insert a nested widget tree from an external source, nested widget part #NWidgetFunction exists.
820 * For further customization, the #SetPadding part may be used.
822 * - Space widgets (#NWidgetSpacer) start with a #NWidget(WidgetType tp), followed by one or more of
823 * - #SetMinimalSize Define the minimal size of the widget.
824 * - #SetFill Define how the widget may grow to make it nicely.
825 * - #SetResize Define how the widget may resize.
826 * - #SetPadding Create additional space around the widget.
828 * - Container widgets #NWidgetHorizontal, #NWidgetHorizontalLTR, #NWidgetVertical, and #NWidgetMatrix, start with a #NWidget(WidgetType tp) part.
829 * Their properties are derived from the child widgets so they cannot be specified.
830 * You can however use
831 * - #SetPadding Define additional padding around the container.
832 * - #SetPIP Set additional pre/inter/post child widget space.
834 * Underneath these properties, all child widgets of the container must be defined. To denote that they are childs, add an indent before the nested widget parts of
835 * the child widgets (it has no meaning for the compiler but it makes the widget parts easier to read).
836 * Below the last child widget, use an #EndContainer part. This part should be aligned with the #NWidget part that started the container.
838 * - Stacked widgets #NWidgetStacked map each of their children onto the same space. It behaves like a container, except there is no pre/inter/post space,
839 * so the widget does not support #SetPIP. #SetPadding is allowed though.
840 * Like the other container widgets, below the last child widgets, a #EndContainer part should be used to denote the end of the stacked widget.
842 * - Background widgets #NWidgetBackground start with a #NWidget(WidgetType tp, Colours col, int16 idx) part.
843 * What follows depends on how the widget is used.
844 * - If the widget is used as a leaf widget, that is, to create some space in the window to display a viewport or some text, use the properties of the
845 * leaf widgets to define how it behaves.
846 * - If the widget is used a background behind other widgets, it is considered to be a container widgets. Use the properties listed there to define its
847 * behaviour.
849 * In both cases, the background widget \b MUST end with a #EndContainer widget part.
851 * @see NestedWidgets
855 * Widget part for storing data and tooltip information.
856 * @ingroup NestedWidgetParts
858 struct NWidgetPartDataTip {
859 uint32 data; ///< Data value of the widget.
860 StringID tooltip; ///< Tooltip of the widget.
864 * Widget part for storing basic widget information.
865 * @ingroup NestedWidgetParts
867 struct NWidgetPartWidget {
868 Colours colour; ///< Widget colour.
869 int16 index; ///< Widget index in the widget array.
873 * Widget part for storing padding.
874 * @ingroup NestedWidgetParts
876 struct NWidgetPartPaddings {
877 uint8 top, right, bottom, left; ///< Paddings for all directions.
881 * Widget part for storing pre/inter/post spaces.
882 * @ingroup NestedWidgetParts
884 struct NWidgetPartPIP {
885 uint8 pre, inter, post; ///< Amount of space before/between/after child widgets.
889 * Widget part for storing minimal text line data.
890 * @ingroup NestedWidgetParts
892 struct NWidgetPartTextLines {
893 uint8 lines; ///< Number of text lines.
894 uint8 spacing; ///< Extra spacing around lines.
895 FontSize size; ///< Font size of text lines.
899 * Pointer to function returning a nested widget.
900 * @param biggest_index Pointer to storage for collecting the biggest index used in the nested widget.
901 * @return Nested widget (tree).
902 * @post \c *biggest_index must contain the value of the biggest index in the returned tree.
904 typedef NWidgetBase *NWidgetFunctionType(int *biggest_index);
907 * Partial widget specification to allow NWidgets to be written nested.
908 * @ingroup NestedWidgetParts
910 struct NWidgetPart {
911 WidgetType type; ///< Type of the part. @see NWidgetPartType.
912 union {
913 Point xy; ///< Part with an x/y size.
914 NWidgetPartDataTip data_tip; ///< Part with a data/tooltip.
915 NWidgetPartWidget widget; ///< Part with a start of a widget.
916 NWidgetPartPaddings padding; ///< Part with paddings.
917 NWidgetPartPIP pip; ///< Part with pre/inter/post spaces.
918 NWidgetPartTextLines text_lines; ///< Part with text line data.
919 NWidgetFunctionType *func_ptr; ///< Part with a function call.
920 NWidContainerFlags cont_flags; ///< Part with container flags.
921 } u;
925 * Widget part function for setting the resize step.
926 * @param dx Horizontal resize step. 0 means no horizontal resizing.
927 * @param dy Vertical resize step. 0 means no vertical resizing.
928 * @ingroup NestedWidgetParts
930 static inline NWidgetPart SetResize(int16 dx, int16 dy)
932 NWidgetPart part;
934 part.type = WPT_RESIZE;
935 part.u.xy.x = dx;
936 part.u.xy.y = dy;
938 return part;
942 * Widget part function for setting the minimal size.
943 * @param x Horizontal minimal size.
944 * @param y Vertical minimal size.
945 * @ingroup NestedWidgetParts
947 static inline NWidgetPart SetMinimalSize(int16 x, int16 y)
949 NWidgetPart part;
951 part.type = WPT_MINSIZE;
952 part.u.xy.x = x;
953 part.u.xy.y = y;
955 return part;
959 * Widget part function for setting the minimal text lines.
960 * @param lines Number of text lines.
961 * @param spacing Extra spacing required.
962 * @param size Font size of text.
963 * @ingroup NestedWidgetParts
965 static inline NWidgetPart SetMinimalTextLines(uint8 lines, uint8 spacing, FontSize size = FS_NORMAL)
967 NWidgetPart part;
969 part.type = WPT_MINTEXTLINES;
970 part.u.text_lines.lines = lines;
971 part.u.text_lines.spacing = spacing;
972 part.u.text_lines.size = size;
974 return part;
978 * Widget part function for setting filling.
979 * @param fill_x Horizontal filling step from minimal size.
980 * @param fill_y Vertical filling step from minimal size.
981 * @ingroup NestedWidgetParts
983 static inline NWidgetPart SetFill(uint fill_x, uint fill_y)
985 NWidgetPart part;
987 part.type = WPT_FILL;
988 part.u.xy.x = fill_x;
989 part.u.xy.y = fill_y;
991 return part;
995 * Widget part function for denoting the end of a container
996 * (horizontal, vertical, WWT_FRAME, WWT_INSET, or WWT_PANEL).
997 * @ingroup NestedWidgetParts
999 static inline NWidgetPart EndContainer()
1001 NWidgetPart part;
1003 part.type = WPT_ENDCONTAINER;
1005 return part;
1009 * Widget part function for setting the data and tooltip.
1010 * @param data Data of the widget.
1011 * @param tip Tooltip of the widget.
1012 * @ingroup NestedWidgetParts
1014 static inline NWidgetPart SetDataTip(uint32 data, StringID tip)
1016 NWidgetPart part;
1018 part.type = WPT_DATATIP;
1019 part.u.data_tip.data = data;
1020 part.u.data_tip.tooltip = tip;
1022 return part;
1026 * Widget part function for setting the data and tooltip of WWT_MATRIX widgets
1027 * @param cols Number of columns. \c 0 means to use draw columns with width according to the resize step size.
1028 * @param rows Number of rows. \c 0 means to use draw rows with height according to the resize step size.
1029 * @param tip Tooltip of the widget.
1030 * @ingroup NestedWidgetParts
1032 static inline NWidgetPart SetMatrixDataTip(uint8 cols, uint8 rows, StringID tip)
1034 return SetDataTip((rows << MAT_ROW_START) | (cols << MAT_COL_START), tip);
1038 * Widget part function for setting additional space around a widget.
1039 * Parameters start above the widget, and are specified in clock-wise direction.
1040 * @param top The padding above the widget.
1041 * @param right The padding right of the widget.
1042 * @param bottom The padding below the widget.
1043 * @param left The padding left of the widget.
1044 * @ingroup NestedWidgetParts
1046 static inline NWidgetPart SetPadding(uint8 top, uint8 right, uint8 bottom, uint8 left)
1048 NWidgetPart part;
1050 part.type = WPT_PADDING;
1051 part.u.padding.top = top;
1052 part.u.padding.right = right;
1053 part.u.padding.bottom = bottom;
1054 part.u.padding.left = left;
1056 return part;
1060 * Widget part function for setting a padding.
1061 * @param padding The padding to use for all directions.
1062 * @ingroup NestedWidgetParts
1064 static inline NWidgetPart SetPadding(uint8 padding)
1066 return SetPadding(padding, padding, padding, padding);
1070 * Widget part function for setting a pre/inter/post spaces.
1071 * @param pre The amount of space before the first widget.
1072 * @param inter The amount of space between widgets.
1073 * @param post The amount of space after the last widget.
1074 * @ingroup NestedWidgetParts
1076 static inline NWidgetPart SetPIP(uint8 pre, uint8 inter, uint8 post)
1078 NWidgetPart part;
1080 part.type = WPT_PIPSPACE;
1081 part.u.pip.pre = pre;
1082 part.u.pip.inter = inter;
1083 part.u.pip.post = post;
1085 return part;
1089 * Attach a scrollbar to a widget.
1090 * The scrollbar is controlled when using the mousewheel on the widget.
1091 * Multiple widgets can refer to the same scrollbar to make the mousewheel work in all of them.
1092 * @param index Widget index of the scrollbar.
1093 * @ingroup NestedWidgetParts
1095 static inline NWidgetPart SetScrollbar(int index)
1097 NWidgetPart part;
1099 part.type = WPT_SCROLLBAR;
1100 part.u.widget.index = index;
1102 return part;
1106 * Widget part function for starting a new 'real' widget.
1107 * @param tp Type of the new nested widget.
1108 * @param col Colour of the new widget.
1109 * @param idx Index of the widget in the widget array.
1110 * @note with #WWT_PANEL, #WWT_FRAME, #WWT_INSET, a new container is started.
1111 * Child widgets must have a index bigger than the parent index.
1112 * @ingroup NestedWidgetParts
1114 static inline NWidgetPart NWidget(WidgetType tp, Colours col, int16 idx = -1)
1116 NWidgetPart part;
1118 part.type = tp;
1119 part.u.widget.colour = col;
1120 part.u.widget.index = idx;
1122 return part;
1126 * Widget part function for starting a new horizontal container, vertical container, or spacer widget.
1127 * @param tp Type of the new nested widget, #NWID_HORIZONTAL(_LTR), #NWID_VERTICAL, #NWID_SPACER, #NWID_SELECTION, and #NWID_MATRIX.
1128 * @param cont_flags Flags for the containers (#NWID_HORIZONTAL(_LTR) and #NWID_VERTICAL).
1129 * @ingroup NestedWidgetParts
1131 static inline NWidgetPart NWidget(WidgetType tp, NWidContainerFlags cont_flags = NC_NONE)
1133 NWidgetPart part;
1135 part.type = tp;
1136 part.u.cont_flags = cont_flags;
1138 return part;
1142 * Obtain a nested widget (sub)tree from an external source.
1143 * @param func_ptr Pointer to function that returns the tree.
1144 * @ingroup NestedWidgetParts
1146 static inline NWidgetPart NWidgetFunction(NWidgetFunctionType *func_ptr)
1148 NWidgetPart part;
1150 part.type = WPT_FUNCTION;
1151 part.u.func_ptr = func_ptr;
1153 return part;
1156 NWidgetContainer *MakeNWidgets(const NWidgetPart *parts, int count, int *biggest_index, NWidgetContainer *container);
1157 NWidgetContainer *MakeWindowNWidgetTree(const NWidgetPart *parts, int count, int *biggest_index, NWidgetStacked **shade_select);
1159 NWidgetBase *MakeCompanyButtonRows(int *biggest_index, int widget_first, int widget_last, int max_length, StringID button_tooltip);
1161 #endif /* WIDGET_TYPE_H */