/* ============================================================
 *
 * This file is a part of digiKam project
 * https://www.digikam.org
 *
 * Date        : 2004-07-03
 * Description : dialog-like popup that displays messages without interrupting the user
 *
 * SPDX-FileCopyrightText: 2009-2026 by Gilles Caulier <caulier dot gilles at gmail dot com>
 * SPDX-FileCopyrightText: 2001-2006 by Richard Moore <rich at kde dot org>
 * SPDX-FileCopyrightText: 2004-2005 by Sascha Cunz <sascha.cunz at tiscali dot de>
 *
 * SPDX-License-Identifier: GPL-2.0-or-later
 *
 * ============================================================ */

#pragma once

// Qt includes

#include <QFrame>

// Local includes

#include "digikam_export.h"

class QSystemTrayIcon;

namespace Digikam
{

/**
 * @short A dialog-like popup that displays messages without interrupting the user.
 *
 * The simplest uses of DNotificationPopup are by using the various message() static
 * methods. The position the popup appears at depends on the type of the parent window:
 *
 */
class DIGIKAM_EXPORT DNotificationPopup : public QFrame
{
    Q_OBJECT
    Q_PROPERTY(bool autoDelete READ autoDelete WRITE setAutoDelete)
    Q_PROPERTY(int timeout     READ timeout    WRITE setTimeout)

public:

    /**
     * Styles that a DNotificationPopup can have.
     */
    enum PopupStyle
    {
        Boxed,             ///< Information will appear in a framed box (default)
        Balloon,           ///< Information will appear in a comic-alike balloon
    };

public:

    /**
     * Creates a popup for the specified widget.
     */
    explicit DNotificationPopup(QWidget* const parent = nullptr, Qt::WindowFlags f = Qt::WindowFlags());

    /**
     * Creates a popup for the specified window.
     */
    explicit DNotificationPopup(WId parent);

    /**
     * Cleans up.
     */
    ~DNotificationPopup() override;

    /**
     * Sets the main view to be the specified widget (which must be a child of the popup).
     */
    void setView(QWidget* child);

    /**
     * Creates a standard view then calls setView(QWidget*) .
     */
    void setView(const QString& caption, const QString& text = QString());

    /**
     * Creates a standard view then calls setView(QWidget*) .
     */
    virtual void setView(const QString& caption, const QString& text, const QPixmap& icon);

    /**
     * Returns a widget that is used as standard view if one of the
     * setView() methods taking the QString arguments is used.
     * You can use the returned widget to customize the passivepopup while
     * keeping the look similar to the "standard" passivepopups.
     *
     * After customizing the widget, pass it to setView( QWidget* )
     *
     * @param caption The window caption (title) on the popup
     * @param text The text for the popup
     * @param icon The icon to use for the popup
     * @param parent The parent widget used for the returned widget. If left 0,
     * then "this", i.e. the passive popup object will be used.
     *
     * @return a QWidget containing the given arguments, looking like the
     * standard passivepopups. The returned widget contains a QVBoxLayout,
     * which is accessible through layout().
     * @see setView( QWidget * )
     * @see setView( const QString&, const QString& )
     * @see setView( const QString&, const QString&, const QPixmap& )
     */
    QWidget* standardView(const QString& caption, const QString& text,
                          const QPixmap& icon, QWidget* parent = nullptr);

    /**
     * Returns the main view.
     */
    QWidget* view() const;

    /**
     * Returns the delay before the popup is removed automatically.
     */
    int timeout() const;

    /**
     * Sets whether the popup will be deleted when it is hidden.
     *
     * The default is false (unless created by one of the static
     * message() overloads).
     */
    virtual void setAutoDelete(bool autoDelete);

    /**
     * Returns whether the popup will be deleted when it is hidden.
     *
     * @see setAutoDelete
     */
    bool autoDelete() const;

    /**
     * Returns the position to which this popup is anchored.
     */
    QPoint anchor() const;

    /**
     * Sets the anchor of this popup.
     *
     * The popup is placed near to the anchor.
     */
    void setAnchor(const QPoint& anchor);

    /**
     * Convenience method that displays popup with the specified  message  beside the
     * icon of the specified widget.
     * Note that the returned object is destroyed when it is hidden.
     * @see setAutoDelete
     */
    static DNotificationPopup* message(const QString& text, QWidget* parent,
                                       const QPoint& p = QPoint());

    /**
     * Convenience method that displays popup with the specified  message  beside the
     * icon of the specified QSystemTrayIcon.
     * Note that the returned object is destroyed when it is hidden.
     * @see setAutoDelete
     */
    static DNotificationPopup* message(const QString& text, QSystemTrayIcon* parent);

    /**
     * Convenience method that displays popup with the specified caption and message
     * beside the icon of the specified widget.
     * Note that the returned object is destroyed when it is hidden.
     * @see setAutoDelete
     */
    static DNotificationPopup* message(const QString& caption, const QString& text,
                                       QWidget* parent, const QPoint& p = QPoint());

    /**
     * Convenience method that displays popup with the specified caption and message
     * beside the icon of the specified QSystemTrayIcon.
     * Note that the returned object is destroyed when it is hidden.
     * @see setAutoDelete
     */
    static DNotificationPopup* message(const QString& caption, const QString& text,
                                       QSystemTrayIcon* parent);

