messagecomposer/kmeditor.h

   1 /**
   2  * kmeditor.h
   3  *
   4  * Copyright 2007 Laurent Montel <montel@kde.org>
   5  * Copyright 2008 Thomas McGuire <mcguire@kde.org>
   6  *
   7  * This library is free software; you can redistribute it and/or
   8  * modify it under the terms of the GNU Lesser General Public
   9  * License as published by the Free Software Foundation; either
  10  * version 2.1 of the License, or (at your option) any later version.
  11  *
  12  * This library is distributed in the hope that it will be useful,
  13  * but WITHOUT ANY WARRANTY; without even the implied warranty of
  14  * MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE.  See the GNU
  15  * Lesser General Public License for more details.
  16  *
  17  * You should have received a copy of the GNU Lesser General Public
  18  * License along with this library; if not, write to the Free Software
  19  * Foundation, Inc., 51 Franklin Street, Fifth Floor, Boston, MA
  20  * 02110-1301  USA
  21  */
  22
  23 #ifndef MESSAGECOMPOSER_KMEDITOR_H
  24 #define MESSAGECOMPOSER_KMEDITOR_H
  25
  26 #include "messagecomposer_export.h"
  27
  28 #include <KPIMTextEdit/TextEdit>
  29
  30 namespace KPIMIdentities {
  31   class Signature;
  32 }
  33
  34 namespace Message {
  35
  36 class TextPart;
  37 class KMeditorPrivate;
  38
  39 /**
  40  * The KMeditor class provides a widget to edit and display text,
  41  * specially geared towards writing e-mails.
  42  *
  43  * It offers sevaral additional functions of a KRichTextWidget:
  44  *
  45  * @li The ability to use an external editor
  46  * @li Utility functions like removing whitespace, inserting a file,
  47  *     adding quotes or rot13'ing the text
  48  */
  49 class MESSAGECOMPOSER_EXPORT KMeditor : public KPIMTextEdit::TextEdit
  50 {
  51   Q_OBJECT
  52
  53   public:
  54
  55     /**
  56      * Constructs a KMeditor object
  57      */
  58     explicit KMeditor( const QString &text, QWidget *parent = 0 );
  59
  60     /**
  61      * Constructs a KMeditor object.
  62      */
  63     explicit KMeditor( QWidget *parent = 0 );
  64
  65     virtual ~KMeditor();
  66
  67     virtual int quoteLength( const QString& line ) const;
  68     virtual const QString defaultQuoteSign() const;
  69
  70     /**
  71      * Sets a quote prefix. Lines starting with the passed quote prefix will
  72      * be highlighted as quotes (in addition to lines that are starting with
  73      * '>' and '|').
  74      */
  75     void setQuotePrefixName( const QString &quotePrefix );
  76
  77     /**
  78      * @return the quote prefix set before with setQuotePrefixName(), or an empty
  79      *         string if that was never called.
  80      */
  81     virtual QString quotePrefixName() const;
  82
  83     //Redefine it for each apps
  84     virtual QString smartQuote( const QString & msg ); //need by kmail
  85
  86     void setUseExternalEditor( bool use );
  87     void setExternalEditorPath( const QString & path );
  88     bool checkExternalEditorFinished();
  89     void killExternalEditor();
  90
  91     /**
  92      * Show the open file dialog and returns the selected URL there.
  93      * The file dialog has an encoding combobox displayed, and the selected
  94      * encoding there will be set as the encoding of the URL's fileEncoding().
  95      */
  96     KUrl insertFile();
  97
  98     /**
  99      * Enables word wrap. Words will be wrapped at the specified column.
 100      *
 101      * @param wrapColumn the column where words will be wrapped
 102      */
 103     void enableWordWrap( int wrapColumn );
 104
 105     /**
 106      * Disables word wrap.
 107      * Note that words are still wrapped at the end of the editor; no scrollbar
 108      * will appear.
 109      */
 110     void disableWordWrap();
 111
 112     /**
 113      * Changes the font of the whole text.
 114      * Also sets the default font for the document.
 115      *
 116      * @param font the font that the whole text will get
 117      */
 118     void setFontForWholeText( const QFont &font );
 119
 120     void setCursorPositionFromStart( unsigned int pos );
 121
 122     /**
 123      * @return the line number where the cursor is. This takes word-wrapping
 124      *         into account. Line numbers start at 0.
 125      */
 126     int linePosition();
 127
 128     /**
 129      * @return the column numbe where the cursor is.
 130      */
 131     int columnNumber();
 132
 133     /**
 134      * Reimplemented again to work around a bug (see comment in implementation).
 135      * FIXME: This is _not_ virtual in the base class
 136      */
 137     void ensureCursorVisible();
 138
 139     /**
 140      * Cleans the whitespace of the edit's text.
 141      * Adjacent tabs and spaces will be converted to a single space.
 142      * Trailing whitespace will be removed.
 143      * More than 2 newlines in a row will be changed to 2 newlines.
 144      * Text in quotes or text inside of the given signature will not be
 145      * cleaned.
 146      * For undo/redo, this is treated as one operation.
 147      *
 148      * @param sig text inside this signature will not be cleaned
 149      */
 150     void cleanWhitespace( const KPIMIdentities::Signature &sig );
 151
 152    /**
 153      * Replaces all occurrences of the old signature with the new signature.
 154      * Text in quotes will be ignored.
 155      * For undo/redo, this is treated as one operation.
 156      * If the old signature is empty, nothing is done.
 157      * If the new signature is empty, the old signature including the
 158      * separator is removed.
 159      *
 160      * @param oldSig the old signature, which will be replaced
 161      * @param newSig the new signature
 162      * @return @p true if oldSig was found (and replaced) at least once
 163      */
 164     bool replaceSignature( const KPIMIdentities::Signature &oldSig,
 165                            const KPIMIdentities::Signature &newSig );
 166
 167     /**
 168      * Fill the given composer Message::TextPart with what's in the editor currently.
 169      * @param textPart The Message::TextPart to fill.
 170      */
 171     void fillComposerTextPart( Message::TextPart* textPart ) const;
 172
 173   public Q_SLOTS:
 174
 175     void slotAddQuotes();
 176     void slotPasteAsQuotation();
 177     void slotRemoveQuotes();
 178
 179     void slotChangeInsertMode();
 180
 181   Q_SIGNALS:
 182
 183     /**
 184      * Emitted whenever the foucs is lost or gained
 185      *
 186      * @param focusGained true if the focus was gained, false when it was lost
 187      */
 188     void focusChanged( bool focusGained );
 189
 190     /**
 191      * Emitted when the user uses the up arrow in the first line. The application
 192      * should then put the focus on the widget above the text edit.
 193      */
 194     void focusUp();
 195
 196     void insertModeChanged();
 197
 198   protected:
 199
 200     /**
 201      * Reimplemented to start the external editor and to emit focusUp().
 202      */
 203     virtual void keyPressEvent ( QKeyEvent * e );
 204
 205   private:
 206     KMeditorPrivate *const d;
 207     friend class KMeditorPrivate;
 208     Q_PRIVATE_SLOT( d, void ensureCursorVisibleDelayed() )
 209     Q_PRIVATE_SLOT( d, void slotEditorFinished( int, QProcess::ExitStatus ) )
 210 };
 211
 212 }
 213
 214 #endif