The base class of all elements in the GUI. More...

#include <gui_region.hpp>

Inheritance diagram for lxgui::gui::region:

Public Member Functions
	region (utils::control_block &block, manager &mgr, const region_core_attributes &attr)
	Contructor.

	~region () override
	Destructor.

	region (const region &)=delete
	Non-copiable.

	region (region &&)=delete
	Non-movable.

region &	operator= (const region &)=delete
	Non-copiable.

region &	operator= (region &&)=delete
	Non-movable.

virtual void	render () const
	Renders this region on the current render target.

virtual void	update (float delta)
	Updates this region's logic.

virtual std::string	serialize (const std::string &tab) const
	Prints all relevant information about this region in a string.

virtual void	copy_from (const region &obj)
	Copies a region's parameters into this region (inheritance).

virtual void	notify_borders_need_update ()
	Tells this region that its borders need updating.

virtual void	notify_scaling_factor_updated ()
	Tells this region that the global interface scaling factor has changed.

const std::string &	get_name () const
	Returns this region's name.

const std::string &	get_raw_name () const
	Returns this region's raw name.

utils::observer_ptr< const frame >	get_parent () const
	Returns this region's parent.

const utils::observer_ptr< frame > &	get_parent ()
	Returns this region's parent.

virtual utils::owner_ptr< region >	release_from_parent ()
	Removes this region from its parent and return an owning pointer.

void	destroy ()
	Forcefully removes this region from the GUI.

void	set_alpha (float alpha)
	Changes this region's alpha (opacity).

float	get_alpha () const
	Returns this region's alpha (opacity).

float	get_effective_alpha () const
	Returns this region's effective alpha (opacity).

void	show ()
	shows this region.

void	hide ()
	hides this region.

void	set_shown (bool is_shown)
	shows/hides this region.

bool	is_shown () const
	Checks if this region is shown.

bool	is_visible () const
	Checks if this region can be seen on the screen.

bool	is_valid () const
	Checks if this region has all its borders correctly defined.

virtual void	set_dimensions (const vector2f &dimensions)
	Changes this region's absolute dimensions (in pixels).

virtual void	set_width (float abs_width)
	Changes this region's absolute width (in pixels).

virtual void	set_height (float abs_height)
	Changes this region's absolute height (in pixels).

void	set_relative_dimensions (const vector2f &dimensions)
	Changes this region's dimensions (relative to its parent).

void	set_relative_width (float rel_width)
	Changes this region's width (relative to its parent).

void	set_relative_height (float rel_height)
	Changes this region's height (relative to its parent).

const vector2f &	get_dimensions () const
	Returns this region's explicitly-defined width and height (in pixels).

vector2f	get_apparent_dimensions () const
	Returns this region's apparent width and height (in pixels).

bool	is_apparent_width_defined () const
	Checks if this region's apparent width is defined.

bool	is_apparent_height_defined () const
	Checks if this region's apparent height is defined.

virtual bool	is_in_region (const vector2f &position) const
	Checks if the provided coordinates are inside this region.

const std::string &	get_region_type () const
	Returns the type of this region.

bool	is_region_type (const std::string &type_name) const
	Checks if this region is of the provided type.

template<typename ObjectType >
bool	is_region_type () const
	Checks if this region is of the provided type.

bool	is_region_type (const region &obj) const
	Checks if this region is of a type equal or derived from the supplied region.

float	get_bottom () const
	Returns the vertical position of this region's bottom border.

vector2f	get_center () const
	Returns the position of this region's center.

float	get_left () const
	Returns the horizontal position of this region's left border.

float	get_right () const
	Returns the horizontal position of this region's right border.

float	get_top () const
	Returns the vertical position of this region's top border.

const bounds2f &	get_borders () const
	Returns this region's borders.

void	clear_all_anchors ()
	Removes all anchors.

void	set_all_anchors (const utils::observer_ptr< region > &obj)
	Adjusts this regions anchors to fit the provided region.

void	set_all_anchors (const std::string &obj_name)
	Adjusts this regions anchors to fit the provided region.

void	set_anchor (const anchor_data &a)
	Adds/replaces an anchor.

template<typename... Args>
void	set_anchor (Args &&... args)
	Adds/replaces an anchor.

bool	depends_on (const region &obj) const
	Checks if this region depends on another.

std::size_t	get_anchor_count () const
	Returns the number of defined anchors.

anchor &	modify_anchor (point p)
	Returns one of this region's anchor to modify it.

const anchor &	get_anchor (point p) const
	Returns one of this region's anchor.

const std::array< std::optional< anchor >, 9 > &	get_anchors () const
	Returns all of this region's anchors.

float	round_to_pixel (float value, utils::rounding_method method=utils::rounding_method::nearest) const
	Round an absolute position on screen to the nearest physical pixel.

vector2f	round_to_pixel (const vector2f &position, utils::rounding_method method=utils::rounding_method::nearest) const
	Round an absolute position on screen to the nearest physical pixel.

void	add_anchored_object (region &obj)
	Notifies this region that another one is anchored to it.

void	remove_anchored_object (region &obj)
	Notifies this region that another one is no longer anchored to it.

bool	is_virtual () const
	Checks if this region is virtual.

void	set_manually_inherited (bool manually_inherited)
	Flags this region as manually inherited or not.

bool	is_manually_inherited () const
	Checks if this object is manually inherited.

virtual utils::observer_ptr< const frame_renderer >	get_effective_frame_renderer () const
	Returns the renderer of this object or its parents.

utils::observer_ptr< frame_renderer >	get_effective_frame_renderer ()
	Returns the renderer of this object or its parents, nullptr if none.

virtual void	notify_renderer_need_redraw ()
	Notifies the renderer of this region that it needs to be redrawn.

const std::vector< utils::observer_ptr< region > > &	get_anchored_objects () const
	Returns the list of all objects that are anchored to this one.

virtual void	notify_loaded ()
	Notifies this region that it has been fully loaded.

bool	is_loaded () const
	Checks if this region has been fully loaded.

virtual void	notify_visible ()
	Notifies this region that it is now visible on screen.

virtual void	notify_invisible ()
	Notifies this region that it is no longer visible on screen.

