/*
    SPDX-FileCopyrightText: 2018 Sven Brauch <mail@svenbrauch.de>
    SPDX-FileCopyrightText: 2018 Michal Srb <michalsrb@gmail.com>

    SPDX-License-Identifier: LGPL-2.0-or-later
*/

#ifndef KTEXTEDITOR_INLINENOTEPROVIDER_H
#define KTEXTEDITOR_INLINENOTEPROVIDER_H

#include <ktexteditor_export.h>

#include <ktexteditor/inlinenote.h>

namespace KTextEditor
{
/*!
 * \class KTextEditor::InlineNoteProvider
 * \inmodule KTextEditor
 * \inheaderfile KTextEditor/InlineNoteProvider
 *
 * \brief A source of inline notes for a document.
 *
 * InlineNoteProvider is a object that can be queried for inline notes in the
 * view. It emits signals when the notes change and should be queried again.
 *
 * \sa KTextEditor::View
 * \since 5.50
 */
class KTEXTEDITOR_EXPORT InlineNoteProvider : public QObject
{
    Q_OBJECT

public:
    /*!
     * Default constructor.
     */
    InlineNoteProvider();

    /*!
     * Virtual destructor to allow inheritance.
     */
    ~InlineNoteProvider() override;

    /*!
     * Get list of inline notes for given line.
     *
     * Should return a vector of columns on which the notes are located.
     * 0 means the note is located before the first character of the line.
     * 1 means the note is located after the first character, etc. If the
     * returned number is greater than the length of the line, the note will be
     * placed behind the text as if there were additional spaces.
     *
     * \note When returning multiple InlineNote%s, use Inline\note:index() to
     *       map the InlineNote to this QList's index.
     *
     * \a line Line number
     *
     * Returns vector of columns where inline notes appear in this line
     */
    virtual QList<int> inlineNotes(int line) const = 0;

    /*!
     * Width to be reserved for the note in the text.
     *
     * Typically, a custom width with the current line height can be returned.
     * If the width depends on the font size, note.font() can be used to obtain
     * the font metrics.
     *
     * Example to reserve a square size for painting:
     * \code
     * return QSize(note.lineHeight(), lineHeight());
     * \endcode
     *
     * \note Do not return heights that are larger than note.lineHeight(),
     *       since the painting code clips to the line height anyways.
     *
     * \a note the InlineNote for which the size is queried
     *
     * Returns the required size of the InlineNote
     */
    virtual QSize inlineNoteSize(const InlineNote &note) const = 0;

    /*!
     * Paint the note into the line.
     *
     * The method should use the given painter to render the note into the
     * line. The painter is translated such that coordinates 0x0 mark the top
     * left corner of the note. The method should not paint outside rectangle
     * given by the size previously returned by inlineNoteSize().
     *
     * The method is given the height of the line, the metrics of current font
     * and the font which it may use during painting.
     *
     * If wanted, you can use note.underMouse() to e.g. highlight the
     *
     * \a note is the note to paint, containing location and index
     *
     * \a painter painter prepared for rendering the note
     *
     * \a direction direction of the line i.e., right to left/left to right
     *
     */
    virtual void paintInlineNote(const InlineNote &note, QPainter &painter, Qt::LayoutDirection direction) const = 0;

    /*!
     * Invoked when a note is activated by the user.
     *
     * This method is called when a user activates a note, i.e. clicks on it.
     * Coordinates of \a pos are in note coordinates, i.e.  relative to the note's
     * top-left corner (same coordinate system as the painter has in paintInlineNote()).
     *
     * The default implementation does nothing.
     *
     * \a note is the note which was activated
     *
     * \a buttons is the button(s) the note was clicked with
     *
     * \a globalPos is the point the note was clicked at in global screen coordinates
     *
     */
    virtual void inlineNoteActivated(const InlineNote &note, Qt::MouseButtons buttons, const QPoint &globalPos);

    /*!
     * Invoked when the mouse cursor moves into the \a note when it was outside before.
     *
     * The default implementation does nothing.
     *
     * \a note is the note which was activated
     *
     * \a globalPos is the location of the mouse cursor in global screen coordinates
     *
     */
    virtual void inlineNoteFocusInEvent(const InlineNote &note, const QPoint &globalPos);

    /*!
     * Invoked when the mouse cursor leaves the note.
     *
     * The default implementation does nothing.
     *
     * \a note the note which was deactivated
     */
    virtual void inlineNoteFocusOutEvent(const InlineNote &note);

    /*!
     * Invoked when the mouse cursor moves inside the note.
     *
     * The default implementation does nothing.
     *
     * \a note is the note which was hovered
     *
     * \a globalPos is the location of the mouse cursor in global screen coordinates
     *
     */
    virtual void inlineNoteMouseMoveEvent(const InlineNote &note, const QPoint &globalPos);

Q_SIGNALS:
    /*!
     * The provider should emit the signal inlineNotesReset() when almost all inline notes
     * changed.
     */
    void inlineNotesReset();

    /*!
     * The provider should emit the signal inlineNotesChanged() whenever one
     * or more InlineNote%s on the line changed.
     */
    void inlineNotesChanged(int line);

private:
    class InlineNoteProviderPrivate *const d = nullptr;
};

}

#endif