OpenTTD Source  20241120-master-g6d3adc6169
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< NWidgetBaseMakeNWidgets (std::span< const NWidgetPart > nwid_parts, std::unique_ptr< NWidgetBase > &&container)
 Construct a nested widget tree from an array of parts. More...
 
std::unique_ptr< NWidgetBaseMakeWindowNWidgetTree (std::span< const NWidgetPart > nwid_parts, NWidgetStacked **shade_select)
 Make a nested widget tree for a window from a parts array. More...
 
constexpr NWidgetPart SetResize (int16_t dx, int16_t dy)
 Widget part function for setting the resize step. More...
 
constexpr NWidgetPart SetMinimalSize (int16_t x, int16_t y)
 Widget part function for setting the minimal size. More...
 
constexpr NWidgetPart SetMinimalTextLines (uint8_t lines, uint8_t spacing, FontSize size=FS_NORMAL)
 Widget part function for setting the minimal text lines. More...
 
constexpr NWidgetPart SetTextStyle (TextColour colour, FontSize size=FS_NORMAL)
 Widget part function for setting the text style. More...
 
constexpr NWidgetPart SetAlignment (StringAlignment align)
 Widget part function for setting the alignment of text/images. More...
 
constexpr NWidgetPart SetFill (uint16_t fill_x, uint16_t fill_y)
 Widget part function for setting filling. More...
 
constexpr NWidgetPart EndContainer ()
 Widget part function for denoting the end of a container (horizontal, vertical, WWT_FRAME, WWT_INSET, or WWT_PANEL).
 
constexpr NWidgetPart SetDataTip (uint32_t data, StringID tip)
 Widget part function for setting the data and tooltip. More...
 
constexpr NWidgetPart SetMatrixDataTip (uint8_t cols, uint8_t rows, StringID tip)
 Widget part function for setting the data and tooltip of WWT_MATRIX widgets. More...
 
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. More...
 
constexpr NWidgetPart SetPadding (const RectPadding &padding)
 Widget part function for setting additional space around a widget. More...
 
constexpr NWidgetPart SetPadding (uint8_t padding)
 Widget part function for setting a padding. More...
 
constexpr NWidgetPart SetPIP (uint8_t pre, uint8_t inter, uint8_t post)
 Widget part function for setting a pre/inter/post spaces. More...
 
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. More...
 
constexpr NWidgetPart SetScrollbar (WidgetID index)
 Attach a scrollbar to a widget. More...
 
constexpr NWidgetPart SetAspect (float ratio, AspectFlags flags=AspectFlags::ResizeX)
 Widget part function for setting the aspect ratio. More...
 
constexpr NWidgetPart NWidget (WidgetType tp, Colours col, WidgetID idx=-1)
 Widget part function for starting a new 'real' widget. More...
 
constexpr NWidgetPart NWidget (WidgetType tp, NWidContainerFlags cont_flags=NC_NONE)
 Widget part function for starting a new horizontal container, vertical container, or spacer widget. More...
 
constexpr 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.

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.

In both cases, the background widget MUST end with a EndContainer widget part.

See also
Hierarchical widgets

Function Documentation

◆ 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_partsSpan of nested widget parts.
containerContainer 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 3239 of file widget.cpp.

References MakeWidgetTree().

Referenced by 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_partsSpan of nested widget parts.
[out]shade_selectPointer to the inserted shade selection widget (nullptr if not unserted).
Returns
Root of the nested widget tree, a vertical container containing the entire GUI.

Definition at line 3258 of file widget.cpp.

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

Referenced by Window::CreateNestedTree().

◆ NWidget() [1/2]

constexpr NWidgetPart NWidget ( WidgetType  tp,
Colours  col,
WidgetID  idx = -1 
)
constexpr

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

Parameters
tpType of the new nested widget.
colColour of the new widget.
idxIndex 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 1309 of file widget_type.h.

Referenced by MakePickerClassWidgets(), and MakePickerTypeWidgets().

◆ NWidget() [2/2]

constexpr NWidgetPart NWidget ( WidgetType  tp,
NWidContainerFlags  cont_flags = NC_NONE 
)
constexpr

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

