[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:       Dominik Haumann <dhdev () gmx ! de>
Date:       2008-03-23 14:09:09
Message-ID: 200803231509.10117.dhdev () gmx ! de
[Download RAW message or body]

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.

2. AnnotationInteractionInterface (View extension interface)

a) Right now, if an annotation provider is set, all views show the annotation
   border. However, line numbers etc are configurable for every view
   independently. This is inconsistent. Possble solution: Add a
   showAnnotations(bool enable) to AnnotationInteractionInterface.

+ virtual void annotationContextMenuAboutToShow( View* view, QMenu* menu, int line ) = 0;

   *think* Isn't that already enough?

   Kate Part impl could be something like:
   void KateView::contextMenuEvent()
   {
     QMenu menu;
     // let the annotation clients can fill the menu... they can connect to
     // the QAction immediately and get what happens this way
     emit annotationContextMenuAboutToShow(this, &menu, the_line);
     if (!menu.isEmpty()) {
       // aha, someone added items -> show the menu
     }
   }

   I don't see why those are needed in addition. Do you have a use case? :)
+    virtual void setAnnotationContextMenu( QMenu* menu ) = 0;
+    virtual QMenu* annotationContextMenu( QMenu* ) const = 0;
+    virtual QMenu* defaultAnnotationContextMenu( QMenu* menu = 0 ) const = 0;

   I can imagine that when clicked you can choose a revision for diffing.
+    virtual void annotationLineClicked( View* view, int line ) = 0;

   What's the use case for double clicking? Especially because a double click
   always emits a single click in advance.
+    virtual void annotationLineDoubleClicked( View* view, int line ) = 0;
   If we don't need this, we could even think about renaming annotationLineClicked
   to annotationLineActivated.

b) rename to AnnotationInterface
   See also 5.

3. LineAnnotationProvider
a) rename to AnnotationProvider (or AnnotaitonModel). The 'line' is implicit
   in the function 'data(line, role)'.

b) svn annotate is of the form
   <revision>    <author>    <text>
   ShortAnnotationRole is revision + author in this case, isn't it?
   svn annotate aligns the information in columns. So I think it would make
   sense to separate this, too. If ShortAnnotationRole is revision + author
   then we cannot have the nice alignment, or do I miss something?
   PS: Personally, I find the revision number very important, you can e.g.
       discard an old commit immediately, or see it's the same as others lines.

   *Thinking about use cases*
   First is of course a VCS. there you have revision + author + line.
   Otoh, it could also be collaborative editing, where we maybe only want to
   set a name (e.g. line changed by userX).
   ...which leads to the question: Is this meant for VCS only?

c) Can we reuse Qt::ItemDataRole here instead of defining a new one?
   At least we can map the existing items pretty good:
   ShortAnnotationRole -> DisplayRole
   FullAnnotationRole  -> ToolTipRole
   Backgroundrole      -> Backgroundrole
   ForegroundRole      -> ForegroundRole
   <missing>           -> Qt::UserRole or Qt::EditRole (== revision)
   Of course the documentation still has to state what roles are used
   for what purposes. Otoh, maybe this simply doesn't make sense and we simply
   should use a new enum.

4. LineAnnotationInterface
   Right now it's a Document extension interface. If we decide to make it a
   view extension interface only we could remove this interface completely
   and move the two functions
+    virtual voie setAnnotationProvider( AnnotationProvider* provider ) = 0;
+    virtual AnnotationProvider* annotationProvider() const = 0;
   to the View.

5. Naming (just ideas)
   AnnotationInteractionInterface -> AnnotationInterface
   LineAnnotationProvider -> AnnotationProvider or AnnotationModel (just
   like CodeCompletionModel)
   LineAnnotationInterface -> remove in favour of only View extension (???)

6. Documentation
   Typo, if we stick to LineAnnotationInterface :)
-Q_DECLARE_INTERFACE(KTextEditor::AnnotationInterface, "org.kde.KTextEditor.AnnotationInterface")
+Q_DECLARE_INTERFACE(KTextEditor::LineAnnotationInterface, "org.kde.KTextEditor.LineAnnotationInterface")

   enum DataRole:
+      ShortAnnotationRole /** This identifies a short annotation information,
+                           * like an author name*/,
   Those doxygen comments do not work, either use ///< or/**<, or if the
   documentation is long, it makes sense to move it before the item:
+      /**
+       * This identifies a short annotation information, like an author name.
+       */
+      ShortAnnotationRole,

   Typo:
- * allows to react on clicks, double clicks on and provde context menus for the
+ * allows to react on clicks, double clicks on and provide context menus for the

7. Thoughts
   Do you plan to implement it in Kate Part for KDE 4.1? If not, it makes
   sense to move the integration to KDE 4.2, so we can still change the
   KTE interface.

Dominik
_______________________________________________
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]