[prev in list] [next in list] [prev in thread] [next in thread]
List: ktexteditor-devel
Subject: Re: [RFC] new Interface to provide custom label/line
From: Andreas Pakulat <apaku () gmx ! de>
Date: 2008-04-02 22:01:10
Message-ID: 20080402220110.GA7251 () morpheus ! apaku ! dnsalias ! org
[Download RAW message or body]
On 23.03.08 15:09:09, Dominik Haumann wrote:
> Hi Andreas,
>
> On Saturday 22 March 2008, Andreas Pakulat wrote:
> > On 02.03.08 14:21:22, Andreas Pakulat wrote:
> > > On 12.01.08 12:26:05, Andreas Pakulat wrote:
> > > > On 12.01.08 13:48:47, Hamish Rodda wrote:
> > > > > On Sun, 6 Jan 2008 03:48:12 am Andreas Pakulat wrote:
> > > > > > Hi,
> > > > > >
> > > > > > for KDevelop4 I'd like to have support for showing a custom label
> > > > > > for each line of a text file. I don't yet have any specific idea
> > > > > > how to implement this as I don't have much (if any) experience
> > > > > > how you guys design the KTE interfaces.
> >
> > Lets see if providing patches gets some more responses. So attached is a
> > diff that adds a couple of interface classes to KTE. Namely thats:
> >
> > LineAnnotationInterface - a document interface that simply allows to
> > associate a LineAnnotationProvider with a document. As the annotation
> > information normally isn't different for different views of a document I
> > think this is the right place to hook this up
> >
> > LineAnnotationProvider - a simple remotely-model-like interface to
> > retrieve the needed information for an annotation. Its simply a short
> > text, a longer text and a way to influence the visual style.
> >
> > AnnotationInteractionInterface - this is a view interface that allows to
> > do interactions with the annotation border, like executing code when an
> > annotation is clicked on, or providing a context menu. (In kdevelop's
> > vcs suppor this could be used to show the diff for a given revision or
> > to display more verbose information in the long text).
> >
> > My next step is to find the code that produces the line-number-border
> > and try to see wether I can use it as base for an implementation of the
> > above.
> >
> > Question? Comments?
> >
> > Andreas
> >
> > PS: If anybody has better naming ideas I'm all ears. The above is just
> > what my limited mind could come up with :)
>
> 1. Implementations
> Just like with other classes who have very small .cpp files (i.e. only virtual
> destructors) put the implementations into ktexteditor.cpp.
Here's an update on the interfaces (unfortunately I didn't yet get
around to the implemention, scheduled for this weekend though). I've
incorporated the changes you mentioned, except that there are still a
document and a view interface as IMHO it makes sense to separate the
two.
Andreas
--
Good day for a change of scene. Repaper the bedroom wall.
["kte_annotation_iface.diff" (text/x-diff)]
Index: annotationmodel.h
===================================================================
--- annotationmodel.h (Revision 0)
+++ annotationmodel.h (Revision 0)
@@ -0,0 +1,74 @@
+/* This file is part of the KDE libraries
+ Copyright 2008 Andreas Pakulat <apaku@gmx.de>
+
+ 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_ANNOTATIONMODEL_H
+#define KDELIBS_KTEXTEDITOR_ANNOTATIONMODEL_H
+
+#include <ktexteditor/ktexteditor_export.h>
+
+#include <QtCore/QVariant>
+
+namespace KTextEditor
+{
+
+/**
+ * \brief An model for providing line annotation information
+ *
+ * \section annoprovide_intro Introduction
+ *
+ * AnnotationModel is a model-like interface that can be implemented
+ * to provide annotation information for each line in a document. It provides
+ * means to retrieve several kinds of data for a given line in the document.
+ *
+ * \section annotprovide_impl Implementing a AnnotationModel
+ *
+ * The public interface of this class is loosely based on the QAbstractItemModel
+ * interfaces. It only has a single method to override which is the \ref data()
+ * method to provide the actual data for a line and role combination.
+ *
+ */
+class KTEXTEDITOR_EXPORT AnnotationModel
+{
+ public:
+
+ virtual ~AnnotationModel() {}
+
+ /**
+ * data() is used to retrieve the information needed to present the
+ * annotation information from the annotation provider. The provider
+ * should return useful information at least for the
+ *
+ * \param line the line for which the data is to be retrieved
+ * \param role the role to identify which kind of annotation is to be retrieved
+ *
+ * \returns a \ref QVariant that contains the data for the given role. The
+ * following roles are supported:
+ *
+ * \ref Qt::DisplayRole - a short display text to be placed in the border
+ * \ref Qt::TooltipRole - a tooltip information, longer text possible
+ * \ref Qt::BackgroundRole - a brush to be used to paint the background on the border
+ * \ref Qt::ForegroundRole - a brush to be used to paint the text on the border
+ */
+ QVariant data( int line, Qt::ItemDataRole role ) const = 0;
+};
+
+}
+
+#endif
+
+// kate: space-indent on; indent-width 2; replace-tabs on;
Index: annotationviewinterface.h
===================================================================
--- annotationviewinterface.h (Revision 0)
+++ annotationviewinterface.h (Revision 0)
@@ -0,0 +1,98 @@
+/* This file is part of the KDE libraries
+ Copyright 2008 Andreas Pakulat <apaku@gmx.de>
+
+ 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_ANNOTATIONVIEWINTERFACE_H
+#define KDELIBS_KTEXTEDITOR_ANNOTATIONVIEWINTERFACE_H
+
+#include <ktexteditor/ktexteditor_export.h>
+
+namespace KTextEditor
+{
+
+/**
+ * \brief Annotation interface for the View
+ *
+ * \ingroup kte_group_view_extensions
+ *
+ * \section annoview_intro Introduction
+ *
+ * The AnnotationViewInterface provides means to interact with the
+ * annotation border that is provided for annotated documents. This interface
+ * allows to react on clicks, double clicks on and provde context menus for the
+ * annotation border.
+ *
+ * \section annoview_access Accessing the AnnotationViewInterface
+ *
+ * The AnnoationInteractionInterface is an extension interface for a
+ * View, i.e. the View inherits the interface \e provided that the
+ * used KTextEditor library implements the interface. Use qobject_cast to
+ * access the interface:
+ * \code
+ * // view is of type KTextEditor::View*
+ * KTextEditor::AnnotationViewInterface *iface =
+ * qobject_cast<KTextEditor::AnnoationInteractionInterface*>( view );
+ *
+ * if( iface ) {
+ * // the implementation supports the interface
+ * // do stuff
+ * iface->setAnnotationBorderVisible( true );
+ * }
+ * \endcode
+ *
+ */
+class KTEXTEDITOR_EXPORT AnnotationViewInterface
+{
+ public:
+ virtual ~AnnotationViewInterface() {}
+
+ /**
+ * This signal is emitted before a context menu is shown on the annotation
+ * border for the given line and view.
+ * \param view the view that the annotation border belongs to
+ * \param menu the context menu that will be shown
+ * \param line the annotated line for which the context menu is shown
+ *
+ * \see setAnnotationContextMenu()
+ */
+ virtual void annotationContextMenuAboutToShow( View* view, QMenu* menu, int line ) = 0;
+
+ /**
+ * This function can be used to show or hide the annotation border
+ * @param visible if true the annotation border is shown, else its hidden.
+ */
+ virtual void setAnnotationBorderVisible( bool visible ) const = 0;
+
+ /**
+ * This signal is emitted when an entry on the annotation border was activated,
+ * for example by clicking or double-clicking it. This follows the KDE wide
+ * setting for activation via click or double-clcik
+ *
+ * \param view the view to which the activated border belongs to
+ * \param line the document line that the activated posistion belongs to
+ */
+ virtual void annotationActivated( View* view, int line ) = 0;
+
+};
+
+}
+
+Q_DECLARE_INTERFACE(KTextEditor::AnnotationViewInterface, "org.kde.KTextEditor.AnnotationViewInterface")
+
+#endif
+
+// kate: space-indent on; indent-width 2; replace-tabs on;
Index: CMakeLists.txt
===================================================================
--- CMakeLists.txt (Revision 792486)
+++ CMakeLists.txt (Arbeitskopie)
@@ -59,6 +59,9 @@
codecompletionmodel.h
configinterface.h
containerinterface.h
+ annotationinterface.h
+ annotationprovider.h
+ annotationview.h
DESTINATION ${INCLUDE_INSTALL_DIR}/ktexteditor COMPONENT Devel)
install( FILES ktexteditor.desktop ktexteditorplugin.desktop DESTINATION ${SERVICETYPES_INSTALL_DIR} )
Index: annotationinterface.h
===================================================================
--- annotationinterface.h (Revision 0)
+++ annotationinterface.h (Revision 0)
@@ -0,0 +1,93 @@
+/* This file is part of the KDE libraries
+ Copyright 2008 Andreas Pakulat <apaku@gmx.de>
+
+ 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_ANNOTATIONINTERFACE_H
+#define KDELIBS_KTEXTEDITOR_ANNOTATIONINTERFACE_H
+
+#include <ktexteditor/ktexteditor_export.h>
+
+namespace KTextEditor
+{
+
+class AnnotationModel;
+
+/**
+ * \brief A Document extension interface for handling Annotation%s
+ *
+ * \ingroup kte_group_doc_extensions
+ *
+ * \section annoiface_intro Introduction
+ *
+ * The AnnotationInterface is designed to provide line annotation information
+ * for a document. This interface provides means to associate a document with a
+ * line annotation provider, which provides some annotation information for
+ * each line in the document.
+ *
+ * \section annoiface_access Accessing the AnnotationInterface
+ *
+ * The AnnotationInterface is an extension interface for a Document, i.e. the
+ * Document inherits the interface \e provided that the
+ * used KTextEditor library implements the interface. Use qobject_cast to
+ * access the interface:
+ * \code
+ * // document is of type KTextEditor::Document*
+ * KTextEditor::AnnotationInterface *iface =
+ * qobject_cast<KTextEditor::AnnotationInterface*>( document );
+ *
+ * if( iface ) {
+ * // the implementation supports the interface
+ * // do stuff
+ * }
+ * \endcode
+ *
+ * \section annoiface_usage Using the AnnotationInterface
+ *
+ * To use the interface simply set your own AnnotationProvider via the
+ * \ref setAnnotationProvider() method.
+ *
+ * \see KTextEditor::AnnotationProvider
+ */
+class KTEXTEDITOR_EXPORT AnnotationInterface
+{
+ public:
+ virtual ~AnnotationInterface() {}
+
+ /**
+ * Sets a new \ref AnnotationProvider for this document to provide
+ * annotation information for each line.
+ *
+ * \param provider the new AnnotationProvider
+ */
+ virtual void setAnnotationModel( AnnotationModel* provider ) = 0;
+
+ /**
+ * returns the currently set \ref AnnotationProvider or 0 if there's none
+ * set
+ * @returns the current \ref AnnotationProvider
+ */
+ virtual AnnotationProvider* annotationModel() const = 0;
+
+};
+
+}
+
+Q_DECLARE_INTERFACE(KTextEditor::AnnotationInterface, "org.kde.KTextEditor.AnnotationInterface")
+
+#endif
+
+// kate: space-indent on; indent-width 2; replace-tabs on;
_______________________________________________
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