libyui-mga  1.0.7
YMGA_CBTable.h
1 /*
2  Copyright 2013 by Angelo Naselli <anaselli at linux dot it>
3 
4  This library is free software; you can redistribute it and/or modify
5  it under the terms of the GNU Lesser General Public License as
6  published by the Free Software Foundation; either version 2.1 of the
7  License, or (at your option) version 3.0 of the License. This library
8  is distributed in the hope that it will be useful, but WITHOUT ANY
9  WARRANTY; without even the implied warranty of MERCHANTABILITY or
10  FITNESS FOR A PARTICULAR PURPOSE. See the GNU Lesser General Public
11  License for more details. You should have received a copy of the GNU
12  Lesser General Public License along with this library; if not, write
13  to the Free Software Foundation, Inc., 51 Franklin Street, Fifth
14  Floor, Boston, MA 02110-1301 USA
15 */
16 
17 
18 /*-/
19 
20  File: YMGA_CBTable.h
21 
22  Author: Angelo Naselli <anaselli@linux.it>
23 
24 /-*/
25 
26 
27 #ifndef YMGA_CBTable_h
28 #define YMGA_CBTable_h
29 
30 #include <yui/YTable.h>
31 #include <yui/YTypes.h>
32 #include <yui/YSelectionWidget.h>
33 #include <yui/YTableItem.h>
34 #include <yui/YTableHeader.h>
35 #include <yui/YEvent.h>
36 
37 enum YCBTableMode {
38  YCBTableCheckBoxOnFirstColumn=2, //back compatible
39  YCBTableCheckBoxOnLastColumn
40  };
41 
42 
43 class YCBTableItem : public YTableItem
44 {
45 public:
46  /**
47  * Default constructor. Use addCell() to give it any content.
48  **/
49  YCBTableItem() : YTableItem(), _checked(false) {}
50 
51  /**
52  * Convenience constructor for table items without any icons.
53  *
54  * This will create up to 10 (0..9) cells. Empty cells for empty labels at
55  * the end of the labels are not created, but empty cells in between are.
56  *
57  * new YCBTableItem( "one", "two", "", "", "five" );
58  *
59  * will create an item with 5 cells:
60  *
61  * cell[0] ==> "one"
62  * cell[1] ==> "two"
63  * cell[2] ==> ""
64  * cell[3] ==> ""
65  * cell[4] ==> "five"
66  **/
67  YCBTableItem( const std::string & label_0,
68  const std::string & label_1 = std::string(),
69  const std::string & label_2 = std::string(),
70  const std::string & label_3 = std::string(),
71  const std::string & label_4 = std::string(),
72  const std::string & label_5 = std::string(),
73  const std::string & label_6 = std::string(),
74  const std::string & label_7 = std::string(),
75  const std::string & label_8 = std::string(),
76  const std::string & label_9 = std::string() ) :
77  YTableItem(label_0, label_1, label_2, label_3,
78  label_4, label_5, label_6, label_7,
79  label_8, label_9), _checked(false) {}
80 
81  /**
82  * Destructor.
83  **/
84  virtual ~YCBTableItem() {}
85 
86  void check(bool val=true) {_checked=val;}
87  bool checked() {return _checked;}
88 
89 private:
90  bool _checked;
91 };
92 
94 
95 /**
96  * See document of YMGA_CBTable
97  * Table: Selection list with multiple columns. The user can select exactly one
98  * row (with all its columns) from that list. Each cell (each column within
99  * each row) has a label text and an optional icon (*).
100  *
101  * This widget is similar to SelectionBox, but it has several columns for each
102  * item (each row). If just one column is desired, consider using SelectionBox
103  * instead.
104  *
105  * Note: This is not something like a spread sheet, and it doesn't pretend or
106  * want to be. Actions are performed on rows, not on individual cells (columns
107  * within one row).
108  *
109  *
110  * (*) Not all UIs (in particular not text-based UIs) support displaying icons,
111  * so an icon should never be an exclusive means to display any kind of
112  * information.
113  **/
114 class YMGA_CBTable: public YSelectionWidget
115 {
116 protected:
117  /**
118  * Constructor.
119  *
120  * 'header' describes the table's headers: Number of columns, column
121  * headings, and column alignment. The widget assumes ownership of this
122  * object and will delete it when appropriate. The header cannot be changed
123  * after creating the widget.
124  *
125  * 'mode' indicates whether the checkbox is in the first or in the last
126  * column.
127  *
128  * header must contains also header for checkbox column (empty string is
129  * allowed if not wanted)
130  **/
131  YMGA_CBTable( YWidget * parent, YTableHeader * header, YCBTableMode mode );
132 
133 public:
134 
135  /**
136  * Destructor.
137  **/
138  virtual ~YMGA_CBTable();
139 
140  /**
141  * Return a descriptive name of this widget class for logging,
142  * debugging etc.
143  **/
144  virtual const char * widgetClass() const { return "YMGA_CBTable"; }
145 
146  /**
147  * Return the number of columns of this table.
148  **/
149  int columns() const;
150 
151  /**
152  * Return 'true' if this table has a column no. 'column'
153  * (counting from 0 on).
154  **/
155  bool hasColumn( int column ) const;
156 
157  /**
158  * Return the header text for the specified column.
159  **/
160  std::string header( int column ) const;
161 
162  /**
163  * Return the alignment for the specified column.
164  **/
165  YAlignmentType alignment( int column ) const;
166 
167  /**
168  * Deliver even more events than with notify() set.
169  *
170  * With "notify" alone, a table widget sends an ActivatedEvent when the
171  * user double-clicks an item or presses the "space" key on it. It does
172  * not send an event when the user just sends another item.
173  *
174  * With "immediate", it also sends a SelectionChangedEvent when the user
175  * selects another item. "immediate" implicitly includes "notify".
176  **/
177  bool immediateMode() const;
178 
179  /**
180  * Set immediateMode() on or off.
181  **/
182  void setImmediateMode( bool immediateMode = true );
183 
184  /**
185  * Return 'true' if the sort order is to be kept in item insertion order,
186  * i.e. if sorting the table by clicking on a column header should be
187  * disabled.
188  **/
189  bool keepSorting() const;
190 
191  /**
192  * Switch between sorting by item insertion order (keepSorting: true) or
193  * allowing the user to sort by an arbitrary column (by clicking on the
194  * column header).
195  *
196  * Derived classes can overwrite this function, but they should call this
197  * base class function in the new implementation.
198  **/
199  virtual void setKeepSorting( bool keepSorting );
200 
201  /**
202  * Return 'true' if the user can select multiple items at the same time
203  * (e.g., with shift-click or ctrl-click).
204  **/
205  bool hasMultiSelection() const;
206 
207  /**
208  * returns the YCBTable checkbox position mode
209  *
210  **/
211  YCBTableMode tableMode();
212 
213  /**
214  * Notification that a cell (its text and/or its icon) was changed from the
215  * outside. Applications are required to call this whenever a table cell is
216  * changed after adding the corresponding table item (the row) to the table
217  * widget.
218  *
219  * Derived classes are required to implement this and update the display
220  * accordingly.
221  *
222  * Note that the position of this cell can be retrieved with cell->column()
223  * and cell->itemIndex().
224  **/
225  virtual void cellChanged( const YTableCell * cell ) = 0;
226 
227  /**
228  * check/uncheck Item from application.
229  *
230  * Derived classes are required to implement this and update the display
231  * accordingly.
232  *
233  * Note that item->check(true) does not update the table
234  *
235  **/
236  virtual void checkItem( YItem * item, bool checked = true ) = 0;
237 
238  /**
239  * Set a property.
240  * Reimplemented from YWidget.
241  *
242  * This function may throw YUIPropertyExceptions.
243  *
244  * This function returns 'true' if the value was successfully set and
245  * 'false' if that value requires special handling (not in error cases:
246  * those are covered by exceptions).
247  **/
248  virtual bool setProperty( const std::string & propertyName,
249  const YPropertyValue & val );
250 
251  /**
252  * Get a property.
253  * Reimplemented from YWidget.
254  *
255  * This method may throw YUIPropertyExceptions.
256  **/
257  virtual YPropertyValue getProperty( const std::string & propertyName );
258 
259  /**
260  * Return this class's property set.
261  * This also initializes the property upon the first call.
262  *
263  * Reimplemented from YWidget.
264  **/
265  virtual const YPropertySet & propertySet();
266 
267 
268  /**
269  * The name of the widget property that will return user input.
270  * Inherited from YWidget.
271  **/
272  const char * userInputProperty() { return YUIProperty_CurrentItem; }
273 
274  /**
275  * Add one item. This widget assumes ownership of the item object and will
276  * delete it in its destructor.
277  *
278  * NOTE: For tree items, call this only for the toplevel items; all
279  * non-toplevel items are already owned by their respective parent
280  * items. Adding them to the parent widget will clash with this ownership.
281  *
282  * Reimplementation of YSelectionWidget::addItem.
283  **/
284  virtual void addItem( YItem * item_disown );
285 
286  /**
287  * Exchange the previous table header with a new one. This will delete the
288  * old YTableHeader object.
289  *
290  * If the new header has a different number of columns than the old one,
291  * all items will implicitly be deleted.
292  **/
293  void setTableHeader( YTableHeader * newHeader );
294 
295  /**
296  * From YSelectionWidget returns the item at index 'index' (from 0)
297  * or 0 if there is no such item.
298  **/
299  virtual YItem* item(int index ) const;
300 
301  /**
302  * When derived classes emit YWidgetEvent with reason ValueChanged
303  * they have to set which item is changed. Who manages the event
304  * have to use changedItem() to get it.
305  *
306  * Derived classes can overwrite this function, but they should call this
307  * base class function in the new implementation.
308  */
309  virtual void setChangedItem( YCBTableItem* pItem );
310 
311  /**
312  * Return the item which value is changed (e.g. checkbox).
313  **/
314  virtual YCBTableItem * changedItem();
315 
316  // yui bindings problem workarounds:
317  /**
318  * YSelectionWidget does not implement the increment of iterator
319  * and bindings seem not to work with iterator++, next function
320  * just returns the iterator icrementation, NOTE that it does not check
321  * input parameter, just increment it.
322  */
323  YItemIterator nextItem( YItemIterator currentIterator);
324 
325  /**
326  * Delete all items.
327  *
328  **/
329  virtual void deleteAllItems();
330 
331  /**
332  * useful cast for bindings.
333  * it does not any assunption on iter, so it is up to the user to
334  * check if it is valid, it just returns *it.
335  */
336  YItem* YItemIteratorToYItem(YItemIterator iter);
337 
338  /**
339  * useful cast for bindings.
340  * it just performs a dynamic_cast
341  */
342  YCBTableItem* toCBYTableItem( YItem* item );
343 
344 private:
345 
346  ImplPtr<YMGA_CBTablePrivate> priv;
347 };
348 
349 
350 #endif // YMGA_CBTable_h
const char * userInputProperty()
The name of the widget property that will return user input.
Definition: YMGA_CBTable.h:272
See document of YMGA_CBTable Table: Selection list with multiple columns.
Definition: YMGA_CBTable.h:114
virtual const char * widgetClass() const
Return a descriptive name of this widget class for logging, debugging etc.
Definition: YMGA_CBTable.h:144
virtual ~YCBTableItem()
Destructor.
Definition: YMGA_CBTable.h:84
YCBTableItem()
Default constructor.
Definition: YMGA_CBTable.h:49
YCBTableItem(const std::string &label_0, const std::string &label_1=std::string(), const std::string &label_2=std::string(), const std::string &label_3=std::string(), const std::string &label_4=std::string(), const std::string &label_5=std::string(), const std::string &label_6=std::string(), const std::string &label_7=std::string(), const std::string &label_8=std::string(), const std::string &label_9=std::string())
Convenience constructor for table items without any icons.
Definition: YMGA_CBTable.h:67