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: YTree.h 00020 00021 Author: Stefan Hundhammer <sh@suse.de> 00022 00023 /-*/ 00024 00025 #ifndef YTree_h 00026 #define YTree_h 00027 00028 #include "YSelectionWidget.h" 00029 00030 class YTreeItem; 00031 class YTreePrivate; 00032 00033 00034 /** 00035 * Tree: List box that displays a (scrollable) list of hierarchical items from 00036 * which the user can select exactly one. Each item has a label text and an 00037 * optional icon (*). 00038 * 00039 * This is very similar to SelectionBox, but each item can have subitems that 00040 * can be open (expanded) or closed (collapsed). 00041 * 00042 * The tree widget also has a caption label that is displayed above the 00043 * tree. The hotkey displayed in that caption label will move the keyboard 00044 * focus into the tree item list. 00045 * 00046 * 00047 * (*) Not all UIs (in particular not text-based UIs) support displaying icons, 00048 * so an icon should never be an exclusive means to display any kind of 00049 * information. 00050 00051 * 'multiSelection' indicates whether or not the user can select multiple 00052 * items at the same time. This can only be set in the constructor. 00053 **/ 00054 00055 00056 class YTree : public YSelectionWidget 00057 { 00058 protected: 00059 /** 00060 * Constructor. 00061 **/ 00062 YTree( YWidget * parent, const std::string & label, bool multiSelection, bool recursiveSelection); 00063 00064 public: 00065 /** 00066 * Destructor. 00067 **/ 00068 virtual ~YTree(); 00069 00070 /** 00071 * Returns a descriptive name of this widget class for logging, 00072 * debugging etc. 00073 **/ 00074 virtual const char * widgetClass() const { return "YTree"; } 00075 00076 /** 00077 * Rebuild the displayed tree from the internally stored YTreeItems. 00078 * 00079 * The application should call this (once) after all items have been added 00080 * with addItem(). YTree::addItems() calls this automatically. 00081 * 00082 * Derived classes are required to implement this. 00083 **/ 00084 virtual void rebuildTree() = 0; 00085 00086 /** 00087 * Add multiple items. For some UIs, this can be more efficient than 00088 * calling addItem() multiple times. This function also automatically calls 00089 * rebuildTree() at the end. 00090 * 00091 * Derived classes can overwrite this function, but they should call this 00092 * base class function at the end of the new implementation. 00093 * 00094 * Reimplemented from YSelectionWidget. 00095 **/ 00096 virtual void addItems( const YItemCollection & itemCollection ); 00097 00098 /** 00099 * Deliver even more events than with notify() set. 00100 * 00101 * For YTree, this is relevant mostly for the NCurses UI: 00102 * 00103 * In graphical UIs like the Qt UI, the user can use the mouse to select an 00104 * item in a tree. With notify() set, this will send an event right away 00105 * (i.e., it will make UserInput and related return, while normally it 00106 * would only return when the user clicks a PushButton). 00107 * 00108 * In the NCurses UI, there is no mouse, so the user has to use the cursor 00109 * keys to move to the item he wants to select. In immediateMode(), every 00110 * cursor key press will make the tree send an event. Without 00111 * immediateMode(), the NCTree will wait until the user hits the [Return] 00112 * key until an event is sent. Depending on what the application does upon 00113 * each selection box event, immediateMode() might make the application 00114 * less responsive. 00115 **/ 00116 bool immediateMode() const; 00117 00118 /** 00119 * Set immediateMode() on or off. 00120 **/ 00121 void setImmediateMode( bool on = true ); 00122 00123 /** 00124 * Set a property. 00125 * Reimplemented from YWidget. 00126 * 00127 * This function may throw YUIPropertyExceptions. 00128 * 00129 * This function returns 'true' if the value was successfully set and 00130 * 'false' if that value requires special handling (not in error cases: 00131 * those are covered by exceptions). 00132 **/ 00133 virtual bool setProperty( const std::string & propertyName, 00134 const YPropertyValue & val ); 00135 00136 /** 00137 * Get a property. 00138 * Reimplemented from YWidget. 00139 * 00140 * This method may throw YUIPropertyExceptions. 00141 **/ 00142 virtual YPropertyValue getProperty( const std::string & propertyName ); 00143 00144 /** 00145 * Return this class's property set. 00146 * This also initializes the property upon the first call. 00147 * 00148 * Reimplemented from YWidget. 00149 **/ 00150 virtual const YPropertySet & propertySet(); 00151 00152 /** 00153 * The name of the widget property that will return user input. 00154 * Inherited from YWidget. 00155 **/ 00156 const char * userInputProperty() { return YUIProperty_CurrentItem; } 00157 00158 00159 /** 00160 * Return 'true' if the user can select multiple items at the same time 00161 **/ 00162 bool hasMultiSelection() const; 00163 00164 /** 00165 * Return the the item that currently has the keyboard focus 00166 * or 0 if no item currently has the keyboard focus. 00167 * 00168 * Notice that for a MultiSelectionBox the current item is not necessarily 00169 * selected, i.e., its check box may or may not be checked. 00170 * 00171 * Derived classes are required to implement this function. 00172 **/ 00173 virtual YTreeItem * currentItem() = 0; 00174 00175 00176 private: 00177 00178 ImplPtr<YTreePrivate> priv; 00179 }; 00180 00181 00182 #endif // YTree_h