tgui::ListBox Class Reference

List box widget. More...

#include <TGUI/Widgets/ListBox.hpp>

Inheritance diagram for tgui::ListBox:

Public Types
typedef std::shared_ptr< ListBox >	Ptr
	Shared widget pointer.
typedef std::shared_ptr< const ListBox >	ConstPtr
	Shared constant widget pointer.
Public Types inherited from tgui::Widget
typedef std::shared_ptr< Widget >	Ptr
	Shared widget pointer.
typedef std::shared_ptr< const Widget >	ConstPtr
	Shared constant widget pointer.

Public Member Functions
	ListBox (const ListBox &copy)
	Copy constructor. More...
ListBox &	operator= (const ListBox &right)
	Overload of assignment operator. More...
std::shared_ptr< ListBoxRenderer >	getRenderer () const
	Returns the renderer, which gives access to functions that determine how the widget is displayed. More...
virtual void	setPosition (const Layout2d &position) override
	Set the position of the widget. More...
void	setSize (const Layout2d &size) override
	Changes the size of the list box. More...
virtual sf::Vector2f	getFullSize () const override
	Returns the full size of the list box. More...
virtual void	setFont (const Font &font) override
	Changes the font of the text in the widget. More...
bool	addItem (const sf::String &itemName, const sf::String &id="")
	Adds an item to the list. More...
bool	setSelectedItem (const sf::String &itemName)
	Selects an item in the list box. More...
bool	setSelectedItemById (const sf::String &id)
	Selects an item in the list box. More...
bool	setSelectedItemByIndex (std::size_t index)
	Selects an item in the list box. More...
void	deselectItem ()
	Deselects the selected item.
bool	removeItem (const sf::String &itemName)
	Removes the item from the list with the given name. More...
bool	removeItemById (const sf::String &id)
	Removes the item that were added with the given id. More...
bool	removeItemByIndex (std::size_t index)
	Removes the item from the list box. More...
void	removeAllItems ()
	Removes all items from the list.
sf::String	getItemById (const sf::String &id) const
	Returns the item name of the item with the given id. More...
sf::String	getSelectedItem () const
	Returns the currently selected item. More...
sf::String	getSelectedItemId () const
	Get the id of the selected item. More...
int	getSelectedItemIndex () const
	Get the index of the selected item. More...
bool	changeItem (const sf::String &originalValue, const sf::String &newValue)
	Changes an item with name originalValue to newValue. More...
bool	changeItemById (const sf::String &id, const sf::String &newValue)
	Changes the name of an item with the given id to newValue. More...
bool	changeItemByIndex (std::size_t index, const sf::String &newValue)
	Changes the name of an item at the given index to newValue. More...
std::size_t	getItemCount ()
	Returns the amount of items in the list box. More...
std::vector< sf::String >	getItems ()
	Return a copy of the items in the list box. More...
const std::vector< sf::String > &	getItemIds ()
	Return a copy of the item ids in the list box. More...
void	setScrollbar (Scrollbar::Ptr scrollbar)
	Changes the scrollbar of the list box. More...
Scrollbar::Ptr	getScrollbar () const
	Access the scrollbar of the list box. More...
void	setItemHeight (unsigned int itemHeight)
	Changes the height of the items in the list box. More...
unsigned int	getItemHeight () const
	Returns the height of the items in the list box. More...
void	setTextSize (unsigned int textSize)
	Changes the text size of the items. More...
unsigned int	getTextSize () const
	Returns the text size of the items. More...
void	setMaximumItems (std::size_t maximumItems=0)
	Changes the maximum items that the list box can contain. More...
std::size_t	getMaximumItems () const
	Returns the maximum items that the list box can contain. More...
void	setAutoScroll (bool autoScroll)
	Changes whether the list box scrolls to the bottom when a new item is added. More...
bool	getAutoScroll () const
	Returns the maximum items that the list box can contain. More...
virtual void	setOpacity (float opacity) override
	Changes the opacity of the widget. More...
