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     /**
  66      * Constructs a KMeditor object.
  67      */
  68     explicit KMeditor( QWidget *parent, const QString& configFile );
  69
  70
  71     virtual ~KMeditor();
  72
  73     virtual int quoteLength( const QString& line ) const;
  74     virtual const QString defaultQuoteSign() const;
  75
  76     /**
  77      * Sets a quote prefix. Lines starting with the passed quote prefix will
  78      * be highlighted as quotes (in addition to lines that are starting with
  79      * '>' and '|').
  80      */
  81     void setQuotePrefixName( const QString &quotePrefix );
  82
  83     /**
  84      * @return the quote prefix set before with setQuotePrefixName(), or an empty
  85      *         string if that was never called.
  86      */
  87     virtual QString quotePrefixName() const;
  88
  89     //Redefine it for each apps
  90     virtual QString smartQuote( const QString & msg ); //need by kmail
  91
  92     void setUseExternalEditor( bool use );
  93     void setExternalEditorPath( const QString & path );
  94     bool checkExternalEditorFinished();
  95     void killExternalEditor();
  96
  97     /**
  98      * Show the open file dialog and returns the selected URL there.
  99      * The file dialog has an encoding combobox displayed, and the selected
 100      * encoding there will be set as the encoding of the URL's fileEncoding().
 101      */
 102     KUrl insertFile();
 103
 104     /**
 105      * Enables word wrap. Words will be wrapped at the specified column.
 106      *
 107      * @param wrapColumn the column where words will be wrapped
 108      */
 109     void enableWordWrap( int wrapColumn );
 110
 111     /**
 112      * Disables word wrap.
 113      * Note that words are still wrapped at the end of the editor; no scrollbar
 114      * will appear.
 115      */
 116     void disableWordWrap();
 117
 118     /**
 119      * Changes the font of the whole text.
 120      * Also sets the default font for the document.
 121      *
 122      * @param font the font that the whole text will get
 123      */
 124     void setFontForWholeText( const QFont &font );
 125
 126     void setCursorPositionFromStart( unsigned int pos );
 127
 128     /**
 129      * @return the line number where the cursor is. This takes word-wrapping
 130      *         into account. Line numbers start at 0.
 131      */
 132     int linePosition();
 133
 134     /**
 135      * @return the column numbe where the cursor is.
 136      */
 137     int columnNumber();
 138
 139     /**
 140      * Reimplemented again to work around a bug (see comment in implementation).
 141      * FIXME: This is _not_ virtual in the base class
 142      */
 143     void ensureCursorVisible();
 144
 145     /**
 146      * Cleans the whitespace of the edit's text.
 147      * Adjacent tabs and spaces will be converted to a single space.
 148      * Trailing whitespace will be removed.
 149      * More than 2 newlines in a row will be changed to 2 newlines.
 150      * Text in quotes or text inside of the given signature will not be
 151      * cleaned.
 152      * For undo/redo, this is treated as one operation.
 153      *
 154      * @param sig text inside this signature will not be cleaned
 155      */
 156     void cleanWhitespace( const KPIMIdentities::Signature &sig );
 157
 158    /**
 159      * Replaces all occurrences of the old signature with the new signature.
 160      * Text in quotes will be ignored.
 161      * For undo/redo, this is treated as one operation.
 162      * If the old signature is empty, nothing is done.
 163      * If the new signature is empty, the old signature including the
 164      * separator is removed.
 165      *
 166      * @param oldSig the old signature, which will be replaced
 167      * @param newSig the new signature
 168      * @return @p true if oldSig was found (and replaced) at least once
 169      */
 170     bool replaceSignature( const KPIMIdentities::Signature &oldSig,
 171                            const KPIMIdentities::Signature &newSig );
 172
 173     /**
 174      * Fill the given composer Message::TextPart with what's in the editor currently.
 175      * @param textPart The Message::TextPart to fill.
 176      */
 177     void fillComposerTextPart( Message::TextPart* textPart ) const;
 178
 179   public Q_SLOTS:
 180
 181     void slotAddQuotes();
 182     void slotPasteAsQuotation();
 183     void slotRemoveQuotes();
 184
 185     void slotChangeInsertMode();
 186
 187   Q_SIGNALS:
 188
 189     /**
 190      * Emitted whenever the foucs is lost or gained
 191      *
 192      * @param focusGained true if the focus was gained, false when it was lost
 193      */
 194     void focusChanged( bool focusGained );
 195
 196     /**
 197      * Emitted when the user uses the up arrow in the first line. The application
 198      * should then put the focus on the widget above the text edit.
 199      */
 200     void focusUp();
 201
 202     void insertModeChanged();
 203
 204   protected:
 205
 206     /**
 207      * Reimplemented to start the external editor and to emit focusUp().
 208      */
 209     virtual void keyPressEvent ( QKeyEvent * e );
 210
 211   private:
 212     KMeditorPrivate *const d;
 213     friend class KMeditorPrivate;
 214     Q_PRIVATE_SLOT( d, void ensureCursorVisibleDelayed() )
 215     Q_PRIVATE_SLOT( d, void slotEditorFinished( int, QProcess::ExitStatus ) )
 216 };
 217
 218 }
 219
 220 #endif