OpenTTD Source: Hierarchical widget parts

OpenTTD Source 1.11.0-RC1

Data Structures | Functions
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. 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. More...
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. More...
static NWidgetPart | SetResize (int16 dx, int16 dy)
| Widget part function for setting the resize step. More...
static NWidgetPart | SetMinimalSize (int16 x, int16 y)
| Widget part function for setting the minimal size. More...
static NWidgetPart | SetMinimalTextLines (uint8 lines, uint8 spacing, FontSize size=FS_NORMAL)
| Widget part function for setting the minimal text lines. More...
static NWidgetPart | SetFill (uint fill_x, uint fill_y)
| Widget part function for setting filling. More...
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 (uint32 data, StringID tip)
| Widget part function for setting the data and tooltip. More...
static NWidgetPart | SetMatrixDataTip (uint8 cols, uint8 rows, StringID tip)
| Widget part function for setting the data and tooltip of WWT_MATRIX widgets. More...
static NWidgetPart | SetPadding (uint8 top, uint8 right, uint8 bottom, uint8 left)
| Widget part function for setting additional space around a widget. More...
static NWidgetPart | SetPadding (uint8 padding)
| Widget part function for setting a padding. More...
static NWidgetPart | SetPIP (uint8 pre, uint8 inter, uint8 post)
| Widget part function for setting a pre/inter/post spaces. More...
static NWidgetPart | SetScrollbar (int index)
| Attach a scrollbar to a widget. More...
static NWidgetPart | NWidget (WidgetType tp, Colours col, int16 idx=-1)
| Widget part function for starting a new 'real' widget. More...
static NWidgetPart | NWidget (WidgetType tp, NWidContainerFlags cont_flags=NC_NONE)
| Widget part function for starting a new horizontal container, vertical container, or spacer widget. More...
static NWidgetPart | NWidgetFunction (NWidgetFunctionType *func_ptr)
| Obtain a nested widget (sub)tree from an external source. More...

## 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, 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 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 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 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

## ◆ MakeNWidgets()

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 nullptr a vertical container is used.

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

Precondition
  `biggest_index` != nullptr

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

Definition at line 2799 of file widget.cpp.

References MakeWidgetTree().

Referenced by MakeWindowNWidgetTree(), and NewGRFDisplay().

## ◆ 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 (`nullptr` if not unserted).

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

Precondition
  `biggest_index` != nullptr

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

Definition at line 2821 of file widget.cpp.

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

Referenced by Window::CreateNestedTree().

## ◆ NWidget() [1/2]

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

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

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

## ◆ NWidget() [2/2]

static NWidgetPart NWidget | ( | WidgetType | tp,
|  | NWidContainerFlags | cont_flags = `NC_NONE`
| ) |  |
| inlinestatic

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

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

## ◆ NWidgetFunction()

static NWidgetPart NWidgetFunction | ( | NWidgetFunctionType * | func_ptr | ) |
| inlinestatic

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

Parameters

  func_ptr | Pointer to function that returns the tree.

Definition at line 1145 of file widget_type.h.

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

## ◆ SetDataTip()

static NWidgetPart SetDataTip | ( | uint32 | data,
|  | StringID | tip
| ) |  |
| inlinestatic

Widget part function for setting the data and tooltip.

Parameters

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

Definition at line 1013 of file widget_type.h.

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

Referenced by SetMatrixDataTip().

## ◆ SetFill()

static NWidgetPart SetFill | ( | uint | fill_x,
|  | uint | fill_y
| ) |  |
| inlinestatic

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

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

## ◆ SetMatrixDataTip()

static NWidgetPart SetMatrixDataTip | ( | uint8 | cols,
|  | uint8 | rows,
|  | StringID | tip
| ) |  |
| inlinestatic

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

References MAT_COL_START, MAT_ROW_START, and SetDataTip().

## ◆ SetMinimalSize()

static NWidgetPart SetMinimalSize | ( | int16 | x,
|  | int16 | y
| ) |  |
| inlinestatic

Widget part function for setting the minimal size.

Parameters

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

Definition at line 946 of file widget_type.h.

## ◆ SetMinimalTextLines()

static NWidgetPart SetMinimalTextLines | ( | uint8 | lines,
|  | uint8 | spacing,
|  | FontSize | size = `FS_NORMAL`
| ) |  |
| inlinestatic

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

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

## ◆ SetPadding() [1/2]

static NWidgetPart SetPadding | ( | uint8 | padding | ) |
| inlinestatic

Widget part function for setting a padding.

Parameters

  padding | The padding to use for all directions.

Definition at line 1063 of file widget_type.h.

References SetPadding().

## ◆ SetPadding() [2/2]

static NWidgetPart SetPadding | ( | uint8 | top,
|  | uint8 | right,
|  | uint8 | bottom,
|  | uint8 | left
| ) |  |
| inlinestatic

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

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

Referenced by SetPadding().

## ◆ SetPIP()

static NWidgetPart SetPIP | ( | uint8 | pre,
|  | uint8 | inter,
|  | uint8 | post
| ) |  |
| inlinestatic

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

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

## ◆ SetResize()

static NWidgetPart SetResize | ( | int16 | dx,
|  | int16 | dy
| ) |  |
| inlinestatic

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

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

## ◆ SetScrollbar()

static NWidgetPart SetScrollbar | ( | int | index | ) |
| inlinestatic

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

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