libyui-mga  1.0.4
 All Classes Functions Enumerations Enumerator
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  * useful cast for bindings.
327  * it does not any assunption on iter, so it is up to the user to
328  * check if it is valid, it just returns *it.
329  */
330  YItem* YItemIteratorToYItem(YItemIterator iter);
331 
332  /**
333  * useful cast for bindings.
334  * it just performs a dynamic_cast
335  */
336  YCBTableItem* toCBYTableItem( YItem* item );
337 
338 private:
339 
340  ImplPtr<YMGA_CBTablePrivate> priv;
341 };
342 
343 
344 #endif // YMGA_CBTable_h
virtual void setKeepSorting(bool keepSorting)
Switch between sorting by item insertion order (keepSorting: true) or allowing the user to sort by an...
YCBTableItem * toCBYTableItem(YItem *item)
useful cast for bindings.
virtual const YPropertySet & propertySet()
Return this class's property set.
YMGA_CBTable(YWidget *parent, YTableHeader *header, YCBTableMode mode)
Constructor.
Definition: YMGA_CBTable.cc:55
YCBTableMode tableMode()
returns the YCBTable checkbox position mode
Definition: YMGA_CBTable.cc:86
virtual void setChangedItem(YCBTableItem *pItem)
When derived classes emit YWidgetEvent with reason ValueChanged they have to set which item is change...
Definition: YMGA_CBTable.cc:80
const char * userInputProperty()
The name of the widget property that will return user input.
Definition: YMGA_CBTable.h:272
virtual void cellChanged(const YTableCell *cell)=0
Notification that a cell (its text and/or its icon) was changed from the outside. ...
virtual void addItem(YItem *item_disown)
Add one item.
Definition: YMGA_CBTable.cc:92
virtual const char * widgetClass() const
Return a descriptive name of this widget class for logging, debugging etc.
Definition: YMGA_CBTable.h:144
YItem * YItemIteratorToYItem(YItemIterator iter)
useful cast for bindings.
virtual void checkItem(YItem *item, bool checked=true)=0
check/uncheck Item from application.
See document of YMGA_CBTable Table: Selection list with multiple columns.
Definition: YMGA_CBTable.h:114
virtual YPropertyValue getProperty(const std::string &propertyName)
Get a property.
int columns() const
Return the number of columns of this table.
virtual ~YCBTableItem()
Destructor.
Definition: YMGA_CBTable.h:84
virtual YItem * item(int index) const
From YSelectionWidget returns the item at index 'index' (from 0) or 0 if there is no such item...
void setImmediateMode(bool immediateMode=true)
Set immediateMode() on or off.
bool hasColumn(int column) const
Return 'true' if this table has a column no.
bool immediateMode() const
Deliver even more events than with notify() set.
std::string header(int column) const
Return the header text for the specified column.
bool keepSorting() const
Return 'true' if the sort order is to be kept in item insertion order, i.e.
void setTableHeader(YTableHeader *newHeader)
Exchange the previous table header with a new one.
Definition: YMGA_CBTable.cc:99
virtual ~YMGA_CBTable()
Destructor.
Definition: YMGA_CBTable.cc:71
YItemIterator nextItem(YItemIterator currentIterator)
YSelectionWidget does not implement the increment of iterator and bindings seem not to work with iter...
YAlignmentType alignment(int column) const
Return the alignment for the specified column.
virtual bool setProperty(const std::string &propertyName, const YPropertyValue &val)
Set a property.
bool hasMultiSelection() const
Return 'true' if the user can select multiple items at the same time (e.g., with shift-click or ctrl-...
YCBTableItem()
Default constructor.
Definition: YMGA_CBTable.h:49
virtual YCBTableItem * changedItem()
Return the item which value is changed (e.g.
Definition: YMGA_CBTable.cc:75
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