Layout nodes

Compact, declarative construction of GTextNode trees for layouts. More...

Data Structures
struct	LayoutNodeConfig
	Base of every node config. More...
struct	LayoutNodeExtentConfig
	Node config with an extent, added to the node's own. More...
struct	LayoutNodeTextConfig
	Text node config. More...
struct	LayoutNodeHeadingsParagraphsConfig
	Headings and paragraphs node config. More...
struct	LayoutNodeTextAttributeConfig
	Attribute text node config; no node is created if the attribute is empty. More...
struct	LayoutNodeTextBufferConfig
	Buffer text node config; no node is created for an empty string. More...
struct	LayoutNodeTextDynamicConfig
	Dynamic text node config. More...
struct	LayoutNodeContainerConfig
	Container node config. More...
struct	LayoutNodeHorizontalConfig
	Horizontal container node config. More...
struct	LayoutNodeVerticalConfig
	Vertical container node config. More...
struct	LayoutNodeConstructorConfig
	Constructor node config. More...
struct	LayoutNodeIconConfig
	Icon node config. More...
struct	LayoutNodeExtentConfig.offset
	Position delta, not affecting neighboring nodes. More...
struct	LayoutNodeExtentConfig.margin
	Size delta, not affecting the node's internal positioning. More...

Macros
#define	ToLayoutTextAlignment(alignment)   (alignment + 1)
	Convert a GTextAlignment to a LayoutTextAlignment.
#define	ToGTextAlignment(alignment)   (alignment - 1)
	Convert a LayoutTextAlignment other than auto to a GTextAlignment.
#define	ToLayoutVerticalAlignment(alignment)   (alignment + 1)
	Convert a GVerticalAlignment to a LayoutVerticalAlignment.
#define	ToGVerticalAlignment(alignment)   (alignment - 1)
	Convert a LayoutVerticalAlignment other than auto to a GVerticalAlignment.
#define	ToLayoutContentSize(size)   ((LayoutContentSize)((size) + 1))
	Convert a PreferredContentSize to a LayoutContentSize.
#define	ToPreferredContentSize(size)   ((PreferredContentSize)((size) - 1))
	Convert a LayoutContentSize other than auto to a PreferredContentSize.

Typedefs
typedef void(*	LayoutNodeTextDynamicUpdate) (const LayoutLayer *layout, const LayoutNodeTextDynamicConfig *config, char *buffer, bool render)
	Fill the buffer of a dynamic text node.
typedef GTextNode *(*	LayoutNodeConstructor) (const LayoutLayer *layout, const LayoutNodeConstructorConfig *config)
	Build the node of a constructor node config.

Enumerations
enum	LayoutTextAlignment { LayoutTextAlignment_Auto = 0 , LayoutTextAlignment_Left = GTextAlignmentLeft + 1 , LayoutTextAlignment_Center = GTextAlignmentCenter + 1 , LayoutTextAlignment_Right = GTextAlignmentRight + 1 }
	Horizontal text alignment; GTextAlignment shifted so that 0 means automatic. More...
enum	LayoutVerticalAlignment { LayoutVerticalAlignment_Auto = 0 , LayoutVerticalAlignment_Left = GVerticalAlignmentTop + 1 , LayoutVerticalAlignment_Center = GVerticalAlignmentCenter + 1 , LayoutVerticalAlignment_Right = GVerticalAlignmentBottom + 1 }
	Vertical alignment; GVerticalAlignment shifted so that 0 means automatic. More...
enum	LayoutColor { LayoutColor_None = 0 , LayoutColor_Primary , LayoutColor_Secondary , LayoutColor_Background }
	Layout color used for text. More...
enum	LayoutContentSize {   LayoutContentSize_Auto = 0 , LayoutContentSize_Small = PreferredContentSizeSmall + 1 , LayoutContentSize_Medium = PreferredContentSizeMedium + 1 , LayoutContentSize_Large = PreferredContentSizeLarge + 1 ,   LayoutContentSize_ExtraLarge = PreferredContentSizeExtraLarge + 1 , LayoutContentSizeDefault = PreferredContentSizeDefault + 1 }
	Content size; PreferredContentSize shifted so that 0 means the system size. More...
enum	LayoutNodeType {   LayoutNodeType_TextAttribute = 0 , LayoutNodeType_TextBuffer , LayoutNodeType_TextDynamic , LayoutNodeType_Text ,   LayoutNodeType_Horizontal , LayoutNodeType_Vertical , LayoutNodeType_Constructor , LayoutNodeType_HeadingsParagraphs ,   LayoutNodeType_Icon , LayoutNodeType_TimelineIcon , LayoutNodeType_TimelinePageBreak , LayoutNodeType_TimelineMetrics }
	Type of a node config, selecting the config struct. More...