void	set_addon (const addon *a)
	Sets the addon this frame belongs to.

const addon *	get_addon () const
	Returns this frame's addon.

std::string	parse_file_name (const std::string &file_name) const
	Convert an addon-relative file path to a application-relative path.

manager &	get_manager ()
	Returns this region's manager.

const manager &	get_manager () const
	Returns this region's manager.

registry &	get_registry ()
	Returns the UI object registry, which keeps track of all objects in the UI.

const registry &	get_registry () const
	Returns the UI object registry, which keeps track of all objects in the UI.

void	remove_glue ()
	Removes the Lua glue.

virtual void	parse_layout (const layout_node &node)
	Parses data from a layout_node.

Static Public Member Functions
static void	register_on_lua (sol::state &lua)
	Registers this region class to the provided Lua state.

Static Public Attributes
static constexpr const char *	class_name = "Region"

Protected Member Functions
virtual void	parse_attributes_ (const layout_node &node)

virtual void	parse_size_node_ (const layout_node &node)

virtual void	parse_anchor_node_ (const layout_node &node)

color	parse_color_node_ (const layout_node &node)

vector2< std::optional< float > >	parse_offset_node_ (const layout_node &node)

vector2< float >	parse_offset_node_or_ (const layout_node &node, float fallback)

std::pair< anchor_type, vector2< std::optional< float > > >	parse_dimension_node_ (const layout_node &node)

void	read_anchors_ (float &left, float &right, float &top, float &bottom, float &x_center, float &y_center) const

bool	make_borders_ (float &min, float &max, float center, float size) const

virtual void	update_borders_ ()

sol::state &	get_lua_ ()

const sol::state &	get_lua_ () const

template<typename T >
void	create_glue_ (T &self)

virtual const std::vector< std::string > &	get_type_list_ () const

void	set_lua_member_ (std::string key, sol::stack_object value)

sol::object	get_lua_member_ (const std::string &key) const

void	set_virtual_ ()
	Makes this region virtual.

void	set_name_ (const std::string &name)
	Sets this region's name.

virtual void	set_parent_ (utils::observer_ptr< frame > parent)
	Changes this region's parent.

template<typename T >
void	initialize_ (T &self, const region_core_attributes &attr)
	Set up function to call in all derived class constructors.

Static Protected Member Functions
template<typename T >
static const std::vector< std::string > &	get_type_list_impl_ ()

Protected Attributes
manager &	manager_

const addon *	addon_ = nullptr

std::string	name_

std::string	raw_name_

utils::observer_ptr< frame >	parent_ = nullptr

bool	is_manually_inherited_ = false

bool	is_virtual_ = false

bool	is_loaded_ = false

bool	is_valid_ = true

std::array< std::optional< anchor >, 9 >	anchor_list_

bounds2< bool >	defined_borders_

bounds2f	borders_

float	alpha_ = 1.0f

bool	is_shown_ = true

bool	is_visible_ = true

vector2f	dimensions_

std::vector< utils::observer_ptr< region > >	anchored_object_list_

Friends
template<typename ObjectType >
const ObjectType *	down_cast (const region *self)
	Obtain a pointer to a derived class.

template<typename ObjectType >
ObjectType *	down_cast (region *self)
	Obtain a pointer to a derived class.

Detailed Description

The base class of all elements in the GUI.

Objects of this class offers core functionalities needed by every element of the interface. They have a name, and a corresponding variable created in Lua to access them. They can have a parent lxgui::gui::frame. They can be placed on the screen at an absolute position, or relative to other regions. They can be shown or hidden.

Apart form this, a region does not contain anything, nor can it display anything on the screen. Any functionality beyond the list above is implemented in specialized subclasses (see the full list below).

Interaction between C++, Lua, and layout files. When a region is created, it must be given a name, for example "PlayerHealthBar". For as long as the object lives, this name will be used to refer to it. In particular, as soon as the object is created, regardless of whether this was done in C++, layout files, or Lua, a new variable will be created in the Lua state with the exact same name, PlayerHealthBar. This variable is a reference to the region, and can be used to interact with it dynamically. Because of this, each object must have a unique name, otherwise it could not be accessible from Lua.

Note: Although you can destroy this Lua variable by setting it to nil, this is not recommended: the object will not be destroyed (nor garbage-collected) because it still exists in the C++ memory space. The only way to truly destroy an object from Lua is to call delete_frame (for frames only). Destroying and creating objects has a cost however. If the object is likely to reappear later with the same content, simply hide it and show it again later on. If the content may change, you can also recycle the object, i.e., keep it alive and simply change its content when it later reappears.

Deleting an object from C++ is done using region::destroy. This will automatically delete all references to this object in Lua as well.

Finally, note that objects do not need to be explicitly destroyed: they will automatically be destroyed when their parent is itself destroyed (see below). Only use explicit destruction when absolutely necessary.

Parent-child relationship. Parents of regions are frames. See the lxgui::gui::frame class documentation for more information. One important aspect of the parent-child relationship is related to the object name. If a region has a parent, it can be given a name starting with "$parent". The name of the parent will automatically replace the "$parent" string. For example, if an object is named "$parentButton" and its parent is named "ErrorMessage", the final name of the object will be "ErrorMessageButton". It can be accessed from the Lua state as ErrorMessageButton, or as ErrorMessage.Button. This is particularly important when using inheritance, as the final name of an inherited child region then naturally depends on the name of its parent.

