libyui  3.0.10
/usr/src/RPM/BUILD/libyui-3.0.10/src/YSelectionWidget.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:         YSelectionWidget.h
00020 
00021   Author:       Stefan Hundhammer <sh@suse.de>
00022 
00023 /-*/
00024 
00025 #ifndef YSelectionWidget_h
00026 #define YSelectionWidget_h
00027 
00028 #include "YWidget.h"
00029 #include "YItem.h"
00030 #include "ImplPtr.h"
00031 
00032 class YSelectionWidgetPrivate;
00033 
00034 /**
00035  * Base class for selection widgets:
00036  *   - YSelectionBox
00037  *   - MultiselectionBox
00038  *   - YCombobox
00039  *   - YTree
00040  *   - YDumbTab
00041  **/
00042 class YSelectionWidget : public YWidget
00043 {
00044 protected:
00045 
00046     /**
00047      * Constructor.
00048      *
00049      * 'singleSelectionMode' indicates if this base class should enforce single
00050      * selection when items are added or when items are selected from the
00051      * application. Note that single selection can also mean that no item is
00052      * selected.
00053      **/
00054     YSelectionWidget( YWidget *                 parent,
00055                       const std::string &       label,
00056                       bool                      enforceSingleSelection,
00057                       bool                      recurisveSelection = false );
00058 
00059 public:
00060     /**
00061      * Destructor.
00062      **/
00063     virtual ~YSelectionWidget();
00064 
00065     /**
00066      * Returns a descriptive name of this widget class for logging,
00067      * debugging etc.
00068      **/
00069     virtual const char * widgetClass() const { return "YSelectionWidget"; }
00070 
00071     /**
00072      * Return this widget's label (the caption above the item list).
00073      **/
00074     std::string label() const;
00075 
00076     /**
00077      * Change this widget's label (the caption above the item list).
00078      *
00079      * Derived classes should overwrite this function, but they should call
00080      * this base class function in the new implementation.
00081      **/
00082     virtual void setLabel( const std::string & newLabel );
00083 
00084     /**
00085      * Add one item. This widget assumes ownership of the item object and will
00086      * delete it in its destructor.
00087      *
00088      * NOTE: For tree items, call this only for the toplevel items; all
00089      * non-toplevel items are already owned by their respective parent
00090      * items. Adding them to the parent widget will clash with this ownership.
00091      *
00092      * Derived classes can overwrite this function, but they should call this
00093      * base class function in the new implementation.
00094      **/
00095     virtual void addItem( YItem * item_disown );
00096 
00097     /**
00098      * Overloaded for convenience: Add an item by string.
00099      **/
00100     void addItem( const std::string & itemLabel, bool selected = false );
00101 
00102     /**
00103      * Overloaded for convenience: Add an item with a text and an icon.
00104      * Note that not all UIs can display icons.
00105      **/
00106     void addItem( const std::string & itemLabel,
00107                   const std::string & iconName,
00108                   bool  selected = false );
00109 
00110     /**
00111      * Add multiple items. For some UIs, this can be more efficient than
00112      * calling addItem() multiple times.
00113      **/
00114     virtual void addItems( const YItemCollection & itemCollection );
00115 
00116     /**
00117      * Delete all items.
00118      *
00119      * Derived classes can overwrite this function, but they should call this
00120      * base class function in the new implementation.
00121      **/
00122     virtual void deleteAllItems();
00123 
00124     /**
00125      * Delete all items and add new items.
00126      **/
00127     void setItems( const YItemCollection & itemCollection )
00128         { deleteAllItems(); addItems( itemCollection ); }
00129 
00130     /**
00131      * Return an iterator that points to the first item.
00132      *
00133      * For YSelectionWidgets that can have tree structures, this iterator will
00134      * iterate over the toplevel items.
00135      *
00136      * Important: Don't use this iterator to iterate over all items and check
00137      * their "selected" state; that information might not always be up to
00138      * date. Use the dedicated functions for that.
00139      **/
00140     YItemIterator       itemsBegin();
00141     YItemConstIterator  itemsBegin() const;
00142 
00143     /**
00144      * Return an iterator that points behind the last item.
00145      **/
00146     YItemIterator       itemsEnd();
00147     YItemConstIterator  itemsEnd() const;
00148 
00149     /**
00150      * Return 'true' if this widget has any items.
00151      **/
00152     bool hasItems() const;
00153 
00154     /**
00155      * Return the number of items.
00156      *
00157      * For YSelectionWidgets that can have tree structures, this returns the
00158      * number of toplevel items.
00159      **/
00160     int itemsCount() const;
00161 
00162     /**
00163      * Return the first item or 0 if there is none.
00164      **/
00165     YItem * firstItem() const;
00166 
00167     /**
00168      * Return the (first) selected item or 0 if none is selected.
00169      **/
00170     virtual YItem * selectedItem();
00171 
00172     /**
00173      * Return all selected items. This is mostly useful for derived classes
00174      * that allow selecting multiple items.
00175      *
00176      * This function does not transfer ownership of those items to the caller,
00177      * so don't try to delete them!
00178      **/
00179     virtual YItemCollection selectedItems();
00180 
00181     /**
00182      * Return 'true' if any item is selected.
00183      **/
00184     bool hasSelectedItem();
00185 
00186     /**
00187      * Select or deselect an item.
00188      *
00189      * Notice that this is different from YItem::setSelected() because unlike
00190      * the latter function, this function informs the parent widget of the
00191      * selection change.
00192      *
00193      * If only one item can be selected at any time (single selection), the
00194      * derived class will make sure to deselect any previous selection, if
00195      * applicable.
00196      *
00197      * Derived classes should overwrite this function, but they should call
00198      * this base class function at the new function's start (this will also
00199      * check if the item really belongs to this widget and throw an exception
00200      * if not).
00201      **/
00202     virtual void selectItem( YItem * item, bool selected = true );
00203 
00204     /**
00205      * Deselect all items.
00206      *
00207      * Derived classes can overwrite this function, but they should call this
00208      * base class function in the new implementation.
00209      **/
00210     virtual void deselectAllItems();
00211 
00212     /**
00213      * Set this widget's base path where to look up icons.
00214      * If this is a relative path, YUI::qApp()->iconBasePath() is prepended.
00215      **/
00216     void setIconBasePath( const std::string & basePath );
00217 
00218     /**
00219      * Return this widget's base path where to look up icons
00220      * as set with setIconBasePath().
00221      **/
00222     std::string iconBasePath() const;
00223 
00224     /**
00225      * Return the full path + file name for the specified icon name.
00226      * If iconBasePath is non-empty, it is prepended to the icon name.
00227      * Otherwise, YUI::yApp()->iconLoader() and its icon search paths
00228      * is used find the icon in one of them
00229      *
00230      * If 'iconName' is empty, this will return an empty string.
00231      **/
00232     std::string iconFullPath( const std::string & iconName ) const;
00233 
00234     /**
00235      * Return the full path + file name for the icon of the specified item.
00236      * If iconBasePath is non-empty, it is prepended to the item's iconName.
00237      * Otherwise, YUI::yApp()->iconLoader() and its icon search paths
00238      * is used find the icon in one of them
00239      *
00240      * If 'item' does not have an iconName specified, this will return an empty
00241      * string.
00242      **/
00243     std::string iconFullPath( YItem * item ) const;
00244 
00245     /**
00246      * Return 'true' if this widget's items contain the specified item.
00247      **/
00248     bool itemsContain( YItem * item ) const;
00249 
00250     /**
00251      * Find the (first) item with the specified label.
00252      * Return 0 if there is no item with that label.
00253      **/
00254     YItem * findItem( const std::string & itemLabel ) const;
00255 
00256     /**
00257      * Get the string of this widget that holds the keyboard shortcut.
00258      *
00259      * Reimplemented from YWidget.
00260      **/
00261     virtual std::string shortcutString() const { return label(); }
00262 
00263     /**
00264      * Set the string of this widget that holds the keyboard shortcut.
00265      *
00266      * Reimplemented from YWidget.
00267      **/
00268     virtual void setShortcutString( const std::string & str )
00269         { setLabel( str ); }
00270 
00271 protected:
00272 
00273     /**
00274      * Set single selection mode on or off. In single selection mode, only one
00275      * item can be selected at any time.
00276      *
00277      * If set, this base class enforces this when items are added or when items
00278      * are selected from the application. Note that single selection can also
00279      * mean that no item is selected.
00280      **/
00281     void setEnforceSingleSelection( bool on );
00282 
00283     /**
00284      * Return 'true' if this base class should enforce single selection.
00285      **/
00286     bool enforceSingleSelection() const;
00287 
00288     /**
00289      * Return 'true' if this base class should select children recursively.
00290      **/
00291     bool recursiveSelection() const;
00292 
00293     /**
00294      * Recursively try to find the first selected item between iterators
00295      * 'begin' and 'end'. Return that item or 0 if there is none.
00296      **/
00297     YItem * findSelectedItem( YItemConstIterator begin,
00298                               YItemConstIterator end );
00299 
00300     /**
00301      * Recursively find all selected items between iterators 'begin' and 'end'
00302      * and add each of them to the 'selectedItems' YItemCollection.
00303      **/
00304     void findSelectedItems( YItemCollection &   selectedItems,
00305                             YItemConstIterator  begin,
00306                             YItemConstIterator  end );
00307 
00308     /**
00309      * Recursively deselect all items between iterators 'begin' and 'end'.
00310      **/
00311     void deselectAllItems( YItemIterator        begin,
00312                            YItemIterator        end );
00313     /**
00314      * Recursively try to find an item with label 'wantedItemLabel' between
00315      * iterators 'begin' and 'end'. Return that item or 0 if there is none.
00316      **/
00317     YItem * findItem    ( const std::string &   wantedItemLabel,
00318                           YItemConstIterator    begin,
00319                           YItemConstIterator    end ) const;
00320 
00321     /**
00322      * Recursively check if 'wantedItem' is between iterators 'begin' and
00323      * 'end'.
00324      **/
00325     bool itemsContain   ( YItem *               wantedItem,
00326                           YItemConstIterator    begin,
00327                           YItemConstIterator    end ) const;
00328     /**
00329      * Return the item at index 'index' (from 0)
00330      * or 0 if there is no such item.
00331      **/
00332     YItem * itemAt( int index ) const;
00333 
00334 
00335 private:
00336 
00337     ImplPtr<YSelectionWidgetPrivate> priv;
00338 };
00339 
00340 
00341 #endif // YSelectionWidget_h
 All Classes Functions Variables Enumerations Friends