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