Functions
GTextNodeVertical *	layout_create_headings_paragraphs_node (const LayoutLayer *layout, const LayoutNodeHeadingsParagraphsConfig *config)
	Create a vertical node with the layout's headings and paragraphs.
GTextNode *	layout_create_text_node_from_config (const LayoutLayer *layout, const LayoutNodeConfig *config)
	Create a tree of text nodes from a config.
GTextNodeCustom *	layout_node_create_kino_layer_wrapper (KinoLayer *kino_layer)
	Wrap a KinoLayer in a custom text node that positions the layer during layout.

Detailed Description

Compact, declarative construction of GTextNode trees for layouts.

A hierarchy of packed LayoutNode configs describes a tree of text nodes, instantiated with layout_create_text_node_from_config(). Whole layouts, such as the timeline cards, are described this way; the generic layout is the simplest example. Every config starts with a LayoutNodeConfig whose type tells which config struct it is.

For the best code size, use static configs without one-use callbacks. Configs on the stack cost stack space, so create the nodes and return immediately, avoiding deeper work such as measuring the view with graphics_text_node_get_size(), which is very stack intensive.

static const LayoutNodeTextAttributeConfig s_title_config = {
  .attr_id = AttributeIdTitle,
  .text.style_font = TextStyleFont_Header,
  .text.extent.node.type = LayoutNodeType_TextAttribute,
};
static const LayoutNodeTextAttributeConfig s_body_config = {
  .attr_id = AttributeIdBody,
  .text.style_font = TextStyleFont_Body,
  .text.extent.node.type = LayoutNodeType_TextAttribute,
};
static const LayoutNodeConfig *s_vertical_nodes[] = {
  &s_title_config.text.extent.node,
  &s_body_config.text.extent.node,
};
static const LayoutNodeVerticalConfig s_vertical_config = {
  .container.extent.node.type = LayoutNodeType_Vertical,
  .container.nodes = (LayoutNodeConfig **)s_vertical_nodes,
  .container.num_nodes = ARRAY_LENGTH(s_vertical_nodes),
};
 
GTextNode *view = layout_create_text_node_from_config(layout,
                                                      &s_vertical_config.container.extent.node);

---

Data Structure Documentation

LayoutNodeConfig

struct LayoutNodeConfig

Base of every node config.

Data Fields
LayoutNodeType	type	Config type.

LayoutNodeExtentConfig

struct LayoutNodeExtentConfig

Node config with an extent, added to the node's own.

Data Fields
struct LayoutNodeExtentConfig.margin	margin	Size delta, not affecting the node's internal positioning.
LayoutNodeConfig	node	Base config.
struct LayoutNodeExtentConfig.offset	offset	Position delta, not affecting neighboring nodes.

LayoutNodeTextConfig

struct LayoutNodeTextConfig

Text node config.

Data Fields
LayoutTextAlignment	alignment: 2	Horizontal alignment.
LayoutNodeExtentConfig	extent	Extent.
uint8_t	fixed_lines: 2	Fixed height as a multiple of the font height (number of lines), 0 for none. Only use for text on the first page: text after the first page fold with fixed lines is not guaranteed to draw.
const char *	font_key	Font key; if NULL the font is taken from style and style_font.
int8_t	line_spacing_delta: 4	Line spacing delta in pixels.
LayoutContentSize	style: 8	Content size used to pick the font.
TextStyleFont	style_font: 8	System theme font used to pick the font.

LayoutNodeHeadingsParagraphsConfig

struct LayoutNodeHeadingsParagraphsConfig

Headings and paragraphs node config.

Data Fields
LayoutNodeExtentConfig	extent	Extent.
TextStyleFont	heading_style_font: 8	Font of the headings.
TextStyleFont	paragraph_style_font: 8	Font of the paragraphs.
LayoutContentSize	size: 8	Content size used to pick the fonts.

LayoutNodeTextAttributeConfig

struct LayoutNodeTextAttributeConfig

Attribute text node config; no node is created if the attribute is empty.

Data Fields
AttributeId	attr_id	String attribute to show.
LayoutNodeTextConfig	text	Text config.

LayoutNodeTextBufferConfig

struct LayoutNodeTextBufferConfig

Buffer text node config; no node is created for an empty string.

