Copy the KDE 3.5 branch to branches/trinity for new KDE 3.5 features.

BUG:215923


git-svn-id: svn://anonsvn.kde.org/home/kde/branches/trinity/kdegames@1054174 283d02a7-25f6-0310-bc7c-ecb5cbfe19da

1 files changed, 223 insertions, 0 deletions

diff --git a/libkdegames/kgame/kgamechat.h b/libkdegames/kgame/kgamechat.h
new file mode 100644
index 00000000..6f7ea65d
--- /dev/null
+++ b/libkdegames/kgame/kgamechat.h
@@ -0,0 +1,223 @@
+/*
+    This file is part of the KDE games library
+    Copyright (C) 2001-2002 Andreas Beckermann (b_mann@gmx.de)
+    Copyright (C) 2001 Martin Heni (martin@heni-online.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 __KGAMECHAT_H__
+#define __KGAMECHAT_H__
+
+#include <qstring.h>
+
+#include "kchatbase.h"
+#include <kdemacros.h>
+class KPlayer;
+class KGame;
+class KGamePropertyBase;
+
+class KGameChatPrivate;
+
+/**
+ * @short A Chat widget for KGame-based games
+ *
+ * Call @ref setFromPlayer() first - this will be used as the "from" part of
+ * every message you will send. Otherwise it won't work! You can also use the
+ * fromPlayer parameter in the constructor though...
+ *
+ * @author Andreas Beckermann <b_mann@gmx.de>
+ **/
+class KDE_EXPORT KGameChat : public KChatBase
+{
+	Q_OBJECT
+public:
+	/**
+	 * Construct a @ref KGame chat widget on @p game that used @p msgid for
+	 * the chat message. The @p fromPlayer is the local player (see @ref
+	 * setFromPlayer).
+	 **/
+	KGameChat(KGame* game, int msgid, KPlayer* fromPlayer, QWidget * parent);
+
+	/**
+	 * @overload
+	 * To make use of this widget you need to call @ref setFromPlayer
+	 * manually.
+	 **/
+	KGameChat(KGame* game, int msgId, QWidget* parent);
+
+	/**
+	 * @overload
+	 * This constructs a widget that is not usable. You must call at least
+	 * setGame, setFromPlayer and setMessageId manually.
+	 * @since 3.2
+	 **/
+	KGameChat(QWidget* parent);
+
+	virtual ~KGameChat();
+
+	enum SendingIds {
+		SendToGroup = 1
+	};
+
+	/**
+	 * This sets the fromPlayer to @p player. The fromPlayer is the
+	 * player that will appear as "from" when you send messages through this
+	 * widget.
+	 * @param player The player of this widget
+	 **/
+	void setFromPlayer(KPlayer* player);
+
+	KPlayer* fromPlayer() const;
+
+	/**
+	 * Set the @ref KGame object for this chat widget. All messages will be
+	 * sent through this object. You don't have to implement any send
+	 * functions, just call this function, call @ref setFromPlayer and be
+	 * done :-)
+	 * @param g The @ref KGame object the messages will be sent through
+	 **/
+	void setKGame(KGame* g);
+
+	KGame* game() const;
+
+	/**
+	 * @return The id of the messages produced by KGameChat. The id will be
+	 * used in @ref KGame as parameter msgid in the method @ref KGame::sendMessage
+	 **/
+	int messageId() const;
+
+	/**
+	 * Change the message id of the chat widget. It is recommended that you
+	 * don't use this but prefer the constructor instead, but in certain
+	 * situations (such as using this widget in Qt designer) it may be
+	 * useful to change the message id.
+	 *
+	 * See also @ref messageId
+	 * @since 3.2
+	 **/
+	void setMessageId(int msgid);
+
+	/**
+	 * reimplemented from @ref KChatBase
+	 * @return @ref KPlayer::name() for the player set by @ref setFromPlayer
+	 **/
+	virtual const QString& fromName() const;
+
+
+public slots:
+	virtual void addMessage(const QString& fromName, const QString& text) { KChatBase::addMessage(fromName, text);}
+	virtual void addMessage(int fromId, const QString& text);
+
+	void slotReceiveMessage(int, const QByteArray&, Q_UINT32 receiver, Q_UINT32 sender);
+
+protected:
+	/**
+	 * @param id The ID of the sending entry, as returned by @ref
+	 * KChatBase::sendingEntry
+	 * @return True if the entry "send to all" was selected, otherwise false
+	 **/
+	bool isSendToAllMessage(int id) const;
+
+	/**
+	 * Used to indicate whether a message shall be sent to a group of
+	 * players. Note that this was not yet implemented when this doc was
+	 * written so this description might be wrong. (FIXME)
+	 * @param id The ID of the sending entry, as returned by @ref
+	 * KChatBase::sendingEntry
+	 * @return True if the message is meant to be sent to a group (see @ref
+	 * KPlayer::group), e.g. if "send to my group" was selected.
+	 **/
+	bool isToGroupMessage(int id) const;
+	
+
+	/**
+	 * Used to indicate whether the message shall be sent to a single player
+	 * only. Note that you can also call @ref isSendToAllMessage and @ref
+	 * isToGroupMessage - if both return false it must be a player message.
+	 * This behaviour might be changed later - so don't depend on it.
+	 *
+	 * See also toPlayerId
+	 * @param id The ID of the sending entry, as returned by 
+	 * KChatBase::sendingEntry
+	 * @return True if the message shall be sent to a special player,
+	 * otherwise false.
+	 **/
+	bool isToPlayerMessage(int id) const;
+
+	/**
+	 * @param id The ID of the sending entry, as returned by
+	 * KChatBase::sendingEntry
+	 * @return The ID of the player (see KPlayer::id) the sending entry
+	 * belongs to. Note that the parameter id is an id as returned by ref
+	 * KChatBase::sendingEntry and the id this method returns is a 
+	 * KPlayer ID. If isToPlayerMessage returns false this method
+	 * returns -1
+	 **/
+	int playerId(int id) const;
+
+	/**
+	 * @param playerId The ID of the KPlayer object
+	 * @return The ID of the sending entry (see KChatBase) or -1 if
+	 * the player id was not found.
+	 **/
+	int sendingId(int playerId) const;
+
+	/**
+	 * @return True if the player with this ID was added before (see 
+	 * slotAddPlayer)
+	 **/
+	bool hasPlayer(int id) const;
+
+	/**
+	 * @param name The name of the added player
+	 * @return A string that will be added as sending entry in @ref
+	 * KChatBase. By default this is "send to name" where name is the name
+	 * that you specify. See also KChatBase::addSendingEntry
+	 **/
+	virtual QString sendToPlayerEntry(const QString& name) const;
+
+
+protected slots:
+	/**
+	 * Unsets a KGame object that has been set using setKGame
+	 * before. You don't have to call this - this is usually done
+	 * automatically.
+	 **/
+	void slotUnsetKGame();
+
+
+	void slotPropertyChanged(KGamePropertyBase*, KPlayer*);
+	void slotAddPlayer(KPlayer*);
+	void slotRemovePlayer(KPlayer*);
+
+	/**
+	 * Called when KPlayer::signalNetworkData is emitted. The message
+	 * gets forwarded to slotReceiveMessage if @p me equals
+	 * fromPlayer.
+	 **/
+	void slotReceivePrivateMessage(int msgid, const QByteArray& buffer, Q_UINT32 sender, KPlayer* me);
+
+protected:
+	virtual void returnPressed(const QString& text);
+
+private:
+	void init(KGame* g, int msgid);
+
+private:
+	KGameChatPrivate* d;
+};
+
+#endif