libyui
3.0.10
|
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