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 / kcarddialog.h < prev    next >
Encoding:
C/C++ Source or Header  |  2005-10-10  |  11.2 KB  |  346 lines
  1. /*
  2.     This file is part of the KDE games library
  3.     Copyright (C) 2000 Martin Heni (martin@heni-online.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 <qstring.h>
  23. #include <kdialogbase.h>
  24. #include <qmap.h> // TODO: remove - it is in kcarddialog.cpp now; left here for source compatibility
  25.  
  26. #include <kdemacros.h>
  27. class QIconViewItem;
  28.  
  29. class KConfig;
  30.  
  31. class KCardDialogPrivate;
  32.  
  33. /**
  34.  * @short A carddeck selection dialog for card games.
  35.  *
  36.  * The KCardDialog provides a dialog for interactive carddeck selection.
  37.  * It gives cardgames an easy to use interface to select front and
  38.  * back of the card sets. As card sets the KDE default cardsets are
  39.  * offered as well as used specified ones.
  40.  *
  41.  * In most cases, the simplest
  42.  * use of this class is the static method KCardDialog::getCardDeck,
  43.  * which pops up the dialog, allows the user to select a carddeck, and
  44.  * returns when the dialog is closed. Only if you really need some specific
  45.  * behaviour or if you overwrite the dialog you need all the other access
  46.  * functions.
  47.  *
  48.  * Example:
  49.  *
  50.  * \code
  51.  *      QString deck,card;
  52.  *      int result = KCardDialog::getCardDeck(deck,card );
  53.  *      if ( result == KCardDialog::Accepted )
  54.  *            ...
  55.  * \endcode
  56.  *
  57.  * Here you can see a card dialog in action
  58.  * @image html "kcarddialog.png" KCarddialog
  59.  *
  60.  * KCardDialog::getCardDeck takes a lot of different parameters which are
  61.  * probably very useful. You can e.g. use the parameters randomDeck and
  62.  * randomCardDir to give the end-user the ability to choose a random
  63.  * deck/carddir. You have to save the value of those parameters in your config
  64.  * file - that's why the parameters are needed. 
  65.  *
  66.  * You can also provide a KConfig pointer (usually kapp->config()). This
  67.  * pointer is used to store information about the dialog in an own group
  68.  * ("KCardDailog"). 
  69.  * So you can just ignore the randomCardDir and randomDeck
  70.  * values and call KCardDialog::getConfigCardDeck instead. The only reson
  71.  * for this function is to read a previously written configuration and give you
  72.  * the information about it. This way you don't have to save any configuration
  73.  * on your own - KCardDialog does this for you.
  74.  *
  75.  * Another Parameter for KCardDialog::getCardDeck is scale. This pointer
  76.  * to a double variable contains the scaling factor the user has chosen in the
  77.  * dialog (the scale box won't be shown if you don't provide this parameter).
  78.  * You might want to check out QPixmap::xFrom which gives you access to
  79.  * scaling. You can e.g. use
  80.  * \code
  81.  * QWMatrix m;
  82.  * m.scale(s,s);
  83.  * pixmap.xForm(m);
  84.  * \endcode
  85.  * to scale your pixmap.
  86.  *
  87.  * @author Martin Heni <martin@heni-online.de>
  88.  * @version $Id: kcarddialog.h 465369 2005-09-29 14:33:08Z mueller $
  89.  */
  90. class KDE_EXPORT KCardDialog : public KDialogBase
  91. {
  92.   Q_OBJECT
  93.  
  94. public:
  95.  
  96.   /**
  97.    *  @li @p Both - both are shown
  98.    *  @li @p NoDeck - The deck (back) selection is not shown
  99.    *  @li @p NoCards - The cards (front) selection is not shown
  100.    */
  101.    enum CardFlags { Both=0, NoDeck=0x01, NoCards=0x02 };
  102.  
  103.    /**
  104.    * Constructs a card deck selection dialog.
  105.    *
  106.    * @param parent The parent widget of the dialog, if any.
  107.    * @param name The name of the dialog.
  108.    * @param flags Specifies whether the dialog is modal or not.
  109.    */
  110.    KCardDialog (QWidget* parent = NULL,const char* name = NULL,
  111.                 CardFlags flags = Both);
  112.    /**
  113.    * Destructs a card deck selection dialog.
  114.    */
  115.    ~KCardDialog();
  116.  
  117.    /**
  118.    * Creates a modal carddeck dialog, lets the user choose a deck,
  119.    * and returns when the dialog is closed.
  120.    *
  121.    * @param deck a reference to the filename used as backside of the
  122.    *        cards. It is an absolute path and can directly be loaded as
  123.    *        pixmap.
  124.    *
  125.    * @param carddir a reference to the directory name used as front of the
  126.    *        cards. The directory contains the card images as 1.png to 52.png
  127.    *
  128.    * @param parent an optional pointer to the parent window of the dialog
  129.    *
  130.    * @param flags what to show
  131.    *
  132.    * @param randomDeck if this pointer is non-zero, *ok is set to TRUE if
  133.    *        the user wants a random deck otherwise to FALSE. Use this in the
  134.    *        config file of your game to load a random deck on startup.
  135.    *        See @ref getRandomDeck()
  136.    *
  137.    * @param randomCardDir if this pointer is non-zero, *ok is set to TRUE if
  138.    *        the user wants a random card otherwise to FALSE.
  139.    *        Use this in the config file of your game to load a random card
  140.    *        foregrounds on startup.
  141.    *        See @ref getRandomCardDir()
  142.    *
  143.    * @param scale If non-zero a box is shown which provides the possibility to
  144.    *        change the size of the cards. The desired scaling factor is returned to the
  145.    *        game in this variable.
  146.    *
  147.    * @param conf If non-zero KCardDialog reads the initial settings for 
  148.    *        this dialog from the applications config file and stores them there
  149.    *        when the dialog is closed. You can just use getConfigCardDeck
  150.    *        to get the deck/carddir the user selected before. Note that the 
  151.    *        parameters randomDeck and randomCardDir overwrite the initial settings from the
  152.    *        config file.
  153.    *
  154.    * @return QDialog::result().
  155.    */
  156.    static int getCardDeck(QString &deck,QString &carddir, QWidget *parent=0,
  157.                           CardFlags flags=Both, bool* randomDeck=0,
  158.                           bool* randomCardDir=0, double* scale=0, KConfig* conf=0);
  159.  
  160.    /**
  161.     * Read the configuration from the applications rc file and put the
  162.     * previously chosen deck/frontside in the parameter deck and carddir.
  163.     *
  164.     * You probably want to use this function on startup of your program so that
  165.     * the user gets exactly the card/frontside he/she chose before. Note that
  166.     * you don't have to care whether the user wants to get a random carddeck or
  167.     * not as this function takes care of this.
  168.     * @param conf The config file to read from
  169.     * @param deck This will contain the chosen deck from the config file (or a
  170.     * random deck if this is desired according to the config)
  171.     * @param cardDir This will contain the chosen cardDir from the config file (or a
  172.     * random cardDir if this is desired according to the config)
  173.     * @param scale The scaling factor (usually 1)
  174.     **/
  175.    static void getConfigCardDeck(KConfig* conf, QString& deck, QString& cardDir, double& scale);
  176.  
  177.    /**
  178.    * Returns the default path to the card deck backsides. You want
  179.    * to use this usually before the user used the card dialog the first
  180.    * time to get a default deck. You can assume that
  181.    * \code
  182.    *   getDefaultDeckPath()
  183.    * \endcode
  184.    * is a valid deck.
  185.    *
  186.    * @return The default path
  187.    */
  188.    static QString getDefaultDeck();
  189.  
  190.    /**
  191.    * Returns the default path to the card frontsides. You want
  192.    * to use this usually before the user used the card dialog the first
  193.    * time to get an default deck. You can assume that
  194.    * \code
  195.    *   getCardPath(getDefaultCardPath(), *)
  196.    * \endcode
  197.    * are valid cards for * from 1 to 52.
  198.    *
  199.    * @return returns the path to the card directory
  200.    */
  201.    static QString getDefaultCardDir();
  202.  
  203.     /**
  204.     * Returns the path to the card frontside specified in dir carddir
  205.     *
  206.     * @param index the card to open
  207.     * @param carddir The carddir which's path shall be searched for
  208.     * @return returns the path to the card
  209.     */
  210.     static QString getCardPath(const QString &carddir, int index);
  211.  
  212.    /**
  213.     * Returns a random deck in deckPath()
  214.     * @return A random deck
  215.     **/
  216.     static QString getRandomDeck();
  217.  
  218.    /**
  219.     * Returns a random directory of cards
  220.     * @return A random card dir
  221.     **/
  222.     static QString getRandomCardDir();
  223.  
  224.    /**
  225.     * Show or hides the "random backside" checkbox
  226.     * @param s Shows the checkbox if true otherwise hides it
  227.     **/
  228.    void showRandomDeckBox(bool s);
  229.  
  230.    /**
  231.     * Show or hides the "random foreside" checkbox
  232.     * @param s Shows the checkbox if true otherwise hides it
  233.     **/
  234.    void showRandomCardDirBox(bool s);
  235.  
  236.    /**
  237.    * Returns the chosen deck, which is a valid path to a imagefile.
  238.    *
  239.    * @return The deck
  240.    */
  241.    const QString& deck() const;
  242.  
  243.    /**
  244.    * Sets the default deck.
  245.    * @param file The full path to an image file
  246.    */
  247.    void setDeck(const QString& file);
  248.  
  249.    /**
  250.    * @return The chosen card directory
  251.    */
  252.    const QString& cardDir() const;
  253.  
  254.    /**
  255.    * Sets the default card directory.
  256.    * @param dir The full path to an card directory
  257.    */
  258.    void setCardDir(const QString& dir);
  259.  
  260.    /**
  261.    * @return the flags set to the dialog
  262.    */
  263.    CardFlags flags() const;
  264.  
  265.    /**
  266.    * Creates the default widgets in the dialog. Must be called after
  267.    * all flags are set. This is only needed if you do NOT use the
  268.    * getCardDeck static function which provides all calls for you.
  269.    */
  270.    void setupDialog(bool showResizeBox = false);
  271.  
  272.    /**
  273.     * @return TRUE if the selected deck is a random deck (i.e. the user checked
  274.     * the random checkbox) otherwise FALSE
  275.     **/
  276.    bool isRandomDeck() const;
  277.  
  278.    /**
  279.     * @return TRUE if the selected carddir is a random dir (i.e. the user
  280.     * checked the random checkbox) otherwise FALSE
  281.     **/
  282.    bool isRandomCardDir() const;
  283.  
  284.    /**
  285.     * @return TRUE if the global checkbox was selected
  286.     **/
  287.    bool isGlobalDeck() const;
  288.  
  289.    /**
  290.     * @return TRUE if the global checkbox was selected
  291.     **/
  292.    bool isGlobalCardDir() const;
  293.  
  294.    /**
  295.     * @return The scaling factor of the card pixmap
  296.     **/
  297.    double cardScale() const;
  298.  
  299.    /**
  300.     * Load the default settings into the dialog (e.g. whether the "use random
  301.     * deck" checkbox is checked or not).
  302.     **/
  303.    void loadConfig(KConfig* conf);
  304.  
  305.    /**
  306.     * Saves the KCardDialog config into a config file. This should be the
  307.     * applications config file - KCardDialog creates an own group
  308.     * ("KCardDialog"). These settings are used by @ref loadConfig and @ref
  309.     * getConfigCardDeck.
  310.     **/
  311.    void saveConfig(KConfig* conf);
  312.  
  313.  
  314. protected:
  315.     void insertCardIcons();
  316.     void insertDeckIcons();
  317.  
  318.     static void getGlobalDeck(QString& cardDir, bool& random);
  319.     static void getGlobalCardDir(QString& deck, bool& random);
  320.  
  321.     static QString getDeckName(const QString& desktop);
  322.  
  323.     /**
  324.      * @return the groupname used by functions like @ref saveConfig and @ref
  325.      * loadConfig.
  326.      **/
  327.     static QString group();
  328.  
  329. protected slots:
  330.    void slotDeckClicked(QIconViewItem *);
  331.    void slotCardClicked(QIconViewItem *);
  332.    void slotRandomCardDirToggled(bool on);
  333.    void slotRandomDeckToggled(bool on);
  334.    void slotCardResized(int);
  335.    void slotDefaultSize();
  336.    void slotSetGlobalDeck();
  337.    void slotSetGlobalCardDir();
  338.  
  339. private:
  340.    static void init();
  341.  
  342.    KCardDialogPrivate* d;
  343. };
  344.  
  345. #endif
  346.