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