libyui  3.0.10
/usr/src/RPM/BUILD/libyui-3.0.10/src/YTree.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:         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
 All Classes Functions Variables Enumerations Friends