1 /* This file is part of the KDE libraries
2     Copyright (C) 2004 Ariya Hidayat <ariya@kde.org>
3     Copyright (C) 2006 Peter Simonsson <peter.simonsson@gmail.com>
4 
5     This library is free software; you can redistribute it and/or
6     modify it under the terms of the GNU Library General Public
7     License version 2 as published by the Free Software Foundation.
8 
9     This library is distributed in the hope that it will be useful,
10     but WITHOUT ANY WARRANTY; without even the implied warranty of
11     MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE.  See the GNU
12     Library General Public License for more details.
13 
14     You should have received a copy of the GNU Library General Public License
15     along with this library; see the file COPYING.LIB.  If not, write to
16     the Free Software Foundation, Inc., 51 Franklin Street, Fifth Floor,
17     Boston, MA 02110-1301, USA.
18 */
19 
20 #ifndef KOZOOMACTION_H
21 #define KOZOOMACTION_H
22 
23 #include <kselectaction.h>
24 #include <KoZoomMode.h>
25 
26 #include "kowidgets_export.h"
27 
28 /**
29  * Class KoZoomAction implements an action to provide zoom values.
30  * In a toolbar, KoZoomAction will show a dropdown list (combobox), also with
31  * the possibility for the user to enter arbritrary zoom value
32  * (must be an integer). The values shown on the list are always
33  * sorted.
34  * In a statusbar it provides a scale (slider) plus an editable value plus
35  * some buttons for special zoommodes
36  */
37 class KOWIDGETS_EXPORT KoZoomAction : public KSelectAction
38 {
39     Q_OBJECT
40     Q_PROPERTY(qreal effectiveZoom READ effectiveZoom NOTIFY zoomChanged)
41 public:
42 
43   /**
44    * Creates a new zoom action.
45    * @param zoomModes which zoom modes that should be shown
46    * @param text The text that will be displayed.
47    * @param parent The action's parent object.
48    */
49     KoZoomAction( KoZoomMode::Modes zoomModes, const QString& text, QObject *parent);
50     ~KoZoomAction() override;
51 
52     /**
53      * Reimplemented from QWidgetAction.
54      */
55     QWidget* createWidget(QWidget* parent) override;
56 
57     enum SpecialButton {
58         AspectMode = 1, ///< changing aspect mode
59         ZoomToSelection = 2, ///< zooms to current selection
60         ZoomToAll = 4 ///< zooms to the whole content of the document
61     };
62     Q_DECLARE_FLAGS(SpecialButtons, SpecialButton)
63 
64     /**
65      * Enables specified special buttons.
66      * This should be called immediately after calling the constructor.
67      * @param buttons mask of the special button flags to enable
68      */
69     void setSpecialButtons( SpecialButtons buttons );
70 
71     qreal effectiveZoom() const;
72 
73 public Q_SLOTS:
74 
75   /**
76    * Sets the zoom. If zoom not yet on the list of zoom values, it will be inserted
77    * into the list at proper place so that the values remain sorted.
78    * emits zoomChanged
79    */
80     void setZoom( qreal zoom );
81 
82   /**
83    * Change the zoom modes that should be shown
84    */
85     void setZoomModes( KoZoomMode::Modes zoomModes );
86 
87   /**
88    * Change the zoom to a closer look than current
89    * Zoom mode will be CONSTANT afterwards
90    * emits zoomChanged
91    */
92     void zoomIn( );
93 
94   /**
95    * Change the zoom to a wider look than current
96    * Zoom mode will be CONSTANT afterwards
97    * emits zoomChanged
98    */
99     void zoomOut( );
100 
101   /**
102    * Set the actual zoom value used in the app. This is needed when using @ref zoomIn() , @ref zoomOut() and/or when
103    * plugged into the viewbar.
104    */
105     void setEffectiveZoom(qreal zoom);
106 
107   /**
108    * Change the selected zoom mode.
109    */
110     void setSelectedZoomMode( KoZoomMode::Mode mode );
111 
112   /**
113    * Change status of "Use same aspect as pixels" button
114    * (emits aspectModeChanged(bool) after the change, ALWAYS)
115    */
116     void setAspectMode(bool status);
117 
118     /**
119      * Returns next preferred zoom level that should be used for
120      * zoom in operations.
121      *
122      * This can be used by the caller, when it needs some special
123      * mode of zooming (e.g. relative to point) and needs
124      * KoCanvasControllerWidget to accomplish this.
125      */
126     qreal nextZoomLevel() const;
127 
128     /**
129      * Returns previous preferred zoom level that should be used for
130      * zoom out operations.
131      *
132      * This can be used by the caller, when it needs some special
133      * mode of zooming (e.g. relative to point) and needs
134      * KoCanvasControllerWidget to accomplish this.
135      */
136     qreal prevZoomLevel() const;
137 
138 protected Q_SLOTS:
139 
140     void triggered( const QString& text );
141     void sliderValueChanged(int value);
142 
143 Q_SIGNALS:
144 
145   /**
146    * Signal zoomChanged is triggered when user changes the zoom value, either by
147    * choosing it from the list or by entering new value.
148    * @param mode The selected zoom mode
149    * @param zoom the zoom, only defined if @p mode is KoZoomMode::ZOOM_CONSTANT
150    */
151     void zoomChanged( KoZoomMode::Mode mode, qreal zoom );
152 
153   /**
154    * Signal aspectModeChanged is triggered when the user toggles the widget.
155    * Nothing else happens except that this signal is emitted.
156    * @param status Whether the special aspect mode is on
157    */
158     void aspectModeChanged( bool status );
159 
160     /**
161      * Signal is triggered when the user clicks the zoom to selection button.
162      * Nothing else happens except that this signal is emitted.
163      */
164     void zoomedToSelection();
165 
166     /**
167      * Signal is triggered when the user clicks the zoom to all button.
168      * Nothing else happens except that this signal is emitted.
169      */
170     void zoomedToAll();
171 
172     void zoomLevelsChanged(const QStringList &values);
173     void currentZoomLevelChanged(const QString &valueString);
174     void sliderChanged(int value);
175 
176 public:
177     /**
178      * Return the minimum zoom possible for documents.
179      *
180      * \return The minimum zoom possible.
181      */
182     qreal minimumZoom();
183     /**
184      * Return the maximum zoom possible for documents.
185      *
186      * \return The maximum zoom possible.
187      */
188     qreal maximumZoom();
189     /**
190      * Clamp the zoom value so that mimimumZoom <= zoom <= maximumZoom.
191      *
192      * \param zoom The value to clamp.
193      *
194      * \return minimumZoom if zoom < minimumZoom, maximumZoom if zoom >
195      * maximumZoom, zoom if otherwise.
196      */
197     qreal clampZoom(qreal zoom);
198 
199     /**
200      * Set the minimum zoom possible for documents.
201      *
202      * Note that after calling this, any existing KoZoomAction instances
203      * should be recreated.
204      *
205      * \param zoom The minimum zoom to use.
206      */
207     void setMinimumZoom(qreal zoom);
208     /**
209      * Set the maximum zoom possible for documents.
210      *
211      * Note that after calling this, any existing KoZoomAction instances
212      * should be recreated.
213      *
214      * \param zoom The maximum zoom to use.
215      */
216     void setMaximumZoom(qreal zoom);
217 
218 protected:
219     /// Regenerates the action's items
220     void regenerateItems( const qreal zoom, bool asCurrent = false );
221 
222 private:
223     void syncSliderWithZoom();
224 
225     Q_DISABLE_COPY( KoZoomAction )
226 
227     class Private;
228     Private * const d;
229 };
230 
231 Q_DECLARE_OPERATORS_FOR_FLAGS(KoZoomAction::SpecialButtons)
232 
233 #endif
234