document.h

Go to the documentation of this file.

/* This file is part of the KDE libraries
   Copyright (C) 2001 Christoph Cullmann <cullmann@kde.org>
   Copyright (C) 2005 Dominik Haumann (dhdev@gmx.de) (documentation)

   This library is free software; you can redistribute it and/or
   modify it under the terms of the GNU Library General Public
   License as published by the Free Software Foundation; either
   version 2 of the License, or (at your option) any later version.

   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 KDELIBS_KTEXTEDITOR_DOCUMENT_H
#define KDELIBS_KTEXTEDITOR_DOCUMENT_H

#include <ktexteditor/ktexteditor_export.h>
// the very important KTextEditor::Cursor class
#include <ktexteditor/cursor.h>
#include <ktexteditor/range.h>

// our main baseclass of the KTextEditor::Document
#include <kparts/part.h>

// the list of views
#include <QtCore/QList>
#include <QtCore/QMetaType>

namespace KTextEditor
{

class Editor;
class View;

class KTEXTEDITOR_EXPORT Document : public KParts::ReadWritePart
{
  Q_OBJECT

  public:
    Document ( QObject *parent = 0);

    virtual ~Document ();

  /*
   * Methods to create and manage the views of this document and access the
   * global editor object.
   */
  public:
    virtual Editor *editor () = 0;

    virtual View *createView ( QWidget *parent ) = 0;

    virtual View* activeView() const = 0;

    virtual const QList<View*> &views() const = 0;

  Q_SIGNALS:
    void viewCreated (KTextEditor::Document *document, KTextEditor::View *view);

  /*
   * General information about this document and its content.
   */
  public:
    virtual const QString &documentName () const = 0;

    virtual QString mimeType() = 0;

  /*
   * SIGNALS
   * following signals should be emitted by the editor document.
   */
  Q_SIGNALS:
    void documentNameChanged ( KTextEditor::Document *document );

    void documentUrlChanged ( KTextEditor::Document *document );

    void modifiedChanged ( KTextEditor::Document *document );

