libyui  3.0.10
/usr/src/RPM/BUILD/libyui-3.0.10/src/YComboBox.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:         YComboBox.h
00020 
00021   Author:       Stefan Hundhammer <sh@suse.de>
00022 
00023 /-*/
00024 
00025 #ifndef YComboBox_h
00026 #define YComboBox_h
00027 
00028 #include "YSelectionWidget.h"
00029 
00030 class YComboBoxPrivate;
00031 
00032 
00033 /**
00034  * ComboBox (a.k.a. "drop down box", "drop down selection"):
00035  *
00036  * A widget with a drop-down list of predefined values to select from.
00037  * Optionally, this widget can be created in "editable" mode which means that
00038  * the user can freely enter any text.
00039  *
00040  * In non-editable mode, a ComboBox works very much like a SelectionBox that
00041  * uses fewer screen space. In that mode, it is recommended to use
00042  * selectedItem() to retrieve its current value and selectItem() to set it.
00043  *
00044  * In editable mode, a ComboBox is more like an InputField with a list to pick
00045  * predefined values from (for less typing). In that mode, it is recommended to
00046  * use value() and setValue().
00047  *
00048  * In either mode, it might be dangerous to use the iterators the
00049  * (itemsBegin(), itemsEnd()) the base class (YSelectionWidget) provides to
00050  * find the currently selected item: The items' "selected" flag may or may not
00051  * be up to date. YComboBox::selectedItem() makes sure they are up to date.
00052  **/
00053 class YComboBox : public YSelectionWidget
00054 {
00055 protected:
00056     /**
00057      * Constructor.
00058      *
00059      * 'editable' means the user can freely enter any value without being
00060      * restricted to the items of the ComboBox's list.
00061      **/
00062     YComboBox( YWidget * parent, const std::string & label, bool editable );
00063 
00064 public:
00065     /**
00066      * Destructor.
00067      **/
00068     virtual ~YComboBox();
00069 
00070     /**
00071      * Returns a descriptive name of this widget class for logging,
00072      * debugging etc.
00073      **/
00074     virtual const char * widgetClass() const { return "YComboBox"; }
00075 
00076     /**
00077      * Return 'true' if this ComboBox is editable, i.e. if the user can freely
00078      * enter any value without being restricted to the items of the ComboBox's
00079      * list.
00080      *
00081      * Notice that this can only be set in the constructor.
00082      **/
00083     bool editable() const;
00084 
00085     /**
00086      * Return the value of this ComboBox:
00087      *
00088      * The text of a list item if the user (or the appplication) selected a
00089      * list item or the content of the ComboBox's input field if the ComboBox
00090      * is editable and the user (or the application) entered text there.
00091      *
00092      * See also YComboBox::selectedItem().
00093      **/
00094     std::string value();
00095 
00096     /**
00097      * Set the value of this ComboBox by string: Try to find a list item with
00098      * that label and select it.
00099      *
00100      * If there is no matching list item, editable ComboBoxes will set their
00101      * input field to that text. Non-editable ComboBoxes will throw an
00102      * exception.
00103      *
00104      * See also selectItem().
00105      **/
00106     void setValue( const std::string & newText );
00107 
00108     /**
00109      * Return the (first) selected item or 0 if none is selected or if this
00110      * ComboBox is editable and the user entered something that does not match
00111      * any of the ComboBox's list items (in that case, use value() instead).
00112      *
00113      * Reimplemented from YSelectionWidget for better reliability: This will
00114      * compare an editable ComboBox's user input against the text labels of
00115      * all items and try to return an item if there is any match.
00116      **/
00117     virtual YItem * selectedItem();
00118 
00119     /**
00120      * Return all selected items.
00121      *
00122      * This is not particularly useful for ComboBoxes since there can be no
00123      * more than one selected item anyway; * better use selectedItem() or
00124      * value() instead.
00125      *
00126      * This function does not transfer ownership of those items to the caller,
00127      * so don't try to delete them!
00128      *
00129      * Reimplemented from YSelectionWidget for better reliability.
00130      **/
00131     virtual YItemCollection selectedItems();
00132 
00133     /**
00134      * Select or deselect an item. See also setValue().
00135      *
00136      * Reimplemented from YSelectionWidget.
00137      **/
00138     virtual void selectItem( YItem * item, bool selected = true );
00139 
00140     /**
00141      * Get the valid input characters. No input validation is performed (i.e.,
00142      * the user can enter anything) if this is empty.
00143      *
00144      * This is only meaningful for if the ComboBox is editable.
00145      **/
00146     std::string validChars();
00147 
00148     /**
00149      * Set the valid input characters. No input validation is performed (i.e.,
00150      * the user can enter anything) if this is empty.
00151      *
00152      * This is only meaningful for if the ComboBox is editable.
00153      *
00154      * Derived classes are free to reimplement this, but they should call this
00155      * base class method at the end of the overloaded function.
00156      **/
00157     virtual void setValidChars( const std::string & validChars );
00158 
00159     /**
00160      * The maximum input length, i.e., the maximum number of characters the
00161      * user can enter. -1 means no limit.
00162      *
00163      * This is only meaningful for if the ComboBox is editable.
00164      **/
00165     int inputMaxLength() const;
00166 
00167     /**
00168      * Set the maximum input length, i.e., the maximum number of characters the
00169      * user can enter. -1 means no limit.
00170      *
00171      * This is only meaningful for if the ComboBox is editable.
00172      *
00173      * Derived classes are free to reimplement this, but they should call this
00174      * base class method at the end of the overloaded function.
00175      **/
00176     virtual void setInputMaxLength( int numberOfChars );
00177 
00178     /**
00179      * Set a property.
00180      * Reimplemented from YWidget.
00181      *
00182      * This function may throw YUIPropertyExceptions.
00183      *
00184      * This function returns 'true' if the value was successfully set and
00185      * 'false' if that value requires special handling (not in error cases:
00186      * those are covered by exceptions).
00187      **/
00188     virtual bool setProperty( const std::string & propertyName,
00189                               const YPropertyValue & val );
00190 
00191     /**
00192      * Get a property.
00193      * Reimplemented from YWidget.
00194      *
00195      * This method may throw YUIPropertyExceptions.
00196      **/
00197     virtual YPropertyValue getProperty( const std::string & propertyName );
00198 
00199     /**
00200      * Return this class's property set.
00201      * This also initializes the property upon the first call.
00202      *
00203      * Reimplemented from YWidget.
00204      **/
00205     virtual const YPropertySet & propertySet();
00206 
00207     /**
00208      * The name of the widget property that will return user input.
00209      * Inherited from YWidget.
00210      **/
00211     const char * userInputProperty() { return YUIProperty_Value; }
00212 
00213 
00214 protected:
00215 
00216     /**
00217      * Return this ComboBox's current value as text.
00218      *
00219      * Called internally from value(), selectedItem() and related.
00220      *
00221      * Derived classes are required to implement this function.
00222      **/
00223     virtual std::string text() = 0;
00224 
00225     /**
00226      *
00227      * Set this ComboBox's current value as text.
00228      *
00229      * Called internally whenever the content is to change
00230      * programmatically. Don't call setValue() or selectItem() from here.
00231      *
00232      * Derived classes are required to implement this function.
00233      **/
00234     virtual void setText( const std::string & newText ) = 0;
00235 
00236 
00237 private:
00238 
00239     ImplPtr<YComboBoxPrivate> priv;
00240 };
00241 
00242 
00243 #endif // YComboBox_h
 All Classes Functions Variables Enumerations Friends