File indexing completed on 2024-05-12 15:45:40
0001 /* 0002 SPDX-FileCopyrightText: 2018 Sven Brauch <mail@svenbrauch.de> 0003 SPDX-FileCopyrightText: 2018 Michal Srb <michalsrb@gmail.com> 0004 0005 SPDX-License-Identifier: LGPL-2.0-or-later 0006 */ 0007 0008 #ifndef KTEXTEDITOR_INLINENOTEPROVIDER_H 0009 #define KTEXTEDITOR_INLINENOTEPROVIDER_H 0010 0011 #include <ktexteditor_export.h> 0012 0013 #include <ktexteditor/inlinenote.h> 0014 0015 namespace KTextEditor 0016 { 0017 /** 0018 * @class InlineNoteProvider inlinenoteprovider.h <KTextEditor/InlineNoteProvider> 0019 * 0020 * @brief A source of inline notes for a document. 0021 * 0022 * InlineNoteProvider is a object that can be queried for inline notes in the 0023 * view. It emits signals when the notes change and should be queried again. 0024 * 0025 * @see InlineNoteInterface 0026 * @since 5.50 0027 */ 0028 class KTEXTEDITOR_EXPORT InlineNoteProvider : public QObject 0029 { 0030 Q_OBJECT 0031 0032 public: 0033 /** 0034 * Default constructor. 0035 */ 0036 InlineNoteProvider(); 0037 0038 /** 0039 * Virtual destructor to allow inheritance. 0040 */ 0041 ~InlineNoteProvider() override; 0042 0043 /** 0044 * Get list of inline notes for given line. 0045 * 0046 * Should return a vector of columns on which the notes are located. 0047 * 0 means the note is located before the first character of the line. 0048 * 1 means the note is located after the first character, etc. If the 0049 * returned number is greater than the length of the line, the note will be 0050 * placed behind the text as if there were additional spaces. 0051 * 0052 * @note When returning multiple InlineNote%s, use InlineNote::index() to 0053 * map the InlineNote to this QVector's index. 0054 * 0055 * @param line Line number 0056 * @returns vector of columns where inline notes appear in this line 0057 */ 0058 virtual QVector<int> inlineNotes(int line) const = 0; 0059 0060 /** 0061 * Width to be reserved for the note in the text. 0062 * 0063 * Typically, a custom width with the current line height can be returned. 0064 * If the width depends on the font size, note.font() can be used to obtain 0065 * the font metrics. 0066 * 0067 * Example to reserve a square size for painting: 0068 * @code 0069 * return QSize(note.lineHeight(), lineHeight()); 0070 * @endcode 0071 * 0072 * @note Do not return heights that are larger than note.lineHeight(), 0073 * since the painting code clips to the line height anyways. 0074 * 0075 * @param note the InlineNote for which the size is queried 0076 * @return the required size of the InlineNote 0077 */ 0078 virtual QSize inlineNoteSize(const InlineNote ¬e) const = 0; 0079 0080 /** 0081 * Paint the note into the line. 0082 * 0083 * The method should use the given painter to render the note into the 0084 * line. The painter is translated such that coordinates 0x0 mark the top 0085 * left corner of the note. The method should not paint outside rectangle 0086 * given by the size previously returned by inlineNoteSize(). 0087 * 0088 * The method is given the height of the line, the metrics of current font 0089 * and the font which it may use during painting. 0090 * 0091 * If wanted, you can use note.underMouse() to e.g. highlight the 0092 * 0093 * @param note note to paint, containing location and index 0094 * @param painter painter prepared for rendering the note 0095 */ 0096 virtual void paintInlineNote(const InlineNote ¬e, QPainter &painter) const = 0; 0097 0098 /** 0099 * Invoked when a note is activated by the user. 0100 * 0101 * This method is called when a user activates a note, i.e. clicks on it. 0102 * Coordinates of @p pos are in note coordinates, i.e. relative to the note's 0103 * top-left corner (same coordinate system as the painter has in paintInlineNote()). 0104 * 0105 * The default implementation does nothing. 0106 * 0107 * @param note the note which was activated 0108 * @param buttons the button(s) the note was clicked with 0109 * @param globalPos the point the note was clicked at in global screen coordinates 0110 */ 0111 virtual void inlineNoteActivated(const InlineNote ¬e, Qt::MouseButtons buttons, const QPoint &globalPos); 0112 0113 /** 0114 * Invoked when the mouse cursor moves into the @p note when it was outside before. 0115 * 0116 * The default implementation does nothing. 0117 * 0118 * @param note the note which was activated 0119 * @param globalPos the location of the mouse cursor in global screen coordinates 0120 */ 0121 virtual void inlineNoteFocusInEvent(const InlineNote ¬e, const QPoint &globalPos); 0122 0123 /** 0124 * Invoked when the mouse cursor leaves the note. 0125 * 0126 * The default implementation does nothing. 0127 * 0128 * @param note the note which was deactivated 0129 */ 0130 virtual void inlineNoteFocusOutEvent(const InlineNote ¬e); 0131 0132 /** 0133 * Invoked when the mouse cursor moves inside the note. 0134 * 0135 * The default implementation does nothing. 0136 * 0137 * @param note the note which was hovered 0138 * @param globalPos the location of the mouse cursor in global screen coordinates 0139 */ 0140 virtual void inlineNoteMouseMoveEvent(const InlineNote ¬e, const QPoint &globalPos); 0141 0142 Q_SIGNALS: 0143 /** 0144 * The provider should emit the signal inlineNotesReset() when almost all inline notes 0145 * changed. 0146 */ 0147 void inlineNotesReset(); 0148 0149 /** 0150 * The provider should emit the signal inlineNotesChanged() whenever one 0151 * or more InlineNote%s on the line changed. 0152 */ 0153 void inlineNotesChanged(int line); 0154 0155 private: 0156 class InlineNoteProviderPrivate *const d = nullptr; 0157 }; 0158 0159 } 0160 0161 #endif