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

KDE's Doxygen guidelines are available online.