/* This file is part of the TDE games library Copyright (C) 2001 Andreas Beckermann (b_mann@gmx.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 __KCHATBASE_H__ #define __KCHATBASE_H__ #include #include #include #include #include class TQListBoxItem; class TDEConfig; class KChatBaseTextPrivate; /** * A TQListBoxText implementation for KChatBase. * * It supports different colors, text fonts, ... * * A KChatBaseText consists of two text items: first the player part then the * text part. This honors KChatBase::addMessage which also uses both. * You can leave the player part out if you don't need it - there won't be any * difference. * * You can set different colors and fonts for both parts. In the future there * will probably some kind of KChatBaseDialog which offers the user the ability * to configure things like color and font on the fly. **/ class KChatBaseText : public TQListBoxText { public: /** * Constructs a KChatBaseText object with the player and text part **/ KChatBaseText(const TQString& player, const TQString& text); /** * Constructs a KChatBaseText object without player part **/ KChatBaseText(const TQString& text); /** * Destruct a KChatBaseText object. **/ virtual ~KChatBaseText(); /** * Set the name part of a message. A message is usually shown like * "name: text" and you can change both parts independently. * * @see setMessage * @param name The name of the sender (e.g. the player) **/ void setName(const TQString& name); /** * Set the text part of a message. A message is usually shown like * "name: message" and you can change both parts independently. * * See also setName * @param message The message that has been sent **/ void setMessage(const TQString& message); /** * @return The name part of a message. * @see setName **/ const TQString& name() const; /** * @return The message text. * @see setMessage **/ const TQString& message() const; /** * You can set the font of the sender name independently of the message * itself. This font is used as the "name: " part of the message. * @return The font that is used for the name **/ TQFont nameFont() const; /** * You can set the font of the message independently of the sender name. * This font is used as the text part of the message. * @return The font thaz is used for message text **/ TQFont messageFont() const; /** * Set the font for the name. * @see nameFont * @param font A pointer to the name font. Only the pointer is stored so * don't delete the object. This way there is only one object for a lot * of messages in memory. **/ void setNameFont(const TQFont* font); /** * Set the font for the message text. * @see messageFont * @param font A pointer to the message font. Only the pointer is stored so * don't delete the object! This way there is only one object for a lot * of messages in memory. **/ void setMessageFont(const TQFont* font); /** **/ virtual int width(TQListBox* ) const; /** **/ virtual int height(TQListBox* ) const; protected: /** **/ virtual void paint(TQPainter*); private: void init(); private: KChatBaseTextPrivate* d; }; class KChatBasePrivate; /** * @short The base class for chat widgets * * This is the base class for both KChat and KGameChat. KGameChat is the class * you want to use if you write a KGame based game as it will do most things for * you. KChat is more or less the same but not KGame dependant * * KChatBase provides a complete chat widget, featuring different sending means * (e.g. "send to all", "send to player1", "send to group2" and so on - see * addSendingEntry). It also provides full auto-completion capabilities (see * TDECompletion and KLineEdit) which defaults to disabled. The user can * change this by right-clicking on the KLineEdit widget and selecting the * desired behaviour. You can also change this manually by calling * setCompletionMode. * * To make KChatBase useful you have to overwrite at least returnPressed. * Here you should send the message to all of your clients (or just some of * them, depending on sendingEntry). * * To add a message just call addMessage with the nickname of the player * who sent the message and the message itself. If you don't want to use * layoutMessage by any reason you can also call addItem directly. But you * should better replace layoutMessage instead. * * You probably don't want to use the abstract class KChatBase directly but use * one of the derived classess KChat or KGameChat. The latter is the * widget of choice if you develop a KGame application as you don't have to * do anything but providing a KGame object. * * @author Andreas Beckermann **/ class KDE_EXPORT KChatBase : public TQFrame { TQ_OBJECT public: /** * @param parent The parent widget for this widget. * @param noComboBox If true then the combo box where the player can * choose where to send messages to (either globally or just to some * players) will not be added. **/ KChatBase(TQWidget* parent, bool noComboBox = false); /** * Destruct the KChatBase object * * Also calls saveConfig **/ virtual ~KChatBase(); enum SendingIds { SendToAll = 0 }; /** * @return The name that will be shown for messages from this widget. Either the * string that was set by setFromName or the name of the player * that was set by setFromPlayer **/ virtual const TQString& fromName() const = 0; /** * Adds a new entry in the combo box. The default is "send to all * players" only. This function is provided for convenience. You can * also call inserSendingEntry with index = -1. * See also nextId! * @param text The text of the new entry * @param id An ID for this entry. This must be unique for this * entry. It has nothing to do with the position of the entry in the * combo box. See nextId * @return True if successful, otherwise false (e.g. if the id is already used) **/ bool addSendingEntry(const TQString& text, int id); /** * Inserts a new entry in the combo box. * @param text The entry * @param id An ID for this entry. This must be unique for this * entry. It has nothing to do with the position of the entry in the * combo box! * @see nextId * @param index The position of the entry. If -1 the entry will be added * at the bottom * @return True if successful, otherwise false (e.g. if the id is already used) **/ bool insertSendingEntry(const TQString& text, int id, int index = -1); /** * This changes a combo box entry. * @param text The new text of the entry * @param id The ID of the item to be changed **/ void changeSendingEntry(const TQString& text, int id); /** * This selects a combo box entry. * @param id The ID of the item to be selected **/ void setSendingEntry(int id); /** * Removes the entry with the ID id from the combo box. Note that id is * _not_ the index of the entry! * @see addSendingEntry * @param id The unique id of the entry **/ void removeSendingEntry(int id); /** * @return The _unique ID_ of the sending entry that has been selected. * @see addSendingEntry * * Note that the entry "send to all" _always_ uses * KChatBase::SendToAll, i.e. 0 as id! **/ int sendingEntry() const; /** * @return The index of the combo box entry with the given id **/ int findIndex(int id) const; /** * @return An ID that has not yet been used in the combo box. * @see addSendingEntry **/ int nextId() const; /** * @return True if this widget is able to send messages (see * returnPressed) and false if not. The default implementation returns * the value which has been set by setAcceptMessage (true by * default) **/ virtual bool acceptMessage() const; /** * See KLineEdit::setCompletionMode **/ void setCompletionMode(TDEGlobalSettings::Completion mode); /** * Set the font that used used for the name part of a message. See also * nameFont and setBothFont **/ void setNameFont(const TQFont& font); /** * Set the font that used used for the message part of a message. * @see messageFont, setBothFont **/ void setMessageFont(const TQFont& font); /** * This sets both - nameFont and messageFont to font. You * probably want to use this if you don't wish to distinguish between * these parts of a message. * @param font A font used for both nameFont and messageFont **/ void setBothFont(const TQFont& font); /** * Same as setNameFont but applies only to system messages. * @see layoutSystemMessage **/ void setSystemNameFont(const TQFont& font); /** * Same as setMessageFont but applies only to system messages. * @see layoutSystemMessage **/ void setSystemMessageFont(const TQFont& font); /** * Same as setBothFont but applies only to system messages. * @see layoutSystemMessage **/ void setSystemBothFont(const TQFont& font); /** * This font should be used for the name (the "from: " part) of a * message. layoutMessage uses this to set the font using * KChatBaseText::setNameFont but if you want to overwrite * layoutMessage you should do this yourself. * @return The font that is used for the name part of the message. **/ const TQFont& nameFont() const; /** * This font should be used for a message. layoutMessage sets the * font of a message using KChatBaseText::setMessageFont but if ypu * replace layoutMessage with your own function you should use * messageFont() yourself. * @return The font that is used for a message **/ const TQFont& messageFont() const; /** * Same as systemNameFont but applies only to system messages. * @see layoutSystemMessage **/ const TQFont& systemNameFont() const; /** * Same as systemMessageFont but applies only to system messages. * @see layoutSystemMessage **/ const TQFont& systemMessageFont() const; /** * Save the configuration of the dialog to a TDEConfig object. If * the supplied TDEConfig pointer is NULL then kapp->config() is used * instead (and the group is changed to "KChatBase") butr the current * group is restored at the end. * @param conf A pointer to the TDEConfig object to save the config * to. If you use 0 then kapp->config() is used and the group is changed * to "KChatBase" (the current group is restored at the end). **/ virtual void saveConfig(TDEConfig* conf = 0); /** * Read the configuration from a TDEConfig object. If the pointer is * NULL kapp->config() is used and the group is changed to "KChatBase". * The current TDEConfig::group is restored after this call. **/ virtual void readConfig(TDEConfig* conf = 0); /** * Set the maximum number of items in the list. If the number of item * exceeds the maximum as many items are deleted (oldest first) as * necessary. The number of items will never exceed this value. * @param maxItems the maximum number of items. -1 (default) for * unlimited. **/ void setMaxItems(int maxItems); /** * Clear all messages in the list. **/ void clear(); /** * @return The maximum number of messages in the list. -1 is unlimited. See also * setMaxItems **/ int maxItems() const; public slots: /** * Add a text in the listbox. See also signalSendMessage() * * Maybe you want to replace this with a function that creates a nicer text * than "fromName: text" * * Update: the function layoutMessage is called by this now. This * means that you will get user defined outlook on the messages :-) * @param fromName The player who sent this message * @param text The text to be added **/ virtual void addMessage(const TQString& fromName, const TQString& text); /** * This works just like addMessage but adds a system message. * layoutSystemMessage is used to generate the displayed item. System * messages will have a different look than player messages. * * You may wish to use this to display status information from your game. **/ virtual void addSystemMessage(const TQString& fromName, const TQString& text); /** * This member function is mainly internally used to add a message. It * is called by addMessage which creates a single text from a * player name and a text. You will hardly ever use this - but if you * need it it will be here ;-) * * But you may want to replace this in a derived class to create a * non-default (maybe nicer ;-) ) behaviour * @param item The TQListBoxItem that is being added **/ virtual void addItem(const TQListBoxItem* item); /** * This clears all messages in the view. Note that only the messages are * cleared, not the sender names in the combo box! **/ void slotClear(); /** * @param a If false this widget cannot send a message until * setAcceptMessage(true) is called **/ void setAcceptMessage(bool a); signals: /** * Emitted when the user right-clicks on a list item. * @see TQListBox::rightButtonClicked **/ void rightButtonClicked(TQListBoxItem*, const TQPoint&); protected: /** * This is called whenever the user pushed return ie wants to send a * message. * * Note that you MUST add the message to the widget when this function * is called as it has already been added to the TDECompletion object * of the KLineEdit widget! * * Must be implemented in derived classes * @param text The message to be sent **/ virtual void returnPressed(const TQString& text) = 0; /** * Replace to customise the combo box. * * Default: i18n("Send to %1).arg(name) * @param name The name of the player * @return The string as it will be shown in the combo box **/ virtual TQString comboBoxItem(const TQString& name) const; /** * Create a TQListBoxItem for this message. This function is not yet * written usefully - currently just a TQListBoxTex object is * created which shows the message in this format: "fromName: text". * This should fit most peoples needs but needs further improvements. **/ virtual TQListBoxItem* layoutMessage(const TQString& fromName, const TQString& text); /** * Create a TQListBoxItem for this message. This does the same as * layoutMessage but generates a system message. You might want to * use such a message to display e.g. status information from your game. * * The default implementation just prepends "--- ". **/ virtual TQListBoxItem* layoutSystemMessage(const TQString& fromName, const TQString& text); private slots: /** * Check if a text was entered and if acceptMessage returns true. * Then add the message to the TDECompletion object of the KLineEdit * widget and call returnPressed **/ void slotReturnPressed(const TQString&); private: void init(bool noComboBox); KChatBasePrivate* d; }; #endif