libyui  3.3.1
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 and an optional icon (*).
41  *
42  * This widget is similar to SelectionBox, but it has several columns for each
43  * item (each row). If just one column is desired, consider using SelectionBox
44  * instead.
45  *
46  * Note: This is not something like a spread sheet, and it doesn't pretend or
47  * want to be. Actions are performed on rows, not on individual cells (columns
48  * within one row).
49  *
50  *
51  * (*) Not all UIs (in particular not text-based UIs) support displaying icons,
52  * so an icon should never be an exclusive means to display any kind of
53  * information.
54  **/
55 class YTable : public YSelectionWidget
56 {
57 protected:
58  /**
59  * Constructor.
60  *
61  * 'header' describes the table's headers: Number of columns, column
62  * headings, and column alignment. The widget assumes ownership of this
63  * object and will delete it when appropriate. The header cannot be changed
64  * after creating the widget.
65  *
66  * 'multiSelection' indicates whether or not the user can select multiple
67  * items at the same time (e.g., with shift-click or ctrl-click). This can
68  * only be set in the constructor.
69  **/
70  YTable( YWidget * parent, YTableHeader * header, bool multiSelection );
71 
72 public:
73 
74  /**
75  * Destructor.
76  **/
77  virtual ~YTable();
78 
79  /**
80  * Return a descriptive name of this widget class for logging,
81  * debugging etc.
82  **/
83  virtual const char * widgetClass() const { return "YTable"; }
84 
85  /**
86  * Return the number of columns of this table.
87  **/
88  int columns() const;
89 
90  /**
91  * Return 'true' if this table has a column no. 'column'
92  * (counting from 0 on).
93  **/
94  bool hasColumn( int column ) const;
95 
96  /**
97  * Return the header text for the specified column.
98  **/
99  std::string header( int column ) const;
100 
101  /**
102  * Return the alignment for the specified column.
103  **/
104  YAlignmentType alignment( int column ) const;
105 
106  /**
107  * Deliver even more events than with notify() set.
108  *
109  * With "notify" alone, a table widget sends an ActivatedEvent when the
110  * user double-clicks an item or presses the "space" key on it. It does
111  * not send an event when the user just sends another item.
112  *
113  * With "immediate", it also sends a SelectionChangedEvent when the user
114  * selects another item. "immediate" implicitly includes "notify".
115  **/
116  bool immediateMode() const;
117 
118  /**
119  * Set immediateMode() on or off.
120  **/
121  void setImmediateMode( bool immediateMode = true );
122 
123  /**
124  * Return 'true' if the sort order is to be kept in item insertion order,
125  * i.e. if sorting the table by clicking on a column header should be
126  * disabled.
127  **/
128  bool keepSorting() const;
129 
130  /**
131  * Switch between sorting by item insertion order (keepSorting: true) or
132  * allowing the user to sort by an arbitrary column (by clicking on the
133  * column header).
134  *
135  * Derived classes can overwrite this function, but they should call this
136  * base class function in the new implementation.
137  **/
138  virtual void setKeepSorting( bool keepSorting );
139 
140  /**
141  * Return 'true' if the user can select multiple items at the same time
142  * (e.g., with shift-click or ctrl-click).
143  **/
144  bool hasMultiSelection() const;
145 
146  /**
147  * Notification that a cell (its text and/or its icon) was changed from the
148  * outside. Applications are required to call this whenever a table cell is
149  * changed after adding the corresponding table item (the row) to the table
150  * widget.
151  *
152  * Derived classes are required to implement this and update the display
153  * accordingly.
154  *
155  * Note that the position of this cell can be retrieved with cell->column()
156  * and cell->itemIndex().
157  **/
158  virtual void cellChanged( const YTableCell * cell ) = 0;
159 
160  /**
161  * Set a property.
162  * Reimplemented from YWidget.
163  *
164  * This function may throw YUIPropertyExceptions.
165  *
166  * This function returns 'true' if the value was successfully set and
167  * 'false' if that value requires special handling (not in error cases:
168  * those are covered by exceptions).
169  **/
170  virtual bool setProperty( const std::string & propertyName,
171  const YPropertyValue & val );
172 
173  /**
174  * Get a property.
175  * Reimplemented from YWidget.
176  *
177  * This method may throw YUIPropertyExceptions.
178  **/
179  virtual YPropertyValue getProperty( const std::string & propertyName );
180 
181  /**
182  * Return this class's property set.
183  * This also initializes the property upon the first call.
184  *
185  * Reimplemented from YWidget.
186  **/
187  virtual const YPropertySet & propertySet();
188 
189 
190  /**
191  * The name of the widget property that will return user input.
192  * Inherited from YWidget.
193  **/
194  const char * userInputProperty() { return YUIProperty_CurrentItem; }
195 
196 
197 protected:
198 
199  /**
200  * Exchange the previous table header with a new one. This will delete the
201  * old YTableHeader object.
202  *
203  * If the new header has a different number of columns than the old one,
204  * all items will implicitly be deleted.
205  **/
206  void setTableHeader( YTableHeader * newHeader );
207 
208 private:
209 
211 };
212 
213 
214 #endif // YTable_h
int columns() const
Return the number of columns of this table.
Definition: YTable.cc:85
YAlignmentType alignment(int column) const
Return the alignment for the specified column.
Definition: YTable.cc:106
Author: Stefan Hundhammer sh@suse.de
YTable(YWidget *parent, YTableHeader *header, bool multiSelection)
Constructor.
Definition: YTable.cc:50
virtual const char * widgetClass() const
Return a descriptive name of this widget class for logging, debugging etc.
Definition: YTable.h:83
virtual void cellChanged(const YTableCell *cell)=0
Notification that a cell (its text and/or its icon) was changed from the outside. ...
Transport class for the value of simple properties.
Definition: YProperty.h:104
bool hasMultiSelection() const
Return &#39;true&#39; if the user can select multiple items at the same time (e.g., with shift-click or ctrl-...
Definition: YTable.cc:144
Base class for various kinds of multi-value widgets.
Helper class for YTable for table column properties:
Definition: YTableHeader.h:43
A set of properties to check names and types against.
Definition: YProperty.h:197
void setImmediateMode(bool immediateMode=true)
Set immediateMode() on or off.
Definition: YTable.cc:120
YWidget * parent() const
Return this widget&#39;s parent or 0 if it doesn&#39;t have a parent.
Definition: YWidget.cc:269
virtual YPropertyValue getProperty(const std::string &propertyName)
Get a property.
Definition: YTable.cc:207
One cell (one column in one row) of a YTableItem.
Definition: YTableItem.h:218
Table: Selection list with multiple columns.
Definition: YTable.h:55
virtual const YPropertySet & propertySet()
Return this class&#39;s property set.
Definition: YTable.cc:151
virtual ~YTable()
Destructor.
Definition: YTable.cc:64
virtual bool setProperty(const std::string &propertyName, const YPropertyValue &val)
Set a property.
Definition: YTable.cc:186
std::string header(int column) const
Return the header text for the specified column.
Definition: YTable.cc:99
bool immediateMode() const
Deliver even more events than with notify() set.
Definition: YTable.cc:113
void setTableHeader(YTableHeader *newHeader)
Exchange the previous table header with a new one.
Definition: YTable.cc:72
const char * userInputProperty()
The name of the widget property that will return user input.
Definition: YTable.h:194
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:137
bool keepSorting() const
Return &#39;true&#39; if the sort order is to be kept in item insertion order, i.e.
Definition: YTable.cc:130
bool hasColumn(int column) const
Return &#39;true&#39; if this table has a column no.
Definition: YTable.cc:92
Abstract base class of all UI widgets.
Definition: YWidget.h:54