summaryrefslogtreecommitdiffstats
path: root/kview/kimageviewer/canvas.h
blob: cbc4b0296b53067b662702c1388582dd3a8dcc95 (plain)
1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
62
63
64
65
66
67
68
69
70
71
72
73
74
75
76
77
78
79
80
81
82
83
84
85
86
87
88
89
90
91
92
93
94
95
96
97
98
99
100
101
102
103
104
105
106
107
108
109
110
111
112
113
114
115
116
117
118
119
120
121
122
123
124
125
126
127
128
129
130
131
132
133
134
135
136
137
138
139
140
141
142
143
144
145
146
147
148
149
150
151
152
153
154
155
156
157
158
159
160
161
162
163
164
165
166
167
168
169
170
171
172
173
174
175
176
177
178
179
180
181
182
183
184
185
186
187
188
189
190
191
192
193
194
195
196
197
198
199
200
201
202
203
204
205
206
207
208
209
210
211
212
213
214
215
216
217
218
219
220
221
222
223
224
225
226
227
228
229
230
231
232
233
234
235
236
237
238
239
240
241
242
243
244
245
246
247
248
249
250
251
252
253
254
255
256
257
258
259
260
261
262
263
264
265
266
267
268
269
270
271
272
273
274
275
276
277
278
279
280
281
282
283
284
285
286
287
288
289
290
291
292
293
294
295
296
297
298
299
300
301
302
303
304
305
306
307
308
309
310
311
312
313
314
315
316
317
318
319
320
321
322
323
324
325
326
327
328
329
330
331
332
333
334
335
336
337
338
339
340
341
342
343
344
345
346
347
348
/*  This file is part of the KDE project
    Copyright (C) 2001-2002 Matthias Kretz <kretz@kde.org>

    This library is free software; you can redistribute it and/or
    modify it under the terms of the GNU Library General Public
    License version 2 as published by the Free Software Foundation.

    This library is distributed in the hope that it will be useful,
    but WITHOUT ANY WARRANTY; without even the implied warranty of
    MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE.  See the GNU
    Library General Public License for more details.

    You should have received a copy of the GNU Library General Public License
    along with this library; see the file COPYING.LIB.  If not, write to
    the Free Software Foundation, Inc., 51 Franklin Street, Fifth Floor,
    Boston, MA 02110-1301, USA.

*/
// $Id$

#ifndef KIMAGEVIEWER_CANVAS_H
#define KIMAGEVIEWER_CANVAS_H

class TQColor;
class TQSize;
class TQImage;
class TQRect;
class TQPoint;
class TQWidget;

#include <tqstring.h>
#include <tqobjdefs.h>
#include <kdemacros.h>
namespace KImageViewer
{

/**
 * An image canvas widget
 *
 * @author Matthias Kretz <kretz@kde.org>
 *
 * You'll find an implementation in tdegraphics (KView). You may
 * still use this interface in your program but it will only work
 * if you have an implementation installed.
 *
 * This is what you have to do to get an image canvas embedded in
 * your program:
 *
 * <pre>
   TQWidget * widget = KParts::ComponentFactory::createInstanceFromQuery<TQWidget>( "KImageViewer/Canvas", TQString(), this );
   m_canvas = static_cast<KImageViewer::Canvas *>( widget->qt_cast( "KImageViewer::Canvas" ) );
   if( ! ( widget && m_canvas ) )
   {
     KMessageBox::error( this, "Could not find the Canvas!" );
     kapp->quit();
   }
   setCentralWidget( widget );
   connect( widget, TQT_SIGNAL( contextPress( const TQPoint & ) ), TQT_SLOT( mySlot( const TQPoint & ) ) );
   connect( m_canvas->widget(), TQT_SIGNAL( contextPress( const TQPoint & ) ), TQT_SLOT( mySlot( const TQPoint & ) ) );
   </pre>
 *
 * You can't connect signals or slots using KImageViewer::Canvas, because this interface
 * doesn't inherit from TQObject. But you can cast to TQWidget and use that instead (or just
 * keep the original pointer to TQWidget around, like shown in the example).
 *
 * This interface is not guaranteed to be kept binary or source compatible
 * until it's finished. So if you're using this interface please get in contact
 * with me.
 */
class KDE_EXPORT Canvas
{
	public:
		/**
		 * set the background color of the canvas
		 */
		virtual void setBgColor( const TQColor & ) = 0;

