TGUI  0.9.1
ListView.hpp
1 //
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 
38 namespace 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 
235  float getCurrentHeaderHeight() const;
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 
371  int getSelectedItemIndex() const;
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 
676  bool getExpandLastColumn() const;
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 
747  void setFixedIconSize(Vector2f iconSize);
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(BackendRenderTargetBase& 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  // Update the maximum item width of the last column by recalculating all items' widths.
913  // Returns whether the max item width was changed.
915  bool updateLastColumnMaxItemWidth();
916 
917 
919  // Update the maximum item width of the last column based on the addition of an Item.
920  // Returns true if the maximum item width was changed.
922  bool updateLastColumnMaxItemWidthWithNewItem(const Item& item);
923 
924 
926  // Update the maximum item width of the last column based on the modification of an Item.
927  // Returns true if the maximum item width was changed.
929  bool updateLastColumnMaxItemWidthWithModifiedItem(const Item& modifiedItem, float oldDesiredWidthInLastColumn);
930 
931 
933  // Add item to selected set
935  void addSelectedItem(int item);
936 
937 
939  // Remove item from selected set
941  void removeSelectedItem(std::size_t item);
942 
943 
945  // Update on which item the mouse is standing, given the current mouse position
947  void updateHoveredItemByMousePos(Vector2f mousePos);
948 
949 
951  // Returns either the configured separator width or the width of vertical grid lines, whichever is larger.
953  unsigned int getTotalSeparatorWidth() const;
954 
955 
957  // Returns the total width an Item takes up at some column, assuming it will not be cut off by the column.
959  float getItemTotalWidth(const Item& item, std::size_t columnIndex) const;
960 
961 
963  // Found out which column is located below the mouse. The mouseLeft is relative to the widget position.
964  // This function should only be called after checking that the mouse is positioned on top of the header.
966  int getColumnIndexBelowMouse(float mouseLeft);
967 
968 
970  // Recalculate the size and viewport size of the scrollbars
972  void updateScrollbars();
973 
975  // Recalculate the maximum value for the vertical scrollbar
977  void updateVerticalScrollbarMaximum();
978 
980  // Recalculate the maximum value for the horizontal scrollbar
982  void updateHorizontalScrollbarMaximum();
983 
984 
986  // Draw the header text for a single column
988  void drawHeaderText(BackendRenderTargetBase& target, RenderStates states, float columnWidth, float headerHeight, std::size_t column) const;
989 
990 
992  // Draw the texts in a single column
994  void drawColumn(BackendRenderTargetBase& target, RenderStates states, std::size_t firstItem, std::size_t lastItem, std::size_t column, float columnWidth) const;
995 
996 
998  // This function is called every frame with the time passed since the last frame.
1000  bool updateTime(Duration elapsedTime) override;
1001 
1002 
1004  // Makes a copy of the widget
1006  Widget::Ptr clone() const override
1007  {
1008  return std::make_shared<ListView>(*this);
1009  }
1010 
1011 
1013  public:
1014 
1020  SignalInt onItemSelect = {"ItemSelected"};
1021 
1022  SignalInt onDoubleClick = {"DoubleClicked"};
1023  SignalInt onRightClick = {"RightClicked"};
1024  SignalInt onHeaderClick = {"HeaderClicked"};
1025 
1026 
1028  protected:
1029 
1030  std::vector<Column> m_columns;
1031  std::vector<Item> m_items;
1032  std::set<std::size_t> m_selectedItems;
1033 
1034  int m_hoveredItem = -1;
1035  int m_lastMouseDownItem = -1;
1036 
1037  float m_requestedHeaderHeight = 0;
1038  unsigned int m_itemHeight = 0;
1039  unsigned int m_requestedTextSize = 0;
1040  unsigned int m_headerTextSize = 0;
1041  unsigned int m_headerSeparatorHeight = 0;
1042  unsigned int m_separatorWidth = 1;
1043  unsigned int m_gridLinesWidth = 1;
1044  unsigned int m_iconCount = 0;
1045  float m_maxIconWidth = 0;
1046  float m_maxItemWidth = 0; // If there are no columns, this is the maximum width from all items
1047  bool m_headerVisible = true;
1048  bool m_showHorizontalGridLines = false;
1049  bool m_showVerticalGridLines = true;
1050  bool m_expandLastColumn = false;
1051  bool m_multiSelect = false;
1052  Vector2f m_fixedIconSize;
1053 
1054  CopiedSharedPtr<ScrollbarChildWidget> m_horizontalScrollbar;
1055  CopiedSharedPtr<ScrollbarChildWidget> m_verticalScrollbar;
1056  Scrollbar::Policy m_verticalScrollbarPolicy = Scrollbar::Policy::Automatic;
1057  Scrollbar::Policy m_horizontalScrollbarPolicy = Scrollbar::Policy::Automatic;
1058 
1059  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
1060  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
1061  bool m_autoScroll = true; // Should the list view scroll to the bottom when a new item is added?
1062 
1063  // Cached renderer properties
1064  Borders m_bordersCached;
1065  Borders m_paddingCached;
1066  Color m_borderColorCached;
1067  Color m_separatorColorCached;
1068  Color m_gridLinesColorCached;
1069  Color m_headerTextColorCached;
1070  Color m_headerBackgroundColorCached;
1071  Color m_backgroundColorCached;
1072  Color m_backgroundColorHoverCached;
1073  Color m_selectedBackgroundColorCached;
1074  Color m_selectedBackgroundColorHoverCached;
1075  Color m_textColorCached;
1076  Color m_textColorHoverCached;
1077  Color m_selectedTextColorCached;
1078  Color m_selectedTextColorHoverCached;
1079 
1081  };
1082 
1084 }
1085 
1087 
1088 #endif // TGUI_LIST_VIEW_HPP
Base class for render targets.
Definition: BackendRenderTarget.hpp:48
Wrapper for colors.
Definition: Color.hpp:52
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
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 insertMultipleItems(std::size_t index, const std::vector< std::vector< String >> &items)
Inserts multiple items into the list.
Signal & getSignal(String signalName) override
Retrieves a signal based on its name.
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.
ListViewRenderer * getRenderer()
Returns the renderer, which gives access to functions that determine how the widget is displayed.
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.
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.
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.
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.
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 draw(BackendRenderTargetBase &target, RenderStates states) const override
Draw the widget to a render target.
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
std::set< std::size_t > getSelectedItemIndices() const
Gets the indices of the selected items.
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.
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 deselectItems()
Deselects the selected items.
void setExpandLastColumn(bool expand)
Changes whether the last column is expanded to fill the list view (if all columns fit inside the list...
void addMultipleItems(const std::vector< std::vector< String >> &items)
Adds multiple items to 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:1006
ListViewRenderer * getSharedRenderer()
Returns the renderer, which gives access to functions that determine how the widget is displayed.
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.
std::vector< std::vector< String > > getItemRows() const
Returns a list of all column values for all items in the list view.
void setItemData(std::size_t index, Any data)
Store some user data with the item.
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.
std::vector< String > getItems() const
Returns a list of the texts in the first column for all items in the list view.
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.
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:49
Wrapper class to store strings.
Definition: String.hpp:74
Definition: Text.hpp:44
Definition: Texture.hpp:48
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