An extended version of RibbonWidget, with more capabilities. More...

#include <dynamic_ribbon_widget.hpp>

Inheritance diagram for GUIEngine::DynamicRibbonWidget:

Public Member Functions
	DynamicRibbonWidget (const bool combo, const bool multi_row)

void	addItem (const irr::core::stringw &user_name, const std::string &code_name, const std::string &image_file, const unsigned int badge=0, IconButtonWidget::IconPathType image_path_type=IconButtonWidget::ICON_PATH_TYPE_RELATIVE)
	Dynamically add an item to the ribbon's list of items (will not be visible until you call 'updateItemDisplay' or 'add'). More...

void	addAnimatedItem (const irr::core::stringw &user_name, const std::string &code_name, const std::vector< std::string > &image_files, const float time_per_frame, const unsigned int badge=0, IconButtonWidget::IconPathType image_path_type=IconButtonWidget::ICON_PATH_TYPE_RELATIVE)
	Dynamically add an animated item to the ribbon's list of items (will not be visible until you call 'updateItemDisplay' or 'add'). More...

void	clearItems ()
	Clears all items added through 'addItem'. More...

void	setBadge (const std::string &name, BadgeType badge)

template<typename Compare >
void	sortItems (Compare comp)
	Sort the list of items with a given comparator. More...

void	registerHoverListener (DynamicRibbonHoverListener *listener)
	Register a listener to be notified of selection changes within the ribbon. More...

EventPropagation	rightPressed (const int playerID)
	Called when right key is pressed.

EventPropagation	leftPressed (const int playerID)
	Called when left key is pressed.

void	updateItemDisplay ()
	Updates icons/labels given current items and scrolling offset, taking care of resizing the dynamic ribbon if the number of items changed.

const std::string &	getSelectionIDString (const int playerID)
	Get the internal name (ID) of the selected item.

irr::core::stringw	getSelectionText (const int playerID)
	Get the user-visible text of the selected item.

const std::vector< ItemDescription > &	getItems () const
	Returns a read-only list of items added to this ribbon.

bool	setSelection (int item_id, const int playerID, const bool focusIt, bool evenIfDeactivated=false)
	Select an item from its numerical ID. More...

bool	setSelection (const std::string &item_codename, const int playerID, const bool focusIt, bool evenIfDeactivated=false)
	Select an item from its codename. More...

virtual void	elementRemoved ()
	Callback from parent class Widget. More...

virtual void	onRibbonWidgetScroll (const int delta_x)
	callback from IRibbonListener

virtual void	onRibbonWidgetFocus (RibbonWidget *emitter, const int playerID)
	callback from IRibbonListener

virtual void	onSelectionChange ()
	callback from IRibbonListener

virtual void	setText (const irr::core::stringw &text)
	Sets the text of a widget from a wchar_t. More...

virtual void	update (float delta)
	Override in children to possibly receive updates (you may need to register to them first)

void	setItemCountHint (int hint)
	Set approximately how many items are expected to be in this ribbon; will help the layout algorithm next time add() is called.

void	setMaxLabelLength (int length)
	Set max length of displayed text. More...

void	registerScrollCallback (void(callback)(void data), void *data)

Public Member Functions inherited from GUIEngine::Widget
	Widget (WidgetType type, bool reserve_id=false)

virtual void	setEventCallbackActive (Input::InputType type, bool active)
	Allow (or not) an event callback for this widget based on input type.

virtual bool	isEventCallbackActive (Input::InputType type) const
	Return if there should be an event callback for this widget based on input type.

void	setParent (irr::gui::IGUIElement *parent)
	Set the irrlicht widget to be used as parent of this widget next time Widget::add() is invoked on this widget.

virtual void	setVisible (bool visible)
	Sets the widget (and its children, if any) visible or not. More...

virtual void	setCollapsed (bool collapsed, Screen *calling_screen=NULL)
	Sets the widget (and its children, if any) collapsed or not. More...

virtual void	setCollapsed (bool collapsed, int uncollapsed_height, Screen *calling_screen=NULL)
	Sets the widget (and its children, if any) collapsed or not. More...

bool	isVisible () const
	Returns if the element is visible. More...

