libyui  3.0.10
/usr/src/RPM/BUILD/libyui-3.0.10/src/YTable.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:         YTable.h
00020 
00021   Author:       Stefan Hundhammer <sh@suse.de>
00022 
00023 /-*/
00024 
00025 #ifndef YTable_h
00026 #define YTable_h
00027 
00028 #include "YTypes.h"
00029 #include "YSelectionWidget.h"
00030 #include "YTableItem.h"
00031 #include "YTableHeader.h"
00032 
00033 class YTablePrivate;
00034 
00035 
00036 
00037 /**
00038  * Table: Selection list with multiple columns. The user can select exactly one
00039  * row (with all its columns) from that list. Each cell (each column within
00040  * each row) has a label text and an optional icon (*).
00041  *
00042  * This widget is similar to SelectionBox, but it has several columns for each
00043  * item (each row). If just one column is desired, consider using SelectionBox
00044  * instead.
00045  *
00046  * Note: This is not something like a spread sheet, and it doesn't pretend or
00047  * want to be. Actions are performed on rows, not on individual cells (columns
00048  * within one row).
00049  *
00050  *
00051  * (*) Not all UIs (in particular not text-based UIs) support displaying icons,
00052  * so an icon should never be an exclusive means to display any kind of
00053  * information.
00054  **/
00055 class YTable : public YSelectionWidget
00056 {
00057 protected:
00058     /**
00059      * Constructor.
00060      *
00061      * 'header' describes the table's headers: Number of columns, column
00062      * headings, and column alignment. The widget assumes ownership of this
00063      * object and will delete it when appropriate. The header cannot be changed
00064      * after creating the widget.
00065      *
00066      * 'multiSelection' indicates whether or not the user can select multiple
00067      * items at the same time (e.g., with shift-click or ctrl-click). This can
00068      * only be set in the constructor.
00069      **/
00070     YTable( YWidget * parent, YTableHeader * header, bool multiSelection );
00071 
00072 public:
00073 
00074     /**
00075      * Destructor.
00076      **/
00077     virtual ~YTable();
00078 
00079     /**
00080      * Return a descriptive name of this widget class for logging,
00081      * debugging etc.
00082      **/
00083     virtual const char * widgetClass() const { return "YTable"; }
00084 
00085     /**
00086      * Return the number of columns of this table.
00087      **/
00088     int columns() const;
00089 
00090     /**
00091      * Return 'true' if this table has a column no. 'column'
00092      * (counting from 0 on).
00093      **/
00094     bool hasColumn( int column ) const;
00095 
00096     /**
00097      * Return the header text for the specified column.
00098      **/
00099     std::string header( int column ) const;
00100 
00101     /**
00102      * Return the alignment for the specified column.
00103      **/
00104     YAlignmentType alignment( int column ) const;
00105 
00106     /**
00107      * Deliver even more events than with notify() set.
00108      *
00109      * With "notify" alone, a table widget sends an ActivatedEvent when the
00110      * user double-clicks an item or presses the "space" key on it. It does
00111      * not send an event when the user just sends another item.
00112      *
00113      * With "immediate", it also sends a SelectionChangedEvent when the user
00114      * selects another item. "immediate" implicitly includes "notify".
00115      **/
00116     bool immediateMode() const;
00117 
00118     /**
00119      * Set immediateMode() on or off.
00120      **/
00121     void setImmediateMode( bool immediateMode = true );
00122 
00123     /**
00124      * Return 'true' if the sort order is to be kept in item insertion order,
00125      * i.e. if sorting the table by clicking on a column header should be
00126      * disabled.
00127      **/
00128     bool keepSorting() const;
00129 
00130     /**
00131      * Switch between sorting by item insertion order (keepSorting: true) or
00132      * allowing the user to sort by an arbitrary column (by clicking on the
00133      * column header).
00134      *
00135      * Derived classes can overwrite this function, but they should call this
00136      * base class function in the new implementation.
00137      **/
00138     virtual void setKeepSorting( bool keepSorting );
00139 
00140     /**
00141      * Return 'true' if the user can select multiple items  at the same time
00142      * (e.g., with shift-click or ctrl-click).
00143      **/
00144     bool hasMultiSelection() const;
00145 
00146     /**
00147      * Notification that a cell (its text and/or its icon) was changed from the
00148      * outside. Applications are required to call this whenever a table cell is
00149      * changed after adding the corresponding table item (the row) to the table
00150      * widget.
00151      *
00152      * Derived classes are required to implement this and update the display
00153      * accordingly.
00154      *
00155      * Note that the position of this cell can be retrieved with cell->column()
00156      * and cell->itemIndex().
00157      **/
00158     virtual void cellChanged( const YTableCell * cell ) = 0;
00159 
00160     /**
00161      * Set a property.
00162      * Reimplemented from YWidget.
00163      *
00164      * This function may throw YUIPropertyExceptions.
00165      *
00166      * This function returns 'true' if the value was successfully set and
00167      * 'false' if that value requires special handling (not in error cases:
00168      * those are covered by exceptions).
00169      **/
00170     virtual bool setProperty( const std::string & propertyName,
00171                               const YPropertyValue & val );
00172 
00173     /**
00174      * Get a property.
00175      * Reimplemented from YWidget.
00176      *
00177      * This method may throw YUIPropertyExceptions.
00178      **/
00179     virtual YPropertyValue getProperty( const std::string & propertyName );
00180 
00181     /**
00182      * Return this class's property set.
00183      * This also initializes the property upon the first call.
00184      *
00185      * Reimplemented from YWidget.
00186      **/
00187     virtual const YPropertySet & propertySet();
00188 
00189 
00190     /**
00191      * The name of the widget property that will return user input.
00192      * Inherited from YWidget.
00193      **/
00194     const char * userInputProperty() { return YUIProperty_CurrentItem; }
00195 
00196 
00197 protected:
00198 
00199     /**
00200      * Exchange the previous table header with a new one. This will delete the
00201      * old YTableHeader object.
00202      *
00203      * If the new header has a different number of columns than the old one,
00204      * all items will implicitly be deleted.
00205      **/
00206     void setTableHeader( YTableHeader * newHeader );
00207 
00208 private:
00209 
00210     ImplPtr<YTablePrivate> priv;
00211 };
00212 
00213 
00214 #endif // YTable_h
 All Classes Functions Variables Enumerations Friends