KDEGames

kchatbase.h
1/*
2 This file is part of the KDE games library
3 SPDX-FileCopyrightText: 2001 Andreas Beckermann <b_mann@gmx.de>
4 SPDX-FileCopyrightText: 2007 Gael de Chalendar (aka Kleag) <kleag@free.fr>
5
6 SPDX-License-Identifier: LGPL-2.0-only
7*/
8
9#ifndef __KCHATBASE_H__
10#define __KCHATBASE_H__
11
12// own
13#include "kdegamesprivate_export.h"
14// KF
15#include <KCompletion>
16// Qt
17#include <QFrame>
18// Std
19#include <memory>
20
21class KConfig;
22
23class KChatBasePrivate;
24class KChatBaseModel;
26class QModelIndex;
27class QPoint;
28
29/**
30 * \class KChatBase kchatbase.h <KChatBase>
31 *
32 * @short The base class for chat widgets
33 *
34 * This is the base class for both KChat and KGameChat. KGameChat is the class
35 * you want to use if you write a KGame based game as it will do most things for
36 * you. KChat is more or less the same but not KGame dependent
37 *
38 * KChatBase provides a complete chat widget, featuring different sending means
39 * (e.g. "send to all", "send to player1", "send to group2" and so on - see
40 * addSendingEntry). It also provides full auto-completion capabilities (see
41 * KCompletion and KLineEdit) which defaults to disabled. The user can
42 * change this by right-clicking on the KLineEdit widget and selecting the
43 * desired behaviour. You can also change this manually by calling
44 * setCompletionMode.
45 *
46 * To make KhatBase useful you have to overwrite at least returnPressed.
47 * Here you should send the message to all of your clients (or just some of
48 * them, depending on sendingEntry).
49 *
50 * To add a message just call addMessage with the nickname of the player
51 * who sent the message and the message itself.
52 *
53 * You probably don't want to use the abstract class KChatBase directly but use
54 * one of the derived classes KChat or KGameChat. The latter is the
55 * widget of choice if you develop a KGame application as you don't have to
56 * do anything but providing a KGame object. If you want to change the kind of
57 * elements displayed (using pixmaps for example), then you will also have to
58 * derive the KChatBaseModel and KChatBaseItemDelegate classes.
59 *
60 * @author Andreas Beckermann <b_mann@gmx.de>
61 * @author Gael de Chalendar (aka Kleag) <kleag@free.fr> for the port to Model/View
62 */
63class KDEGAMESPRIVATE_EXPORT KChatBase : public QFrame
64{
65 Q_OBJECT
66
67public:
68 /**
69 * @param parent The parent widget for this widget.
70 * @param model
71 * @param delegate
72 * @param noComboBox If true then the combo box where the player can
73 * choose where to send messages to (either globally or just to some
74 * players) will not be added.
75 */
76 explicit KChatBase(QWidget *parent, KChatBaseModel *model = nullptr, KChatBaseItemDelegate *delegate = nullptr, bool noComboBox = false);
77
78 /**
79 * Destruct the KChatBase object
80 *
81 * Also calls saveConfig
82 */
83 ~KChatBase() override;
84
85 enum SendingIds { SendToAll = 0 };
86
87 /**
88 * @return The name that will be shown for messages from this widget. Either the
89 * string that was set by setFromName or the name of the player
90 * that was set by setFromPlayer
91 */
92 virtual QString fromName() const = 0;
93
94 /**
95 * Adds a new entry in the combo box. The default is "send to all
96 * players" only. This function is provided for convenience. You can
97 * also call insertSendingEntry with index = -1.
98 * See also nextId!
99 * @param text The text of the new entry
100 * @param id An ID for this entry. This must be unique for this
101 * entry. It has nothing to do with the position of the entry in the
102 * combo box. See nextId
103 * @return True if successful, otherwise false (e.g. if the id is already used)
104 */
105 bool addSendingEntry(const QString &text, int id);
106
107 /**
108 * Inserts a new entry in the combo box.
109 * @param text The entry
110 * @param id An ID for this entry. This must be unique for this
111 * entry. It has nothing to do with the position of the entry in the
112 * combo box!
113 * @see nextId
114 * @param index The position of the entry. If -1 the entry will be added
115 * at the bottom
116 * @return True if successful, otherwise false (e.g. if the id is already used)
117 */
118 bool insertSendingEntry(const QString &text, int id, int index = -1);
119
120 /**
121 * This changes a combo box entry.
122 * @param text The new text of the entry
123 * @param id The ID of the item to be changed
124 */
125 void changeSendingEntry(const QString &text, int id);
126
127 /**
128 * This selects a combo box entry.
129 * @param id The ID of the item to be selected
130 */
131 void setSendingEntry(int id);
132
133 /**
134 * Removes the entry with the ID id from the combo box. Note that id is
135 * _not_ the index of the entry!
136 * @see addSendingEntry
137 * @param id The unique id of the entry
138 */
139 void removeSendingEntry(int id);
140
141 /**
142 * @return The _unique ID_ of the sending entry that has been selected.
143 * @see addSendingEntry
144 *
145 * Note that the entry "send to all" _always_ uses
146 * KChatBase::SendToAll, i.e. 0 as id!
147 */
148 int sendingEntry() const;
149
150 /**
151 * @return The index of the combo box entry with the given id
152 */
153 int findIndex(int id) const;
154
155 /**
156 * @return An ID that has not yet been used in the combo box.
157 * @see addSendingEntry
158 */
159 int nextId() const;
160
161 /**
162 * @return True if this widget is able to send messages (see
163 * returnPressed) and false if not. The default implementation returns
164 * the value which has been set by setAcceptMessage (true by
165 * default)
166 */
167 virtual bool acceptMessage() const;
168
169 /**
170 * See KLineEdit::setCompletionMode
171 */
172 void setCompletionMode(KCompletion::CompletionMode mode);
173
174 /**
175 * Set the font that is used for the name part of a message. See also
176 * nameFont and setBothFont
177 */
178 void setNameFont(const QFont &font);
179
180 /**
181 * Set the font that is used for the message part of a message.
182 * @see messageFont, setBothFont
183 */
184 void setMessageFont(const QFont &font);
185
186 /**
187 * This sets both - nameFont and messageFont to font. You
188 * probably want to use this if you don't wish to distinguish between
189 * these parts of a message.
190 * @param font A font used for both nameFont and messageFont
191 */
192 void setBothFont(const QFont &font);
193
194 /**
195 * Same as setNameFont but applies only to system messages.
196 * @see layoutSystemMessage
197 */
198 void setSystemNameFont(const QFont &font);
199
200 /**
201 * Same as setMessageFont but applies only to system messages.
202 * @see layoutSystemMessage
203 */
204 void setSystemMessageFont(const QFont &font);
205
206 /**
207 * Same as setBothFont but applies only to system messages.
208 * @see layoutSystemMessage
209 */
210 void setSystemBothFont(const QFont &font);
211
212 /**
213 * This font should be used for the name (the "from: " part) of a
214 * message. layoutMessage uses this to set the font using
215 * KChatBaseItemDelegate::setNameFont but if you want to overwrite
216 * layoutMessage you should do this yourself.
217 * @return The font that is used for the name part of the message.
218 */
219 QFont nameFont() const;
220
221 /**
222 * This font should be used for a message. layoutMessage sets the
223 * font of a message using KChatBaseItemDelegate::setMessageFont but if you
224 * replace layoutMessage with your own function you should use
225 * messageFont() yourself.
226 * @return The font that is used for a message
227 */
228 QFont messageFont() const;
229
230 /**
231 * Same as systemNameFont but applies only to system messages.
232 * @see layoutSystemMessage
233 */
234 QFont systemNameFont() const;
235
236 /**
237 * Same as systemMessageFont but applies only to system messages.
238 * @see layoutSystemMessage
239 */
240 QFont systemMessageFont() const;
241
242 /**
243 * Save the configuration of the dialog to a KConfig object. If
244 * the supplied KConfig pointer is NULL then KGlobal::config() is used
245 * instead (and the group is changed to "KChatBase") butr the current
246 * group is restored at the end.
247 * @param conf A pointer to the KConfig object to save the config
248 * to. If you use 0 then KGlobal::config() is used and the group is changed
249 * to "KChatBase" (the current group is restored at the end).
250 */
251 virtual void saveConfig(KConfig *conf = nullptr);
252
253 /**
254 * Read the configuration from a KConfig object. If the pointer is
255 * NULL KGlobal::config() is used and the group is changed to "KChatBase".
256 * The current KConfig::group is restored after this call.
257 */
258 virtual void readConfig(KConfig *conf = nullptr);
259
260 /**
261 * Set the maximum number of items in the list. If the number of item
262 * exceeds the maximum as many items are deleted (oldest first) as
263 * necessary. The number of items will never exceed this value.
264 * @param maxItems the maximum number of items. -1 (default) for
265 * unlimited.
266 */
267 void setMaxItems(int maxItems);
268
269 /**
270 * Clear all messages in the list.
271 */
272 void clear();
273
274 /**
275 * @return The maximum number of messages in the list. -1 is unlimited. See also
276 * setMaxItems
277 */
278 int maxItems() const;
279
280 KChatBaseModel *model();
281 void setModel(KChatBaseModel *m);
282
283public Q_SLOTS:
284 /**
285 * Add a text in the listbox. See also signalSendMessage()
286 *
287 * Maybe you want to replace this with a function that creates a nicer text
288 * than "fromName: text"
289 *
290 * Update: the function layoutMessage is called by this now. This
291 * means that you will get user defined outlook on the messages :-)
292 * @param fromName The player who sent this message
293 * @param text The text to be added
294 */
295 virtual void addMessage(const QString &fromName, const QString &text);
296
297 /**
298 * This works just like addMessage but adds a system message.
299 * layoutSystemMessage is used to generate the displayed item. System
300 * messages will have a different look than player messages.
301 *
302 * You may wish to use this to display status information from your game.
303 */
304 virtual void addSystemMessage(const QString &fromName, const QString &text);
305
306 /**
307 * This clears all messages in the view. Note that only the messages are
308 * cleared, not the sender names in the combo box!
309 */
310 void slotClear();
311
312 /**
313 * @param a If false this widget cannot send a message until
314 * setAcceptMessage(true) is called
315 */
316 void setAcceptMessage(bool a);
317
318protected:
319 /**
320 * This is called whenever the user pushed return ie wants to send a
321 * message.
322 *
323 * Note that you MUST add the message to the widget when this function
324 * is called as it has already been added to the KCompletion object
325 * of the KLineEdit widget!
326 *
327 * Must be implemented in derived classes
328 * @param text The message to be sent
329 */
330 virtual void returnPressed(const QString &text) = 0;
331
332 /**
333 * Replace to customize the combo box.
334 *
335 * Default: i18n("Send to %1).arg(name)
336 * @param name The name of the player
337 * @return The string as it will be shown in the combo box
338 */
339 virtual QString comboBoxItem(const QString &name) const;
340
341 /**
342 * Returns the model index of the message at the viewport coordinates point
343 * @param pos position to check index for
344 * @return model index of message with coordinates pos
345 */
346 QModelIndex indexAt(QPoint pos) const;
347
348private Q_SLOTS:
349 /**
350 * Check if a text was entered and if acceptMessage returns true.
351 * Then add the message to the KCompletion object of the KLineEdit
352 * widget and call returnPressed
353 */
354 void slotReturnPressed(const QString &);
355
356 /**
357 * Implements custom menu which is applicable for one chat message
358 * @param pos point where custom menu has been requested (widget coordinates)
359 */
360 virtual void customMenuHandler(QPoint pos);
361
362protected:
363 KChatBase(KChatBasePrivate &dd, QWidget *parent, bool noComboBox);
364
365private:
366 friend class KGameChat;
368 std::unique_ptr<KChatBasePrivate> const d;
369 // KF6 TODO: change private d to protected d_ptr, use normal Q_DECLARE_PRIVATE, remove subclass friend
370};
371
372#endif
A delegate (see the Qt Model/View module for details) to paint the lines of the KChatBase list model ...
The model used to store messages displayed in the chat dialog messages list.
The base class for chat widgets.
Definition kchatbase.h:64
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.
A Chat widget for KGame-based games.
Definition kgamechat.h:36
Q_SLOTSQ_SLOTS
T qobject_cast(QObject *object)
This file is part of the KDE documentation.
Documentation copyright © 1996-2024 The KDE developers.
Generated on Fri Jun 14 2024 11:52:26 by doxygen 1.10.0 written by Dimitri van Heesch, © 1997-2006

KDE's Doxygen guidelines are available online.