[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-03-22 18:21:19
Message-ID: 20080322182119.GA19999 () morpheus ! apaku ! dnsalias ! org
[Download RAW message or body]
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 :)
--
Best of all is never to have been born. Second best is to die soon.
["kte_annotation_interfaces.diff" (text/x-diff)]
Index: interfaces/ktexteditor/annotationinteractioninterface.h
===================================================================
--- interfaces/ktexteditor/annotationinteractioninterface.h (Revision 0)
+++ interfaces/ktexteditor/annotationinteractioninterface.h (Revision 0)
@@ -0,0 +1,127 @@
+/* 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_ANNOTATIONINTERACTIONINTERFACE_H
+#define KDELIBS_KTEXTEDITOR_ANNOTATIONINTERACTIONINTERFACE_H
+
+#include <ktexteditor/ktexteditor_export.h>
+
+namespace KTextEditor
+{
+
+/**
+ * \brief Annotation interaction interface for the View
+ *
+ * \ingroup kte_group_view_extensions
+ *
+ * \section annointeract_intro Introduction
+ *
+ * The AnnotationInteractionInterface 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 annointeract_access Accessing the AnnoationInteractionInterface
+ *
+ * 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::AnnoationInteractionInterface *iface =
+ * qobject_cast<KTextEditor::AnnoationInteractionInterface*>( view );
+ *
+ * if( iface ) {
+ * // the implementation supports the interface
+ * // do stuff
+ * }
+ * \endcode
+ *
+ */
+class KTEXTEDITOR_EXPORT AnnotationInteractionInterface
+{
+ public:
+ virtual ~AnnotationInteractionInterface();
+
+ /**
+ * 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; +
+ /**
+ * Set the context menu on the annotation border of this view to menu
+ *
+ * \param menu the new context menu to show on the annotation border of this \
view + *
+ * \see annotationContextMenu()
+ * \see defaultAnnotationContextMenu()
+ */
+ virtual void setAnnotationContextMenu( QMenu* menu ) = 0;
+
+ /**
+ * Get the annotation context menu for this view
+ *
+ * \returns the currently set annotation context menu in this view or 0
+ *
+ * \see setAnnotationContextMenu()
+ * \see defaultAnnotationContextMenu()
+ */
+ virtual QMenu* annotationContextMenu( QMenu* ) const = 0;
+
+ /**
+ * Populate menu with default actions for the annotation border
+ *
+ * If menu is null, a new menu will be created
+ *
+ * \param menu the menu to populate, or null to create a new menu
+ *
+ * \returns the menu, wether newly created or passed initially
+ */
+ virtual QMenu* defaultAnnotationContextMenu( QMenu* menu = 0 ) const = 0;
+
+ /**
+ * This signal is emitted when the annotation border was clicked on.
+ *
+ * \param view the view that was clicked in
+ * \param line the document line that the click-posistion belongs to
+ */
+ virtual void annotationLineClicked( View* view, int line ) = 0;
+
+ /**
+ * This signal is emitted when the annotation border was double clicked on.
+ *
+ * \param view the view that was double clicked in
+ * \param line the document line that the click-posistion belongs to
+ */
+ virtual void annotationLineDoubleClicked( View* view, int line ) = 0;
+};
+
+}
+
+Q_DECLARE_INTERFACE(KTextEditor::AnnotationInteractionInterface, \
"org.kde.KTextEditor.AnnotationInteractionInterface") +
+#endif
+
+// kate: space-indent on; indent-width 2; replace-tabs on;
Index: interfaces/ktexteditor/lineannotationprovider.h
===================================================================
--- interfaces/ktexteditor/lineannotationprovider.h (Revision 0)
+++ interfaces/ktexteditor/lineannotationprovider.h (Revision 0)
@@ -0,0 +1,85 @@
+/* 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_LINEANNOTATIONPROVIDER_H
+#define KDELIBS_KTEXTEDITOR_LINEANNOTATIONPROVIDER_H
+
+#include <ktexteditor/ktexteditor_export.h>
+
+#include <QtCore/QVariant>
+
+namespace KTextEditor
+{
+
+/**
+ * \brief An interface for providing line annotation information
+ *
+ * \section lineannoprovide_intro Introduction
+ *
+ * LineAnnotationProvider 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 lineannotprovide_impl Implementing a LineAnnotationProvider
+ *
+ * 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 LineAnnotationProvider
+{
+ public:
+ /**
+ * Identifies which data for a line should be retrieved
+ */
+ enum DataRole {
+ ShortAnnotationRole /** This identifies a short annotation information,
+ * like an author name*/,
+ FullAnnotationRole /** This identifies the complete annotation
+ * information */,
+ BackgroundRole /** Can be used to supply background drawing information
+ * for the annotation */,
+ ForegroundRole /** Can be used to supply foreground drawing information
+ * for the annotation */
+ };
+
+ virtual ~LineAnnotationProvider();
+
+ /**
+ * 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
+ * \ref ShortAnnotationRole and \ref FullAnnotationRole.
+ *
+ * \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. For the
+ * \ref ShortAnnotationRole and \ref FullAnnotationRole the variant should \
contain + * a \ref QString, for the other two roles it might either be a \ref \
QColor or + * a \ref QBrush.
+ */
+ QVariant data( int line, DataRole role ) const = 0;
+};
+
+}
+
+#endif
+
+// kate: space-indent on; indent-width 2; replace-tabs on;
Index: interfaces/ktexteditor/lineannotationinterface.h
===================================================================
--- interfaces/ktexteditor/lineannotationinterface.h (Revision 0)
+++ interfaces/ktexteditor/lineannotationinterface.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_LINEANNOTATIONINTERFACE_H
+#define KDELIBS_KTEXTEDITOR_LINEANNOTATIONINTERFACE_H
+
+#include <ktexteditor/ktexteditor_export.h>
+
+namespace KTextEditor
+{
+
+class LineAnnotationProvider;
+
+/**
+ * \brief A Document extension interface for handling LineAnnotation%s
+ *
+ * \ingroup kte_group_doc_extensions
+ *
+ * \section lineannoiface_intro Introduction
+ *
+ * The LineAnnotationInterface 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 lineannoiface_access Accessing the LineAnnotationInterface
+ *
+ * The LineAnnotationInterface 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::LineAnnotationInterface *iface =
+ * qobject_cast<KTextEditor::LineAnnotationInterface*>( document );
+ *
+ * if( iface ) {
+ * // the implementation supports the interface
+ * // do stuff
+ * }
+ * \endcode
+ *
+ * \section lineannoiface_usage Using the LineAnnotationInterface
+ *
+ * To use the interface simply set your own LineAnnotationProvider via the
+ * \ref setLineAnnotationProvider() method.
+ *
+ * \see KTextEditor::LineAnnotationProvider
+ */
+class KTEXTEDITOR_EXPORT LineAnnotationInterface
+{
+ public:
+ virtual ~LineAnnotationInterface();
+
+ /**
+ * Sets a new \ref LineAnnotationProvider for this document to provide
+ * annotation information for each line.
+ *
+ * \param provider the new LineAnnotationProvider
+ */
+ virtual void setLineAnnotationProvider( LineAnnotationProvider* provider ) = 0;
+
+ /**
+ * returns the currently set \ref LineAnnotationProvider or 0 if there's none
+ * set
+ * @returns the current \ref LineAnnotationProvider
+ */
+ virtual LineAnnotationProvider* lineAnnotationProvider() const = 0;
+
+};
+
+}
+
+Q_DECLARE_INTERFACE(KTextEditor::AnnotationInterface, \
"org.kde.KTextEditor.AnnotationInterface") +
+#endif
+
+// kate: space-indent on; indent-width 2; replace-tabs on;
Index: interfaces/ktexteditor/annotationinteractioninterface.cpp
===================================================================
--- interfaces/ktexteditor/annotationinteractioninterface.cpp (Revision 0)
+++ interfaces/ktexteditor/annotationinteractioninterface.cpp (Revision 0)
@@ -0,0 +1,25 @@
+/* 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.
+*/
+
+#include "annotationinteractioninterface.h"
+
+AnnotationInteractionInterface::~AnnotationInteractionInterface()
+{
+}
+
+// kate: space-indent on; indent-width 2; replace-tabs on;
Index: interfaces/ktexteditor/lineannotationprovider.cpp
===================================================================
--- interfaces/ktexteditor/lineannotationprovider.cpp (Revision 0)
+++ interfaces/ktexteditor/lineannotationprovider.cpp (Revision 0)
@@ -0,0 +1,32 @@
+/* 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.
+*/
+
+#include "lineannotationprovider.h"
+
+using namespace KTextEditor;
+
+LineAnnotationProvider::LineAnnotationProvider()
+ : d(0)
+{
+}
+
+LineAnnotationProvider::~LineAnnotationProvider()
+{
+}
+
+// kate: space-indent on; indent-width 2; replace-tabs on;
Index: interfaces/ktexteditor/lineannotationinterface.cpp
===================================================================
--- interfaces/ktexteditor/lineannotationinterface.cpp (Revision 0)
+++ interfaces/ktexteditor/lineannotationinterface.cpp (Revision 0)
@@ -0,0 +1,27 @@
+/* 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.
+*/
+
+#include "lineannotationinterface.h"
+
+using namespace KTextEditor;
+
+LineAnnotationInterface::~LineAnnotationInterface()
+{
+}
+
+// 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