[prev in list] [next in list] [prev in thread] [next in thread] 

List:       ktexteditor-devel
Subject:    Re: Access to the currently displayed document range
From:       Michel Ludwig <michel.ludwig () kdemail ! net>
Date:       2008-03-26 20:57:20
Message-ID: 200803262157.20567.michel.ludwig () kdemail ! net
[Download RAW message or body]

Hi,

On Wed 26 Mar 2008, Dominik Haumann wrote:
> 1. We just discussed this on IRC and came to the conclusions:
> - rename DisplayInterface to ViewportInterface
> - rename getDisplayedRange to displayRange
> - rename displayedRangeChanged to displayRangeChanged
> - change Q_SIGNALS to public, as the class does not inherit QObject
>   (see variableinterface.h for an example)
> - add documentation that also states that the columns are of importance,
>   think of dynamically wrapped lines
> - the range returned by displayRange() is a object and no pointer, which
>   was a typo in the first place
>
> If I missed anything, please add it :)

I've attached a new version.

> 3. With the above change, we also thought about the already existing
> signals KTE::View::horizontalScrollPositionChanged
>   KTE::View::verticalScrollPositionChanged
> Question is whether they are still needed (or needed at all):
> - Are there use cases where displayedRangeChanged is not enough with
>   regard to verticalScrollPositionChanged?
>   If not, verticalScrollPositionChanged should be marked as \deprecated for
>   KDE5 and the ViewportInterface should be merged into KTE::View.

What if a really long line is shown that is dynamically wrapped and is longer 
than what can be shown in the viewport? Then one could change the vertical 
scroll position but the displayed range would not change...

(I know it's an adventurous use case :-))

> - Is horizontalScrollPositionChanged needed at all? displayedRangeChanged
>   does NOT tell you about this. But I wonder whether anyone uses this
>   signal. If not, it should be marked as \deprecated, too.

My experience as a developer that uses KTextEditor interfaces tells me that 
there are never enough signals! ;-)

Michel

["viewportinterface.h" (text/x-c++hdr)]

/* This file is part of the KDE libraries
   Copyright (C) 2008 Michel Ludwig <michel.ludwig@kdemail.net>

   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_VIEWPORTINTERFACE_H
#define KDELIBS_KTEXTEDITOR_VIEWPORTINTERFACE_H

#include <ktexteditor/ktexteditor_export.h>

class KConfigGroup;

#include <QtCore/QObject>

#include <KTextEditor/Range>
#include <KTextEditor/View>

namespace KTextEditor
{
/**
 * \brief Viewport interface extension for the View.
 *
 * \ingroup kte_group_view_extensions
 *
 * \section viewport_intro Introduction
 *
 * The ViewportInterface is an extension for Views which allows for notifications when the
 * currently displayed document range changes.
 *
 * \section viewport_support Adding Viewport Support
 *
 * To add Viewport support a KTextEditor implementation has to derive the
 * View class from ViewportInterface and reimplement the purely virtual methods defined
 * in this interface.
 *
 * \section viewport_access Accessing the ViewportInterface
 *
 * The ViewportInterface is supposed to be an extension interface for a View, i.e. the
 * View inherits the interface \e provided that it implements the interface. Use qobject_cast to
 * access the implementation:
 * \code
 * // object is of type KTextEditor::View*
 * KTextEditor::ViewportInterface *iface =
 *     qobject_cast<KTextEditor::ViewportInterface*>( object );
 *
 * if( iface ) {
 *     // interface is supported
 *     // do stuff
 * }
 * \endcode
 *
 * \since 4.1
 * \see KTextEditor::View
 * \author Michel Ludwig \<michel.ludwig@kdemail.net\>
 */
class KTEXTEDITOR_EXPORT ViewportInterface
{
  public:
    /**
     * Constructor.
     */
    ViewportInterface();

    /**
     * Virtual destructor.
     */
    virtual ~ViewportInterface();

  public:
    //
    // signals!!
    //
    /**
     * This signal is emitted whenever the displayed document range in \p view
     * changes.
     *
     * \param view View whose displayed document range has changed
     * \warning This 'method' needs to be implemented as a signal!
     * \since 4.1
     */
    void displayRangeChanged(KTextEditor::View *view) = 0;

  public:
    /**
     * Get the range of the document which is currently displayed in the View.
     * Please note that the values for the columns returned are also of particular
     * importance due to the dynamic word wrap feature, for example.
     *
     * \return Range of the document which is currently displayed
     * \since 4.1
     */
    virtual KTextEditor::Range displayRange() = 0;

   private:
    class ViewportInterfacePrivate* const d;
};

}

Q_DECLARE_INTERFACE(KTextEditor::ViewportInterface, "org.kde.KTextEditor.ViewportInterface")

#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]