OpenTTD Source: Hierarchical widget parts

OpenTTD Source 15.0-RC2

Data Structures | Functions
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 | NWidgetPartTextStyle
| Widget part for storing text colour. More...
struct | NWidgetPartAlignment
| Widget part for setting text/image alignment within a widget. More...
struct | NWidgetPart
| Partial widget specification to allow NWidgets to be written nested. More...

## Functions
std::unique_ptr< NWidgetBase > | MakeNWidgets (std::span< const NWidgetPart > nwid_parts, std::unique_ptr< NWidgetBase > &&container)
| Construct a nested widget tree from an array of parts.
std::unique_ptr< NWidgetBase > | MakeWindowNWidgetTree (std::span< const NWidgetPart > nwid_parts, NWidgetStacked **shade_select)
| Make a nested widget tree for a window from a parts array.
constexpr NWidgetPart | SetResize (int16_t dx, int16_t dy)
| Widget part function for setting the resize step.
constexpr NWidgetPart | SetMinimalSize (int16_t x, int16_t y)
| Widget part function for setting the minimal size.
constexpr NWidgetPart | SetToolbarSpacerMinimalSize ()
| Widget part function to setting the minimal size for a toolbar spacer.
constexpr NWidgetPart | SetToolbarMinimalSize (int width)
| Widget part function to setting the minimal size for a toolbar button.
constexpr NWidgetPart | SetMinimalTextLines (uint8_t lines, uint8_t spacing, FontSize size=FS_NORMAL)
| Widget part function for setting the minimal text lines.
constexpr NWidgetPart | SetTextStyle (TextColour colour, FontSize size=FS_NORMAL)
| Widget part function for setting the text style.
constexpr NWidgetPart | SetAlignment (StringAlignment align)
| Widget part function for setting the alignment of text/images.
constexpr NWidgetPart | SetFill (uint16_t fill_x, uint16_t fill_y)
| Widget part function for setting filling.
constexpr NWidgetPart | EndContainer ()
| Widget part function for denoting the end of a container (horizontal, vertical, WWT_FRAME, WWT_INSET, or WWT_PANEL).
constexpr NWidgetPart | SetStringTip (StringID string, StringID tip={})
| Widget part function for setting the string and tooltip.
constexpr NWidgetPart | SetSpriteTip (SpriteID sprite, StringID tip={})
| Widget part function for setting the sprite and tooltip.
constexpr NWidgetPart | SetSpriteStringTip (SpriteID sprite, StringID string, StringID tip={})
| Widget part function for setting the sprite, string and tooltip.
constexpr NWidgetPart | SetArrowWidgetTypeTip (ArrowWidgetValues widget_type, StringID tip={})
| Widget part function for setting the arrow widget type and tooltip.
constexpr NWidgetPart | SetResizeWidgetTypeTip (ResizeWidgetValues widget_type, StringID tip)
| Widget part function for setting the resize widget type and tooltip.
constexpr NWidgetPart | SetAlternateColourTip (Colours colour, StringID tip)
| Widget part function for setting the alternate colour and tooltip.
constexpr NWidgetPart | SetMatrixDataTip (uint32_t cols, uint32_t rows, StringID tip={})
| Widget part function for setting the data and tooltip of WWT_MATRIX widgets.
constexpr NWidgetPart | SetToolTip (StringID tip)
| Widget part function for setting tooltip and clearing the widget data.
constexpr NWidgetPart | SetPadding (uint8_t top, uint8_t right, uint8_t bottom, uint8_t left)
| Widget part function for setting additional space around a widget.
constexpr NWidgetPart | SetPadding (uint8_t horizontal, uint8_t vertical)
| Widget part function for setting additional space around a widget.
constexpr NWidgetPart | SetPadding (const RectPadding &padding)
| Widget part function for setting additional space around a widget.
constexpr NWidgetPart | SetPadding (uint8_t padding)
| Widget part function for setting a padding.
constexpr NWidgetPart | SetPIP (uint8_t pre, uint8_t inter, uint8_t post)
| Widget part function for setting a pre/inter/post spaces.
constexpr NWidgetPart | SetPIPRatio (uint8_t ratio_pre, uint8_t ratio_inter, uint8_t ratio_post)
| Widget part function for setting a pre/inter/post ratio.
constexpr NWidgetPart | SetScrollbar (WidgetID index)
| Attach a scrollbar to a widget.
constexpr NWidgetPart | SetAspect (float ratio, AspectFlags flags=AspectFlag::ResizeX)
| Widget part function for setting the aspect ratio.
constexpr NWidgetPart | NWidget (WidgetType tp, Colours col, WidgetID idx=INVALID_WIDGET)
| Widget part function for starting a new 'real' widget.
constexpr NWidgetPart | NWidget (WidgetType tp, NWidContainerFlags cont_flags={}, WidgetID idx=INVALID_WIDGET)
| Widget part function for starting a new horizontal container, vertical container, or spacer widget.
constexpr 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_t 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.
  - SetStringTip Define the string and the tooltip of the widget.
  - SetSpriteTip Define the sprite ID and the tooltip of the widget.
  - SetToolTip Define 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, NWidgetVertical, and NWidgetMatrix, 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 children, 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 children 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_t 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

