summaryrefslogtreecommitdiff
diff options
context:
space:
mode:
-rw-r--r--src/tile_cmd.h2
-rw-r--r--src/widget.cpp53
-rw-r--r--src/widget_type.h107
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;