TGUI  1.0-alpha
ListView.hpp
1
2//
3// TGUI - Texus' Graphical User Interface
4// Copyright (C) 2012-2022 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
120
126 void setSize(const Layout2d& size) override;
127 using Widget::setSize;
128
129
139 std::size_t addColumn(const String& text, float width = 0, ColumnAlignment alignment = ColumnAlignment::Left);
140
141
148 void setColumnText(std::size_t index, const String& text);
149
150
158 String getColumnText(std::size_t index) const;
159
160
167 void setColumnWidth(std::size_t index, float width);
168
169
177 float getColumnWidth(std::size_t index) const;
178
179
186 void setColumnAlignment(std::size_t columnIndex, ColumnAlignment alignment);
187
188
196 ColumnAlignment getColumnAlignment(std::size_t columnIndex) const;
197
198
203
204
210 std::size_t getColumnCount() const;
211
212
218 void setHeaderHeight(float height);
219
220
226 float getHeaderHeight() const;
227
228
235
236
242 void setHeaderVisible(bool showHeader);
243
244
250 bool getHeaderVisible() const;
251
252
260 std::size_t addItem(const String& text);
261
262
270 std::size_t addItem(const std::vector<String>& item);
271
272
278 void addMultipleItems(const std::vector<std::vector<String>>& items);
279
286 void insertItem(std::size_t index, const String& text);
287
294 void insertItem(std::size_t index, const std::vector<String>& item);
295
302 void insertMultipleItems(std::size_t index, const std::vector<std::vector<String>>& items);
303
312 bool changeItem(std::size_t index, const std::vector<String>& item);
313
314
324 bool changeSubItem(std::size_t index, std::size_t column, const String& item);
325
326
334 bool removeItem(std::size_t index);
335
336
341
342
348 void setSelectedItem(std::size_t index);
349
350
356 void setSelectedItems(const std::set<std::size_t>& indices);
357
358
363
364
371
372
378 std::set<std::size_t> getSelectedItemIndices() const;
379
380
386 void setMultiSelect(bool multiSelect);
387
388
394 bool getMultiSelect() const;
395
396
409 void setItemData(std::size_t index, Any data);
410
411
418 template <typename T>
419 T getItemData(std::size_t index) const
420 {
421 if (index < m_items.size())
422 return AnyCast<T>(m_items[index].data);
423 else
424 throw std::bad_cast();
425 }
426
427
434 void setItemIcon(std::size_t index, const Texture& texture);
435
436
444 Texture getItemIcon(std::size_t index) const;
445
446
452 std::size_t getItemCount() const;
453
454
462 String getItem(std::size_t index) const;
463
464
474 std::vector<String> getItemRow(std::size_t index) const;
475
476
485 String getItemCell(std::size_t rowIndex, std::size_t columnIndex) const;
486
487
493 std::vector<String> getItems() const;
494
495
501 std::vector<std::vector<String>> getItemRows() const;
502
503
510 void sort(std::size_t index, const std::function<bool(const String&, const String&)>& cmp);
511
512
518 void setItemHeight(unsigned int itemHeight);
519
520
526 unsigned int getItemHeight() const;
527
528
536 void setHeaderTextSize(unsigned int textSize);
537
538
544 unsigned int getHeaderTextSize() const;
545
546
552 void setSeparatorWidth(unsigned int width);
553
554
560 unsigned int getSeparatorWidth() const;
561
562
568 void setHeaderSeparatorHeight(unsigned int height);
569
570
576 unsigned int getHeaderSeparatorHeight() const;
577
578
584 void setGridLinesWidth(unsigned int width);
585
586
592 unsigned int getGridLinesWidth() const;
593
594
602 void setAutoScroll(bool autoScroll);
603
604
610 bool getAutoScroll() const;
611
612
620 void setShowVerticalGridLines(bool showGridLines);
621
622
629
630
638 void setShowHorizontalGridLines(bool showGridLines);
639
640
647
648
654 void setExpandLastColumn(bool expand);
655
656
663
664
670
671
677
678
684
685
691
692
698 void setVerticalScrollbarValue(unsigned int value);
699
700
706 unsigned int getVerticalScrollbarValue() const;
707
708
714 void setHorizontalScrollbarValue(unsigned int value);
715
716
722 unsigned int getHorizontalScrollbarValue() const;
723
724
734
735
744
745
753 void setResizableColumns(bool resizable);
754
755
764
765
770 bool isMouseOnWidget(Vector2f pos) const override;
771
775 void leftMousePressed(Vector2f pos) override;
776
780 void leftMouseReleased(Vector2f pos) override;
781
785 void rightMousePressed(Vector2f pos) override;
786
790 void mouseMoved(Vector2f pos) override;
791
795 bool mouseWheelScrolled(float delta, Vector2f pos) override;
796
800 void mouseNoLongerOnWidget() override;
801
805 void leftMouseButtonNoLongerDown() override;
806
810 void keyPressed(const Event::KeyEvent& event) override;
811
812
819 void draw(BackendRenderTarget& target, RenderStates states) const override;
820
821
823 protected:
824
834 Signal& getSignal(String signalName) override;
835
836
842 void rendererChanged(const String& property) override;
843
844
848 std::unique_ptr<DataIO::Node> save(SavingRenderersMap& renderers) const override;
849
850
854 void load(const std::unique_ptr<DataIO::Node>& node, const LoadingRenderersMap& renderers) override;
855
856
860 void mouseEnteredWidget() override;
861
862
866 void mouseLeftWidget() override;
867
868
872 void updateTextSize() override;
873
874
876 // Returns the size without the borders
878 Vector2f getInnerSize() const;
879
880
882 // Create a Text object for an item from the given caption, using the preset color, font, text size and opacity
884 Text createText(const String& caption);
885
886
888 // Create a Text object for a header text from the given caption, using the preset color, font, text size and opacity
890 Text createHeaderText(const String& caption);
891
892
894 // Changes the color of all Text objects in an item
896 virtual void setItemColor(std::size_t index, const Color& color);
897
898
900 // Calculate the width of the column based on its caption when no column width was provided
902 float calculateAutoColumnWidth(const Text& text);
903
904
906 // Update the colors of the selected and hovered items
908 void updateSelectedAndhoveredItemColors();
909
910
912 // Update the color of all the items
914 void updateItemColors();
915
916
918 // Changes the color of all header texts
920 void updateHeaderTextsColor();
921
922
924 // Update on which item the mouse is standing
926 void updateHoveredItem(int item);
927
928
930 // Update which item is selected
932 void updateSelectedItem(int item);
933
934
936 // Selects multiple items when multi-select is on and the user selects an item while the shift key is held down
938 void selectRangeFromEvent(std::size_t item);
939
940
942 // Update the maximum item width of the last column by recalculating all items' widths.
943 // Returns whether the max item width was changed.
945 bool updateLastColumnMaxItemWidth();
946
947
949 // Update the maximum item width of the last column based on the addition of an Item.
950 // Returns true if the maximum item width was changed.
952 bool updateLastColumnMaxItemWidthWithNewItem(const Item& item);
953
954
956 // Update the maximum item width of the last column based on the modification of an Item.
957 // Returns true if the maximum item width was changed.
959 bool updateLastColumnMaxItemWidthWithModifiedItem(const Item& modifiedItem, float oldDesiredWidthInLastColumn);
960
961
963 // Add item to selected set
965 void addSelectedItem(int item);
966
967
969 // Remove item from selected set
971 void removeSelectedItem(std::size_t item);
972
973
975 // Update on which item the mouse is standing, given the current mouse position
977 void updateHoveredItemByMousePos(Vector2f mousePos);
978
979
981 // Returns either the configured separator width or the width of vertical grid lines, whichever is larger.
983 unsigned int getTotalSeparatorWidth() const;
984
985
987 // Returns the total width an Item takes up at some column, assuming it will not be cut off by the column.
989 float getItemTotalWidth(const Item& item, std::size_t columnIndex) const;
990
991
993 // Found out which column is located below the mouse. The mouseLeft is relative to the widget position.
994 // This function should only be called after checking that the mouse is positioned on top of the header.
996 int getColumnIndexBelowMouse(float mouseLeft);
997
998
1000 // Returns whether the mouse is standing between two columns.
1001 // If true then columnIndex is set to the index of border below the mouse (1 is the border between first two columns).
1002 // If true then pixelOffset is set to the distance between the center of the border and the mouse position.
1003 // If false then columnIndex and pixelOffset remain unchanged.
1005 bool findBorderBelowMouse(Vector2f pos, std::size_t& columnIndex, float& pixelOffset) const;
1006
1007
1009 // Recalculate the size and viewport size of the scrollbars
1011 void updateScrollbars();
1012
1014 // Recalculate the maximum value for the vertical scrollbar
1016 void updateVerticalScrollbarMaximum();
1017
1019 // Recalculate the maximum value for the horizontal scrollbar
1021 void updateHorizontalScrollbarMaximum();
1022
1023
1025 // Draw the header text for a single column
1027 void drawHeaderText(BackendRenderTarget& target, RenderStates states, float columnWidth, float headerHeight, std::size_t column) const;
1028
1029
1031 // Draw the texts in a single column
1033 void drawColumn(BackendRenderTarget& target, RenderStates states, std::size_t firstItem, std::size_t lastItem, std::size_t column, float columnWidth) const;
1034
1035
1037 // This function is called every frame with the time passed since the last frame.
1039 bool updateTime(Duration elapsedTime) override;
1040
1041
1043 // Makes a copy of the widget
1045 Widget::Ptr clone() const override;
1046
1047
1049 public:
1050
1056 SignalInt onItemSelect = {"ItemSelected"};
1057
1058 SignalInt onDoubleClick = {"DoubleClicked"};
1059 SignalInt onRightClick = {"RightClicked"};
1060 SignalInt onHeaderClick = {"HeaderClicked"};
1061
1062
1064 protected:
1065
1066 std::vector<Column> m_columns;
1067 std::vector<Item> m_items;
1068 std::set<std::size_t> m_selectedItems;
1069
1070 int m_hoveredItem = -1;
1071 int m_firstSelectedItemIndex = -1;
1072 int m_focusedItemIndex = -1;
1073
1074 float m_requestedHeaderHeight = 0;
1075 unsigned int m_itemHeight = 0;
1076 unsigned int m_headerTextSize = 0;
1077 unsigned int m_headerSeparatorHeight = 0;
1078 unsigned int m_separatorWidth = 1;
1079 unsigned int m_gridLinesWidth = 1;
1080 unsigned int m_iconCount = 0;
1081 float m_maxIconWidth = 0;
1082 float m_maxItemWidth = 0; // If there are no columns, this is the maximum width from all items
1083 bool m_headerVisible = true;
1084 bool m_showHorizontalGridLines = false;
1085 bool m_showVerticalGridLines = true;
1086 bool m_expandLastColumn = false;
1087 bool m_multiSelect = false;
1088 bool m_resizableColumns = false;
1089 Vector2f m_fixedIconSize;
1090 Cursor::Type m_currentListViewMouseCursor = Cursor::Type::Arrow;
1091 std::size_t m_resizingColumn = 0;
1092 float m_resizingColumnPixelOffset = 0;
1093
1094 CopiedSharedPtr<ScrollbarChildWidget> m_horizontalScrollbar;
1095 CopiedSharedPtr<ScrollbarChildWidget> m_verticalScrollbar;
1096 Scrollbar::Policy m_verticalScrollbarPolicy = Scrollbar::Policy::Automatic;
1097 Scrollbar::Policy m_horizontalScrollbarPolicy = Scrollbar::Policy::Automatic;
1098
1099 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
1100 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
1101 bool m_autoScroll = true; // Should the list view scroll to the bottom when a new item is added?
1102
1103 Sprite m_spriteHeaderBackground;
1104 Sprite m_spriteBackground;
1105
1106 // Cached renderer properties
1107 Borders m_bordersCached;
1108 Borders m_paddingCached;
1109 Color m_borderColorCached;
1110 Color m_separatorColorCached;
1111 Color m_gridLinesColorCached;
1112 Color m_headerTextColorCached;
1113 Color m_headerBackgroundColorCached;
1114 Color m_backgroundColorCached;
1115 Color m_backgroundColorHoverCached;
1116 Color m_selectedBackgroundColorCached;
1117 Color m_selectedBackgroundColorHoverCached;
1118 Color m_textColorCached;
1119 Color m_textColorHoverCached;
1120 Color m_selectedTextColorCached;
1121 Color m_selectedTextColorHoverCached;
1122
1124 };
1125
1127}
1128
1130
1131#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
Type
List of available cursors.
Definition: Cursor.hpp:48
@ Arrow
Arrow cursor (default)
Wrapper for durations.
Definition: Duration.hpp:52
Class to store the position or size of a widget.
Definition: Layout.hpp:284
Definition: ListViewRenderer.hpp:37
List view widget.
Definition: ListView.hpp:46
Signal & getSignal(String signalName) override
Retrieves a signal based on its name.
void updateTextSize() override
Called when the text size is changed (either by setTextSize or via the renderer)
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.
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:419
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 setResizableColumns(bool resizable)
Changes whether the user can resize the columns by dragging the border between columns.
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.
bool getResizableColumns() const
Returns whether the user can resize the columns by dragging the border between columns.
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
void mouseEnteredWidget() override
This function is called when the mouse enters the widget.
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.
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.
void mouseLeftWidget() override
This function is called when the mouse leaves the widget.
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:48
Definition: Texture.hpp:52
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