bool	isCollapsed () const
	Returns whether the element is collapsed (through setCollapsed). More...

bool	isActivated () const

virtual EventPropagation	onActivationInput (const int playerID)

virtual void	move (const int x, const int y, const int w, const int h)
	Call to resize/move the widget. More...

bool	isSelected (const int playerID) const
	Get whether this widget is selected (only makes sense in some cases where a widget is part of a bigger widget, e.g. More...

void	setSelected (const int playerID, bool state)

bool	isBottomBar () const

bool	isTopBar () const

bool	ok () const

virtual EventPropagation	onClick ()
	Gets called when the widget is active and got clicked. More...

virtual irr::core::dimension2di	getDimension () const

virtual void	setActive (bool active=true)
	Sets an widget to be either activated or deactivated (i.e. More...

template<typename T >
T *	getIrrlichtElement ()
	Get the underlying irrLicht GUI element, casted to the right type.

template<typename T >
const T *	getIrrlichtElement () const
	Get the underlying irrLicht GUI element, casted to the right type; const version.

irr::gui::IGUIElement *	getIrrlichtElement ()
	Get the underlying irrLicht GUI element.

void	moveIrrlichtElement ()

bool	isSameIrrlichtWidgetAs (const Widget *ref) const

const irr::core::stringw &	getText () const
	Returns the text of a widget. More...

WidgetType	getType () const

int	getID () const
	Get the irrlicht widget ID attributed to this widget. More...

bool	isFocusable () const
	Get whether this object is allowed to receive focus.

void	setFocusable (bool f)

void	setFocusForPlayer (const int playerID)
	Focus the widget for the given player. More...

bool	isFocusedForPlayer (const int playerID)
	Find whether this widget is focused by a given player. More...

void	unsetFocusForPlayer (const int playerID)
	Internal method, do not call it. More...

const PtrVector< Widget > &	getChildren () const

PtrVector< Widget > &	getChildren ()

bool	deleteChild (const char *id)
	removes and deletes the child with the given PROP_ID More...

bool	searchInsideMe () const

virtual int	getWidthNeededAroundLabel () const
	When inferring widget size from its label length, this method will be called to if/how much space must be added to the raw label's size for the widget to be large enough.

virtual int	getHeightNeededAroundLabel () const
	When inferring widget size from its label length, this method will be called to if/how much space must be added to the raw label's size for the widget to be large enough.

void	setBadge (BadgeType badge_bit)
	adds a particular badge to this widget. More...

void	unsetBadge (BadgeType badge_bit)
	removes a particular bade from this widget, if it had it. More...

void	resetAllBadges ()
	sets this widget to have no badge More...

int	getBadges () const
	Get which badges are currently on this widget. More...

bool	hasTooltip () const

irr::core::stringw	getTooltipText () const
	Only call if hasTooltip() returned true.

void	setTooltip (irr::core::stringw s)

Public Attributes
PtrVector< RibbonWidget, REF >	m_rows
	Reference pointers only, the actual instances are owned by m_children. More...

Public Attributes inherited from GUIEngine::Widget
Widget *	m_event_handler
	This is set to NULL by default; set to something else in a widget to mean that events happening on this widget should also be passed to m_event_handler->transmitEvent, which is usually the parent analysing events from its children. More...

bool	m_supports_multiplayer
	Whether this widget supports multiplayer interaction (i.e. More...

int	m_tab_down_root
	Instead of searching for widget IDs smaller/greater than that of this object, navigation through widgets will start from these IDs (if they are set). More...

int	m_tab_up_root
	Instead of searching for widget IDs smaller/greater than that of this object, navigation through widgets will start from these IDs (if they are set). More...

int	m_x
	Coordinates of the widget once added (the difference between those x/h and PROP_WIDTH/PROP_HEIGHT is that the props are read in raw form from the XML file; PROP_WIDTH can then be e.g. More...

int	m_y

int	m_w

int	m_h

bool	m_show_bounding_box
	Whether to show a bounding box around this widget (used for sections)

bool	m_is_bounding_box_round
	Only used if m_show_bounding_box is true.

int	m_reserved_id
	Used in two cases : 1) For 'placeholder' divisions; at the time the layout is created, there is nothing to place there yet, but we know there eventually will. More...

std::map< Property, std::string >	m_properties
	A map that holds values for all specified widget properties (in the XML file) More...

Public Attributes inherited from GUIEngine::SkinWidgetContainer
int	m_skin_x

int	m_skin_y

int	m_skin_w

int	m_skin_h

bool	m_skin_dest_areas_inited

bool	m_skin_dest_areas_yflip_inited

int	m_skin_dest_x

int	m_skin_dest_y

int	m_skin_dest_x2

int	m_skin_dest_y2

core::rect< s32 >	m_skin_dest_area_left

core::rect< s32 >	m_skin_dest_area_center

core::rect< s32 >	m_skin_dest_area_right

core::rect< s32 >	m_skin_dest_area_top

core::rect< s32 >	m_skin_dest_area_bottom

core::rect< s32 >	m_skin_dest_area_top_left

core::rect< s32 >	m_skin_dest_area_top_right

core::rect< s32 >	m_skin_dest_area_bottom_left

core::rect< s32 >	m_skin_dest_area_bottom_right

core::rect< s32 >	m_skin_dest_area_left_yflip

core::rect< s32 >	m_skin_dest_area_center_yflip

core::rect< s32 >	m_skin_dest_area_right_yflip

core::rect< s32 >	m_skin_dest_area_top_yflip

core::rect< s32 >	m_skin_dest_area_bottom_yflip

core::rect< s32 >	m_skin_dest_area_top_left_yflip

core::rect< s32 >	m_skin_dest_area_top_right_yflip

core::rect< s32 >	m_skin_dest_area_bottom_left_yflip

core::rect< s32 >	m_skin_dest_area_bottom_right_yflip

short	m_skin_r

short	m_skin_g

short	m_skin_b

Private Member Functions
RibbonWidget *	getSelectedRibbon (const int playerID)
	Returns the currently selected row.

RibbonWidget *	getRowContaining (Widget *w)
	Returns the row.

void	updateLabel (RibbonWidget *from_this_ribbon=NULL)
	Updates the visible label to match the currently selected item.

void	propagateSelection ()
	Even though the ribbon grid widget looks like a grid, it is really a vertical stack of independant ribbons. More...

EventPropagation	focused (const int playerID)
	Callback called widget is focused.

void	buildInternalStructure ()
	Removes all previously added contents icons, and re-adds them (calculating the new amount)

void	scroll (int x_delta, bool evenIfDeactivated=false)
	Call this to scroll within a scrollable ribbon.

virtual void	add ()
	Callbacks.

virtual EventPropagation	mouseHovered (Widget *child, const int playerID)
	used when you set eventSupervisors - see m_event_handler explainations below called when one of a widget's children is hovered. More...

virtual EventPropagation	transmitEvent (Widget *w, const std::string &originator, const int playerID)
	All widgets, including their parents (m_event_handler) will be notified on event through this call. More...

bool	findItemInRows (const char name, int p_row, int *p_id)

float	getFontScale (int icon_width) const

void	setLabelSize (const irr::core::stringw &text)

irr::core::stringw	getUserName (const irr::core::stringw &user_name) const

Private Attributes
PtrVector< DynamicRibbonHoverListener >	m_hover_listeners
	A list of all listeners that registered to be notified on hover/selection.

bool	m_has_label
	Used for ribbon grids that have a label at the bottom.

irr::gui::IGUIStaticText *	m_label

int	m_label_height
	Height of ONE label text line (if label is multiline only one line is measured here). More...

bool	m_animated_contents
	Whether this ribbon contains at least one animated item.

bool	m_scrolling_enabled
	Whether there are more items than can fit in a single screen; arrows will then appear on each side of the ribbon to scroll the contents.

int	m_previous_item_count
	Used to keep track of item count changes.

std::vector< ItemDescription >	m_items
	List of items in the ribbon.

int	m_arrows_w
	Width of the scrolling arrows on each side.

int	m_scroll_offset
	Current scroll offset within items.

int	m_child_width
	Width and height of children as declared in the GUI file.

int	m_child_height

int	m_row_amount
	Number of rows and columns. More...

int	m_col_amount

int	m_needed_cols
	The total number of columns given item count and row count (even counting not visible with current scrolling)

bool	m_multi_row
	Whether this ribbon can have multiple rows (i.e. More...

std::vector< int >	m_ids
	irrlicht relies on consecutive IDs to perform keyboard navigation between widgets. More...

bool	m_combo
	Whether this is a "combo" style ribbon grid widget.

IconButtonWidget *	m_left_widget

IconButtonWidget *	m_right_widget

int	m_selected_item [MAX_PLAYER_COUNT]
	Used for combo ribbons, to contain the ID of the currently selected item for each player.

int	m_item_count_hint

irr::gui::ScalableFont *	m_font
	Font used to write the labels, can be scaled down depending on the length of the text.

int	m_max_label_width
	Max width of a label, in pixels.

unsigned int	m_max_label_length
	Max length of a label, in characters.

DynamicRibbonScrollCallback	m_scroll_callback

Friends
class	RibbonWidget

Additional Inherited Members
Static Public Member Functions inherited from GUIEngine::Widget
static void	resetIDCounters ()
	When switching to a new screen, this function will be called to reset ID counters (so we start again from ID 0, and don't grow to big numbers)

static int	getNewID ()
	Provides a new unique ID on each call, for widgets that can be focused.

static int	getNewNoFocusID ()
	Provides a new unique ID on each call, for widgets that can not be focused.

static bool	isFocusableId (const int id)
	get whether the given ID represents an ID of a widget that can be focused More...

Protected Member Functions inherited from GUIEngine::Widget
virtual EventPropagation	upPressed (const int playerID)
	called when up key is pressed and focus is on widget. More...

virtual EventPropagation	downPressed (const int playerID)
	called when down key is pressed and focus is on widget. More...

virtual void	unfocused (const int playerID, Widget *new_focus)
	override in children if you need to know when the widget is unfocused. More...

Protected Attributes inherited from GUIEngine::Widget
unsigned int	m_magic_number

std::bitset< Input::IT_LAST+1 >	m_active_event_callback

int	m_absolute_x
	Used during loading, by the layout engine. More...

int	m_absolute_y

int	m_absolute_w

int	m_absolute_h

int	m_absolute_reverse_x

int	m_absolute_reverse_y

float	m_relative_x

float	m_relative_y

float	m_relative_w

float	m_relative_h

irr::core::stringw	m_text
	PROP_TEXT is a special case : since it can be translated it can't go in the map above, which uses narrow strings.

bool	m_title_font
	When true, this widget shall use a bigger and more colourful font.

bool	m_selected [MAX_PLAYER_COUNT]
	Can be used in children to indicate whether a widget is selected or not. More...

bool	m_check_inside_me
	Whether to descend in the children of this widget when searching a widget from its ID or name. More...

irr::gui::IGUIElement *	m_parent
	An irrlicht parent (most often used to put widgets in dialogs)

irr::gui::IGUIElement *	m_element
	IrrLicht widget created to represent this object.

int	m_id
	numerical ID used by irrLicht to identify this widget (not the same as the string identificator specified in the XML file)

bool	m_player_focus [MAX_PLAYER_COUNT]
	Usually, only one widget at a time can be focused. More...

bool	m_reserve_id
	Whether to reserve an ID in 'm_reserved_id' when widget is added.

WidgetType	m_type
	Type of this widget.

PtrVector< Widget >	m_children
	If this widget has any children, they go here. More...

int	m_badges
	A bitmask of which badges to show, if any; choices are *_BADGE, defined above.

bool	m_deactivated
	A simple flag that can be raised to deactivate this widget.

bool	m_is_visible
	A flag to indicate whether this widget should be visible or not. More...

bool	m_focusable
	Set to false if widget is something that should not receive focus.

bool	m_bottom_bar

bool	m_top_bar

int	m_badge_x_shift
	If a badge wouldn't look too pretty on the very side of the widget.

bool	m_has_tooltip

irr::core::stringw	m_tooltip_text

int	m_uncollapsed_height
	height of the widget before it was collapsed (only set if widget got collapsed)

bool	m_is_collapsed
	A flag to indicate whether this widget got collapsed. More...

Detailed Description

An extended version of RibbonWidget, with more capabilities.

A dynamic ribbon builds upon RibbonWidget, adding dynamic contents creation and sizing, scrolling, multiple-row layouts.

Note: items you add to a list are kept after the the ribbon was in is removed (i.e. you don't need to add items everytime the screen is shown, only upon loading)

Constructor & Destructor Documentation

◆ DynamicRibbonWidget()

DynamicRibbonWidget::DynamicRibbonWidget	(	const bool	combo,
		const bool	multi_row
	)

Parameters

combo	Whether this is a "combo" ribbon, i.e. whether there is always one selected item. If set to false, will behave more like a toolbar.
multi_row	Whether this ribbon can have more than one row

Member Function Documentation

◆ addAnimatedItem()

void DynamicRibbonWidget::addAnimatedItem	(	const irr::core::stringw &	user_name,
		const std::string &	code_name,
		const std::vector< std::string > &	image_files,
		const float	time_per_frame,
		const unsigned int	badge = `0`,
		IconButtonWidget::IconPathType	image_path_type = `IconButtonWidget::ICON_PATH_TYPE_RELATIVE`
	)

Dynamically add an animated item to the ribbon's list of items (will not be visible until you call 'updateItemDisplay' or 'add').

Animated means it has many images that will be shown in a slideshown fashion.

Parameters

user_name	The name that will shown to the user (may be translated)
code_name	The non-translated internal name used to uniquely identify this item.
image_files	A path to a texture that will the icon of this item (path relative to data dir, just like PROP_ICON)
time_per_frame	Time (in seconds) to spend at each image.
badge	Whether to add badges to this item (bitmask, see possible values in widget.hpp)
image_path_type	How to interpret the path to the image (absolute or relative)

◆ addItem()

void DynamicRibbonWidget::addItem	(	const irr::core::stringw &	user_name,
		const std::string &	code_name,
		const std::string &	image_file,
		const unsigned int	badge = `0`,
		IconButtonWidget::IconPathType	image_path_type = `IconButtonWidget::ICON_PATH_TYPE_RELATIVE`
	)

Dynamically add an item to the ribbon's list of items (will not be visible until you call 'updateItemDisplay' or 'add').

Parameters

user_name	The name that will shown to the user (may be translated)
code_name	The non-translated internal name used to uniquely identify this item.
image_file	A path to a texture that will the icon of this item (path relative to data dir, just like PROP_ICON)
badge	Whether to add badges to this item (bitmask, see possible values in widget.hpp)
image_path_type	How to interpret the path to the image (absolute or relative)

◆ clearItems()

void DynamicRibbonWidget::clearItems ( )

Clears all items added through 'addItem'.

You can then add new items with 'addItem' and call 'updateItemDisplay' to update the display.

◆ elementRemoved()

void DynamicRibbonWidget::elementRemoved ( )

virtual

Callback from parent class Widget.

Reimplemented from GUIEngine::Widget.

◆ mouseHovered()

EventPropagation DynamicRibbonWidget::mouseHovered	(	Widget *	child,
		const int	playerID
	)

privatevirtual

used when you set eventSupervisors - see m_event_handler explainations below called when one of a widget's children is hovered.

Returns: 'EVENT_LET' if main event handler should be notified of a change, 'EVENT_BLOCK' otherwise

Reimplemented from GUIEngine::Widget.

◆ propagateSelection()

void DynamicRibbonWidget::propagateSelection ( )

private

Even though the ribbon grid widget looks like a grid, it is really a vertical stack of independant ribbons.

DynamicRibbonWidget is made of several ribbons; each of them thus has its own selection independently of each other.

When moving selection horizontally, this method is used to notify other rows above and below of which column is selected, so that moving vertically to another row keeps the same selected column.

To keep a grid feeling (i.e. you remain in the same column when pressing up/down), this method is used to ensure that all children ribbons always select the same column

◆ registerHoverListener()

void DynamicRibbonWidget::registerHoverListener ( DynamicRibbonHoverListener * listener )

Register a listener to be notified of selection changes within the ribbon.

Note: The ribbon takes ownership of this listener and will delete it.; The listener will be deleted upon leaving the screen, so you will likely want to add a listener in the "init" callback of your screen.

◆ setMaxLabelLength()

void GUIEngine::DynamicRibbonWidget::setMaxLabelLength ( int length )

inline

Set max length of displayed text.

◆ setSelection() [1/2]

bool DynamicRibbonWidget::setSelection	(	int	item_id,
		const int	playerID,
		const bool	focusIt,
		bool	evenIfDeactivated = `false`
	)

Select an item from its numerical ID.

Only for [1-row] combo ribbons.

Parameters

item_id In range [0 .. number of items added through 'addItem' - 1]

Returns: Whether setting the selection was successful (whether the item exists)

◆ setSelection() [2/2]

bool DynamicRibbonWidget::setSelection	(	const std::string &	item_codename,
		const int	playerID,
		const bool	focusIt,
		bool	evenIfDeactivated = `false`
	)

Select an item from its codename.

Returns: Whether setting the selection was successful (whether the item exists)

◆ setText()

void DynamicRibbonWidget::setText ( const irr::core::stringw & s )

virtual

Sets the text of a widget from a wchar_t.

Handy for many constant strings used in stk.

Note: Not all widgets use strings, so some widgets may ignore this text property; Changing the text property will only take effect the next time this widget is add()ed

Reimplemented from GUIEngine::Widget.

◆ sortItems()

template<typename Compare >

void GUIEngine::DynamicRibbonWidget::sortItems ( Compare comp )

inline

Sort the list of items with a given comparator.

◆ transmitEvent()

EventPropagation DynamicRibbonWidget::transmitEvent	(	Widget *	w,
		const std::string &	originator,
		const int	playerID
	)

privatevirtual

All widgets, including their parents (m_event_handler) will be notified on event through this call.

Must return whether main (GUI engine user) event callback should be notified or not. Note that in the case of a hierarchy of widgets (with m_event_handler), only the topmost widget of the chain decides whether the main handler is notified; return value is not read for others.

Reimplemented from GUIEngine::Widget.

Member Data Documentation

◆ m_ids

std::vector<int> GUIEngine::DynamicRibbonWidget::m_ids

private

irrlicht relies on consecutive IDs to perform keyboard navigation between widgets.

However, since this widget is dynamic, irrlicht widgets are not created as early as all others, so by the time we're ready to create the full contents of this widget, the ID generator is already incremented, thus messing up keyboard navigation. To work around this, at the same time all other widgets are created, I gather a number of IDs (the number of rows) and store them here. Then, when we're finally ready to create the contents dynamically, we can re-use these IDs and get correct navigation order.

◆ m_label_height

int GUIEngine::DynamicRibbonWidget::m_label_height

private

Height of ONE label text line (if label is multiline only one line is measured here).

If there is no label, will be 0.

◆ m_multi_row

bool GUIEngine::DynamicRibbonWidget::m_multi_row

private

Whether this ribbon can have multiple rows (i.e.

ribbon grid) or is a single line

◆ m_row_amount

int GUIEngine::DynamicRibbonWidget::m_row_amount

private

Number of rows and columns.

Number of columns can dynamically change, number of row is determined at creation

◆ m_rows

PtrVector<RibbonWidget, REF> GUIEngine::DynamicRibbonWidget::m_rows

Reference pointers only, the actual instances are owned by m_children.

Used to create multiple-row ribbons (what appears to be a grid of icons is actually a vector of stacked basic ribbons)

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

guiengine/widgets/dynamic_ribbon_widget.hpp
guiengine/widgets/dynamic_ribbon_widget.cpp

Public Member Functions

Public Attributes

Private Member Functions

Private Attributes

Friends

Additional Inherited Members

Detailed Description

Constructor & Destructor Documentation

◆ DynamicRibbonWidget()

Member Function Documentation

◆ addAnimatedItem()

◆ addItem()

◆ clearItems()

◆ elementRemoved()

◆ mouseHovered()

◆ propagateSelection()

◆ registerHoverListener()

◆ setMaxLabelLength()

◆ setSelection() [1/2]

◆ setSelection() [2/2]

◆ setText()

◆ sortItems()

◆ transmitEvent()

Member Data Documentation

◆ m_ids

◆ m_label_height

◆ m_multi_row

◆ m_row_amount

◆ m_rows