[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-01 10:19:09
Message-ID: 46B05E1D.8090707 () freehackers ! org
[Download RAW message or body]
Hi,
Thanks for the feedback so far.
So, I returned to the simple API that was proposed initially. If a kpart
container provides the extension, he should support all the methods.
All methods of ContainerExtension are pure virtual, except for the
constructor and destructor. I removed the d pointer of
ContainerExtension because of this: because the class is only an
interface, it won't store anything.
I added a method to fetch the current activeView, as per Dominik suggestion.
Dominik Haumann wrote:
> class ...EXPORT... ContainerInterface {
> virtual void setContainer( ContainerExtension * ext ) = 0;
> virtual ContainerExtension * container() = 0;
> };
>
> Then, the following code peaces:
> ContainerInterface *iface = qobject_cast<ContainerInterface*>(editor); // cast the editor
> if (iface) {
> // support + 100% implementation of ContainerExtension exists
> } else {
> // not supported, now you can't do anything useful with ContainerExtension
> // anyway, so it's not supported
> }
I don't think it is possible this way. The kpart provides the editor,
but it is the kpart host that should provide a container extension. The
kpart host is not able to change the editor implementation. So, we need
setters and getters.
> + virtual bool setActiveView( View * view )=0;
>
> We have similar functions in the Kate App in KateViewSpace:
> ::currentView();
> ::showView();
>
> ...what about a getter function like activeView()?
good idea. Included in the current patch.
>
>
> Instead of calling the functions requestViewRemoval etc, what about simply
> removeView() etc? The bool return type already contains the success.
>
> [...]
>> +
>> +
>> +}; // namespace KTextEditor
> ^
> breaks gcc's -pedantic option.
I wonder why. It is not allowed to put a ; after a namespace ? How do i
enable -pedantic in KDE compilation ?
I removed the colon anyway.
> I agree with Chriostoph: Please keep the API minimal. If a lib implements
> the interface, it simply should implement all the functions.
That's the case now.
> Api documentation related stuff (the nitpicking part ;) ):
> - use \foo instead of @foo. We agreed on that some time ago, just to be
> consistent within KTE
Ok.
> - use
> /**
> *
> */ ;)
Ok.
> - \see & \sa always comes last, after \return (as in the Qt-documentaion)
Ok.
New patch. New comments ?
cheers,
Philippe - working on getting the patch accepted
["kte-container-ext-4.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,18 @@
return m_document->removeLine(line);
}
+// ==========================================================
+// ContainerExtension
+// ==========================================================
+
+ContainerExtension::ContainerExtension()
+{
+}
+
+ContainerExtension::~ContainerExtension()
+{
+}
+
+
// kate: space-indent on; indent-width 2; replace-tabs on;
Index: containerextension.h
===================================================================
--- containerextension.h (revision 0)
+++ containerextension.h (revision 0)
@@ -0,0 +1,168 @@
+/* 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.
+ *
+ * Other extensions may 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 ) {
+ * doc = ext->createDoc();
+ * // do something with the new doc
+ * } else {
+ * // kpart can not request additional document
+ * }
+ * \endcode
+ */
+class KTEXTEDITOR_EXPORT ContainerExtension
+{
+ public:
+
+ /** Constructor */
+ ContainerExtension();
+
+ /** Virtual destructor */
+ virtual ~ContainerExtension();
+
+ /** Set the \p view requested by the part as the active view.
+ *
+ * \return true if the active view has been switched,
+ * false if changing the active view from the kpart is not
+ * supported.
+ *
+ * \sa activeView
+ */
+ virtual bool 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 * createDoc()
+ * {
+ * 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 * createDoc()=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 removeDoc( 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
Index: CMakeLists.txt
===================================================================
--- CMakeLists.txt (revision 694330)
+++ CMakeLists.txt (working copy)
@@ -59,6 +59,7 @@
codecompletioninterface.h
codecompletionmodel.h
configinterface.h
+ containerextension.h
DESTINATION ${INCLUDE_INSTALL_DIR}/ktexteditor )
install( FILES ktexteditor.desktop ktexteditorplugin.desktop DESTINATION ${SERVICETYPES_INSTALL_DIR} )
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