libyui  3.0.10
/usr/src/RPM/BUILD/libyui-3.0.10/src/YTableItem.h
00001 /*
00002   Copyright (C) 2000-2012 Novell, Inc
00003   This library is free software; you can redistribute it and/or modify
00004   it under the terms of the GNU Lesser General Public License as
00005   published by the Free Software Foundation; either version 2.1 of the
00006   License, or (at your option) version 3.0 of the License. This library
00007   is distributed in the hope that it will be useful, but WITHOUT ANY
00008   WARRANTY; without even the implied warranty of MERCHANTABILITY or 
00009   FITNESS FOR A PARTICULAR PURPOSE. See the GNU Lesser General Public
00010   License for more details. You should have received a copy of the GNU
00011   Lesser General Public License along with this library; if not, write
00012   to the Free Software Foundation, Inc., 51 Franklin Street, Fifth
00013   Floor, Boston, MA 02110-1301 USA
00014 */
00015 
00016 
00017 /*-/
00018 
00019   File:         YTableItem.h
00020 
00021   Author:       Stefan Hundhammer <sh@suse.de>
00022 
00023 /-*/
00024 
00025 #ifndef YTableItem_h
00026 #define YTableItem_h
00027 
00028 #include "YItem.h"
00029 
00030 
00031 class YTableCell;
00032 
00033 typedef std::vector<YTableCell *>               YTableCellCollection;
00034 typedef YTableCellCollection::iterator          YTableCellIterator;
00035 typedef YTableCellCollection::const_iterator    YTableCellConstIterator;
00036 
00037 
00038 /**
00039  * Item class for YTable items. Each YTableItem corresponds to one row in a
00040  * YTable.
00041  *
00042  * A YTableItem might have any number of cells (columns within this row),
00043  * including none. The YTable widget is free to ignore any excess cells if
00044  * there are more than the YTable widget has columns. The YTable widget is to
00045  * treat nonexistent cells like empty ones.
00046  *
00047  * Note that while YTable items and their cells can be manipulated through
00048  * pointers, their visual representation on screen might be updated only upon
00049  * calling certain methods of the YTable widget. See the YTable reference for
00050  * details.
00051  **/
00052 class YTableItem: public YItem
00053 {
00054 public:
00055 
00056     /**
00057      * Default constructor. Use addCell() to give it any content.
00058      **/
00059     YTableItem();
00060 
00061     /**
00062      * Convenience constructor for table items without any icons.
00063      *
00064      * This will create up to 10 (0..9) cells. Empty cells for empty labels at
00065      * the end of the labels are not created, but empty cells in between are.
00066      *
00067      *     new YTableItem( "one", "two", "", "", "five" );
00068      *
00069      * will create an item with 5 cells:
00070      *
00071      *     cell[0] ==> "one"
00072      *     cell[1] ==> "two"
00073      *     cell[2] ==> ""
00074      *     cell[3] ==> ""
00075      *     cell[4] ==> "five"
00076      **/
00077     YTableItem( const std::string & label_0,
00078                 const std::string & label_1 = std::string(),
00079                 const std::string & label_2 = std::string(),
00080                 const std::string & label_3 = std::string(),
00081                 const std::string & label_4 = std::string(),
00082                 const std::string & label_5 = std::string(),
00083                 const std::string & label_6 = std::string(),
00084                 const std::string & label_7 = std::string(),
00085                 const std::string & label_8 = std::string(),
00086                 const std::string & label_9 = std::string() );
00087 
00088     /**
00089      * Destructor.
00090      *
00091      * This will delete all cells.
00092      **/
00093     virtual ~YTableItem();
00094 
00095     /**
00096      * Add a cell. This item will assume ownership over the cell and delete it
00097      * when appropriate (when the table is destroyed or when table items are
00098      * replaced), at which time the pointer will become invalid.
00099      *
00100      * Cells can still be changed after they (and the item they belong to) are
00101      * added, but in that case, YTable::cellChanged() needs to be called to
00102      * update the table display accordingly.
00103      **/
00104     void addCell( YTableCell * cell_disown );
00105 
00106     /**
00107      * Create a new cell and add it (even if both 'label' and
00108      * 'iconName' are empty).
00109      **/
00110     void addCell( const std::string & label, const std::string & iconName = std::string() );
00111 
00112     /**
00113      * Delete all cells.
00114      **/
00115     void deleteCells();
00116 
00117     /**
00118      * Return an iterator that points to the first cell of this item.
00119      **/
00120     YTableCellIterator          cellsBegin()            { return _cells.begin(); }
00121     YTableCellConstIterator     cellsBegin() const      { return _cells.begin(); }
00122 
00123     /**
00124      * Return an iterator that points after the last cell of this item.
00125      **/
00126     YTableCellIterator          cellsEnd()              { return _cells.end(); }
00127     YTableCellConstIterator     cellsEnd() const        { return _cells.end(); }
00128 
00129     /**
00130      * Return the cell at the specified index (counting from 0 on)
00131      * or 0 if there is none.
00132      **/
00133     const YTableCell * cell( int index ) const;
00134     YTableCell * cell( int index );
00135 
00136     /**
00137      * Return the number of cells this item has.
00138      **/
00139     int cellCount() const { return _cells.size(); }
00140 
00141     /**
00142      * Return 'true' if this item has a cell with the specified index
00143      * (counting from 0 on), 'false' otherwise.
00144      **/
00145     bool hasCell( int index ) const;
00146 
00147     /**
00148      * Return the label of cell no. 'index' (counting from 0 on) or an empty
00149      * string if there is no cell with that index.
00150      **/
00151     std::string label( int index ) const;
00152 
00153     /**
00154      * Return the icon name of cell no. 'index' (counting from 0 on) or an empty
00155      * string if there is no cell with that index.
00156      **/
00157     std::string iconName( int index ) const;
00158 
00159     /**
00160      * Return 'true' if there is a cell with the specified index that has an
00161      * icon name.
00162      **/
00163     bool hasIconName( int index ) const;
00164 
00165     /**
00166      * Just for debugging.
00167      **/
00168     std::string label() const { return label(0); }
00169 
00170 private:
00171 
00172     // Disable unwanted base class methods. They don't make sense in this
00173     // context since there is not just one single label or icon name, but one
00174     // for each cell.
00175 
00176     std::string iconName()      const                   { return ""; }
00177     bool        hasIconName()   const                   { return false; }
00178     void        setLabel        ( const std::string & ) {}
00179     void        setIconName     ( const std::string & ) {}
00180 
00181 
00182     //
00183     // Data members
00184     //
00185 
00186     YTableCellCollection _cells;
00187 };
00188 
00189 
00190 
00191 /**
00192  * One cell (one column in one row) of a YTableItem. Each cell has a label (a
00193  * user visible text) and optionally an icon (*).
00194  *
00195  * Note that cells don't have individual IDs; they have just an index.
00196  * The first cell in an item is cell(0). In an ideal world, each YTableItem
00197  * would have exactly as many cells as there are columns in the YTable, but
00198  * these classes make no such assumptions. A YTableItem might have any number
00199  * of cells, including none.
00200  *
00201  * The YTable widget is free to ignore any excess cells if there are more than
00202  * the YTable widget has columns. If there are less cells than the table has
00203  * columns, the nonexistent cells will be treated as empty.
00204  *
00205  *
00206  * (*) Not all UIs can handle icons. UIs that can't handle them will simply
00207  * ignore any icons specified for YTableCells. Thus, applications should either
00208  * check the UI capabilities if it can handle icons or use icons only as an
00209  * additional visual cue that still has a text counterpart (so the user can
00210  * still make sense of the table content when no icons are visible).
00211  **/
00212 class YTableCell
00213 {
00214 public:
00215     /**
00216      * Constructor with label and optional icon name for cells that don't have
00217      * a parent item yet (that will be added to a parent later with
00218      * setParent()).
00219      **/
00220     YTableCell( const std::string & label, const std::string & iconName = "" )
00221         : _label( label )
00222         , _iconName( iconName )
00223         , _parent( 0 )
00224         , _column ( -1 )
00225         {}
00226 
00227     /**
00228      * Constructor with parent, column no., label and optional icon name for
00229      * cells that are created with a parent.
00230      **/
00231     YTableCell( YTableItem *            parent,
00232                 int                     column,
00233                 const std::string &     label,
00234                 const std::string &     iconName = "" )
00235         : _label( label )
00236         , _iconName( iconName )
00237         , _parent( parent )
00238         , _column ( column )
00239         {}
00240 
00241     /**
00242      * Destructor. Not strictly needed inside this class, but useful for
00243      * derived classes. Since this is the only virtual method of this class,
00244      * the cost of this is a vtable for this class and a pointer to the vtable
00245      * in each instance.
00246      **/
00247     virtual ~YTableCell() {}
00248 
00249     /**
00250      * Return this cells's label. This is what the user sees in a dialog, so
00251      * this will usually be a translated text.
00252      **/
00253     std::string label() const { return _label; }
00254 
00255     /**
00256      * Set this cell's label.
00257      *
00258      * If this is called after the corresponding table item (table row) is
00259      * added to the table widget, call YTable::cellChanged() to notify the
00260      * table widget about the fact. Only then will the display be updated.
00261      **/
00262     void setLabel( const std::string & newLabel ) { _label = newLabel; }
00263 
00264     /**
00265      * Return this cell's icon name.
00266      **/
00267     std::string iconName() const { return _iconName; }
00268 
00269     /**
00270      * Return 'true' if this cell has an icon name.
00271      **/
00272     bool hasIconName() const { return ! _iconName.empty(); }
00273 
00274     /**
00275      * Set this cell's icon name.
00276      *
00277      * If this is called after the corresponding table item (table row) is
00278      * added to the table widget, call YTable::cellChanged() to notify the
00279      * table widget about the fact. Only then will the display be updated.
00280      **/
00281     void setIconName( const std::string & newIconName ) { _iconName = newIconName; }
00282 
00283     /**
00284      * Return this cell's parent item or 0 if it doesn't have one yet.
00285      **/
00286     YTableItem * parent() const { return _parent; }
00287 
00288     /**
00289      * Return this cell's column no. (counting from 0on) or -1 if it doesn't
00290      * have a parent yet.
00291      **/
00292     int column() const { return _column; }
00293 
00294     /**
00295      * Convenience function: Return this cell's parent item's index within its
00296      * table widget or -1 if there is no parent item or no parent table.
00297      **/
00298     int itemIndex() const { return _parent ? _parent->index() : -1; }
00299 
00300     /**
00301      * Set this cell's parent item and column no. if it doesn't have a parent
00302      * yet.
00303      *
00304      * This method will throw an exception if the cell already has a parent.
00305      **/
00306     void reparent( YTableItem * parent, int column );
00307 
00308 
00309 private:
00310 
00311     std::string         _label;
00312     std::string         _iconName;
00313     YTableItem *        _parent;
00314     int                 _column;
00315 };
00316 
00317 
00318 
00319  #endif // YTableItem_h
 All Classes Functions Variables Enumerations Friends