virtual sf::Vector2f	getWidgetOffset () const override
	Returns the distance between the position where the widget is drawn and where the widget is placed. More...
virtual void	setPosition (const Layout2d &position)
	set the position of the widget More...
void	setPosition (const Layout &x, const Layout &y)
	set the position of the widget More...
virtual void	setSize (const Layout2d &size)
	Changes the size of the widget. More...
void	setSize (const Layout &width, const Layout &height)
	Changes the size of the widget. More...
Public Member Functions inherited from tgui::Widget
	Widget ()
	Default constructor.
	Widget (const Widget &copy)
	Copy constructor. More...
	~Widget ()
	Destructor.
Widget &	operator= (const Widget &right)
	Overload of assignment operator. More...
std::shared_ptr< WidgetRenderer >	getRenderer () const
	Returns the renderer, which gives access to functions that determine how the widget is displayed. More...
virtual sf::Vector2f	getAbsolutePosition () const
	Get the absolute position of the widget instead of the relative position to its parent. More...
virtual void	show ()
	Shows the widget. More...
virtual void	showWithEffect (ShowAnimationType type, sf::Time duration)
	Shows the widget by introducing it with an animation. More...
virtual void	hide ()
	Hides the widget. More...
virtual void	hideWithEffect (ShowAnimationType type, sf::Time duration)
	Hides the widget by making it leave with an animation. More...
bool	isVisible () const
	Returns true when the widget is visible. More...
virtual void	enable ()
	Enables the widget. More...
virtual void	disable (bool blockMouseEvents=true)
	Disables the widget. More...
bool	isEnabled () const
	Returns true when the widget is enabled. More...
virtual void	focus ()
	Focus the widget. More...
virtual void	unfocus ()
	Unfocus the widget. More...
bool	isFocused () const
	Returns true when the widget is focused and false otherwise. More...
const std::string &	getWidgetType () const
	Returns the type of the widget. More...
Container *	getParent () const
	Returns a pointer to the parent widget. More...
float	getOpacity () const
	Returns the opacity of the widget. More...
virtual void	moveToFront ()
	Places the widget before all other widgets.
virtual void	moveToBack ()
	Places the widget behind all other widgets.
void	setToolTip (Widget::Ptr toolTip)
	Sets the tool tip that should be displayed when hovering over the widget. More...
Widget::Ptr	getToolTip ()
	Returns the tool tip that is displayed when hovering over the widget. More...
std::shared_ptr< sf::Font >	getFont () const
	Returns the font associated with the widget (if any) More...
void	detachTheme ()
	Detach the theme from the widget. More...
std::shared_ptr< BaseTheme >	getTheme () const
	Returns the theme to which the widget is currently connected. More...
std::string	getPrimaryLoadingParameter () const
	Returns the primary parameter that was passed to the loader to load this widget. More...
std::string	getSecondaryLoadingParameter () const
	Returns the secondary parameter that was passed to the loader to load this widget. More...
void	setPosition (const Layout &x, const Layout &y)
	set the position of the widget More...
void	setSize (const Layout &width, const Layout &height)
	Changes the size of the widget. More...
Public Member Functions inherited from tgui::Transformable
virtual	~Transformable ()
	Virtual destructor.
void	setPosition (const Layout &x, const Layout &y)
	set the position of the widget More...
sf::Vector2f	getPosition () const
	get the position of the widget More...
void	move (const Layout2d &offset)
	Move the widget by a given offset. More...
void	move (const Layout &x, const Layout &y)
	Move the widget by a given offset. More...
void	setSize (const Layout &width, const Layout &height)
	Changes the size of the widget. More...
virtual sf::Vector2f	getSize () const
	Returns the size of the widget. More...
void	scale (const Layout2d &factors)
	Scale the widget. More...
void	scale (const Layout &x, const Layout &y)
	Scale the widget. More...
Public Member Functions inherited from tgui::SignalWidgetBase
	SignalWidgetBase ()=default
	Default constructor.
	SignalWidgetBase (const SignalWidgetBase &copy)
	Copy constructor. More...