Data Fields
const char *	str	String copied into the node.
LayoutNodeTextConfig	text	Text config.
bool	use_i18n	Whether str is an i18n key to translate.

LayoutNodeTextDynamicConfig

struct LayoutNodeTextDynamicConfig

Dynamic text node config.

Data Fields
uint16_t	buffer_size	Size of the text buffer in bytes.
void *	context	User data for update.
LayoutNodeTextConfig	text	Text config.
LayoutNodeTextDynamicUpdate	update	Update function.

LayoutNodeContainerConfig

struct LayoutNodeContainerConfig

Container node config.

Data Fields
LayoutNodeExtentConfig	extent	Extent.
uint8_t	extra_capacity	Extra child capacity, for nodes added after creation.
LayoutNodeConfig **	nodes	Configs of the child nodes.
uint8_t	num_nodes	Number of child configs.

LayoutNodeHorizontalConfig

struct LayoutNodeHorizontalConfig

Horizontal container node config.

Data Fields
LayoutNodeContainerConfig	container	Container config.
LayoutTextAlignment	horizontal_alignment	Horizontal alignment of the children.

LayoutNodeVerticalConfig

struct LayoutNodeVerticalConfig

Vertical container node config.

Data Fields
LayoutNodeContainerConfig	container	Container config.
LayoutVerticalAlignment	vertical_alignment	Vertical alignment of the children.

LayoutNodeConstructorConfig

struct LayoutNodeConstructorConfig

Constructor node config.

Data Fields
LayoutNodeConstructor	constructor	Constructor.
void *	context	User data for constructor.
LayoutNodeExtentConfig	extent	Extent, added to that of the constructed node.

LayoutNodeIconConfig

struct LayoutNodeIconConfig

Icon node config.

Data Fields
GAlign	align	Alignment of the icon.
LayoutNodeExtentConfig	extent	Extent.
KinoLayer **	icon_layer	Set to the created KinoLayer, which is added to the layout; the caller destroys it.
AppResourceInfo *	res_info	Resource of the icon.

LayoutNodeExtentConfig.offset

struct LayoutNodeExtentConfig.offset

Position delta, not affecting neighboring nodes.

Data Fields
int8_t	x	Horizontal offset in pixels.
int8_t	y	Vertical offset in pixels.

LayoutNodeExtentConfig.margin

struct LayoutNodeExtentConfig.margin

Size delta, not affecting the node's internal positioning.

Data Fields
int8_t	h	Height delta in pixels.
int8_t	w	Width delta in pixels.

Macro Definition Documentation

ToGTextAlignment

#define ToGTextAlignment

(

alignment

)

(alignment - 1)

Convert a LayoutTextAlignment other than auto to a GTextAlignment.

Parameters

alignment

LayoutTextAlignment.

ToGVerticalAlignment

#define ToGVerticalAlignment

(

alignment

)

(alignment - 1)

Convert a LayoutVerticalAlignment other than auto to a GVerticalAlignment.

Parameters

alignment

LayoutVerticalAlignment.

ToLayoutContentSize

#define ToLayoutContentSize

(

size

)

((LayoutContentSize)((size) + 1))

Convert a PreferredContentSize to a LayoutContentSize.

Parameters

size	PreferredContentSize.

ToLayoutTextAlignment

#define ToLayoutTextAlignment

(

alignment

)

(alignment + 1)

Convert a GTextAlignment to a LayoutTextAlignment.

Parameters

alignment

GTextAlignment.

ToLayoutVerticalAlignment

#define ToLayoutVerticalAlignment

(

alignment

)

(alignment + 1)

Convert a GVerticalAlignment to a LayoutVerticalAlignment.

Parameters

alignment

GVerticalAlignment.

ToPreferredContentSize

#define ToPreferredContentSize

(

size

)

((PreferredContentSize)((size) - 1))

Convert a LayoutContentSize other than auto to a PreferredContentSize.

Parameters

size	LayoutContentSize.

Typedef Documentation

LayoutNodeConstructor

typedef GTextNode *(* LayoutNodeConstructor) (const LayoutLayer *layout, const LayoutNodeConstructorConfig *config)

Build the node of a constructor node config.

Parameters

layout	Layout the node belongs to.
config	Config of the node.

Returns

New node, or NULL.

LayoutNodeTextDynamicUpdate

typedef void(* LayoutNodeTextDynamicUpdate) (const LayoutLayer *layout, const LayoutNodeTextDynamicConfig *config, char *buffer, bool render)

Fill the buffer of a dynamic text node.

Parameters

	layout	Layout the node belongs to.
	config	Config of the node.
