1 /***************************************************************************
2                              qgsannotationitemwidget.h
3                              ------------------------
4     Date                 : September 2021
5     Copyright            : (C) 2021 Nyall Dawson
6     Email                : nyall dot dawson at gmail dot com
7  ***************************************************************************
8  *                                                                         *
9  *   This program is free software; you can redistribute it and/or modify  *
10  *   it under the terms of the GNU General Public License as published by  *
11  *   the Free Software Foundation; either version 2 of the License, or     *
12  *   (at your option) any later version.                                   *
13  *                                                                         *
14  ***************************************************************************/
15 #ifndef QGSANNOTATIONITEMWIDGET_H
16 #define QGSANNOTATIONITEMWIDGET_H
17 
18 #include "qgis_gui.h"
19 #include "qgis_sip.h"
20 #include "qgspanelwidget.h"
21 #include "qgssymbolwidgetcontext.h"
22 
23 class QgsAnnotationItem;
24 
25 /**
26  * \class QgsAnnotationItemBaseWidget
27  * \ingroup gui
28  *
29  * \brief A base class for property widgets for annotation items.
30  *
31  * All annotation item widgets should inherit from this base class.
32  *
33  * \since QGIS 3.22
34 */
35 class GUI_EXPORT QgsAnnotationItemBaseWidget: public QgsPanelWidget
36 {
37     Q_OBJECT
38 
39   public:
40 
41     /**
42      * Constructor for QgsAnnotationItemBaseWidget.
43      */
44     QgsAnnotationItemBaseWidget( QWidget *parent SIP_TRANSFERTHIS );
45 
46     /**
47      * Creates a new item matching the settings defined in the widget.
48      */
49     virtual QgsAnnotationItem *createItem() = 0 SIP_FACTORY;
50 
51     /**
52      * Updates an existing item to match the settings defined in the widget.
53      */
54     virtual void updateItem( QgsAnnotationItem *item ) = 0;
55 
56     /**
57      * Sets the current \a item to show in the widget. If TRUE is returned, \a item
58      * was an acceptable type for display in this widget and the widget has been
59      * updated to match \a item's properties.
60      *
61      * If FALSE is returned, then the widget could not be successfully updated
62      * to show the properties of \a item.
63      */
64     bool setItem( QgsAnnotationItem *item );
65 
66     /**
67      * Sets the \a context in which the widget is shown, e.g., the associated map canvas and expression contexts.
68      * \see context()
69      */
70     virtual void setContext( const QgsSymbolWidgetContext &context );
71 
72     /**
73      * Returns the context in which the widget is shown, e.g., the associated map canvas and expression contexts.
74      * \see setContext()
75      */
76     QgsSymbolWidgetContext context() const;
77 
78   public slots:
79 
80     /**
81      * Focuses the default widget for the page.
82      */
83     virtual void focusDefaultWidget();
84 
85   signals:
86 
87     /**
88      * Emitted when the annotation item definition in the widget is changed by the user.
89      */
90     void itemChanged();
91 
92   protected:
93 
94     /**
95      * Attempts to update the widget to show the properties
96      * for the specified \a item.
97      *
98      * Subclasses can override this if they support changing items in place.
99      *
100      * Implementations must return TRUE if the item was accepted and
101      * the widget was updated.
102      */
103     virtual bool setNewItem( QgsAnnotationItem *item );
104 
105     //! Context in which widget is shown
106     QgsSymbolWidgetContext mContext;
107 };
108 
109 #endif // QGSANNOTATIONITEMWIDGET_H
110