--- --- 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
69 TGUI_NODISCARD static ListBox::Ptr create();
70
79 TGUI_NODISCARD static ListBox::Ptr copy(const ListBox::ConstPtr& listBox);
80
85 TGUI_NODISCARD ListBoxRenderer* getSharedRenderer() override;
86 TGUI_NODISCARD const ListBoxRenderer* getSharedRenderer() const override;
87
93 TGUI_NODISCARD ListBoxRenderer* getRenderer() override;
94
101 void setSize(const Layout2d& size) override;
102 using Widget::setSize;
103
114 std::size_t addItem(const String& itemName, const String& id = "");
115
130 bool setSelectedItem(const String& itemName);
131
147
161 bool setSelectedItemByIndex(std::size_t index);
162
168
181 bool removeItem(const String& itemName);
182
195 bool removeItemById(const String& id);
196
210 bool removeItemByIndex(std::size_t index);
211
217
228 TGUI_NODISCARD String getItemById(const String& id) const;
229
237 TGUI_NODISCARD String getItemByIndex(std::size_t index) const;
238
248 TGUI_NODISCARD int getIndexById(const String& id) const;
249
257 TGUI_NODISCARD String getIdByIndex(std::size_t index) const;
258
266 TGUI_NODISCARD String getSelectedItem() const;
267
275 TGUI_NODISCARD String getSelectedItemId() const;
276
283 TGUI_NODISCARD int getSelectedItemIndex() const;
284
298 bool changeItem(const String& originalValue, const String& newValue);
299
313 bool changeItemById(const String& id, const String& newValue);
314
326 bool changeItemByIndex(std::size_t index, const String& newValue);
327
334 TGUI_NODISCARD std::size_t getItemCount() const;
335
342 TGUI_NODISCARD std::vector<String> getItems() const;
343
352 TGUI_NODISCARD std::vector<String> getItemIds() const;
353
366 void setItemData(std::size_t index, Any data);
367
374 template <typename DataType>
375 TGUI_NODISCARD DataType getItemData(std::size_t index) const
376 {
377 if (index < m_items.size())
378 return AnyCast<DataType>(m_items[index].data);
379 else
380 throw std::bad_cast();
381 }
382
391 void setItemHeight(unsigned int itemHeight);
392
399 TGUI_NODISCARD unsigned int getItemHeight() const;
400
410 void setMaximumItems(std::size_t maximumItems = 0);
411
419 TGUI_NODISCARD std::size_t getMaximumItems() const;
420
429 void setAutoScroll(bool autoScroll);
430
435 TGUI_NODISCARD bool getAutoScroll() const;
436
445
451 TGUI_NODISCARD HorizontalAlignment getTextAlignment() const;
452
460 TGUI_NODISCARD bool contains(const String& item) const;
461
469 TGUI_NODISCARD bool containsId(const String& id) const;
470
476 void setScrollbarValue(unsigned int value);
477
483 TGUI_NODISCARD unsigned int getScrollbarValue() const;
484
491 TGUI_NODISCARD bool isMouseOnWidget(Vector2f pos) const override;
492
496 bool leftMousePressed(Vector2f pos) override;
497
501 void leftMouseReleased(Vector2f pos) override;
502
506 void mouseMoved(Vector2f pos) override;
507
511 bool scrolled(float delta, Vector2f pos, bool touch) override;
512
516 void mouseNoLongerOnWidget() override;
517
521 void leftMouseButtonNoLongerDown() override;
522
526 void keyPressed(const Event::KeyEvent& event) override;
527
537 bool canHandleKeyPress(const Event::KeyEvent& event) override;
538
546 void draw(BackendRenderTarget& target, RenderStates states) const override;
547
549 protected:
550
560 TGUI_NODISCARD Signal& getSignal(String signalName) override;
561
568 void rendererChanged(const String& property) override;
569
573 TGUI_NODISCARD std::unique_ptr<DataIO::Node> save(SavingRenderersMap& renderers) const override;
574
578 void load(const std::unique_ptr<DataIO::Node>& node, const LoadingRenderersMap& renderers) override;
579
583 void updateTextSize() override;
584
586 // Returns the size without the borders
588 TGUI_NODISCARD Vector2f getInnerSize() const;
589
591 // Updates the position of the items and the scrollbar
593 void updateItemPositions();
594
596 // Update the colors and text style of the selected and hovered items
598 void updateSelectedAndHoveringItemColorsAndStyle();
599
601 // Update the color and text style of all the items
603 void updateItemColorsAndStyle();
604
606 // Update on which item the mouse is standing
608 void updateHoveringItem(int item);
609
611 // Update which item is selected
613 void updateSelectedItem(int item);
614
616 // Checks whether the scrollbar value was changed and emit the onScroll event if it did
618 void triggerOnScroll();
619
621 // This function is called every frame with the time passed since the last frame.
623 bool updateTime(Duration elapsedTime) override;
624
626 // Makes a copy of the widget
628 TGUI_NODISCARD Widget::Ptr clone() const override;
629
631 public:
632
633 SignalItem onItemSelect = {"ItemSelected"};
634 SignalItem onMousePress = {"MousePressed"};
635 SignalItem onMouseRelease = {"MouseReleased"};
636 SignalItem onDoubleClick = {"DoubleClicked"};
637 SignalUInt onScroll = {"Scrolled"};
638
640 protected:
641
642 struct Item
643 {
644 Text text;
645 Any data;
646 String id;
647 };
648
649 std::vector<Item> m_items;
650
651 // What is the index of the selected item?
652 // This is also used by combo box, so it can't just be changed to a pointer!
653 int m_selectedItem = -1;
654
655 int m_hoveringItem = -1;
656
657 unsigned int m_itemHeight = 0;
658
659 // This will store the maximum number of items in the list box (zero by default, meaning that there is no limit)
660 std::size_t m_maxItems = 0;
661
662 // When there are too many items a scrollbar will be shown
664 unsigned int m_lastScrollbarValue = 0;
665
666 // Will be set to true after the first click, but gets reset to false when the second click does not occur soon after
667 bool m_possibleDoubleClick = false;
668
669 bool m_autoScroll = true;
670 HorizontalAlignment m_textAlignment = HorizontalAlignment::Left;
671
672 Sprite m_spriteBackground;
673
674 // Cached renderer properties
675 Borders m_bordersCached;
676 Borders m_paddingCached;
677 Color m_borderColorCached;
678 Color m_backgroundColorCached;
679 Color m_backgroundColorHoverCached;
680 Color m_selectedBackgroundColorCached;
681 Color m_selectedBackgroundColorHoverCached;
682 Color m_textColorCached;
683 Color m_textColorHoverCached;
684 Color m_selectedTextColorCached;
685 Color m_selectedTextColorHoverCached;
686 TextStyles m_textStyleCached;
687 TextStyles m_selectedTextStyleCached;
688
690 };
691
693}
694
696
697#endif // TGUI_LIST_BOX_HPP
Base class for render targets.
Definition BackendRenderTarget.hpp:48
Wrapper for colors.
Definition Color.hpp:74
Definition CopiedSharedPtr.hpp:45
Wrapper for durations.
Definition Duration.hpp:56
Class to store the position or size of a widget.
Definition Layout.hpp:328
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.
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:375
Definition ListBoxRenderer.hpp:37
Definition Outline.hpp:39
Signal to which the user can subscribe to get callbacks from.
Definition Signal.hpp:62
Signal to which the user can subscribe to get callbacks from.
Definition Signal.hpp:559
Definition Sprite.hpp:48
Wrapper class to store strings.
Definition String.hpp:101
Backend-independent wrapper around the backend-specific text class.
Definition Text.hpp:50
Wrapper for text styles.
Definition TextStyle.hpp:57
The parent class for every widget.
Definition Widget.hpp:84
std::shared_ptr< Widget > Ptr
Shared widget pointer.
Definition Widget.hpp:87
Namespace that contains all TGUI functions and classes.
Definition AbsoluteOrRelativeValue.hpp:39
HorizontalAlignment
The horizontal alignment.
Definition Layout.hpp:52
KeyPressed event parameters.
Definition Event.hpp:169
Definition ListBox.hpp:643
States used for drawing.
Definition RenderStates.hpp:39