KDEGames

kgamechat.h
1 /*
2  This file is part of the KDE games library
3  SPDX-FileCopyrightText: 2001-2002 Andreas Beckermann <[email protected]>
4  SPDX-FileCopyrightText: 2001 Martin Heni <kde at heni-online.de>
5 
6  SPDX-License-Identifier: LGPL-2.0-only
7 */
8 
9 #ifndef __KGAMECHAT_H__
10 #define __KGAMECHAT_H__
11 
12 // own
13 #include "../kchatbase.h"
14 #include "kdegamesprivate_export.h"
15 // Qt
16 #include <QString>
17 
18 class KPlayer;
19 class KGame;
20 class KGamePropertyBase;
21 
22 class KGameChatPrivate;
23 
24 /**
25  * \class KGameChat kgamechat.h <KGame/KGameChat>
26  *
27  * @short A Chat widget for KGame-based games
28  *
29  * Call @ref setFromPlayer() first - this will be used as the "from" part of
30  * every message you will send. Otherwise it won't work! You can also use the
31  * fromPlayer parameter in the constructor though...
32  *
33  * @author Andreas Beckermann <[email protected]>
34  */
35 class KDEGAMESPRIVATE_EXPORT KGameChat : public KChatBase
36 {
37  Q_OBJECT
38 
39 public:
40  /**
41  * Construct a @ref KGame chat widget on @p game that used @p msgid for
42  * the chat message. The @p fromPlayer is the local player (see @ref
43  * setFromPlayer).
44  */
45  KGameChat(KGame *game, int msgid, KPlayer *fromPlayer, QWidget *parent, KChatBaseModel *model = nullptr, KChatBaseItemDelegate *delegate = nullptr);
46 
47  /**
48  * @overload
49  * To make use of this widget you need to call @ref setFromPlayer
50  * manually.
51  */
52  KGameChat(KGame *game, int msgId, QWidget *parent, KChatBaseModel *model = nullptr, KChatBaseItemDelegate *delegate = nullptr);
53 
54  /**
55  * @overload
56  * This constructs a widget that is not usable. You must call at least
57  * setGame, setFromPlayer and setMessageId manually.
58  */
59  explicit KGameChat(QWidget *parent);
60 
61  ~KGameChat() override;
62 
63  enum SendingIds { SendToGroup = 1 };
64 
65  /**
66  * This sets the fromPlayer to @p player. The fromPlayer is the
67  * player that will appear as "from" when you send messages through this
68  * widget.
69  * @param player The player of this widget
70  */
71  void setFromPlayer(KPlayer *player);
72 
73  KPlayer *fromPlayer() const;
74 
75  /**
76  * Set the @ref KGame object for this chat widget. All messages will be
77  * sent through this object. You don't have to implement any send
78  * functions, just call this function, call @ref setFromPlayer and be
79  * done :-)
80  * @param g The @ref KGame object the messages will be sent through
81  */
82  void setKGame(KGame *g);
83 
84  KGame *game() const;
85 
86  /**
87  * @return The id of the messages produced by KGameChat. The id will be
88  * used in @ref KGame as parameter msgid in the method @ref KGame::sendMessage
89  */
90  int messageId() const;
91 
92  /**
93  * Change the message id of the chat widget. It is recommended that you
94  * don't use this but prefer the constructor instead, but in certain
95  * situations (such as using this widget in Qt designer) it may be
96  * useful to change the message id.
97  *
98  * See also @ref messageId
99  */
100  void setMessageId(int msgid);
101 
102  /**
103  * reimplemented from @ref KChatBase
104  * @return @ref KPlayer::name() for the player set by @ref setFromPlayer
105  */
106  QString fromName() const override;
107 
108 public Q_SLOTS:
109  void addMessage(const QString &fromName, const QString &text) override
110  {
111  KChatBase::addMessage(fromName, text);
112  }
113  virtual void addMessage(int fromId, const QString &text);
114 
115  void slotReceiveMessage(int, const QByteArray &, quint32 receiver, quint32 sender);
116 
117 protected:
118  /**
119  * @param id The ID of the sending entry, as returned by @ref KChatBase sendingEntry
120  * @return True if the entry "send to all" was selected, otherwise false
121  */
122  bool isSendToAllMessage(int id) const;
123 
124  /**
125  * Used to indicate whether a message shall be sent to a group of
126  * players. Note that this was not yet implemented when this doc was
127  * written so this description might be wrong. (FIXME)
128  * @param id The ID of the sending entry, as returned by @ref KChatBase sendingEntry
129  * @return True if the message is meant to be sent to a group (see @ref KPlayer::group
130  * ), e.g. if "send to my group" was selected.
131  */
132  bool isToGroupMessage(int id) const;
133 
134  /**
135  * Used to indicate whether the message shall be sent to a single player
136  * only. Note that you can also call @ref isSendToAllMessage and @ref
137  * isToGroupMessage - if both return false it must be a player message.
138  * This behaviour might be changed later - so don't depend on it.
139  *
140  * See also toPlayerId
141  * @param id The ID of the sending entry, as returned by
142  * @ref KChatBase sendingEntry
143  * @return True if the message shall be sent to a special player,
144  * otherwise false.
145  */
146  bool isToPlayerMessage(int id) const;
147 
148  /**
149  * @param id The ID of the sending entry, as returned by
150  * @ref KChatBase sendingEntry
151  * @return The ID of the player (see KPlayer::id) the sending entry
152  * belongs to. Note that the parameter id is an id as returned by
153  * @ref KChatBase sendingEntry and the id this method returns is a
154  * KPlayer ID. If @ref isToPlayerMessage returns false this method
155  * returns -1
156  */
157  int playerId(int id) const;
158 
159  /**
160  * @param playerId The ID of the KPlayer object
161  * @return The ID of the sending entry (see KChatBase) or -1 if
162  * the player id was not found.
163  */
164  int sendingId(int playerId) const;
165 
166  /**
167  * @return True if the player with this ID was added before (see
168  * slotAddPlayer)
169  */
170  bool hasPlayer(int id) const;
171 
172  /**
173  * @param name The name of the added player
174  * @return A string that will be added as sending entry in @ref
175  * KChatBase. By default this is "send to name" where name is the name
176  * that you specify. See also KChatBase::addSendingEntry
177  */
178  virtual QString sendToPlayerEntry(const QString &name) const;
179 
180 protected Q_SLOTS:
181  /**
182  * Unsets a KGame object that has been set using setKGame
183  * before. You don't have to call this - this is usually done
184  * automatically.
185  */
186  void slotUnsetKGame();
187 
188  void slotPropertyChanged(KGamePropertyBase *, KPlayer *);
189  void slotAddPlayer(KPlayer *);
190  void slotRemovePlayer(KPlayer *);
191 
192  /**
193  * Called when KPlayer::signalNetworkData is emitted. The message
194  * gets forwarded to slotReceiveMessage if @p me equals
195  * fromPlayer.
196  */
197  void slotReceivePrivateMessage(int msgid, const QByteArray &buffer, quint32 sender, KPlayer *me);
198 
199 protected:
200  void returnPressed(const QString &text) override;
201 
202 private:
203  void init(KGame *g, int msgid);
204 
205 private:
206  Q_DECLARE_PRIVATE_D(KChatBase::d, KGameChat)
207 };
208 
209 #endif
virtual void addMessage(const QString &fromName, const QString &text)
Add a text in the listbox.
Definition: kchatbase.cpp:396
Q_SLOTSQ_SLOTS
The base class for chat widgets.
Definition: kchatbase.h:63
QCA_EXPORT void init()
The main KDE game object.
Definition: kgame.h:46
Base class for a game player.
Definition: kplayer.h:59
virtual QString fromName() const =0
virtual void returnPressed(const QString &text)=0
This is called whenever the user pushed return ie wants to send a message.
Base class of KGameProperty.
Definition: kgameproperty.h:36
A Chat widget for KGame-based games.
Definition: kgamechat.h:35
This file is part of the KDE documentation.
Documentation copyright © 1996-2023 The KDE developers.
Generated on Tue Nov 28 2023 03:50:18 by doxygen 1.8.17 written by Dimitri van Heesch, © 1997-2006

KDE's Doxygen guidelines are available online.