kleopatra/utils/kleo_kicondialog.h

   1 /* vi: ts=8 sts=4 sw=4
   2  *
   3  * This file is part of the KDE project, module kfile.
   4  * Copyright (C) 2000 Geert Jansen <jansen@kde.org>
   5  *           (C) 2000 Kurt Granroth <granroth@kde.org>
   6  *           (C) 1997 Christoph Neerfeld <chris@kde.org>
   7  *           (C) 2002 Carsten Pfeiffer <pfeiffer@kde.org>
   8  *
   9  * This is free software; it comes under the GNU Library General
  10  * Public License, version 2. See the file "COPYING.LIB" for the
  11  * exact licensing terms.
  12  */
  13
  14 #ifndef __KLEO_KICONDIALOG_H__
  15 #define __KLEO_KICONDIALOG_H__
  16
  17 #include <QtCore/QStringList>
  18 #include <QtGui/QPushButton>
  19
  20 #include <kdialog.h>
  21 #include <klistwidget.h>
  22
  23 class KIconLoader;
  24
  25 namespace Kleo {
  26 namespace KioAvoidance {
  27
  28 /**
  29  * Icon canvas for KIconDialog.
  30  */
  31 class KIconCanvas: public KListWidget
  32 {
  33     Q_OBJECT
  34
  35 public:
  36     /**
  37      * Creates a new icon canvas.
  38      *
  39      * @param parent The parent widget.
  40      */
  41     explicit KIconCanvas(QWidget *parent=0L);
  42
  43     /**
  44      * Destroys the icon canvas.
  45      */
  46     ~KIconCanvas();
  47
  48     /**
  49      * Load icons into the canvas.
  50      */
  51     void loadFiles(const QStringList& files);
  52
  53     /**
  54      * Returns the current icon.
  55      */
  56     QString getCurrent() const;
  57
  58 public Q_SLOTS:
  59     /**
  60      * Call this slot to stop the loading of the icons.
  61      */
  62     void stopLoading();
  63
  64 Q_SIGNALS:
  65     /**
  66      * Emitted when the current icon has changed.
  67      */
  68     void nameChanged(const QString&);
  69
  70     /**
  71      * This signal is emitted when the loading of the icons
  72      * has started.
  73      *
  74      * @param count The number of icons to be loaded.
  75      */
  76     void startLoading(int count);
  77
  78     /**
  79      * This signal is emitted whenever an icon has been loaded.
  80      *
  81      * @param number The number of the currently loaded item.
  82      */
  83     void progress(int number);
  84
  85     /**
  86      * This signal is emitted when the loading of the icons
  87      * has been finished.
  88      */
  89     void finished();
  90
  91 private:
  92     class KIconCanvasPrivate;
  93     KIconCanvasPrivate* const d;
  94
  95     Q_DISABLE_COPY(KIconCanvas)
  96
  97     Q_PRIVATE_SLOT(d, void _k_slotLoadFiles())
  98     Q_PRIVATE_SLOT(d, void _k_slotCurrentChanged(QListWidgetItem *item))
  99 };
 100
 101
 102 /**
 103  * Dialog for interactive selection of icons. Use the function
 104  * getIcon() let the user select an icon.
 105  *
 106  * @short An icon selection dialog.
 107  */
 108 class KIconDialog: public KDialog
 109 {
 110     Q_OBJECT
 111
 112 public:
 113     /**
 114      * Constructs an icon selection dialog using the global iconloader.
 115      *
 116      * @param parent The parent widget.
 117      */
 118     explicit KIconDialog(QWidget *parent=0L);
 119
 120     /**
 121      * Constructs an icon selection dialog using a specific iconloader.
 122      *
 123      * @param loader The icon loader to use.
 124      * @param parent The parent widget.
 125      */
 126     explicit KIconDialog(KIconLoader *loader, QWidget *parent=0);
 127
 128     /**
 129      * Destructs the dialog.
 130      */
 131     ~KIconDialog();
 132
 133     /**
 134      * Sets a strict icon size policy for allowed icons. When true,
 135      * only icons of the specified group's size in getIcon() are shown.
 136      * When false, icons not available at the desired group's size will
 137      * also be selectable.
 138      */
 139     void setStrictIconSize(bool b);
 140     /**
 141      * Returns true if a strict icon size policy is set.
 142      */
 143     bool strictIconSize() const;
 144     /**
 145      * sets a custom icon directory
 146      */
 147     void setCustomLocation( const QString& location );
 148
 149     /**
 150      * Sets the size of the icons to be shown / selected.
 151      * @see KIconLoader::StdSizes
 152      * @see iconSize
 153      */
 154     void setIconSize(int size);
 155
 156     /**
 157      * Returns the iconsize set via setIconSize() or 0, if the default
 158      * iconsize will be used.
 159      */
 160     int iconSize() const;
 161
 162     /**
 163      * Allows you to set the same parameters as in the class method
 164      * getIcon(), as well as two additional parameters to lock
 165      * the choice between system and user dirs and to lock the custom user
 166      * dir itself.
 167      */
 168
 169     void setup( KIconLoader::Group group,
 170                 KIconLoader::Context context = KIconLoader::Application,
 171                 bool strictIconSize = false, int iconSize = 0,
 172                 bool user = false, bool lockUser = false,
 173                 bool lockCustomDir = false );
 174
 175     /**
 176      * exec()utes this modal dialog and returns the name of the selected icon,
 177      * or QString() if the dialog was aborted.
 178      * @returns the name of the icon, suitable for loading with KIconLoader.
 179      * @see getIcon
 180      */
 181     QString openDialog();
 182
 183     /**
 184      * show()es this dialog and emits a newIcon(const QString&) signal when
 185      * successful. QString() will be emitted if the dialog was aborted.
 186      */
 187     void showDialog();
 188
 189     /**
 190      * Pops up the dialog an lets the user select an icon.
 191      *
 192      * @param group The icon group this icon is intended for. Providing the
 193      * group shows the icons in the dialog with the same appearance as when
 194      * used outside the dialog.
 195      * @param context The initial icon context. Initially, the icons having
 196      * this context are shown in the dialog. The user can change this.
 197      * @param strictIconSize When true, only icons of the specified group's size
 198      * are shown, otherwise icon not available in the desired group's size
 199      * will also be selectable.
 200      * @param iconSize the size of the icons -- the default of the icongroup
 201      *        if set to 0
 202      * @param user Begin with the "user icons" instead of "system icons".
 203      * @param parent The parent widget of the dialog.
 204      * @param caption The caption to use for the dialog.
 205      * @return The name of the icon, suitable for loading with KIconLoader.
 206      */
 207     static QString getIcon(KIconLoader::Group group=KIconLoader::Desktop,
 208                            KIconLoader::Context context=KIconLoader::Application,
 209                            bool strictIconSize=false, int iconSize = 0,
 210                            bool user=false, QWidget *parent=0,
 211                            const QString &caption=QString());
 212
 213 Q_SIGNALS:
 214     void newIconName(const QString&);
 215
 216 protected Q_SLOTS:
 217     void slotOk();
 218
 219 private:
 220     class KIconDialogPrivate;
 221     KIconDialogPrivate* const d;
 222
 223     Q_DISABLE_COPY(KIconDialog)
 224
 225     Q_PRIVATE_SLOT(d, void _k_slotContext(int))
 226     Q_PRIVATE_SLOT(d, void _k_slotStartLoading(int))
 227     Q_PRIVATE_SLOT(d, void _k_slotProgress(int))
 228     Q_PRIVATE_SLOT(d, void _k_slotFinished())
 229     Q_PRIVATE_SLOT(d, void _k_slotAcceptIcons())
 230 #ifndef QT_NO_FILEDIALOG
 231     Q_PRIVATE_SLOT(d, void _k_slotBrowse())
 232 #endif
 233     Q_PRIVATE_SLOT(d, void _k_slotOtherIconClicked())
 234     Q_PRIVATE_SLOT(d, void _k_slotSystemIconClicked())
 235 };
 236
 237
 238 /**
 239  * A pushbutton for choosing an icon. Pressing on the button will open a
 240  * KIconDialog for the user to select an icon. The current icon will be
 241  * displayed on the button.
 242  *
 243  * @see KIconDialog
 244  * @short A push button that allows selection of an icon.
 245  */
 246 class KIconButton: public QPushButton
 247 {
 248     Q_OBJECT
 249     Q_PROPERTY( QString icon READ icon WRITE setIcon RESET resetIcon )
 250     Q_PROPERTY( int iconSize READ iconSize WRITE setIconSize)
 251     Q_PROPERTY( bool strictIconSize READ strictIconSize WRITE setStrictIconSize )
 252
 253 public:
 254     /**
 255      * Constructs a KIconButton using the global iconloader.
 256      *
 257      * @param parent The parent widget.
 258      */
 259     explicit KIconButton(QWidget *parent=0L);
 260
 261     /**
 262      * Constructs a KIconButton using a specific KIconLoader.
 263      *
 264      * @param loader The icon loader to use.
 265      * @param parent The parent widget.
 266      */
 267     KIconButton(KIconLoader *loader, QWidget *parent);
 268     /**
 269      * Destructs the button.
 270      */
 271     ~KIconButton();
 272
 273     /**
 274      * Sets a strict icon size policy for allowed icons. When true,
 275      * only icons of the specified group's size in setIconType are allowed,
 276      * and only icons of that size will be shown in the icon dialog.
 277      */
 278     void setStrictIconSize(bool b);
 279     /**
 280      * Returns true if a strict icon size policy is set.
 281      */
 282     bool strictIconSize() const;
 283
 284     /**
 285      * Sets the icon group and context. Use KIconLoader::NoGroup if you want to
 286      * allow icons for any group in the given context.
 287      */
 288     void setIconType(KIconLoader::Group group, KIconLoader::Context context, bool user=false);
 289
 290     /**
 291      * Sets the button's initial icon.
 292      */
 293     void setIcon(const QString& icon);
 294
 295     void setIcon(const QIcon& icon);
 296
 297     /**
 298      * Resets the icon (reverts to an empty button).
 299      */
 300     void resetIcon();
 301
 302     /**
 303      * Returns the name of the selected icon.
 304      */
 305     const QString &icon() const;
 306
 307     /**
 308      * Sets the size of the icon to be shown / selected.
 309      * @see KIconLoader::StdSizes
 310      * @see iconSize
 311      */
 312     void setIconSize( int size );
 313
 314     /**
 315      * Returns the iconsize set via setIconSize() or 0, if the default
 316      * iconsize will be used.
 317      */
 318     int iconSize() const;
 319
 320 Q_SIGNALS:
 321     /**
 322      * Emitted when the icon has changed.
 323      */
 324     void iconChanged(const QString &icon);
 325
 326 private:
 327     class KIconButtonPrivate;
 328     KIconButtonPrivate* const d;
 329
 330     Q_DISABLE_COPY(KIconButton)
 331
 332     Q_PRIVATE_SLOT(d, void _k_slotChangeIcon())
 333     Q_PRIVATE_SLOT(d, void _k_newIconName(const QString&))
 334 };
 335
 336 }
 337 }
 338
 339 #endif // __KLEO_KICONDIALOG_H__