]> git.saurik.com Git - wxWidgets.git/blame - docs/latex/wx/image.tex
Small changes
[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
4from data, or using the constructor taking a wxBitmap object. An image
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
11the \helpref{ConvertToBitmap}{wximageconverttobitmap} function. This bitmap can then
12be drawn in a device context, using \helpref{wxDC::DrawBitmap}{wxdcdrawbitmap}.
13
14One colour value of the image may be used as a mask colour which will lead to the automatic
15creation of a \helpref{wxMask}{wxmask} object associated to the bitmap object.
12a44087 16
8727a1fe
GRG
17\wxheading{Available image handlers}
18
19The following image handlers are available. {\bf wxBMPHandler} is always
20installed by default. To use other image formats, install the appropiate
21handler with \helpref{wxImage::AddHandler}{wximageaddhandler} or
22\helpref{wxInitAllImageHandlers}{wxinitallimagehandlers}.
23
24\twocolwidtha{5cm}%
25\begin{twocollist}
26\twocolitem{{\bf \indexit{wxBMPHandler}}}{Only for loading, always installed.}
27\twocolitem{{\bf \indexit{wxPNGHandler}}}{For loading and saving.}
28\twocolitem{{\bf \indexit{wxJPEGHandler}}}{For loading and saving.}
29\twocolitem{{\bf \indexit{wxGIFHandler}}}{Only for loading, due to legal issues.}
30\twocolitem{{\bf \indexit{wxPCXHandler}}}{For loading and saving (see below).}
31\twocolitem{{\bf \indexit{wxPNMHandler}}}{For loading and saving (see below).}
32\end{twocollist}
33
34When saving in PCX format, {\bf wxPCXHandler} will count the number of
35different colours in the image; if there are 256 or less colours, it will
36save as 8 bit, else it will save as 24 bit.
37
38Loading PNMs only works for ASCII or raw RGB images. When saving in
39PNM format, {\bf wxPNMHandler} will always save as raw RGB.
40
1e6d9499
JS
41\wxheading{Derived from}
42
43\helpref{wxObject}{wxobject}
44
954b8ae6
JS
45\wxheading{Include files}
46
47<wx/image.h>
48
1e6d9499
JS
49\wxheading{See also}
50
51\helpref{wxBitmap}{wxbitmap}
b5a4a47d 52\helpref{wxInitAllImageHandlers}{wxinitallimagehandlers}
1e6d9499
JS
53
54\latexignore{\rtfignore{\wxheading{Members}}}
55
56\membersection{wxImage::wxImage}\label{wximageconstr}
57
58\func{}{wxImage}{\void}
59
60Default constructor.
61
62\func{}{wxImage}{\param{const wxImage\& }{image}}
63
64Copy constructor.
65
66\func{}{wxImage}{\param{const wxBitmap\&}{ bitmap}}
67
12a44087
RR
68Constructs an image from a platform-dependent bitmap. This preserves
69mask information so that bitmaps and images can be converted back
70and forth without loss in that respect.
1e6d9499
JS
71
72\func{}{wxImage}{\param{int}{ width}, \param{int}{ height}}
73
74Creates an image with the given width and height.
75
087c0d5e 76\func{}{wxImage}{\param{const wxString\& }{name}, \param{long}{ type = wxBITMAP\_TYPE\_ANY}}
1e6d9499 77
9e9ee68e
VS
78\func{}{wxImage}{\param{const wxString\& }{name}, \param{const wxString\&}{ mimetype}}
79
1e6d9499
JS
80Loads an image from a file.
81
087c0d5e 82\func{}{wxImage}{\param{wxInputStream\& }{stream}, \param{long}{ type = wxBITMAP\_TYPE\_ANY}}
45b5751f 83
9e9ee68e
VS
84\func{}{wxImage}{\param{wxInputStream\& }{stream}, \param{const wxString\&}{ mimetype}}
85
45b5751f
JS
86Loads an image from an input stream.
87
1e6d9499
JS
88\wxheading{Parameters}
89
90\docparam{width}{Specifies the width of the image.}
91
92\docparam{height}{Specifies the height of the image.}
93
94\docparam{name}{This refers to an image filename. Its meaning is determined by the {\it type} parameter.}
95
45b5751f
JS
96\docparam{stream}{This refers to an input stream. Its meaning is determined by the {\it type} parameter. It is equal to loading from file except that you provide opened stream (file, HTTP or any other custom class).}
97
1e6d9499
JS
98\docparam{type}{May be one of the following:
99
6be663cf 100\twocolwidtha{5cm}%
1e6d9499 101\begin{twocollist}
f6fcbb63
RR
102\twocolitem{{\bf \indexit{wxBITMAP\_TYPE\_BMP}}}{Load a Windows bitmap file.}
103\twocolitem{{\bf \indexit{wxBITMAP\_TYPE\_PNG}}}{Load a PNG bitmap file.}
48b4e302 104\twocolitem{{\bf \indexit{wxBITMAP\_TYPE\_JPEG}}}{Load a JPEG bitmap file.}
2376d03d
VS
105\twocolitem{{\bf \indexit{wxBITMAP\_TYPE\_GIF}}}{Load a GIF bitmap file.}
106\twocolitem{{\bf \indexit{wxBITMAP\_TYPE\_PCX}}}{Load a PCX bitmap file.}
107\twocolitem{{\bf \indexit{wxBITMAP\_TYPE\_PNM}}}{Load a PNM bitmap file.}
087c0d5e 108\twocolitem{{\bf \indexit{wxBITMAP\_TYPE\_ANY}}}{Will try to autodetect the format.}
1e6d9499
JS
109\end{twocollist}
110
111The validity of these flags depends on the platform and wxWindows configuration.
48b4e302
VS
112If all possible wxWindows settings are used, the loading a BMP (Windows bitmap) file,
113a PNG (portable network graphics) file and a JPEG file is supported on all platforms that
12a44087 114implement wxImage.}
1e6d9499 115
9e9ee68e
VS
116\docparam{mimetype}{MIME type string (for example 'image/jpeg')}
117
f899db6d 118Note : you must call wxImage::AddHandler(new wxJPEGHandler) during application
0a9f2522
VS
119initialization in order to work with JPEGs.
120
1e6d9499
JS
121\wxheading{See also}
122
123\helpref{wxImage::LoadFile}{wximageloadfile}
124
f899db6d
RD
125\pythonnote{Constructors supported by wxPython are:\par
126\indented{2cm}{\begin{twocollist}
c9110876
VS
127\twocolitem{{\bf wxImage(name, flag)}}{Loads an image from a file}
128\twocolitem{{\bf wxNullImage()}}{Create a null image (has no size or
f899db6d 129image data)}
c9110876 130\twocolitem{{\bf wxEmptyImage(width, height)}}{Creates an empty image
f899db6d 131of the given size}
c9110876 132\twocolitem{{\bf wxImageFromMime(name, mimetype}}{Creates an image from
f899db6d 133the given file of the given mimetype}
c9110876 134\twocolitem{{\bf wxImageFromBitmap(bitmap)}}{Creates an image from a
f899db6d
RD
135platform-dependent bitmap}
136\end{twocollist}}
137}
138
1e6d9499
JS
139\membersection{wxImage::\destruct{wxImage}}
140
141\func{}{\destruct{wxImage}}{\void}
142
143Destructor.
144
145\membersection{wxImage::AddHandler}\label{wximageaddhandler}
146
147\func{static void}{AddHandler}{\param{wxImageHandler*}{ handler}}
148
149Adds a handler to the end of the static list of format handlers.
150
151\docparam{handler}{A new image format handler object. There is usually only one instance
152of a given handler class in an application session.}
153
154\wxheading{See also}
155
156\helpref{wxImageHandler}{wximagehandler}
157
c9110876 158\pythonnote{In wxPython this static method is named {\tt wxImage_AddHandler}.}
1e6d9499
JS
159\membersection{wxImage::CleanUpHandlers}
160
161\func{static void}{CleanUpHandlers}{\void}
162
163Deletes all image handlers.
164
165This function is called by wxWindows on exit.
166
167\membersection{wxImage::ConvertToBitmap}\label{wximageconverttobitmap}
168
169\constfunc{wxBitmap}{ConvertToBitmap}{\void}
170
12a44087
RR
171Converts the image to a platform-specific bitmap object. This has to be done
172to actually display an image as you cannot draw an image directly on a window.
173The resulting bitmap will use the colour depth of the current system which entails
7468b994
RR
174that a colour reduction has to take place.
175
176When in 8-bit mode (PseudoColour mode), the GTK port will use a color cube created
177on program start-up to look up colors. This ensures a very fast conversion, but
178the image quality won't be perfect (and could be better for photo images using more
179sophisticated dithering algorithms).
1e6d9499
JS
180
181\membersection{wxImage::Create}\label{wximagecreate}
182
183\func{bool}{Create}{\param{int}{ width}, \param{int}{ height}}
184
185Creates a fresh image.
186
187\wxheading{Parameters}
188
189\docparam{width}{The width of the image in pixels.}
190
191\docparam{height}{The height of the image in pixels.}
192
193\wxheading{Return value}
194
195TRUE if the call succeeded, FALSE otherwise.
196
197\membersection{wxImage::Destroy}\label{wximagedestroy}
198
199\func{bool}{Destroy}{\void}
200
201Destroys the image data.
202
203\membersection{wxImage::FindHandler}
204
205\func{static wxImageHandler*}{FindHandler}{\param{const wxString\& }{name}}
206
207Finds the handler with the given name.
208
209\func{static wxImageHandler*}{FindHandler}{\param{const wxString\& }{extension}, \param{long}{ imageType}}
210
211Finds the handler associated with the given extension and type.
212
213\func{static wxImageHandler*}{FindHandler}{\param{long }{imageType}}
214
215Finds the handler associated with the given image type.
216
9e9ee68e
VS
217\func{static wxImageHandler*}{FindHandlerMime}{\param{const wxString\& }{mimetype}}
218
219Finds the handler associated with the given MIME type.
220
1e6d9499
JS
221\docparam{name}{The handler name.}
222
223\docparam{extension}{The file extension, such as ``bmp".}
224
f6fcbb63 225\docparam{imageType}{The image type, such as wxBITMAP\_TYPE\_BMP.}
1e6d9499 226
9e9ee68e
VS
227\docparam{mimetype}{MIME type.}
228
1e6d9499
JS
229\wxheading{Return value}
230
231A pointer to the handler if found, NULL otherwise.
232
233\wxheading{See also}
234
235\helpref{wxImageHandler}{wximagehandler}
236
237\membersection{wxImage::GetBlue}\label{wximagegetblue}
238
239\constfunc{unsigned char}{GetBlue}{\param{int}{ x}, \param{int}{ y}}
240
241Returns the blue intensity at the given coordinate.
242
243\membersection{wxImage::GetData}\label{wximagegetdata}
244
245\constfunc{unsigned char*}{GetData}{\void}
246
12a44087
RR
247Returns the image data as an array. This is most often used when doing
248direct image manipulation. The return value points to an array of
249chararcters in RGBGBRGB... format.
1e6d9499
JS
250
251\membersection{wxImage::GetGreen}\label{wximagegetgreen}
252
253\constfunc{unsigned char}{GetGreen}{\param{int}{ x}, \param{int}{ y}}
254
255Returns the green intensity at the given coordinate.
256
257\membersection{wxImage::GetRed}\label{wximagegetred}
258
259\constfunc{unsigned char}{GetRed}{\param{int}{ x}, \param{int}{ y}}
260
261Returns the red intensity at the given coordinate.
262
263\membersection{wxImage::GetHandlers}
264
265\func{static wxList\&}{GetHandlers}{\void}
266
267Returns the static list of image format handlers.
268
269\wxheading{See also}
270
271\helpref{wxImageHandler}{wximagehandler}
272
273\membersection{wxImage::GetHeight}\label{wximagegetheight}
274
275\constfunc{int}{GetHeight}{\void}
276
277Gets the height of the image in pixels.
278
279\membersection{wxImage::GetMaskBlue}\label{wximagegetmaskblue}
280
281\constfunc{unsigned char}{GetMaskBlue}{\void}
282
283Gets the blue value of the mask colour.
284
285\membersection{wxImage::GetMaskGreen}\label{wximagegetmaskgreen}
286
287\constfunc{unsigned char}{GetMaskGreen}{\void}
288
289Gets the green value of the mask colour.
290
291\membersection{wxImage::GetMaskRed}\label{wximagegetmaskred}
292
293\constfunc{unsigned char}{GetMaskRed}{\void}
294
295Gets the red value of the mask colour.
296
fc9c7c09
RR
297\membersection{wxImage::GetSubImage}\label{wximagegetsubimage}
298
7468b994 299\constfunc{wxImage}{GetSubImage}{\param{const wxRect\&}{ rect}}
fc9c7c09
RR
300
301Returns a sub image of the current one as long as the rect belongs entirely to
302the image.
303
1e6d9499
JS
304\membersection{wxImage::GetWidth}\label{wximagegetwidth}
305
306\constfunc{int}{GetWidth}{\void}
307
308Gets the width of the image in pixels.
309
310\wxheading{See also}
311
312\helpref{wxImage::GetHeight}{wximagegetheight}
313
314\membersection{wxImage::HasMask}\label{wximagehasmask}
315
316\constfunc{bool}{HasMask}{\void}
317
318Returns TRUE if there is a mask active, FALSE otherwise.
319
320\membersection{wxImage::InitStandardHandlers}
321
322\func{static void}{InitStandardHandlers}{\void}
323
a14e57f9
SB
324Internal use only. Adds standard image format handlers. It only install BMP
325for the time being, which is use by wxBitmap.
1e6d9499 326
a14e57f9
SB
327This function is called by wxWindows on startup, and shouldn't be called by
328the user.
1e6d9499
JS
329
330\wxheading{See also}
331
332\helpref{wxImageHandler}{wximagehandler}
b5a4a47d 333\helpref{wxInitAllImageHandlers}{wxinitallimagehandlers}
1e6d9499
JS
334
335\membersection{wxImage::InsertHandler}
336
337\func{static void}{InsertHandler}{\param{wxImageHandler*}{ handler}}
338
339Adds a handler at the start of the static list of format handlers.
340
341\docparam{handler}{A new image format handler object. There is usually only one instance
342of a given handler class in an application session.}
343
344\wxheading{See also}
345
346\helpref{wxImageHandler}{wximagehandler}
347
348\membersection{wxImage::LoadFile}\label{wximageloadfile}
349
a14e57f9 350\func{bool}{LoadFile}{\param{const wxString\&}{ name}, \param{long}{ type = wxBITMAP\_TYPE\_ANY}}
1e6d9499 351
9e9ee68e
VS
352\func{bool}{LoadFile}{\param{const wxString\&}{ name}, \param{const wxString\&}{ mimetype}}
353
a14e57f9 354Loads an image from a file. If no handler type is provided, the library will
88b1927c 355try to use wxBITMAP\_TYPE\_BMP.
1e6d9499 356
45b5751f
JS
357\func{bool}{LoadFile}{\param{wxInputStream\&}{ stream}, \param{long}{ type}}
358
9e9ee68e
VS
359\func{bool}{LoadFile}{\param{wxInputStream\&}{ stream}, \param{const wxString\&}{ mimetype}}
360
45b5751f
JS
361Loads an image from an input stream.
362
1e6d9499
JS
363\wxheading{Parameters}
364
365\docparam{name}{A filename.
366The meaning of {\it name} is determined by the {\it type} parameter.}
367
45b5751f
JS
368\docparam{stream}{An input stream.
369The meaning of {\it stream} data is determined by the {\it type} parameter.}
370
1e6d9499
JS
371\docparam{type}{One of the following values:
372
6be663cf 373\twocolwidtha{5cm}%
1e6d9499 374\begin{twocollist}
f6fcbb63 375\twocolitem{{\bf wxBITMAP\_TYPE\_BMP}}{Load a Windows image file.}
a14e57f9 376\twocolitem{{\bf wxBITMAP\_TYPE\_GIF}}{Load a GIF image file.}
7468b994 377\twocolitem{{\bf wxBITMAP\_TYPE\_TIF}}{Load a TIFF image file.}
48b4e302 378\twocolitem{{\bf wxBITMAP\_TYPE\_JPEG}}{Load a JPEG image file.}
a14e57f9
SB
379\twocolitem{{\bf wxBITMAP\_TYPE\_PCX}}{Load a PCX image file.}
380\twocolitem{{\bf wxBITMAP\_TYPE\_PNG}}{Load a PNG image file.}
381\twocolitem{{\bf wxBITMAP\_TYPE\_PNM}}{Load a PNM image file.}
1e6d9499
JS
382\end{twocollist}
383
384The validity of these flags depends on the platform and wxWindows configuration.}
385
9e9ee68e
VS
386\docparam{mimetype}{MIME type string (for example 'image/jpeg')}
387
1e6d9499
JS
388\wxheading{Return value}
389
390TRUE if the operation succeeded, FALSE otherwise.
391
392\wxheading{See also}
393
394\helpref{wxImage::SaveFile}{wximagesavefile}
395
f899db6d
RD
396\pythonnote{In place of a single overloaded method name, wxPython
397implements the following methods:\par
398\indented{2cm}{\begin{twocollist}
c9110876 399\twocolitem{{\bf LoadFile(filename, type)}}{Loads an image of the given
f899db6d 400type from a file}
c9110876 401\twocolitem{{\bf LoadMimeFile(filename, mimetype)}}{Loads an image of the given
f899db6d
RD
402mimetype from a file}
403\end{twocollist}}
404}
405
406
1e6d9499
JS
407\membersection{wxImage::Ok}\label{wximageok}
408
409\constfunc{bool}{Ok}{\void}
410
411Returns TRUE if image data is present.
412
413\membersection{wxImage::RemoveHandler}
414
415\func{static bool}{RemoveHandler}{\param{const wxString\& }{name}}
416
417Finds the handler with the given name, and removes it. The handler
418is not deleted.
419
420\docparam{name}{The handler name.}
421
422\wxheading{Return value}
423
424TRUE if the handler was found and removed, FALSE otherwise.
425
426\wxheading{See also}
427
428\helpref{wxImageHandler}{wximagehandler}
429
430\membersection{wxImage::SaveFile}\label{wximagesavefile}
431
432\func{bool}{SaveFile}{\param{const wxString\& }{name}, \param{int}{ type}}
433
9e9ee68e
VS
434\func{bool}{SaveFile}{\param{const wxString\& }{name}, \param{const wxString\&}{ mimetype}}
435
1e6d9499
JS
436Saves a image in the named file.
437
45b5751f
JS
438\func{bool}{SaveFile}{\param{wxOutputStream\& }{stream}, \param{int}{ type}}
439
9e9ee68e
VS
440\func{bool}{SaveFile}{\param{wxOutputStream\& }{stream}, \param{const wxString\&}{ mimetype}}
441
45b5751f
JS
442Saves a image in the given stream.
443
1e6d9499
JS
444\wxheading{Parameters}
445
446\docparam{name}{A filename. The meaning of {\it name} is determined by the {\it type} parameter.}
447
45b5751f
JS
448\docparam{stream}{An output stream. The meaning of {\it stream} is determined by the {\it type} parameter.}
449
7468b994 450\docparam{type}{Currently three types can be used:
1e6d9499 451
6be663cf 452\twocolwidtha{5cm}%
1e6d9499 453\begin{twocollist}
f6fcbb63 454\twocolitem{{\bf wxBITMAP\_TYPE\_PNG}}{Save a PNG image file.}
48b4e302 455\twocolitem{{\bf wxBITMAP\_TYPE\_JPEG}}{Save a JPEG image file.}
7468b994 456\twocolitem{{\bf wxBITMAP\_TYPE\_PCX}}{Save a PCX image file.}
1e6d9499
JS
457\end{twocollist}
458
12a44087
RR
459The validity of these flags depends on the platform and wxWindows configuration
460as well as user-added handlers.}
1e6d9499 461
9e9ee68e
VS
462\docparam{mimetype}{MIME type.}
463
1e6d9499
JS
464\wxheading{Return value}
465
466TRUE if the operation succeeded, FALSE otherwise.
467
468\wxheading{Remarks}
469
470Depending on how wxWindows has been configured, not all formats may be available.
471
472\wxheading{See also}
473
474\helpref{wxImage::LoadFile}{wximageloadfile}
475
f899db6d
RD
476\pythonnote{In place of a single overloaded method name, wxPython
477implements the following methods:\par
478\indented{2cm}{\begin{twocollist}
c9110876 479\twocolitem{{\bf SaveFile(filename, type)}}{Saves the image using the given
f899db6d 480type to the named file}
c9110876 481\twocolitem{{\bf SaveMimeFile(filename, mimetype)}}{Saves the image using the given
f899db6d
RD
482mimetype to the named file}
483\end{twocollist}}
484}
485
7468b994
RR
486\membersection{wxImage::Replace}\label{wximagereplace}
487
488\func{void}{Replace}{\param{unsigned char}{ r1}, \param{unsigned char}{ g1}, \param{unsigned char}{ b1},
489\param{unsigned char}{ r2}, \param{unsigned char}{ g2}, \param{unsigned char}{ b2}}
490
491Replaces the colour specified by {\it r1,g1,b1} by the colour {\it r2,g2,b2}.
492
ce9a75d2
VZ
493\membersection{wxImage::Rescale}\label{wximagerescale}
494
6e807169 495\func{wxImage \&}{Rescale}{\param{int}{ width}, \param{int}{ height}}
ce9a75d2 496
9c884972
RR
497Changes the size of the image in-place: after a call to this function, the
498image will have the given width and height.
ce9a75d2 499
6e807169
VZ
500Returns the (modified) image itself.
501
ce9a75d2
VZ
502\wxheading{See also}
503
504\helpref{Scale}{wximagescale}
505
1e6d9499
JS
506\membersection{wxImage::Scale}\label{wximagescale}
507
ce9a75d2 508\constfunc{wxImage}{Scale}{\param{int}{ width}, \param{int}{ height}}
1e6d9499 509
12a44087
RR
510Returns a scaled version of the image. This is also useful for
511scaling bitmaps in general as the only other way to scale bitmaps
ce9a75d2
VZ
512is to blit a wxMemoryDC into another wxMemoryDC.
513
7468b994 514It may be mentioned that the GTK port uses this function internally
fc9c7c09 515to scale bitmaps when using mapping mode in wxDC.
ce9a75d2
VZ
516
517Example:
518
519\begin{verbatim}
520 // get the bitmap from somewhere
521 wxBitmap bmp = ...;
522
523 // rescale it to have size of 32*32
524 if ( bmp.GetWidth() != 32 || bmp.GetHeight() != 32 )
525 {
526 wxImage image(bmp);
527 bmp = image.Scale(32, 32).ConvertToBitmap();
528
529 // another possibility:
530 image.Rescale(32, 32);
531 bmp = image;
532 }
533
534\end{verbatim}
535
536\wxheading{See also}
537
538\helpref{Rescale}{wximagerescale}
1e6d9499
JS
539
540\membersection{wxImage::SetData}\label{wximagesetdata}
541
542\func{void}{SetData}{\param{unsigned char*}{data}}
543
f899db6d 544Sets the image data without performing checks. The data given must have
12a44087
RR
545the size (width*height*3) or results will be unexpected. Don't use this
546method if you aren't sure you know what you are doing.
1e6d9499
JS
547
548\membersection{wxImage::SetMask}\label{wximagesetmask}
549
550\func{void}{SetMask}{\param{bool}{ hasMask = TRUE}}
551
552Specifies whether there is a mask or not. The area of the mask is determined by the current mask colour.
553
554\membersection{wxImage::SetMaskColour}\label{wximagesetmaskcolour}
555
556\func{void}{SetMaskColour}{\param{unsigned char }{red}, \param{unsigned char }{blue}, \param{unsigned char }{green}}
557
b1170810 558Sets the mask colour for this image (and tells the image to use the mask).
1e6d9499
JS
559
560\membersection{wxImage::SetRGB}\label{wximagesetrgb}
561
562\func{void}{SetRGB}{\param{int }{x}, \param{int }{y}, \param{unsigned char }{red}, \param{unsigned char }{blue}, \param{unsigned char }{green}}
563
12a44087
RR
564Sets the pixel at the given coordinate. This routine performs bounds-checks
565for the coordinate so it can be considered a safe way to manipulate the
566data, but in some cases this might be too slow so that the data will have to
7468b994
RR
567be set directly. In that case you will have to get access to the image data
568using the \helpref{GetData}{wximagegetdata} method.
1e6d9499
JS
569
570\membersection{wxImage::operator $=$}
571
572\func{wxImage\& }{operator $=$}{\param{const wxImage\& }{image}}
573
574Assignment operator. This operator does not copy any data, but instead
575passes a pointer to the data in {\it image} and increments a reference
576counter. It is a fast operation.
577
578\wxheading{Parameters}
579
580\docparam{image}{Image to assign.}
581
582\wxheading{Return value}
583
584Returns 'this' object.
585
586\membersection{wxImage::operator $==$}
587
588\func{bool}{operator $==$}{\param{const wxImage\& }{image}}
589
590Equality operator. This operator tests whether the internal data pointers are
591equal (a fast test).
592
593\wxheading{Parameters}
594
595\docparam{image}{Image to compare with 'this'}
596
597\wxheading{Return value}
598
599Returns TRUE if the images were effectively equal, FALSE otherwise.
600
601\membersection{wxImage::operator $!=$}
602
603\func{bool}{operator $!=$}{\param{const wxImage\& }{image}}
604
605Inequality operator. This operator tests whether the internal data pointers are
606unequal (a fast test).
607
608\wxheading{Parameters}
609
610\docparam{image}{Image to compare with 'this'}
611
612\wxheading{Return value}
613
614Returns TRUE if the images were unequal, FALSE otherwise.
615
616\section{\class{wxImageHandler}}\label{wximagehandler}
617
1e6d9499
JS
618This is the base class for implementing image file loading/saving, and image creation from data.
619It is used within wxImage and is not normally seen by the application.
620
621If you wish to extend the capabilities of wxImage, derive a class from wxImageHandler
622and add the handler using \helpref{wxImage::AddHandler}{wximageaddhandler} in your
623application initialisation.
624
48b4e302
VS
625\wxheading{Note (Legal Issue)}
626
954b8ae6 627This software is based in part on the work of the Independent JPEG Group.
48b4e302
VS
628
629(Applies when wxWindows is linked with JPEG support. wxJPEGHandler uses libjpeg
630created by IJG.)
631
1e6d9499
JS
632\wxheading{Derived from}
633
634\helpref{wxObject}{wxobject}
635
954b8ae6
JS
636\wxheading{Include files}
637
638<wx/image.h>
639
1e6d9499
JS
640\wxheading{See also}
641
642\helpref{wxImage}{wximage}
b5a4a47d 643\helpref{wxInitAllImageHandlers}{wxinitallimagehandlers}
1e6d9499
JS
644
645\latexignore{\rtfignore{\wxheading{Members}}}
646
647\membersection{wxImageHandler::wxImageHandler}\label{wximagehandlerconstr}
648
649\func{}{wxImageHandler}{\void}
650
651Default constructor. In your own default constructor, initialise the members
652m\_name, m\_extension and m\_type.
653
654\membersection{wxImageHandler::\destruct{wxImageHandler}}
655
656\func{}{\destruct{wxImageHandler}}{\void}
657
658Destroys the wxImageHandler object.
659
660\membersection{wxImageHandler::GetName}
661
662\constfunc{wxString}{GetName}{\void}
663
664Gets the name of this handler.
665
666\membersection{wxImageHandler::GetExtension}
667
668\constfunc{wxString}{GetExtension}{\void}
669
670Gets the file extension associated with this handler.
671
7941ba11
RR
672\membersection{wxImageHandler::GetImageCount}\label{wximagehandlergetimagecount}
673
674\func{int}{GetImageCount}{\param{wxInputStream\&}{ stream}}
675
676If the image file contains more than one image and the image handler is capable
677of retrieving these individually, this function will return the number of
678available images.
679
680\docparam{stream}{Opened input stream for reading image file.}
681
682\wxheading{Return value}
683
684Number of available images. For most image handles, this defaults to 1.
685
1e6d9499
JS
686\membersection{wxImageHandler::GetType}
687
688\constfunc{long}{GetType}{\void}
689
690Gets the image type associated with this handler.
691
9e9ee68e
VS
692\membersection{wxImageHandler::GetMimeType}
693
694\constfunc{wxString}{GetMimeType}{\void}
695
696Gets the MIME type associated with this handler.
697
1e6d9499
JS
698\membersection{wxImageHandler::LoadFile}\label{wximagehandlerloadfile}
699
7941ba11 700\func{bool}{LoadFile}{\param{wxImage* }{image}, \param{wxInputStream\&}{ stream}, \param{bool}{ verbose=TRUE}, \param{int}{ index=0}}
1e6d9499 701
7941ba11
RR
702Loads a image from a stream, putting the resulting data into {\it image}. If the image file contains
703more than one image and the image handler is capable of retrieving these individually, {\it index}
704indicates which image to read from the stream.
1e6d9499
JS
705
706\wxheading{Parameters}
707
708\docparam{image}{The image object which is to be affected by this operation.}
709
7941ba11
RR
710\docparam{stream}{Opened input stream for reading images.}
711
712\docparam{verbose}{If set to TRUE, errors reported by the image handler will produce wxLogMessages.}
713
714\docparam{index}{The index of the image in the file (starting from zero).}
1e6d9499
JS
715
716\wxheading{Return value}
717
718TRUE if the operation succeeded, FALSE otherwise.
719
720\wxheading{See also}
721
722\helpref{wxImage::LoadFile}{wximageloadfile}\\
723\helpref{wxImage::SaveFile}{wximagesavefile}\\
724\helpref{wxImageHandler::SaveFile}{wximagehandlersavefile}
725
726\membersection{wxImageHandler::SaveFile}\label{wximagehandlersavefile}
727
45b5751f 728\func{bool}{SaveFile}{\param{wxImage* }{image}, \param{wxOutputStream\& }{stream}}
1e6d9499 729
45b5751f 730Saves a image in the output stream.
1e6d9499
JS
731
732\wxheading{Parameters}
733
734\docparam{image}{The image object which is to be affected by this operation.}
735
7941ba11 736\docparam{stream}{An opened stream for writing images.}
1e6d9499
JS
737
738\wxheading{Return value}
739
740TRUE if the operation succeeded, FALSE otherwise.
741
742\wxheading{See also}
743
744\helpref{wxImage::LoadFile}{wximageloadfile}\\
745\helpref{wxImage::SaveFile}{wximagesavefile}\\
746\helpref{wxImageHandler::LoadFile}{wximagehandlerloadfile}
747
748\membersection{wxImageHandler::SetName}
749
750\func{void}{SetName}{\param{const wxString\& }{name}}
751
752Sets the handler name.
753
754\wxheading{Parameters}
755
756\docparam{name}{Handler name.}
757
758\membersection{wxImageHandler::SetExtension}
759
760\func{void}{SetExtension}{\param{const wxString\& }{extension}}
761
762Sets the handler extension.
763
764\wxheading{Parameters}
765
766\docparam{extension}{Handler extension.}
767
768\membersection{wxImageHandler::SetType}
769
770\func{void}{SetType}{\param{long }{type}}
771
772Sets the handler type.
773
774\wxheading{Parameters}
775
776\docparam{name}{Handler type.}
777
9e9ee68e
VS
778
779\membersection{wxImageHandler::SetMimeType}
780
781\func{void}{SetMimeType}{\param{const wxString\& }{mimetype}}
782
783Sets the handler MIME type.
784
785\wxheading{Parameters}
786
787\docparam{mimename}{Handler MIME type.}
788