## ◆ EndContainer()

constexpr NWidgetPart EndContainer | ( |  | ) |
| constexpr

Widget part function for denoting the end of a container (horizontal, vertical, WWT_FRAME, WWT_INSET, or WWT_PANEL).

Definition at line 1229 of file widget_type.h.

References WPT_ENDCONTAINER.

Referenced by MakePickerClassWidgets(), and MakePickerTypeWidgets().

## ◆ MakeNWidgets()

std::unique_ptr< NWidgetBase > MakeNWidgets | ( | std::span< const NWidgetPart > | nwid_parts,
|  | std::unique_ptr< NWidgetBase > && | container
| ) |  |

Construct a nested widget tree from an array of parts.

Parameters

  nwid_parts | Span of nested widget parts.
  container | Container to add the nested widgets to. In case it is nullptr a vertical container is used.

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

Definition at line 3374 of file widget.cpp.

References MakeWidgetTree().

Referenced by MakePickerClassWidgets(), MakePickerTypeWidgets(), MakeWindowNWidgetTree(), and NewGRFDisplay().

## ◆ MakeWindowNWidgetTree()

std::unique_ptr< NWidgetBase > MakeWindowNWidgetTree | ( | std::span< const NWidgetPart > | nwid_parts,
|  | 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

  | nwid_parts | Span of nested widget parts.
  [out] | shade_select | Pointer to the inserted shade selection widget (`nullptr` if not inserted).

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

Definition at line 3393 of file widget.cpp.

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

Referenced by Window::CreateNestedTree().

## ◆ NWidget() [1/2]

constexpr NWidgetPart NWidget | ( | WidgetType | tp,
|  | Colours | col,
|  | WidgetID | idx = `INVALID_WIDGET`
| ) |  |
| constexpr

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.

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 1424 of file widget_type.h.

Referenced by MakePickerClassWidgets(), and MakePickerTypeWidgets().

## ◆ NWidget() [2/2]

constexpr NWidgetPart NWidget | ( | WidgetType | tp,
|  | NWidContainerFlags | cont_flags = `{}`,
|  | WidgetID | idx = `INVALID_WIDGET`
| ) |  |
| constexpr

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

Parameters

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

Definition at line 1435 of file widget_type.h.

## ◆ NWidgetFunction()

constexpr NWidgetPart NWidgetFunction | ( | NWidgetFunctionType * | func_ptr | ) |
| constexpr

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

Parameters

  func_ptr | Pointer to function that returns the tree.

Definition at line 1445 of file widget_type.h.

References WPT_FUNCTION.

## ◆ SetAlignment()

constexpr NWidgetPart SetAlignment | ( | StringAlignment | align | ) |
| constexpr

Widget part function for setting the alignment of text/images.

Parameters

  align | Alignment of text/image within widget.

Definition at line 1208 of file widget_type.h.

References WPT_ALIGNMENT.

## ◆ SetAlternateColourTip()

constexpr NWidgetPart SetAlternateColourTip | ( | Colours | colour,
|  | StringID | tip
| ) |  |
| constexpr

Widget part function for setting the alternate colour and tooltip.

Parameters

  colour | Alternate colour of the widget.
  tip | Tooltip of the widget.

Definition at line 1296 of file widget_type.h.

References WPT_DATATIP.

## ◆ SetArrowWidgetTypeTip()

constexpr NWidgetPart SetArrowWidgetTypeTip | ( | ArrowWidgetValues | widget_type,
|  | StringID | tip = `{}`
| ) |  |
| constexpr

Widget part function for setting the arrow widget type and tooltip.

Parameters

  widget_type | Type of the widget to draw.
  tip | Tooltip of the widget.

Definition at line 1274 of file widget_type.h.

## ◆ SetAspect()

constexpr NWidgetPart SetAspect | ( | float | ratio,
|  | AspectFlags | flags = `AspectFlag::ResizeX`
| ) |  |
| constexpr

Widget part function for setting the aspect ratio.

Parameters

  ratio | Desired aspect ratio, or 0 for none.
  flags | Dimensions which should be resized.

Definition at line 1410 of file widget_type.h.

References WPT_ASPECT.

Referenced by MakePickerTypeWidgets().

## ◆ SetFill()

constexpr NWidgetPart SetFill | ( | uint16_t | fill_x,
|  | uint16_t | fill_y
| ) |  |
| constexpr

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 1219 of file widget_type.h.

References WPT_FILL.

Referenced by MakePickerClassWidgets(), and MakePickerTypeWidgets().

## ◆ SetMatrixDataTip()

constexpr NWidgetPart SetMatrixDataTip | ( | uint32_t | cols,
|  | uint32_t | rows,
|  | StringID | tip = `{}`
| ) |  |
| constexpr

Widget part function for setting the data and tooltip of WWT_MATRIX widgets.

Parameters

  cols | Number of columns. `0` means to use draw columns with width according to the resize step size.
  rows | Number of rows. `0` means to use draw rows with height according to the resize step size.
  tip | Tooltip of the widget.

Definition at line 1308 of file widget_type.h.

Referenced by MakePickerClassWidgets().

## ◆ SetMinimalSize()

constexpr NWidgetPart SetMinimalSize | ( | int16_t | x,
|  | int16_t | y
| ) |  |
| constexpr

Widget part function for setting the minimal size.

Parameters

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

Definition at line 1156 of file widget_type.h.

References WPT_MINSIZE.

Referenced by MakePickerClassWidgets().

## ◆ SetMinimalTextLines()

constexpr NWidgetPart SetMinimalTextLines | ( | uint8_t | lines,
|  | uint8_t | spacing,
|  | FontSize | size = `FS_NORMAL`
| ) |  |
| constexpr

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 1187 of file widget_type.h.

References WPT_MINTEXTLINES.

Referenced by MakePickerTypeWidgets().

## ◆ SetPadding() [1/4]

constexpr NWidgetPart SetPadding | ( | const RectPadding & | padding | ) |
| constexpr

Widget part function for setting additional space around a widget.

Parameters

  r | The padding around the widget.

Definition at line 1353 of file widget_type.h.

References WPT_PADDING.

## ◆ SetPadding() [2/4]

constexpr NWidgetPart SetPadding | ( | uint8_t | horizontal,
|  | uint8_t | vertical
| ) |  |
| constexpr

Widget part function for setting additional space around a widget.

Parameters

  horizontal | The padding on either side of the widget.
  vertical | The padding above and below the widget.

Definition at line 1343 of file widget_type.h.

References WPT_PADDING.

## ◆ SetPadding() [3/4]

constexpr NWidgetPart SetPadding | ( | uint8_t | padding | ) |
| constexpr

Widget part function for setting a padding.

Parameters

  padding | The padding to use for all directions.

Definition at line 1363 of file widget_type.h.

References SetPadding().

## ◆ SetPadding() [4/4]

constexpr NWidgetPart SetPadding | ( | uint8_t | top,
|  | uint8_t | right,
|  | uint8_t | bottom,
|  | uint8_t | left
| ) |  |
| constexpr

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 1332 of file widget_type.h.

References WPT_PADDING.

Referenced by MakePickerClassWidgets(), MakePickerTypeWidgets(), and SetPadding().

## ◆ SetPIP()

constexpr NWidgetPart SetPIP | ( | uint8_t | pre,
|  | uint8_t | inter,
|  | uint8_t | post
| ) |  |
| constexpr

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 1375 of file widget_type.h.

References WPT_PIPSPACE.

Referenced by MakePickerTypeWidgets().

## ◆ SetPIPRatio()

constexpr NWidgetPart SetPIPRatio | ( | uint8_t | ratio_pre,
|  | uint8_t | ratio_inter,
|  | uint8_t | ratio_post
| ) |  |
| constexpr

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

Parameters

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

Definition at line 1387 of file widget_type.h.

References WPT_PIPRATIO.

## ◆ SetResize()

constexpr NWidgetPart SetResize | ( | int16_t | dx,
|  | int16_t | dy
| ) |  |
| constexpr

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 1145 of file widget_type.h.

References WPT_RESIZE.

Referenced by MakePickerClassWidgets(), and MakePickerTypeWidgets().

## ◆ SetResizeWidgetTypeTip()

constexpr NWidgetPart SetResizeWidgetTypeTip | ( | ResizeWidgetValues | widget_type,
|  | StringID | tip
| ) |  |
| constexpr

Widget part function for setting the resize widget type and tooltip.

Parameters

  widget_type | Type of the widget to draw.
  tip | Tooltip of the widget.

Definition at line 1285 of file widget_type.h.

References WPT_DATATIP.

## ◆ SetScrollbar()

constexpr NWidgetPart SetScrollbar | ( | WidgetID | index | ) |
| constexpr

Attach a scrollbar to a widget.

The scrollbar is controlled when using the mousewheel on the widget. Multiple widgets can refer to the same scrollbar to make the mousewheel work in all of them.

Parameters

  index | Widget index of the scrollbar.

Definition at line 1399 of file widget_type.h.

References WPT_SCROLLBAR.

Referenced by MakePickerClassWidgets(), and MakePickerTypeWidgets().

## ◆ SetSpriteStringTip()

constexpr NWidgetPart SetSpriteStringTip | ( | SpriteID | sprite,
|  | StringID | string,
|  | StringID | tip = `{}`
| ) |  |
| constexpr

Widget part function for setting the sprite, string and tooltip.

Parameters

  sprite | Sprite of the widget.
  string | String of the widget.
  tip | Tooltip of the widget.

Definition at line 1263 of file widget_type.h.

## ◆ SetSpriteTip()

constexpr NWidgetPart SetSpriteTip | ( | SpriteID | sprite,
|  | StringID | tip = `{}`
| ) |  |
| constexpr

Widget part function for setting the sprite and tooltip.

Parameters

  sprite | Sprite of the widget.
  tip | Tooltip of the widget.

Definition at line 1251 of file widget_type.h.

Referenced by MakePickerTypeWidgets().

## ◆ SetStringTip()

constexpr NWidgetPart SetStringTip | ( | StringID | string,
|  | StringID | tip = `{}`
| ) |  |
| constexpr

Widget part function for setting the string and tooltip.

Parameters

  string | String of the widget.
  tip | Tooltip of the widget.

Definition at line 1240 of file widget_type.h.

Referenced by MakePickerClassWidgets(), and MakePickerTypeWidgets().

## ◆ SetTextStyle()

constexpr NWidgetPart SetTextStyle | ( | TextColour | colour,
|  | FontSize | size = `FS_NORMAL`
| ) |  |
| constexpr

Widget part function for setting the text style.

Parameters

  colour | Colour to draw string within widget.
  size | Font size to draw string within widget.

Definition at line 1198 of file widget_type.h.

References WPT_TEXTSTYLE.

## ◆ SetToolbarMinimalSize()

constexpr NWidgetPart SetToolbarMinimalSize | ( | int | width | ) |
| constexpr

Widget part function to setting the minimal size for a toolbar button.

Parameters

  width | Width of button, measured in multiples of the standard toolbar button size.

Definition at line 1175 of file widget_type.h.

References WPT_MINSIZE.

## ◆ SetToolbarSpacerMinimalSize()

constexpr NWidgetPart SetToolbarSpacerMinimalSize | ( |  | ) |
| constexpr

Widget part function to setting the minimal size for a toolbar spacer.

Definition at line 1165 of file widget_type.h.

References WPT_MINSIZE.

## ◆ SetToolTip()

constexpr NWidgetPart SetToolTip | ( | StringID | tip | ) |
| constexpr

Widget part function for setting tooltip and clearing the widget data.

Parameters

  tip | Tooltip of the widget.

Definition at line 1318 of file widget_type.h.

References WPT_DATATIP.