libyui  2.42.5
 All Classes Functions Variables Enumerations Friends
YTableItem.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: YTableItem.h
20 
21  Author: Stefan Hundhammer <sh@suse.de>
22 
23 /-*/
24 
25 #ifndef YTableItem_h
26 #define YTableItem_h
27 
28 #include "YItem.h"
29 
30 
31 class YTableCell;
32 
33 typedef std::vector<YTableCell *> YTableCellCollection;
34 typedef YTableCellCollection::iterator YTableCellIterator;
35 typedef YTableCellCollection::const_iterator YTableCellConstIterator;
36 
37 
38 /**
39  * Item class for YTable items. Each YTableItem corresponds to one row in a
40  * YTable.
41  *
42  * A YTableItem might have any number of cells (columns within this row),
43  * including none. The YTable widget is free to ignore any excess cells if
44  * there are more than the YTable widget has columns. The YTable widget is to
45  * treat nonexistent cells like empty ones.
46  *
47  * Note that while YTable items and their cells can be manipulated through
48  * pointers, their visual representation on screen might be updated only upon
49  * calling certain methods of the YTable widget. See the YTable reference for
50  * details.
51  **/
52 class YTableItem: public YItem
53 {
54 public:
55 
56  /**
57  * Default constructor. Use addCell() to give it any content.
58  **/
59  YTableItem();
60 
61  /**
62  * Convenience constructor for table items without any icons.
63  *
64  * This will create up to 10 (0..9) cells. Empty cells for empty labels at
65  * the end of the labels are not created, but empty cells in between are.
66  *
67  * new YTableItem( "one", "two", "", "", "five" );
68  *
69  * will create an item with 5 cells:
70  *
71  * cell[0] ==> "one"
72  * cell[1] ==> "two"
73  * cell[2] ==> ""
74  * cell[3] ==> ""
75  * cell[4] ==> "five"
76  **/
77  YTableItem( const std::string & label_0,
78  const std::string & label_1 = std::string(),
79  const std::string & label_2 = std::string(),
80  const std::string & label_3 = std::string(),
81  const std::string & label_4 = std::string(),
82  const std::string & label_5 = std::string(),
83  const std::string & label_6 = std::string(),
84  const std::string & label_7 = std::string(),
85  const std::string & label_8 = std::string(),
86  const std::string & label_9 = std::string() );
87 
88  /**
89  * Destructor.
90  *
91  * This will delete all cells.
92  **/
93  virtual ~YTableItem();
94 
95  /**
96  * Add a cell. This item will assume ownership over the cell and delete it
97  * when appropriate (when the table is destroyed or when table items are
98  * replaced), at which time the pointer will become invalid.
99  *
100  * Cells can still be changed after they (and the item they belong to) are
101  * added, but in that case, YTable::cellChanged() needs to be called to
102  * update the table display accordingly.
103  **/
104  void addCell( YTableCell * cell_disown );
105 
106  /**
107  * Create a new cell and add it (even if both 'label' and
108  * 'iconName' are empty).
109  **/
110  void addCell( const std::string & label, const std::string & iconName = std::string() );
111 
112  /**
113  * Delete all cells.
114  **/
115  void deleteCells();
116 
117  /**
118  * Return an iterator that points to the first cell of this item.
119  **/
120  YTableCellIterator cellsBegin() { return _cells.begin(); }
121  YTableCellConstIterator cellsBegin() const { return _cells.begin(); }
122 
123  /**
124  * Return an iterator that points after the last cell of this item.
125  **/
126  YTableCellIterator cellsEnd() { return _cells.end(); }
127  YTableCellConstIterator cellsEnd() const { return _cells.end(); }
128 
129  /**
130  * Return the cell at the specified index (counting from 0 on)
131  * or 0 if there is none.
132  **/
133  const YTableCell * cell( int index ) const;
134  YTableCell * cell( int index );
135 
136  /**
137  * Return the number of cells this item has.
138  **/
139  int cellCount() const { return _cells.size(); }
140 
141  /**
142  * Return 'true' if this item has a cell with the specified index
143  * (counting from 0 on), 'false' otherwise.
144  **/
145  bool hasCell( int index ) const;
146 
147  /**
148  * Return the label of cell no. 'index' (counting from 0 on) or an empty
149  * string if there is no cell with that index.
150  **/
151  std::string label( int index ) const;
152 
153  /**
154  * Return the icon name of cell no. 'index' (counting from 0 on) or an empty
155  * string if there is no cell with that index.
156  **/
157  std::string iconName( int index ) const;
158 
159  /**
160  * Return 'true' if there is a cell with the specified index that has an
161  * icon name.
162  **/
163  bool hasIconName( int index ) const;
164 
165  /**
166  * Just for debugging.
167  **/
168  std::string label() const { return label(0); }
169 
170 private:
171 
172  // Disable unwanted base class methods. They don't make sense in this
173  // context since there is not just one single label or icon name, but one
174  // for each cell.
175 
176  std::string iconName() const { return ""; }
177  bool hasIconName() const { return false; }
178  void setLabel ( const std::string & ) {}
179  void setIconName ( const std::string & ) {}
180 
181 
182  //
183  // Data members
184  //
185 
186  YTableCellCollection _cells;
187 };
188 
189 
190 
191 /**
192  * One cell (one column in one row) of a YTableItem. Each cell has a label (a
193  * user visible text) and optionally an icon (*).
194  *
195  * Note that cells don't have individual IDs; they have just an index.
196  * The first cell in an item is cell(0). In an ideal world, each YTableItem
197  * would have exactly as many cells as there are columns in the YTable, but
198  * these classes make no such assumptions. A YTableItem might have any number
199  * of cells, including none.
200  *
201  * The YTable widget is free to ignore any excess cells if there are more than
202  * the YTable widget has columns. If there are less cells than the table has
203  * columns, the nonexistent cells will be treated as empty.
204  *
205  *
206  * (*) Not all UIs can handle icons. UIs that can't handle them will simply
207  * ignore any icons specified for YTableCells. Thus, applications should either
208  * check the UI capabilities if it can handle icons or use icons only as an
209  * additional visual cue that still has a text counterpart (so the user can
210  * still make sense of the table content when no icons are visible).
211  **/
213 {
214 public:
215  /**
216  * Constructor with label and optional icon name for cells that don't have
217  * a parent item yet (that will be added to a parent later with
218  * setParent()).
219  **/
220  YTableCell( const std::string & label, const std::string & iconName = "" )
221  : _label( label )
222  , _iconName( iconName )
223  , _parent( 0 )
224  , _column ( -1 )
225  {}
226 
227  /**
228  * Constructor with parent, column no., label and optional icon name for
229  * cells that are created with a parent.
230  **/
232  int column,
233  const std::string & label,
234  const std::string & iconName = "" )
235  : _label( label )
236  , _iconName( iconName )
237  , _parent( parent )
238  , _column ( column )
239  {}
240 
241  /**
242  * Destructor. Not strictly needed inside this class, but useful for
243  * derived classes. Since this is the only virtual method of this class,
244  * the cost of this is a vtable for this class and a pointer to the vtable
245  * in each instance.
246  **/
247  virtual ~YTableCell() {}
248 
249  /**
250  * Return this cells's label. This is what the user sees in a dialog, so
251  * this will usually be a translated text.
252  **/
253  std::string label() const { return _label; }
254 
255  /**
256  * Set this cell's label.
257  *
258  * If this is called after the corresponding table item (table row) is
259  * added to the table widget, call YTable::cellChanged() to notify the
260  * table widget about the fact. Only then will the display be updated.
261  **/
262  void setLabel( const std::string & newLabel ) { _label = newLabel; }
263 
264  /**
265  * Return this cell's icon name.
266  **/
267  std::string iconName() const { return _iconName; }
268 
269  /**
270  * Return 'true' if this cell has an icon name.
271  **/
272  bool hasIconName() const { return ! _iconName.empty(); }
273 
274  /**
275  * Set this cell's icon name.
276  *
277  * If this is called after the corresponding table item (table row) is
278  * added to the table widget, call YTable::cellChanged() to notify the
279  * table widget about the fact. Only then will the display be updated.
280  **/
281  void setIconName( const std::string & newIconName ) { _iconName = newIconName; }
282 
283  /**
284  * Return this cell's parent item or 0 if it doesn't have one yet.
285  **/
286  YTableItem * parent() const { return _parent; }
287 
288  /**
289  * Return this cell's column no. (counting from 0on) or -1 if it doesn't
290  * have a parent yet.
291  **/
292  int column() const { return _column; }
293 
294  /**
295  * Convenience function: Return this cell's parent item's index within its
296  * table widget or -1 if there is no parent item or no parent table.
297  **/
298  int itemIndex() const { return _parent ? _parent->index() : -1; }
299 
300  /**
301  * Set this cell's parent item and column no. if it doesn't have a parent
302  * yet.
303  *
304  * This method will throw an exception if the cell already has a parent.
305  **/
306  void reparent( YTableItem * parent, int column );
307 
308 
309 private:
310 
311  std::string _label;
312  std::string _iconName;
313  YTableItem * _parent;
314  int _column;
315 };
316 
317 
318 
319  #endif // YTableItem_h