cpp/openttd-patchpack/source Changeset - r11794:2780553402ea

Changeset - r11794:2780553402ea

Parent rev.

Child rev.

[Not reviewed]

master

0 3 0

alberth - 15 years ago 2009-04-30 17:35:38
alberth@openttd.org

(svn r16189) -Doc: Additions and improvement of (mainly) nested widgets/widget-parts doxygen docs.

3 files changed with 134 insertions and 20 deletions:

src/tile_cmd.h

src/widget.cpp

src/widget_type.h

0 comments (0 inline, 0 general)

src/tile_cmd.h

➞

Show inline comments

@@ @@ -69,7 +69,7 @@ typedef uint GetSlopeZProc(TileIndex til @@
 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
  */

src/widget.cpp

➞

Show inline comments

@@ @@ -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, byt @@
 	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 wid @@
+}
 /* == 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_ @@
 	this->pip_post = pip_post;
+}
 /** Horizontal container widget. */
 NWidgetHorizontal::NWidgetHorizontal() : NWidgetContainer(NWID_HORIZONTAL)
+{
+}
@@ @@ -986,6 +1020,7 @@ void NWidgetHorizontal::StoreWidgets(Wid @@
+	}
+}
 /** Horizontal left-to-right container widget. */
 NWidgetHorizontalLTR::NWidgetHorizontalLTR() : NWidgetHorizontal()
+{
 	this->type = NWID_HORIZONTAL_LTR;
@@ @@ -1001,6 +1036,7 @@ void NWidgetHorizontalLTR::StoreWidgets( @@
 	NWidgetHorizontal::StoreWidgets(widgets, length, left_moving, top_moving, false);
+}
 /** Vertical container widget. */
 NWidgetVertical::NWidgetVertical() : NWidgetContainer(NWID_VERTICAL)
+{
+}
@@ @@ -1224,6 +1260,7 @@ void NWidgetBackground::StoreWidgets(Wid @@
 /**
  * Nested leaf 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.
@@ @@ -1314,6 +1351,7 @@ NWidgetLeaf::NWidgetLeaf(WidgetType tp, @@
  * @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 NWidgetP @@
  * @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)
+{

src/widget_type.h

➞

Show inline comments

@@ @@ -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(int1 @@
 /**
  * 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(Poin @@
  * 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 @@
 /**
  * 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 @@
  * 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 @@
 /**
  * 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(uin @@
 /**
  * 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(NWi @@
+}
 /**
  * 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(uin @@
 /**
  * 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(uin @@
  * @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 p @@
  * @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(Widget @@
 /**
  * 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(Widget @@
 	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;

0 comments (0 inline, 0 general)