File indexing completed on 2024-05-12 15:45:39

 /*
     SPDX-FileCopyrightText: 2017-2018 Friedrich W. H. Kossebau <kossebau@kde.org>
 
     SPDX-License-Identifier: LGPL-2.0-or-later
 */
 
 #ifndef KTEXTEDITOR_ABSTRACTANNOTATIONITEMDELEGATE_H
 #define KTEXTEDITOR_ABSTRACTANNOTATIONITEMDELEGATE_H
 
 #include <ktexteditor_export.h>
 
 #include <QObject>
 #include <QStyleOption>
 
 class QHelpEvent;
 class QPoint;
 
 namespace KTextEditor
 {
 class AnnotationModel;
 class View;
 
 /**
  * \brief The style option set for an annotation item, as painted by AbstractAnnotationItemDelegate
  *
  * \since 5.53
  * \see KTextEditor::AbstractAnnotationItemDelegate
  */
 class KTEXTEDITOR_EXPORT StyleOptionAnnotationItem : public QStyleOption
 {
 public:
     // TODO: not sure what SO_Default implies, but no clue how to maintain a user type registry?
     enum StyleOptionType { Type = SO_Default };
     enum StyleOptionVersion { Version = 1 };
 
     /**
      * Index of the displayed line in the wrapped lines for the given real line
      */
     int wrappedLine = 0;
     /**
      * Number of wrapped lines for the given real line
      *
      * A value of 1 means no wrapping has happened and the real line is displayed as one line.
      */
     int wrappedLineCount = 1;
     /**
      * Index of the displayed line in the displayed lines for the same group
      */
     int visibleWrappedLineInGroup = 0;
 
     /**
      * The view where the annotation is shown
      *
      * There is always a view set.
      */
     KTextEditor::View *view = nullptr;
     /**
      * Recommended size for icons or other symbols that will be rendered by the delegate
      *
      * The default value is QSize(-1, -1).
      */
     QSize decorationSize;
     /**
      * The metrics of the font used for rendering the text document
      */
     QFontMetricsF contentFontMetrics;
 
     /**
      * Enum for describing the relative position of a real line in the row of consecutive
      * displayed lines which belong to the same group of annotation items
      * @see AnnotationItemGroupPositions
      */
     enum AnnotationItemGroupPosition {
         InvalidGroupPosition = 0, ///< Position not specified or not belonging to a group
         InGroup = 0x1 << 0, ///< Real line belongs to a group
         GroupBegin = 0x1 << 1, ///< Real line is first of consecutive lines from same group
         GroupEnd = 0x1 << 2, ///< Real line is last of consecutive lines from same group
     };
     /// Stores a combination of #AnnotationItemGroupPosition values.
     Q_DECLARE_FLAGS(AnnotationItemGroupPositions, AnnotationItemGroupPosition)
 
     /**
      * Relative position of the real line in the row of consecutive displayed lines
      * which belong to the same group of annotation items
      */
     AnnotationItemGroupPositions annotationItemGroupingPosition = InvalidGroupPosition;
 
 public:
     StyleOptionAnnotationItem();
     StyleOptionAnnotationItem(const StyleOptionAnnotationItem &other);
     StyleOptionAnnotationItem &operator=(const StyleOptionAnnotationItem &) = default;
 
 protected:
     explicit StyleOptionAnnotationItem(int version);
 };
 
 /**
  * \class AbstractAnnotationItemDelegate abstractannotationitemdelegate.h <KTextEditor/AbstractAnnotationItemDelegate>
  *
  * \brief A delegate for rendering line annotation information and handling events
  *
  * \section annodelegate_intro Introduction
  *
  * AbstractAnnotationItemDelegate is a base class that can be reimplemented
  * to customize the rendering of annotation information for each line in a document.
  * It provides also the hooks to define handling of help events like tooltip or of
  * the request for a context menu.
  *
  * \section annodelegate_impl Implementing an AbstractAnnotationItemDelegate
  *
  * The public interface of this class is loosely based on the QAbstractItemDelegate
  * interfaces. It has five methods to implement.
  *
  * \since 5.53
  * \see KTextEditor::AnnotationModel, KTextEditor::AnnotationViewInterfaceV2
  */
 class KTEXTEDITOR_EXPORT AbstractAnnotationItemDelegate : public QObject
 {
     Q_OBJECT
 
 protected:
     explicit AbstractAnnotationItemDelegate(QObject *parent = nullptr);
 
 public:
     ~AbstractAnnotationItemDelegate() override;
 
 public:
     /**
      * This pure abstract function must be reimplemented to provide custom rendering.
      * Use the painter and style option to render the annotation information for the line
      * specified by the arguments @p model and @p line.
      * @param painter the painter object
      * @param option the option object with the info needed for styling
      * @param model the annotation model providing the annotation information
      * @param line index of the real line the annotation information should be painted for
      *
      * Reimplement this in line with sizeHint().
      */
     virtual void paint(QPainter *painter, const KTextEditor::StyleOptionAnnotationItem &option, KTextEditor::AnnotationModel *model, int line) const = 0;
     /**
      * This pure abstract function must be reimplemented to provide custom rendering.
      * Use the style option to calculate the best size for the annotation information
      * for the line specified by the arguments @p model and @p line.
      * This should be the size for the display for a single displayed content line,
      * i.e. with no line wrapping or consecutive multiple annotation item of the same group assumed.
      *
      * @note If AnnotationViewInterfaceV2::uniformAnnotationItemSizes() is @c true for the view
      * this delegate is used by, it is assumed that the returned value is the same for
      * any line.
      *
      * @param option the option object with the info needed for styling
      * @param model the annotation model providing the annotation information
      * @param line index of the real line the annotation information should be painted for
      * @return best size for the annotation information
      *
      * Reimplement this in line with paint().
      */
     virtual QSize sizeHint(const KTextEditor::StyleOptionAnnotationItem &option, KTextEditor::AnnotationModel *model, int line) const = 0;
     /**
      * Whenever a help event occurs, this function is called with the event view option
      * and @p model and @p line specifying the item where the event occurs.
      * This pure abstract function must be reimplemented to provide custom tooltips.
      * @param event the help event
      * @param view the view for which the help event is requested
      * @param option the style option object with the info needed for styling, including the rect of the annotation
      * @param model the annotation model providing the annotation information
      * @param line index of the real line the annotation information should be painted for
      * @return @c true if the event could be handled (implies that the data obtained from the model had the required role), @c false otherwise
      *
      * Reimplement this in line with hideTooltip().
      */
     virtual bool helpEvent(QHelpEvent *event,
                            KTextEditor::View *view,
                            const KTextEditor::StyleOptionAnnotationItem &option,
                            KTextEditor::AnnotationModel *model,
                            int line) = 0;
     /**
      * This pure abstract function must be reimplemented to provide custom tooltips.
      * It is called whenever a possible still shown tooltip no longer is valid,
      * e.g. if the annotations have been hidden.
      * @param view the view for which the tooltip was requested
      *
      * Reimplement this in line with helpEvent().
      */
     virtual void hideTooltip(KTextEditor::View *view) = 0;
 
 Q_SIGNALS:
     /**
      * This signal must be emitted when the sizeHint() for @p model and @p line changed.
      * The view automatically connects to this signal and relayouts as necessary.
      * If AnnotationViewInterfaceV2::uniformAnnotationItemSizes is set on the view,
      * it is sufficient to emit sizeHintChanged only for one line.
      * @param model the annotation model providing the annotation information
      * @param line index of the real line the annotation information should be painted for
      */
     void sizeHintChanged(KTextEditor::AnnotationModel *model, int line);
 };
 
 }
 
 #endif