[out]	buffer	Text buffer of config->buffer_size bytes.
	render	true when drawing, false when measuring.

Enumeration Type Documentation

LayoutColor

enum LayoutColor

Layout color used for text.

Enumerator
LayoutColor_None	Keep the node's default color.
LayoutColor_Primary	Primary color of the layout.
LayoutColor_Secondary	Secondary color of the layout.
LayoutColor_Background	Background color of the layout.

LayoutContentSize

enum LayoutContentSize

Content size; PreferredContentSize shifted so that 0 means the system size.

Enumerator
LayoutContentSize_Auto	System content size.
LayoutContentSize_Small	Small.
LayoutContentSize_Medium	Medium.
LayoutContentSize_Large	Large.
LayoutContentSize_ExtraLarge	Extra large.
LayoutContentSizeDefault	Platform default size.

LayoutNodeType

enum LayoutNodeType

Type of a node config, selecting the config struct.

Enumerator
LayoutNodeType_TextAttribute	Text node whose text points to a string attribute (LayoutNodeTextAttributeConfig).
LayoutNodeType_TextBuffer	Text node with a buffer initialized from a literal string (LayoutNodeTextBufferConfig).
LayoutNodeType_TextDynamic	Dynamic text node with a buffer of a given size filled by an update function (LayoutNodeTextDynamicConfig). Use sparingly, it is expensive in code space.
LayoutNodeType_Text	Text node without a buffer (LayoutNodeTextConfig).
LayoutNodeType_Horizontal	Horizontal container populated with the given nodes (LayoutNodeHorizontalConfig).
LayoutNodeType_Vertical	Vertical container populated with the given nodes (LayoutNodeVerticalConfig).
LayoutNodeType_Constructor	Arbitrary node built by a constructor (LayoutNodeConstructorConfig). Use sparingly, it is expensive in code space.
LayoutNodeType_HeadingsParagraphs	Vertical container of text nodes pointing to the layout's headings and paragraphs attributes (LayoutNodeHeadingsParagraphsConfig).
LayoutNodeType_Icon	Custom node wrapping a newly created KinoLayer (LayoutNodeIconConfig).
LayoutNodeType_TimelineIcon	Node positioning the TimelineLayout's icon layer (LayoutNodeExtentConfig). TimelineLayout only.
LayoutNodeType_TimelinePageBreak	Page break showing the glance arrow and marking the TimelineLayout as having a page break (LayoutNodeConfig). TimelineLayout only.
LayoutNodeType_TimelineMetrics	Vertical container of icons, names and values from the layout's metric attributes (LayoutNodeExtentConfig). TimelineLayout only.

LayoutTextAlignment

enum LayoutTextAlignment

Horizontal text alignment; GTextAlignment shifted so that 0 means automatic.

Enumerator
LayoutTextAlignment_Auto	Left on rectangular displays, centered on round ones.
LayoutTextAlignment_Left	Left aligned.
LayoutTextAlignment_Center	Centered.
LayoutTextAlignment_Right	Right aligned.

LayoutVerticalAlignment

enum LayoutVerticalAlignment

Vertical alignment; GVerticalAlignment shifted so that 0 means automatic.

Enumerator
LayoutVerticalAlignment_Auto	Default alignment of the node.
LayoutVerticalAlignment_Left	Top aligned.
LayoutVerticalAlignment_Center	Centered.
LayoutVerticalAlignment_Right	Bottom aligned.

Function Documentation

layout_create_headings_paragraphs_node()

GTextNodeVertical * layout_create_headings_paragraphs_node	(	const LayoutLayer *	layout,
		const LayoutNodeHeadingsParagraphsConfig *	config
	)

Create a vertical node with the layout's headings and paragraphs.

Parameters

layout	Layout whose headings and paragraphs attributes are shown.
config	Fonts and content size.

Returns

New node, or NULL if there are no headings.

layout_create_text_node_from_config()

GTextNode * layout_create_text_node_from_config	(	const LayoutLayer *	layout,
		const LayoutNodeConfig *	config
	)

Create a tree of text nodes from a config.

Parameters

layout	Layout the nodes belong to.
config	Root config, may be NULL.

Returns

New node tree, or NULL.

layout_node_create_kino_layer_wrapper()

GTextNodeCustom * layout_node_create_kino_layer_wrapper

(

KinoLayer *

kino_layer

)

Wrap a KinoLayer in a custom text node that positions the layer during layout.

Parameters

kino_layer

Layer to position; not owned.

Returns

New node.