SignalWidgetBase &	operator= (const SignalWidgetBase &right)
	Overload of assignment operator. More...
template<typename Func , typename... Args>
unsigned int	connect (const std::string &signalNames, Func func, Args... args)
	Connects a signal handler function to one or more signals. More...
template<typename Func , typename... Args>
unsigned int	connectEx (const std::string &signalName, Func func, Args... args)
	Connects a signal handler function to one or more signals. More...
void	disconnect (unsigned int id)
	Disconnects a connection. More...
void	disconnectAll (const std::string &signalName)
	Disconnect all connections from a certain signal. More...
void	disconnectAll ()
	Disconnect all connections from a all signals.

Static Public Member Functions
static ListBox::Ptr	create ()
	Creates a new list box widget. More...
static ListBox::Ptr	copy (ListBox::ConstPtr listBox)
	Makes a copy of another list box. More...

Protected Member Functions
virtual void	reload (const std::string &primary="", const std::string &secondary="", bool force=false) override
	Reload the widget. More...
virtual Widget::Ptr	clone () const override
	Makes a copy of the widget if you don't know its exact type. More...
Protected Member Functions inherited from tgui::Widget
void	attachTheme (std::shared_ptr< BaseTheme > theme)
	Attach a theme to the widget. More...

Detailed Description

List box widget.

Signals:

• ItemSelected (a new item was selected)
  • Optional parameter sf::String: Name of the item (the text that is visible)
  • Optional parameters sf::String and sf::String: Name and id of the item
  • Uses Callback member 'text' and 'itemId'
