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 );

  /*
   * 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;

    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;