A vertical list widget with text entries. More...

#include <list_widget.hpp>

Inheritance diagram for GUIEngine::ListWidget:

Classes
struct	Column

Public Types
typedef irr::gui::CGUISTKListBox::ListItem	ListItem

typedef ListItem::ListCell	ListCell

Public Member Functions
virtual void	add ()
	implement add method from base class GUIEngine::Widget

virtual void	unfocused (const int playerID, Widget *new_focus)
	implement callback from base class GUIEngine::Widget

virtual void	elementRemoved ()
	implement callback from base class GUIEngine::Widget

void	setIcons (irr::gui::STKModifiedSpriteBank *icons, int size=-1)
	set the icon bank to use for list entries.

void	addItem (const std::string &internal_name, const irr::core::stringw &name, const int icon=-1, bool center=false)
	add an item to the list

void	addItem (const std::string &internal_name, const std::vector< ListCell > &contents)

void	createHeader ()
	create a header based on m_header

void	clear ()
	erases all items in the list, don't clear header

void	clearColumns ()
	clear the header

int	getItemCount () const

int	getSelectionID () const

std::string	getSelectionInternalName ()

irr::core::stringw	getSelectionLabel (const int cell=0) const

void	selectItemWithLabel (const irr::core::stringw &name)

int	getItemID (const std::string &internalName) const
	Finds the ID of the item that has a given internal name.

void	setSelectionID (const int index)
	change the selected item

void	renameCell (const int row_num, const int col_num, const irr::core::stringw &newName, const int icon=-1)
	rename an item and/or change its icon based on its ID

void	renameItem (const int row_num, const irr::core::stringw &newName, const int icon=-1)
	renames first cell only

void	renameItem (const std::string &internal_name, const irr::core::stringw &newName, const int icon=-1)

void	renameCell (const std::string internalName, const int col_num, const irr::core::stringw &newName, const int icon=-1)
	rename an item and/or change its icon based on its internal name

void	markItemRed (const int id, bool red=true)
	Make an item red to mark an error, for instance.

void	markItemBlue (const int id, bool blue=true)

void	emphasisItem (const int id, bool enable=true)

void	markItemRed (const std::string &internalName, bool red=true)
	Make an item red to mark an error, for instance.

void	markItemBlue (const std::string &internalName, bool blue=true)

void	emphasisItem (const std::string &internalName, bool enable=true)

virtual EventPropagation	transmitEvent (Widget *w, const std::string &originator, const int playerID)
	Override callback from Widget.

virtual EventPropagation	upPressed (const int playerID)
	implementing method from base class Widget

virtual EventPropagation	downPressed (const int playerID)
	implementing method from base class Widget

virtual EventPropagation	leftPressed (const int playerID)
	implementing method from base class Widget

virtual EventPropagation	rightPressed (const int playerID)
	implementing method from base class Widget

EventPropagation	moveToNextItem (const bool down)
	implement common core parts of upPressed and downPressed

void	setColumnListener (IListWidgetHeaderListener *listener)

void	addColumn (irr::core::stringw col, int proportion=1)
	Columns are persistent across multiple "clear" add/remove cycles.

void	addColumn (irr::video::ITexture *tex, int proportion=1)

void	setSortable (bool sortable)

void	focusHeader (const NavigationDirection nav)

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

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.

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

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

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

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

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.

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.

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.

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

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

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

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

WidgetType	getType () const

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

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.

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

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

const PtrVector< Widget > &	getChildren () const

PtrVector< Widget > &	getChildren ()

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

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

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.

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

void	resetAllBadges ()
	sets this widget to have no badge

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

bool	hasTooltip () const

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

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

Public Attributes
SkinWidgetContainer	m_selection_skin_info

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.

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

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

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

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.

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.

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

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

Private Attributes
bool	m_use_icons
	whether this list has icons

irr::gui::STKModifiedSpriteBank *	m_icons
	if m_use_icons is true, this will contain the icon bank

PtrVector< Widget >	m_header_elements

Widget *	m_selected_column

bool	m_sort_desc
	whether this list is sorted in descending order

bool	m_sort_default
	true when deault sorting is enabled

int	m_sort_col
	index of column

bool	m_choosing_header

std::vector< Column >	m_header
	Leave empty for no header.

IListWidgetHeaderListener *	m_listener

bool	m_sortable

bool	m_header_created

Friends
class	Skin

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

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

virtual EventPropagation	leftPressed (const int playerID)
	called when left key is pressed and focus is on widget.

virtual EventPropagation	upPressed (const int playerID)
	called when up key is pressed and focus is on widget.

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

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.

virtual EventPropagation	focused (const int playerID)
	override in children if you need to know when the widget is focused.

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

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.

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.

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

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.

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.

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.

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.

Detailed Description

A vertical list widget with text entries.

Note: items you add to a list are not kept after the the list is in was removed (i.e. you need to add items everytime the screen is shown)

Member Function Documentation

◆ add()

void ListWidget::add ( )

virtual

implement add method from base class GUIEngine::Widget

Reimplemented from GUIEngine::Widget.

◆ addColumn()

void GUIEngine::ListWidget::addColumn	(	irr::core::stringw	col,
		int	proportion = `1`
	)

inline

Columns are persistent across multiple "clear" add/remove cycles.

clearColumns clear them immediately.

Parameters

proportion A column with proportion 2 will be twice as large as a column with proportion 1

◆ addItem()

