libyui  3.3.1
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 both 'label' and
114  * 'iconName' are empty).
115  **/
116  void addCell( const std::string & label, const std::string & iconName = std::string() );
117 
118  /**
119  * Delete all cells.
120  **/
121  void deleteCells();
122 
123  /**
124  * Return an iterator that points to the first cell of this item.
125  **/
126  YTableCellIterator cellsBegin() { return _cells.begin(); }
127  YTableCellConstIterator cellsBegin() const { return _cells.begin(); }
128 
129  /**
130  * Return an iterator that points after the last cell of this item.
131  **/
132  YTableCellIterator cellsEnd() { return _cells.end(); }
133  YTableCellConstIterator cellsEnd() const { return _cells.end(); }
134 
135  /**
136  * Return the cell at the specified index (counting from 0 on)
137  * or 0 if there is none.
138  **/
139  const YTableCell * cell( int index ) const;
140  YTableCell * cell( int index );
141 
142  /**
143  * Return the number of cells this item has.
144  **/
145  int cellCount() const { return _cells.size(); }
146 
147  /**
148  * Return 'true' if this item has a cell with the specified index
149  * (counting from 0 on), 'false' otherwise.
150  **/
151  bool hasCell( int index ) const;
152 
153  /**
154  * Return the label 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 label( int index ) const;
158 
159  /**
160  * Return the icon name of cell no. 'index' (counting from 0 on) or an empty
161  * string if there is no cell with that index.
162  **/
163  std::string iconName( int index ) const;
164 
165  /**
166  * Return 'true' if there is a cell with the specified index that has an
167  * icon name.
168  **/
169  bool hasIconName( int index ) const;
170 
171  /**
172  * Just for debugging.
173  **/
174  std::string label() const { return label(0); }
175 
176 private:
177 
178  // Disable unwanted base class methods. They don't make sense in this
179  // context since there is not just one single label or icon name, but one
180  // for each cell.
181 
182  std::string iconName() const { return ""; }
183  bool hasIconName() const { return false; }
184  void setLabel ( const std::string & ) {}
185  void setIconName ( const std::string & ) {}
186 
187 
188  //
189  // Data members
190  //
191 
192  YTableCellCollection _cells;
193 };
194 
195 
196 
197 /**
198  * One cell (one column in one row) of a YTableItem. Each cell has a label (a
199  * user visible text) and optionally an icon (*).
200  *
201  * Note that cells don't have individual IDs; they have just an index.
202  * The first cell in an item is cell(0). In an ideal world, each YTableItem
203  * would have exactly as many cells as there are columns in the YTable, but
204  * these classes make no such assumptions. A YTableItem might have any number
205  * of cells, including none.
206  *
207  * The YTable widget is free to ignore any excess cells if there are more than
208  * the YTable widget has columns. If there are less cells than the table has
209  * columns, the nonexistent cells will be treated as empty.
210  *
211  *
212  * (*) Not all UIs can handle icons. UIs that can't handle them will simply
213  * ignore any icons specified for YTableCells. Thus, applications should either
214  * check the UI capabilities if it can handle icons or use icons only as an
215  * additional visual cue that still has a text counterpart (so the user can
216  * still make sense of the table content when no icons are visible).
217  **/
219 {
220 public:
221  /**
222  * Constructor with label and optional icon name for cells that don't have
223  * a parent item yet (that will be added to a parent later with
224  * setParent()).
225  **/
226  YTableCell( const std::string & label, const std::string & iconName = "" )
227  : _label( label )
228  , _iconName( iconName )
229  , _parent( 0 )
230  , _column ( -1 )
231  {}
232 
233  /**
234  * Constructor with parent, column no., label and optional icon name for
235  * cells that are created with a parent.
236  **/
238  int column,
239  const std::string & label,
240  const std::string & iconName = "" )
241  : _label( label )
242  , _iconName( iconName )
243  , _parent( parent )
244  , _column ( column )
245  {}
246 
247  /**
248  * Destructor. Not strictly needed inside this class, but useful for
249  * derived classes. Since this is the only virtual method of this class,
250  * the cost of this is a vtable for this class and a pointer to the vtable
251  * in each instance.
252  **/
253  virtual ~YTableCell() {}
254 
255  /**
256  * Return this cells's label. This is what the user sees in a dialog, so
257  * this will usually be a translated text.
258  **/
259  std::string label() const { return _label; }
260 
261  /**
262  * Set this cell's label.
263  *
264  * If this is called after the corresponding table item (table row) is
265  * added to the table widget, call YTable::cellChanged() to notify the
266  * table widget about the fact. Only then will the display be updated.
267  **/
268  void setLabel( const std::string & newLabel ) { _label = newLabel; }
269 
270  /**
271  * Return this cell's icon name.
272  **/
273  std::string iconName() const { return _iconName; }
274 
275  /**
276  * Return 'true' if this cell has an icon name.
277  **/
278  bool hasIconName() const { return ! _iconName.empty(); }
279 
280  /**
281  * Set this cell's icon name.
282  *
283  * If this is called after the corresponding table item (table row) is
284  * added to the table widget, call YTable::cellChanged() to notify the
285  * table widget about the fact. Only then will the display be updated.
286  **/
287  void setIconName( const std::string & newIconName ) { _iconName = newIconName; }
288 
289  /**
290  * Return this cell's parent item or 0 if it doesn't have one yet.
291  **/
292  YTableItem * parent() const { return _parent; }
293 
294  /**
295  * Return this cell's column no. (counting from 0on) or -1 if it doesn't
296  * have a parent yet.
297  **/
298  int column() const { return _column; }
299 
300  /**
301  * Convenience function: Return this cell's parent item's index within its
302  * table widget or -1 if there is no parent item or no parent table.
303  **/
304  int itemIndex() const { return _parent ? _parent->index() : -1; }
305 
306  /**
307  * Set this cell's parent item and column no. if it doesn't have a parent
308  * yet.
309  *
310  * This method will throw an exception if the cell already has a parent.
311  **/
312  void reparent( YTableItem * parent, int column );
313 
314 
315 private:
316 
317  std::string _label;
318  std::string _iconName;
319  YTableItem * _parent;
320  int _column;
321 };
322 
323 
324 
325  #endif // YTableItem_h
std::string label() const
Just for debugging.
Definition: YTableItem.h:174
void deleteCells()
Delete all cells.
Definition: YTableItem.cc:89
std::string iconName(int index) const
Return the icon name of cell no.
Definition: YTableItem.cc:155
void setLabel(const std::string &newLabel)
Set this cell&#39;s label.
Definition: YTableItem.h:268
bool hasIconName() const
Return &#39;true&#39; if this cell has an icon name.
Definition: YTableItem.h:278
void addCell(YTableCell *cell_disown)
Add a cell.
Definition: YTableItem.cc:105
bool hasCell(int index) const
Return &#39;true&#39; if this item has a cell with the specified index (counting from 0 on), &#39;false&#39; otherwise.
Definition: YTableItem.cc:125
YTableCell(YTableItem *parent, int column, const std::string &label, const std::string &iconName="")
Constructor with parent, column no., label and optional icon name for cells that are created with a p...
Definition: YTableItem.h:237
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:132
virtual ~YTableItem()
Destructor.
Definition: YTableItem.cc:82
virtual ~YTableCell()
Destructor.
Definition: YTableItem.h:253
One cell (one column in one row) of a YTableItem.
Definition: YTableItem.h:218
int index() const
Return the index of this item (as set with setIndex() ).
Definition: YItem.h:124
YTableCellCollection::iterator YTableCellIterator
Mutable iterator over YTableCellCollection.
Definition: YTableItem.h:39
virtual YItem * parent() const
Returns this item&#39;s parent item or 0 if it is a toplevel item.
Definition: YItem.h:189
YTableCellCollection::const_iterator YTableCellConstIterator
Const iterator over YTableCellCollection.
Definition: YTableItem.h:41
std::string label() const
Return this cells&#39;s label.
Definition: YTableItem.h:259
Simple item class for SelectionBox, ComboBox, MultiSelectionBox etc.
Definition: YItem.h:49
bool hasIconName(int index) const
Return &#39;true&#39; if there is a cell with the specified index that has an icon name.
Definition: YTableItem.cc:162
int cellCount() const
Return the number of cells this item has.
Definition: YTableItem.h:145
std::vector< YTableCell * > YTableCellCollection
Collection of pointers to YTableCell.
Definition: YTableItem.h:37
int column() const
Return this cell&#39;s column no.
Definition: YTableItem.h:298
std::string iconName() const
Return this cell&#39;s icon name.
Definition: YTableItem.h:273
void setIconName(const std::string &newIconName)
Set this cell&#39;s icon name.
Definition: YTableItem.h:287
YTableItem * parent() const
Return this cell&#39;s parent item or 0 if it doesn&#39;t have one yet.
Definition: YTableItem.h:292
int itemIndex() const
Convenience function: Return this cell&#39;s parent item&#39;s index within its table widget or -1 if there i...
Definition: YTableItem.h:304
YTableCellIterator cellsEnd()
Return an iterator that points after the last cell of this item.
Definition: YTableItem.h:132
Item class for YTable items.
Definition: YTableItem.h:58
YTableItem()
Default constructor.
Definition: YTableItem.cc:29
YTableCell(const std::string &label, const std::string &iconName="")
Constructor with label and optional icon name for cells that don&#39;t have a parent item yet (that will ...
Definition: YTableItem.h:226
YTableCellIterator cellsBegin()
Return an iterator that points to the first cell of this item.
Definition: YTableItem.h:126