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	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. More...

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. 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.

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.
- 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_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

◆ 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 3210 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_parts	Span of nested widget parts.
[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.

Definition at line 3229 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

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 1311 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

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 1322 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 1332 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 1172 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

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

Definition at line 1297 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

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

Definition at line 1204 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_x	Horizontal filling step from minimal size.
fill_y	Vertical filling step from minimal size.

Definition at line 1183 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

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 1216 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

x	Horizontal minimal size.
y	Vertical minimal size.

Definition at line 1139 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

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

Definition at line 1151 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

r	The padding around the widget.

Definition at line 1240 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

padding The padding to use for all directions.

Definition at line 1250 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

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 1230 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

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 1262 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

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 1274 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 1128 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

index Widget index of the scrollbar.

Definition at line 1286 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

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

Definition at line 1162 of file widget_type.h.

References WPT_TEXTSTYLE.

Data Structures

Functions

Detailed Description

Function Documentation

◆ MakeNWidgets()

◆ MakeWindowNWidgetTree()

◆ NWidget() [1/2]

◆ NWidget() [2/2]

◆ NWidgetFunction()

◆ SetAlignment()

◆ SetAspect()

◆ SetDataTip()

◆ SetFill()

◆ SetMatrixDataTip()

◆ SetMinimalSize()

◆ SetMinimalTextLines()

◆ SetPadding() [1/3]

◆ SetPadding() [2/3]

◆ SetPadding() [3/3]

◆ SetPIP()

◆ SetPIPRatio()

◆ SetResize()

◆ SetScrollbar()

◆ SetTextStyle()