summaryrefslogtreecommitdiffstats
path: root/libkdegames/kchatbase.h
diff options
context:
space:
mode:
Diffstat (limited to 'libkdegames/kchatbase.h')
-rw-r--r--libkdegames/kchatbase.h510
1 files changed, 510 insertions, 0 deletions
diff --git a/libkdegames/kchatbase.h b/libkdegames/kchatbase.h
new file mode 100644
index 00000000..07f786f9
--- /dev/null
+++ b/libkdegames/kchatbase.h
@@ -0,0 +1,510 @@
+/*
+ This file is part of the KDE games library
+ Copyright (C) 2001 Andreas Beckermann (b_mann@gmx.de)
+
+ This library is free software; you can redistribute it and/or
+ modify it under the terms of the GNU Library General Public
+ License version 2 as published by the Free Software Foundation.
+
+ 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., 51 Franklin Street, Fifth Floor,
+ Boston, MA 02110-1301, USA.
+*/
+#ifndef __KCHATBASE_H__
+#define __KCHATBASE_H__
+
+#include <qframe.h>
+#include <qstring.h>
+#include <qlistbox.h>
+
+#include <kglobalsettings.h>
+#include <kdemacros.h>
+class QListBoxItem;
+
+class KConfig;
+
+
+class KChatBaseTextPrivate;
+
+/**
+ * A QListBoxText implementation for KChatBase.
+ *
+ * It supports different colors, text fonts, ...
+ *
+ * A KChatBaseText consists of two text items: first the player part then the
+ * text part. This honors KChatBase::addMessage which also uses both.
+ * You can leave the player part out if you don't need it - there won't be any
+ * difference.
+ *
+ * You can set different colors and fonts for both parts. In the future there
+ * will probably some kind of KChatBaseDialog which offers the user the ability
+ * to configure things like color and font on the fly.
+ **/
+class KChatBaseText : public QListBoxText
+{
+public:
+
+ /**
+ * Constructs a KChatBaseText object with the player and text part
+ **/
+ KChatBaseText(const QString& player, const QString& text);
+
+ /**
+ * Constructs a KChatBaseText object without player part
+ **/
+ KChatBaseText(const QString& text);
+
+ /**
+ * Destruct a KChatBaseText object.
+ **/
+ virtual ~KChatBaseText();
+
+ /**
+ * Set the name part of a message. A message is usually shown like
+ * "name: text" and you can change both parts independently.
+ *
+ * @see setMessage
+ * @param name The name of the sender (e.g. the player)
+ **/
+ void setName(const QString& name);
+
+ /**
+ * Set the text part of a message. A message is usually shown like
+ * "name: message" and you can change both parts independently.
+ *
+ * See also setName
+ * @param message The message that has been sent
+ **/
+ void setMessage(const QString& message);
+
+ /**
+ * @return The name part of a message.
+ * @see setName
+ **/
+ const QString& name() const;
+
+ /**
+ * @return The message text.
+ * @see setMessage
+ **/
+ const QString& message() const;
+
+ /**
+ * You can set the font of the sender name independently of the message
+ * itself. This font is used as the "name: " part of the message.
+ * @return The font that is used for the name
+ **/
+ QFont nameFont() const;
+
+ /**
+ * You can set the font of the message independently of the sender name.
+ * This font is used as the text part of the message.
+ * @return The font thaz is used for message text
+ **/
+ QFont messageFont() const;
+
+ /**
+ * Set the font for the name.
+ * @see nameFont
+ * @param font A pointer to the name font. Only the pointer is stored so
+ * don't delete the object. This way there is only one object for a lot
+ * of messages in memory.
+ **/
+ void setNameFont(const QFont* font);
+
+ /**
+ * Set the font for the message text.
+ * @see messageFont
+ * @param font A pointer to the message font. Only the pointer is stored so
+ * don't delete the object! This way there is only one object for a lot
+ * of messages in memory.
+ **/
+ void setMessageFont(const QFont* font);
+
+ /**
+ **/
+ virtual int width(QListBox* ) const;
+
+ /**
+ **/
+ virtual int height(QListBox* ) const;
+
+protected:
+ /**
+ **/
+ virtual void paint(QPainter*);
+
+private:
+ void init();
+
+private:
+ KChatBaseTextPrivate* d;
+};
+
+
+class KChatBasePrivate;
+
+/**
+ * @short The base class for chat widgets
+ *
+ * This is the base class for both KChat and KGameChat. KGameChat is the class
+ * you want to use if you write a KGame based game as it will do most things for
+ * you. KChat is more or less the same but not KGame dependant
+ *
+ * KChatBase provides a complete chat widget, featuring different sending means
+ * (e.g. "send to all", "send to player1", "send to group2" and so on - see
+ * addSendingEntry). It also provides full auto-completion capabilities (see
+ * KCompletion and KLineEdit) which defaults to disabled. The user can
+ * change this by right-clicking on the KLineEdit widget and selecting the
+ * desired behaviour. You can also change this manually by calling
+ * setCompletionMode.
+ *
+ * To make KChatBase useful you have to overwrite at least returnPressed.
+ * Here you should send the message to all of your clients (or just some of
+ * them, depending on sendingEntry).
+ *
+ * To add a message just call addMessage with the nickname of the player
+ * who sent the message and the message itself. If you don't want to use
+ * layoutMessage by any reason you can also call addItem directly. But you
+ * should better replace layoutMessage instead.
+ *
+ * You probably don't want to use the abstract class KChatBase directly but use
+ * one of the derived classess KChat or KGameChat. The latter is the
+ * widget of choice if you develop a KGame application as you don't have to
+ * do anything but providing a KGame object.
+ *
+ * @author Andreas Beckermann <b_mann@gmx.de>
+ **/
+class KDE_EXPORT KChatBase : public QFrame
+{
+ Q_OBJECT
+public:
+ /**
+ * @param parent The parent widget for this widget.
+ * @param noComboBox If true then the combo box where the player can
+ * choose where to send messages to (either globally or just to some
+ * players) will not be added.
+ **/
+ KChatBase(QWidget* parent, bool noComboBox = false);
+
+ /**
+ * Destruct the KChatBase object
+ *
+ * Also calls saveConfig
+ **/
+ virtual ~KChatBase();
+
+ enum SendingIds {
+ SendToAll = 0
+ };
+
+ /**
+ * @return The name that will be shown for messages from this widget. Either the
+ * string that was set by setFromName or the name of the player
+ * that was set by setFromPlayer
+ **/
+ virtual const QString& fromName() const = 0;
+
+ /**
+ * Adds a new entry in the combo box. The default is "send to all
+ * players" only. This function is provided for convenience. You can
+ * also call inserSendingEntry with index = -1.
+ * See also nextId!
+ * @param text The text of the new entry
+ * @param id An ID for this entry. This must be unique for this
+ * entry. It has nothing to do with the position of the entry in the
+ * combo box. See nextId
+ * @return True if successful, otherwise false (e.g. if the id is already used)
+ **/
+ bool addSendingEntry(const QString& text, int id);
+
+ /**
+ * Inserts a new entry in the combo box.
+ * @param text The entry
+ * @param id An ID for this entry. This must be unique for this
+ * entry. It has nothing to do with the position of the entry in the
+ * combo box!
+ * @see nextId
+ * @param index The position of the entry. If -1 the entry will be added
+ * at the bottom
+ * @return True if successful, otherwise false (e.g. if the id is already used)
+ **/
+ bool insertSendingEntry(const QString& text, int id, int index = -1);
+
+ /**
+ * This changes a combo box entry.
+ * @param text The new text of the entry
+ * @param id The ID of the item to be changed
+ **/
+ void changeSendingEntry(const QString& text, int id);
+
+ /**
+ * This selects a combo box entry.
+ * @param id The ID of the item to be selected
+ **/
+ void setSendingEntry(int id);
+
+ /**
+ * Removes the entry with the ID id from the combo box. Note that id is
+ * _not_ the index of the entry!
+ * @see addSendingEntry
+ * @param id The unique id of the entry
+ **/
+ void removeSendingEntry(int id);
+
+ /**
+ * @return The _unique ID_ of the sending entry that has been selected.
+ * @see addSendingEntry
+ *
+ * Note that the entry "send to all" _always_ uses
+ * KChatBase::SendToAll, i.e. 0 as id!
+ **/
+ int sendingEntry() const;
+
+ /**
+ * @return The index of the combo box entry with the given id
+ **/
+ int findIndex(int id) const;
+
+ /**
+ * @return An ID that has not yet been used in the combo box.
+ * @see addSendingEntry
+ **/
+ int nextId() const;
+
+ /**
+ * @return True if this widget is able to send messages (see
+ * returnPressed) and false if not. The default implementation returns
+ * the value which has been set by setAcceptMessage (true by
+ * default)
+ **/
+ virtual bool acceptMessage() const;
+
+ /**
+ * See KLineEdit::setCompletionMode
+ **/
+ void setCompletionMode(KGlobalSettings::Completion mode);
+
+ /**
+ * Set the font that used used for the name part of a message. See also
+ * nameFont and setBothFont
+ **/
+ void setNameFont(const QFont& font);
+
+ /**
+ * Set the font that used used for the message part of a message.
+ * @see messageFont, setBothFont
+ **/
+ void setMessageFont(const QFont& font);
+
+ /**
+ * This sets both - nameFont and messageFont to font. You
+ * probably want to use this if you don't wish to distinguish between
+ * these parts of a message.
+ * @param font A font used for both nameFont and messageFont
+ **/
+ void setBothFont(const QFont& font);
+
+ /**
+ * Same as setNameFont but applies only to system messages.
+ * @see layoutSystemMessage
+ **/
+ void setSystemNameFont(const QFont& font);
+
+ /**
+ * Same as setMessageFont but applies only to system messages.
+ * @see layoutSystemMessage
+ **/
+ void setSystemMessageFont(const QFont& font);
+
+ /**
+ * Same as setBothFont but applies only to system messages.
+ * @see layoutSystemMessage
+ **/
+ void setSystemBothFont(const QFont& font);
+
+ /**
+ * This font should be used for the name (the "from: " part) of a
+ * message. layoutMessage uses this to set the font using
+ * KChatBaseText::setNameFont but if you want to overwrite
+ * layoutMessage you should do this yourself.
+ * @return The font that is used for the name part of the message.
+ **/
+ const QFont& nameFont() const;
+
+ /**
+ * This font should be used for a message. layoutMessage sets the
+ * font of a message using KChatBaseText::setMessageFont but if ypu
+ * replace layoutMessage with your own function you should use
+ * messageFont() yourself.
+ * @return The font that is used for a message
+ **/
+ const QFont& messageFont() const;
+
+ /**
+ * Same as systemNameFont but applies only to system messages.
+ * @see layoutSystemMessage
+ **/
+ const QFont& systemNameFont() const;
+
+ /**
+ * Same as systemMessageFont but applies only to system messages.
+ * @see layoutSystemMessage
+ **/
+ const QFont& systemMessageFont() const;
+
+ /**
+ * Save the configuration of the dialog to a KConfig object. If
+ * the supplied KConfig pointer is NULL then kapp->config() is used
+ * instead (and the group is changed to "KChatBase") butr the current
+ * group is restored at the end.
+ * @param conf A pointer to the KConfig object to save the config
+ * to. If you use 0 then kapp->config() is used and the group is changed
+ * to "KChatBase" (the current group is restored at the end).
+ **/
+ virtual void saveConfig(KConfig* conf = 0);
+
+ /**
+ * Read the configuration from a KConfig object. If the pointer is
+ * NULL kapp->config() is used and the group is changed to "KChatBase".
+ * The current KConfig::group is restored after this call.
+ **/
+ virtual void readConfig(KConfig* conf = 0);
+
+ /**
+ * Set the maximum number of items in the list. If the number of item
+ * exceeds the maximum as many items are deleted (oldest first) as
+ * necessary. The number of items will never exceed this value.
+ * @param maxItems the maximum number of items. -1 (default) for
+ * unlimited.
+ **/
+ void setMaxItems(int maxItems);
+
+ /**
+ * Clear all messages in the list.
+ **/
+ void clear();
+
+ /**
+ * @return The maximum number of messages in the list. -1 is unlimited. See also
+ * setMaxItems
+ **/
+ int maxItems() const;
+
+
+public slots:
+ /**
+ * Add a text in the listbox. See also signalSendMessage()
+ *
+ * Maybe you want to replace this with a function that creates a nicer text
+ * than "fromName: text"
+ *
+ * Update: the function layoutMessage is called by this now. This
+ * means that you will get user defined outlook on the messages :-)
+ * @param fromName The player who sent this message
+ * @param text The text to be added
+ **/
+ virtual void addMessage(const QString& fromName, const QString& text);
+
+ /**
+ * This works just like addMessage but adds a system message.
+ * layoutSystemMessage is used to generate the displayed item. System
+ * messages will have a different look than player messages.
+ *
+ * You may wish to use this to display status information from your game.
+ **/
+ virtual void addSystemMessage(const QString& fromName, const QString& text);
+
+ /**
+ * This member function is mainly internally used to add a message. It
+ * is called by addMessage which creates a single text from a
+ * player name and a text. You will hardly ever use this - but if you
+ * need it it will be here ;-)
+ *
+ * But you may want to replace this in a derived class to create a
+ * non-default (maybe nicer ;-) ) behaviour
+ * @param item The QListBoxItem that is being added
+ **/
+ virtual void addItem(const QListBoxItem* item);
+
+
+ /**
+ * This clears all messages in the view. Note that only the messages are
+ * cleared, not the sender names in the combo box!
+ **/
+ void slotClear();
+
+ /**
+ * @param a If false this widget cannot send a message until
+ * setAcceptMessage(true) is called
+ **/
+ void setAcceptMessage(bool a);
+
+signals:
+ /**
+ * Emitted when the user right-clicks on a list item.
+ * @see QListBox::rightButtonClicked
+ **/
+ void rightButtonClicked(QListBoxItem*, const QPoint&);
+
+protected:
+ /**
+ * This is called whenever the user pushed return ie wants to send a
+ * message.
+ *
+ * Note that you MUST add the message to the widget when this function
+ * is called as it has already been added to the KCompletion object
+ * of the KLineEdit widget!
+ *
+ * Must be implemented in derived classes
+ * @param text The message to be sent
+ **/
+ virtual void returnPressed(const QString& text) = 0;
+
+ /**
+ * Replace to customise the combo box.
+ *
+ * Default: i18n("Send to %1).arg(name)
+ * @param name The name of the player
+ * @return The string as it will be shown in the combo box
+ **/
+ virtual QString comboBoxItem(const QString& name) const;
+
+ /**
+ * Create a QListBoxItem for this message. This function is not yet
+ * written usefully - currently just a QListBoxTex object is
+ * created which shows the message in this format: "fromName: text".
+ * This should fit most peoples needs but needs further improvements.
+ **/
+ virtual QListBoxItem* layoutMessage(const QString& fromName, const QString& text);
+
+ /**
+ * Create a QListBoxItem for this message. This does the same as
+ * layoutMessage but generates a system message. You might want to
+ * use such a message to display e.g. status information from your game.
+ *
+ * The default implementation just prepends "--- ".
+ **/
+ virtual QListBoxItem* layoutSystemMessage(const QString& fromName, const QString& text);
+
+private slots:
+ /**
+ * Check if a text was entered and if acceptMessage returns true.
+ * Then add the message to the KCompletion object of the KLineEdit
+ * widget and call returnPressed
+ **/
+ void slotReturnPressed(const QString&);
+
+private:
+ void init(bool noComboBox);
+
+ KChatBasePrivate* d;
+};
+
+#endif