KDEGames

kchatbase.h
1 /*
2  This file is part of the KDE games library
3  SPDX-FileCopyrightText: 2001 Andreas Beckermann <[email protected]>
4  SPDX-FileCopyrightText: 2007 Gael de Chalendar (aka Kleag) <[email protected]>
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 
21 class KConfig;
22 
23 class KChatBasePrivate;
24 class KChatBaseModel;
26 class QModelIndex;
27 class 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 <[email protected]>
61  * @author Gael de Chalendar (aka Kleag) <[email protected]> for the port to Model/View
62  */
63 class KDEGAMESPRIVATE_EXPORT KChatBase : public QFrame
64 {
65  Q_OBJECT
66 
67 public:
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 
283 public 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 
318 protected:
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  const QModelIndex indexAt(const QPoint &pos) const;
347 
348 private 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(const QPoint &pos);
361 
362 protected:
363  KChatBase(KChatBasePrivate &dd, QWidget *parent, bool noComboBox);
364 
365 private:
366  friend class KGameChat;
367  Q_DECLARE_PRIVATE_D(d, KChatBase)
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
Q_SLOTSQ_SLOTS
The base class for chat widgets.
Definition: kchatbase.h:63
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 Oct 3 2023 04:05:54 by doxygen 1.8.17 written by Dimitri van Heesch, © 1997-2006

KDE's Doxygen guidelines are available online.