# Hierarchical widget parts

To make nested widgets easier to enter, nested widget parts have been created. More...

## Data Structures

struct | NWidgetPartDataTip
| Widget part for storing data and tooltip information. More...
struct | NWidgetPartWidget
| Widget part for storing basic widget information. More...
struct | NWidgetPartPaddings
| Widget part for storing padding. More...
struct | NWidgetPartPIP
| Widget part for storing pre/inter/post spaces. More...
struct | NWidgetPartTextLines
| Widget part for storing minimal text line data. More...
struct | NWidgetPart
| Partial widget specification to allow NWidgets to be written nested. More...

## Functions

NWidgetContainer * | MakeNWidgets (const NWidgetPart *parts, int count, int *biggest_index, NWidgetContainer *container)
| Construct a nested widget tree from an array of parts.
NWidgetContainer * | MakeWindowNWidgetTree (const NWidgetPart *parts, int count, int *biggest_index, NWidgetStacked **shade_select)
| Make a nested widget tree for a window from a parts array.
static NWidgetPart | SetResize (int16 dx, int16 dy)
| Widget part function for setting the resize step.
static NWidgetPart | SetMinimalSize (int16 x, int16 y)
| Widget part function for setting the minimal size.
static NWidgetPart | SetMinimalTextLines (uint8 lines, uint8 spacing, FontSize size=FS_NORMAL)
| Widget part function for setting the minimal text lines.
static NWidgetPart | SetFill (uint fill_x, uint fill_y)
| Widget part function for setting filling.
static NWidgetPart | EndContainer ()
| Widget part function for denoting the end of a container (horizontal, vertical, WWT_FRAME, WWT_INSET, or WWT_PANEL).
static NWidgetPart | SetDataTip (uint16 data, StringID tip)
| Widget part function for setting the data and tooltip.
static NWidgetPart | SetPadding (uint8 top, uint8 right, uint8 bottom, uint8 left)
| Widget part function for setting additional space around a widget.
static NWidgetPart | SetPadding (uint8 padding)
| Widget part function for setting a padding.
static NWidgetPart | SetPIP (uint8 pre, uint8 inter, uint8 post)
| Widget part function for setting a pre/inter/post spaces.
static NWidgetPart | NWidget (WidgetType tp, Colours col, int16 idx=-1)
| Widget part function for starting a new 'real' widget.
static NWidgetPart | NWidget (WidgetType tp, NWidContainerFlags cont_flags=NC_NONE)
| Widget part function for starting a new horizontal container, vertical container, or spacer widget.
static NWidgetPart | NWidgetFunction (NWidgetFunctionType *func_ptr)
| Obtain a nested widget (sub)tree from an external source.

## Detailed Description

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.

- Stacked widgets NWidgetStacked map each of their childs onto the same space. It behaves like a container, except there is no pre/inter/post space, so the widget does not support SetPIP. SetPadding is allowed though. Like the other container widgets, below the last child widgets, a EndContainer part should be used to denote the end of the stacked widget.

- 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 MUST end with a EndContainer widget part.

See also:
  Hierarchical widgets

## Function Documentation

NWidgetContainer* MakeNWidgets | ( | const NWidgetPart * | parts,
|  | int | count,
|  | int * | biggest_index,
|  | NWidgetContainer * | container |
| ) |  |  |

Construct a nested widget tree from an array of parts.

Parameters:

  | parts | Array with parts of the widgets.
  | count | Length of the parts array.
  | biggest_index | Pointer to biggest nested widget index collected in the tree.
  | container | Container to add the nested widgets to. In case it is NULL a vertical container is used.

Returns:
  Root of the nested widget tree, a vertical container containing the entire GUI.

Precondition:
  `biggest_index` != NULL

Postcondition:
  `*biggest_index` contains the largest widget index of the tree and `-1` if no index is used.

Definition at line 2342 of file widget.cpp.

References MakeWidgetTree().

Referenced by MakeWindowNWidgetTree().

NWidgetContainer* MakeWindowNWidgetTree | ( | const NWidgetPart * | parts,
|  | int | count,
|  | int * | biggest_index,
|  | NWidgetStacked ** | shade_select |
| ) |  |  |

Make a nested widget tree for a window from a parts array.

Besides loading, it inserts a shading selection widget between the title bar and the window body if the first widget in the parts array looks like a title bar (it is a horizontal container with a caption widget) and has a shade box widget.

Parameters:

  | parts | Array with parts of the widgets.
  | count | Length of the parts array.
  | biggest_index | Pointer to biggest nested widget index collected in the tree.
  `[out]` | shade_select | Pointer to the inserted shade selection widget (`NULL` if not unserted).

Returns:
  Root of the nested widget tree, a vertical container containing the entire GUI.

Precondition:
  `biggest_index` != NULL

Postcondition:
  `*biggest_index` contains the largest widget index of the tree and `-1` if no index is used.

Definition at line 2363 of file widget.cpp.

References NWidgetContainer::Add(), NWidgetContainer::GetWidgetOfType(), MakeNWidgets(), MakeWidgetTree(), max(), WWT_CAPTION, and WWT_SHADEBOX.

Referenced by Window::CreateNestedTree().

static NWidgetPart NWidget | ( | WidgetType | tp,
|  | NWidContainerFlags | cont_flags = `NC_NONE` |
| ) |  |  | `[inline, static]`