    /**
     * Convenience method that displays popup with the specified icon, caption and
     * message beside the icon of the specified widget.
     * Note that the returned object is destroyed when it is hidden.
     * @see setAutoDelete
     */
    static DNotificationPopup* message(const QString& caption, const QString& text,
                                       const QPixmap& icon, QWidget* parent, int timeout = -1,
                                       const QPoint& p = QPoint());

    /**
     * Convenience method that displays popup with the specified icon, caption and
     * message beside the icon of the specified QSystemTrayIcon.
     * Note that the returned object is destroyed when it is hidden.
     * @see setAutoDelete
     */
    static DNotificationPopup* message(const QString& caption, const QString& text,
                                       const QPixmap& icon, QSystemTrayIcon* parent, int timeout = -1);

    /**
     * Convenience method that displays popup with the specified icon, caption and
     * message beside the icon of the specified window.
     * Note that the returned object is destroyed when it is hidden.
     * @see setAutoDelete
     */
    static DNotificationPopup* message(const QString& caption, const QString& text,
                                       const QPixmap& icon, WId parent,
                                       int timeout = -1, const QPoint& p = QPoint());

    /**
     * Convenience method that displays popup with the specified popup-style and message beside the
     * icon of the specified widget.
     * Note that the returned object is destroyed when it is hidden.
     * @see setAutoDelete
     */
    static DNotificationPopup* message(int popupStyle, const QString& text, QWidget* parent, const QPoint& p = QPoint());

    /**
     * Convenience method that displays popup with the specified popup-style and message beside the
     * icon of the specified QSystemTrayIcon.
     * Note that the returned object is destroyed when it is hidden.
     * @see setAutoDelete
     */
    static DNotificationPopup* message(int popupStyle, const QString& text, QSystemTrayIcon* parent);

    /**
     * Convenience method that displays popup with the specified popup-style, caption and message
     * beside the icon of the specified QSystemTrayIcon.
     * Note that the returned object is destroyed when it is hidden.
     * @see setAutoDelete
     */
    static DNotificationPopup* message(int popupStyle, const QString& caption, const QString& text,
                                       QSystemTrayIcon* parent);

    /**
     * Convenience method that displays popup with the specified popup-style, caption and message
     * beside the icon of the specified widget.
     * Note that the returned object is destroyed when it is hidden.
     * @see setAutoDelete
     */
    static DNotificationPopup* message(int popupStyle, const QString& caption, const QString& text,
                                       QWidget* parent, const QPoint& p = QPoint());

    /**
     * Convenience method that displays popup with the specified popup-style, icon, caption and
     * message beside the icon of the specified widget.
     * Note that the returned object is destroyed when it is hidden.
     * @see setAutoDelete
     */
    static DNotificationPopup* message(int popupStyle, const QString& caption, const QString& text,
                                       const QPixmap& icon, QWidget* parent, int timeout = -1,
                                       const QPoint& p = QPoint());

    /**
     * Convenience method that displays popup with the specified popup-style, icon, caption and
     * message beside the icon of the specified QSystemTrayIcon.
     * Note that the returned object is destroyed when it is hidden.
     * @see setAutoDelete
     */
    static DNotificationPopup* message(int popupStyle, const QString& caption, const QString& text,
                                       const QPixmap& icon, QSystemTrayIcon* parent, int timeout = -1);

    /**
     * Convenience method that displays popup with the specified popup-style, icon, caption and
     * message beside the icon of the specified window.
     * Note that the returned object is destroyed when it is hidden.
     * @see setAutoDelete
     */
    static DNotificationPopup* message(int popupStyle, const QString& caption, const QString& text,
                                       const QPixmap& icon, WId parent, int timeout = -1,
                                       const QPoint& p = QPoint());

    /**
     * we create an overloaded version of show()
     */
    using QFrame::show;

public Q_SLOTS:

    /**
     * Sets the delay for the popup is removed automatically. Setting the delay to 0
     * disables the timeout, if you're doing this, you may want to connect the
     * clicked() signal to the hide() slot.
     * Setting the delay to -1 makes it use the default value.
     *
     * @see timeout
     */
    void setTimeout(int delay);

    /**
     * Sets the visual appearance of the popup.
     * @see PopupStyle
     */
    void setPopupStyle(int popupstyle);

    /**
     * Shows the popup in the given point
     */
    void show(const QPoint& p);

    void setVisible(bool visible) override;

Q_SIGNALS:

    /**
     * Emitted when the popup is clicked.
     */
    void clicked();

    /**
     * Emitted when the popup is clicked at a specific position.
     */
    void clickedAt(const QPoint& pos);

protected:

    /**
     * Positions the popup.
     *
     * The default implementation attempts to place it by the taskbar
     * entry; failing that it places it by the window of the associated
     * widget; failing that it places it at the location given by
     * defaultLocation().
     *
     * @see moveNear()
     */
    virtual void positionSelf();

    /**
     * Returns a default location for popups when a better placement
     * cannot be found.
     *
     * The default implementation returns the top-left corner of the
     * available work area of the desktop (ie: minus panels, etc).
     */
    virtual QPoint defaultLocation() const;

    /**
     * Moves the popup to be adjacent to @p target.
     *
     * The popup will be placed adjacent to, but outside of, @p target,
     * without going off the current desktop.
     *
     * Reimplementations of positionSelf() can use this to actually
     * position the popup.
     */
    void moveNear(const QRect& target);

    void hideEvent(QHideEvent*) override;
    void mouseReleaseEvent(QMouseEvent* e) override;
    void paintEvent(QPaintEvent* pe) override;

private:

    class Private;
    Private* const d = nullptr;
};

} // namespace Digikam
