]> git.saurik.com Git - wxWidgets.git/blame - docs/latex/wx/image.tex
fixed wxPageSetupDialogData::SetPaperId() to take value, not reference
[wxWidgets.git] / docs / latex / wx / image.tex
CommitLineData
1e6d9499
JS
1\section{\class{wxImage}}\label{wximage}
2
3This class encapsulates a platform-independent image. An image can be created
b06a6b20 4from data, or using \helpref{wxBitmap::ConvertToImage}{wxbitmapconverttoimage}. An image
1e6d9499
JS
5can be loaded from a file in a variety of formats, and is extensible to new formats
6via image format handlers. Functions are available to set and get image bits, so
7it can be used for basic image manipulation.
8
7468b994
RR
9A wxImage cannot (currently) be drawn directly to a \helpref{wxDC}{wxdc}. Instead,
10a platform-specific \helpref{wxBitmap}{wxbitmap} object must be created from it using
b06a6b20
VS
11the \helpref{wxBitmap::wxBitmap(wxImage,int depth)}{wxbitmapconstr} constructor.
12This bitmap can then
7468b994
RR
13be drawn in a device context, using \helpref{wxDC::DrawBitmap}{wxdcdrawbitmap}.
14
15One colour value of the image may be used as a mask colour which will lead to the automatic
16creation of a \helpref{wxMask}{wxmask} object associated to the bitmap object.
12a44087 17
8727a1fe
GRG
18\wxheading{Available image handlers}
19
20The following image handlers are available. {\bf wxBMPHandler} is always
21installed by default. To use other image formats, install the appropiate
fa482912 22handler with \helpref{wxImage::AddHandler}{wximageaddhandler} or
8727a1fe
GRG
23\helpref{wxInitAllImageHandlers}{wxinitallimagehandlers}.
24
25\twocolwidtha{5cm}%
26\begin{twocollist}
606a3178
GT
27\twocolitem{\indexit{wxBMPHandler}}{Only for loading, always installed.}
28\twocolitem{\indexit{wxPNGHandler}}{For loading and saving.}
29\twocolitem{\indexit{wxJPEGHandler}}{For loading and saving.}
30\twocolitem{\indexit{wxGIFHandler}}{Only for loading, due to legal issues.}
31\twocolitem{\indexit{wxPCXHandler}}{For loading and saving (see below).}
32\twocolitem{\indexit{wxPNMHandler}}{For loading and saving (see below).}
b86e511a
VS
33\twocolitem{\indexit{wxTIFFHandler}}{For loading and saving.}
34\twocolitem{\indexit{wxXPMHandler}}{For loading and saving.}
37b83ca6 35\twocolitem{\indexit{wxICOHandler}}{For loading and saving.}
a61d25e6 36\twocolitem{\indexit{wxCURHandler}}{For loading and saving.}
658974ae 37\twocolitem{\indexit{wxANIHandler}}{For loading and saving.}
8727a1fe
GRG
38\end{twocollist}
39
40When saving in PCX format, {\bf wxPCXHandler} will count the number of
41different colours in the image; if there are 256 or less colours, it will
42save as 8 bit, else it will save as 24 bit.
43
44Loading PNMs only works for ASCII or raw RGB images. When saving in
45PNM format, {\bf wxPNMHandler} will always save as raw RGB.
46
1e6d9499
JS
47\wxheading{Derived from}
48
49\helpref{wxObject}{wxobject}
50
954b8ae6
JS
51\wxheading{Include files}
52
53<wx/image.h>
54
1e6d9499
JS
55\wxheading{See also}
56
f6081a04 57\helpref{wxBitmap}{wxbitmap},
b5a4a47d 58\helpref{wxInitAllImageHandlers}{wxinitallimagehandlers}
1e6d9499
JS
59
60\latexignore{\rtfignore{\wxheading{Members}}}
61
62\membersection{wxImage::wxImage}\label{wximageconstr}
63
64\func{}{wxImage}{\void}
65
66Default constructor.
67
68\func{}{wxImage}{\param{const wxImage\& }{image}}
69
70Copy constructor.
71
72\func{}{wxImage}{\param{const wxBitmap\&}{ bitmap}}
73
b06a6b20
VS
74(Deprecated form, use \helpref{wxBitmap::ConvertToImage}{wxbitmapconverttoimage}
75instead.) Constructs an image from a platform-dependent bitmap. This preserves
12a44087
RR
76mask information so that bitmaps and images can be converted back
77and forth without loss in that respect.
1e6d9499
JS
78
79\func{}{wxImage}{\param{int}{ width}, \param{int}{ height}}
80
81Creates an image with the given width and height.
82
e7240349 83\func{}{wxImage}{\param{int}{ width}, \param{int}{ height}, \param{unsigned char*}{ data}, \param{bool}{ static\_data=FALSE}}
f6bcfd97
BP
84
85Creates an image from given data with the given width and height. If
e7240349 86{\it static\_data} is TRUE, then wxImage will not delete the actual
f6bcfd97
BP
87image data in its destructor, otherwise it will free it by calling
88{\it free()}.
89
a61d25e6 90\func{}{wxImage}{\param{const wxString\& }{name}, \param{long}{ type = wxBITMAP\_TYPE\_ANY}, \param{int}{ index = -1}}
1e6d9499 91
a61d25e6 92\func{}{wxImage}{\param{const wxString\& }{name}, \param{const wxString\&}{ mimetype}, \param{int}{ index = -1}}
9e9ee68e 93
1e6d9499
JS
94Loads an image from a file.
95
a61d25e6 96\func{}{wxImage}{\param{wxInputStream\& }{stream}, \param{long}{ type = wxBITMAP\_TYPE\_ANY}, \param{int}{ index = -1}}
45b5751f 97
a61d25e6 98\func{}{wxImage}{\param{wxInputStream\& }{stream}, \param{const wxString\&}{ mimetype}, \param{int}{ index = -1}}
9e9ee68e 99
45b5751f
JS
100Loads an image from an input stream.
101
1e6d9499
JS
102\wxheading{Parameters}
103
104\docparam{width}{Specifies the width of the image.}
105
106\docparam{height}{Specifies the height of the image.}
107
31fd9b6b 108\docparam{name}{Name of the file from which to load the image.}
1e6d9499 109
31fd9b6b 110\docparam{stream}{Opened input stream from which to load the image. Currently, the stream must support seeking.}
45b5751f 111
1e6d9499
JS
112\docparam{type}{May be one of the following:
113
6be663cf 114\twocolwidtha{5cm}%
1e6d9499 115\begin{twocollist}
606a3178
GT
116\twocolitem{\indexit{wxBITMAP\_TYPE\_BMP}}{Load a Windows bitmap file.}
117\twocolitem{\indexit{wxBITMAP\_TYPE\_GIF}}{Load a GIF bitmap file.}
118\twocolitem{\indexit{wxBITMAP\_TYPE\_JPEG}}{Load a JPEG bitmap file.}
119\twocolitem{\indexit{wxBITMAP\_TYPE\_PNG}}{Load a PNG bitmap file.}
120\twocolitem{\indexit{wxBITMAP\_TYPE\_PCX}}{Load a PCX bitmap file.}
121\twocolitem{\indexit{wxBITMAP\_TYPE\_PNM}}{Load a PNM bitmap file.}
122\twocolitem{\indexit{wxBITMAP\_TYPE\_TIF}}{Load a TIFF bitmap file.}
b86e511a 123\twocolitem{\indexit{wxBITMAP\_TYPE\_XPM}}{Load a XPM bitmap file.}
a61d25e6
VS
124\twocolitem{\indexit{wxBITMAP\_TYPE\_ICO}}{Load a Windows icon file (ICO).}
125\twocolitem{\indexit{wxBITMAP\_TYPE\_CUR}}{Load a Windows cursor file (CUR).}
658974ae 126\twocolitem{\indexit{wxBITMAP\_TYPE\_ANI}}{Load a Windows animated cursor file (ANI).}
606a3178 127\twocolitem{\indexit{wxBITMAP\_TYPE\_ANY}}{Will try to autodetect the format.}
31fd9b6b 128\end{twocollist}}
1e6d9499 129
9e9ee68e
VS
130\docparam{mimetype}{MIME type string (for example 'image/jpeg')}
131
a61d25e6
VS
132\docparam{index}{Index of the image to load in the case that the image file contains multiple images.
133This is only used by ICO and TIFF handlers. The default value (-1) means
134"choose the default image" and is interpreted as the first image (index=0) by
135the TIFF handler and as the largest and most colourful one by the ICO handler.}
136
31fd9b6b
GRG
137\wxheading{Remarks}
138
139Depending on how wxWindows has been configured, not all formats may be available.
140
fa482912
JS
141Note: any handler other than BMP must be previously
142initialized with \helpref{wxImage::AddHandler}{wximageaddhandler} or
31fd9b6b 143\helpref{wxInitAllImageHandlers}{wxinitallimagehandlers}.
0a9f2522 144
a61d25e6
VS
145Note: you can use \helpref{GetOptionInt}{wximagegetoptionint} to get the
146hotspot for loaded cursor file:
147\begin{verbatim}
148 int hotspot_x = image.GetOptionInt(wxCUR_HOTSPOT_X);
149 int hotspot_y = image.GetOptionInt(wxCUR_HOTSPOT_Y);
150
151\end{verbatim}
152
1e6d9499
JS
153\wxheading{See also}
154
155\helpref{wxImage::LoadFile}{wximageloadfile}
156
f899db6d
RD
157\pythonnote{Constructors supported by wxPython are:\par
158\indented{2cm}{\begin{twocollist}
c9110876
VS
159\twocolitem{{\bf wxImage(name, flag)}}{Loads an image from a file}
160\twocolitem{{\bf wxNullImage()}}{Create a null image (has no size or
f899db6d 161image data)}
c9110876 162\twocolitem{{\bf wxEmptyImage(width, height)}}{Creates an empty image
f899db6d 163of the given size}
c9110876 164\twocolitem{{\bf wxImageFromMime(name, mimetype}}{Creates an image from
f899db6d 165the given file of the given mimetype}
c9110876 166\twocolitem{{\bf wxImageFromBitmap(bitmap)}}{Creates an image from a
f899db6d
RD
167platform-dependent bitmap}
168\end{twocollist}}
169}
170
5873607e
VZ
171\perlnote{Constructors supported by wxPerl are:\par
172\begin{itemize}
173\item{Wx::Image->new( bitmap )}
174\item{Wx::Image->new( width, height )}
175\item{Wx::Image->new( name, type )}
176\item{Wx::Image->new( name, mimetype )}
177\end{itemize}
178}
179
1e6d9499
JS
180\membersection{wxImage::\destruct{wxImage}}
181
182\func{}{\destruct{wxImage}}{\void}
183
184Destructor.
185
186\membersection{wxImage::AddHandler}\label{wximageaddhandler}
187
188\func{static void}{AddHandler}{\param{wxImageHandler*}{ handler}}
189
190Adds a handler to the end of the static list of format handlers.
191
192\docparam{handler}{A new image format handler object. There is usually only one instance
193of a given handler class in an application session.}
194
195\wxheading{See also}
196
197\helpref{wxImageHandler}{wximagehandler}
198
e7240349 199\pythonnote{In wxPython this static method is named {\tt wxImage\_AddHandler}.}
1e6d9499
JS
200\membersection{wxImage::CleanUpHandlers}
201
202\func{static void}{CleanUpHandlers}{\void}
203
204Deletes all image handlers.
205
206This function is called by wxWindows on exit.
207
208\membersection{wxImage::ConvertToBitmap}\label{wximageconverttobitmap}
209
210\constfunc{wxBitmap}{ConvertToBitmap}{\void}
211
b06a6b20
VS
212Deprecated, use equivalent \helpref{wxBitmap constructor}{wxbitmapconstr}
213(which takes wxImage and depth as its arguments) instead.
7468b994 214
b06a6b20 215\membersection{wxImage::ConvertToMono}\label{wxbitmapconverttomono}
1e6d9499 216
b06a6b20
VS
217\constfunc{wxImage}{ConvertToMono}{\param{unsigned char}{ r}, \param{unsigned char}{ g}, \param{unsigned char}{ b}}
218
219Returns monochromatic version of the image. The returned image has white
220colour where the original has {\it (r,g,b)} colour and black colour
221everywhere else.
3ca6a5f0 222
f6bcfd97
BP
223\membersection{wxImage::Copy}\label{wximagecopy}
224
225\constfunc{wxImage}{Copy}{\void}
226
227Returns an identical copy of the image.
228
1e6d9499
JS
229\membersection{wxImage::Create}\label{wximagecreate}
230
231\func{bool}{Create}{\param{int}{ width}, \param{int}{ height}}
232
233Creates a fresh image.
234
235\wxheading{Parameters}
236
237\docparam{width}{The width of the image in pixels.}
238
239\docparam{height}{The height of the image in pixels.}
240
241\wxheading{Return value}
242
243TRUE if the call succeeded, FALSE otherwise.
244
245\membersection{wxImage::Destroy}\label{wximagedestroy}
246
247\func{bool}{Destroy}{\void}
248
249Destroys the image data.
250
37b83ca6
VS
251\membersection{wxImage::FindFirstUnusedColour}\label{wximagefindfirstunusedcolour}
252
253\func{bool}{FindFirstUnusedColour}{\param{unsigned char *}{ r}, \param{unsigned char *}{ g}, \param{unsigned char *}{ b}, \param{unsigned char}{ startR = 1}, \param{unsigned char}{ startG = 0}, \param{unsigned char}{ startB = 0}}
254
255\wxheading{Parameters}
256
257\docparam{r,g,b}{Pointers to variables to save the colour.}
258
259\docparam{startR,startG,startB}{Initial values of the colour. Returned colour
260will have RGB values equal to or greater than these.}
261
262Finds the first colour that is never used in the image. The search begins at
263given initial colour and continues by increasing R, G and B components (in this
264order) by 1 until an unused colour is found or the colour space exhausted.
265
266\wxheading{Return value}
267
268Returns FALSE if there is no unused colour left, TRUE on success.
269
270\wxheading{Notes}
271
272Note that this method involves computing the histogram, which is
273computationally intensive operation.
274
1e6d9499
JS
275\membersection{wxImage::FindHandler}
276
277\func{static wxImageHandler*}{FindHandler}{\param{const wxString\& }{name}}
278
279Finds the handler with the given name.
280
281\func{static wxImageHandler*}{FindHandler}{\param{const wxString\& }{extension}, \param{long}{ imageType}}
282
283Finds the handler associated with the given extension and type.
284
285\func{static wxImageHandler*}{FindHandler}{\param{long }{imageType}}
286
287Finds the handler associated with the given image type.
288
9e9ee68e
VS
289\func{static wxImageHandler*}{FindHandlerMime}{\param{const wxString\& }{mimetype}}
290
291Finds the handler associated with the given MIME type.
292
1e6d9499
JS
293\docparam{name}{The handler name.}
294
295\docparam{extension}{The file extension, such as ``bmp".}
296
f6fcbb63 297\docparam{imageType}{The image type, such as wxBITMAP\_TYPE\_BMP.}
1e6d9499 298
9e9ee68e
VS
299\docparam{mimetype}{MIME type.}
300
1e6d9499
JS
301\wxheading{Return value}
302
303A pointer to the handler if found, NULL otherwise.
304
305\wxheading{See also}
306
307\helpref{wxImageHandler}{wximagehandler}
308
309\membersection{wxImage::GetBlue}\label{wximagegetblue}
310
311\constfunc{unsigned char}{GetBlue}{\param{int}{ x}, \param{int}{ y}}
312
313Returns the blue intensity at the given coordinate.
314
315\membersection{wxImage::GetData}\label{wximagegetdata}
316
317\constfunc{unsigned char*}{GetData}{\void}
318
12a44087
RR
319Returns the image data as an array. This is most often used when doing
320direct image manipulation. The return value points to an array of
321chararcters in RGBGBRGB... format.
1e6d9499
JS
322
323\membersection{wxImage::GetGreen}\label{wximagegetgreen}
324
325\constfunc{unsigned char}{GetGreen}{\param{int}{ x}, \param{int}{ y}}
326
327Returns the green intensity at the given coordinate.
328
649d13e8 329\membersection{wxImage::GetImageCount}\label{wximagegetimagecount}
a61d25e6 330
649d13e8 331\func{static int}{GetImageCount}{\param{const wxString\&}{ filename}, \param{long}{ type = wxBITMAP\_TYPE\_ANY}}
a61d25e6 332
649d13e8 333\func{static int}{GetImageCount}{\param{wxInputStream\&}{ stream}, \param{long}{ type = wxBITMAP\_TYPE\_ANY}}
a61d25e6
VS
334
335If the image file contains more than one image and the image handler is capable
336of retrieving these individually, this function will return the number of
337available images.
338
339\docparam{name}{Name of the file to query.}
340
341\docparam{stream}{Opened input stream with image data. Currently, the stream must support seeking.}
342
343\docparam{type}{May be one of the following:
344
345\twocolwidtha{5cm}%
346\begin{twocollist}
347\twocolitem{\indexit{wxBITMAP\_TYPE\_BMP}}{Load a Windows bitmap file.}
348\twocolitem{\indexit{wxBITMAP\_TYPE\_GIF}}{Load a GIF bitmap file.}
349\twocolitem{\indexit{wxBITMAP\_TYPE\_JPEG}}{Load a JPEG bitmap file.}
350\twocolitem{\indexit{wxBITMAP\_TYPE\_PNG}}{Load a PNG bitmap file.}
351\twocolitem{\indexit{wxBITMAP\_TYPE\_PCX}}{Load a PCX bitmap file.}
352\twocolitem{\indexit{wxBITMAP\_TYPE\_PNM}}{Load a PNM bitmap file.}
353\twocolitem{\indexit{wxBITMAP\_TYPE\_TIF}}{Load a TIFF bitmap file.}
354\twocolitem{\indexit{wxBITMAP\_TYPE\_XPM}}{Load a XPM bitmap file.}
355\twocolitem{\indexit{wxBITMAP\_TYPE\_ICO}}{Load a Windows icon file (ICO).}
356\twocolitem{\indexit{wxBITMAP\_TYPE\_CUR}}{Load a Windows cursor file (CUR).}
658974ae 357\twocolitem{\indexit{wxBITMAP\_TYPE\_ANI}}{Load a Windows animated cursor file (ANI).}
a61d25e6
VS
358\twocolitem{\indexit{wxBITMAP\_TYPE\_ANY}}{Will try to autodetect the format.}
359\end{twocollist}}
360
361\wxheading{Return value}
362
363Number of available images. For most image handlers, this is 1 (exceptions
364are TIFF and ICO formats).
365
1e6d9499
JS
366\membersection{wxImage::GetRed}\label{wximagegetred}
367
368\constfunc{unsigned char}{GetRed}{\param{int}{ x}, \param{int}{ y}}
369
370Returns the red intensity at the given coordinate.
371
372\membersection{wxImage::GetHandlers}
373
374\func{static wxList\&}{GetHandlers}{\void}
375
376Returns the static list of image format handlers.
377
378\wxheading{See also}
379
380\helpref{wxImageHandler}{wximagehandler}
381
382\membersection{wxImage::GetHeight}\label{wximagegetheight}
383
384\constfunc{int}{GetHeight}{\void}
385
386Gets the height of the image in pixels.
387
388\membersection{wxImage::GetMaskBlue}\label{wximagegetmaskblue}
389
390\constfunc{unsigned char}{GetMaskBlue}{\void}
391
392Gets the blue value of the mask colour.
393
394\membersection{wxImage::GetMaskGreen}\label{wximagegetmaskgreen}
395
396\constfunc{unsigned char}{GetMaskGreen}{\void}
397
398Gets the green value of the mask colour.
399
400\membersection{wxImage::GetMaskRed}\label{wximagegetmaskred}
401
402\constfunc{unsigned char}{GetMaskRed}{\void}
403
404Gets the red value of the mask colour.
405
3ca6a5f0
BP
406\membersection{wxImage::GetPalette}\label{wximagegetpalette}
407
408\constfunc{const wxPalette\&}{GetPalette}{\void}
409
410Returns the palette associated with the image. Currently the palette is only
b06a6b20 411used when converting to wxBitmap under Windows.
3ca6a5f0
BP
412
413Eventually wxImage handlers will set the palette if one exists in the image file.
414
fc9c7c09
RR
415\membersection{wxImage::GetSubImage}\label{wximagegetsubimage}
416
7468b994 417\constfunc{wxImage}{GetSubImage}{\param{const wxRect\&}{ rect}}
fc9c7c09
RR
418
419Returns a sub image of the current one as long as the rect belongs entirely to
420the image.
421
1e6d9499
JS
422\membersection{wxImage::GetWidth}\label{wximagegetwidth}
423
424\constfunc{int}{GetWidth}{\void}
425
426Gets the width of the image in pixels.
427
428\wxheading{See also}
429
430\helpref{wxImage::GetHeight}{wximagegetheight}
431
432\membersection{wxImage::HasMask}\label{wximagehasmask}
433
434\constfunc{bool}{HasMask}{\void}
435
436Returns TRUE if there is a mask active, FALSE otherwise.
437
5e5437e0
JS
438\membersection{wxImage::GetOption}\label{wximagegetoption}
439
440\constfunc{wxString}{GetOption}{\param{const wxString\&}{ name}}
441
442Gets a user-defined option. The function is case-insensitive to {\it name}.
443
444For example, when saving as a JPEG file, the option {\bf quality} is
445used, which is a number between 0 and 100 (0 is terrible, 100 is very good).
446
447\wxheading{See also}
448
449\helpref{wxImage::SetOption}{wximagesetoption},\rtfsp
450\helpref{wxImage::GetOptionInt}{wximagegetoptionint},\rtfsp
451\helpref{wxImage::HasOption}{wximagehasoption}
452
453\membersection{wxImage::GetOptionInt}\label{wximagegetoptionint}
454
455\constfunc{int}{GetOptionInt}{\param{const wxString\&}{ name}}
456
457Gets a user-defined option as an integer. The function is case-insensitive to {\it name}.
458
459\wxheading{See also}
460
461\helpref{wxImage::SetOption}{wximagesetoption},\rtfsp
462\helpref{wxImage::GetOption}{wximagegetoption},\rtfsp
463\helpref{wxImage::HasOption}{wximagehasoption}
464
465\membersection{wxImage::HasOption}\label{wximagehasoption}
466
467\constfunc{bool}{HasOption}{\param{const wxString\&}{ name}}
468
469Returns TRUE if the given option is present. The function is case-insensitive to {\it name}.
470
471\wxheading{See also}
472
473\helpref{wxImage::SetOption}{wximagesetoption},\rtfsp
474\helpref{wxImage::GetOption}{wximagegetoption},\rtfsp
475\helpref{wxImage::GetOptionInt}{wximagegetoptionint}
476
1e6d9499
JS
477\membersection{wxImage::InitStandardHandlers}
478
479\func{static void}{InitStandardHandlers}{\void}
480
a14e57f9 481Internal use only. Adds standard image format handlers. It only install BMP
31fd9b6b 482for the time being, which is used by wxBitmap.
1e6d9499 483
a14e57f9
SB
484This function is called by wxWindows on startup, and shouldn't be called by
485the user.
1e6d9499
JS
486
487\wxheading{See also}
488
fa482912 489\helpref{wxImageHandler}{wximagehandler},
b5a4a47d 490\helpref{wxInitAllImageHandlers}{wxinitallimagehandlers}
1e6d9499
JS
491
492\membersection{wxImage::InsertHandler}
493
494\func{static void}{InsertHandler}{\param{wxImageHandler*}{ handler}}
495
496Adds a handler at the start of the static list of format handlers.
497
498\docparam{handler}{A new image format handler object. There is usually only one instance
499of a given handler class in an application session.}
500
501\wxheading{See also}
502
503\helpref{wxImageHandler}{wximagehandler}
504
505\membersection{wxImage::LoadFile}\label{wximageloadfile}
506
a61d25e6 507\func{bool}{LoadFile}{\param{const wxString\&}{ name}, \param{long}{ type = wxBITMAP\_TYPE\_ANY}, \param{int}{ index = -1}}
1e6d9499 508
a61d25e6 509\func{bool}{LoadFile}{\param{const wxString\&}{ name}, \param{const wxString\&}{ mimetype}, \param{int}{ index = -1}}
9e9ee68e 510
a14e57f9 511Loads an image from a file. If no handler type is provided, the library will
31fd9b6b 512try to autodetect the format.
1e6d9499 513
a61d25e6 514\func{bool}{LoadFile}{\param{wxInputStream\&}{ stream}, \param{long}{ type}, \param{int}{ index = -1}}
45b5751f 515
a61d25e6 516\func{bool}{LoadFile}{\param{wxInputStream\&}{ stream}, \param{const wxString\&}{ mimetype}, \param{int}{ index = -1}}
9e9ee68e 517
45b5751f
JS
518Loads an image from an input stream.
519
1e6d9499
JS
520\wxheading{Parameters}
521
31fd9b6b 522\docparam{name}{Name of the file from which to load the image.}
1e6d9499 523
31fd9b6b 524\docparam{stream}{Opened input stream from which to load the image. Currently, the stream must support seeking.}
45b5751f 525
1e6d9499
JS
526\docparam{type}{One of the following values:
527
6be663cf 528\twocolwidtha{5cm}%
1e6d9499 529\begin{twocollist}
f6fcbb63 530\twocolitem{{\bf wxBITMAP\_TYPE\_BMP}}{Load a Windows image file.}
a14e57f9 531\twocolitem{{\bf wxBITMAP\_TYPE\_GIF}}{Load a GIF image file.}
48b4e302 532\twocolitem{{\bf wxBITMAP\_TYPE\_JPEG}}{Load a JPEG image file.}
a14e57f9
SB
533\twocolitem{{\bf wxBITMAP\_TYPE\_PCX}}{Load a PCX image file.}
534\twocolitem{{\bf wxBITMAP\_TYPE\_PNG}}{Load a PNG image file.}
535\twocolitem{{\bf wxBITMAP\_TYPE\_PNM}}{Load a PNM image file.}
31fd9b6b 536\twocolitem{{\bf wxBITMAP\_TYPE\_TIF}}{Load a TIFF image file.}
b86e511a 537\twocolitem{{\bf wxBITMAP\_TYPE\_XPM}}{Load a XPM image file.}
a61d25e6
VS
538\twocolitem{{\bf wxBITMAP\_TYPE\_ICO}}{Load a Windows icon file (ICO).}
539\twocolitem{{\bf wxBITMAP\_TYPE\_CUR}}{Load a Windows cursor file (CUR).}
658974ae 540\twocolitem{\indexit{wxBITMAP\_TYPE\_ANI}}{Load a Windows animated cursor file (ANI).}
31fd9b6b
GRG
541\twocolitem{{\bf wxBITMAP\_TYPE\_ANY}}{Will try to autodetect the format.}
542\end{twocollist}}
1e6d9499 543
9e9ee68e
VS
544\docparam{mimetype}{MIME type string (for example 'image/jpeg')}
545
a61d25e6
VS
546\docparam{index}{Index of the image to load in the case that the image file contains multiple images.
547This is only used by ICO and TIFF handlers. The default value (-1) means
548"choose the default image" and is interpreted as the first image (index=0) by
549the TIFF handler and as the largest and most colourful one by the ICO handler.}
550
31fd9b6b
GRG
551\wxheading{Remarks}
552
553Depending on how wxWindows has been configured, not all formats may be available.
554
a61d25e6
VS
555Note: you can use \helpref{GetOptionInt}{wximagegetoptionint} to get the
556hotspot for loaded cursor file:
557\begin{verbatim}
558 int hotspot_x = image.GetOptionInt(wxCUR_HOTSPOT_X);
559 int hotspot_y = image.GetOptionInt(wxCUR_HOTSPOT_Y);
560
561\end{verbatim}
37b83ca6 562
1e6d9499
JS
563\wxheading{Return value}
564
565TRUE if the operation succeeded, FALSE otherwise.
566
567\wxheading{See also}
568
569\helpref{wxImage::SaveFile}{wximagesavefile}
570
f899db6d
RD
571\pythonnote{In place of a single overloaded method name, wxPython
572implements the following methods:\par
573\indented{2cm}{\begin{twocollist}
c9110876 574\twocolitem{{\bf LoadFile(filename, type)}}{Loads an image of the given
f899db6d 575type from a file}
c9110876 576\twocolitem{{\bf LoadMimeFile(filename, mimetype)}}{Loads an image of the given
f899db6d
RD
577mimetype from a file}
578\end{twocollist}}
579}
580
5873607e
VZ
581\perlnote{Methods supported by wxPerl are:\par
582\begin{itemize}
606a3178
GT
583\item{bitmap->LoadFile( name, type )}
584\item{bitmap->LoadFile( name, mimetype )}
5873607e
VZ
585\end{itemize}
586}
587
f899db6d 588
1e6d9499
JS
589\membersection{wxImage::Ok}\label{wximageok}
590
591\constfunc{bool}{Ok}{\void}
592
593Returns TRUE if image data is present.
594
595\membersection{wxImage::RemoveHandler}
596
597\func{static bool}{RemoveHandler}{\param{const wxString\& }{name}}
598
599Finds the handler with the given name, and removes it. The handler
600is not deleted.
601
602\docparam{name}{The handler name.}
603
604\wxheading{Return value}
605
606TRUE if the handler was found and removed, FALSE otherwise.
607
608\wxheading{See also}
609
610\helpref{wxImageHandler}{wximagehandler}
611
612\membersection{wxImage::SaveFile}\label{wximagesavefile}
613
614\func{bool}{SaveFile}{\param{const wxString\& }{name}, \param{int}{ type}}
615
9e9ee68e
VS
616\func{bool}{SaveFile}{\param{const wxString\& }{name}, \param{const wxString\&}{ mimetype}}
617
1e6d9499
JS
618Saves a image in the named file.
619
45b5751f
JS
620\func{bool}{SaveFile}{\param{wxOutputStream\& }{stream}, \param{int}{ type}}
621
9e9ee68e
VS
622\func{bool}{SaveFile}{\param{wxOutputStream\& }{stream}, \param{const wxString\&}{ mimetype}}
623
45b5751f
JS
624Saves a image in the given stream.
625
1e6d9499
JS
626\wxheading{Parameters}
627
31fd9b6b 628\docparam{name}{Name of the file to save the image to.}
1e6d9499 629
31fd9b6b 630\docparam{stream}{Opened output stream to save the image to.}
45b5751f 631
7468b994 632\docparam{type}{Currently three types can be used:
1e6d9499 633
6be663cf 634\twocolwidtha{5cm}%
1e6d9499 635\begin{twocollist}
48b4e302 636\twocolitem{{\bf wxBITMAP\_TYPE\_JPEG}}{Save a JPEG image file.}
31fd9b6b
GRG
637\twocolitem{{\bf wxBITMAP\_TYPE\_PNG}}{Save a PNG image file.}
638\twocolitem{{\bf wxBITMAP\_TYPE\_PCX}}{Save a PCX image file (tries to save as 8-bit if possible, falls back to 24-bit otherwise).}
639\twocolitem{{\bf wxBITMAP\_TYPE\_PNM}}{Save a PNM image file (as raw RGB always).}
b86e511a
VS
640\twocolitem{{\bf wxBITMAP\_TYPE\_TIFF}}{Save a TIFF image file.}
641\twocolitem{{\bf wxBITMAP\_TYPE\_XPM}}{Save a XPM image file.}
a61d25e6
VS
642\twocolitem{{\bf wxBITMAP\_TYPE\_ICO}}{Save a ICO image file. }
643\twocolitem{{\bf wxBITMAP\_TYPE\_ICO}}{Save a Windows icon file (ICO) (the size may be up to 255 wide by 127 high. A single image is saved in 8 colors at the size supplied).}
644\twocolitem{{\bf wxBITMAP\_TYPE\_CUR}}{Save a Windows cursor file (CUR).}
31fd9b6b 645\end{twocollist}}
1e6d9499 646
9e9ee68e
VS
647\docparam{mimetype}{MIME type.}
648
1e6d9499
JS
649\wxheading{Return value}
650
651TRUE if the operation succeeded, FALSE otherwise.
652
653\wxheading{Remarks}
654
655Depending on how wxWindows has been configured, not all formats may be available.
656
a61d25e6
VS
657Note: you can use \helpref{GetOptionInt}{wximagegetoptionint} to set the
658hotspot before saving an image into a cursor file (default hotspot is in
659the centre of the image):
660\begin{verbatim}
661 image.SetOption(wxCUR_HOTSPOT_X, hotspotX);
662 image.SetOption(wxCUR_HOTSPOT_Y, hotspotY);
663
664\end{verbatim}
665
1e6d9499
JS
666\wxheading{See also}
667
668\helpref{wxImage::LoadFile}{wximageloadfile}
669
f899db6d
RD
670\pythonnote{In place of a single overloaded method name, wxPython
671implements the following methods:\par
672\indented{2cm}{\begin{twocollist}
c9110876 673\twocolitem{{\bf SaveFile(filename, type)}}{Saves the image using the given
f899db6d 674type to the named file}
c9110876 675\twocolitem{{\bf SaveMimeFile(filename, mimetype)}}{Saves the image using the given
f899db6d
RD
676mimetype to the named file}
677\end{twocollist}}
678}
679
5873607e
VZ
680\perlnote{Methods supported by wxPerl are:\par
681\begin{itemize}
606a3178
GT
682\item{bitmap->SaveFile( name, type )}
683\item{bitmap->SaveFile( name, mimetype )}
5873607e
VZ
684\end{itemize}
685}
686
f6bcfd97
BP
687\membersection{wxImage::Mirror}\label{wximagemirror}
688
689\constfunc{wxImage}{Mirror}{\param{bool}{ horizontally = TRUE}}
690
691Returns a mirrored copy of the image. The parameter {\it horizontally}
692indicates the orientation.
693
7468b994
RR
694\membersection{wxImage::Replace}\label{wximagereplace}
695
696\func{void}{Replace}{\param{unsigned char}{ r1}, \param{unsigned char}{ g1}, \param{unsigned char}{ b1},
697\param{unsigned char}{ r2}, \param{unsigned char}{ g2}, \param{unsigned char}{ b2}}
698
699Replaces the colour specified by {\it r1,g1,b1} by the colour {\it r2,g2,b2}.
700
ce9a75d2
VZ
701\membersection{wxImage::Rescale}\label{wximagerescale}
702
6e807169 703\func{wxImage \&}{Rescale}{\param{int}{ width}, \param{int}{ height}}
ce9a75d2 704
9c884972
RR
705Changes the size of the image in-place: after a call to this function, the
706image will have the given width and height.
ce9a75d2 707
6e807169
VZ
708Returns the (modified) image itself.
709
ce9a75d2
VZ
710\wxheading{See also}
711
712\helpref{Scale}{wximagescale}
713
ed8297b9 714\membersection{wxImage::Rotate}\label{wximagerotate}
7a632f10
JS
715
716\func{wxImage}{Rotate}{\param{double}{ angle}, \param{const wxPoint\& }{rotationCentre},
717 \param{bool}{ interpolating = TRUE}, \param{wxPoint*}{ offsetAfterRotation = NULL}}
718
719Rotates the image about the given point, by {\it angle} radians. Passing TRUE
b4e87ec3
GRG
720to {\it interpolating} results in better image quality, but is slower. If the
721image has a mask, then the mask colour is used for the uncovered pixels in the
722rotated image background. Else, black (rgb 0, 0, 0) will be used.
7a632f10
JS
723
724Returns the rotated image, leaving this image intact.
725
f6bcfd97
BP
726\membersection{wxImage::Rotate90}\label{wximagerotate90}
727
728\constfunc{wxImage}{Rotate90}{\param{bool}{ clockwise = TRUE}}
729
730Returns a copy of the image rotated 90 degrees in the direction
731indicated by {\it clockwise}.
732
1e6d9499
JS
733\membersection{wxImage::Scale}\label{wximagescale}
734
ce9a75d2 735\constfunc{wxImage}{Scale}{\param{int}{ width}, \param{int}{ height}}
1e6d9499 736
12a44087
RR
737Returns a scaled version of the image. This is also useful for
738scaling bitmaps in general as the only other way to scale bitmaps
ce9a75d2
VZ
739is to blit a wxMemoryDC into another wxMemoryDC.
740
7468b994 741It may be mentioned that the GTK port uses this function internally
f6bcfd97 742to scale bitmaps when using mapping modes in wxDC.
ce9a75d2
VZ
743
744Example:
745
746\begin{verbatim}
747 // get the bitmap from somewhere
748 wxBitmap bmp = ...;
749
750 // rescale it to have size of 32*32
751 if ( bmp.GetWidth() != 32 || bmp.GetHeight() != 32 )
752 {
753 wxImage image(bmp);
b06a6b20 754 bmp = wxBitmap(image.Scale(32, 32));
ce9a75d2
VZ
755
756 // another possibility:
757 image.Rescale(32, 32);
758 bmp = image;
759 }
760
761\end{verbatim}
762
763\wxheading{See also}
764
765\helpref{Rescale}{wximagerescale}
1e6d9499
JS
766
767\membersection{wxImage::SetData}\label{wximagesetdata}
768
769\func{void}{SetData}{\param{unsigned char*}{data}}
770
f899db6d 771Sets the image data without performing checks. The data given must have
12a44087
RR
772the size (width*height*3) or results will be unexpected. Don't use this
773method if you aren't sure you know what you are doing.
1e6d9499
JS
774
775\membersection{wxImage::SetMask}\label{wximagesetmask}
776
777\func{void}{SetMask}{\param{bool}{ hasMask = TRUE}}
778
779Specifies whether there is a mask or not. The area of the mask is determined by the current mask colour.
780
781\membersection{wxImage::SetMaskColour}\label{wximagesetmaskcolour}
782
783\func{void}{SetMaskColour}{\param{unsigned char }{red}, \param{unsigned char }{blue}, \param{unsigned char }{green}}
784
b1170810 785Sets the mask colour for this image (and tells the image to use the mask).
1e6d9499 786
37b83ca6
VS
787\membersection{wxImage::SetMaskFromImage}\label{wximagesetmaskfromimage}
788
789\func{bool}{SetMaskFromImage}{\param{const wxImage\&}{ mask}, \param{unsigned char}{ mr}, \param{unsigned char}{ mg}, \param{unsigned char}{ mb}}
790
791\wxheading{Parameters}
792
793\docparam{mask}{The mask image to extract mask shape from. Must have same dimensions as the image.}
794
795\docparam{mr,mg,mb}{RGB value of pixels in {\it mask} that will be used to create the mask.}
796
797Sets image's mask so that the pixels that have RGB value of {\it mr,mg,mb}
798in {\it mask} will be masked in the image. This is done by first finding an
799unused colour in the image, setting this colour as the mask colour and then
800using this colour to draw all pixels in the image who corresponding pixel
801in {\it mask} has given RGB value.
802
803\wxheading{Return value}
804
805Returns FALSE if {\it mask} does not have same dimensions as the image or if
806there is no unused colour left. Returns TRUE if the mask was successfully
807applied.
808
809\wxheading{Notes}
810
811Note that this method involves computing the histogram, which is
812computationally intensive operation.
813
5e5437e0
JS
814\membersection{wxImage::SetOption}\label{wximagesetoption}
815
816\func{void}{SetOption}{\param{const wxString\&}{ name}, \param{const wxString\&}{ value}}
817
818\func{void}{SetOption}{\param{const wxString\&}{ name}, \param{int}{ value}}
819
820Sets a user-defined option. The function is case-insensitive to {\it name}.
821
822For example, when saving as a JPEG file, the option {\bf quality} is
823used, which is a number between 0 and 100 (0 is terrible, 100 is very good).
824
825\wxheading{See also}
826
827\helpref{wxImage::GetOption}{wximagegetoption},\rtfsp
828\helpref{wxImage::GetOptionInt}{wximagegetoptionint},\rtfsp
829\helpref{wxImage::HasOption}{wximagehasoption}
830
3ca6a5f0
BP
831\membersection{wxImage::SetPalette}\label{wximagesetpalette}
832
833\func{void}{SetPalette}{\param{const wxPalette\&}{ palette}}
834
b06a6b20
VS
835Associates a palette with the image. The palette may be used when converting
836wxImage to wxBitmap (MSW only at present) or in file save operations (none as yet).
3ca6a5f0 837
1e6d9499
JS
838\membersection{wxImage::SetRGB}\label{wximagesetrgb}
839
f6bcfd97 840\func{void}{SetRGB}{\param{int }{x}, \param{int }{y}, \param{unsigned char }{red}, \param{unsigned char }{green}, \param{unsigned char }{blue}}
1e6d9499 841
12a44087
RR
842Sets the pixel at the given coordinate. This routine performs bounds-checks
843for the coordinate so it can be considered a safe way to manipulate the
844data, but in some cases this might be too slow so that the data will have to
7468b994
RR
845be set directly. In that case you will have to get access to the image data
846using the \helpref{GetData}{wximagegetdata} method.
1e6d9499
JS
847
848\membersection{wxImage::operator $=$}
849
850\func{wxImage\& }{operator $=$}{\param{const wxImage\& }{image}}
851
852Assignment operator. This operator does not copy any data, but instead
853passes a pointer to the data in {\it image} and increments a reference
854counter. It is a fast operation.
855
856\wxheading{Parameters}
857
858\docparam{image}{Image to assign.}
859
860\wxheading{Return value}
861
862Returns 'this' object.
863
864\membersection{wxImage::operator $==$}
865
866\func{bool}{operator $==$}{\param{const wxImage\& }{image}}
867
868Equality operator. This operator tests whether the internal data pointers are
869equal (a fast test).
870
871\wxheading{Parameters}
872
873\docparam{image}{Image to compare with 'this'}
874
875\wxheading{Return value}
876
877Returns TRUE if the images were effectively equal, FALSE otherwise.
878
879\membersection{wxImage::operator $!=$}
880
881\func{bool}{operator $!=$}{\param{const wxImage\& }{image}}
882
883Inequality operator. This operator tests whether the internal data pointers are
884unequal (a fast test).
885
886\wxheading{Parameters}
887
888\docparam{image}{Image to compare with 'this'}
889
890\wxheading{Return value}
891
892Returns TRUE if the images were unequal, FALSE otherwise.
893
894\section{\class{wxImageHandler}}\label{wximagehandler}
895
1e6d9499
JS
896This is the base class for implementing image file loading/saving, and image creation from data.
897It is used within wxImage and is not normally seen by the application.
898
899If you wish to extend the capabilities of wxImage, derive a class from wxImageHandler
900and add the handler using \helpref{wxImage::AddHandler}{wximageaddhandler} in your
901application initialisation.
902
48b4e302
VS
903\wxheading{Note (Legal Issue)}
904
954b8ae6 905This software is based in part on the work of the Independent JPEG Group.
48b4e302
VS
906
907(Applies when wxWindows is linked with JPEG support. wxJPEGHandler uses libjpeg
908created by IJG.)
909
1e6d9499
JS
910\wxheading{Derived from}
911
912\helpref{wxObject}{wxobject}
913
954b8ae6
JS
914\wxheading{Include files}
915
916<wx/image.h>
917
1e6d9499
JS
918\wxheading{See also}
919
fa482912 920\helpref{wxImage}{wximage},
b5a4a47d 921\helpref{wxInitAllImageHandlers}{wxinitallimagehandlers}
1e6d9499
JS
922
923\latexignore{\rtfignore{\wxheading{Members}}}
924
925\membersection{wxImageHandler::wxImageHandler}\label{wximagehandlerconstr}
926
927\func{}{wxImageHandler}{\void}
928
929Default constructor. In your own default constructor, initialise the members
930m\_name, m\_extension and m\_type.
931
932\membersection{wxImageHandler::\destruct{wxImageHandler}}
933
934\func{}{\destruct{wxImageHandler}}{\void}
935
936Destroys the wxImageHandler object.
937
938\membersection{wxImageHandler::GetName}
939
940\constfunc{wxString}{GetName}{\void}
941
942Gets the name of this handler.
943
944\membersection{wxImageHandler::GetExtension}
945
946\constfunc{wxString}{GetExtension}{\void}
947
948Gets the file extension associated with this handler.
949
649d13e8 950\membersection{wxImageHandler::GetImageCount}\label{wximagehandlergetimagecount}
7941ba11 951
649d13e8 952\func{int}{GetImageCount}{\param{wxInputStream\&}{ stream}}
7941ba11
RR
953
954If the image file contains more than one image and the image handler is capable
955of retrieving these individually, this function will return the number of
956available images.
957
31fd9b6b 958\docparam{stream}{Opened input stream for reading image data. Currently, the stream must support seeking.}
7941ba11
RR
959
960\wxheading{Return value}
961
a61d25e6
VS
962Number of available images. For most image handlers, this is 1 (exceptions
963are TIFF and ICO formats).
7941ba11 964
1e6d9499
JS
965\membersection{wxImageHandler::GetType}
966
967\constfunc{long}{GetType}{\void}
968
969Gets the image type associated with this handler.
970
9e9ee68e
VS
971\membersection{wxImageHandler::GetMimeType}
972
973\constfunc{wxString}{GetMimeType}{\void}
974
975Gets the MIME type associated with this handler.
976
1e6d9499
JS
977\membersection{wxImageHandler::LoadFile}\label{wximagehandlerloadfile}
978
7941ba11 979\func{bool}{LoadFile}{\param{wxImage* }{image}, \param{wxInputStream\&}{ stream}, \param{bool}{ verbose=TRUE}, \param{int}{ index=0}}
1e6d9499 980
7941ba11
RR
981Loads a image from a stream, putting the resulting data into {\it image}. If the image file contains
982more than one image and the image handler is capable of retrieving these individually, {\it index}
983indicates which image to read from the stream.
1e6d9499
JS
984
985\wxheading{Parameters}
986
987\docparam{image}{The image object which is to be affected by this operation.}
988
31fd9b6b 989\docparam{stream}{Opened input stream for reading image data.}
7941ba11
RR
990
991\docparam{verbose}{If set to TRUE, errors reported by the image handler will produce wxLogMessages.}
992
993\docparam{index}{The index of the image in the file (starting from zero).}
1e6d9499
JS
994
995\wxheading{Return value}
996
997TRUE if the operation succeeded, FALSE otherwise.
998
999\wxheading{See also}
1000
fa482912
JS
1001\helpref{wxImage::LoadFile}{wximageloadfile},
1002\helpref{wxImage::SaveFile}{wximagesavefile},
1e6d9499
JS
1003\helpref{wxImageHandler::SaveFile}{wximagehandlersavefile}
1004
1005\membersection{wxImageHandler::SaveFile}\label{wximagehandlersavefile}
1006
45b5751f 1007\func{bool}{SaveFile}{\param{wxImage* }{image}, \param{wxOutputStream\& }{stream}}
1e6d9499 1008
45b5751f 1009Saves a image in the output stream.
1e6d9499
JS
1010
1011\wxheading{Parameters}
1012
1013\docparam{image}{The image object which is to be affected by this operation.}
1014
31fd9b6b 1015\docparam{stream}{Opened output stream for writing the data.}
1e6d9499
JS
1016
1017\wxheading{Return value}
1018
1019TRUE if the operation succeeded, FALSE otherwise.
1020
1021\wxheading{See also}
1022
fa482912
JS
1023\helpref{wxImage::LoadFile}{wximageloadfile},
1024\helpref{wxImage::SaveFile}{wximagesavefile},
1e6d9499
JS
1025\helpref{wxImageHandler::LoadFile}{wximagehandlerloadfile}
1026
1027\membersection{wxImageHandler::SetName}
1028
1029\func{void}{SetName}{\param{const wxString\& }{name}}
1030
1031Sets the handler name.
1032
1033\wxheading{Parameters}
1034
1035\docparam{name}{Handler name.}
1036
1037\membersection{wxImageHandler::SetExtension}
1038
1039\func{void}{SetExtension}{\param{const wxString\& }{extension}}
1040
1041Sets the handler extension.
1042
1043\wxheading{Parameters}
1044
1045\docparam{extension}{Handler extension.}
1046
f6bcfd97 1047\membersection{wxImageHandler::SetMimeType}\label{wximagehandlersetmimetype}
1e6d9499 1048
f6bcfd97 1049\func{void}{SetMimeType}{\param{const wxString\& }{mimetype}}
1e6d9499 1050
f6bcfd97 1051Sets the handler MIME type.
1e6d9499
JS
1052
1053\wxheading{Parameters}
1054
f6bcfd97 1055\docparam{mimename}{Handler MIME type.}
9e9ee68e 1056
f6bcfd97 1057\membersection{wxImageHandler::SetType}
9e9ee68e 1058
f6bcfd97 1059\func{void}{SetType}{\param{long }{type}}
9e9ee68e 1060
f6bcfd97 1061Sets the handler type.
9e9ee68e
VS
1062
1063\wxheading{Parameters}
1064
f6bcfd97 1065\docparam{name}{Handler type.}
9e9ee68e 1066