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 / kchatbase.h < prev    next >
Encoding:
C/C++ Source or Header  |  2005-10-10  |  15.1 KB  |  511 lines
  1. /*
  2.     This file is part of the KDE games library
  3.     Copyright (C) 2001 Andreas Beckermann (b_mann@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 __KCHATBASE_H__
  20. #define __KCHATBASE_H__
  21.  
  22. #include <qframe.h>
  23. #include <qstring.h>
  24. #include <qlistbox.h>
  25.  
  26. #include <kglobalsettings.h>
  27. #include <kdemacros.h>
  28. class QListBoxItem;
  29.  
  30. class KConfig;
  31.  
  32.  
  33. class KChatBaseTextPrivate;
  34.  
  35. /**
  36.  * A QListBoxText implementation for KChatBase.
  37.  *
  38.  * It supports different colors, text fonts, ...
  39.  *
  40.  * A KChatBaseText consists of two text items: first the player part then the
  41.  * text part. This honors KChatBase::addMessage which also uses both. 
  42.  * You can leave the player part out if you don't need it - there won't be any
  43.  * difference. 
  44.  *
  45.  * You can set different colors and fonts for both parts. In the future there
  46.  * will probably some kind of KChatBaseDialog which offers the user the ability
  47.  * to configure things like color and font on the fly.
  48.  **/
  49. class KChatBaseText : public QListBoxText
  50. {
  51. public:
  52.  
  53.     /**
  54.      * Constructs a KChatBaseText object with the player and text part
  55.      **/
  56.     KChatBaseText(const QString& player, const QString& text);
  57.     
  58.     /**
  59.      * Constructs a KChatBaseText object without player part
  60.      **/
  61.     KChatBaseText(const QString& text);
  62.     
  63.     /**
  64.      * Destruct a KChatBaseText object.
  65.      **/
  66.     virtual ~KChatBaseText();
  67.  
  68.     /**
  69.      * Set the name part of a message. A message is usually shown like
  70.      * "name: text" and you can change both parts independently.
  71.      * 
  72.      * @see setMessage
  73.      * @param name The name of the sender (e.g. the player)
  74.      **/
  75.     void setName(const QString& name);
  76.  
  77.     /**
  78.      * Set the text part of a message. A message is usually shown like
  79.      * "name: message" and you can change both parts independently.
  80.      * 
  81.      * See also setName
  82.      * @param message The message that has been sent
  83.      **/
  84.     void setMessage(const QString& message);
  85.  
  86.     /**
  87.      * @return The name part of a message. 
  88.      * @see setName
  89.      **/
  90.     const QString& name() const;
  91.  
  92.     /**
  93.      * @return The message text. 
  94.      * @see setMessage
  95.      **/
  96.     const QString& message() const;
  97.  
  98.     /**
  99.      * You can set the font of the sender name independently of the message
  100.      * itself. This font is used as the "name: " part of the message.
  101.      * @return The font that is used for the name
  102.      **/
  103.     QFont nameFont() const;
  104.  
  105.     /**
  106.      * You can set the font of the message independently of the sender name.
  107.      * This font is used as the text part of the message.
  108.      * @return The font thaz is used for message text
  109.      **/
  110.     QFont messageFont() const;
  111.  
  112.     /**
  113.      * Set the font for the name. 
  114.      * @see nameFont
  115.      * @param font A pointer to the name font. Only the pointer is stored so
  116.      * don't delete the object. This way there is only one object for a lot
  117.      * of messages in memory.
  118.      **/
  119.     void setNameFont(const QFont* font);
  120.  
  121.     /**
  122.      * Set the font for the message text.
  123.      * @see messageFont
  124.      * @param font A pointer to the message font. Only the pointer is stored so
  125.      * don't delete the object! This way there is only one object for a lot
  126.      * of messages in memory.
  127.      **/
  128.     void setMessageFont(const QFont* font);
  129.  
  130.     /**
  131.      **/
  132.     virtual int width(QListBox* ) const;
  133.  
  134.     /**
  135.      **/
  136.     virtual int height(QListBox* ) const;
  137.  
  138. protected:
  139.     /**
  140.      **/
  141.     virtual void paint(QPainter*);
  142.  
  143. private:
  144.     void init();
  145.  
  146. private:
  147.     KChatBaseTextPrivate* d;
  148. };
  149.  
  150.  
  151. class KChatBasePrivate;
  152.  
  153. /**
  154.  * @short The base class for chat widgets
  155.  *
  156.  * This is the base class for both KChat and KGameChat. KGameChat is the class
  157.  * you want to use if you write a KGame based game as it will do most things for
  158.  * you. KChat is more or less the same but not KGame dependant
  159.  *
  160.  * KChatBase provides a complete chat widget, featuring different sending means
  161.  * (e.g. "send to all", "send to player1", "send to group2" and so on - see 
  162.  * addSendingEntry). It also provides full auto-completion capabilities (see
  163.  * KCompletion and KLineEdit) which defaults to disabled. The user can
  164.  * change this by right-clicking on the KLineEdit widget and selecting the
  165.  * desired behaviour. You can also change this manually by calling 
  166.  * setCompletionMode.
  167.  *
  168.  * To make KChatBase useful you have to overwrite at least returnPressed.
  169.  * Here you should send the message to all of your clients (or just some of
  170.  * them, depending on sendingEntry).
  171.  *
  172.  * To add a message just call addMessage with the nickname of the player
  173.  * who sent the message and the message itself. If you don't want to use
  174.  * layoutMessage by any reason you can also call addItem directly. But you
  175.  * should better replace layoutMessage instead.
  176.  *
  177.  * You probably don't want to use the abstract class KChatBase directly but use
  178.  * one of the derived classess KChat or KGameChat. The latter is the
  179.  * widget of choice if you develop a KGame application as you don't have to
  180.  * do anything but providing a KGame object.
  181.  *
  182.  * @author Andreas Beckermann <b_mann@gmx.de>
  183.  **/
  184. class KDE_EXPORT KChatBase : public QFrame
  185. {
  186.     Q_OBJECT
  187. public:
  188.     /**
  189.      * @param parent The parent widget for this widget.
  190.      * @param noComboBox If true then the combo box where the player can
  191.      * choose where to send messages to (either globally or just to some
  192.      * players) will not be added.
  193.      **/
  194.     KChatBase(QWidget* parent, bool noComboBox = false);
  195.  
  196.     /**
  197.      * Destruct the KChatBase object
  198.      *
  199.      * Also calls saveConfig
  200.      **/
  201.     virtual ~KChatBase();
  202.  
  203.     enum SendingIds {
  204.         SendToAll = 0
  205.     };
  206.  
  207.     /**
  208.      * @return The name that will be shown for messages from this widget. Either the
  209.      * string that was set by setFromName or the name of the player
  210.      * that was set by setFromPlayer
  211.      **/
  212.     virtual const QString& fromName() const = 0;
  213.  
  214.     /**
  215.      * Adds a new entry in the combo box. The default is "send to all
  216.      * players" only. This function is provided for convenience. You can
  217.      * also call inserSendingEntry with index = -1.
  218.      * See also nextId!
  219.      * @param text The text of the new entry
  220.      * @param id An ID for this entry. This must be unique for this
  221.      * entry. It has nothing to do with the position of the entry in the
  222.      * combo box. See nextId
  223.      * @return True if successful, otherwise false (e.g. if the id is already used)
  224.      **/
  225.     bool addSendingEntry(const QString& text, int id);
  226.  
  227.     /**
  228.      * Inserts a new entry in the combo box.
  229.      * @param text The entry
  230.      * @param id An ID for this entry. This must be unique for this
  231.      * entry. It has nothing to do with the position of the entry in the
  232.      * combo box! 
  233.      * @see nextId
  234.      * @param index The position of the entry. If -1 the entry will be added
  235.      * at the bottom
  236.      * @return True if successful, otherwise false (e.g. if the id is already used)
  237.      **/
  238.     bool insertSendingEntry(const QString& text, int id, int index = -1);
  239.  
  240.     /**
  241.      * This changes a combo box entry.
  242.      * @param text The new text of the entry
  243.      * @param id The ID of the item to be changed
  244.      **/
  245.     void changeSendingEntry(const QString& text, int id);
  246.  
  247.     /**
  248.      * This selects a combo box entry.
  249.      * @param id The ID of the item to be selected
  250.      **/
  251.     void setSendingEntry(int id);
  252.  
  253.     /**
  254.      * Removes the entry with the ID id from the combo box. Note that id is
  255.      * _not_ the index of the entry! 
  256.      * @see addSendingEntry
  257.      * @param id The unique id of the entry
  258.      **/
  259.     void removeSendingEntry(int id);
  260.  
  261.     /**
  262.      * @return The _unique ID_ of the sending entry that has been selected.
  263.      * @see addSendingEntry
  264.      *
  265.      * Note that the entry "send to all" _always_ uses
  266.      * KChatBase::SendToAll, i.e. 0 as id!
  267.      **/
  268.     int sendingEntry() const;
  269.     
  270.     /**
  271.      * @return The index of the combo box entry with the given id
  272.      **/
  273.     int findIndex(int id) const;
  274.  
  275.     /**
  276.      * @return An ID that has not yet been used in the combo box.
  277.      * @see addSendingEntry
  278.      **/
  279.     int nextId() const;
  280.  
  281.     /**
  282.      * @return True if this widget is able to send messages (see 
  283.      * returnPressed) and false if not. The default implementation returns
  284.      * the value which has been set by setAcceptMessage (true by
  285.      * default)
  286.      **/
  287.     virtual bool acceptMessage() const;
  288.  
  289.     /**
  290.      * See KLineEdit::setCompletionMode
  291.      **/
  292.     void setCompletionMode(KGlobalSettings::Completion mode);
  293.  
  294.     /**
  295.      * Set the font that used used for the name part of a message. See also
  296.      * nameFont and setBothFont
  297.      **/
  298.     void setNameFont(const QFont& font);
  299.     
  300.     /**
  301.      * Set the font that used used for the message part of a message.
  302.      * @see messageFont, setBothFont
  303.      **/
  304.     void setMessageFont(const QFont& font);
  305.  
  306.     /**
  307.      * This sets both - nameFont and messageFont to font. You
  308.      * probably want to use this if you don't wish to distinguish between
  309.      * these parts of a message.
  310.      * @param font A font used for both nameFont and messageFont
  311.      **/
  312.     void setBothFont(const QFont& font);
  313.  
  314.     /**
  315.      * Same as setNameFont but applies only to system messages.
  316.      * @see layoutSystemMessage
  317.      **/
  318.     void setSystemNameFont(const QFont& font);
  319.  
  320.     /**
  321.      * Same as setMessageFont but applies only to system messages.
  322.      * @see layoutSystemMessage
  323.      **/
  324.     void setSystemMessageFont(const QFont& font);
  325.  
  326.     /**
  327.      * Same as setBothFont but applies only to system messages.
  328.      * @see layoutSystemMessage
  329.      **/
  330.     void setSystemBothFont(const QFont& font);
  331.  
  332.     /**
  333.      * This font should be used for the name (the "from: " part) of a
  334.      * message. layoutMessage uses this to set the font using
  335.      * KChatBaseText::setNameFont but if you want to overwrite 
  336.      * layoutMessage you should do this yourself.
  337.      * @return The font that is used for the name part of the message.
  338.      **/
  339.     const QFont& nameFont() const;
  340.  
  341.     /**
  342.      * This font should be used for a message. layoutMessage sets the
  343.      * font of a message using KChatBaseText::setMessageFont but if ypu
  344.      * replace layoutMessage with your own function you should use
  345.      * messageFont() yourself.
  346.      * @return The font that is used for a message
  347.      **/
  348.     const QFont& messageFont() const;
  349.  
  350.     /**
  351.      * Same as systemNameFont but applies only to system messages.
  352.      * @see layoutSystemMessage
  353.      **/
  354.     const QFont& systemNameFont() const;
  355.  
  356.     /**
  357.      * Same as systemMessageFont but applies only to system messages.
  358.      * @see layoutSystemMessage
  359.      **/
  360.     const QFont& systemMessageFont() const;
  361.  
  362.     /**
  363.      * Save the configuration of the dialog to a KConfig object. If
  364.      * the supplied KConfig pointer is NULL then kapp->config() is used
  365.      * instead (and the group is changed to "KChatBase") butr the current
  366.      * group is restored at the end.
  367.      * @param conf A pointer to the KConfig object to save the config
  368.      * to. If you use 0 then kapp->config() is used and the group is changed
  369.      * to "KChatBase" (the current group is restored at the end).
  370.      **/
  371.     virtual void saveConfig(KConfig* conf = 0);
  372.  
  373.     /**
  374.      * Read the configuration from a KConfig object. If the pointer is
  375.      * NULL kapp->config() is used and the group is changed to "KChatBase".
  376.      * The current KConfig::group is restored after this call.
  377.      **/
  378.     virtual void readConfig(KConfig* conf = 0);
  379.  
  380.     /**
  381.      * Set the maximum number of items in the list. If the number of item
  382.      * exceeds the maximum as many items are deleted (oldest first) as
  383.      * necessary. The number of items will never exceed this value.
  384.      * @param maxItems the maximum number of items. -1 (default) for
  385.      * unlimited.
  386.      **/
  387.     void setMaxItems(int maxItems);
  388.  
  389.     /**
  390.      * Clear all messages in the list.
  391.      **/
  392.     void clear();
  393.  
  394.     /**
  395.      * @return The maximum number of messages in the list. -1 is unlimited. See also
  396.      * setMaxItems
  397.      **/
  398.     int maxItems() const;
  399.  
  400.  
  401. public slots:
  402.     /**
  403.      * Add a text in the listbox. See also signalSendMessage()
  404.      *
  405.      * Maybe you want to replace this with a function that creates a nicer text
  406.      * than "fromName: text"
  407.      *
  408.      * Update: the function layoutMessage is called by this now. This
  409.      * means that you will get user defined outlook on the messages :-)
  410.      * @param fromName The player who sent this message
  411.      * @param text The text to be added 
  412.      **/
  413.     virtual void addMessage(const QString& fromName, const QString& text);
  414.  
  415.     /**
  416.      * This works just like addMessage but adds a system message. 
  417.      * layoutSystemMessage is used to generate the displayed item. System
  418.      * messages will have a different look than player messages.
  419.      *
  420.      * You may wish to  use this to display status information from your game.
  421.      **/
  422.     virtual void addSystemMessage(const QString& fromName, const QString& text);
  423.  
  424.     /**
  425.      * This member function is mainly internally used to add a message. It
  426.      * is called by addMessage which creates a single text from a
  427.      * player name and a text. You will hardly ever use this - but if you
  428.      * need it it will be here ;-)
  429.      *
  430.      * But you may want to replace this in a derived class to create a
  431.      * non-default (maybe nicer ;-) ) behaviour
  432.      * @param item The QListBoxItem that is being added
  433.      **/
  434.     virtual void addItem(const QListBoxItem* item);
  435.  
  436.  
  437.     /**
  438.      * This clears all messages in the view. Note that only the messages are
  439.      * cleared, not the sender names in the combo box!
  440.      **/
  441.     void slotClear();
  442.  
  443.     /**
  444.      * @param a If false this widget cannot send a message until
  445.      * setAcceptMessage(true) is called
  446.      **/
  447.     void setAcceptMessage(bool a);
  448.     
  449. signals:
  450.     /**
  451.      * Emitted when the user right-clicks on a list item. 
  452.      * @see QListBox::rightButtonClicked
  453.      **/
  454.     void rightButtonClicked(QListBoxItem*, const QPoint&);
  455.  
  456. protected:
  457.     /**
  458.      * This is called whenever the user pushed return ie wants to send a
  459.      * message.
  460.      *
  461.      * Note that you MUST add the message to the widget when this function
  462.      * is called as it has already been added to the KCompletion object
  463.      * of the KLineEdit widget!
  464.      *
  465.      * Must be implemented in derived classes
  466.      * @param text The message to be sent
  467.      **/
  468.     virtual void returnPressed(const QString& text) = 0;
  469.  
  470.     /**
  471.      * Replace to customise the combo box.
  472.      *
  473.      * Default: i18n("Send to %1).arg(name)
  474.      * @param name The name of the player
  475.      * @return The string as it will be shown in the combo box
  476.      **/
  477.     virtual QString comboBoxItem(const QString& name) const;
  478.  
  479.     /**
  480.      * Create a QListBoxItem for this message. This function is not yet
  481.      * written usefully - currently just a QListBoxTex object is
  482.      * created which shows the message in this format: "fromName: text".
  483.      * This should fit most peoples needs but needs further improvements.
  484.      **/
  485.     virtual QListBoxItem* layoutMessage(const QString& fromName, const QString& text);
  486.  
  487.     /**
  488.      * Create a QListBoxItem for this message. This does the same as
  489.      * layoutMessage but generates a system message. You might want to
  490.      * use such a message to display e.g. status information from your game.
  491.      *
  492.      * The default implementation just prepends "--- ".
  493.      **/
  494.     virtual QListBoxItem* layoutSystemMessage(const QString& fromName, const QString& text);
  495.  
  496. private slots:
  497.     /**
  498.      * Check if a text was entered and if acceptMessage returns true. 
  499.      * Then add the message to the KCompletion object of the KLineEdit
  500.      * widget and call returnPressed
  501.      **/
  502.     void slotReturnPressed(const QString&);
  503.  
  504. private:
  505.     void init(bool noComboBox);
  506.  
  507.     KChatBasePrivate* d;
  508. };
  509.  
  510. #endif
  511.