libkdegames/kcarddialog.h

   1 /*
   2     This file is part of the KDE games library
   3     Copyright 2008 Andreas Pakulat <apaku@gmx.de>
   4
   5     This library is free software; you can redistribute it and/or
   6     modify it under the terms of the GNU Library General Public
   7     License version 2 as published by the Free Software Foundation.
   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 #ifndef __KCARDDIALOG_H_
  20 #define __KCARDDIALOG_H_
  21
  22 #include <QtGui/QWidget>
  23 #include <kdialog.h>
  24 #include <kconfig.h>
  25
  26 #include <libkdegames_export.h>
  27
  28 class QListWidgetItem;
  29 class KCardWidgetPrivate;
  30 class KCardWidget;
  31
  32 /**
  33  * \class KCardDialog kcarddialog.h <KCardDialog>
  34  *
  35  * @short A convenience class to display a standalone card selection dialog.
  36  *
  37  * This is a simple convenience class to embed the @ref KCardWidget into a
  38  * KDialog that has an Ok and Cancel button and an appropriate caption.
  39  *
  40  * Usage Example:
  41  * \code
  42  *   KConfigGroup(KGlobal::config(),"CardOptions");
  43  *   KCardWidget* cardwiget = new KCardwidget();
  44  *   cardwidget->readSettings(configGroup);
  45  *   KCardDialog dlg(cardwidget);
  46  *   if(dlg.exec() == QDialog::Accepted)
  47  *   {
  48  *     cardwidget->saveSettings(configGroup);
  49  *     configGroup.sync();
  50  *     //now update the graphics
  51  *   }
  52  * \endcode
  53  *
  54  */
  55 class KDEGAMES_EXPORT KCardDialog : public KDialog
  56 {
  57   Q_OBJECT
  58 public:
  59   KCardDialog(KCardWidget* widget);
  60 };
  61
  62 /**
  63  * \class KCardWidget kcarddialog.h <KCardDialog>
  64  *
  65  * @short A carddeck selection widget for card games.
  66  *
  67  * The KCardWidget provides a widget for interactive carddeck selection.
  68  * It gives cardgames an easy to use interface to select front and
  69  * back of the card sets. As card sets the KDE default cardsets are
  70  * offered as well as used specified ones.
  71  *
  72  * This class can be used in two ways: Embedding it into an existing
  73  * dialog or creating a small KDialog just for the carddeck selection.
  74  *
  75  * Card sets (front and back) are identified by their (translated) names.
  76  *
  77  * Here you can see a card widget in action
  78  * @image html "kcarddialog.png" KCardwidget
  79  *
  80  * You can use a KConfigGroup to initialize the state of the widget or
  81  * let the widget store its current state to a config group.
  82  *
  83  * For an example usage see @ref KCardDialog.
  84  *
  85  */
  86 class KDEGAMES_EXPORT KCardWidget : public QWidget
  87 {
  88   Q_OBJECT
  89
  90 public:
  91
  92    /**
  93     * Constructs a card deck selection widget.
  94     *
  95     * @param parent The parent widget of the widget, if any.
  96     */
  97    KCardWidget (QWidget* parent = NULL);
  98
  99    /**
 100     * Read the settings from a config file
 101     * @param group the configuration group
 102     */
 103    void readSettings(const KConfigGroup& group);
 104
 105    /**
 106     * Destructs a card deck selection dialog.
 107     */
 108    ~KCardWidget();
 109
 110    /**
 111     * Saves the KCardWidget config into a config file.
 112     * These settings are used by @ref KCardWidget.
 113     */
 114    void saveSettings(KConfigGroup& group) const;
 115
 116    /**
 117     * set the name of the card deck (back side)
 118     * @param name the new name to select as back side
 119     */
 120    void setBackName(const QString& name);
 121
 122    /**
 123     * Retrieve the name of the card deck (back side) from the widget.
 124     * @return The deck name.
 125     */
 126    QString backName() const;
 127
 128    /**
 129     * Retrieve the locking status
 130     * @return true if the backside selection is locked to the frontside
 131     */
 132    bool isLocked() const;
 133
 134    /**
 135     * Retrieve the current state of the "Show old style decks" checkbox
 136     * @return whether or not fixed size card decks are shown in the list
 137     */
 138    bool isFixedSizeAllowed() const;
 139
 140    /**
 141     * set the name of the card set (front side)
 142     * @param name the new name to select as front side
 143     */
 144    void setFrontName(const QString& name);
 145
 146    /**
 147     * Retrieve the name of the card set (front side) from the dialog.
 148     * @return The card set name.
 149     */
 150    QString frontName() const;
 151
 152 public Q_SLOTS:
 153    /**
 154     * Allow the user to select fixed size cards
 155     * @param fixedSizeAllowed if set to true will show scalable and also fixed
 156     * size card decks in the dialog
 157     */
 158    void setFixedSizeAllowed(bool fixedSizeAllowed);
 159
 160    /**
 161     * enable or disable locked selection, when locking is enabled the user
 162     * can only choose the front sides and the backside will be determined
 163     * from the frontside
 164     * @param locked whether to lock the front and backside selection
 165     */
 166    void setLocked(bool locked);
 167
 168 protected:
 169     void insertCardIcons();
 170
 171     /**
 172      * Insert the back sides into the list view.
 173      */
 174     void insertDeckIcons();
 175
 176     /**
 177      * Configure the dialog GUI.
 178      */
 179     void setupGUI();
 180
 181 protected Q_SLOTS:
 182     /**
 183      * Called by the card set list view when a new item was selected.
 184      */
 185     void updateFront();
 186
 187      /**
 188      * Called by the card deck list view when a new item was selected.
 189      * @param current The newly selected item.
 190      * @param last    The previously selected item.
 191      */
 192     void updateBack();
 193
 194 private:
 195    /**
 196     * The dialog data.
 197     */
 198    KCardWidgetPrivate* const d;
 199 };
 200
 201 #endif