		/**
		 * returns the current background color
		 */
		virtual const TQColor & bgColor() const = 0;

		/**
		 * the depth of the contained image
		 */
		virtual int imageDepth() const = 0;

		/**
		 * the size of the unzoomed image
		 */
		virtual TQSize imageSize() const = 0;

		/**
		 * the size of the zoomed (current) image
		 */
		virtual TQSize currentSize() const = 0;

		/**
		 * returns the zoom factor
		 */
		virtual double zoom() const = 0;

		/**
		 * @return The current (unzoomed) image
		 * Take care that the canas may delete the image so you probably need to
		 * make a copy of the image if you want to keep it around.
		 */
		virtual const TQImage * image() const = 0;

		/**
		 * Scrolls the content so that the point (x, y) is in the top-left corner.
		 */
		virtual void setXYOffset( int x, int y ) = 0;

		/**
		 * Returns the leftmost visible X coordinate of the image.
		 */
		virtual int xOffset() const = 0;

		/**
		 * Returns the topmost visible Y coordinate of the image.
		 */
		virtual int yOffset() const = 0;

		/**
		 * Returns whether to use fast or smooth scaling
		 */
		virtual bool fastScale() const = 0;

		/**
		 * Return whether the image should always be centered.
		 */
		virtual bool centered() const = 0;

		/**
		 * Return the selected rectangle. If nothing is selected the rectangle is
		 * empty but doesn't have to be null.
		 */
		virtual TQRect selection() const = 0;

		/**
		 * Returns whether the aspect ratio of the image is kept
		 */
		virtual bool keepAspectRatio() const = 0;

		/**
		 * @return the number of available blend effects
		 */
		virtual unsigned int numOfBlendEffects() const { return 0; }

		/**
		 * @return the description of the blend effect
		 */
		virtual TQString blendEffectDescription( unsigned int ) const { return TQString(); }

		/**
		 * Sets the blending effect used to create a transition between images
		 */
		virtual void setBlendEffect( unsigned int idx ) { m_iBlendEffect = idx; }

		/**
		 * @return the current blend effect index
		 */
		virtual unsigned int blendEffect() const { return m_iBlendEffect; }

		/**
		 * @return the current maximum image size
		 */
		virtual const TQSize & maximumImageSize() const = 0;

		/**
		 * @return the current minimum image size
		 */
		virtual const TQSize & minimumImageSize() const = 0;

		/**
		 * @return a pointer to the TQWidget interface of this object
		 */
		virtual TQWidget * widget() = 0;

	signals:
		/**
		 * a mouse button was pressed and a context menu should be openend
		 */
		virtual void contextPress( const TQPoint & ) = 0;

		/**
		 * the size of the image has changed (a new image was loaded, or the
		 * image was zoomed or cropped)
		 *
		 * it passes the new size of the image
		 */
		virtual void imageSizeChanged( const TQSize & ) = 0;

		/**
		 * The zoom of the image has changed.
		 */
		virtual void zoomChanged( double zoom ) = 0;

		/**
		 * The selection has changed. Connect to this signal if you want to
		 * do something with a selection of the image (e.g. crop).
		 */
		virtual void selectionChanged( const TQRect & ) = 0;

		/**
		 * Emitted when an image is finished being shown. If a blend effect is being used
		 * the signal is emitted when the effect is finished.
		 */
		virtual void showingImageDone() = 0;

