--- --- TGUI: include/TGUI/Widgets/ListBox.hpp Source File
TGUI  1.x-dev
Loading...
Searching...
No Matches
ListBox.hpp
1
2//
3// TGUI - Texus' Graphical User Interface
4// Copyright (C) 2012-2024 Bruno Van de Velde (vdv_b@tgui.eu)
5//
6// This software is provided 'as-is', without any express or implied warranty.
7// In no event will the authors be held liable for any damages arising from the use of this software.
8//
9// Permission is granted to anyone to use this software for any purpose,
10// including commercial applications, and to alter it and redistribute it freely,
11// subject to the following restrictions:
12//
13// 1. The origin of this software must not be misrepresented;
14// you must not claim that you wrote the original software.
15// If you use this software in a product, an acknowledgment
16// in the product documentation would be appreciated but is not required.
17//
18// 2. Altered source versions must be plainly marked as such,
19// and must not be misrepresented as being the original software.
20//
21// 3. This notice may not be removed or altered from any source distribution.
22//
24
25#ifndef TGUI_LIST_BOX_HPP
26#define TGUI_LIST_BOX_HPP
27
28#include <TGUI/CopiedSharedPtr.hpp>
29#include <TGUI/Widgets/Scrollbar.hpp>
30#include <TGUI/Renderers/ListBoxRenderer.hpp>
31#include <TGUI/Text.hpp>
32
34
35TGUI_MODULE_EXPORT namespace tgui
36{
40 class TGUI_API ListBox : public Widget
41 {
42 public:
43
44 using Ptr = std::shared_ptr<ListBox>;
45 using ConstPtr = std::shared_ptr<const ListBox>;
46
47 static constexpr const char StaticWidgetType[] = "ListBox";
48
52 using TextAlignment TGUI_DEPRECATED("Use tgui::HorizontalAlignment instead") = HorizontalAlignment;
53
61 ListBox(const char* typeName = StaticWidgetType, bool initRenderer = true);
62
68 TGUI_NODISCARD static ListBox::Ptr create();
69
77 TGUI_NODISCARD static ListBox::Ptr copy(const ListBox::ConstPtr& listBox);
78
83 TGUI_NODISCARD ListBoxRenderer* getSharedRenderer() override;
84 TGUI_NODISCARD const ListBoxRenderer* getSharedRenderer() const override;
85
91 TGUI_NODISCARD ListBoxRenderer* getRenderer() override;
92
98 void setSize(const Layout2d& size) override;
99 using Widget::setSize;
100
111 std::size_t addItem(const String& itemName, const String& id = "");
112
126 bool setSelectedItem(const String& itemName);
127
142
155 bool setSelectedItemByIndex(std::size_t index);
156
161
173 bool removeItem(const String& itemName);
174
186 bool removeItemById(const String& id);
187
200 bool removeItemByIndex(std::size_t index);
201
206
216 TGUI_NODISCARD String getItemById(const String& id) const;
217
225 TGUI_NODISCARD String getItemByIndex(std::size_t index) const;
226
236 TGUI_NODISCARD int getIndexById(const String& id) const;
237
245 TGUI_NODISCARD String getIdByIndex(std::size_t index) const;
246
253 TGUI_NODISCARD String getSelectedItem() const;
254
261 TGUI_NODISCARD String getSelectedItemId() const;
262
268 TGUI_NODISCARD int getSelectedItemIndex() const;
269
282 bool changeItem(const String& originalValue, const String& newValue);
283
296 bool changeItemById(const String& id, const String& newValue);
297
308 bool changeItemByIndex(std::size_t index, const String& newValue);
309
315 TGUI_NODISCARD std::size_t getItemCount() const;
316
322 TGUI_NODISCARD std::vector<String> getItems() const;
323
331 TGUI_NODISCARD std::vector<String> getItemIds() const;
332
345 void setItemData(std::size_t index, Any data);
346
353 template <typename DataType>
354 TGUI_NODISCARD DataType getItemData(std::size_t index) const
355 {
356 if (index < m_items.size())
357 return AnyCast<DataType>(m_items[index].data);
358 else
359 throw std::bad_cast();
360 }
361
369 void setItemHeight(unsigned int itemHeight);
370
376 TGUI_NODISCARD unsigned int getItemHeight() const;
377
386 void setMaximumItems(std::size_t maximumItems = 0);
387
394 TGUI_NODISCARD std::size_t getMaximumItems() const;
395
403 void setAutoScroll(bool autoScroll);
404
409 TGUI_NODISCARD bool getAutoScroll() const;
410
419
425 TGUI_NODISCARD HorizontalAlignment getTextAlignment() const;
426
434 TGUI_NODISCARD bool contains(const String& item) const;
435
443 TGUI_NODISCARD bool containsId(const String& id) const;
444
450 void setScrollbarValue(unsigned int value);
451
457 TGUI_NODISCARD unsigned int getScrollbarValue() const;
458
466 TGUI_NODISCARD unsigned int getScrollbarMaxValue() const;
467
473 TGUI_NODISCARD bool isMouseOnWidget(Vector2f pos) const override;
474
478 bool leftMousePressed(Vector2f pos) override;
479
483 void leftMouseReleased(Vector2f pos) override;
484
488 void mouseMoved(Vector2f pos) override;
489
493 bool scrolled(float delta, Vector2f pos, bool touch) override;
494
498 void mouseNoLongerOnWidget() override;
499
503 void leftMouseButtonNoLongerDown() override;
504
508 void keyPressed(const Event::KeyEvent& event) override;
509
519 bool canHandleKeyPress(const Event::KeyEvent& event) override;
520
527 void draw(BackendRenderTarget& target, RenderStates states) const override;
528
530 protected:
531
541 TGUI_NODISCARD Signal& getSignal(String signalName) override;
542
548 void rendererChanged(const String& property) override;
549
553 TGUI_NODISCARD std::unique_ptr<DataIO::Node> save(SavingRenderersMap& renderers) const override;
554
558 void load(const std::unique_ptr<DataIO::Node>& node, const LoadingRenderersMap& renderers) override;
559
563 void updateTextSize() override;
564
566 // Returns the size without the borders
568 TGUI_NODISCARD Vector2f getInnerSize() const;
569
571 // Updates the position of the items and the scrollbar
573 void updateItemPositions();
574
576 // Update the colors and text style of the selected and hovered items
578 void updateSelectedAndHoveringItemColorsAndStyle();
579
581 // Update the color and text style of all the items
583 void updateItemColorsAndStyle();
584
586 // Update on which item the mouse is standing
588 void updateHoveringItem(int item);
589
591 // Update which item is selected
593 void updateSelectedItem(int item);
594
596 // Checks whether the scrollbar value was changed and emit the onScroll event if it did
598 void triggerOnScroll();
599
601 // This function is called every frame with the time passed since the last frame.
603 bool updateTime(Duration elapsedTime) override;
604
606 // Makes a copy of the widget
608 TGUI_NODISCARD Widget::Ptr clone() const override;
609
611 public:
612
613 SignalItem onItemSelect = {"ItemSelected"};
614 SignalItem onMousePress = {"MousePressed"};
615 SignalItem onMouseRelease = {"MouseReleased"};
616 SignalItem onDoubleClick = {"DoubleClicked"};
617 SignalUInt onScroll = {"Scrolled"};
618
620 protected:
621
622 struct Item
623 {
624 Text text;
625 Any data;
626 String id;
627 };
628
629 std::vector<Item> m_items;
630
631 // What is the index of the selected item?
632 // This is also used by combo box, so it can't just be changed to a pointer!
633 int m_selectedItem = -1;
634
635 int m_hoveringItem = -1;
636
637 unsigned int m_itemHeight = 0;
638
639 // This will store the maximum number of items in the list box (zero by default, meaning that there is no limit)
640 std::size_t m_maxItems = 0;
641
642 // When there are too many items a scrollbar will be shown
644 unsigned int m_lastScrollbarValue = 0;
645
646 // Will be set to true after the first click, but gets reset to false when the second click does not occur soon after
647 bool m_possibleDoubleClick = false;
648
649 bool m_autoScroll = true;
650 HorizontalAlignment m_textAlignment = HorizontalAlignment::Left;
651
652 Sprite m_spriteBackground;
653
654 // Cached renderer properties
655 Borders m_bordersCached;
656 Borders m_paddingCached;
657 Color m_borderColorCached;
658 Color m_backgroundColorCached;
659 Color m_backgroundColorHoverCached;
660 Color m_selectedBackgroundColorCached;
661 Color m_selectedBackgroundColorHoverCached;
662 Color m_textColorCached;
663 Color m_textColorHoverCached;
664 Color m_selectedTextColorCached;
665 Color m_selectedTextColorHoverCached;
666 TextStyles m_textStyleCached;
667 TextStyles m_selectedTextStyleCached;
668
670 };
671
673}
674
676
677#endif // TGUI_LIST_BOX_HPP
Base class for render targets.
Definition BackendRenderTarget.hpp:46
Wrapper for colors.
Definition Color.hpp:73
Definition CopiedSharedPtr.hpp:42
Wrapper for durations.
Definition Duration.hpp:55
Class to store the position or size of a widget.
Definition Layout.hpp:313
List box widget.
Definition ListBox.hpp:41
TGUI_NODISCARD String getItemById(const String &id) const
Returns the item name of the item with the given id.
bool changeItem(const String &originalValue, const String &newValue)
Changes an item with name originalValue to newValue.
void setItemHeight(unsigned int itemHeight)
Changes the height of the items in the list box.
TGUI_NODISCARD unsigned int getScrollbarMaxValue() const
Returns the maximum thumb position of the scrollbar.
bool changeItemByIndex(std::size_t index, const String &newValue)
Changes the name of an item at the given index to newValue.
TGUI_NODISCARD Signal & getSignal(String signalName) override
Retrieves a signal based on its name.
bool changeItemById(const String &id, const String &newValue)
Changes the name of an item with the given id to newValue.
void setTextAlignment(HorizontalAlignment alignment)
Changes the horizontal text alignment.
TGUI_NODISCARD String getItemByIndex(std::size_t index) const
Returns the item name of the item at the given index.
void setItemData(std::size_t index, Any data)
Store some user data with the item.
TGUI_NODISCARD std::vector< String > getItems() const
Returns a copy of the items in the list box.
TGUI_NODISCARD bool contains(const String &item) const
Returns whether the list box contains the given item.
void updateTextSize() override
Called when the text size is changed (either by setTextSize or via the renderer)
void deselectItem()
Deselects the selected item.
TGUI_NODISCARD std::vector< String > getItemIds() const
Returns a copy of the item ids in the list box.
std::shared_ptr< const ListBox > ConstPtr
Shared constant widget pointer.
Definition ListBox.hpp:45
TGUI_NODISCARD bool getAutoScroll() const
Returns whether the list box scrolls to the bottom when a new item is added.
void setMaximumItems(std::size_t maximumItems=0)
Changes the maximum items that the list box can contain.
TGUI_NODISCARD ListBoxRenderer * getRenderer() override
Returns the renderer, which gives access to functions that determine how the widget is displayed.
TGUI_NODISCARD bool containsId(const String &id) const
Returns whether the list box contains an item with the given id.
void draw(BackendRenderTarget &target, RenderStates states) const override
Draw the widget to a render target.
bool leftMousePressed(Vector2f pos) override
Called by the parent when the left mouse button goes down on top of the widget.
bool canHandleKeyPress(const Event::KeyEvent &event) override
Called by the parent of the widget to check if keyPressed would process the event.
TGUI_NODISCARD String getSelectedItem() const
Returns the currently selected item.
void removeAllItems()
Removes all items from the list.
TGUI_NODISCARD HorizontalAlignment getTextAlignment() const
Gets the current horizontal text alignment.
bool removeItemByIndex(std::size_t index)
Removes the item from the list box.
TGUI_NODISCARD String getIdByIndex(std::size_t index) const
Returns the id of the item at the given index.
void load(const std::unique_ptr< DataIO::Node > &node, const LoadingRenderersMap &renderers) override
Loads the widget from a tree of nodes.
static TGUI_NODISCARD ListBox::Ptr create()
Creates a new list box widget.
TGUI_NODISCARD unsigned int getItemHeight() const
Returns the height of the items in the list box.
bool removeItemById(const String &id)
Removes the item that were added with the given id.
bool scrolled(float delta, Vector2f pos, bool touch) override
Called by the parent on scroll event (either from mouse wheel of from two finger scrolling on a touch...
TGUI_NODISCARD int getIndexById(const String &id) const
Returns the index of the item with the given id.
bool setSelectedItemById(const String &id)
Selects an item in the list box.
bool setSelectedItem(const String &itemName)
Selects an item in the list box.
void setScrollbarValue(unsigned int value)
Changes the thumb position of the scrollbar.
bool removeItem(const String &itemName)
Removes the item from the list with the given name.
void setSize(const Layout2d &size) override
Changes the size of the list box.
static TGUI_NODISCARD ListBox::Ptr copy(const ListBox::ConstPtr &listBox)
Makes a copy of another list box.
TGUI_NODISCARD std::size_t getMaximumItems() const
Returns the maximum items that the list box can contain.
TGUI_NODISCARD std::size_t getItemCount() const
Returns the amount of items in the list box.
TGUI_NODISCARD ListBoxRenderer * getSharedRenderer() override
Returns the renderer, which gives access to functions that determine how the widget is displayed.
TGUI_NODISCARD String getSelectedItemId() const
Gets the id of the selected item.
std::size_t addItem(const String &itemName, const String &id="")
Adds an item to the list.
void rendererChanged(const String &property) override
Function called when one of the properties of the renderer is changed.
void setAutoScroll(bool autoScroll)
Changes whether the list box scrolls to the bottom when a new item is added.
TGUI_NODISCARD bool isMouseOnWidget(Vector2f pos) const override
Returns whether the mouse position (which is relative to the parent widget) lies on top of the widget...
TGUI_NODISCARD std::unique_ptr< DataIO::Node > save(SavingRenderersMap &renderers) const override
Saves the widget as a tree node in order to save it to a file.
std::shared_ptr< ListBox > Ptr
Shared widget pointer.
Definition ListBox.hpp:44
TGUI_NODISCARD unsigned int getScrollbarValue() const
Returns the thumb position of the scrollbar.
bool setSelectedItemByIndex(std::size_t index)
Selects an item in the list box.
TGUI_NODISCARD int getSelectedItemIndex() const
Gets the index of the selected item.
TGUI_NODISCARD Widget::Ptr clone() const override
Makes a copy of the widget if you don't know its exact type.
TGUI_NODISCARD DataType getItemData(std::size_t index) const
Returns user data stored in the item.
Definition ListBox.hpp:354
Definition ListBoxRenderer.hpp:35
Definition Outline.hpp:38
Signal to which the user can subscribe to get callbacks from.
Definition Signal.hpp:61
Signal to which the user can subscribe to get callbacks from.
Definition Signal.hpp:522
Definition Sprite.hpp:47
Wrapper class to store strings.
Definition String.hpp:96
Backend-independent wrapper around the backend-specific text class.
Definition Text.hpp:48
Wrapper for text styles.
Definition TextStyle.hpp:55
The parent class for every widget.
Definition Widget.hpp:83
std::shared_ptr< Widget > Ptr
Shared widget pointer.
Definition Widget.hpp:86
Namespace that contains all TGUI functions and classes.
Definition AbsoluteOrRelativeValue.hpp:38
HorizontalAlignment
The horizontal alignment.
Definition Layout.hpp:61
KeyPressed event parameters.
Definition Event.hpp:168
Definition ListBox.hpp:623
States used for drawing.
Definition RenderStates.hpp:38