1 \section{\class{wxImage
}}\label{wximage
}
3 This class encapsulates a platform-independent image. An image can be created
4 from data, or using
\helpref{wxBitmap::ConvertToImage
}{wxbitmapconverttoimage
}. 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.
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{wxBitmap::wxBitmap(wxImage,int depth)
}{wxbitmapconstr
} constructor.
13 be drawn in a device context, using
\helpref{wxDC::DrawBitmap
}{wxdcdrawbitmap
}.
15 One colour value of the image may be used as a mask colour which will lead to the automatic
16 creation of a
\helpref{wxMask
}{wxmask
} object associated to the bitmap object.
18 \wxheading{Available image handlers
}
20 The following image handlers are available.
{\bf wxBMPHandler
} is always
21 installed by default. To use other image formats, install the appropiate
22 handler with
\helpref{wxImage::AddHandler
}{wximageaddhandler
} or
23 \helpref{wxInitAllImageHandlers
}{wxinitallimagehandlers
}.
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).
}
33 \twocolitem{\indexit{wxTIFFHandler
}}{For loading and saving.
}
34 \twocolitem{\indexit{wxXPMHandler
}}{For loading and saving.
}
35 \twocolitem{\indexit{wxICOHandler
}}{For loading and saving.
}
36 \twocolitem{\indexit{wxCURHandler
}}{For loading and saving.
}
39 When saving in PCX format,
{\bf wxPCXHandler
} will count the number of
40 different colours in the image; if there are
256 or less colours, it will
41 save as
8 bit, else it will save as
24 bit.
43 Loading PNMs only works for ASCII or raw RGB images. When saving in
44 PNM format,
{\bf wxPNMHandler
} will always save as raw RGB.
46 \wxheading{Derived from
}
48 \helpref{wxObject
}{wxobject
}
50 \wxheading{Include files
}
56 \helpref{wxBitmap
}{wxbitmap
},
57 \helpref{wxInitAllImageHandlers
}{wxinitallimagehandlers
}
59 \latexignore{\rtfignore{\wxheading{Members
}}}
61 \membersection{wxImage::wxImage
}\label{wximageconstr
}
63 \func{}{wxImage
}{\void}
67 \func{}{wxImage
}{\param{const wxImage\&
}{image
}}
71 \func{}{wxImage
}{\param{const wxBitmap\&
}{ bitmap
}}
73 (Deprecated form, use
\helpref{wxBitmap::ConvertToImage
}{wxbitmapconverttoimage
}
74 instead.) Constructs an image from a platform-dependent bitmap. This preserves
75 mask information so that bitmaps and images can be converted back
76 and forth without loss in that respect.
78 \func{}{wxImage
}{\param{int
}{ width
},
\param{int
}{ height
}}
80 Creates an image with the given width and height.
82 \func{}{wxImage
}{\param{int
}{ width
},
\param{int
}{ height
},
\param{unsigned char*
}{ data
},
\param{bool
}{ static
\_data=FALSE
}}
84 Creates an image from given data with the given width and height. If
85 {\it static
\_data} is TRUE, then wxImage will not delete the actual
86 image data in its destructor, otherwise it will free it by calling
89 \func{}{wxImage
}{\param{const wxString\&
}{name
},
\param{long
}{ type = wxBITMAP
\_TYPE\_ANY},
\param{int
}{ index = -
1}}
91 \func{}{wxImage
}{\param{const wxString\&
}{name
},
\param{const wxString\&
}{ mimetype
},
\param{int
}{ index = -
1}}
93 Loads an image from a file.
95 \func{}{wxImage
}{\param{wxInputStream\&
}{stream
},
\param{long
}{ type = wxBITMAP
\_TYPE\_ANY},
\param{int
}{ index = -
1}}
97 \func{}{wxImage
}{\param{wxInputStream\&
}{stream
},
\param{const wxString\&
}{ mimetype
},
\param{int
}{ index = -
1}}
99 Loads an image from an input stream.
101 \wxheading{Parameters
}
103 \docparam{width
}{Specifies the width of the image.
}
105 \docparam{height
}{Specifies the height of the image.
}
107 \docparam{name
}{Name of the file from which to load the image.
}
109 \docparam{stream
}{Opened input stream from which to load the image. Currently, the stream must support seeking.
}
111 \docparam{type
}{May be one of the following:
115 \twocolitem{\indexit{wxBITMAP
\_TYPE\_BMP}}{Load a Windows bitmap file.
}
116 \twocolitem{\indexit{wxBITMAP
\_TYPE\_GIF}}{Load a GIF bitmap file.
}
117 \twocolitem{\indexit{wxBITMAP
\_TYPE\_JPEG}}{Load a JPEG bitmap file.
}
118 \twocolitem{\indexit{wxBITMAP
\_TYPE\_PNG}}{Load a PNG bitmap file.
}
119 \twocolitem{\indexit{wxBITMAP
\_TYPE\_PCX}}{Load a PCX bitmap file.
}
120 \twocolitem{\indexit{wxBITMAP
\_TYPE\_PNM}}{Load a PNM bitmap file.
}
121 \twocolitem{\indexit{wxBITMAP
\_TYPE\_TIF}}{Load a TIFF bitmap file.
}
122 \twocolitem{\indexit{wxBITMAP
\_TYPE\_XPM}}{Load a XPM bitmap file.
}
123 \twocolitem{\indexit{wxBITMAP
\_TYPE\_ICO}}{Load a Windows icon file (ICO).
}
124 \twocolitem{\indexit{wxBITMAP
\_TYPE\_CUR}}{Load a Windows cursor file (CUR).
}
125 \twocolitem{\indexit{wxBITMAP
\_TYPE\_ANY}}{Will try to autodetect the format.
}
128 \docparam{mimetype
}{MIME type string (for example 'image/jpeg')
}
130 \docparam{index
}{Index of the image to load in the case that the image file contains multiple images.
131 This is only used by ICO and TIFF handlers. The default value (-
1) means
132 "choose the default image" and is interpreted as the first image (index=
0) by
133 the TIFF handler and as the largest and most colourful one by the ICO handler.
}
137 Depending on how wxWindows has been configured, not all formats may be available.
139 Note: any handler other than BMP must be previously
140 initialized with
\helpref{wxImage::AddHandler
}{wximageaddhandler
} or
141 \helpref{wxInitAllImageHandlers
}{wxinitallimagehandlers
}.
143 Note: you can use
\helpref{GetOptionInt
}{wximagegetoptionint
} to get the
144 hotspot for loaded cursor file:
146 int hotspot_x = image.GetOptionInt(wxCUR_HOTSPOT_X);
147 int hotspot_y = image.GetOptionInt(wxCUR_HOTSPOT_Y);
153 \helpref{wxImage::LoadFile
}{wximageloadfile
}
155 \pythonnote{Constructors supported by wxPython are:
\par
156 \indented{2cm
}{\begin{twocollist
}
157 \twocolitem{{\bf wxImage(name, flag)
}}{Loads an image from a file
}
158 \twocolitem{{\bf wxNullImage()
}}{Create a null image (has no size or
160 \twocolitem{{\bf wxEmptyImage(width, height)
}}{Creates an empty image
162 \twocolitem{{\bf wxImageFromMime(name, mimetype
}}{Creates an image from
163 the given file of the given mimetype
}
164 \twocolitem{{\bf wxImageFromBitmap(bitmap)
}}{Creates an image from a
165 platform-dependent bitmap
}
169 \perlnote{Constructors supported by wxPerl are:
\par
171 \item{Wx::Image->new( bitmap )
}
172 \item{Wx::Image->new( width, height )
}
173 \item{Wx::Image->new( name, type )
}
174 \item{Wx::Image->new( name, mimetype )
}
178 \membersection{wxImage::
\destruct{wxImage
}}
180 \func{}{\destruct{wxImage
}}{\void}
184 \membersection{wxImage::AddHandler
}\label{wximageaddhandler
}
186 \func{static void
}{AddHandler
}{\param{wxImageHandler*
}{ handler
}}
188 Adds a handler to the end of the static list of format handlers.
190 \docparam{handler
}{A new image format handler object. There is usually only one instance
191 of a given handler class in an application session.
}
195 \helpref{wxImageHandler
}{wximagehandler
}
197 \pythonnote{In wxPython this static method is named
{\tt wxImage
\_AddHandler}.
}
198 \membersection{wxImage::CleanUpHandlers
}
200 \func{static void
}{CleanUpHandlers
}{\void}
202 Deletes all image handlers.
204 This function is called by wxWindows on exit.
206 \membersection{wxImage::ConvertToBitmap
}\label{wximageconverttobitmap
}
208 \constfunc{wxBitmap
}{ConvertToBitmap
}{\void}
210 Deprecated, use equivalent
\helpref{wxBitmap constructor
}{wxbitmapconstr
}
211 (which takes wxImage and depth as its arguments) instead.
213 \membersection{wxImage::ConvertToMono
}\label{wxbitmapconverttomono
}
215 \constfunc{wxImage
}{ConvertToMono
}{\param{unsigned char
}{ r
},
\param{unsigned char
}{ g
},
\param{unsigned char
}{ b
}}
217 Returns monochromatic version of the image. The returned image has white
218 colour where the original has
{\it (r,g,b)
} colour and black colour
221 \membersection{wxImage::Copy
}\label{wximagecopy
}
223 \constfunc{wxImage
}{Copy
}{\void}
225 Returns an identical copy of the image.
227 \membersection{wxImage::Create
}\label{wximagecreate
}
229 \func{bool
}{Create
}{\param{int
}{ width
},
\param{int
}{ height
}}
231 Creates a fresh image.
233 \wxheading{Parameters
}
235 \docparam{width
}{The width of the image in pixels.
}
237 \docparam{height
}{The height of the image in pixels.
}
239 \wxheading{Return value
}
241 TRUE if the call succeeded, FALSE otherwise.
243 \membersection{wxImage::Destroy
}\label{wximagedestroy
}
245 \func{bool
}{Destroy
}{\void}
247 Destroys the image data.
249 \membersection{wxImage::FindFirstUnusedColour
}\label{wximagefindfirstunusedcolour
}
251 \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}}
253 \wxheading{Parameters
}
255 \docparam{r,g,b
}{Pointers to variables to save the colour.
}
257 \docparam{startR,startG,startB
}{Initial values of the colour. Returned colour
258 will have RGB values equal to or greater than these.
}
260 Finds the first colour that is never used in the image. The search begins at
261 given initial colour and continues by increasing R, G and B components (in this
262 order) by
1 until an unused colour is found or the colour space exhausted.
264 \wxheading{Return value
}
266 Returns FALSE if there is no unused colour left, TRUE on success.
270 Note that this method involves computing the histogram, which is
271 computationally intensive operation.
273 \membersection{wxImage::FindHandler
}
275 \func{static wxImageHandler*
}{FindHandler
}{\param{const wxString\&
}{name
}}
277 Finds the handler with the given name.
279 \func{static wxImageHandler*
}{FindHandler
}{\param{const wxString\&
}{extension
},
\param{long
}{ imageType
}}
281 Finds the handler associated with the given extension and type.
283 \func{static wxImageHandler*
}{FindHandler
}{\param{long
}{imageType
}}
285 Finds the handler associated with the given image type.
287 \func{static wxImageHandler*
}{FindHandlerMime
}{\param{const wxString\&
}{mimetype
}}
289 Finds the handler associated with the given MIME type.
291 \docparam{name
}{The handler name.
}
293 \docparam{extension
}{The file extension, such as ``bmp".
}
295 \docparam{imageType
}{The image type, such as wxBITMAP
\_TYPE\_BMP.
}
297 \docparam{mimetype
}{MIME type.
}
299 \wxheading{Return value
}
301 A pointer to the handler if found, NULL otherwise.
305 \helpref{wxImageHandler
}{wximagehandler
}
307 \membersection{wxImage::GetBlue
}\label{wximagegetblue
}
309 \constfunc{unsigned char
}{GetBlue
}{\param{int
}{ x
},
\param{int
}{ y
}}
311 Returns the blue intensity at the given coordinate.
313 \membersection{wxImage::GetData
}\label{wximagegetdata
}
315 \constfunc{unsigned char*
}{GetData
}{\void}
317 Returns the image data as an array. This is most often used when doing
318 direct image manipulation. The return value points to an array of
319 chararcters in RGBGBRGB... format.
321 \membersection{wxImage::GetGreen
}\label{wximagegetgreen
}
323 \constfunc{unsigned char
}{GetGreen
}{\param{int
}{ x
},
\param{int
}{ y
}}
325 Returns the green intensity at the given coordinate.
327 \membersection{wxImage::GetImageCount
}\label{wximagegetimagecount
}
329 \func{static int
}{GetImageCount
}{\param{const wxString\&
}{ filename
},
\param{long
}{ type = wxBITMAP
\_TYPE\_ANY}}
331 \func{static int
}{GetImageCount
}{\param{wxInputStream\&
}{ stream
},
\param{long
}{ type = wxBITMAP
\_TYPE\_ANY}}
333 If the image file contains more than one image and the image handler is capable
334 of retrieving these individually, this function will return the number of
337 \docparam{name
}{Name of the file to query.
}
339 \docparam{stream
}{Opened input stream with image data. Currently, the stream must support seeking.
}
341 \docparam{type
}{May be one of the following:
345 \twocolitem{\indexit{wxBITMAP
\_TYPE\_BMP}}{Load a Windows bitmap file.
}
346 \twocolitem{\indexit{wxBITMAP
\_TYPE\_GIF}}{Load a GIF bitmap file.
}
347 \twocolitem{\indexit{wxBITMAP
\_TYPE\_JPEG}}{Load a JPEG bitmap file.
}
348 \twocolitem{\indexit{wxBITMAP
\_TYPE\_PNG}}{Load a PNG bitmap file.
}
349 \twocolitem{\indexit{wxBITMAP
\_TYPE\_PCX}}{Load a PCX bitmap file.
}
350 \twocolitem{\indexit{wxBITMAP
\_TYPE\_PNM}}{Load a PNM bitmap file.
}
351 \twocolitem{\indexit{wxBITMAP
\_TYPE\_TIF}}{Load a TIFF bitmap file.
}
352 \twocolitem{\indexit{wxBITMAP
\_TYPE\_XPM}}{Load a XPM bitmap file.
}
353 \twocolitem{\indexit{wxBITMAP
\_TYPE\_ICO}}{Load a Windows icon file (ICO).
}
354 \twocolitem{\indexit{wxBITMAP
\_TYPE\_CUR}}{Load a Windows cursor file (CUR).
}
355 \twocolitem{\indexit{wxBITMAP
\_TYPE\_ANY}}{Will try to autodetect the format.
}
358 \wxheading{Return value
}
360 Number of available images. For most image handlers, this is
1 (exceptions
361 are TIFF and ICO formats).
363 \membersection{wxImage::GetRed
}\label{wximagegetred
}
365 \constfunc{unsigned char
}{GetRed
}{\param{int
}{ x
},
\param{int
}{ y
}}
367 Returns the red intensity at the given coordinate.
369 \membersection{wxImage::GetHandlers
}
371 \func{static wxList\&
}{GetHandlers
}{\void}
373 Returns the static list of image format handlers.
377 \helpref{wxImageHandler
}{wximagehandler
}
379 \membersection{wxImage::GetHeight
}\label{wximagegetheight
}
381 \constfunc{int
}{GetHeight
}{\void}
383 Gets the height of the image in pixels.
385 \membersection{wxImage::GetMaskBlue
}\label{wximagegetmaskblue
}
387 \constfunc{unsigned char
}{GetMaskBlue
}{\void}
389 Gets the blue value of the mask colour.
391 \membersection{wxImage::GetMaskGreen
}\label{wximagegetmaskgreen
}
393 \constfunc{unsigned char
}{GetMaskGreen
}{\void}
395 Gets the green value of the mask colour.
397 \membersection{wxImage::GetMaskRed
}\label{wximagegetmaskred
}
399 \constfunc{unsigned char
}{GetMaskRed
}{\void}
401 Gets the red value of the mask colour.
403 \membersection{wxImage::GetPalette
}\label{wximagegetpalette
}
405 \constfunc{const wxPalette\&
}{GetPalette
}{\void}
407 Returns the palette associated with the image. Currently the palette is only
408 used when converting to wxBitmap under Windows.
410 Eventually wxImage handlers will set the palette if one exists in the image file.
412 \membersection{wxImage::GetSubImage
}\label{wximagegetsubimage
}
414 \constfunc{wxImage
}{GetSubImage
}{\param{const wxRect\&
}{ rect
}}
416 Returns a sub image of the current one as long as the rect belongs entirely to
419 \membersection{wxImage::GetWidth
}\label{wximagegetwidth
}
421 \constfunc{int
}{GetWidth
}{\void}
423 Gets the width of the image in pixels.
427 \helpref{wxImage::GetHeight
}{wximagegetheight
}
429 \membersection{wxImage::HasMask
}\label{wximagehasmask
}
431 \constfunc{bool
}{HasMask
}{\void}
433 Returns TRUE if there is a mask active, FALSE otherwise.
435 \membersection{wxImage::GetOption
}\label{wximagegetoption
}
437 \constfunc{wxString
}{GetOption
}{\param{const wxString\&
}{ name
}}
439 Gets a user-defined option. The function is case-insensitive to
{\it name
}.
441 For example, when saving as a JPEG file, the option
{\bf quality
} is
442 used, which is a number between
0 and
100 (
0 is terrible,
100 is very good).
446 \helpref{wxImage::SetOption
}{wximagesetoption
},
\rtfsp
447 \helpref{wxImage::GetOptionInt
}{wximagegetoptionint
},
\rtfsp
448 \helpref{wxImage::HasOption
}{wximagehasoption
}
450 \membersection{wxImage::GetOptionInt
}\label{wximagegetoptionint
}
452 \constfunc{int
}{GetOptionInt
}{\param{const wxString\&
}{ name
}}
454 Gets a user-defined option as an integer. The function is case-insensitive to
{\it name
}.
458 \helpref{wxImage::SetOption
}{wximagesetoption
},
\rtfsp
459 \helpref{wxImage::GetOption
}{wximagegetoption
},
\rtfsp
460 \helpref{wxImage::HasOption
}{wximagehasoption
}
462 \membersection{wxImage::HasOption
}\label{wximagehasoption
}
464 \constfunc{bool
}{HasOption
}{\param{const wxString\&
}{ name
}}
466 Returns TRUE if the given option is present. The function is case-insensitive to
{\it name
}.
470 \helpref{wxImage::SetOption
}{wximagesetoption
},
\rtfsp
471 \helpref{wxImage::GetOption
}{wximagegetoption
},
\rtfsp
472 \helpref{wxImage::GetOptionInt
}{wximagegetoptionint
}
474 \membersection{wxImage::InitStandardHandlers
}
476 \func{static void
}{InitStandardHandlers
}{\void}
478 Internal use only. Adds standard image format handlers. It only install BMP
479 for the time being, which is used by wxBitmap.
481 This function is called by wxWindows on startup, and shouldn't be called by
486 \helpref{wxImageHandler
}{wximagehandler
},
487 \helpref{wxInitAllImageHandlers
}{wxinitallimagehandlers
}
489 \membersection{wxImage::InsertHandler
}
491 \func{static void
}{InsertHandler
}{\param{wxImageHandler*
}{ handler
}}
493 Adds a handler at the start of the static list of format handlers.
495 \docparam{handler
}{A new image format handler object. There is usually only one instance
496 of a given handler class in an application session.
}
500 \helpref{wxImageHandler
}{wximagehandler
}
502 \membersection{wxImage::LoadFile
}\label{wximageloadfile
}
504 \func{bool
}{LoadFile
}{\param{const wxString\&
}{ name
},
\param{long
}{ type = wxBITMAP
\_TYPE\_ANY},
\param{int
}{ index = -
1}}
506 \func{bool
}{LoadFile
}{\param{const wxString\&
}{ name
},
\param{const wxString\&
}{ mimetype
},
\param{int
}{ index = -
1}}
508 Loads an image from a file. If no handler type is provided, the library will
509 try to autodetect the format.
511 \func{bool
}{LoadFile
}{\param{wxInputStream\&
}{ stream
},
\param{long
}{ type
},
\param{int
}{ index = -
1}}
513 \func{bool
}{LoadFile
}{\param{wxInputStream\&
}{ stream
},
\param{const wxString\&
}{ mimetype
},
\param{int
}{ index = -
1}}
515 Loads an image from an input stream.
517 \wxheading{Parameters
}
519 \docparam{name
}{Name of the file from which to load the image.
}
521 \docparam{stream
}{Opened input stream from which to load the image. Currently, the stream must support seeking.
}
523 \docparam{type
}{One of the following values:
527 \twocolitem{{\bf wxBITMAP
\_TYPE\_BMP}}{Load a Windows image file.
}
528 \twocolitem{{\bf wxBITMAP
\_TYPE\_GIF}}{Load a GIF image file.
}
529 \twocolitem{{\bf wxBITMAP
\_TYPE\_JPEG}}{Load a JPEG image file.
}
530 \twocolitem{{\bf wxBITMAP
\_TYPE\_PCX}}{Load a PCX image file.
}
531 \twocolitem{{\bf wxBITMAP
\_TYPE\_PNG}}{Load a PNG image file.
}
532 \twocolitem{{\bf wxBITMAP
\_TYPE\_PNM}}{Load a PNM image file.
}
533 \twocolitem{{\bf wxBITMAP
\_TYPE\_TIF}}{Load a TIFF image file.
}
534 \twocolitem{{\bf wxBITMAP
\_TYPE\_XPM}}{Load a XPM image file.
}
535 \twocolitem{{\bf wxBITMAP
\_TYPE\_ICO}}{Load a Windows icon file (ICO).
}
536 \twocolitem{{\bf wxBITMAP
\_TYPE\_CUR}}{Load a Windows cursor file (CUR).
}
537 \twocolitem{{\bf wxBITMAP
\_TYPE\_ANY}}{Will try to autodetect the format.
}
540 \docparam{mimetype
}{MIME type string (for example 'image/jpeg')
}
542 \docparam{index
}{Index of the image to load in the case that the image file contains multiple images.
543 This is only used by ICO and TIFF handlers. The default value (-
1) means
544 "choose the default image" and is interpreted as the first image (index=
0) by
545 the TIFF handler and as the largest and most colourful one by the ICO handler.
}
549 Depending on how wxWindows has been configured, not all formats may be available.
551 Note: you can use
\helpref{GetOptionInt
}{wximagegetoptionint
} to get the
552 hotspot for loaded cursor file:
554 int hotspot_x = image.GetOptionInt(wxCUR_HOTSPOT_X);
555 int hotspot_y = image.GetOptionInt(wxCUR_HOTSPOT_Y);
559 \wxheading{Return value
}
561 TRUE if the operation succeeded, FALSE otherwise.
565 \helpref{wxImage::SaveFile
}{wximagesavefile
}
567 \pythonnote{In place of a single overloaded method name, wxPython
568 implements the following methods:
\par
569 \indented{2cm
}{\begin{twocollist
}
570 \twocolitem{{\bf LoadFile(filename, type)
}}{Loads an image of the given
572 \twocolitem{{\bf LoadMimeFile(filename, mimetype)
}}{Loads an image of the given
573 mimetype from a file
}
577 \perlnote{Methods supported by wxPerl are:
\par
579 \item{bitmap->LoadFile( name, type )
}
580 \item{bitmap->LoadFile( name, mimetype )
}
585 \membersection{wxImage::Ok
}\label{wximageok
}
587 \constfunc{bool
}{Ok
}{\void}
589 Returns TRUE if image data is present.
591 \membersection{wxImage::RemoveHandler
}
593 \func{static bool
}{RemoveHandler
}{\param{const wxString\&
}{name
}}
595 Finds the handler with the given name, and removes it. The handler
598 \docparam{name
}{The handler name.
}
600 \wxheading{Return value
}
602 TRUE if the handler was found and removed, FALSE otherwise.
606 \helpref{wxImageHandler
}{wximagehandler
}
608 \membersection{wxImage::SaveFile
}\label{wximagesavefile
}
610 \func{bool
}{SaveFile
}{\param{const wxString\&
}{name
},
\param{int
}{ type
}}
612 \func{bool
}{SaveFile
}{\param{const wxString\&
}{name
},
\param{const wxString\&
}{ mimetype
}}
614 Saves a image in the named file.
616 \func{bool
}{SaveFile
}{\param{wxOutputStream\&
}{stream
},
\param{int
}{ type
}}
618 \func{bool
}{SaveFile
}{\param{wxOutputStream\&
}{stream
},
\param{const wxString\&
}{ mimetype
}}
620 Saves a image in the given stream.
622 \wxheading{Parameters
}
624 \docparam{name
}{Name of the file to save the image to.
}
626 \docparam{stream
}{Opened output stream to save the image to.
}
628 \docparam{type
}{Currently three types can be used:
632 \twocolitem{{\bf wxBITMAP
\_TYPE\_JPEG}}{Save a JPEG image file.
}
633 \twocolitem{{\bf wxBITMAP
\_TYPE\_PNG}}{Save a PNG image file.
}
634 \twocolitem{{\bf wxBITMAP
\_TYPE\_PCX}}{Save a PCX image file (tries to save as
8-bit if possible, falls back to
24-bit otherwise).
}
635 \twocolitem{{\bf wxBITMAP
\_TYPE\_PNM}}{Save a PNM image file (as raw RGB always).
}
636 \twocolitem{{\bf wxBITMAP
\_TYPE\_TIFF}}{Save a TIFF image file.
}
637 \twocolitem{{\bf wxBITMAP
\_TYPE\_XPM}}{Save a XPM image file.
}
638 \twocolitem{{\bf wxBITMAP
\_TYPE\_ICO}}{Save a ICO image file.
}
639 \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).
}
640 \twocolitem{{\bf wxBITMAP
\_TYPE\_CUR}}{Save a Windows cursor file (CUR).
}
643 \docparam{mimetype
}{MIME type.
}
645 \wxheading{Return value
}
647 TRUE if the operation succeeded, FALSE otherwise.
651 Depending on how wxWindows has been configured, not all formats may be available.
653 Note: you can use
\helpref{GetOptionInt
}{wximagegetoptionint
} to set the
654 hotspot before saving an image into a cursor file (default hotspot is in
655 the centre of the image):
657 image.SetOption(wxCUR_HOTSPOT_X, hotspotX);
658 image.SetOption(wxCUR_HOTSPOT_Y, hotspotY);
664 \helpref{wxImage::LoadFile
}{wximageloadfile
}
666 \pythonnote{In place of a single overloaded method name, wxPython
667 implements the following methods:
\par
668 \indented{2cm
}{\begin{twocollist
}
669 \twocolitem{{\bf SaveFile(filename, type)
}}{Saves the image using the given
670 type to the named file
}
671 \twocolitem{{\bf SaveMimeFile(filename, mimetype)
}}{Saves the image using the given
672 mimetype to the named file
}
676 \perlnote{Methods supported by wxPerl are:
\par
678 \item{bitmap->SaveFile( name, type )
}
679 \item{bitmap->SaveFile( name, mimetype )
}
683 \membersection{wxImage::Mirror
}\label{wximagemirror
}
685 \constfunc{wxImage
}{Mirror
}{\param{bool
}{ horizontally = TRUE
}}
687 Returns a mirrored copy of the image. The parameter
{\it horizontally
}
688 indicates the orientation.
690 \membersection{wxImage::Replace
}\label{wximagereplace
}
692 \func{void
}{Replace
}{\param{unsigned char
}{ r1
},
\param{unsigned char
}{ g1
},
\param{unsigned char
}{ b1
},
693 \param{unsigned char
}{ r2
},
\param{unsigned char
}{ g2
},
\param{unsigned char
}{ b2
}}
695 Replaces the colour specified by
{\it r1,g1,b1
} by the colour
{\it r2,g2,b2
}.
697 \membersection{wxImage::Rescale
}\label{wximagerescale
}
699 \func{wxImage \&
}{Rescale
}{\param{int
}{ width
},
\param{int
}{ height
}}
701 Changes the size of the image in-place: after a call to this function, the
702 image will have the given width and height.
704 Returns the (modified) image itself.
708 \helpref{Scale
}{wximagescale
}
710 \membersection{wxImage::Rotate
}\label{wximagerotate
}
712 \func{wxImage
}{Rotate
}{\param{double
}{ angle
},
\param{const wxPoint\&
}{rotationCentre
},
713 \param{bool
}{ interpolating = TRUE
},
\param{wxPoint*
}{ offsetAfterRotation = NULL
}}
715 Rotates the image about the given point, by
{\it angle
} radians. Passing TRUE
716 to
{\it interpolating
} results in better image quality, but is slower. If the
717 image has a mask, then the mask colour is used for the uncovered pixels in the
718 rotated image background. Else, black (rgb
0,
0,
0) will be used.
720 Returns the rotated image, leaving this image intact.
722 \membersection{wxImage::Rotate90
}\label{wximagerotate90
}
724 \constfunc{wxImage
}{Rotate90
}{\param{bool
}{ clockwise = TRUE
}}
726 Returns a copy of the image rotated
90 degrees in the direction
727 indicated by
{\it clockwise
}.
729 \membersection{wxImage::Scale
}\label{wximagescale
}
731 \constfunc{wxImage
}{Scale
}{\param{int
}{ width
},
\param{int
}{ height
}}
733 Returns a scaled version of the image. This is also useful for
734 scaling bitmaps in general as the only other way to scale bitmaps
735 is to blit a wxMemoryDC into another wxMemoryDC.
737 It may be mentioned that the GTK port uses this function internally
738 to scale bitmaps when using mapping modes in wxDC.
743 // get the bitmap from somewhere
746 // rescale it to have size of
32*
32
747 if ( bmp.GetWidth() !=
32 || bmp.GetHeight() !=
32 )
750 bmp = wxBitmap(image.Scale(
32,
32));
752 // another possibility:
753 image.Rescale(
32,
32);
761 \helpref{Rescale
}{wximagerescale
}
763 \membersection{wxImage::SetData
}\label{wximagesetdata
}
765 \func{void
}{SetData
}{\param{unsigned char*
}{data
}}
767 Sets the image data without performing checks. The data given must have
768 the size (width*height*
3) or results will be unexpected. Don't use this
769 method if you aren't sure you know what you are doing.
771 \membersection{wxImage::SetMask
}\label{wximagesetmask
}
773 \func{void
}{SetMask
}{\param{bool
}{ hasMask = TRUE
}}
775 Specifies whether there is a mask or not. The area of the mask is determined by the current mask colour.
777 \membersection{wxImage::SetMaskColour
}\label{wximagesetmaskcolour
}
779 \func{void
}{SetMaskColour
}{\param{unsigned char
}{red
},
\param{unsigned char
}{blue
},
\param{unsigned char
}{green
}}
781 Sets the mask colour for this image (and tells the image to use the mask).
783 \membersection{wxImage::SetMaskFromImage
}\label{wximagesetmaskfromimage
}
785 \func{bool
}{SetMaskFromImage
}{\param{const wxImage\&
}{ mask
},
\param{unsigned char
}{ mr
},
\param{unsigned char
}{ mg
},
\param{unsigned char
}{ mb
}}
787 \wxheading{Parameters
}
789 \docparam{mask
}{The mask image to extract mask shape from. Must have same dimensions as the image.
}
791 \docparam{mr,mg,mb
}{RGB value of pixels in
{\it mask
} that will be used to create the mask.
}
793 Sets image's mask so that the pixels that have RGB value of
{\it mr,mg,mb
}
794 in
{\it mask
} will be masked in the image. This is done by first finding an
795 unused colour in the image, setting this colour as the mask colour and then
796 using this colour to draw all pixels in the image who corresponding pixel
797 in
{\it mask
} has given RGB value.
799 \wxheading{Return value
}
801 Returns FALSE if
{\it mask
} does not have same dimensions as the image or if
802 there is no unused colour left. Returns TRUE if the mask was successfully
807 Note that this method involves computing the histogram, which is
808 computationally intensive operation.
810 \membersection{wxImage::SetOption
}\label{wximagesetoption
}
812 \func{void
}{SetOption
}{\param{const wxString\&
}{ name
},
\param{const wxString\&
}{ value
}}
814 \func{void
}{SetOption
}{\param{const wxString\&
}{ name
},
\param{int
}{ value
}}
816 Sets a user-defined option. The function is case-insensitive to
{\it name
}.
818 For example, when saving as a JPEG file, the option
{\bf quality
} is
819 used, which is a number between
0 and
100 (
0 is terrible,
100 is very good).
823 \helpref{wxImage::GetOption
}{wximagegetoption
},
\rtfsp
824 \helpref{wxImage::GetOptionInt
}{wximagegetoptionint
},
\rtfsp
825 \helpref{wxImage::HasOption
}{wximagehasoption
}
827 \membersection{wxImage::SetPalette
}\label{wximagesetpalette
}
829 \func{void
}{SetPalette
}{\param{const wxPalette\&
}{ palette
}}
831 Associates a palette with the image. The palette may be used when converting
832 wxImage to wxBitmap (MSW only at present) or in file save operations (none as yet).
834 \membersection{wxImage::SetRGB
}\label{wximagesetrgb
}
836 \func{void
}{SetRGB
}{\param{int
}{x
},
\param{int
}{y
},
\param{unsigned char
}{red
},
\param{unsigned char
}{green
},
\param{unsigned char
}{blue
}}
838 Sets the pixel at the given coordinate. This routine performs bounds-checks
839 for the coordinate so it can be considered a safe way to manipulate the
840 data, but in some cases this might be too slow so that the data will have to
841 be set directly. In that case you will have to get access to the image data
842 using the
\helpref{GetData
}{wximagegetdata
} method.
844 \membersection{wxImage::operator $=$
}
846 \func{wxImage\&
}{operator $=$
}{\param{const wxImage\&
}{image
}}
848 Assignment operator. This operator does not copy any data, but instead
849 passes a pointer to the data in
{\it image
} and increments a reference
850 counter. It is a fast operation.
852 \wxheading{Parameters
}
854 \docparam{image
}{Image to assign.
}
856 \wxheading{Return value
}
858 Returns 'this' object.
860 \membersection{wxImage::operator $==$
}
862 \func{bool
}{operator $==$
}{\param{const wxImage\&
}{image
}}
864 Equality operator. This operator tests whether the internal data pointers are
867 \wxheading{Parameters
}
869 \docparam{image
}{Image to compare with 'this'
}
871 \wxheading{Return value
}
873 Returns TRUE if the images were effectively equal, FALSE otherwise.
875 \membersection{wxImage::operator $!=$
}
877 \func{bool
}{operator $!=$
}{\param{const wxImage\&
}{image
}}
879 Inequality operator. This operator tests whether the internal data pointers are
880 unequal (a fast test).
882 \wxheading{Parameters
}
884 \docparam{image
}{Image to compare with 'this'
}
886 \wxheading{Return value
}
888 Returns TRUE if the images were unequal, FALSE otherwise.
890 \section{\class{wxImageHandler
}}\label{wximagehandler
}
892 This is the base class for implementing image file loading/saving, and image creation from data.
893 It is used within wxImage and is not normally seen by the application.
895 If you wish to extend the capabilities of wxImage, derive a class from wxImageHandler
896 and add the handler using
\helpref{wxImage::AddHandler
}{wximageaddhandler
} in your
897 application initialisation.
899 \wxheading{Note (Legal Issue)
}
901 This software is based in part on the work of the Independent JPEG Group.
903 (Applies when wxWindows is linked with JPEG support. wxJPEGHandler uses libjpeg
906 \wxheading{Derived from
}
908 \helpref{wxObject
}{wxobject
}
910 \wxheading{Include files
}
916 \helpref{wxImage
}{wximage
},
917 \helpref{wxInitAllImageHandlers
}{wxinitallimagehandlers
}
919 \latexignore{\rtfignore{\wxheading{Members
}}}
921 \membersection{wxImageHandler::wxImageHandler
}\label{wximagehandlerconstr
}
923 \func{}{wxImageHandler
}{\void}
925 Default constructor. In your own default constructor, initialise the members
926 m
\_name, m
\_extension and m
\_type.
928 \membersection{wxImageHandler::
\destruct{wxImageHandler
}}
930 \func{}{\destruct{wxImageHandler
}}{\void}
932 Destroys the wxImageHandler object.
934 \membersection{wxImageHandler::GetName
}
936 \constfunc{wxString
}{GetName
}{\void}
938 Gets the name of this handler.
940 \membersection{wxImageHandler::GetExtension
}
942 \constfunc{wxString
}{GetExtension
}{\void}
944 Gets the file extension associated with this handler.
946 \membersection{wxImageHandler::GetImageCount
}\label{wximagehandlergetimagecount
}
948 \func{int
}{GetImageCount
}{\param{wxInputStream\&
}{ stream
}}
950 If the image file contains more than one image and the image handler is capable
951 of retrieving these individually, this function will return the number of
954 \docparam{stream
}{Opened input stream for reading image data. Currently, the stream must support seeking.
}
956 \wxheading{Return value
}
958 Number of available images. For most image handlers, this is
1 (exceptions
959 are TIFF and ICO formats).
961 \membersection{wxImageHandler::GetType
}
963 \constfunc{long
}{GetType
}{\void}
965 Gets the image type associated with this handler.
967 \membersection{wxImageHandler::GetMimeType
}
969 \constfunc{wxString
}{GetMimeType
}{\void}
971 Gets the MIME type associated with this handler.
973 \membersection{wxImageHandler::LoadFile
}\label{wximagehandlerloadfile
}
975 \func{bool
}{LoadFile
}{\param{wxImage*
}{image
},
\param{wxInputStream\&
}{ stream
},
\param{bool
}{ verbose=TRUE
},
\param{int
}{ index=
0}}
977 Loads a image from a stream, putting the resulting data into
{\it image
}. If the image file contains
978 more than one image and the image handler is capable of retrieving these individually,
{\it index
}
979 indicates which image to read from the stream.
981 \wxheading{Parameters
}
983 \docparam{image
}{The image object which is to be affected by this operation.
}
985 \docparam{stream
}{Opened input stream for reading image data.
}
987 \docparam{verbose
}{If set to TRUE, errors reported by the image handler will produce wxLogMessages.
}
989 \docparam{index
}{The index of the image in the file (starting from zero).
}
991 \wxheading{Return value
}
993 TRUE if the operation succeeded, FALSE otherwise.
997 \helpref{wxImage::LoadFile
}{wximageloadfile
},
998 \helpref{wxImage::SaveFile
}{wximagesavefile
},
999 \helpref{wxImageHandler::SaveFile
}{wximagehandlersavefile
}
1001 \membersection{wxImageHandler::SaveFile
}\label{wximagehandlersavefile
}
1003 \func{bool
}{SaveFile
}{\param{wxImage*
}{image
},
\param{wxOutputStream\&
}{stream
}}
1005 Saves a image in the output stream.
1007 \wxheading{Parameters
}
1009 \docparam{image
}{The image object which is to be affected by this operation.
}
1011 \docparam{stream
}{Opened output stream for writing the data.
}
1013 \wxheading{Return value
}
1015 TRUE if the operation succeeded, FALSE otherwise.
1017 \wxheading{See also
}
1019 \helpref{wxImage::LoadFile
}{wximageloadfile
},
1020 \helpref{wxImage::SaveFile
}{wximagesavefile
},
1021 \helpref{wxImageHandler::LoadFile
}{wximagehandlerloadfile
}
1023 \membersection{wxImageHandler::SetName
}
1025 \func{void
}{SetName
}{\param{const wxString\&
}{name
}}
1027 Sets the handler name.
1029 \wxheading{Parameters
}
1031 \docparam{name
}{Handler name.
}
1033 \membersection{wxImageHandler::SetExtension
}
1035 \func{void
}{SetExtension
}{\param{const wxString\&
}{extension
}}
1037 Sets the handler extension.
1039 \wxheading{Parameters
}
1041 \docparam{extension
}{Handler extension.
}
1043 \membersection{wxImageHandler::SetMimeType
}\label{wximagehandlersetmimetype
}
1045 \func{void
}{SetMimeType
}{\param{const wxString\&
}{mimetype
}}
1047 Sets the handler MIME type.
1049 \wxheading{Parameters
}
1051 \docparam{mimename
}{Handler MIME type.
}
1053 \membersection{wxImageHandler::SetType
}
1055 \func{void
}{SetType
}{\param{long
}{type
}}
1057 Sets the handler type.
1059 \wxheading{Parameters
}
1061 \docparam{name
}{Handler type.
}