		/**
		 * This signal is emitted whenever the canvas changes between image/no-image. For
		 * example, if someone calls @ref clear() hasImage( false ) is emitted if an image
		 * was shown before.
		 */
		virtual void hasImage( bool ) = 0;

		/**
		 * Some methods of the canvas not only change the way the image is shown (e.g. zoom)
		 * but also change the image itself (e.g. rotation) - @ref image() returns something
		 * different. If such a change happens this signal is emitted.
		 * It is not emitted when a new image is set with the @ref setImage() methods.
		 */
		virtual void imageChanged() = 0;

		/**
		 * The current mouse cursor position on the image.
		 */
		virtual void cursorPos( const TQPoint & ) = 0;

	public slots:
		/**
		 * Set if the image should always be centered if the canvas is
		 * bigger than the image.
		 */
		virtual void setCentered( bool ) = 0;

		/**
		 * Give the canvas a new image to show. The zoom level is kept.
		 */
		virtual void setImage( const TQImage & ) = 0;

		/**
		 * Give the canvas a new image to show.
		 *
		 * You have to pass the size the image should have when it appears
		 * on screen.
		 */
		virtual void setImage( const TQImage &, const TQSize & ) = 0;

		/**
		 * Set the zoom to be used when showing the image.
		 */
		virtual void setZoom( double ) = 0;

		/**
		 * Fit the image into the requested width and height.
		 */
		virtual void boundImageTo( const TQSize & size ) = 0;

		/**
		 * Set the maximum size of the image. If this is set the image will
		 * never exceed this size.
		 *
		 * If you set this to 0x0 the image size may be as big as possible
		 */
		virtual void setMaximumImageSize( const TQSize & ) = 0;

		/**
		 * Set the minimum size of the image. If this is set the image will
		 * never be smaller than this size.
		 *
		 * If you set this to 0x0 the image size can be as small as possible
		 */
		virtual void setMinimumImageSize( const TQSize & ) = 0;

		/**
		 * Resize the image to the given size. It will keep the aspect ratio
		 * as long as keepAspectRatio is true (default). The image will be as
		 * large as possible within the given constraints.
		 */
		virtual void resizeImage( const TQSize & ) = 0;

		/**
		 * Hides the scrollbars of the canvas. It's still possible to scroll
		 * by moving the image with the mouse.
		 */
		virtual void hideScrollbars( bool ) = 0;

		/**
		 * Changes the zoom behaviour: Normally the aspect ratio of the image
		 * won't change, but if you want to allow it you may do.
		 */
		virtual void setKeepAspectRatio( bool ) = 0;

		/**
		 * If the canvas supports different methods for scaling you may
		 * switch between fast and smooth scaling.
		 *
		 * It defaults to smooth scaling.
		 */
		virtual void setFastScale( bool ) = 0;

		/**
		 * clears the canvas (no image loaded)
		 */
		virtual void clear() = 0;

		/**
		 * flip the image horizontally
		 *
		 * @param change  If set to true the internal image will be changed, else
		 *                only the shown image changes and @ref image() still returns
		 *                the same as before this call.
		 */
		virtual void flipHorizontal( bool change = false ) = 0;

		/**
		 * flip the image vertically
		 *
		 * @param change  If set to true the internal image will be changed, else
		 *                only the shown image changes and @ref image() still returns
		 *                the same as before this call.
		 */
		virtual void flipVertical( bool change = false ) = 0;

		/**
		 * rotate the image a degrees counterclockwise
		 *
		 * @param angle   The angle in degrees that the image should be rotated.
		 * @param change  If set to true the internal image will be changed, else
		 *                only the shown image changes and @ref image() still returns
		 *                the same as before this call.
		 */
		virtual void rotate( double angle, bool change = false ) = 0;
		
	protected:
		Canvas();
		virtual ~Canvas();
		unsigned int m_iBlendEffect;

}; //class Canvas
} //namespace KImageViewer

// vim:sw=4:ts=4

#endif // KIMAGEVIEWER_CANVAS_H