//warning ADD IN KDE5
//    void readWriteChanged (KTextEditor::Document *document);

  /*
   * VERY IMPORTANT: Methods to set and query the current encoding of the
   * document
   */
  public:
    virtual bool setEncoding (const QString &encoding) = 0;

    virtual const QString &encoding () const = 0;

  /*
   * General file related actions.
   * All this actions cause user interaction in some cases.
   */
  public:
    virtual bool documentReload () = 0;

    virtual bool documentSave () = 0;

    virtual bool documentSaveAs () = 0;

 Q_SIGNALS:
    void documentSavedOrUploaded(KTextEditor::Document* document,bool saveAs);

 /*
  * Methodes to create/end editing sequences.
  */
 public:
    virtual bool startEditing () = 0;

    virtual bool endEditing () = 0;

  /*
   * General access to the document's text content.
   */
  public:
    virtual QString text () const = 0;

    virtual QString text ( const Range& range, bool block = false ) const = 0;

    virtual QChar character( const Cursor& position ) const = 0;

    // TODO: KDE5, add wordAt(), implementation already exists in KateDocument::getWord().
    //       In the implementation, reuse wordRangeAt() to avoid code duplication.
    /*
     * Get the word at the text position \p cursor.
     * The returned word is defined by the word boundaries to the left and
     * right starting at \p cursor. The algorithm takes highlighting information
     * into account, e.g. a dash ('-') in C++ is interpreted as word boundary,
     * whereas e.g. CSS allows identifiers with dash ('-').
     *
     * If \p cursor is not a valid text position or if there is no word
     * under the requested position \p cursor, an empty string is returned.
     *
     * \param cursor requested cursor position for the word
     * \return the word under the cursor or an empty string if there is no word.
     *
     * \see wordRangeAt(), characterAt()
     */
    //QString wordAt(const KTextEditor::Cursor& cursor) const = 0;

    // TODO: KDE5, add wordRangeAt(), implementation for the range already exists in KateDocument::getWord()
    /*
     * Get the text range for the word located under the text position \p cursor.
     * The returned word is defined by the word boundaries to the left and
     * right starting at \p cursor. The algorithm takes highlighting information
     * into account, e.g. a dash ('-') in C++ is interpreted as word boundary,
     * whereas e.g. CSS allows identifiers with dash ('-').
     *
     * If \p cursor is not a valid text position or if there is no word
     * under the requested position \p cursor, an invalid text range is returned.
     * If the text range is valid, it is \e always on a single line.
     *
     * \param cursor requested cursor position for the word
     * \return the Range spanning the word under the cursor or an invalid range if there is no word.
     *
     * \see wordAt(), characterAt(), KTextEditor::Range::isValid()
     */
    //KTextEditor::Range wordRangeAt(const KTextEditor::Cursor& cursor) const = 0;

    // TODO: KDE5 add this function (Sven Brauch, Dominik Haumann, Milian Wolff)
    //       and use this in Kate Part's text selection to disallow seleting
    //       half surrogates.
    /*
     * Get whether \p cursor is a valid text position.
     * A cursor position at (line, column) is valid, if
     * - line >= 0 and line < lines() holds, and
     * - column >= 0 and column <= lineLength(column).
     *
     * The text position \p cursor is also invalid if it is inside a Unicode surrogate.
     * Therefore, use this function when iterating over the characters of a line.
     *
     * \param cursor cursor position to check for validity
     * \return true, if \p cursor is a valid text position, otherwise \p false
     *
     * \see KTextEditor::Range::isValid()
     */
    // in impl, use QChar::isHighSurrogate() + QChar::isLowSurrogate()
    //bool isValidTextPosition(const KTextEditor::Cursor& cursor) const = 0;

    virtual QStringList textLines ( const Range& range, bool block = false ) const = 0;

    virtual QString line ( int line ) const = 0;

    virtual int lines () const = 0;

    virtual Cursor documentEnd() const = 0;

    inline Range documentRange() const { return Range(Cursor::start(), documentEnd()); }

    virtual int totalCharacters() const = 0;

    virtual bool isEmpty() const;

    virtual int lineLength ( int line ) const = 0;

    inline Cursor endOfLine(int line) const { return Cursor(line, lineLength(line)); }

    virtual bool setText ( const QString &text ) = 0;

    virtual bool setText ( const QStringList &text ) = 0;

    virtual bool clear () = 0;

    virtual bool insertText ( const Cursor &position, const QString &text, bool block = false ) = 0;

    virtual bool insertText ( const Cursor &position, const QStringList &text, bool block = false ) = 0;

    virtual bool replaceText ( const Range &range, const QString &text, bool block = false );

    virtual bool replaceText ( const Range &range, const QStringList &text, bool block = false );

    virtual bool removeText ( const Range &range, bool block = false ) = 0;

    virtual bool cursorInText(const Cursor &cursor);

    virtual bool insertLine ( int line, const QString &text ) = 0;

    virtual bool insertLines ( int line, const QStringList &text ) = 0;

    virtual bool removeLine ( int line ) = 0;

  /*
   * SIGNALS
   * Following signals should be emitted by the document if the text content
   * is changed.
   */
  Q_SIGNALS:
    void textChanged(KTextEditor::Document *document);

    void textInserted(KTextEditor::Document *document, const KTextEditor::Range& range);

    void textRemoved(KTextEditor::Document *document, const KTextEditor::Range& range);

    void textRemoved(KTextEditor::Document *document, const KTextEditor::Range& range, const QString& oldText);
    
    void textChanged(KTextEditor::Document *document, const KTextEditor::Range& oldRange, const KTextEditor::Range& newRange);

    void textChanged(KTextEditor::Document *document, const KTextEditor::Range& oldRange, const QString& oldText, const KTextEditor::Range& newRange);
    
    void aboutToClose(KTextEditor::Document *document);

    void aboutToReload(KTextEditor::Document *document);

    void reloaded(KTextEditor::Document *document);

    void exclusiveEditStart(KTextEditor::Document *document);

    void exclusiveEditEnd(KTextEditor::Document *document);

  /*
   * Access to the mode/highlighting subsystem
   */
  public:
    virtual QString mode() const = 0;

    virtual QString highlightingMode() const = 0;

    virtual QStringList modes() const = 0;

    virtual QStringList highlightingModes() const = 0;

    virtual bool setMode(const QString &name) = 0;

    virtual bool setHighlightingMode(const QString &name) = 0;

    virtual QString highlightingModeSection( int index ) const = 0;

    virtual QString modeSection( int index ) const = 0;

  /*
   * SIGNALS
   * Following signals should be emitted by the document if the mode
   * of the document changes
   */
  Q_SIGNALS:
    void modeChanged(KTextEditor::Document *document);

    void highlightingModeChanged(KTextEditor::Document *document);

  private:
    class DocumentPrivate* const d;

  public:
    void setSuppressOpeningErrorDialogs(bool suppress);
    bool suppressOpeningErrorDialogs() const;
    bool openingError() const;
    QString openingErrorMessage() const;

  protected:
    void setOpeningError(bool errors);
    void setOpeningErrorMessage(const QString& message);
};

}

Q_DECLARE_METATYPE(KTextEditor::Document*)

#endif

// kate: space-indent on; indent-width 2; replace-tabs on;