Widget part function for starting a new horizontal container, vertical container, or spacer widget.

Parameters:

  | tp | Type of the new nested widget, NWID_HORIZONTAL(_LTR), NWID_VERTICAL, NWID_SPACER, or NWID_SELECTION.
  | cont_flags | Flags for the containers (NWID_HORIZONTAL(_LTR) and NWID_VERTICAL).

Definition at line 769 of file widget_type.h.

References NWidgetPart::cont_flags, and NWidgetPart::type.

static NWidgetPart NWidget | ( | WidgetType | tp,
|  | Colours | col,
|  | int16 | idx = `-1` |
| ) |  |  | `[inline, static]`

Widget part function for starting a new 'real' widget.

Parameters:

  | tp | Type of the new nested widget.
  | col | Colour of the new widget.
  | 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.

Definition at line 752 of file widget_type.h.

References NWidgetPartWidget::colour, NWidgetPartWidget::index, NWidgetPart::type, and NWidgetPart::widget.

static NWidgetPart NWidgetFunction | ( | NWidgetFunctionType * | func_ptr | ) | `[inline, static]`

Obtain a nested widget (sub)tree from an external source.

Parameters:

  | func_ptr | Pointer to function that returns the tree.

Definition at line 784 of file widget_type.h.

References NWidgetPart::func_ptr, NWidgetPart::type, and WPT_FUNCTION.

static NWidgetPart SetDataTip | ( | uint16 | data,
|  | StringID | tip |
| ) |  |  | `[inline, static]`

Widget part function for setting the data and tooltip.

Parameters:

  | data | Data of the widget.
  | tip | Tooltip of the widget.

Definition at line 681 of file widget_type.h.

References NWidgetPartDataTip::data, NWidgetPart::data_tip, NWidgetPartDataTip::tooltip, NWidgetPart::type, and WPT_DATATIP.

Referenced by GameOptionsWindow::OnInvalidateData().

static NWidgetPart SetFill | ( | uint | fill_x,
|  | uint | fill_y |
| ) |  |  | `[inline, static]`

Widget part function for setting filling.

Parameters:

  | fill_x | Horizontal filling step from minimal size.
  | fill_y | Vertical filling step from minimal size.

Definition at line 651 of file widget_type.h.

References NWidgetPart::type, WPT_FILL, and NWidgetPart::xy.

static NWidgetPart SetMinimalSize | ( | int16 | x,
|  | int16 | y |
| ) |  |  | `[inline, static]`

Widget part function for setting the minimal size.

Parameters:

  | x | Horizontal minimal size.
  | y | Vertical minimal size.

Definition at line 615 of file widget_type.h.

References NWidgetPart::type, WPT_MINSIZE, and NWidgetPart::xy.

static NWidgetPart SetMinimalTextLines | ( | uint8 | lines,
|  | uint8 | spacing,
|  | FontSize | size = `FS_NORMAL` |
| ) |  |  | `[inline, static]`

Widget part function for setting the minimal text lines.

Parameters:

  | lines | Number of text lines.
  | spacing | Extra spacing required.
  | size | Font size of text.

Definition at line 633 of file widget_type.h.

References NWidgetPartTextLines::lines, NWidgetPartTextLines::size, NWidgetPartTextLines::spacing, NWidgetPart::text_lines, NWidgetPart::type, and WPT_MINTEXTLINES.

static NWidgetPart SetPadding | ( | uint8 | padding | ) | `[inline, static]`

Widget part function for setting a padding.

Parameters:

  | padding | The padding to use for all directions.

Definition at line 719 of file widget_type.h.

References SetPadding().

static NWidgetPart SetPadding | ( | uint8 | top,
|  | uint8 | right,
|  | uint8 | bottom,
|  | uint8 | left |
| ) |  |  | `[inline, static]`

Widget part function for setting additional space around a widget.

Parameters start above the widget, and are specified in clock-wise direction.

Parameters:

  | top | The padding above the widget.
  | right | The padding right of the widget.
  | bottom | The padding below the widget.
  | left | The padding left of the widget.

Definition at line 701 of file widget_type.h.

References NWidgetPartPaddings::left, NWidgetPart::padding, NWidgetPart::type, and WPT_PADDING.

Referenced by SetPadding().

static NWidgetPart SetPIP | ( | uint8 | pre,
|  | uint8 | inter,
|  | uint8 | post |
| ) |  |  | `[inline, static]`

Widget part function for setting a pre/inter/post spaces.

Parameters:

  | pre | The amount of space before the first widget.
  | inter | The amount of space between widgets.
  | post | The amount of space after the last widget.

Definition at line 731 of file widget_type.h.

References NWidgetPart::pip, NWidgetPartPIP::post, NWidgetPart::type, and WPT_PIPSPACE.

static NWidgetPart SetResize | ( | int16 | dx,
|  | int16 | dy |
| ) |  |  | `[inline, static]`

Widget part function for setting the resize step.

Parameters:

  | dx | Horizontal resize step. 0 means no horizontal resizing.
  | dy | Vertical resize step. 0 means no vertical resizing.

Definition at line 598 of file widget_type.h.

References NWidgetPart::type, WPT_RESIZE, and NWidgetPart::xy.