libyui  3.0.5
 All Classes Functions Variables Enumerations Friends
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