[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-08-02 16:25:14
Message-ID: 46B2056A.2090606 () freehackers ! org
[Download RAW message or body]
Hi,
Another patch. That one does not compile, I only want to validate the API.
I took the design approach that you mentionned in the last mail, similar
to the CommandInterface.
I made a distinction between a generic Container class that only serves
as default return type of ContainerInterface::container() and a given
extension.
The first extension is MultiDocMultiView (suggestion for better names
are welcome) but I have more extensions in mind:
- one extension to allow the kpart to request the application to exit.
This to support :q in Yzis.
- one extension to allow the kpart to send output to the kpart host. For
example, if I execute a script in Yzis, it might make sense to display
the output in KDevelop output window instead of splitting the current
Yzis view.
Probably more will come as Yzis grows in capabilities.
Comments welcome.
Philippe
["kte-container-ext-5.diff" (text/x-diff)]
Index: containerinterface.h
===================================================================
--- containerinterface.h (revision 0)
+++ containerinterface.h (revision 0)
@@ -0,0 +1,76 @@
+
+
+/**
+ * \brief Class that allows the kpart host to provide some extensions.
+ *
+ * \ingroup kte_group_command_extensions
+ *
+ * The KTextEditor framework allows the kpart host to provide additional
+ * services to the kpart. Those services are defined in a set of classes
+ * who all inherit from ContainerExtension().
+ *
+ * If the container supports those specific services, it should set an
+ * instance of their class with ContainerInterface::setContainer().
+ *
+ * To obtain a ContainerInterface, the kpart host should do:
+ * \code
+ * // inside the kpart host
+ * Editor * editor = KTextEditor::EditorChooser::editor();
+ * ContainerInterface * iface = qobject_cast<ConainterInterace *>( editor );
+ * if (iface != NULL) {
+ * iface->setContainer( myContainerExtension );
+ * } else {
+ * // the kpart does not support ContainerInterface.
+ * }
+ * \endcode
+ *
+ * If the qobject_cast<> returns NULL, it simply means that the kpart is not
+ * interted in those extensions (or that it does not support them).
+ *
+ * \sa Container
+ */
+class ContainerInterface
+{
+ public:
+
+ /** \brief Virtual Destructor */
+ ~ContainerInterface() {}
+
+ /** Set the KTextEditor container.
+ *
+ * This method is used by the KTextEditor host to set an instance
+ * of a class providing optional container extensions.
+ *
+ * \sa container, Container
+ */
+ virtual void setContainer( Container * a_container ) = 0;
+
+ /** Fetch the container extension.
+ *
+ * This method is used by the KTextEditor component to know
+ * which extensions are supported by the KTextEditor host.
+ *
+ * The kpart will cast the result with qobject_cast() to the right
+ * container extension to see if that particular extension is supported:
+ *
+ * <b>Example:</b>
+ * \code
+ * // inside the kpart
+ * SomeContainerExtension * myExt =
+ * qobject_cast<SomeContainerExtension *>( editor->container() );
+ *
+ * if (myExt) {
+ * // do some stuff with the specific container extension
+ * // ...
+ * } else {
+ * // too bad, that extesion is not supported.
+ * }
+ * \endcode
+ *
+ * \sa setContainer, Container
+ */
+ virtual Container * container() = 0;
+};
+
+Q_DECLARE_INTERFACE(KTextEditor::ContainerInterface, \
"org.kde.KTextEditor.ContainerInterface") +
Index: editorchooser.h
===================================================================
--- editorchooser.h (revision 694330)
+++ editorchooser.h (working copy)
@@ -123,6 +123,12 @@
/**
* Static accessor to get the Editor instance of the currently used
* KTextEditor component.
+ *
+ * That Editor instance can be qobject-cast to specific extensions.
+ * If the result of the cast is not NULL, that extension is supported:
+ *
+ *
+ *
* \param postfix config group postfix string
* \param fallBackToKatePart if \e true, the returned Editor component
* will be a katepart if no other implementation can be found
Index: container.h
===================================================================
--- container.h (revision 0)
+++ container.h (revision 0)
@@ -0,0 +1,167 @@
+/* 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;
+
+/**
+ * \brief Base 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.
+ *
+ * This class is the mother of the classes providing container extensions.
+ *
+ * KTE Host supporting additional capabilities should provide a class that
+ * inherits from the container extensions.
+ *
+ * An instance of this extension should be set to the editor via
+ * ContainerInterface::setContainerExtension().Check ContainerInterface() to
+ * see how to obtain an instance of ContainerInterface.
+ *
+ * To check if a given extension is supported, kpart code should do:
+ * \code
+ * Editor * editor = KTextEditor::EditorChooser::editor();
+ * ContainerInterface * iface = qobject_cast<ContainerInterface *>( editor );
+ * if (iface) {
+ * SomeContainerExtension * extension = qobject_cast<SomeContainerExtension *>( \
editor->containerExtension() ); + * if (extension != NULL ) {
+ * // great, that extesion is supported
+ * // use the extension !
+ * }
+ * }
+ * \endcode
+ */
+class Container : public QObject
+{
+ Q_OBJECT
+
+ public:
+ virtual ~Container() {}
+
+};
+
+class KTEXTEDITOR_EXPORT MultiDocMultiViewContainer
+ : public Container
+{
+ public:
+
+ /** Constructor */
+ MultiDocMultiViewContainer();
+
+ /** Virtual destructor */
+ virtual ~MultiDocMultiViewContainer();
+
+ /** Set the \p view requested by the part as the active view.
+ *
+ * \sa activeView
+ */
+ virtual void setActiveView( View * view )=0;
+
+ /** Get the current activew view.
+ *
+ * \return the active view.
+ *
+ * \sa setActiveView
+ */
+ virtual View * activeView()=0;
+
+ /** Create a new Document and return it to the kpart.
+ *
+ * Canonical implementation is:
+ * \code
+ * Document * createDocument()
+ * {
+ * 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.
+ *
+ * \return a pointer to the new Document object.
+ */
+ virtual Document * createDocument()=0;
+
+ /** Removes 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 (removeView() has been called on all the views of the
+ * document previously).
+ *
+ * The signal aboutToClose() is emitted before this method is
+ * called.
+ *
+ * \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 removeDocument( Document * doc )=0;
+
+ /** Creates a new View and return it to the kpart.
+ *
+ * Canonical implementation is:
+ * \code
+ * View * createView( Document * doc )
+ * {
+ * // set parentWidget to relevant value
+ * return doc->createView( parentWidget );
+ * }
+ * \endcode
+ *
+ * The signal viewCreated() will be emitted during the createView()
+ * call.
+ *
+ * \return a pointer to the new View created.
+ */
+ virtual View * createView( Document * doc )=0;
+
+ /** Removes the View \p view .
+ *
+ * The view is still valid when this call is made but will be deleted
+ * shortly after.
+ *
+ * \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 removeView( View * view )=0;
+
+};
+
+
+} // namespace KTextEditor
+
+
+#endif // KDELIBS_KTEXTEDITOR_CONTAINER_EXTENSION_H
_______________________________________________
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