libyui  3.10.0
YTable.h
1 /*
2  Copyright (C) 2000-2012 Novell, Inc
3  This library is free software; you can redistribute it and/or modify
4  it under the terms of the GNU Lesser General Public License as
5  published by the Free Software Foundation; either version 2.1 of the
6  License, or (at your option) version 3.0 of the License. This library
7  is distributed in the hope that it will be useful, but WITHOUT ANY
8  WARRANTY; without even the implied warranty of MERCHANTABILITY or
9  FITNESS FOR A PARTICULAR PURPOSE. See the GNU Lesser General Public
10  License for more details. You should have received a copy of the GNU
11  Lesser General Public License along with this library; if not, write
12  to the Free Software Foundation, Inc., 51 Franklin Street, Fifth
13  Floor, Boston, MA 02110-1301 USA
14 */
15 
16 
17 /*-/
18 
19  File: YTable.h
20 
21  Author: Stefan Hundhammer <sh@suse.de>
22 
23 /-*/
24 
25 #ifndef YTable_h
26 #define YTable_h
27 
28 #include "YTypes.h"
29 #include "YSelectionWidget.h"
30 #include "YTableItem.h"
31 #include "YTableHeader.h"
32 
33 class YTablePrivate;
34 
35 
36 
37 /**
38  * Table: Selection list with multiple columns. The user can select exactly one
39  * row (with all its columns) from that list. Each cell (each column within
40  * each row) has a label text, an optional icon (*) and an optional sort-key
41  * (used instead of the label text during sort).
42  *
43  * This widget is similar to SelectionBox, but it has several columns for each
44  * item (each row). If just one column is desired, consider using SelectionBox
45  * instead.
46  *
47  * Note: This is not something like a spread sheet, and it doesn't pretend or
48  * want to be. Actions are performed on rows, not on individual cells (columns
49  * within one row).
50  *
51  *
52  * (*) Not all UIs (in particular not text-based UIs) support displaying icons,
53  * so an icon should never be an exclusive means to display any kind of
54  * information.
55  **/
56 class YTable : public YSelectionWidget
57 {
58 protected:
59  /**
60  * Constructor.
61  *
62  * 'header' describes the table's headers: Number of columns, column
63  * headings, and column alignment. The widget assumes ownership of this
64  * object and will delete it when appropriate. The header cannot be changed
65  * after creating the widget.
66  *
67  * 'multiSelection' indicates whether or not the user can select multiple
68  * items at the same time (e.g., with shift-click or ctrl-click). This can
69  * only be set in the constructor.
70  **/
71  YTable( YWidget * parent, YTableHeader * header, bool multiSelection );
72 
73 public:
74 
75  /**
76  * Destructor.
77  **/
78  virtual ~YTable();
79 
80  /**
81  * Return a descriptive name of this widget class for logging,
82  * debugging etc.
83  **/
84  virtual const char * widgetClass() const { return "YTable"; }
85 
86  /**
87  * Return the number of columns of this table.
88  **/
89  int columns() const;
90 
91  /**
92  * Return 'true' if this table has a column no. 'column'
93  * (counting from 0 on).
94  **/
95  bool hasColumn( int column ) const;
96 
97  /**
98  * Return the header text for the specified column.
99  **/
100  std::string header( int column ) const;
101 
102  /**
103  * Return the alignment for the specified column.
104  **/
105  YAlignmentType alignment( int column ) const;
106 
107  /**
108  * Deliver even more events than with notify() set.
109  *
110  * With "notify" alone, a table widget sends an ActivatedEvent when the
111  * user double-clicks an item or presses the "space" key on it. It does
112  * not send an event when the user just sends another item.
113  *
114  * With "immediate", it also sends a SelectionChangedEvent when the user
115  * selects another item. "immediate" implicitly includes "notify".
116  **/
117  bool immediateMode() const;
118 
119  /**
120  * Set immediateMode() on or off.
121  **/
122  void setImmediateMode( bool immediateMode = true );
123 
124  /**
125  * Return 'true' if the sort order is to be kept in item insertion order,
126  * i.e. if sorting the table by clicking on a column header should be
127  * disabled.
128  **/
129  bool keepSorting() const;
130 
131  /**
132  * Switch between sorting by item insertion order (keepSorting: true) or
133  * allowing the user to sort by an arbitrary column (by clicking on the
134  * column header).
135  *
136  * Derived classes can overwrite this function, but they should call this
137  * base class function in the new implementation.
138  **/
139  virtual void setKeepSorting( bool keepSorting );
140 
141  /**
142  * Return 'true' if the user can select multiple items at the same time
143  * (e.g., with shift-click or ctrl-click).
144  **/
145  bool hasMultiSelection() const;
146 
147  /**
148  * Try to find an item with label 'wantedItemLabel' in column 'column'
149  * between iterators 'begin' and 'end'. Return that item or 0 if there is
150  * none.
151  **/
152 
153  YItem * findItem( const std::string & wantedItemLabel, int column ) const;
154 
155  YItem * findItem( const std::string & wantedItemLabel,
156  int column,
158  YItemConstIterator end ) const;
159 
160  /**
161  * Notification that a cell (its text, its icon and/or sort-key) was
162  * changed from the outside. Applications are required to call this
163  * whenever a table cell is changed after adding the corresponding table
164  * item (the row) to the table widget.
165  *
166  * Derived classes are required to implement this and update the display
167  * accordingly.
168  *
169  * Note that the position of this cell can be retrieved with cell->column()
170  * and cell->itemIndex().
171  **/
172  virtual void cellChanged( const YTableCell * cell ) = 0;
173 
174  /**
175  * Set a property.
176  * Reimplemented from YWidget.
177  *
178  * This function may throw YUIPropertyExceptions.
179  *
180  * This function returns 'true' if the value was successfully set and
181  * 'false' if that value requires special handling (not in error cases:
182  * those are covered by exceptions).
183  **/
184  virtual bool setProperty( const std::string & propertyName,
185  const YPropertyValue & val );
186 
187  /**
188  * Get a property.
189  * Reimplemented from YWidget.
190  *
191  * This method may throw YUIPropertyExceptions.
192  **/
193  virtual YPropertyValue getProperty( const std::string & propertyName );
194 
195  /**
196  * Return this class's property set.
197  * This also initializes the property upon the first call.
198  *
199  * Reimplemented from YWidget.
200  **/
201  virtual const YPropertySet & propertySet();
202 
203 
204  /**
205  * The name of the widget property that will return user input.
206  * Inherited from YWidget.
207  **/
208  const char * userInputProperty() { return YUIProperty_CurrentItem; }
209 
210 
211 protected:
212 
213  /**
214  * Exchange the previous table header with a new one. This will delete the
215  * old YTableHeader object.
216  *
217  * If the new header has a different number of columns than the old one,
218  * all items will implicitly be deleted.
219  **/
220  void setTableHeader( YTableHeader * newHeader );
221 
222 private:
223 
225 };
226 
227 
228 #endif // YTable_h
YWidget::parent
YWidget * parent() const
Return this widget's parent or 0 if it doesn't have a parent.
Definition: YWidget.cc:271
YTable::setProperty
virtual bool setProperty(const std::string &propertyName, const YPropertyValue &val)
Set a property.
Definition: YTable.cc:214
YTable::findItem
YItem * findItem(const std::string &wantedItemLabel, int column) const
Try to find an item with label 'wantedItemLabel' in column 'column' between iterators 'begin' and 'en...
Definition: YTable.cc:152
YWidget
Abstract base class of all UI widgets.
Definition: YWidget.h:54
YSelectionWidget
Base class for various kinds of multi-value widgets.
Definition: YSelectionWidget.h:42
YWidget::end
YWidgetListIterator end()
A helper for the range-based "for" loop.
Definition: YWidget.h:245
YTablePrivate
Definition: YTable.cc:35
YTable::userInputProperty
const char * userInputProperty()
The name of the widget property that will return user input.
Definition: YTable.h:208
YTable::columns
int columns() const
Return the number of columns of this table.
Definition: YTable.cc:87
YTable::setImmediateMode
void setImmediateMode(bool immediateMode=true)
Set immediateMode() on or off.
Definition: YTable.cc:122
YTable::getProperty
virtual YPropertyValue getProperty(const std::string &propertyName)
Get a property.
Definition: YTable.cc:235
YPropertySet
A set of properties to check names and types against.
Definition: YProperty.h:197
YWidget::begin
YWidgetListIterator begin()
A helper for the range-based "for" loop.
Definition: YWidget.h:238
YTable::propertySet
virtual const YPropertySet & propertySet()
Return this class's property set.
Definition: YTable.cc:179
YTable::keepSorting
bool keepSorting() const
Return 'true' if the sort order is to be kept in item insertion order, i.e.
Definition: YTable.cc:132
YTable
Table: Selection list with multiple columns.
Definition: YTable.h:56
ImplPtr< YTablePrivate >
YTableItem.h
YTable::setTableHeader
void setTableHeader(YTableHeader *newHeader)
Exchange the previous table header with a new one.
Definition: YTable.cc:74
YTable::YTable
YTable(YWidget *parent, YTableHeader *header, bool multiSelection)
Constructor.
Definition: YTable.cc:52
YTable::setKeepSorting
virtual void setKeepSorting(bool keepSorting)
Switch between sorting by item insertion order (keepSorting: true) or allowing the user to sort by an...
Definition: YTable.cc:139
YTable::widgetClass
virtual const char * widgetClass() const
Return a descriptive name of this widget class for logging, debugging etc.
Definition: YTable.h:84
YTable::hasColumn
bool hasColumn(int column) const
Return 'true' if this table has a column no.
Definition: YTable.cc:94
YTable::header
std::string header(int column) const
Return the header text for the specified column.
Definition: YTable.cc:101
YPropertyValue
Transport class for the value of simple properties.
Definition: YProperty.h:104
YTable::immediateMode
bool immediateMode() const
Deliver even more events than with notify() set.
Definition: YTable.cc:115
YTable::hasMultiSelection
bool hasMultiSelection() const
Return 'true' if the user can select multiple items at the same time (e.g., with shift-click or ctrl-...
Definition: YTable.cc:146
YTableCell
One cell (one column in one row) of a YTableItem.
Definition: YTableItem.h:219
YTable::~YTable
virtual ~YTable()
Destructor.
Definition: YTable.cc:66
YTable::alignment
YAlignmentType alignment(int column) const
Return the alignment for the specified column.
Definition: YTable.cc:108
YTypes.h
YTableHeader
Helper class for YTable for table column properties:
Definition: YTableHeader.h:43
YItemConstIterator
YItemCollection::const_iterator YItemConstIterator
Const iterator over YItemCollection.
Definition: YItem.h:42
YTable::cellChanged
virtual void cellChanged(const YTableCell *cell)=0
Notification that a cell (its text, its icon and/or sort-key) was changed from the outside.
YItem
Simple item class for SelectionBox, ComboBox, MultiSelectionBox etc.
Definition: YItem.h:49