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()

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 1242 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 3375 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 3394 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]

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

References INVALID_WIDGET.

Referenced by MakePickerClassWidgets(), and MakePickerTypeWidgets().

◆ NWidget() [2/2]

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).
idx	Optional identifier of the widget.

Definition at line 1449 of file widget_type.h.

◆ NWidgetFunction()

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

References WPT_FUNCTION.

◆ SetAlignment()

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

References WPT_ALIGNMENT.

◆ SetAlternateColourTip()

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

References WPT_DATATIP.

◆ SetArrowWidgetTypeTip()

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

◆ SetAspect()

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

References WPT_ASPECT.

Referenced by MakePickerTypeWidgets().

◆ SetFill()

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

References Point, and WPT_FILL.

Referenced by MakePickerClassWidgets(), and MakePickerTypeWidgets().

◆ SetMatrixDataTip()

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

Referenced by MakePickerClassWidgets().

◆ SetMinimalSize()

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

References Point, and WPT_MINSIZE.

Referenced by MakePickerClassWidgets().

◆ SetMinimalTextLines()

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

References FS_NORMAL, and WPT_MINTEXTLINES.

Referenced by MakePickerTypeWidgets().

◆ SetPadding() [1/4]

NWidgetPart SetPadding ( const RectPadding & padding )

constexpr

Widget part function for setting additional space around a widget.

Parameters

padding The padding around the widget.

Definition at line 1366 of file widget_type.h.

References WPT_PADDING.

◆ SetPadding() [2/4]

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

References WPT_PADDING.

◆ SetPadding() [3/4]

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

References SetPadding().

◆ SetPadding() [4/4]

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

References WPT_PADDING.

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

◆ SetPIP()

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

References WPT_PIPSPACE.

Referenced by MakePickerTypeWidgets().

◆ SetPIPRatio()

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

ratio_pre	The ratio of space before the first widget.
ratio_inter	The ratio of space between widgets.
ratio_post	The ratio of space after the last widget.

Definition at line 1400 of file widget_type.h.

References WPT_PIPRATIO.

◆ SetResize()

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

References Point, and WPT_RESIZE.

Referenced by MakePickerClassWidgets(), and MakePickerTypeWidgets().

◆ SetResizeWidgetTypeTip()

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

References WPT_DATATIP.

◆ SetScrollbar()

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

References WPT_SCROLLBAR.

Referenced by MakePickerClassWidgets(), and MakePickerTypeWidgets().

◆ SetSpriteStringTip()

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

◆ SetSpriteTip()

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

Referenced by MakePickerTypeWidgets().

◆ SetStringTip()

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

Referenced by MakePickerClassWidgets(), and MakePickerTypeWidgets().

◆ SetTextStyle()

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

References FS_NORMAL, and WPT_TEXTSTYLE.

◆ SetToolbarMinimalSize()

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

References Point, and WPT_MINSIZE.

◆ SetToolbarSpacerMinimalSize()

NWidgetPart SetToolbarSpacerMinimalSize ( )

constexpr

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

Definition at line 1178 of file widget_type.h.

References Point, and WPT_MINSIZE.

◆ SetToolTip()

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

References WPT_DATATIP.

Referenced by MakePickerClassWidgets().

Data Structures

Functions

Detailed Description

Function Documentation

◆ EndContainer()

◆ MakeNWidgets()

◆ MakeWindowNWidgetTree()

◆ NWidget() [1/2]

◆ NWidget() [2/2]

◆ NWidgetFunction()

◆ SetAlignment()

◆ SetAlternateColourTip()

◆ SetArrowWidgetTypeTip()

◆ SetAspect()

◆ SetFill()

◆ SetMatrixDataTip()

◆ SetMinimalSize()

◆ SetMinimalTextLines()

◆ SetPadding() [1/4]

◆ SetPadding() [2/4]

◆ SetPadding() [3/4]

◆ SetPadding() [4/4]

◆ SetPIP()

◆ SetPIPRatio()

◆ SetResize()

◆ SetResizeWidgetTypeTip()

◆ SetScrollbar()

◆ SetSpriteStringTip()

◆ SetSpriteTip()

◆ SetStringTip()

◆ SetTextStyle()

◆ SetToolbarMinimalSize()

◆ SetToolbarSpacerMinimalSize()

◆ SetToolTip()