[prev in list] [next in list] [prev in thread] [next in thread]
List: ktexteditor-devel
Subject: Re: KTextEditor container extension
From: Philippe Fremy <phil () freehackers ! org>
Date: 2007-07-30 15:28:44
Message-ID: 46AE03AC.8060101 () freehackers ! org
[Download RAW message or body]
Christoph Cullmann wrote:
> On Thursday 26 July 2007 13:46, Philippe Fremy wrote:
>> Here is a new version, with no abbreviations. In the last patch, I also
>> forgot to add the containerextension.h file, which is corrected in this
>> one.
>>
>> Please review.
> Nearly perfect ;) Perhaps make the functions of the Container just pure
> virtual, apps implementing it can still do nothing there. Beside that, the d
> pointer of the editor must be created and the container ext pointer needs to
> be nulled in it.
>
I am moving forward.
Patch again, with your suggestions and also with proper include guards,
exporting of symbols and copyright text.
I also improved the API. While working on Yzis, I realise that one needs
to know in advance whether a given extension is supported, which was not
possible when relying on returned values of methods. So I added
supportsXXX methods.
Comments welcome.
Philippe
["kte-container-ext-3.diff" (text/x-diff)]
Index: ktexteditor.cpp
===================================================================
--- ktexteditor.cpp (revision 694330)
+++ ktexteditor.cpp (working copy)
@@ -40,6 +40,7 @@
#include "plugin.moc"
#include "commandinterface.h"
+#include "containerextension.h"
#include "markinterface.h"
#include "modificationinterface.h"
#include "searchinterface.h"
@@ -69,16 +70,37 @@
{
}
+class KTextEditor::EditorPrivate {
+ public:
+ EditorPrivate()
+ : m_containerExtension(0)
+ {}
+ ContainerExtension * m_containerExtension;
+};
+
Editor::Editor( QObject *parent )
: QObject ( parent )
- , d(0)
+ , d(new EditorPrivate)
{
}
Editor::~Editor()
{
+ delete d;
}
+void Editor::setContainerExtension( ContainerExtension * ext )
+{
+ d->m_containerExtension = ext;
+}
+
+ContainerExtension * Editor::containerExtension()
+{
+ return d->m_containerExtension;
+
+}
+
+
class KTextEditor::DocumentPrivate {
public:
DocumentPrivate()
@@ -362,5 +384,27 @@
return m_document->removeLine(line);
}
+// ==========================================================
+// ContainerExtension
+// ==========================================================
+
+class KTextEditor::ContainerExtensionPrivate {
+ public:
+ ContainerExtensionPrivate() {}
+};
+
+
+ContainerExtension::ContainerExtension( QObject * parent )
+: d(new ContainerExtensionPrivate())
+{
+ Q_UNUSED( parent );
+}
+
+ContainerExtension::~ContainerExtension()
+{
+ delete d;
+}
+
+
// kate: space-indent on; indent-width 2; replace-tabs on;
Index: containerextension.h
===================================================================
--- containerextension.h (revision 0)
+++ containerextension.h (revision 0)
@@ -0,0 +1,210 @@
+/* This file is part of the KDE libraries
+ Copyright (C) 2007 Philippe Fremy (phil at freehackers dot org)
+
+ 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 KDELIBS_KTEXTEDITOR_CONTAINER_EXTENSION_H
+#define KDELIBS_KTEXTEDITOR_CONTAINER_EXTENSION_H
+
+#include <ktexteditor/ktexteditor_export.h>
+
+namespace KTextEditor
+{
+
+class Document;
+class View;
+class ContainterExtensionPrivate;
+
+/** Main Class for extending a KTextEditor container.
+ *
+ * The kpart container for the KTextEditor interface may have different
+ * capabilities. For example, inside KDevelop or Kate, the container can
+ * manage multiple views and multiple documents. However, if the kpart text
+ * is used inside konqueror as a replacement of the text entry in html
+ * forms, the container will only support one view with one document.
+ *
+ * The goal of this class is to allow the KTE kpart to know a bit more about
+ * its container. The part adjust its behavior depending on what the
+ * container supports.
+ *
+ * KTE Host supporting additional capabilities should provide a class that
+ * inherits from the container extensions and from QObject and should define
+ * the Q_OBJECT macro.
+ *
+ * The QObject inheritance is necessary to make the qobject_cast() function
+ * work properly.
+ *
+ * An instance of this extension should be set to the editor via
+ * Editor::setContainerExtension().
+ *
+ * The default container extension to allow the kpart component to request
+ * additional views and additional documents.
+ *
+ * Each method of the extension can optionally be supported or not. See the
+ * doc of each method to inform the kpart if that feature is supported.
+ *
+ * Other extensions will be defined in the future.
+ *
+ * To check if this extension is supported, kpart code should do:
+ * @code
+ * Editor * editor = KTextEditor::EditorChooser::editor();
+ * ContainterExtension * ext = qobject_cast<ContainerExtension *>( editor->ContainerExtension() );
+ * if (ext != NULL && if (ext->supportsDocumentCreation()) {
+ * doc = ext->requestDocumentCreation();
+ * // do something with the new doc
+ * } else {
+ * // kpart can not request additional document
+ * }
+ * @endcode
+ */
+class KTEXTEDITOR_EXPORT ContainerExtension
+{
+ public:
+
+ /** Constructor */
+ ContainerExtension( QObject * parent = 0);
+
+ /** Virtual destructor */
+ virtual ~ContainerExtension();
+
+ /** Tell if the setActiveView() method is supported.
+ *
+ * @return true if setActiveView() is supported, false otherwise.
+ */
+ virtual bool supportsSetActiveView()=0;
+
+ /** Set the @p view requested by the part as the active view.
+ * @sa supportsSetActiveView.
+ *
+ * @return true if the active view has been switched,
+ * false if changing the active view from the kpart is not supported.
+ */
+ virtual bool setActiveView( View * view )=0;
+
+ /** Tell if the requestDocumentCreation() method is supported.
+ *
+ * @return true if requestDocumentCreation() is supported, false
+ * otherwise.
+ */
+ virtual bool supportsDocumentCreation()=0;
+
+ /** Create a new Document and return it to the kpart.
+ *
+ * Canonical implementation is:
+ * @code
+ * Document * requestDocumentCreation()
+ * {
+ * Document * doc;
+ * // set parentQObject to relevant value
+ * doc = editor->createDocument( parentQObject );
+ * // integrate the new document in the document list of the
+ * // container, ...
+ * return doc;
+ * }
+ * @endcode
+ *
+ * The signal documentCreated() will be emitted during the creation.
+ *
+ * @sa supportsDocumentCreation.
+ *
+ * @return a pointer to the new Document object, or NULL if the
+ * container does not support document creation from the kpart.
+ */
+ virtual Document * requestDocumentCreation()=0;
+
+ /** Tell if the requestDocumentRemoval() method is supported.
+ *
+ * @return true if requestDocumentRemoval() is supported, false
+ * otherwise.
+ */
+ virtual bool supportsDocumentRemoval()=0;
+
+ /** Request removal of document @p doc .
+ *
+ * The document is about to be removed but is still valid when this
+ * call is made. The Document does not contain any view when this
+ * call is made (requestViewRemoval() has been called on all the views of the
+ * document previously).
+ *
+ * The signal aboutToClose() is emitted before this method is
+ * called.
+ *
+ * @sa supportsDocumentRemoval.
+ *
+ * @return true if the removal is authorized and acted, or
+ * false if removing documents by the kpart is not supported
+ * by the container.
+ */
+ virtual bool requestDocumentRemoval( Document * doc )=0;
+
+ /** Tell if the requestViewCreation() method is supported.
+ *
+ * @return true if requestViewCreation() is supported, false
+ * otherwise.
+ */
+ virtual bool supportsViewCreation()=0;
+
+ /** Create a new View and return it to the kpart.
+ *
+ * Canonical implementation is:
+ * @code
+ * View * requestViewCreation( Document * doc )
+ * {
+ * // set parentWidget to relevant value
+ * return doc->createView( parentWidget );
+ * }
+ * @endcode
+ *
+ * The signal viewCreated() will be emitted during the createView()
+ * call.
+ *
+ * @sa supportsViewCreation.
+ *
+ * @return a pointer to the new View created, or
+ * NULL if the container does not support view creation
+ * from the kpart.
+ */
+ virtual View * requestViewCreation( Document * doc )=0;
+
+ /** Tell if the requestViewRemoval() method is supported.
+ *
+ * @return true if requestViewRemoval() is supported, false
+ * otherwise.
+ */
+ virtual bool supportsViewRemoval()=0;
+
+ /** Request removal of the View @p view .
+ *
+ * The view is still valid when this call is made but will be deleted
+ * shortly after.
+ *
+ * @sa supportsViewRemoval.
+ *
+ * @return true if the removal is authorized and acted, or
+ * false if the container does not support view removing from
+ * the kpart, or
+ */
+ virtual bool requestViewRemoval( View * view )=0;
+
+ private:
+ class ContainerExtensionPrivate* const d;
+};
+
+
+}; // namespace KTextEditor
+
+
+#endif // KDELIBS_KTEXTEDITOR_CONTAINER_EXTENSION_H
Index: document.h
===================================================================
--- document.h (revision 694330)
+++ document.h (working copy)
@@ -147,7 +147,7 @@
virtual View *createView ( QWidget *parent ) = 0;
/**
- * Return the view which is currently has user focus, if any.
+ * Return the view which currently has user focus, if any.
*/
virtual View* activeView() const = 0;
Index: editor.h
===================================================================
--- editor.h (revision 694330)
+++ editor.h (working copy)
@@ -34,6 +34,7 @@
class Document;
class ConfigPage;
+class ContainerExtension;
/**
* \brief Accessor interface for Editor part.
@@ -117,6 +118,39 @@
*/
virtual ~Editor ();
+ /** Set the KTextEditor container supported extensions.
+ *
+ * This method is used by the KTextEditor host to set an instance
+ * of a class providing optional container extensions.
+ *
+ * @sa containerExtension, ContainerExtension
+ */
+ virtual void setContainerExtension( ContainerExtension * ext );
+
+ /** Fetch the container extension.
+ *
+ * This method is used by the KTextEditor component to know
+ * which extensions are supported by the KTextEditor host.
+ *
+ * The results should be cast with qobject_cast() to the right container
+ * extension to see if that particular extension is supported:
+ *
+ * <b>Example:</b>
+ * @code
+ * MyContainerExt * myExt =
+ * qobject_cast<MyContainerExtension*>( editor->containerExtension() );
+ *
+ * if (myExt) {
+ * // do some stuff with the specific host extension
+ * // ...
+ * }
+ * @endcode
+ *
+ * @sa setContainerExtension, ContainerExtension
+ */
+ virtual ContainerExtension * containerExtension();
+
+
/*
* Methods to create and manage the documents.
*/
_______________________________________________
KTextEditor-Devel mailing list
KTextEditor-Devel@kde.org
https://mail.kde.org/mailman/listinfo/ktexteditor-devel
[prev in list] [next in list] [prev in thread] [next in thread]
Configure |
About |
News |
Add a list |
Sponsored by KoreLogic