|
|
/* * This file is part of the KDE Libraries * Copyright (C) 1999-2001 Mirko Boehm (mirko@kde.org) and * Espen Sand (espen@kde.org) * * This library is free software; you can redistribute it and/or * modify it under the terms of the GNU Library General Public * License as published by the Free Software Foundation; either * version 2 of the License, or (at your option) any later version. * * This library is distributed in the hope that it will be useful, * but WITHOUT ANY WARRANTY; without even the implied warranty of * MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the GNU * Library General Public License for more details. * * You should have received a copy of the GNU Library General Public License * along with this library; see the file COPYING.LIB. If not, write to * the Free Software Foundation, Inc., 59 Temple Place - Suite 330, * Boston, MA 02111-1307, USA. * */ #ifndef _KDIALOG_BASE_H_ #define _KDIALOG_BASE_H_ #include#include #include #include class KSeparator; class KURLLabel; class QBoxLayout; class QPixmap; /** * Used internally by @ref KDialogBase. * @internal */ class KDialogBaseButton; /** * Used internally by @ref KDialogBase. * @internal */ class KDialogBaseTile : public QObject { Q_OBJECT public: KDialogBaseTile( QObject *parent=0, const char *name=0 ); ~KDialogBaseTile(); void set( const QPixmap *pix ); const QPixmap *get() const; public slots: void cleanup(); signals: void pixmapChanged(); private: QPixmap *mPixmap; class KDialogBaseTilePrivate; KDialogBaseTilePrivate *d; }; /** * Provides basic functionality needed by nearly all dialogs. * * It offers the standard action buttons you'd expect to find in a * dialog as well as the capability to define at most three configurable * buttons. You can define a main widget that contains your specific * dialog layout or you can use a predefined layout. Currently, @p * TreeList/Paged, @p Tabbed, @p Plain, @p Swallow and @p IconList * mode layouts (faces) are available. * * The class takes care of the geometry management. You only need to define * a minimum size for the widget you want to use as the main widget. * * You can set a background tile (pixmap) for parts of the dialog. The * tile you select is shared by all instances of this class in your * application so that they all get the same look and feel. * * There is a tutorial available on http://developer.kde.org/ (NOT YET) * that contains * copy/paste examples as well a screenshots on how to use this class. * * @sect Standard buttons (action buttons): * * You select which buttons should be displayed, but you do not choose the * order in which they are displayed. This ensures a standard interface in * KDE. The button order can be changed, but this ability is only available * for a central KDE control tool. The following buttons are available: * OK, Cancel/Close, Apply/Try, Default, Help and three user definable * buttons: User1, User1 and User3. You must specify the text of the UserN * buttons. Each button has a virtual slot so you can overload the method * when required. The default slots emit a signal as well, so you can choose * to connect a signal instead of overriding the slot. * The default implementation of @ref slotHelp() will automatically enable * the help system if you have provided a path to the help text. * @ref slotCancel() and @ref slotClose() will run @ref QDialog::reject() * while @ref slotOk() will run @ref QDialog::accept(). You define a default * button in the constructor. * * If you don't not want any buttons at all because your dialog is special * in some way, then set the buttonMask argument in the constructor to zero * (0). The optional button box separator line should not be enabled * in this case. Note that the KDialogBase will animate a button press * when the user press Escape. The button that is enabled is either Cancel, * Close or the button that is defined by @ref setEscapeButton() The * animation will not take place when the buttonMask is zero. Your * custom dialog code should reimplement the @ref keyPressEvent and * animate the cancel button so that the dialog behaves like regular * dialogs. NOTE: None of the regular slots (like @ref slotOk() ) or * signals that are related to the standard action buttons will be used * when you don't use these buttons. * * @sect Dialog shapes: * * You can either use one of the prebuilt, easy to use, faces or * define your own main widget. The dialog provides ready to use * TreeList, Tabbed, Plain, Swallow and IconList faces. KDialogBase uses * the @ref KJanusWidget class internally to accomplish this. If you * use TreeList, Tabbed or IconList mode, then add pages with @ref addPage(). * If you want complete control of how the dialog contents should look, * then you can define a main widget by using @ref setMainWidget(). You * only need to set the minimum size of that widget and the dialog will * resize itself to fit this minimum size. The dialog is resizeable, but * can not be made smaller than its minimum size. * * @sect Layout: * * The dialog consists of a help area on top (becomes visible if you define * a help path and use @ref enableLinkedHelp()), the main area which is * the built-in dialog face or your own widget in the middle and by default * a button box at the bottom. The button box can also be placed at the * right edge (to the right of the main widget). Use * @ref setButtonBoxOrientation() to control this behavior. A separator * can be placed above the button box (or to the left when the button box * is at the right edge). Normally you specify that you want a separator * in the constructor, but you can use @ref enableButtonSeparator() as well. * * @sect Standard compliance: * * The class is derived from @ref KDialog, so you get automatic access to * the @ref KDialog::marginHint(), @ref KDialog::spacingHint() and the * extended @ref KDialog::setCaption() method. NOTE: The main widget you * use will be positioned inside the dialog using a margin (or border) * equal to @ref KDialog::marginHint(). You shall not add a margin yourself. * The example below (from kedit) shows how you use the top level widget * and its layout. The second argument (the border) to @ref QVBoxLayout * is 0. This situation is valid for @ref addPage , @ref addVBoxPage , * @ref addHBoxPage , @ref addGridPage , @ref makeMainWidget , * @ref makeVBoxMainWidget , @ref makeHBoxMainWidget and * @ref makeGridMainWidget as well. * * Example: * * * UrlDlg::UrlDlg( QWidget *parent, const QString& caption, * const QString& urltext) * : KDialogBase( parent, "urldialog", true, caption, Ok|Cancel, Ok, true ) * { * QWidget *page = new QWidget( this ); * setMainWidget(page); * QVBoxLayout *topLayout = new QVBoxLayout( page, 0, spacingHint() ); * * QLabel *label = new QLabel( caption, page, "caption" ); * topLayout->addWidget( label ); * * lineedit = new QLineEdit( urltext, page, "lineedit" ); * lineedit->setMinimumWidth(fontMetrics().maxWidth()*20); * topLayout->addWidget( lineedit ); * * topLayout->addStretch(10); * } ** * If you use @ref makeVBoxMainWidget(), then the dialog above can be made * simpler but you lose the ability to add a stretchable area: * ** UrlDlg::UrlDlg( QWidget *parent, const QString& caption, * const QString& urltext) * : KDialogBase( parent, "urldialog", true, caption, Ok|Cancel, Ok, true ) * { * QVBox *page = makeVBoxMainWidget(); * QLabel *label = new QLabel( caption, page, "caption" ); * * lineedit = new QLineEdit( urltext, page, "lineedit" ); * lineedit->setMinimumWidth(fontMetrics().maxWidth()*20); * } ** * This class can be used in many ways. Note that most KDE ui widgets * and many of KDE core applications use the KDialogBase so for more * inspiration you should study the code for these. * * @short A dialog base class which standard buttons and predefined layouts. * @author Mirko Boehm (mirko@kde.org) and Espen Sand (espen@kde.org) */ class KDialogBase : public KDialog { Q_OBJECT public: /** * @li @p Help - Show Help-button. * @li @p Default - Show Default-button. * @li @p Details - Show Details-button. * @li @p Ok - Show Ok-button. * @li @p Apply - Show Apply-button. * @li @p Try - Show Try-button. * @li @p Cancel - Show Cancel-button. * @li @p Close - Show Close-button. * @li @p User1 - Show User define-button 1. * @li @p User2 - Show User define-button 2. * @li @p User3 - Show User define-button 3. * @li @p No - Show No-button. * @li @p Yes - Show Yes-button. * @li @p Stretch - Used internally. Ignored when used in a constructor. * @li @p Filler - Used internally. Ignored when used in a constructor. */ enum ButtonCode { Help = 0x00000001, Default = 0x00000002, Ok = 0x00000004, Apply = 0x00000008, Try = 0x00000010, Cancel = 0x00000020, Close = 0x00000040, User1 = 0x00000080, User2 = 0x00000100, User3 = 0x00000200, No = 0x00000080, Yes = 0x00000100, Details = 0x00000400, Filler = 0x40000000, Stretch = 0x80000000 }; enum ActionButtonStyle { ActionStyle0=0, // KDE std ActionStyle1, ActionStyle2, ActionStyle3, ActionStyle4, ActionStyleMAX }; /** * @li @p TreeList - A dialog with a tree on the left side and a * representation of the contents on the right side. * @li @p Tabbed - A dialog using a @ref QTabWidget. * @li @p Plain - A normal dialog. * @li @p Swallow * @li @p IconList - A dialog with an iconlist on the left side and a * representation of the contents on the right side. */ enum DialogType { TreeList = KJanusWidget::TreeList, Tabbed = KJanusWidget::Tabbed, Plain = KJanusWidget::Plain, Swallow = KJanusWidget::Swallow, IconList = KJanusWidget::IconList }; private: struct SButton { SButton() { box = 0; mask = 0; style = 0; } QPushButton *append( int key, const QString &text ); void resize( bool sameWidth, int margin, int spacing, int orientation ); QPushButton *button( int key ); QWidget *box; int mask; int style; QListlist; }; public: /** * Constructor for the standard mode where you must specify the main * widget with @ref setMainWidget() . * * @param parent Parent of the dialog. * @param name Dialog name (for internal use only) * @param modal Controls dialog modality. If @p false, the rest of the * program interface (example: other dialogs) is accessible while * the dialog is open. * @param caption The dialog caption. Do not specify the application name * here. The class will take care of that. * @param buttonMask Specifies which buttons will be visible. If zero * (0) no button box will be made. * @param defaultButton Specifies which button will be marked as * the default. * @param separator If @p true, a separator line is drawn between the * action buttons and the main widget. * @param user1 User button1 text. * @param user2 User button2 text. * @param user3 User button3 text. */ KDialogBase( QWidget *parent=0, const char *name=0, bool modal=true, const QString &caption=QString::null, int buttonMask=Ok|Apply|Cancel, ButtonCode defaultButton=Ok, bool separator=false, const QString &user1=QString::null, const QString &user2=QString::null, const QString &user3=QString::null); /** * Constructor for the predefined layout mode where you specify the * kind of layout (face). * * @param dialogFace You can use TreeList, Tabbed, Plain, Swallow or * IconList. * @param caption The dialog caption. Do not specify the application name * here. The class will take care of that. * @param buttonMask Specifies which buttons will be visible. If zero * (0) no button box will be made. * @param defaultButton Specifies which button will be marked as * the default. * @param parent Parent of the dialog. * @param name Dialog name (for internal use only). * @param modal Controls dialog modality. If @p false, the rest of the * program interface (example: other dialogs) is accessible while * the dialog is open. * @param separator If @p true, a separator line is drawn between the * action buttons and the main widget. * @param user1 User button1 text. * @param user2 User button2 text. * @param user3 User button3 text. */ KDialogBase( int dialogFace, const QString &caption, int buttonMask, ButtonCode defaultButton, QWidget *parent=0, const char *name=0, bool modal=true, bool separator=false, const QString &user1=QString::null, const QString &user2=QString::null, const QString &user3=QString::null); /** * Constructor for a message box mode where the @p buttonMask can only * contain Yes, No, or Cancel. * * If you need other names you can rename * the buttons with @ref setButtonText(). The dialog box is not resizable * by default but this can be changed by @ref setInitialSize(). If you * select 'modal' to be true, the dialog will return Yes, No, or Cancel * when closed otherwise you can use the signals @ref yesClicked(), * @ref noClicked(), or @ref cancelClicked() to determine the state. * * @param caption The dialog caption. Do not specify the application name * here. The class will take care of that. * @param buttonMask Specifies which buttons will be visible. If zero * (0) no button box will be made. * @param defaultButton Specifies which button will be marked as * the default. * @param escapeButton Specifies which button will be activated by * when the dialog receives a @p Key_Escape keypress. * @param parent Parent of the dialog. * @param name Dialog name (for internal use only). * @param modal Controls dialog modality. If @p false, the rest of the * program interface (example: other dialogs) is accessible * while the dialog is open. * @param separator If @p true, a separator line is drawn between the * action buttons and the main widget. * @param user1 User button1 text. * @param user2 User button2 text. * @param user3 User button3 text. */ KDialogBase( const QString &caption, int buttonMask=Yes|No|Cancel, ButtonCode defaultButton=Yes, ButtonCode escapeButton=Cancel, QWidget *parent=0, const char *name=0, bool modal=true, bool separator=false, QString yes = QString::null, // i18n("&Yes") QString no = QString::null, // i18n("&No"), QString cancel = QString::null // i18n("&Cancel") ); /** * Destructor. */ ~KDialogBase(); /** * Destruct the Dialog delayed. * * You can call this function from * slots like @ref closeClicked() and @ref hidden(). * You should not use the dialog any more after * calling this function. */ void delayedDestruct(); /** * Sets the orientation of the button box. * * It can be @p Vertical or @p Horizontal. If @p Horizontal * (default), the button box is positioned at the bottom of the * dialog. If @p Vertical it will be placed at the right edge of the * dialog. * * @param orientation The button box orientation. */ void setButtonBoxOrientation( int orientation ); /** * Set the button that will be activated when the Escape key * is pressed. * * Normally you should not use this function. By default, * the Escape key is mapped to either the Cancel or the Close button * if one of these buttons are defined. The user expects that Escape will * cancel an operation so use this function with caution. * * @param id The button code. */ void setEscapeButton( ButtonCode id ); /** * Adjust the size of the dialog to fit the contents just before * @ref QDialog::exec() or @ref QDialog::show() is called. * * This method will not be called if the dialog has been explicitly * resized before showing it. **/ virtual void adjustSize(); virtual QSize sizeHint() const; virtual QSize minimumSizeHint() const; /** * Retrieve the empty page when the predefined layout is used in @p Plain * mode. * * This widget must used as the toplevel widget of your dialog * code. * * @return The widget or 0 if the predefined layout mode is not @p Plain * or if you don't use any predefined layout. */ QFrame *plainPage(); /** * Add a page to the dialog when the class is used in @p TreeList , * @p IconList or @p Tabbed mode. * * The returned widget must be used as the * toplevel widget for this particular page. * Note: The returned frame widget has no * layout manager associated with it. In order to use it you must * create a layout yourself as the example below illustrates: * * * QFrame *page = addPage( i18n("Layout") ); * QVBoxLayout *topLayout = new QVBoxLayout( page, 0, 6 ); * QLabel *label = new QLabel( i18n("Layout type"), page ); * topLayout->addWidget( label ); * .. ** * @param itemName String used in the list or as tab item name. * @param header Header text use in the list modes. Ignored in @p Tabbed * mode. If empty, the item text is used instead. * @param pixmap Used in @p IconList mode. You should prefer a pixmap * with size 32x32 pixels. * * @return The page widget which must be used as the toplevel widget for * the page. */ QFrame *addPage( const QString &item, const QString &header=QString::null, const QPixmap &pixmap=QPixmap() ); /** * This is like @ref addPage() just above, with the difference that the first * element is a list of strings. * * These strings are used to form a path * of folders down to the given page. The initial elements are names * for the folders, while the last element is the name of the page. * Note: This does yet only work for the @p TreeList face. Later this may * be added for the @p IconList face too. In other faces than the * @p TreeList, all the strings except the last one is ignored. **/ QFrame *addPage( const QStringList &items, const QString &header=QString::null, const QPixmap &pixmap=QPixmap() ); /** * Add a page to the dialog when the class is used in @p TreeList, * @p IconList or @p Tabbed mode. * * The returned widget must be used as the toplevel widget for * this particular page. The widget contains a @ref QVBoxLayout * layout so the widget children are lined up vertically. You can * use it as follows: * ** QVBox *page = addVBoxPage( i18n("Layout") ); * QLabel *label = new QLabel( i18n("Layout type"), page ); * .. ** * @param itemName String used in the list or as tab item name. * @param header Header text use in the list modes. Ignored in @p Tabbed * mode. If empty, the item text is used instead. * @param pixmap Used in @p IconList mode. You should prefer a pixmap * with size 32x32 pixels. * * @return The page widget which must be used as the toplevel widget for * the page. */ QVBox *addVBoxPage( const QString &itemName, const QString &header=QString::null, const QPixmap &pixmap=QPixmap() ); /** * This is like @ref addVBoxPage() just above, with the difference * that the first element is a list of strings. * * These strings are used to form a path * of folders down to the given page. The initial elements are names * for the folders, while the last element is the name of the page. * Note: This does yet only work for the @p TreeList face. Later this may * be added for the @p IconList face too. In other faces than the * @p TreeList, all the strings except the last one is ignored. **/ QVBox *addVBoxPage( const QStringList &items, const QString &header=QString::null, const QPixmap &pixmap=QPixmap() ); /** * Add a page to the dialog when the class is used in @p TreeList, * @p IconList or @p Tabbed mode. * * The returned widget must be used as the * toplevel widget for this particular page. The widget contains a * @ref QHBoxLayout layout so the widget children are lined up horizontally. * You can use it as follows: * * @param itemName String used in the list or as tab item name. * @param header Header text use in the list modes. Ignored in Tabbed * mode. If empty, the item text is used instead. * @param pixmap Used in IconList mode. You should prefer a pixmap * with size 32x32 pixels. * * @return The page widget which must be used as the toplevel widget for * the page. */ QHBox *addHBoxPage( const QString &itemName, const QString &header=QString::null, const QPixmap &pixmap=QPixmap() ); /** * This is like @ref addHBoxPage() just above, with the * difference that the first element is a list of strings. * * These strings are used to form a path * of folders down to the given page. The initial elements are names * for the folders, while the last element is the name of the page. * Note: This does yet only work for the @p TreeList face. Later this may * be added for the @p IconList face too. In other faces than the * @p TreeList, all the strings except the last one is ignored. **/ QHBox *addHBoxPage( const QStringList &items, const QString &header=QString::null, const QPixmap &pixmap=QPixmap() ); /** * Add a page to the dialog when the class is used in @p TreeList, * @p IconList or @p Tabbed mode. * * The returned widget must be used as the * toplevel widget for this particular page. The widget contains a * @ref QGridLayout layout so the widget children are positioned in a grid. * * @param n Specifies the number of columns if @p dir is @ref QGrid::Horizontal * or the number of rows if @p dir is @ref QGrid::Vertical. * @param dir Can be @ref QGrid::Horizontal or @ref QGrid::Vertical. * @param itemName String used in the list or as tab item name. * @param header Header text use in the list modes @p Ignored in @p Tabbed * mode. If empty, the item text is used instead. * @param pixmap Used in @p IconList mode. You should prefer a pixmap * with size 32x32 pixels. * * @return The page widget which must be used as the toplevel widget for * the page. */ QGrid *addGridPage( int n, QGrid::Direction dir, const QString &itemName, const QString &header=QString::null, const QPixmap &pixmap=QPixmap() ); /** * This is like @ref addGridPage() just above, with the difference * that the first element is a list of strings. * * These strings are used to form a path * of folders down to the given page. The initial elements are names * for the folders, while the last element is the name of the page. * Note: This does yet only work for the @p TreeList face. Later this may * be added for the @p IconList face too. In other faces than the * @p TreeList, all the strings except the last one is ignored. **/ QGrid *addGridPage( int n, QGrid::Direction dir, const QStringList &items, const QString &header=QString::null, const QPixmap &pixmap=QPixmap() ); /** * Set the icon used in @p TreeList Mode for the given path. * * @param path The path for which this icon should be shown. * @param pixmap The icon used. **/ void setFolderIcon(const QStringList &path,const QPixmap &pixmap); /** * Make a main widget. * * The function will make a @ref QFrame widget * and use @ref setMainWidget() to register it. You can @em not use this * function more than once, @em not if you have already defined a * main widget with @ref setMainWidget() and @em not if you have used the * constructor where you define the face (@p Plain, @p Swallow, @p Tabbed, * @p TreeList). * * @return The main widget or 0 if any of the rules described above * were broken. */ QFrame *makeMainWidget(); /** * Make a main widget. * * The function will make a @ref QVBox widget * and use @ref setMainWidget() to register it. You @em can use this * function more than once, @em not if you have already defined a * main widget with @ref setMainWidget() and @em not if you have used the * constructor where you define the face (@p Plain, @p Swallow, @p Tabbed, * @p TreeList, @p IconList). * * @return The main widget or 0 if any of the rules described above * were broken. */ QVBox *makeVBoxMainWidget(); /** * Make a main widget. * * The function will make a @ref QHBox widget * and use @ref setMainWidget() to register it. You can @em not use this * function more than once, @em not if you have already defined a * main widget with @ref setMainWidget() and @p not if you have used the * constructor where you define the face (@p Plain, @p Swallow, @p Tabbed, * @p TreeList, @p IconList). * * @return The main widget or 0 if any of the rules described above * were broken. */ QHBox *makeHBoxMainWidget(); /** * Make a main widget. * * The function will make a @ref QGrid widget * and use @ref setMainWidget() to register it. You can @em not use this * function more than once, @em not if you have already defined a * main widget with @ref #setMainWidget and @em not if you have used the * constructor where you define the face (Plain, Swallow, Tabbed, * TreeList, IconList). * * @param n Specifies the number of columns if 'dir' is QGrid::Horizontal * or the number of rows if 'dir' is QGrid::Vertical. * @param dir Can be QGrid::Horizontal or QGrid::Vertical. * * @return The main widget or 0 if any of the rules described above * were broken. */ QGrid *makeGridMainWidget( int n, QGrid::Direction dir ); /** * Hide or display the a separator line drawn between the action * buttons an the main widget. */ void enableButtonSeparator( bool state ); /** * Hide or display a general action button. * * Only buttons that have * been created in the constructor can be displayed. This method will * not create a new button. * * @param id Button identifier. * @param state true display the button(s). */ void showButton( ButtonCode id, bool state ); /** * Hide or display the OK button. * * The OK button must have * been created in the constructor to be displayed. * * @param state If @p true, display the button(s). */ void showButtonOK( bool state ); /** * Hide or display the Apply button. * * The Apply button must have * been created in the constructor to be displayed. * * @param state true display the button(s). */ void showButtonApply( bool state ); /** * Hide or display the Cancel button. The Cancel button must have * been created in the constructor to be displayed. * * @param state @p true display the button(s). */ void showButtonCancel( bool state ); /** * Set the page with @p index to be displayed. * * This method will only * work when the dialog is using the predefined shape of TreeList, * IconList or Tabbed. * * @param index Index of the page to be shown. * @return @p true if the page is shown, @p false otherwise. */ bool showPage( int index ); /** * Retrieve the index of the active page. * * This method will only work when the dialog is using the * predefined shape of Tabbed, TreeList or IconList. * * @return The page index or -1 if there is no active page. */ int activePageIndex() const; /** * Returns the index of a page created with @ref #addPage(), * @ref #addVBoxPage(), @ref addHBoxPage() or @ref #addGridPage(). * You can can compare this index with the value returned from * @ref #activePageIndex() if you need to do some page specific actions * in your code. * * The returned index will never change so you can safely use this * function once and save the value. * * @param widget The widget returned by @ref #addPage(), @ref #addVBoxPage(), * @ref #addHBoxPage() or @ref #addGridPage(). * * @return The index or -1 if the face is not Tabbed, TreeList or * IconList */ int pageIndex( QWidget *widget ) const; /** * Set the main user definable widget. * * If the dialog is using the predefined Swallow mode, the widget will * be reparented to the internal swallow control widget. If the dialog * is being used in the standard mode then the @p widget must have the * dialog as parent. * * @param widget The widget to be displayed as main widget. If it * is 0, then the dialog will show an empty space of 100x100 pixels * instead. */ void setMainWidget( QWidget *widget ); /** * Retrieve the main widget if any. * * @return The current main widget. Can be 0 if no widget has been defined. */ QWidget *mainWidget(); /** * @deprecated * Use @ref mainWidget() instead */ QWidget *getMainWidget(); /** * Convenience method. * * Freezes the dialog size using the minimum size * of the dialog. This method should only be called right before * @ref show() or @ref exec(). */ void disableResize(); /** * Convenience method. Set the initial dialog size. * * This method should * only be called right before @ref show() or @ref exec(). The initial * size will be * ignored if smaller than the dialog's minimum size. * * @param s Startup size. * @param noResize If @p true the dialog can not be resized. */ void setInitialSize( const QSize &s, bool noResize=false ); /** * Convenience method. Addd a size to the default minimum size of a * dialog. * * This method should only be called right before @ref show() or * @ref exec(). * * @param s Size added to minimum size. * @param noResize If @p true the dialog can not be resized. */ void incInitialSize( const QSize &s, bool noResize=false ); /** * Sets the text of the OK button. * * If the default parameters are used * (that is, if no parameters are given) the standard texts are set: * The button shows "OK", the tooltip contains "Accept settings." * (internationalized) and the quickhelp text explains the standard * behavior of the OK button in settings dialogs. * * @param text Button text. * @param tooltip Tooltip text. * @param quickhelp Quick help text. */ void setButtonOKText( const QString &text=QString::null, const QString &tooltip=QString::null, const QString &quickhelp=QString::null ); /** * Sets the text of the Apply button. * * If the default parameters are * used (that is, if no parameters are given) the standard texts are set: * The button shows "Apply", the tooltip contains "Apply settings." * (internationalized) and the quickhelp text explains the standard * behavior of the apply button in settings dialogs. * * @param text Button text. * @param tooltip Tooltip text. * @param quickhelp Quick help text. */ void setButtonApplyText( const QString &text=QString::null, const QString &tooltip=QString::null, const QString &quickhelp=QString::null ); /** * Set the text of the Cancel button. * * If the default parameters are * used (that is, if no parameters are given) the standard texts are set: * The button shows "Cancel", everything else will not be set. * * @param text Button text. * @param tooltip Tooltip text. * @param quickhelp Quick help text. */ void setButtonCancelText( const QString &text=QString::null, const QString &tooltip=QString::null, const QString &quickhelp=QString::null ); /** * Set the text of any button. * * @param id The button identifier. * @param text Button text. */ void setButtonText( ButtonCode id, const QString &text ); /** * Set the tooltip text of any button. * * @param id The button identifier. * @param text Button text. */ void setButtonTip( ButtonCode id, const QString &text ); /** * Sets the "What's this?" text of any button. * * @param id The button identifier. * @param text Button text. */ void setButtonWhatsThis( ButtonCode id, const QString &text ); /** * This function has only effect in TreeList mode. * * Defines how the tree list widget is resized when the dialog is * resized horizontally. By default the tree list keeps its width * when the dialog becomes wider. * * @param state The resize mode. If false (default) the tree list keeps * its current width when the dialog becomes wider. */ void setTreeListAutoResize( bool state ); /** * This function has only effect in TreeList mode. * * This tells the widgets whether the icons given in the @ref addPage, * @ref addVBoxPage, @ref addHBoxPage, or @ref addGridPage methods should * be shown in the TreeList. * * Note: This method must be called before calling any of the methods * which add icons to the page. * * @param state If true the icons are shown. **/ void setShowIconsInTreeList(bool state); /** * This function has only effect in TreeList mode. * * This tells the widgets whether the root should be decorated. * For details see @ref QListView::setRootIsDecorated * * @param state Root will be decorated if true. **/ void setRootIsDecorated( bool state ); /** * This function has only effect in IconList mode. * * Defines how the icon list widget is displayed. By default it is * the widgets in the dialog pages that decide the minimum height * of the dialog. A vertical scrollbar can be used in the icon list * area. * * @param state The visibility mode. If true, the minimum height is * adjusted so that every icon in the list is visible at the * same time. The vertical scrollbar will never be visible. */ void setIconListAllVisible( bool state ); /** * Check whether the background tile is set or not. * * @return @p true if there is defined a background tile. */ static bool haveBackgroundTile(); /** * Retrieve a pointer to the background tile if there is one. * * @return The tile pointer or 0 if no tile is defined. * **/ static const QPixmap *backgroundTile(); /** * @deprecated * Use @ref backgroundTile() instead. */ static const QPixmap *getBackgroundTile(); /** * Set the background tile. * * If it is Null (0), the background image is deleted. * * @param pix The background tile. */ static void setBackgroundTile( const QPixmap *pix ); /** * Enable hiding of the background tile (if any). * * @param state @p true will make the tile visible. */ void showTile( bool state ); /** * @deprecated * Do not use this method. It is included for compatibility reasons. * * This method returns the border widths in all directions the dialog * needs for itself. Respect this, or get bad looking results. * The references are upper left x (@p ulx), upper left y (@p uly), * lower right x (@p lrx), and lower left y (@p lly). * The results are differences in pixels from the * dialogs corners. */ void getBorderWidths( int& ulx, int& uly, int& lrx, int& lry ) const; /** * @deprecated * Do not use this method. It is included for compatibility reasons. * * This method returns the contents rectangle of the work area. Place * your widgets inside this rectangle, and use it to set up * their geometry. Be careful: The rectangle is only valid after * resizing the dialog, as it is a result of the resizing process. * If you need the "overhead" the dialog needs for its elements, * use @ref getBorderWidths(). */ QRect getContentsRect(); /** * Calculate the size hint for the dialog. * * With this method it is easy to calculate a size hint for a * dialog derived from KDialogBase if you know the width and height of * the elements you add to the widget. The rectangle returned is * calculated so that all elements exactly fit into it. Thus, you may * set it as a minimum size for the resulting dialog. * * You should not need to use this method and never if you use one of * the predefined shapes. * * @param w The width of you special widget. * @param h The height of you special widget. * @return The minimum width and height of the dialog using @p w and @p h * as the size of the main widget. */ QSize calculateSize( int w, int h ); /** * Retrieve the help link text. * * If no text has been defined, * "Get help..." (internationalized) is returned. * * @return The help link text. */ QString helpLinkText(); /** * Retrieve the action button that corresponds to the @p id. * * Normally * you should not use this function. @em Never delete the object returned * by this function. See also @ref enableButton(), @ref showButton(), * @ref setButtonTip(), @ref setButtonWhatsThis(), and @ref setButtonText(). * * @param id Integer identifier of the button. * @return The action button or 0 if the button does not exists. * */ QPushButton *actionButton( ButtonCode id ); public slots: /** * Enable or disable (gray out) a general action button. * * @param id Button identifier. * @param state @p true enables the button(s). */ void enableButton( ButtonCode id, bool state ); /** * Enable or disable (gray out) the OK button. * * @param state @p true enables the button. */ void enableButtonOK( bool state ); /** * Enable or disable (gray out) the Apply button. * * @param state true enables the button. */ void enableButtonApply( bool state ); /** * Enable or disable (gray out) the Cancel button. * * @param state true enables the button. */ void enableButtonCancel( bool state ); /** * Display or hide the help link area on the top of the dialog. * * @param state @p true will display the area. */ void enableLinkedHelp( bool state ); /** * Set the text that is shown as the linked text. * * If text is empty, * the text "Get help..." (internationalized) is used instead. * * @param text The link text. */ void setHelpLinkText( const QString &text ); /** * Set the help path and topic. * * @param anchor Defined anchor in your docbook sources * @param appname Defines the appname the help belongs to * If empty it's the current one */ void setHelp( const QString &anchor, const QString &appname = QString::null ); /** * Connected to help link label. */ void helpClickedSlot( const QString & ); /** * Set the status of the Details button. */ void setDetails(bool showDetails); /** * Set the widget that gets shown when "Details" is enabled. * * The dialog takes over ownership of the widget. * Any previously set widget gets deleted. */ void setDetailsWidget(QWidget *detailsWidget); /** * This method is called automatically whenever the background has * changed. You do not need to use this method. */ void updateBackground(); signals: /** * The Help button was pressed. This signal is only emitted if * @ref slotHelp() is not replaced. */ void helpClicked(); /** * The Default button was pressed. This signal is only emitted if * @ref slotDefault() is not replaced. */ void defaultClicked(); /** * The User3 button was pressed. This signal is only emitted if * @ref slotUser3() is not replaced. */ void user3Clicked(); /** * The User2 button was pressed. This signal is only emitted if * @ref slotUser2() is not replaced. */ void user2Clicked(); /** * The User1 button was pressed. This signal is only emitted if * @ref slotUser1() is not replaced. */ void user1Clicked(); /** * The Apply button was pressed. This signal is only emitted if * @ref slotApply() is not replaced. */ void applyClicked(); /** * The Try button was pressed. This signal is only emitted if * @ref slotTry() is not replaced. */ void tryClicked(); /** * The OK button was pressed. This signal is only emitted if * @ref slotOk() is not replaced. */ void okClicked(); /** * The Yes button was pressed. This signal is only emitted if * @ref slotYes() is not replaced. */ void yesClicked(); /** * The No button was pressed. This signal is only emitted if * @ref slotNo() is not replaced. */ void noClicked(); /** * The Cancel button was pressed. This signal is only emitted if * @ref slotCancel() is not replaced. */ void cancelClicked(); /** * The Close button was pressed. This signal is only emitted if * @ref slotClose() is not replaced. */ void closeClicked(); /** * Do not use this signal. Is is kept for compatibility reasons. * Use @ref applyClicked() instead. */ void apply(); /** * The background tile has changed. */ void backgroundChanged(); /** * The dialog is about to be hidden. * * A dialog is hidden after a user clicks a button that ends * the dialog or when the user switches to another desktop or * minimizes the dialog. */ void hidden(); /** * The dialog has finished. * * A dialog emits finished after a user clicks a button that ends * the dialog. * * This signal is also emitted when you call @ref hide() * * If you have stored a pointer to the * dialog do @em not try to delete the pointer in the slot that is * connected to this signal. * * You should use @ref delayedDestruct() instead. */ void finished(); /** * The detailsWidget is about to get shown. This is your last chance * to call setDetailsWidget if you haven't done so yet. */ void aboutToShowDetails(); protected: /** * Maps some keys to the actions buttons. F1 is mapped to the Help * button if present and Escape to the Cancel or Close if present. The * button action event is animated. */ virtual void keyPressEvent( QKeyEvent *e ); /** * Emits the @ref hidden signal. You can connect to that signal to * detect when a dialog has been closed. */ virtual void hideEvent( QHideEvent * ); /** * Detects when a dialog is being closed from the window manager * controls. If the Cancel or Close button is present then the button * is activated. Otherwise standard @ref QDialog behavior * will take place. */ virtual void closeEvent( QCloseEvent *e ); protected slots: /** * Activated when the Help button has been clicked. If a help * text has been defined, the help system will be activated. */ virtual void slotHelp(); /** * Activated when the Default button has been clicked. */ virtual void slotDefault(); /** * Activated when the Details button has been clicked. * @see detailsClicked(bool) * (This function is not virtual to maintain BC) * KDE3.0: Make virtual for consistency with the other functions. */ void slotDetails(); /** * Activated when the User3 button has been clicked. */ virtual void slotUser3(); /** * Activated when the User2 button has been clicked. */ virtual void slotUser2(); /** * Activated when the User1 button has been clicked. */ virtual void slotUser1(); /** * Activated when the Ok button has been clicked. The * @ref QDialog::accept() is activated. */ virtual void slotOk(); /** * Activated when the Apply button has been clicked. */ virtual void slotApply(); /** * Activated when the Try button has been clicked. */ virtual void slotTry(); /** * Activated when the Yes button has been clicked. The * @ref QDialog::done( Yes ) is activated. */ virtual void slotYes(); /** * Activated when the Yes button has been clicked. The * @ref QDialog::done( No ) is activated. */ virtual void slotNo(); /** * Activated when the Cancel button has been clicked. The * @ref QDialog::reject() is activated in regular mode and * @ref QDialog::done( Cancel ) when in message box mode. */ virtual void slotCancel(); /** * Activated when the Close button has been clicked. The * @ref QDialog::reject() is activated. */ virtual void slotClose(); /** * Do not use this slot. Is is kept for compatibility reasons. * Activated when the Apply button has been clicked */ virtual void applyPressed(); /** * Updates the margins and spacings. */ void updateGeometry(); /** * Deletes the dialog. */ void slotDelayedDestruct(); private: /** * Prepares the layout that manages the widgets of the dialog */ void setupLayout(); /** * Prepares a relay that is used to send signals between * all KDialogBase instances of a program. Should only be used in the * constructor. */ void makeRelay(); /** * Makes the button box and all the buttons in it. This method must * only be ran once from the constructor. * * @param buttonMask Specifies what buttons will be made. * @param defaultButton Specifies what button we be marked as the * default. * @param user1 User button1 text. * @param user2 User button2 text. * @param user2 User button3 text. */ void makeButtonBox( int mask, ButtonCode defaultButton, const QString &user1 = QString::null, const QString &user2 = QString::null, const QString &user3 = QString::null ); /** * Sets the action button that is marked as default and has focus. * * @param p The action button. * @param isDefault If true, make the button default * @param isFocus If true, give the button focus. */ void setButtonFocus( QPushButton *p, bool isDefault, bool isFocus ); /** * Prints an error message using qDebug if @ref makeMainWidget , * @ref makeVBoxMainWidget , @ref makeHBoxMainWidget or * @ref makeGridMainWidget failed. */ void printMakeMainWidgetError(); private slots: /** * Sets the action button order according to the 'style'. * * @param style The style index. */ void setButtonStyle( int style ); private: QBoxLayout *mTopLayout; QWidget *mMainWidget; KURLLabel *mUrlHelp; KJanusWidget *mJanus; KSeparator *mActionSep; SButton mButton; bool mIsActivated; QString mAnchor; QString mHelpApp; QString mHelpLinkText; static KDialogBaseTile *mTile; bool mShowTile; bool mMessageBoxMode; int mButtonOrientation; ButtonCode mEscapeButton; class KDialogBasePrivate; KDialogBasePrivate *d; }; #endif
| Generated by: dfaure on kde.faure.org on Thu Jan 17 22:16:05 2002, using kdoc 2.0a53. |