• MousePressed (left mouse went down on top of an item
  • Optional parameter sf::String: Name of the item (the text that is visible)
  • Optional parameters sf::String and sf::String: Name and id of the item
  • Uses Callback member 'text' and 'itemId'
• MouseReleased (left mouse went up on top of an item after it went down on of the items of the list box)
  • Optional parameter sf::String: Name of the item (the text that is visible)
  • Optional parameters sf::String and sf::String: Name and id of the item
  • Uses Callback member 'text' and 'itemId'
• DoubleClicked (double clicked on an item with the left mouse button)
  • Optional parameter sf::String: Name of the item (the text that is visible)
  • Optional parameters sf::String and sf::String: Name and id of the item
  • Uses Callback member 'text' and 'itemId'
• Inherited signals from Widget

Constructor & Destructor Documentation

ListBox()

tgui::ListBox::ListBox

(

const ListBox &

copy

)

Copy constructor.

Parameters

copy	Instance to copy

Member Function Documentation

addItem()

bool tgui::ListBox::addItem	(	const sf::String &	itemName,
		const sf::String &	id = ""
	)

Adds an item to the list.

Parameters

itemName	The name of the item you want to add (this is the text that will be displayed inside the list box)
id	Optional unique id given to this item for the purpose to later identifying this item.

Returns

• true when the item was successfully added
• false when the list box is full (you have set a maximum item limit and you are trying to add more items)
• false when there is no scrollbar and you try to have more items than fit inside the list box

See also

setMaximumItems

changeItem()

bool tgui::ListBox::changeItem	(	const sf::String &	originalValue,
		const sf::String &	newValue
	)

Changes an item with name originalValue to newValue.

Parameters

originalValue	The name of the item which you want to change
newValue	The new name for that item

In case the names are not unique, only the first item with that name will be changed.

Returns

• true when the item was changed
• false when none of the items had the given name

changeItemById()

bool tgui::ListBox::changeItemById	(	const sf::String &	id,
		const sf::String &	newValue
	)

Changes the name of an item with the given id to newValue.

Parameters

id	The unique id of the item which you want to change
newValue	The new name for that item

In case the id is not unique, only the first item with that id will be changed.

Returns

• true when the item was changed
• false when none of the items had the given id

changeItemByIndex()

bool tgui::ListBox::changeItemByIndex	(	std::size_t	index,
		const sf::String &	newValue
	)

Changes the name of an item at the given index to newValue.

Parameters

index	The index of the item which you want to change
newValue	The new name for that item

Returns

• true when the item was changed
• false when the index was too high

clone()

virtual Widget::Ptr tgui::ListBox::clone ( ) const

inlineoverrideprotectedvirtual

Makes a copy of the widget if you don't know its exact type.

This function should only be used when you don't know the type of the widget. If you know what kind of widget you are copying, you should use the copy function.

Returns

Copy of the widget

Implements tgui::Widget.

copy()

static ListBox::Ptr tgui::ListBox::copy ( ListBox::ConstPtr  listBox )

static

Makes a copy of another list box.

Parameters

listBox

The other list box

Returns

The new list box

create()

static ListBox::Ptr tgui::ListBox::create ( )

static

Creates a new list box widget.

Returns

The new list box

getAutoScroll()

bool tgui::ListBox::getAutoScroll ( ) const

inline

Returns the maximum items that the list box can contain.

Returns

The maximum items inside the list box. If the function returns 0 then there is no limit.

getFullSize()

virtual sf::Vector2f tgui::ListBox::getFullSize ( ) const

overridevirtual

Returns the full size of the list box.

The size returned by this function includes the borders.

Returns

Full size of the list box

Reimplemented from tgui::Transformable.

getItemById()

sf::String tgui::ListBox::getItemById

(

const sf::String &

id

)

const

Returns the item name of the item with the given id.

Parameters

id	The id of the item that was given to it when it was added

In case the id is not unique, the first item with that id will be returned.

Returns

The requested item, or an empty string when no item matches the id

getItemCount()

std::size_t tgui::ListBox::getItemCount ( )

inline

Returns the amount of items in the list box.

Returns

Number of items inside the list box

getItemHeight()

unsigned int tgui::ListBox::getItemHeight

(

)

const

Returns the height of the items in the list box.

Returns

The item height

getItemIds()

const std::vector< sf::String > & tgui::ListBox::getItemIds

(

)

Return a copy of the item ids in the list box.

Returns

item ids

Items that were not given an id simply have an empty string as id.

getItems()

std::vector< sf::String > tgui::ListBox::getItems

(

)

Return a copy of the items in the list box.

Returns

items

getMaximumItems()

std::size_t tgui::ListBox::getMaximumItems ( ) const

inline

Returns the maximum items that the list box can contain.

Returns

The maximum items inside the list box. If the function returns 0 then there is no limit.

getRenderer()

std::shared_ptr< ListBoxRenderer > tgui::ListBox::getRenderer ( ) const

inline

Returns the renderer, which gives access to functions that determine how the widget is displayed.

Returns

Reference to the renderer

getScrollbar()

Scrollbar::Ptr tgui::ListBox::getScrollbar

(

)

const

Access the scrollbar of the list box.

Returns

scrollbar in the list box

You should not change the scrollbar yourself

getSelectedItem()

sf::String tgui::ListBox::getSelectedItem

(

)

const

Returns the currently selected item.

Returns

The selected item. When no item was selected then this function will return an empty string.

getSelectedItemId()

sf::String tgui::ListBox::getSelectedItemId

(

)

const

Get the id of the selected item.

Returns

The id of the selected item, which was the optional id passed to the addItem function. When no item was selected then this function returns an empty string.

getSelectedItemIndex()

int tgui::ListBox::getSelectedItemIndex

(

)

const

Get the index of the selected item.

Returns

The index of the selected item, or -1 when no item was selected

getTextSize()

unsigned int tgui::ListBox::getTextSize

(

)

const

Returns the text size of the items.

Returns

The text size

getWidgetOffset()

virtual sf::Vector2f tgui::ListBox::getWidgetOffset ( ) const

overridevirtual

Returns the distance between the position where the widget is drawn and where the widget is placed.

This is basically the width and height of the optional borders drawn around widgets.

Returns

Offset of the widget

Reimplemented from tgui::Widget.

operator=()

ListBox & tgui::ListBox::operator=

(

const ListBox &

right

)

Overload of assignment operator.

Parameters

right

Instance to assign

Returns

Reference to itself

reload()

virtual void tgui::ListBox::reload ( const std::string &  primary = "", const std::string &  secondary = "", bool  force = false  )

overrideprotectedvirtual

Reload the widget.

Parameters

primary	Primary parameter for the loader
secondary	Secondary parameter for the loader
force	Try to only change the looks of the widget and not alter the widget itself when false

Exceptions

Exception

when the connected theme could not create the widget

When primary is an empty string the built-in white theme will be used.

Reimplemented from tgui::Widget.

removeItem()

bool tgui::ListBox::removeItem

(

const sf::String &

itemName

)

Removes the item from the list with the given name.

Parameters

itemName

The item to remove

In case the names are not unique, only the first item with that name will be removed.

Returns

• true when the item was removed
• false when the name did not match any item

removeItemById()

bool tgui::ListBox::removeItemById

(

const sf::String &

id

)

Removes the item that were added with the given id.

Parameters

id	Id that was given to the addItem function.

In case the id is not unique, only the first item with that id will be removed.

Returns

• true when the item was removed
• false when there was no item with the given id

removeItemByIndex()

bool tgui::ListBox::removeItemByIndex

(

std::size_t

index

)

Removes the item from the list box.

Parameters

index

Index of the item in the list box

Returns

• true when the item was removed
• false when the index was too high

See also

removeItem

removeItemById

setAutoScroll()

void tgui::ListBox::setAutoScroll

(

bool

autoScroll

)

Changes whether the list box scrolls to the bottom when a new item is added.

Parameters

autoScroll

Should list box scroll to the bottom when new items are added?

Auto scrolling is enabled by default.

setFont()

virtual void tgui::ListBox::setFont ( const Font &  font )

overridevirtual

Changes the font of the text in the widget.

Parameters

font	The new font.

When you don't call this function then the font from the parent widget will be used.

Reimplemented from tgui::Widget.

setItemHeight()

void tgui::ListBox::setItemHeight

(

unsigned int

itemHeight

)

Changes the height of the items in the list box.

Parameters

itemHeight

The size of a single item in the list

Warning

When there is no scrollbar then the items will be removed when they no longer fit inside the list box.

setMaximumItems()

void tgui::ListBox::setMaximumItems

(

std::size_t

maximumItems = 0

)

Changes the maximum items that the list box can contain.

Parameters

maximumItems

The maximum items inside the list box. When the maximum is set to 0 then the limit will be disabled.

If no scrollbar was loaded then there is always a limitation because there will be a limited space for the items.

setOpacity()

virtual void tgui::ListBox::setOpacity ( float  opacity )

overridevirtual

Changes the opacity of the widget.

Parameters

opacity

The opacity of the widget. 0 means completely transparent, while 1 (default) means fully opaque.

Reimplemented from tgui::Widget.

setPosition() [1/3]

void tgui::Transformable::setPosition ( const Layout &  x, const Layout &  y  )

inline

set the position of the widget

This function completely overwrites the previous position. See the move function to apply an offset based on the previous position instead. The default position of a transformable widget is (0, 0).

Parameters

x	New x coordinate
y	New y coordinate

See also

move, getPosition

Usage examples:

// Place the widget on an exact position
widget->setPosition(40, 30);
 
// Place the widget 50 pixels below another widget
widget->setPosition(otherWidget->getPosition().x, otherWidget->getPosition().y + otherWidget->getSize().y + 50);
 
// Place the widget 50 pixels below another widget and automatically move it when the other widget moves
widget->setPosition(tgui::bindLeft(otherWidget), tgui::bindBottom(otherWidget) + 50);

setPosition() [2/3]

virtual void tgui::Transformable::setPosition ( const Layout2d &  position )

virtual

set the position of the widget

This function completely overwrites the previous position. See the move function to apply an offset based on the previous position instead. The default position of a transformable widget is (0, 0).

Parameters

position

New position

See also

move, getPosition

Usage examples:

// Place the widget on an exact position
widget->setPosition({40, 30});
 
// Place the widget 50 pixels below another widget
widget->setPosition(otherWidget->getPosition() + sf::Vector2f{0, otherWidget->getSize().y + 50});
 
// Place the widget 50 pixels below another widget and automatically move it when the other widget moves
widget->setPosition({tgui::bindLeft(otherWidget), tgui::bindBottom(otherWidget) + 50});

Reimplemented from tgui::Widget.

setPosition() [3/3]

virtual void tgui::ListBox::setPosition ( const Layout2d &  position )

overridevirtual

Set the position of the widget.

This function completely overwrites the previous position. See the move function to apply an offset based on the previous position instead. The default position of a transformable widget is (0, 0).

Parameters

position

New position

See also

move, getPosition

Reimplemented from tgui::Widget.

setScrollbar()

void tgui::ListBox::setScrollbar

(

Scrollbar::Ptr

scrollbar

)

Changes the scrollbar of the list box.

Parameters

scrollbar

The new scrollbar to use in the list box

Pass a nullptr to remove the scrollbar. Note that when removing the scrollbar while there are too many items to fit in the list box then the excess items will be removed.

The scrollbar should have no parent and you should not change it yourself. The function is meant to be used like this:

listBox->setScrollbar(theme->load("scrollbar"));

setSelectedItem()

bool tgui::ListBox::setSelectedItem

(

const sf::String &

itemName

)

Selects an item in the list box.

Parameters

itemName

The item you want to select

In case the names are not unique, the first item with that name will be selected.

Returns

• true on success
• false when none of the items matches the name

See also

setSelectedItemById

setSelectedItemById()

bool tgui::ListBox::setSelectedItemById

(

const sf::String &

id

)

Selects an item in the list box.

Parameters

id	Unique id passed to addItem

In case the id would not be unique, the first item with that id will be selected.

Returns

• true on success
• false when none of the items has the given id

See also

setSelectedItem

setSelectedItemByIndex()

bool tgui::ListBox::setSelectedItemByIndex

(

std::size_t

index

)

Selects an item in the list box.

Parameters

index

Index of the item in the list box

Returns

• true on success
• false when the index was too high

See also

setSelectedItem

setSelectedItemById

setSize() [1/3]

void tgui::Transformable::setSize ( const Layout &  width, const Layout &  height  )

inline

Changes the size of the widget.

Parameters

width	Width of the widget
height	Height of the widget

Usage examples:

// Give the widget an exact size
widget->setSize(40, 30);
 
// Make the widget 50 pixels higher than some other widget
widget->setSize(otherWidget->getSize().x, otherWidget->getSize().y + 50);
 
// Make the widget 50 pixels higher than some other widget and automatically resize it when the other widget resizes
widget->setSize(tgui::bindWidth(otherWidget), tgui::bindHeight(otherWidget) + 50);

setSize() [2/3]

virtual void tgui::Transformable::setSize ( const Layout2d &  size )

virtual

Changes the size of the widget.

Parameters

size	Size of the widget

Usage examples:

// Give the widget an exact size
widget->setSize({40, 30});
 
// Make the widget 50 pixels higher than some other widget
widget->setSize(otherWidget->getSize() + sf::Vector2f{0, 50});
 
// Make the widget 50 pixels higher than some other widget and automatically resize it when the other widget resizes
widget->setSize(tgui::bindSize(otherWidget) + sf::Vector2f{0, 50});

Reimplemented from tgui::Widget.

setSize() [3/3]

void tgui::ListBox::setSize ( const Layout2d &  size )

overridevirtual

Changes the size of the list box.

Parameters

size	The new size of the list box

Reimplemented from tgui::Widget.

setTextSize()

void tgui::ListBox::setTextSize

(

unsigned int

textSize

)

Changes the text size of the items.

Parameters

textSize

The size size of the text

This will not change the height that each item has. By default (or when passing 0 to this function) the text will be auto-sized to nicely fit inside this item height.

See also

setItemHeight

---

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

• include/TGUI/Widgets/ListBox.hpp