TGUI  0.10-dev
ListView.hpp
1
2//
3// TGUI - Texus' Graphical User Interface
4// Copyright (C) 2012-2021 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
26#ifndef TGUI_LIST_VIEW_HPP
27#define TGUI_LIST_VIEW_HPP
28
29
30#include <TGUI/CopiedSharedPtr.hpp>
31#include <TGUI/Widgets/Scrollbar.hpp>
32#include <TGUI/Renderers/ListViewRenderer.hpp>
33#include <TGUI/Text.hpp>
34#include <set>
35
37
38namespace tgui
39{
45 class TGUI_API ListView : public Widget
46 {
47 public:
48
49 typedef std::shared_ptr<ListView> Ptr;
50 typedef std::shared_ptr<const ListView> ConstPtr;
51
55 enum class ColumnAlignment
56 {
57 Left,
58 Center,
59 Right
60 };
61
62 struct Item
63 {
64 std::vector<Text> texts;
65 Any data;
66 Sprite icon;
67 };
68
69 struct Column
70 {
71 float width = 0;
72 float designWidth = 0;
73 float maxItemWidth = 0;
74 Text text;
75 ColumnAlignment alignment = ColumnAlignment::Left;
76 };
77
78
86 ListView(const char* typeName = "ListView", bool initRenderer = true);
87
88
94
95
104
105
111 const ListViewRenderer* getSharedRenderer() const;
112
119 const ListViewRenderer* getRenderer() const;
120
121
127 void setSize(const Layout2d& size) override;
128 using Widget::setSize;
129
130
140 std::size_t addColumn(const String& text, float width = 0, ColumnAlignment alignment = ColumnAlignment::Left);
141
142
149 void setColumnText(std::size_t index, const String& text);
150
151
159 String getColumnText(std::size_t index) const;
160
161
168 void setColumnWidth(std::size_t index, float width);
169
170
178 float getColumnWidth(std::size_t index) const;
179
180
187 void setColumnAlignment(std::size_t columnIndex, ColumnAlignment alignment);
188
189
197 ColumnAlignment getColumnAlignment(std::size_t columnIndex) const;
198
199
204
205
211 std::size_t getColumnCount() const;
212
213
219 void setHeaderHeight(float height);
220
221
227 float getHeaderHeight() const;
228
229
236
237
243 void setHeaderVisible(bool showHeader);
244
245
251 bool getHeaderVisible() const;
252
253
261 std::size_t addItem(const String& text);
262
263
271 std::size_t addItem(const std::vector<String>& item);
272
273
279 void addMultipleItems(const std::vector<std::vector<String>>& items);
280
287 void insertItem(std::size_t index, const String& text);
288
295 void insertItem(std::size_t index, const std::vector<String>& item);
296
303 void insertMultipleItems(std::size_t index, const std::vector<std::vector<String>>& items);
304
313 bool changeItem(std::size_t index, const std::vector<String>& item);
314
315
325 bool changeSubItem(std::size_t index, std::size_t column, const String& item);
326
327
335 bool removeItem(std::size_t index);
336
337
342
343
349 void setSelectedItem(std::size_t index);
350
351
357 void setSelectedItems(const std::set<std::size_t>& indices);
358
359
364
365
372
373
379 std::set<std::size_t> getSelectedItemIndices() const;
380
381
387 void setMultiSelect(bool multiSelect);
388
389
395 bool getMultiSelect() const;
396
397
410 void setItemData(std::size_t index, Any data);
411
412
419 template <typename T>
420 T getItemData(std::size_t index) const
421 {
422 if (index < m_items.size())
423 return AnyCast<T>(m_items[index].data);
424 else
425 throw std::bad_cast();
426 }
427
428
435 void setItemIcon(std::size_t index, const Texture& texture);
436
437
445 Texture getItemIcon(std::size_t index) const;
446
447
453 std::size_t getItemCount() const;
454
455
463 String getItem(std::size_t index) const;
464
465
475 std::vector<String> getItemRow(std::size_t index) const;
476
477
486 String getItemCell(std::size_t rowIndex, std::size_t columnIndex) const;
487
488
494 std::vector<String> getItems() const;
495
496
502 std::vector<std::vector<String>> getItemRows() const;
503
504
511 void sort(std::size_t index, const std::function<bool(const String&, const String&)>& cmp);
512
513
519 void setItemHeight(unsigned int itemHeight);
520
521
527 unsigned int getItemHeight() const;
528
529
540 void setTextSize(unsigned int textSize) override;
541
542
550 void setHeaderTextSize(unsigned int textSize);
551
552
558 unsigned int getHeaderTextSize() const;
559
560
566 void setSeparatorWidth(unsigned int width);
567
568
574 unsigned int getSeparatorWidth() const;
575
576
582 void setHeaderSeparatorHeight(unsigned int height);
583
584
590 unsigned int getHeaderSeparatorHeight() const;
591
592
598 void setGridLinesWidth(unsigned int width);
599
600
606 unsigned int getGridLinesWidth() const;
607
608
616 void setAutoScroll(bool autoScroll);
617
618
624 bool getAutoScroll() const;
625
626
634 void setShowVerticalGridLines(bool showGridLines);
635
636
643
644
652 void setShowHorizontalGridLines(bool showGridLines);
653
654
661
662
668 void setExpandLastColumn(bool expand);
669
670
677
678
684
685
691
692
698
699
705
706
712 void setVerticalScrollbarValue(unsigned int value);
713
714
720 unsigned int getVerticalScrollbarValue() const;
721
722
728 void setHorizontalScrollbarValue(unsigned int value);
729
730
736 unsigned int getHorizontalScrollbarValue() const;
737
738
748
749
758
759
764 bool isMouseOnWidget(Vector2f pos) const override;
765
769 void leftMousePressed(Vector2f pos) override;
770
774 void leftMouseReleased(Vector2f pos) override;
775
779 void rightMousePressed(Vector2f pos) override;
780
784 void mouseMoved(Vector2f pos) override;
785
789 bool mouseWheelScrolled(float delta, Vector2f pos) override;
790
794 void mouseNoLongerOnWidget() override;
795
799 void leftMouseButtonNoLongerDown() override;
800
804 void keyPressed(const Event::KeyEvent& event) override;
805
806
813 void draw(BackendRenderTarget& target, RenderStates states) const override;
814
815
817 protected:
818
828 Signal& getSignal(String signalName) override;
829
830
836 void rendererChanged(const String& property) override;
837
838
842 std::unique_ptr<DataIO::Node> save(SavingRenderersMap& renderers) const override;
843
844
848 void load(const std::unique_ptr<DataIO::Node>& node, const LoadingRenderersMap& renderers) override;
849
850
852 // Returns the size without the borders
854 Vector2f getInnerSize() const;
855
856
858 // Create a Text object for an item from the given caption, using the preset color, font, text size and opacity
860 Text createText(const String& caption);
861
862
864 // Create a Text object for a header text from the given caption, using the preset color, font, text size and opacity
866 Text createHeaderText(const String& caption);
867
868
870 // Changes the color of all Text objects in an item
872 virtual void setItemColor(std::size_t index, const Color& color);
873
874
876 // Calculate the width of the column based on its caption when no column width was provided
878 float calculateAutoColumnWidth(const Text& text);
879
880
882 // Update the colors of the selected and hovered items
884 void updateSelectedAndhoveredItemColors();
885
886
888 // Update the color of all the items
890 void updateItemColors();
891
892
894 // Changes the color of all header texts
896 void updateHeaderTextsColor();
897
898
900 // Update on which item the mouse is standing
902 void updateHoveredItem(int item);
903
904
906 // Update which item is selected
908 void updateSelectedItem(int item);
909
910
912 // Selects multiple items when multi-select is on and the user selects an item while the shift key is held down
914 void selectRangeFromEvent(std::size_t item);
915
916
918 // Update the maximum item width of the last column by recalculating all items' widths.
919 // Returns whether the max item width was changed.
921 bool updateLastColumnMaxItemWidth();
922
923
925 // Update the maximum item width of the last column based on the addition of an Item.
926 // Returns true if the maximum item width was changed.
928 bool updateLastColumnMaxItemWidthWithNewItem(const Item& item);
929
930
932 // Update the maximum item width of the last column based on the modification of an Item.
933 // Returns true if the maximum item width was changed.
935 bool updateLastColumnMaxItemWidthWithModifiedItem(const Item& modifiedItem, float oldDesiredWidthInLastColumn);
936
937
939 // Add item to selected set
941 void addSelectedItem(int item);
942
943
945 // Remove item from selected set
947 void removeSelectedItem(std::size_t item);
948
949
951 // Update on which item the mouse is standing, given the current mouse position
953 void updateHoveredItemByMousePos(Vector2f mousePos);
954
955
957 // Returns either the configured separator width or the width of vertical grid lines, whichever is larger.
959 unsigned int getTotalSeparatorWidth() const;
960
961
963 // Returns the total width an Item takes up at some column, assuming it will not be cut off by the column.
965 float getItemTotalWidth(const Item& item, std::size_t columnIndex) const;
966
967
969 // Found out which column is located below the mouse. The mouseLeft is relative to the widget position.
970 // This function should only be called after checking that the mouse is positioned on top of the header.
972 int getColumnIndexBelowMouse(float mouseLeft);
973
974
976 // Recalculate the size and viewport size of the scrollbars
978 void updateScrollbars();
979
981 // Recalculate the maximum value for the vertical scrollbar
983 void updateVerticalScrollbarMaximum();
984
986 // Recalculate the maximum value for the horizontal scrollbar
988 void updateHorizontalScrollbarMaximum();
989
990
992 // Draw the header text for a single column
994 void drawHeaderText(BackendRenderTarget& target, RenderStates states, float columnWidth, float headerHeight, std::size_t column) const;
995
996
998 // Draw the texts in a single column
1000 void drawColumn(BackendRenderTarget& target, RenderStates states, std::size_t firstItem, std::size_t lastItem, std::size_t column, float columnWidth) const;
1001
1002
1004 // This function is called every frame with the time passed since the last frame.
1006 bool updateTime(Duration elapsedTime) override;
1007
1008
1010 // Makes a copy of the widget
1012 Widget::Ptr clone() const override
1013 {
1014 return std::make_shared<ListView>(*this);
1015 }
1016
1017
1019 public:
1020
1026 SignalInt onItemSelect = {"ItemSelected"};
1027
1028 SignalInt onDoubleClick = {"DoubleClicked"};
1029 SignalInt onRightClick = {"RightClicked"};
1030 SignalInt onHeaderClick = {"HeaderClicked"};
1031
1032
1034 protected:
1035
1036 std::vector<Column> m_columns;
1037 std::vector<Item> m_items;
1038 std::set<std::size_t> m_selectedItems;
1039
1040 int m_hoveredItem = -1;
1041 int m_firstSelectedItemIndex = -1;
1042 int m_focusedItemIndex = -1;
1043
1044 float m_requestedHeaderHeight = 0;
1045 unsigned int m_itemHeight = 0;
1046 unsigned int m_requestedTextSize = 0;
1047 unsigned int m_headerTextSize = 0;
1048 unsigned int m_headerSeparatorHeight = 0;
1049 unsigned int m_separatorWidth = 1;
1050 unsigned int m_gridLinesWidth = 1;
1051 unsigned int m_iconCount = 0;
1052 float m_maxIconWidth = 0;
1053 float m_maxItemWidth = 0; // If there are no columns, this is the maximum width from all items
1054 bool m_headerVisible = true;
1055 bool m_showHorizontalGridLines = false;
1056 bool m_showVerticalGridLines = true;
1057 bool m_expandLastColumn = false;
1058 bool m_multiSelect = false;
1059 Vector2f m_fixedIconSize;
1060
1061 CopiedSharedPtr<ScrollbarChildWidget> m_horizontalScrollbar;
1062 CopiedSharedPtr<ScrollbarChildWidget> m_verticalScrollbar;
1063 Scrollbar::Policy m_verticalScrollbarPolicy = Scrollbar::Policy::Automatic;
1064 Scrollbar::Policy m_horizontalScrollbarPolicy = Scrollbar::Policy::Automatic;
1065
1066 int m_mouseOnHeaderIndex = -1; // If the left mouse is down, this contains the index of the column if the mouse went down on the header
1067 int m_possibleDoubleClick = false; // Will be set to true after the first click, but gets reset to false when the second click does not occur soon after
1068 bool m_autoScroll = true; // Should the list view scroll to the bottom when a new item is added?
1069
1070 // Cached renderer properties
1071 Borders m_bordersCached;
1072 Borders m_paddingCached;
1073 Color m_borderColorCached;
1074 Color m_separatorColorCached;
1075 Color m_gridLinesColorCached;
1076 Color m_headerTextColorCached;
1077 Color m_headerBackgroundColorCached;
1078 Color m_backgroundColorCached;
1079 Color m_backgroundColorHoverCached;
1080 Color m_selectedBackgroundColorCached;
1081 Color m_selectedBackgroundColorHoverCached;
1082 Color m_textColorCached;
1083 Color m_textColorHoverCached;
1084 Color m_selectedTextColorCached;
1085 Color m_selectedTextColorHoverCached;
1086
1088 };
1089
1091}
1092
1094
1095#endif // TGUI_LIST_VIEW_HPP
Base class for render targets.
Definition: BackendRenderTarget.hpp:48
Wrapper for colors.
Definition: Color.hpp:63
Definition: CopiedSharedPtr.hpp:40
Wrapper for durations.
Definition: Duration.hpp:52
Class to store the position or size of a widget.
Definition: Layout.hpp:262
Definition: ListViewRenderer.hpp:37
List view widget.
Definition: ListView.hpp:46
Signal & getSignal(String signalName) override
Retrieves a signal based on its name.
void setShowVerticalGridLines(bool showGridLines)
Changes whether lines are drawn between columns.
bool isMouseOnWidget(Vector2f pos) const override
Returns whether the mouse position (which is relative to the parent widget) lies on top of the widget...
Scrollbar::Policy getVerticalScrollbarPolicy() const
Returns when the vertical scrollbar should be displayed.
std::shared_ptr< ListView > Ptr
Shared widget pointer.
Definition: ListView.hpp:49
void setSelectedItems(const std::set< std::size_t > &indices)
Selects items in the list view.
void setTextSize(unsigned int textSize) override
Changes the text size of the items.
bool getShowHorizontalGridLines() const
Returns whether lines are drawn between items.
String getColumnText(std::size_t index) const
Returns the text of a column.
void setHeaderTextSize(unsigned int textSize)
Changes the text size of the header caption.
bool changeItem(std::size_t index, const std::vector< String > &item)
Changes an item with values for multiple columns to the list.
T getItemData(std::size_t index) const
Returns user data stored in the item.
Definition: ListView.hpp:420
std::size_t addColumn(const String &text, float width=0, ColumnAlignment alignment=ColumnAlignment::Left)
Adds a column.
unsigned int getVerticalScrollbarValue() const
Returns the thumb position of the vertical scrollbar.
void setHorizontalScrollbarPolicy(Scrollbar::Policy policy)
Changes when the horizontal scrollbar should be displayed.
void removeAllItems()
Removes all items from the list.
void setColumnAlignment(std::size_t columnIndex, ColumnAlignment alignment)
Changes the text alignment within a column.
ColumnAlignment getColumnAlignment(std::size_t columnIndex) const
Returns the current text alignment within a column.
void setColumnWidth(std::size_t index, float width)
Changes the width of a column.
String getItem(std::size_t index) const
Retrieves an item in the list.
static ListView::Ptr copy(ListView::ConstPtr listView)
Makes a copy of another list view.
std::shared_ptr< const ListView > ConstPtr
Shared constant widget pointer.
Definition: ListView.hpp:50
unsigned int getSeparatorWidth() const
Returns the width of the column separator.
void setSize(const Layout2d &size) override
Changes the size of the list view.
void setHeaderVisible(bool showHeader)
Changes whether the header is shown.
void insertItem(std::size_t index, const String &text)
Inserts an item into the list.
std::vector< String > getItemRow(std::size_t index) const
Retrieves the values of all columns for an item in the list.
void setColumnText(std::size_t index, const String &text)
Changes the text of a column.
unsigned int getHorizontalScrollbarValue() const
Returns the thumb position of the horizontal scrollbar.
String getItemCell(std::size_t rowIndex, std::size_t columnIndex) const
Retrieves the value for a cell in the list.
void setVerticalScrollbarValue(unsigned int value)
Changes the thumb position of the vertical scrollbar.
bool getExpandLastColumn() const
Returns whether the last column is expanded to fill the list view (if all columns fit inside the list...
float getHeaderHeight() const
Returns the height of the header row.
std::size_t getColumnCount() const
Returns the amount of columns in the list view.
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.
unsigned int getGridLinesWidth() const
Returns the width of the grid lines.
void sort(std::size_t index, const std::function< bool(const String &, const String &)> &cmp)
Sort items.
Vector2f getFixedIconSize() const
Returns to which size all icons should be scaled.
void setHorizontalScrollbarValue(unsigned int value)
Changes the thumb position of the horizontal scrollbar.
void insertMultipleItems(std::size_t index, const std::vector< std::vector< String > > &items)
Inserts multiple items into the list.
bool getHeaderVisible() const
Returns whether the header is shown.
bool changeSubItem(std::size_t index, std::size_t column, const String &item)
Changes the caption of a single value in the item.
int getSelectedItemIndex() const
Gets the index of the selected item.
std::size_t addItem(const String &text)
Adds an item to the list.
unsigned int getItemHeight() const
Returns the height of the items in the list view.
void insertItem(std::size_t index, const std::vector< String > &item)
Inserts an item into the list.
void setItemIcon(std::size_t index, const Texture &texture)
Sets a small icon in front of the item.
float getColumnWidth(std::size_t index) const
Returns the width of a column.
void setVerticalScrollbarPolicy(Scrollbar::Policy policy)
Changes when the vertical scrollbar should be displayed.
void setFixedIconSize(Vector2f iconSize)
Sets a size to which all icons should be scaled.
ColumnAlignment
The text alignment for all texts within a column.
Definition: ListView.hpp:56
static ListView::Ptr create()
Creates a new list view widget.
std::size_t getItemCount() const
Returns the amount of items in the list view.
void load(const std::unique_ptr< DataIO::Node > &node, const LoadingRenderersMap &renderers) override
Loads the widget from a tree of nodes.
ListViewRenderer * getSharedRenderer()
Returns the renderer, which gives access to functions that determine how the widget is displayed.
bool getAutoScroll() const
Returns whether the list view scrolls to the bottom when a new item is added.
void setHeaderHeight(float height)
Changes the height of the header row.
void setShowHorizontalGridLines(bool showGridLines)
Changes whether lines are drawn between items.
void draw(BackendRenderTarget &target, RenderStates states) const override
Draw the widget to a render target.
void deselectItems()
Deselects the selected items.
void addMultipleItems(const std::vector< std::vector< String > > &items)
Adds multiple items to the list.
void setExpandLastColumn(bool expand)
Changes whether the last column is expanded to fill the list view (if all columns fit inside the list...
void setAutoScroll(bool autoScroll)
Changes whether the list view scrolls to the bottom when a new item is added.
std::size_t addItem(const std::vector< String > &item)
Adds an item with values for multiple columns to the list.
Widget::Ptr clone() const override
Makes a copy of the widget if you don't know its exact type.
Definition: ListView.hpp:1012
std::vector< std::vector< String > > getItemRows() const
Returns a list of all column values for all items in the list view.
std::set< std::size_t > getSelectedItemIndices() const
Gets the indices of the selected items.
void setItemHeight(unsigned int itemHeight)
Changes the height of the items in the list view.
void setSelectedItem(std::size_t index)
Selects an item in the list view.
void setSeparatorWidth(unsigned int width)
Changes the width of the column separator.
bool getMultiSelect() const
Returns multi selection of the items is allowed.
void setHeaderSeparatorHeight(unsigned int height)
Changes the height of the separator between the header and the items.
void setItemData(std::size_t index, Any data)
Store some user data with the item.
std::vector< String > getItems() const
Returns a list of the texts in the first column for all items in the list view.
unsigned int getHeaderTextSize() const
Returns the text size of the header caption.
Texture getItemIcon(std::size_t index) const
Gets the icon displayed in front of the item.
Scrollbar::Policy getHorizontalScrollbarPolicy() const
Returns when the horizontal scrollbar should be displayed.
void setMultiSelect(bool multiSelect)
Allow multi selection of the items.
void removeAllColumns()
Removes all columns.
bool removeItem(std::size_t index)
Removes the item from the list view.
float getCurrentHeaderHeight() const
Returns the height of the header or 0 if no header row is shown.
void rendererChanged(const String &property) override
Function called when one of the properties of the renderer is changed.
bool getShowVerticalGridLines() const
Returns whether lines are drawn between items.
unsigned int getHeaderSeparatorHeight() const
Returns the height of the separator between the header and the items.
void setGridLinesWidth(unsigned int width)
Changes the width of the grid lines.
ListViewRenderer * getRenderer()
Returns the renderer, which gives access to functions that determine how the widget is displayed.
Definition: Outline.hpp:39
Policy
Defines when the scrollbar shows up.
Definition: Scrollbar.hpp:50
@ Automatic
Show the scrollbar only when needed (default)
Signal to which the user can subscribe to get callbacks from.
Definition: Signal.hpp:58
Definition: Sprite.hpp:45
Wrapper class to store strings.
Definition: String.hpp:79
Definition: Text.hpp:44
Definition: Texture.hpp:49
The parent class for every widget.
Definition: Widget.hpp:70
std::shared_ptr< Widget > Ptr
Shared widget pointer.
Definition: Widget.hpp:73
virtual void setSize(const Layout2d &size)
Changes the size of the widget.
Namespace that contains all TGUI functions and classes.
Definition: AbsoluteOrRelativeValue.hpp:36
KeyPressed event parameters.
Definition: Event.hpp:167
Definition: ListView.hpp:70
Definition: ListView.hpp:63
States used for drawing.
Definition: RenderStates.hpp:39