home *** CD-ROM | disk | FTP | other *** search
/ Personal Computer World 2009 February / PCWFEB09.iso / Software / Linux / SLAX 6.0.8 / slax-6.0.8.iso / slax / base / 006-devel.lzm / usr / include / kinputdialog.h < prev    next >
Encoding:
C/C++ Source or Header  |  2005-10-10  |  12.1 KB  |  291 lines
  1. /*
  2.   Copyright (C) 2003 Nadeem Hasan <nhasan@kde.org>
  3.  
  4.   This library is free software; you can redistribute it and/or
  5.   modify it under the terms of the GNU Library General Public
  6.   License as published by the Free Software Foundation; either
  7.   version 2 of the License, or (at your option) any later version.
  8.  
  9.   This library is distributed in the hope that it will be useful,
  10.   but WITHOUT ANY WARRANTY; without even the implied warranty of
  11.   MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE.  See the GNU
  12.   Library General Public License for more details.
  13.  
  14.   You should have received a copy of the GNU Library General Public License
  15.   along with this library; see the file COPYING.LIB.  If not, write to
  16.   the Free Software Foundation, Inc., 51 Franklin Street, Fifth Floor,
  17.   Boston, MA 02110-1301, USA.
  18. */
  19.  
  20. #ifndef KINPUTDIALOG_H
  21. #define KINPUTDIALOG_H
  22.  
  23. class QValidator;
  24.  
  25. class KLineEdit;
  26. class KIntSpinBox;
  27. class KDoubleSpinBox;
  28. class KComboBox;
  29. class KTextEdit;
  30. class KInputDialogPrivate;
  31.  
  32. #include <kdialogbase.h>
  33.  
  34. /**
  35.  * The KInputDialog class provides a simple dialog to get a single value
  36.  * from the user. The value can be a string, a number (either an integer or
  37.  * a float) or an item from a list. This class is designed to be source
  38.  * compatible with QInputDialog.
  39.  *
  40.  * Five static convenience functions are provided: getText(), getInteger().
  41.  * getDouble(), getItem() and getItemList().
  42.  *
  43.  * @since 3.2
  44.  * @author Nadeem Hasan <nhasan@kde.org>
  45.  */
  46. class KDEUI_EXPORT KInputDialog : public KDialogBase
  47. {
  48.   Q_OBJECT
  49.  
  50.   private:
  51.  
  52.     /**
  53.      * Constructor. This class is not designed to be instantiated except
  54.      * from the static member functions.
  55.      */
  56.     KInputDialog( const QString &caption, const QString &label,
  57.       const QString &value, QWidget *parent, const char *name,
  58.       QValidator *validator, const QString &mask );
  59.     KInputDialog( const QString &caption, const QString &label,
  60.       const QString &value, QWidget *parent, const char *name );
  61.     KInputDialog( const QString &caption, const QString &label, int value,
  62.       int minValue, int maxValue, int step, int base, QWidget *parent,
  63.       const char *name );
  64.     KInputDialog( const QString &caption, const QString &label, double value,
  65.       double minValue, double maxValue, double step, int decimals,
  66.       QWidget *parent, const char *name );
  67.     KInputDialog( const QString &caption, const QString &label,
  68.       const QStringList &list, int current, bool editable, QWidget *parent,
  69.       const char *name );
  70.     KInputDialog( const QString &caption, const QString &label,
  71.       const QStringList &list, const QStringList &select, bool editable,
  72.       QWidget *parent, const char *name );
  73.  
  74.     ~KInputDialog();
  75.  
  76.     KLineEdit *lineEdit() const;
  77.     KIntSpinBox *intSpinBox() const;
  78.     KDoubleSpinBox *doubleSpinBox() const;
  79.     KComboBox *comboBox() const;
  80.     KListBox *listBox() const;
  81.     KTextEdit *textEdit() const;
  82.  
  83.   private slots:
  84.  
  85.     void slotEditTextChanged( const QString& );
  86.     void slotUpdateButtons( const QString& );
  87.  
  88.   public:
  89.  
  90.     /**
  91.      * Static convenience function to get a string from the user.
  92.      *
  93.      * caption is the text that is displayed in the title bar. label is the
  94.      * text that appears as a label for the line edit. value is the initial
  95.      * value of the line edit. ok will be set to true if user pressed Ok
  96.      * and false if user pressed Cancel.
  97.      *
  98.      * If you provide a validator, the Ok button is disabled as long as
  99.      * the validator doesn't return Acceptable. If there is no validator,
  100.      * the Ok button is enabled whenever the line edit isn't empty. If you
  101.      * want to accept empty input, create a trivial QValidator that
  102.      * always returns acceptable, e.g. QRegExpValidator with a regexp
  103.      * of ".*".
  104.      *
  105.      * @param caption   Caption of the dialog
  106.      * @param label     Text of the label for the line edit
  107.      * @param value     Initial value of the line edit
  108.      * @param ok        This bool would be set to true if user pressed Ok
  109.      * @param parent    Parent of the dialog widget
  110.      * @param name      Name of the dialog widget
  111.      * @param validator A @ref QValidator to be associated with the line edit
  112.      * @param mask      Mask associated with the line edit. See the
  113.      *                  documentation for @ref QLineEdit about masks.
  114.      *
  115.      * @return String user entered if Ok was pressed, else a null string
  116.      */
  117.     static QString getText( const QString &caption, const QString &label,
  118.         const QString &value=QString::null, bool *ok=0, QWidget *parent=0,
  119.         const char *name=0, QValidator *validator=0,
  120.         const QString &mask=QString::null );
  121.  
  122.     /** 
  123.      * Same as @ref getText except it provides an extra parameter to specify 
  124.      * a QWhatsThis text for the input widget.
  125.      *
  126.      * ### KDE4: Merge with getText.
  127.      *
  128.      * @since KDE 3.3
  129.      **/
  130.     static QString text( const QString &caption, const QString &label, 
  131.         const QString &value=QString::null, bool *ok=0, QWidget *parent=0, 
  132.         const char *name=0, QValidator *validator=0,
  133.         const QString &mask=QString::null,
  134.         const QString& whatsThis=QString::null );
  135.  
  136.     /**
  137.      * Static convenience function to get a multiline string from the user.
  138.      *
  139.      * caption is the text that is displayed in the title bar. label is the
  140.      * text that appears as a label for the line edit. value is the initial
  141.      * value of the line edit. ok will be set to true if user pressed Ok
  142.      * and false if user pressed Cancel.
  143.      *
  144.      * @param caption   Caption of the dialog
  145.      * @param label     Text of the label for the line edit
  146.      * @param value     Initial value of the line edit
  147.      * @param ok        This bool would be set to true if user pressed Ok
  148.      * @param parent    Parent of the dialog widget
  149.      * @param name      Name of the dialog widget
  150.      *
  151.      * @return String user entered if Ok was pressed, else a null string
  152.      * @since 3.3
  153.      */
  154.     static QString getMultiLineText( const QString &caption,
  155.         const QString &label, const QString &value=QString::null,
  156.         bool *ok=0, QWidget *parent=0, const char *name=0 );
  157.  
  158.     /**
  159.      * Static convenience function to get an integer from the user.
  160.      *
  161.      * caption is the text that is displayed in the title bar. label is the
  162.      * text that appears as the label for the spin box. value is the initial
  163.      * value for the spin box. minValue and maxValue are the minimum and
  164.      * maximum allowable values the user may choose. step is the amount by
  165.      * which the value will change as the user presses the increment and
  166.      * decrement buttons of the spin box. Base is the base of the number.
  167.      *
  168.      * @param caption  Caption of the dialog
  169.      * @param label    Text of the label for the spin box
  170.      * @param value    Initial value of the spin box
  171.      * @param minValue Minimum value user can input
  172.      * @param maxValue Maximum value user can input
  173.      * @param step     Amount by which value is incremented or decremented
  174.      * @param base     Base of the number
  175.      * @param ok       This bool would be set to true if user pressed Ok
  176.      * @param parent   Parent of the dialog widget
  177.      * @param name     Name of the dialog widget
  178.      *
  179.      * @return Number user entered if Ok was pressed, else 0
  180.      */
  181.  
  182.     static int getInteger( const QString &caption, const QString &label,
  183.         int value=0, int minValue=-2147483647, int maxValue=2147483647,
  184.         int step=1, int base=10, bool *ok=0, QWidget *parent=0,
  185.         const char *name=0 );
  186.  
  187.     /**
  188.      * This is an overloaded convenience function. It behaves exactly same as
  189.      * above except it assumes base to be 10, i.e. accepts decimal numbers.
  190.      */
  191.     static int getInteger( const QString &caption, const QString &label,
  192.         int value=0, int minValue=-2147483647, int maxValue=2147483647,
  193.         int step=1, bool *ok=0, QWidget *parent=0, const char *name=0 );
  194.  
  195.     /**
  196.      * Static convenience function to get a floating point number from the user.
  197.      *
  198.      * caption is the text that is displayed in the title bar. label is the
  199.      * text that appears as the label for the spin box. value is the initial
  200.      * value for the spin box. minValue and maxValue are the minimum and
  201.      * maximum allowable values the user may choose. step is the amount by
  202.      * which the value will change as the user presses the increment and
  203.      * decrement buttons of the spin box.
  204.      *
  205.      * @param caption  Caption of the dialog
  206.      * @param label    Text of the label for the spin box
  207.      * @param value    Initial value of the spin box
  208.      * @param minValue Minimum value user can input
  209.      * @param maxValue Maximum value user can input
  210.      * @param step     Amount by which value is incremented or decremented
  211.      * @param decimals Number of digits after the decimal point
  212.      * @param ok       This bool would be set to true if user pressed Ok
  213.      * @param parent   Parent of the dialog widget
  214.      * @param name     Name of the dialog widget
  215.      *
  216.      * @return Number user entered if Ok was pressed, else 0
  217.      */
  218.     static double getDouble( const QString &caption, const QString &label,
  219.         double value=0, double minValue=-2147483647, 
  220.         double maxValue=2147483647, double step=0.1, int decimals=1,
  221.         bool *ok=0, QWidget *parent=0, const char *name=0 );
  222.  
  223.     /**
  224.      * This is an overloaded convenience function. It behaves exctly like
  225.      * the above function.
  226.      */
  227.     static double getDouble( const QString &caption, const QString &label,
  228.         double value=0, double minValue=-2147483647, 
  229.         double maxValue=2147483647, int decimals=1, bool *ok=0,
  230.         QWidget *parent=0, const char *name=0 );
  231.  
  232.     /**
  233.      * Static convenience function to let the user select an item from a
  234.      * list. caption is the text that is displayed in the title bar.
  235.      * label is the text that appears as the label for the list. list
  236.      * is the string list which is inserted into the list, and current
  237.      * is the number of the item which should be the selected item. If 
  238.      * editable is true, the user can enter their own text.
  239.      *
  240.      * @param caption  Caption of the dialog
  241.      * @param label    Text of the label for the spin box
  242.      * @param list     List of item for user to choose from
  243.      * @param current  Index of the selected item
  244.      * @param editable If true, user can enter own text
  245.      * @param ok       This bool would be set to true if user pressed Ok
  246.      * @param parent   Parent of the dialog widget
  247.      * @param name     Name of the dialog widget
  248.      *
  249.      * @return Text of the selected item. If @p editable is true this can be
  250.      *         a text entered by the user.
  251.      */
  252.     static QString getItem( const QString &caption, const QString &label,
  253.         const QStringList &list, int current=0, bool editable=false,
  254.         bool *ok=0, QWidget *parent=0, const char *name=0 );
  255.  
  256.     /**
  257.      * Static convenience function to let the user select one or more
  258.      * items from a listbox. caption is the text that is displayed in the
  259.      * title bar. label is the text that appears as the label for the listbox.
  260.      * list is the string list which is inserted into the listbox, select
  261.      * is the list of item(s) that should be the selected. If multiple is 
  262.      * true, the user can select multiple items.
  263.      *
  264.      * @param caption  Caption of the dialog
  265.      * @param label    Text of the label for the spin box
  266.      * @param list     List of item for user to choose from
  267.      * @param select   List of item(s) that should be selected
  268.      * @param multiple If true, user can select multiple items
  269.      * @param ok       This bool would be set to true if user pressed Ok
  270.      * @param parent   Parent of the dialog widget
  271.      * @param name     Name of the dialog widget
  272.      *
  273.      * @return List of selected items if multiple is true, else currently
  274.      *         selected item as a QStringList
  275.      */
  276.     static QStringList getItemList( const QString &caption,
  277.         const QString &label, const QStringList &list=QStringList(),
  278.         const QStringList &select=QStringList(), bool multiple=false,
  279.         bool *ok=0, QWidget *parent=0, const char *name=0 );
  280.  
  281.   private:
  282.  
  283.     KInputDialogPrivate* const d;
  284.     friend class KInputDialogPrivate;
  285. };
  286.  
  287. #endif // KINPUTDIALOG_H
  288.  
  289. /* vim: set ai et sw=2 ts=2
  290. */
  291.