void ListWidget::addItem	(	const std::string &	internal_name,
		const irr::core::stringw &	name,
		const int	icon = `-1`,
		bool	center = `false`
	)

add an item to the list

Parameters

name	user-visible, potentially translated, name of the item
icon	ID of the icon within the icon bank. Only used if an icon bank was passed.

Precondition: may only be called after the widget has been added to the screen with add()

◆ clear()

void ListWidget::clear ( )

erases all items in the list, don't clear header

Precondition: may only be called after the widget has been added to the screen with add()

◆ clearColumns()

void ListWidget::clearColumns ( )

clear the header

Precondition: may only be called after the widget has been added to the screen with add()

◆ createHeader()

void ListWidget::createHeader ( )

create a header based on m_header

Precondition: may only be called after the widget has been added to the screen with add()

◆ downPressed()

EventPropagation ListWidget::downPressed ( const int playerID )

virtual

implementing method from base class Widget

Reimplemented from GUIEngine::Widget.

◆ elementRemoved()

void ListWidget::elementRemoved ( )

virtual

implement callback from base class GUIEngine::Widget

Reimplemented from GUIEngine::Widget.

◆ getItemCount()

int ListWidget::getItemCount ( ) const

Returns: the number of items in the list

Precondition: may only be called after the widget has been added to the screen with add()

◆ getSelectionID()

int ListWidget::getSelectionID ( ) const

Returns: the index of the selected element within the list, or -1 if none

Precondition: may only be called after the widget has been added to the screen with add()

◆ getSelectionInternalName()

std::string ListWidget::getSelectionInternalName ( )

Returns: the text of the selected item

Precondition: may only be called after the widget has been added to the screen with add()

◆ leftPressed()

EventPropagation ListWidget::leftPressed ( const int playerID )

virtual

implementing method from base class Widget

Reimplemented from GUIEngine::Widget.

◆ markItemRed() [1/2]

void ListWidget::markItemRed	(	const int	id,
		bool	red = `true`
	)

Make an item red to mark an error, for instance.

Precondition: may only be called after the widget has been added to the screen with add()

◆ markItemRed() [2/2]

void GUIEngine::ListWidget::markItemRed	(	const std::string &	internalName,
		bool	red = `true`
	)

inline

Make an item red to mark an error, for instance.

Precondition: may only be called after the widget has been added to the screen with add()

◆ renameCell() [1/2]

void ListWidget::renameCell	(	const int	row_num,
		const int	col_num,
		const irr::core::stringw &	newName,
		const int	icon = `-1`
	)

rename an item and/or change its icon based on its ID

Precondition: may only be called after the widget has been added to the screen with add()

◆ renameCell() [2/2]

void GUIEngine::ListWidget::renameCell	(	const std::string	internalName,
		const int	col_num,
		const irr::core::stringw &	newName,
		const int	icon = `-1`
	)

inline

rename an item and/or change its icon based on its internal name

Precondition: may only be called after the widget has been added to the screen with add()

◆ rightPressed()

EventPropagation ListWidget::rightPressed ( const int playerID )

virtual

implementing method from base class Widget

Reimplemented from GUIEngine::Widget.

◆ setActive()

void ListWidget::setActive ( bool active = true )

virtual

Sets an widget to be either activated or deactivated (i.e.

greyed out)

Parameters

active Active (true) or deactive (false). Defaults to true.

Reimplemented from GUIEngine::Widget.

◆ setIcons()

void ListWidget::setIcons	(	irr::gui::STKModifiedSpriteBank *	icons,
		int	size = `-1`
	)

set the icon bank to use for list entries.

The height of list entries will be ajusted to the size of the highest icon. Icons must therefore be at least as high as text.

Note: the list widget does NOT take ownership of the bank, dso you must delete it when you're done with it (but do not delete it when the list widget is still active)

Precondition: may only be called after the widget has been added to the screen with add()

◆ setSelectionID()

void ListWidget::setSelectionID ( const int index )

change the selected item

Parameters

index the index of the element to select within the list, or -1 to select nothing

Precondition: may only be called after the widget has been added to the screen with add()

◆ transmitEvent()

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

virtual

Override callback from Widget.

Allows sort icon to change depending on sort order

Reimplemented from GUIEngine::Widget.

◆ unfocused()

void ListWidget::unfocused	(	const int	playerID,
		Widget *	new_focus
	)

virtual

implement callback from base class GUIEngine::Widget

Reimplemented from GUIEngine::Widget.

◆ upPressed()

EventPropagation ListWidget::upPressed ( const int playerID )

virtual

implementing method from base class Widget

Reimplemented from GUIEngine::Widget.

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

guiengine/widgets/list_widget.hpp
guiengine/widgets/list_widget.cpp

Classes

Public Types

Public Member Functions

Public Attributes

Private Member Functions

Private Attributes

Friends

Additional Inherited Members

Detailed Description

Member Function Documentation

◆ add()

◆ addColumn()

◆ addItem()

◆ clear()

◆ clearColumns()

◆ createHeader()

◆ downPressed()

◆ elementRemoved()

◆ getItemCount()

◆ getSelectionID()

◆ getSelectionInternalName()

◆ leftPressed()

◆ markItemRed() [1/2]

◆ markItemRed() [2/2]

◆ renameCell() [1/2]

◆ renameCell() [2/2]

◆ rightPressed()

◆ setActive()

◆ setIcons()

◆ setSelectionID()

◆ transmitEvent()

◆ unfocused()

◆ upPressed()