Parameters
tpType of the new nested widget, NWID_HORIZONTAL, NWID_VERTICAL, NWID_SPACER, NWID_SELECTION, and NWID_MATRIX.
cont_flagsFlags for the containers (NWID_HORIZONTAL and NWID_VERTICAL).

Definition at line 1320 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_ptrPointer to function that returns the tree.

Definition at line 1330 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
alignAlignment of text/image within widget.

Definition at line 1170 of file widget_type.h.

References WPT_ALIGNMENT.

◆ SetAspect()

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

Widget part function for setting the aspect ratio.

Parameters
ratioDesired aspect ratio, or 0 for none.
flagsDimensions which should be resized.

Definition at line 1295 of file widget_type.h.

◆ SetDataTip()

constexpr NWidgetPart SetDataTip ( uint32_t  data,
StringID  tip 
)
constexpr

Widget part function for setting the data and tooltip.

Parameters
dataData of the widget.
tipTooltip of the widget.

Definition at line 1202 of file widget_type.h.

References WPT_DATATIP.

Referenced by SetMatrixDataTip().

◆ SetFill()

constexpr NWidgetPart SetFill ( uint16_t  fill_x,
uint16_t  fill_y 
)
constexpr

Widget part function for setting filling.

Parameters
fill_xHorizontal filling step from minimal size.
fill_yVertical filling step from minimal size.

Definition at line 1181 of file widget_type.h.

◆ SetMatrixDataTip()

constexpr NWidgetPart SetMatrixDataTip ( uint8_t  cols,
uint8_t  rows,
StringID  tip 
)
constexpr

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

Parameters
colsNumber of columns. 0 means to use draw columns with width according to the resize step size.
rowsNumber of rows. 0 means to use draw rows with height according to the resize step size.
tipTooltip of the widget.

Definition at line 1214 of file widget_type.h.

References MAT_COL_START, MAT_ROW_START, and SetDataTip().

◆ SetMinimalSize()

constexpr NWidgetPart SetMinimalSize ( int16_t  x,
int16_t  y 
)
constexpr

Widget part function for setting the minimal size.

Parameters
xHorizontal minimal size.
yVertical minimal size.

Definition at line 1137 of file widget_type.h.

◆ 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
linesNumber of text lines.
spacingExtra spacing required.
sizeFont size of text.

Definition at line 1149 of file widget_type.h.

References WPT_MINTEXTLINES.

◆ SetPadding() [1/3]

constexpr NWidgetPart SetPadding ( const RectPadding padding)
constexpr

Widget part function for setting additional space around a widget.

Parameters
rThe padding around the widget.

Definition at line 1238 of file widget_type.h.

References WPT_PADDING.

◆ SetPadding() [2/3]

constexpr NWidgetPart SetPadding ( uint8_t  padding)
constexpr

Widget part function for setting a padding.

Parameters
paddingThe padding to use for all directions.

Definition at line 1248 of file widget_type.h.

References SetPadding().

◆ SetPadding() [3/3]

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
topThe padding above the widget.
rightThe padding right of the widget.
bottomThe padding below the widget.
leftThe padding left of the widget.

Definition at line 1228 of file widget_type.h.

References WPT_PADDING.

Referenced by 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
preThe amount of space before the first widget.
interThe amount of space between widgets.
postThe amount of space after the last widget.

Definition at line 1260 of file widget_type.h.

References WPT_PIPSPACE.

◆ 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
preThe ratio of space before the first widget.
interThe ratio of space between widgets.
postThe ratio of space after the last widget.

Definition at line 1272 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
dxHorizontal resize step. 0 means no horizontal resizing.
dyVertical resize step. 0 means no vertical resizing.

Definition at line 1126 of file widget_type.h.

References WPT_RESIZE.

◆ 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
indexWidget index of the scrollbar.

Definition at line 1284 of file widget_type.h.

References WPT_SCROLLBAR.

◆ SetTextStyle()

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

Widget part function for setting the text style.

Parameters
colourColour to draw string within widget.
sizeFont size to draw string within widget.

Definition at line 1160 of file widget_type.h.

References WPT_TEXTSTYLE.