diff options
| -rw-r--r-- | src/tile_cmd.h | 2 | ||||
| -rw-r--r-- | src/widget.cpp | 53 | ||||
| -rw-r--r-- | src/widget_type.h | 107 |
3 files changed, 138 insertions, 24 deletions
diff --git a/src/tile_cmd.h b/src/tile_cmd.h index e7c178778..e60105900 100644 --- a/src/tile_cmd.h +++ b/src/tile_cmd.h @@ -69,7 +69,7 @@ typedef uint GetSlopeZProc(TileIndex tile, uint x, uint y); typedef CommandCost ClearTileProc(TileIndex tile, DoCommandFlag flags); /** - * Tile callback function signature for obtaining accepted carog of a tile + * Tile callback function signature for obtaining accepted cargo of a tile * @param tile Tile queried for its accepted cargo * @param res Storage destination of the cargo accepted */ diff --git a/src/widget.cpp b/src/widget.cpp index a861a0d44..e47e942c7 100644 --- a/src/widget.cpp +++ b/src/widget.cpp @@ -12,8 +12,8 @@ #include "table/sprites.h" #include "table/strings.h" -static const char *UPARROW = "\xEE\x8A\xA0"; -static const char *DOWNARROW = "\xEE\x8A\xAA"; +static const char *UPARROW = "\xEE\x8A\xA0"; ///< String containing an upwards pointing arrow. +static const char *DOWNARROW = "\xEE\x8A\xAA"; ///< String containing a downwards pointing arrow. /** * Compute the vertical position of the draggable part of scrollbar @@ -524,6 +524,13 @@ void Window::DrawWidgets() const } +/** + * Evenly distribute the combined horizontal length of two consecutive widgets. + * @param w Window containing the widgets. + * @param a Left widget to resize. + * @param b Right widget to resize. + * @note Widgets are assumed to lie against each other. + */ static void ResizeWidgets(Window *w, byte a, byte b) { int16 offset = w->widget[a].left; @@ -534,6 +541,14 @@ static void ResizeWidgets(Window *w, byte a, byte b) w->widget[b].left = w->widget[a].right + 1; } +/** + * Evenly distribute the combined horizontal length of three consecutive widgets. + * @param w Window containing the widgets. + * @param a Left widget to resize. + * @param b Middle widget to resize. + * @param c Right widget to resize. + * @note Widgets are assumed to lie against each other. + */ static void ResizeWidgets(Window *w, byte a, byte b, byte c) { int16 offset = w->widget[a].left; @@ -638,7 +653,25 @@ void Window::DrawSortButtonState(int widget, SortButtonState state) const } -/* == Nested widgets == */ +/** + * @defgroup NestedWidgets Hierarchical widgets. + * Hierarchical widgets, also known as nested widgets, are widgets stored in a tree. At the leafs of the tree are (mostly) the 'real' widgets + * visible to the user. At higher levels, widgets get organized in container widgets, until all widgets of the window are merged. + * + * A leaf widget is one of + * - #NWidgetLeaf for widgets visible for the user, or + * - #NWidgetSpacer for creating (flexible) empty space between widgets. + * + * A container widget is one of + * - #NWidgetHorizontal for organizing child widgets in a (horizontal) row. The row switches order depending on the language setting (thus supporting + * right-to-left languages), + * - #NWidgetHorizontalLTR for organizing child widgets in a (horizontal) row, always in the same order. All childs below this container will also + * never swap order. + * - #NWidgetVertical for organizing child widgets underneath each other. + * - #NWidgetBackground for adding a background behind its child widget. + * + * @see NestedWidgetParts + */ /** * Base class constructor. @@ -878,6 +911,7 @@ void NWidgetContainer::SetPIP(uint8 pip_pre, uint8 pip_inter, uint8 pip_post) this->pip_post = pip_post; } +/** Horizontal container widget. */ NWidgetHorizontal::NWidgetHorizontal() : NWidgetContainer(NWID_HORIZONTAL) { } @@ -986,6 +1020,7 @@ void NWidgetHorizontal::StoreWidgets(Widget *widgets, int length, bool left_movi } } +/** Horizontal left-to-right container widget. */ NWidgetHorizontalLTR::NWidgetHorizontalLTR() : NWidgetHorizontal() { this->type = NWID_HORIZONTAL_LTR; @@ -1001,6 +1036,7 @@ void NWidgetHorizontalLTR::StoreWidgets(Widget *widgets, int length, bool left_m NWidgetHorizontal::StoreWidgets(widgets, length, left_moving, top_moving, false); } +/** Vertical container widget. */ NWidgetVertical::NWidgetVertical() : NWidgetContainer(NWID_VERTICAL) { } @@ -1223,10 +1259,11 @@ void NWidgetBackground::StoreWidgets(Widget *widgets, int length, bool left_movi /** * Nested leaf widget. - * @param tp Type of leaf widget. - * @param index Index in the widget array used by the window system. - * @param data Data of the widget. - * @param tip Tooltip of the widget. + * @param tp Type of leaf widget. + * @param colour Colour of the leaf widget. + * @param index Index in the widget array used by the window system. + * @param data Data of the widget. + * @param tip Tooltip of the widget. */ NWidgetLeaf::NWidgetLeaf(WidgetType tp, Colours colour, int index, uint16 data, StringID tip) : NWidgetCore(tp, colour, true, true, data, tip) { @@ -1314,6 +1351,7 @@ NWidgetLeaf::NWidgetLeaf(WidgetType tp, Colours colour, int index, uint16 data, * @param rtl Direction of the language. * @return Widget array with the converted widgets. * @note Caller should release returned widget array with \c free(widgets). + * @ingroup NestedWidgets */ Widget *InitializeNWidgets(NWidgetBase *nwid, bool rtl) { @@ -1595,6 +1633,7 @@ static int MakeWidgetTree(const NWidgetPart *parts, int count, NWidgetBase *pare * @param parts Array with parts of the widgets. * @param count Length of the \a parts array. * @return Root of the nested widget tree, a vertical container containing the entire GUI. + * @ingroup NestedWidgetParts */ NWidgetContainer *MakeNWidgets(const NWidgetPart *parts, int count) { diff --git a/src/widget_type.h b/src/widget_type.h index f34be9bf1..0a7772163 100644 --- a/src/widget_type.h +++ b/src/widget_type.h @@ -144,6 +144,7 @@ struct Widget { /** * Baseclass for nested widgets. + * @ingroup NestedWidgets */ class NWidgetBase : public ZeroedMemoryAllocator { public: @@ -174,7 +175,8 @@ public: uint8 padding_left; ///< Paddings added to the left of the widget. Managed by parent container widget. }; -/** Base class for a resizable nested widget. */ +/** Base class for a resizable nested widget. + * @ingroup NestedWidgets */ class NWidgetResizeBase : public NWidgetBase { public: NWidgetResizeBase(WidgetType tp, bool fill_x, bool fill_y); @@ -186,7 +188,8 @@ public: void AssignMinimalPosition(uint x, uint y, uint given_width, uint given_height, bool allow_resize_x, bool allow_resize_y, bool rtl); }; -/** Base class for a 'real' widget. */ +/** Base class for a 'real' widget. + * @ingroup NestedWidgets */ class NWidgetCore : public NWidgetResizeBase { public: NWidgetCore(WidgetType tp, Colours colour, bool def_fill_x, bool def_fill_y, uint16 widget_data, StringID tool_tip); @@ -203,7 +206,8 @@ public: StringID tool_tip; ///< Tooltip of the widget. @see Widget::tootips }; -/** Baseclass for container widgets. */ +/** Baseclass for container widgets. + * @ingroup NestedWidgets */ class NWidgetContainer : public NWidgetBase { public: NWidgetContainer(WidgetType tp); @@ -224,7 +228,8 @@ protected: NWidgetBase *tail; ///< Pointer to last widget in container. }; -/** Horizontal container. */ +/** Horizontal container. + * @ingroup NestedWidgets */ class NWidgetHorizontal : public NWidgetContainer { public: NWidgetHorizontal(); @@ -235,7 +240,8 @@ public: void StoreWidgets(Widget *widgets, int length, bool left_moving, bool top_moving, bool rtl); }; -/** Horizontal container that doesn't change the direction of the widgets for RTL languages. */ +/** Horizontal container that doesn't change the direction of the widgets for RTL languages. + * @ingroup NestedWidgets */ class NWidgetHorizontalLTR : public NWidgetHorizontal { public: NWidgetHorizontalLTR(); @@ -245,7 +251,8 @@ public: void StoreWidgets(Widget *widgets, int length, bool left_moving, bool top_moving, bool rtl); }; -/** Vertical container */ +/** Vertical container. + * @ingroup NestedWidgets */ class NWidgetVertical : public NWidgetContainer { public: NWidgetVertical(); @@ -257,7 +264,8 @@ public: }; -/** Spacer widget */ +/** Spacer widget. + * @ingroup NestedWidgets */ class NWidgetSpacer : public NWidgetResizeBase { public: NWidgetSpacer(int length, int height); @@ -266,7 +274,8 @@ public: void StoreWidgets(Widget *widgets, int length, bool left_moving, bool top_moving, bool rtl); }; -/** Nested widget with a child. */ +/** Nested widget with a child. + * @ingroup NestedWidgets */ class NWidgetBackground : public NWidgetCore { public: NWidgetBackground(WidgetType tp, Colours colour, int index, NWidgetContainer *child = NULL); @@ -283,7 +292,8 @@ private: NWidgetContainer *child; ///< Child widget. }; -/** Leaf widget. */ +/** Leaf widget. + * @ingroup NestedWidgets */ class NWidgetLeaf : public NWidgetCore { public: NWidgetLeaf(WidgetType tp, Colours colour, int index, uint16 data, StringID tip); @@ -292,26 +302,71 @@ public: Widget *InitializeNWidgets(NWidgetBase *nwid, bool rtl = false); bool CompareWidgetArrays(const Widget *orig, const Widget *gen, bool report = true); -/* == Nested widget parts == */ +/** + * @defgroup NestedWidgetParts Hierarchical widget parts + * 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. + * + * - Leaf widgets start with a #NWidget(WidgetType tp, Colours col, int16 idx) part. + * Next, specify its properties with one or more of + * - #SetMinimalSize Define the minimal size of the widget. + * - #SetFill Define how the widget may grow to make it nicely. + * - #SetDataTip Define the data and the tooltip of the widget. + * - #SetResize Define how the widget may resize. + * - #SetPadding Create additional space around the widget. + * + * - To insert a nested widget tree from an external source, nested widget part #NWidgetFunction exists. + * For further customization, the #SetPadding part may be used. + * + * - Space widgets (#NWidgetSpacer) start with a #NWidget(WidgetType tp), followed by one or more of + * - #SetMinimalSize Define the minimal size of the widget. + * - #SetFill Define how the widget may grow to make it nicely. + * - #SetResize Define how the widget may resize. + * - #SetPadding Create additional space around the widget. + * + * - Container widgets #NWidgetHorizontal, #NWidgetHorizontalLTR, and #NWidgetVertical, start with a #NWidget(WidgetType tp) part. + * Their properties are derived from the child widgets so they cannot be specified. + * You can however use + * - #SetPadding Define additional padding around the container. + * - #SetPIP Set additional pre/inter/post child widget space. + * . + * 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 + * the child widgets (it has no meaning for the compiler but it makes the widget parts easier to read). + * Below the last child widget, use an #EndContainer part. This part should be aligned with the #NWidget part that started the container. + * + * - Background widgets #NWidgetBackground start with a #NWidget(WidgetType tp, Colours col, int16 idx) part. + * What follows depends on how the widget is used. + * - 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 + * leaf widgets to define how it behaves. + * - 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 + * behaviour. + * . + * In both cases, the background widget \b MUST end with a #EndContainer widget part. + * + * @see NestedWidgets + */ -/** Widget part for storing data and tooltip information. */ +/** Widget part for storing data and tooltip information. + * @ingroup NestedWidgetParts */ struct NWidgetPartDataTip { uint16 data; ///< Data value of the widget. StringID tooltip; ///< Tooltip of the widget. }; -/** Widget part for storing basic widget information. */ +/** Widget part for storing basic widget information. + * @ingroup NestedWidgetParts */ struct NWidgetPartWidget { Colours colour; ///< Widget colour. int16 index; ///< Widget index in the widget array. }; -/** Widget part for storing padding. */ +/** Widget part for storing padding. + * @ingroup NestedWidgetParts */ struct NWidgetPartPaddings { uint8 top, right, bottom, left; ///< Paddings for all directions. }; -/** Widget part for storing pre/inter/post spaces. */ +/** Widget part for storing pre/inter/post spaces. + * @ingroup NestedWidgetParts */ struct NWidgetPartPIP { uint8 pre, inter, post; ///< Amount of space before/between/after child widgets. }; @@ -319,7 +374,8 @@ struct NWidgetPartPIP { /** Pointer to function returning a nested widget. */ typedef NWidgetBase *NWidgetFunctionType(); -/** Partial widget specification to allow NWidgets to be written nested. */ +/** Partial widget specification to allow NWidgets to be written nested. + * @ingroup NestedWidgetParts */ struct NWidgetPart { WidgetType type; ///< Type of the part. @see NWidgetPartType. union { @@ -338,6 +394,7 @@ struct NWidgetPart { * Widget part function for setting the resize step. * @param dx Horizontal resize step. 0 means no horizontal resizing. * @param dy Vertical resize step. 0 means no horizontal resizing. + * @ingroup NestedWidgetParts */ static inline NWidgetPart SetResize(int16 dx, int16 dy) { @@ -353,6 +410,7 @@ static inline NWidgetPart SetResize(int16 dx, int16 dy) /** * Widget part function for using a pointer to set the resize step. * @param ptr Pointer to horizontal and vertical resize step. + * @ingroup NestedWidgetParts */ static inline NWidgetPart SetResize(Point *ptr) { @@ -368,6 +426,7 @@ static inline NWidgetPart SetResize(Point *ptr) * Widget part function for setting the minimal size. * @param dx Horizontal minimal size. * @param dy Vertical minimal size. + * @ingroup NestedWidgetParts */ static inline NWidgetPart SetMinimalSize(int16 x, int16 y) { @@ -383,6 +442,7 @@ static inline NWidgetPart SetMinimalSize(int16 x, int16 y) /** * Widget part function for using a pointer to set the minimal size. * @param ptr Pointer to horizontal and vertical minimal size. + * @ingroup NestedWidgetParts */ static inline NWidgetPart SetMinimalSize(Point *ptr) { @@ -398,6 +458,7 @@ static inline NWidgetPart SetMinimalSize(Point *ptr) * Widget part function for setting filling. * @param x_fill Allow horizontal filling from minimal size. * @param y_fill Allow vertical filling from minimal size. + * @ingroup NestedWidgetParts */ static inline NWidgetPart SetFill(bool x_fill, bool y_fill) { @@ -413,6 +474,7 @@ static inline NWidgetPart SetFill(bool x_fill, bool y_fill) /** * Widget part function for denoting the end of a container * (horizontal, vertical, WWT_FRAME, WWT_INSET, or WWT_PANEL). + * @ingroup NestedWidgetParts */ static inline NWidgetPart EndContainer() { @@ -426,6 +488,7 @@ static inline NWidgetPart EndContainer() /** Widget part function for setting the data and tooltip. * @param data Data of the widget. * @param tip Tooltip of the widget. + * @ingroup NestedWidgetParts */ static inline NWidgetPart SetDataTip(uint16 data, StringID tip) { @@ -441,6 +504,7 @@ static inline NWidgetPart SetDataTip(uint16 data, StringID tip) /** * Widget part function for setting the data and tooltip via a pointer. * @param ptr Pointer to the data and tooltip of the widget. + * @ingroup NestedWidgetParts */ static inline NWidgetPart SetDataTip(NWidgetPartDataTip *ptr) { @@ -453,11 +517,13 @@ static inline NWidgetPart SetDataTip(NWidgetPartDataTip *ptr) } /** - * Widget part function for setting a padding. + * Widget part function for setting additional space around a widget. + * Parameters start above the widget, and are specified in clock-wise direction. * @param top The padding above the widget. * @param right The padding right of the widget. * @param bottom The padding below the widget. * @param left The padding left of the widget. + * @ingroup NestedWidgetParts */ static inline NWidgetPart SetPadding(uint8 top, uint8 right, uint8 bottom, uint8 left) { @@ -475,6 +541,7 @@ static inline NWidgetPart SetPadding(uint8 top, uint8 right, uint8 bottom, uint8 /** * Widget part function for setting a padding. * @param padding The padding to use for all directions. + * @ingroup NestedWidgetParts */ static inline NWidgetPart SetPadding(uint8 padding) { @@ -486,6 +553,7 @@ static inline NWidgetPart SetPadding(uint8 padding) * @param pre The amount of space before the first widget. * @param inter The amount of space between widgets. * @param post The amount of space after the last widget. + * @ingroup NestedWidgetParts */ static inline NWidgetPart SetPIP(uint8 pre, uint8 inter, uint8 post) { @@ -506,6 +574,7 @@ static inline NWidgetPart SetPIP(uint8 pre, uint8 inter, uint8 post) * @param idx Index of the widget in the widget array. * @note with #WWT_PANEL, #WWT_FRAME, #WWT_INSET, a new container is started. * Child widgets must have a index bigger than the parent index. + * @ingroup NestedWidgetParts */ static inline NWidgetPart NWidget(WidgetType tp, Colours col, int16 idx) { @@ -521,6 +590,7 @@ static inline NWidgetPart NWidget(WidgetType tp, Colours col, int16 idx) /** * Widget part function for starting a new horizontal container, vertical container, or spacer widget. * @param tp Type of the new nested widget, #NWID_HORIZONTAL(_LTR), #NWID_VERTICAL, or #NWID_SPACER + * @ingroup NestedWidgetParts */ static inline NWidgetPart NWidget(WidgetType tp) { @@ -531,6 +601,11 @@ static inline NWidgetPart NWidget(WidgetType tp) return part; } +/** + * Obtain a nested widget (sub)tree from an external source. + * @param func_ptr Pointer to function that returns the tree. + * @ingroup NestedWidgetParts + */ static inline NWidgetPart NWidgetFunction(NWidgetFunctionType *func_ptr) { NWidgetPart part; |