A child will inherit some properties from its parent: transparency, scaling, visibility (show/hide), strata (if not explicitly specified), level (incremented from its parent's), and renderer (if not explicitly specified). Note in particular that the parent-child relationship does not impose any link between the child and its parent's position and size: this must be done explicitly with anchors, as required.

Lastly, a child is owned by its parent: if the parent is destroyed, the child will be destroyed as well.

Positioning. regions have a position on the screen, but this is not parameterized as a simple pair of X and Y coordinates. Instead, objects are positioned based on a list of "anchors". Anchors are links between objects, which force one edge or one corner of a given object to match with the edge or corner of another object. For example, given two objects A and B, you can create an anchor that links the top-left corner of A to the top-left corner of B. The position of A will automatically be linked to the position of B, hence if B moves, A will follow. To further refine this positioning, you can specify anchor offsets: for example, you may want A's top-left corner to be shifted from B's top-left corner by two pixels in the X direction, and five in the Y direction. This offset can be defined either as an absolute number of pixels, or as a relative fraction of the size of the object being anchored to. For example, you can specify that A's top-left corner links to B's top-left corner, with an horizontal offset equal to 30% of B's width. Read the "Anchors" section below for more information.

An object which has no anchor will be considered "invalid" and will not be displayed.

Sizing. There are two ways to specify the size of a region. The first and most straightforward approach is to directly set its width and/or height. This must be specified as an absolute number of pixels. The second and more versatile method is to use more than one anchor for opposite sides of the object, for example an anchor for the "left" and another for the "right" edge. This will implicitly give a width to the object, depending on the position of the other objects to which it is anchored. Anchors will always override the absolute width and height of an object if they provide any constraint on the extents of the object in a given dimension.

An object which has neither a fixed absolute size, nor has it size implicitly constrained by anchors, is considered "invalid" and will not be displayed.

Anchors. There are nine available anchor points:

TOP_LEFT: constrains the max Y and min X.
TOP_RIGHT: constrains the max Y and max X.
BOTTOM_LEFT: constrains the min Y and min X.
BOTTOM_RIGHT: constrains the min Y and max X.
LEFT: constrains the min X and the midpoint in Y.
RIGHT: constrains the max X and the midpoint in Y.
TOP: constrains the max Y and the midpoint in X.
BOTTOM: constrains the min Y and the midpoint in X.
CENTER: constrains the midpoint in X and Y.

If you specify two constraints on the same point (for example: TOP_LEFT and BOTTOM_LEFT both constrain the min X coordinate), the most stringent constraint always wins. Constraints on the midpoints are more subtle however, as they will always be discarded when both the min and max are constrained. For example, consider an object A of fixed size 30x30 and some other object B of fixed size 40x40. If we anchor the RIGHT of A to the LEFT of B, A's vertical center will be automatically aligned with B's vertical center. This is the effect of the midpoint constraint. Now, if we further anchor the TOP of A to the TOP of B, we have more than one anchor constraining the vertical extents of A (see "Sizing" above), therefore A's fixed height of 30 pixels will be ignored from now on. It will shrink to a height of 20 pixels, i.e., the distance between B's top edge and its vertical center. Finally, if we further anchor the BOTTOM of A to the BOTTOM of B, the constraint on A's midpoint will be ignored: A will be enlarged to a height of 40 pixels, i.e., the distance between B's top and bottom edges.

Definition at line 161 of file gui_region.hpp.

Constructor & Destructor Documentation

◆ region() [1/3]

lxgui::gui::region::region	(	utils::control_block &	block,
		manager &	mgr,
		const region_core_attributes &	attr
	)

explicit

Contructor.

Definition at line 21 of file gui_region.cpp.

◆ ~region()

lxgui::gui::region::~region ( )

override

Destructor.

Definition at line 35 of file gui_region.cpp.

◆ region() [2/3]

lxgui::gui::region::region ( const region & )

delete

Non-copiable.

◆ region() [3/3]

lxgui::gui::region::region ( region && )

delete

Non-movable.

Member Function Documentation

◆ add_anchored_object()

void lxgui::gui::region::add_anchored_object ( region & obj )

Notifies this region that another one is anchored to it.

Parameters

obj	The anchored region

Note: Anchored objects get their borders automatically updated whenever this object's borders are updated.

Definition at line 561 of file gui_region.cpp.

◆ clear_all_anchors()

void lxgui::gui::region::clear_all_anchors ( )

Removes all anchors.

Note: This region and its children won't be visible until you define at least one anchor.

Definition at line 365 of file gui_region.cpp.

◆ copy_from()

void lxgui::gui::region::copy_from ( const region & obj )

virtual

Copies a region's parameters into this region (inheritance).

Parameters

obj	The region to copy

Reimplemented in lxgui::gui::animated_texture, lxgui::gui::button, lxgui::gui::check_button, lxgui::gui::edit_box, lxgui::gui::font_string, lxgui::gui::frame, lxgui::gui::scroll_frame, lxgui::gui::slider, lxgui::gui::status_bar, and lxgui::gui::texture.

Definition at line 128 of file gui_region.cpp.

◆ create_glue_()

template<typename T >

void lxgui::gui::region::create_glue_ ( T & self )

protected

Definition at line 136 of file gui_region_tpl.hpp.

◆ depends_on()

bool lxgui::gui::region::depends_on ( const region & obj ) const

Checks if this region depends on another.

Parameters

obj	The region to test

Note: Useful to detect circular references.

Definition at line 503 of file gui_region.cpp.

◆ destroy()

void lxgui::gui::region::destroy ( )

Forcefully removes this region from the GUI.

Warning: After calling this function, any pointer to the object is invalidated! Only call this function if you need the object to be destroyed early, before its parent (if any) would itself be destroyed.

Definition at line 333 of file gui_region.cpp.

◆ get_addon()

const addon * lxgui::gui::region::get_addon ( ) const

Returns this frame's addon.

Returns: This frame's addon

Note: Returns "nullptr" if the frame has been created by Lua code and wasn't assigned a parent.

Definition at line 843 of file gui_region.cpp.

◆ get_alpha()

float lxgui::gui::region::get_alpha ( ) const

Returns this region's alpha (opacity).

Returns: This region's alpha (opacity).

Definition at line 157 of file gui_region.cpp.

◆ get_anchor()

const anchor & lxgui::gui::region::get_anchor ( point p ) const

Returns one of this region's anchor.

Parameters

p	The anchor point

Returns: A pointer to the anchor, nullptr if none

Definition at line 539 of file gui_region.cpp.

◆ get_anchor_count()

std::size_t lxgui::gui::region::get_anchor_count ( ) const

Returns the number of defined anchors.

Returns: The number of defined anchors

Definition at line 519 of file gui_region.cpp.

◆ get_anchored_objects()

const std::vector< utils::observer_ptr< region > > & lxgui::gui::region::get_anchored_objects ( ) const

Returns the list of all objects that are anchored to this one.

Returns: The list of all objects that are anchored to this one

Definition at line 790 of file gui_region.cpp.

◆ get_anchors()

const std::array< std::optional< anchor >, 9 > & lxgui::gui::region::get_anchors ( ) const

Returns all of this region's anchors.

Returns: All of this region's anchors

Definition at line 549 of file gui_region.cpp.

◆ get_apparent_dimensions()

vector2f lxgui::gui::region::get_apparent_dimensions ( ) const

Returns this region's apparent width and height (in pixels).

Returns: This region's apparent width and height (in pixels)

Note: If you need to get the actual size of a region on the screen, use this function instead of get_dimensions(), as some regions may not have their dimensions explicitly defined, and instead get their extents from anchors.

Definition at line 276 of file gui_region.cpp.

◆ get_borders()

const bounds2f & lxgui::gui::region::get_borders ( ) const

Returns this region's borders.

Returns: This region's borders

Definition at line 361 of file gui_region.cpp.

◆ get_bottom()

float lxgui::gui::region::get_bottom ( ) const

Returns the vertical position of this region's bottom border.

Returns: The vertical position of this region's bottom border

Definition at line 357 of file gui_region.cpp.

◆ get_center()

vector2f lxgui::gui::region::get_center ( ) const

Returns the position of this region's center.

Returns: The position of this region's center

Definition at line 341 of file gui_region.cpp.

◆ get_dimensions()

const vector2f & lxgui::gui::region::get_dimensions ( ) const

Returns this region's explicitly-defined width and height (in pixels).

Returns: This region's explicitly-defined width and height (in pixels)

Note: If you need to get the actual size of a region on the screen, use get_apparent_dimensions(), as some regions may not have their dimensions explicitly defined, and instead get their extents from anchors. If a dimension is not explicitly defined, it will be returned as zero.

Definition at line 272 of file gui_region.cpp.

◆ get_effective_alpha()

float lxgui::gui::region::get_effective_alpha ( ) const

Returns this region's effective alpha (opacity).

Returns: This region's effective alpha (opacity).

Note: This includes the region's parent alpha.

Definition at line 161 of file gui_region.cpp.

◆ get_effective_frame_renderer() [1/2]

utils::observer_ptr< frame_renderer > lxgui::gui::region::get_effective_frame_renderer ( )

inline

Returns the renderer of this object or its parents, nullptr if none.

Returns: The renderer of this object or its parents, nullptr if none

Note: For more information, see frame::set_frame_renderer().

Definition at line 615 of file gui_region.hpp.

◆ get_effective_frame_renderer() [2/2]

utils::observer_ptr< const frame_renderer > lxgui::gui::region::get_effective_frame_renderer ( ) const

virtual

Returns the renderer of this object or its parents.

Returns: The renderer of this object or its parents

Note: For more information, see frame::set_frame_renderer().

Reimplemented in lxgui::gui::frame.

Definition at line 802 of file gui_region.cpp.

◆ get_left()

float lxgui::gui::region::get_left ( ) const

Returns the horizontal position of this region's left border.

Returns: The horizontal position of this region's left border

Definition at line 345 of file gui_region.cpp.

◆ get_lua_() [1/2]

sol::state & lxgui::gui::region::get_lua_ ( )

protected

Definition at line 767 of file gui_region.cpp.

◆ get_lua_() [2/2]

const sol::state & lxgui::gui::region::get_lua_ ( ) const

protected

Definition at line 771 of file gui_region.cpp.

◆ get_lua_member_()

sol::object lxgui::gui::region::get_lua_member_ ( const std::string & key ) const

protected

◆ get_manager() [1/2]

manager & lxgui::gui::region::get_manager ( )

inline

Returns this region's manager.

Returns: This region's manager

Definition at line 693 of file gui_region.hpp.

◆ get_manager() [2/2]

const manager & lxgui::gui::region::get_manager ( ) const

inline

Returns this region's manager.

Returns: This region's manager

Definition at line 701 of file gui_region.hpp.

◆ get_name()

const std::string & lxgui::gui::region::get_name ( ) const

Returns this region's name.

Returns: This region's name

Definition at line 140 of file gui_region.cpp.

◆ get_parent() [1/2]

const utils::observer_ptr< frame > & lxgui::gui::region::get_parent ( )

inline

Returns this region's parent.

Returns: This region's parent

Definition at line 237 of file gui_region.hpp.

◆ get_parent() [2/2]

utils::observer_ptr< const frame > lxgui::gui::region::get_parent ( ) const

inline

Returns this region's parent.

Returns: This region's parent

Definition at line 229 of file gui_region.hpp.

◆ get_raw_name()

const std::string & lxgui::gui::region::get_raw_name ( ) const

Returns this region's raw name.

Returns: This region's raw name

Note: This is the name of the region before "$parent" has been replaced by its parent's name.

Definition at line 144 of file gui_region.cpp.

◆ get_region_type()

const std::string & lxgui::gui::region::get_region_type ( ) const

Returns the type of this region.

Returns: The type of this region

Definition at line 148 of file gui_region.cpp.

◆ get_registry() [1/2]

registry & lxgui::gui::region::get_registry ( )

Returns the UI object registry, which keeps track of all objects in the UI.

Returns: The registry object

Definition at line 850 of file gui_region.cpp.

◆ get_registry() [2/2]

const registry & lxgui::gui::region::get_registry ( ) const

Returns the UI object registry, which keeps track of all objects in the UI.

Returns: The registry object

Definition at line 855 of file gui_region.cpp.

◆ get_right()

float lxgui::gui::region::get_right ( ) const

Returns the horizontal position of this region's right border.

Returns: The horizontal position of this region's right border

Definition at line 349 of file gui_region.cpp.

◆ get_top()

float lxgui::gui::region::get_top ( ) const

Returns the vertical position of this region's top border.

Returns: The vertical position of this region's top border

Definition at line 353 of file gui_region.cpp.

◆ get_type_list_()

const std::vector< std::string > & lxgui::gui::region::get_type_list_ ( ) const

protectedvirtual

Reimplemented in lxgui::gui::button, lxgui::gui::check_button, lxgui::gui::edit_box, lxgui::gui::frame, lxgui::gui::layered_region, lxgui::gui::scroll_frame, lxgui::gui::slider, and lxgui::gui::status_bar.

Definition at line 860 of file gui_region.cpp.

◆ get_type_list_impl_()

template<typename T >

const std::vector< std::string > & lxgui::gui::region::get_type_list_impl_ ( )

staticprotected

Definition at line 147 of file gui_region_tpl.hpp.

◆ hide()

void lxgui::gui::region::hide ( )

hides this region.

Note: All its children won't be visible on the screen anymore, even if they are still marked as shown.

Definition at line 186 of file gui_region.cpp.

◆ initialize_()

template<typename T >

void lxgui::gui::region::initialize_	(	T &	self,
		const region_core_attributes &	attr
	)

protected

Set up function to call in all derived class constructors.

Parameters

self	A pointer to the derived `this`
attr	The region attributes provided to the constructor

Definition at line 141 of file gui_region_tpl.hpp.

◆ is_apparent_height_defined()

bool lxgui::gui::region::is_apparent_height_defined ( ) const

Checks if this region's apparent height is defined.

Returns: 'true' if defined, 'false' otherwise

Note: The apparent height is defined if either the region's absolute or relative height is explicitly specified (from set_height(), set_relative_height(), set_dimensions(), or set_relative_dimensions()), or if its left and right borders are anchored. A region with an undefined apparent height will not be rendered on the screen until its height is defined.

Definition at line 284 of file gui_region.cpp.

◆ is_apparent_width_defined()

bool lxgui::gui::region::is_apparent_width_defined ( ) const

Checks if this region's apparent width is defined.

Returns: 'true' if defined, 'false' otherwise

Note: The apparent width is defined if either the region's absolute or relative width is explicitly specified (from set_width(), set_relative_width(), set_dimensions(), or set_relative_dimensions()), or if its left and right borders are anchored. A region with an undefined apparent width will not be rendered on the screen until its width is defined.

Definition at line 280 of file gui_region.cpp.

◆ is_in_region()

bool lxgui::gui::region::is_in_region ( const vector2f & position ) const

virtual

Checks if the provided coordinates are inside this region.

Parameters

position The coordinates to test

Returns: 'true' if the provided coordinates are inside this region

Reimplemented in lxgui::gui::frame, and lxgui::gui::slider.

Definition at line 288 of file gui_region.cpp.

◆ is_loaded()

bool lxgui::gui::region::is_loaded ( ) const

Checks if this region has been fully loaded.

Note: A region that is not fully loaded still has all its core attributes set, hence can be considered as "fully constructed" from a C++ point of view. However, semantically, the object may need further steps to be complete, as designed by the UI designer. Therefore, form the UI's point of view, a region is considered "complete" only if is_loaded() returns 'true' (see notifu_loaded()). Only then can the region, e.g., react to or generate events.

Definition at line 798 of file gui_region.cpp.

◆ is_manually_inherited()

bool lxgui::gui::region::is_manually_inherited ( ) const

Checks if this object is manually inherited.

Returns: 'true' if this object is manually inherited

Note: For more information, see set_manually_inherited().

Definition at line 784 of file gui_region.cpp.

◆ is_region_type() [1/3]

template<typename ObjectType >

bool lxgui::gui::region::is_region_type ( ) const

inline

Checks if this region is of the provided type.

Returns: 'true' if this region is of the provided type

Definition at line 423 of file gui_region.hpp.

◆ is_region_type() [2/3]

bool lxgui::gui::region::is_region_type ( const region & obj ) const

inline

Checks if this region is of a type equal or derived from the supplied region.

Returns: 'true' if this region is of a type equal or derived from the supplied region

Definition at line 431 of file gui_region.hpp.

◆ is_region_type() [3/3]

bool lxgui::gui::region::is_region_type ( const std::string & type_name ) const

Checks if this region is of the provided type.

Parameters

type_name The type to test

Returns: 'true' if this region is of the provided type

Definition at line 152 of file gui_region.cpp.

◆ is_shown()

bool lxgui::gui::region::is_shown ( ) const

Checks if this region is shown.

Returns: 'true' if this region is shown

Definition at line 203 of file gui_region.cpp.

◆ is_valid()

bool lxgui::gui::region::is_valid ( ) const

Checks if this region has all its borders correctly defined.

Returns: 'true' if this region has all its borders correctly defined

Note: To be valid, a region needs to have a defined position and size along both the X and Y dimensions. This means either one anchor and a set size, or two opposite anchors. For example, any anchor plus a call to set_dimensions(). Or a top_left plus a bottom_right anchors. Or a left plus a right anchors plus a call to set_height().

Definition at line 211 of file gui_region.cpp.

◆ is_virtual()

bool lxgui::gui::region::is_virtual ( ) const

Checks if this region is virtual.

Returns: 'true' if this region is virtual

Note: A virtual region will not be displayed on the screen, but can serve as a template to create new GUI elements (it is then "inherited", although note that this has no connection to C++ inheritance).

Definition at line 553 of file gui_region.cpp.

◆ is_visible()

bool lxgui::gui::region::is_visible ( ) const

Checks if this region can be seen on the screen.

Returns: 'true' if this region can be seen on the screen

Definition at line 207 of file gui_region.cpp.

◆ make_borders_()

bool lxgui::gui::region::make_borders_	(	float &	min,
		float &	max,
		float	center,
		float	size
	)		const

protected

Definition at line 585 of file gui_region.cpp.

◆ modify_anchor()

anchor & lxgui::gui::region::modify_anchor ( point p )

Returns one of this region's anchor to modify it.

Parameters

p	The anchor point

Returns: A reference to the anchor, will throw if this point has no anchor.

Note: After you have modified the anchor, you must call notify_borders_need_update() to ensure that the object's borders are properly updated.

Definition at line 529 of file gui_region.cpp.

◆ notify_borders_need_update()

void lxgui::gui::region::notify_borders_need_update ( )

virtual

Tells this region that its borders need updating.

Reimplemented in lxgui::gui::slider.

Definition at line 744 of file gui_region.cpp.

◆ notify_invisible()

void lxgui::gui::region::notify_invisible ( )

virtual

Notifies this region that it is no longer visible on screen.

Note: Automatically called by show()/hide().

Reimplemented in lxgui::gui::frame.

Definition at line 813 of file gui_region.cpp.

◆ notify_loaded()

void lxgui::gui::region::notify_loaded ( )

virtual

Notifies this region that it has been fully loaded.

See also: is_loaded()

Reimplemented in lxgui::gui::frame.

Definition at line 794 of file gui_region.cpp.

◆ notify_renderer_need_redraw()

void lxgui::gui::region::notify_renderer_need_redraw ( )

virtual

Notifies the renderer of this region that it needs to be redrawn.

Note: Automatically called by any shape-changing function.

Reimplemented in lxgui::gui::frame, and lxgui::gui::layered_region.

Definition at line 788 of file gui_region.cpp.

◆ notify_scaling_factor_updated()

void lxgui::gui::region::notify_scaling_factor_updated ( )

virtual

Tells this region that the global interface scaling factor has changed.

Reimplemented in lxgui::gui::edit_box, lxgui::gui::font_string, lxgui::gui::frame, and lxgui::gui::scroll_frame.

Definition at line 759 of file gui_region.cpp.

◆ notify_visible()

void lxgui::gui::region::notify_visible ( )

virtual

Notifies this region that it is now visible on screen.

Note: Automatically called by show()/hide().

Reimplemented in lxgui::gui::frame.

Definition at line 808 of file gui_region.cpp.

◆ operator=() [1/2]

region & lxgui::gui::region::operator= ( const region & )

delete

Non-copiable.

◆ operator=() [2/2]

region & lxgui::gui::region::operator= ( region && )

delete

Non-movable.

◆ parse_anchor_node_()

void lxgui::gui::region::parse_anchor_node_ ( const layout_node & node )

protectedvirtual

Definition at line 89 of file gui_region_parser.cpp.

◆ parse_attributes_()

void lxgui::gui::region::parse_attributes_ ( const layout_node & node )

protectedvirtual

Reimplemented in lxgui::gui::button, lxgui::gui::edit_box, lxgui::gui::frame, lxgui::gui::layered_region, lxgui::gui::slider, and lxgui::gui::status_bar.

Definition at line 133 of file gui_region_parser.cpp.

◆ parse_color_node_()

color lxgui::gui::region::parse_color_node_ ( const layout_node & node )

protected

Definition at line 10 of file gui_region_parser.cpp.

◆ parse_dimension_node_()

std::pair< anchor_type, vector2< std::optional< float > > > lxgui::gui::region::parse_dimension_node_ ( const layout_node & node )

protected

Definition at line 35 of file gui_region_parser.cpp.

◆ parse_file_name()

std::string lxgui::gui::region::parse_file_name ( const std::string & file_name ) const

Convert an addon-relative file path to a application-relative path.

Parameters

file_name The raw file name

Returns: The modified file name

Note: All file names must be relative to the current working directory (typically, the application's executable path), but sometimes it is more convenient and maintainable to specify a path that is relative to the addon directory. This can be achieved by simply putting "|" in front of a file name, which will then be interpreted as relative to the addon directory. This function takes care of this transformation.

Definition at line 818 of file gui_region.cpp.

◆ parse_layout()

void lxgui::gui::region::parse_layout ( const layout_node & node )

virtual

Parses data from a layout_node.

Parameters

node	The layout node

Reimplemented in lxgui::gui::frame, lxgui::gui::animated_texture, lxgui::gui::font_string, lxgui::gui::layered_region, and lxgui::gui::texture.

Definition at line 127 of file gui_region_parser.cpp.

◆ parse_offset_node_()

vector2< std::optional< float > > lxgui::gui::region::parse_offset_node_ ( const layout_node & node )

protected

Definition at line 24 of file gui_region_parser.cpp.

◆ parse_offset_node_or_()

vector2< float > lxgui::gui::region::parse_offset_node_or_	(	const layout_node &	node,
		float	fallback
	)

protected

Definition at line 28 of file gui_region_parser.cpp.

◆ parse_size_node_()

void lxgui::gui::region::parse_size_node_ ( const layout_node & node )

protectedvirtual

Definition at line 65 of file gui_region_parser.cpp.

◆ read_anchors_()

void lxgui::gui::region::read_anchors_	(	float &	left,
		float &	right,
		float &	top,
		float &	bottom,
		float &	x_center,
		float &	y_center
	)		const

protected

Definition at line 614 of file gui_region.cpp.

◆ register_on_lua()

static void lxgui::gui::region::register_on_lua ( sol::state & lua )

static

Registers this region class to the provided Lua state.

◆ release_from_parent()

utils::owner_ptr< region > lxgui::gui::region::release_from_parent ( )

virtual

Removes this region from its parent and return an owning pointer.

Returns: An owning pointer to this region

Reimplemented in lxgui::gui::frame, and lxgui::gui::layered_region.

Definition at line 329 of file gui_region.cpp.

◆ remove_anchored_object()

void lxgui::gui::region::remove_anchored_object ( region & obj )

Notifies this region that another one is no longer anchored to it.

Parameters

obj	The region no longer anchored

See also: add_anchored_object()

Definition at line 565 of file gui_region.cpp.

◆ remove_glue()

void lxgui::gui::region::remove_glue ( )

Removes the Lua glue.

Definition at line 775 of file gui_region.cpp.

◆ render()

void lxgui::gui::region::render ( ) const

virtual

Renders this region on the current render target.

Reimplemented in lxgui::gui::animated_texture, lxgui::gui::font_string, lxgui::gui::frame, and lxgui::gui::texture.

Definition at line 765 of file gui_region.cpp.

◆ round_to_pixel() [1/2]

vector2f lxgui::gui::region::round_to_pixel	(	const vector2f &	position,
		utils::rounding_method	method = `utils::rounding_method::nearest`
	)		const

Round an absolute position on screen to the nearest physical pixel.

Parameters

position	The input absolute position (can be fractional)
method	The rounding method

Returns: The position of the nearest physical pixel

Definition at line 578 of file gui_region.cpp.

◆ round_to_pixel() [2/2]

float lxgui::gui::region::round_to_pixel	(	float	value,
		utils::rounding_method	method = `utils::rounding_method::nearest`
	)		const

Round an absolute position on screen to the nearest physical pixel.

Parameters

value	The input absolute position (can be fractional)
method	The rounding method

Returns: The position of the nearest physical pixel

Definition at line 573 of file gui_region.cpp.

◆ serialize()

std::string lxgui::gui::region::serialize ( const std::string & tab ) const

virtual

Prints all relevant information about this region in a string.

Parameters

tab	The offset to give to all lines

Returns: All relevant information about this region

Reimplemented in lxgui::gui::animated_texture, lxgui::gui::button, lxgui::gui::check_button, lxgui::gui::font_string, lxgui::gui::frame, lxgui::gui::layered_region, lxgui::gui::slider, lxgui::gui::status_bar, and lxgui::gui::texture.

Definition at line 91 of file gui_region.cpp.

◆ set_addon()

void lxgui::gui::region::set_addon ( const addon * a )

Sets the addon this frame belongs to.

Parameters

a	The addon this frame belongs to

Definition at line 833 of file gui_region.cpp.

◆ set_all_anchors() [1/2]

void lxgui::gui::region::set_all_anchors ( const std::string & obj_name )

Adjusts this regions anchors to fit the provided region.

Parameters

obj_name The name of the object to fit to

Note: Removes all anchors and defines two new ones.

Definition at line 404 of file gui_region.cpp.

◆ set_all_anchors() [2/2]

void lxgui::gui::region::set_all_anchors ( const utils::observer_ptr< region > & obj )

Adjusts this regions anchors to fit the provided region.

Parameters

obj	A pointer to the object you want to wrap

Note: Removes all anchors and defines two new ones.

Definition at line 437 of file gui_region.cpp.

◆ set_alpha()

void lxgui::gui::region::set_alpha ( float alpha )

Changes this region's alpha (opacity).

Parameters

alpha The new alpha value

Note: Default is 1.0f.

Definition at line 169 of file gui_region.cpp.

◆ set_anchor() [1/2]

template<typename... Args>

void lxgui::gui::region::set_anchor ( Args &&... args )

inline

Adds/replaces an anchor.

Parameters

args	Argument to construct a new anchor_data

Definition at line 503 of file gui_region.hpp.

◆ set_anchor() [2/2]

void lxgui::gui::region::set_anchor ( const anchor_data & a )

Adds/replaces an anchor.

Parameters

a	The anchor to add

Definition at line 473 of file gui_region.cpp.

◆ set_dimensions()

void lxgui::gui::region::set_dimensions ( const vector2f & dimensions )

virtual

Changes this region's absolute dimensions (in pixels).

Parameters

dimensions The new dimensions

Reimplemented in lxgui::gui::frame.

Definition at line 215 of file gui_region.cpp.

◆ set_height()

void lxgui::gui::region::set_height ( float abs_height )

virtual

Changes this region's absolute height (in pixels).

Parameters

abs_height The new height

Reimplemented in lxgui::gui::frame.

Definition at line 239 of file gui_region.cpp.

◆ set_lua_member_()

void lxgui::gui::region::set_lua_member_	(	std::string	key,
		sol::stack_object	value
	)

protected

◆ set_manually_inherited()

void lxgui::gui::region::set_manually_inherited ( bool manually_inherited )

Flags this region as manually inherited or not.

Note: By default, all regions are automatically inherited. This is generally the desired behavior for regions defined by the user, but it is less desirable for "special" or "internal" regions necessary for the proper operation of some region types (e.g., the texture used by a button), which need special treatment or registration.

Definition at line 780 of file gui_region.cpp.

◆ set_name_()

void lxgui::gui::region::set_name_ ( const std::string & name )

protected

Sets this region's name.

Parameters

name	This region's name

Note: Can only be called once. If you need to set both the name and the parent at the same time (typically, at creation), use set_name_and_parent_().

Definition at line 294 of file gui_region.cpp.

◆ set_parent_()

void lxgui::gui::region::set_parent_ ( utils::observer_ptr< frame > parent )

protectedvirtual

Changes this region's parent.

Parameters

parent The new parent

Note: Default is nullptr.

Reimplemented in lxgui::gui::frame.

Definition at line 312 of file gui_region.cpp.

◆ set_relative_dimensions()

void lxgui::gui::region::set_relative_dimensions ( const vector2f & dimensions )

Changes this region's dimensions (relative to its parent).

Parameters

dimensions The new dimensions (relative)

Definition at line 251 of file gui_region.cpp.

◆ set_relative_height()

void lxgui::gui::region::set_relative_height ( float rel_height )

Changes this region's height (relative to its parent).

Parameters

rel_height The new height

Definition at line 265 of file gui_region.cpp.

◆ set_relative_width()

void lxgui::gui::region::set_relative_width ( float rel_width )

Changes this region's width (relative to its parent).

Parameters

rel_width The new width

Definition at line 258 of file gui_region.cpp.

◆ set_shown()

void lxgui::gui::region::set_shown ( bool is_shown )

shows/hides this region.

Parameters

is_shown 'true' if you want to show this region

Note: See show() and hide() for more information.

Definition at line 196 of file gui_region.cpp.

◆ set_virtual_()

void lxgui::gui::region::set_virtual_ ( )

protected

Makes this region virtual.

Note: See is_virtual().

Definition at line 557 of file gui_region.cpp.

◆ set_width()

void lxgui::gui::region::set_width ( float abs_width )

virtual

Changes this region's absolute width (in pixels).

Parameters

abs_width The new width

Reimplemented in lxgui::gui::frame.

Definition at line 227 of file gui_region.cpp.

◆ show()

void lxgui::gui::region::show ( )

shows this region.

Note: Its parent must be shown for it to appear on the screen.

Definition at line 176 of file gui_region.cpp.

◆ update()

void lxgui::gui::region::update ( float delta )

virtual

Updates this region's logic.

Parameters

delta Time spent since last update

Reimplemented in lxgui::gui::frame, and lxgui::gui::animated_texture.

Definition at line 763 of file gui_region.cpp.

◆ update_borders_()

void lxgui::gui::region::update_borders_ ( )

protectedvirtual

Reimplemented in lxgui::gui::frame.

Definition at line 669 of file gui_region.cpp.

Friends And Related Symbol Documentation

◆ down_cast [1/2]

template<typename ObjectType >

const ObjectType * down_cast ( const region * self )

friend

Obtain a pointer to a derived class.

Parameters

self	The pointer to down cast

Returns: A pointer to a derived class

Note: Like dynamic_cast(), this will return nullptr if this region is not of the requested type. However, it will throw if the cast failed because the derived class destructor has already been called. This indicates a programming error.

Definition at line 837 of file gui_region.hpp.

◆ down_cast [2/2]

template<typename ObjectType >

ObjectType * down_cast ( region * self )

friend

Obtain a pointer to a derived class.

Parameters

self	The pointer to down cast

Returns: A pointer to a derived class

Note: Like dynamic_cast(), this will return nullptr if this region is not of the requested type. However, it will throw if the cast failed because the derived class destructor has already been called. This indicates a programming error.

Definition at line 886 of file gui_region.hpp.

Member Data Documentation

◆ addon_

const addon* lxgui::gui::region::addon_ = nullptr

protected

Definition at line 802 of file gui_region.hpp.

◆ alpha_

float lxgui::gui::region::alpha_ = 1.0f

protected

Definition at line 818 of file gui_region.hpp.

◆ anchor_list_

std::array<std::optional<anchor>, 9> lxgui::gui::region::anchor_list_

protected

Definition at line 814 of file gui_region.hpp.

◆ anchored_object_list_

std::vector<utils::observer_ptr<region> > lxgui::gui::region::anchored_object_list_

protected

Definition at line 824 of file gui_region.hpp.

◆ borders_

bounds2f lxgui::gui::region::borders_

protected

Definition at line 816 of file gui_region.hpp.

◆ class_name

constexpr const char* lxgui::gui::region::class_name = "Region"

staticconstexpr

Definition at line 735 of file gui_region.hpp.

◆ defined_borders_

bounds2<bool> lxgui::gui::region::defined_borders_

protected

Definition at line 815 of file gui_region.hpp.

◆ dimensions_

vector2f lxgui::gui::region::dimensions_

protected

Definition at line 822 of file gui_region.hpp.

◆ is_loaded_

bool lxgui::gui::region::is_loaded_ = false

protected

Definition at line 811 of file gui_region.hpp.

◆ is_manually_inherited_

bool lxgui::gui::region::is_manually_inherited_ = false

protected

Definition at line 809 of file gui_region.hpp.

◆ is_shown_

bool lxgui::gui::region::is_shown_ = true

protected

Definition at line 819 of file gui_region.hpp.

◆ is_valid_

bool lxgui::gui::region::is_valid_ = true

protected

Definition at line 812 of file gui_region.hpp.

◆ is_virtual_

bool lxgui::gui::region::is_virtual_ = false

protected

Definition at line 810 of file gui_region.hpp.

◆ is_visible_

bool lxgui::gui::region::is_visible_ = true

protected

Definition at line 820 of file gui_region.hpp.

◆ manager_

manager& lxgui::gui::region::manager_

protected

Definition at line 800 of file gui_region.hpp.

◆ name_

std::string lxgui::gui::region::name_

protected

Definition at line 804 of file gui_region.hpp.

◆ parent_

utils::observer_ptr<frame> lxgui::gui::region::parent_ = nullptr

protected

Definition at line 807 of file gui_region.hpp.

◆ raw_name_

std::string lxgui::gui::region::raw_name_

protected

Definition at line 805 of file gui_region.hpp.

The documentation for this class was generated from the following files:

/home/runner/work/lxgui/lxgui/include/lxgui/gui_region.hpp
/home/runner/work/lxgui/lxgui/src/gui_region.cpp
/home/runner/work/lxgui/lxgui/src/gui_region_parser.cpp
/home/runner/work/lxgui/lxgui/include/lxgui/gui_region_tpl.hpp

Public Member Functions

Static Public Member Functions

Static Public Attributes

Protected Member Functions

Static Protected Member Functions

Protected Attributes

Friends

Detailed Description

Constructor & Destructor Documentation

◆ region() [1/3]

◆ ~region()

◆ region() [2/3]

◆ region() [3/3]

Member Function Documentation

◆ add_anchored_object()

◆ clear_all_anchors()

◆ copy_from()

◆ create_glue_()

◆ depends_on()

◆ destroy()

◆ get_addon()

◆ get_alpha()

◆ get_anchor()

◆ get_anchor_count()

◆ get_anchored_objects()

◆ get_anchors()

◆ get_apparent_dimensions()

◆ get_borders()

◆ get_bottom()

◆ get_center()

◆ get_dimensions()

◆ get_effective_alpha()

◆ get_effective_frame_renderer() [1/2]

◆ get_effective_frame_renderer() [2/2]

◆ get_left()

◆ get_lua_() [1/2]

◆ get_lua_() [2/2]

◆ get_lua_member_()

◆ get_manager() [1/2]

◆ get_manager() [2/2]

◆ get_name()

◆ get_parent() [1/2]

◆ get_parent() [2/2]

◆ get_raw_name()

◆ get_region_type()

◆ get_registry() [1/2]

◆ get_registry() [2/2]

◆ get_right()

◆ get_top()

◆ get_type_list_()

◆ get_type_list_impl_()

◆ hide()

◆ initialize_()

◆ is_apparent_height_defined()

◆ is_apparent_width_defined()

◆ is_in_region()

◆ is_loaded()

◆ is_manually_inherited()

◆ is_region_type() [1/3]

◆ is_region_type() [2/3]

◆ is_region_type() [3/3]

◆ is_shown()

◆ is_valid()

◆ is_virtual()

◆ is_visible()

◆ make_borders_()

◆ modify_anchor()

◆ notify_borders_need_update()

◆ notify_invisible()

◆ notify_loaded()

◆ notify_renderer_need_redraw()

◆ notify_scaling_factor_updated()

◆ notify_visible()

◆ operator=() [1/2]

◆ operator=() [2/2]

◆ parse_anchor_node_()

◆ parse_attributes_()

◆ parse_color_node_()

◆ parse_dimension_node_()

◆ parse_file_name()