1 \section{\class{wxImage
}}\label{wximage
}
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.
9 A wxImage cannot (currently) be drawn directly to a wxDC. Instead, a platform-specific
10 wxBitmap object must be created from it, and that bitmap drawn on the wxDC, using
13 \wxheading{Derived from
}
15 \helpref{wxObject
}{wxobject
}
17 \wxheading{Include files
}
23 \helpref{wxBitmap
}{wxbitmap
}
25 \latexignore{\rtfignore{\wxheading{Members
}}}
27 \membersection{wxImage::wxImage
}\label{wximageconstr
}
29 \func{}{wxImage
}{\void}
33 \func{}{wxImage
}{\param{const wxImage\&
}{image
}}
37 \func{}{wxImage
}{\param{const wxBitmap\&
}{ bitmap
}}
39 Constructs an image from a platform-dependent bitmap. This preserves
40 mask information so that bitmaps and images can be converted back
41 and forth without loss in that respect.
43 \func{}{wxImage
}{\param{int
}{ width
},
\param{int
}{ height
}}
45 Creates an image with the given width and height.
47 \func{}{wxImage
}{\param{const wxString\&
}{name
},
\param{long
}{ type = wxBITMAP
\_TYPE\_PNG}}
49 \func{}{wxImage
}{\param{const wxString\&
}{name
},
\param{const wxString\&
}{ mimetype
}}
51 Loads an image from a file.
53 \func{}{wxImage
}{\param{wxInputStream\&
}{stream
},
\param{long
}{ type = wxBITMAP
\_TYPE\_PNG}}
55 \func{}{wxImage
}{\param{wxInputStream\&
}{stream
},
\param{const wxString\&
}{ mimetype
}}
57 Loads an image from an input stream.
59 \wxheading{Parameters
}
61 \docparam{width
}{Specifies the width of the image.
}
63 \docparam{height
}{Specifies the height of the image.
}
65 \docparam{name
}{This refers to an image filename. Its meaning is determined by the
{\it type
} parameter.
}
67 \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).
}
69 \docparam{type
}{May be one of the following:
73 \twocolitem{{\bf \indexit{wxBITMAP
\_TYPE\_BMP}}}{Load a Windows bitmap file.
}
74 \twocolitem{{\bf \indexit{wxBITMAP
\_TYPE\_PNG}}}{Load a PNG bitmap file.
}
75 \twocolitem{{\bf \indexit{wxBITMAP
\_TYPE\_JPEG}}}{Load a JPEG bitmap file.
}
78 The validity of these flags depends on the platform and wxWindows configuration.
79 If all possible wxWindows settings are used, the loading a BMP (Windows bitmap) file,
80 a PNG (portable network graphics) file and a JPEG file is supported on all platforms that
83 \docparam{mimetype
}{MIME type string (for example 'image/jpeg')
}
85 Note : you must call wxImage::AddHandler(new wxJPEGHandler) during application
86 initialization in order to work with JPEGs.
90 \helpref{wxImage::LoadFile
}{wximageloadfile
}
92 \pythonnote{Constructors supported by wxPython are:
\par
93 \indented{2cm
}{\begin{twocollist
}
94 \twocolitem{\bf{wxImage(name, flag)
}}{Loads an image from a file
}
95 \twocolitem{\bf{wxNullImage()
}}{Create a null image (has no size or
97 \twocolitem{\bf{wxEmptyImage(width, height)
}}{Creates an empty image
99 \twocolitem{\bf{wxImageFromMime(name, mimetype
}}{Creates an image from
100 the given file of the given mimetype
}
101 \twocolitem{\bf{wxImageFromBitmap(bitmap)
}}{Creates an image from a
102 platform-dependent bitmap
}
106 \membersection{wxImage::
\destruct{wxImage
}}
108 \func{}{\destruct{wxImage
}}{\void}
112 \membersection{wxImage::AddHandler
}\label{wximageaddhandler
}
114 \func{static void
}{AddHandler
}{\param{wxImageHandler*
}{ handler
}}
116 Adds a handler to the end of the static list of format handlers.
118 \docparam{handler
}{A new image format handler object. There is usually only one instance
119 of a given handler class in an application session.
}
123 \helpref{wxImageHandler
}{wximagehandler
}
125 \pythonnote{In wxPython this static method is named
\tt{wxImage_AddHandler
}.
}
126 \membersection{wxImage::CleanUpHandlers
}
128 \func{static void
}{CleanUpHandlers
}{\void}
130 Deletes all image handlers.
132 This function is called by wxWindows on exit.
134 \membersection{wxImage::ConvertToBitmap
}\label{wximageconverttobitmap
}
136 \constfunc{wxBitmap
}{ConvertToBitmap
}{\void}
138 Converts the image to a platform-specific bitmap object. This has to be done
139 to actually display an image as you cannot draw an image directly on a window.
140 The resulting bitmap will use the colour depth of the current system which entails
141 that a (crude) colour reduction has to take place. When in
8-bit mode, this
142 routine will use a
color cube created on program start-up to look up colors.
143 Still, the image quality won't be perfect for photo images.
145 \membersection{wxImage::Create
}\label{wximagecreate
}
147 \func{bool
}{Create
}{\param{int
}{ width
},
\param{int
}{ height
}}
149 Creates a fresh image.
151 \wxheading{Parameters
}
153 \docparam{width
}{The width of the image in pixels.
}
155 \docparam{height
}{The height of the image in pixels.
}
157 \wxheading{Return value
}
159 TRUE if the call succeeded, FALSE otherwise.
161 \membersection{wxImage::Destroy
}\label{wximagedestroy
}
163 \func{bool
}{Destroy
}{\void}
165 Destroys the image data.
167 \membersection{wxImage::FindHandler
}
169 \func{static wxImageHandler*
}{FindHandler
}{\param{const wxString\&
}{name
}}
171 Finds the handler with the given name.
173 \func{static wxImageHandler*
}{FindHandler
}{\param{const wxString\&
}{extension
},
\param{long
}{ imageType
}}
175 Finds the handler associated with the given extension and type.
177 \func{static wxImageHandler*
}{FindHandler
}{\param{long
}{imageType
}}
179 Finds the handler associated with the given image type.
181 \func{static wxImageHandler*
}{FindHandlerMime
}{\param{const wxString\&
}{mimetype
}}
183 Finds the handler associated with the given MIME type.
185 \docparam{name
}{The handler name.
}
187 \docparam{extension
}{The file extension, such as ``bmp".
}
189 \docparam{imageType
}{The image type, such as wxBITMAP
\_TYPE\_BMP.
}
191 \docparam{mimetype
}{MIME type.
}
193 \wxheading{Return value
}
195 A pointer to the handler if found, NULL otherwise.
199 \helpref{wxImageHandler
}{wximagehandler
}
201 \membersection{wxImage::GetBlue
}\label{wximagegetblue
}
203 \constfunc{unsigned char
}{GetBlue
}{\param{int
}{ x
},
\param{int
}{ y
}}
205 Returns the blue intensity at the given coordinate.
207 \membersection{wxImage::GetData
}\label{wximagegetdata
}
209 \constfunc{unsigned char*
}{GetData
}{\void}
211 Returns the image data as an array. This is most often used when doing
212 direct image manipulation. The return value points to an array of
213 chararcters in RGBGBRGB... format.
215 \membersection{wxImage::GetGreen
}\label{wximagegetgreen
}
217 \constfunc{unsigned char
}{GetGreen
}{\param{int
}{ x
},
\param{int
}{ y
}}
219 Returns the green intensity at the given coordinate.
221 \membersection{wxImage::GetRed
}\label{wximagegetred
}
223 \constfunc{unsigned char
}{GetRed
}{\param{int
}{ x
},
\param{int
}{ y
}}
225 Returns the red intensity at the given coordinate.
227 \membersection{wxImage::GetHandlers
}
229 \func{static wxList\&
}{GetHandlers
}{\void}
231 Returns the static list of image format handlers.
235 \helpref{wxImageHandler
}{wximagehandler
}
237 \membersection{wxImage::GetHeight
}\label{wximagegetheight
}
239 \constfunc{int
}{GetHeight
}{\void}
241 Gets the height of the image in pixels.
243 \membersection{wxImage::GetMaskBlue
}\label{wximagegetmaskblue
}
245 \constfunc{unsigned char
}{GetMaskBlue
}{\void}
247 Gets the blue value of the mask colour.
249 \membersection{wxImage::GetMaskGreen
}\label{wximagegetmaskgreen
}
251 \constfunc{unsigned char
}{GetMaskGreen
}{\void}
253 Gets the green value of the mask colour.
255 \membersection{wxImage::GetMaskRed
}\label{wximagegetmaskred
}
257 \constfunc{unsigned char
}{GetMaskRed
}{\void}
259 Gets the red value of the mask colour.
261 \membersection{wxImage::GetWidth
}\label{wximagegetwidth
}
263 \constfunc{int
}{GetWidth
}{\void}
265 Gets the width of the image in pixels.
269 \helpref{wxImage::GetHeight
}{wximagegetheight
}
271 \membersection{wxImage::HasMask
}\label{wximagehasmask
}
273 \constfunc{bool
}{HasMask
}{\void}
275 Returns TRUE if there is a mask active, FALSE otherwise.
277 \membersection{wxImage::InitAllHandlers
}\label{wximageinitallhandlers
}
279 \func{static void
}{InitAllHandlers
}{\void}
281 Adds some common image format handlers, which, depending on wxWindows
282 configuration, can be handlers for BMP (loading) (always installed), GIF
283 (loading and saving), PCX (loading and saving), PNM (loading and saving as raw
284 rgb), PNG (loading and saving), JPEG (loading and saving), file formats.
288 \helpref{wxImageHandler
}{wximagehandler
}
290 \membersection{wxImage::InitStandardHandlers
}
292 \func{static void
}{InitStandardHandlers
}{\void}
294 Internal use only. Adds standard image format handlers. It only install BMP
295 for the time being, which is use by wxBitmap.
297 This function is called by wxWindows on startup, and shouldn't be called by
302 \helpref{wxImageHandler
}{wximagehandler
}
303 \helpref{wxImage::InitAllHandlers
}{wximageinitallhandlers
}
305 \membersection{wxImage::InsertHandler
}
307 \func{static void
}{InsertHandler
}{\param{wxImageHandler*
}{ handler
}}
309 Adds a handler at the start of the static list of format handlers.
311 \docparam{handler
}{A new image format handler object. There is usually only one instance
312 of a given handler class in an application session.
}
316 \helpref{wxImageHandler
}{wximagehandler
}
318 \membersection{wxImage::LoadFile
}\label{wximageloadfile
}
320 \func{bool
}{LoadFile
}{\param{const wxString\&
}{ name
},
\param{long
}{ type = wxBITMAP
\_TYPE\_ANY}}
322 \func{bool
}{LoadFile
}{\param{const wxString\&
}{ name
},
\param{const wxString\&
}{ mimetype
}}
324 Loads an image from a file. If no handler type is provided, the library will
325 try to use wxBITMAP
\_TYPE\_BMP or all known handlers previously installed
326 through a call to
\helpref{wxImage::InitAllHandlers
}{wximageinitallhandlers
}.
328 \func{bool
}{LoadFile
}{\param{wxInputStream\&
}{ stream
},
\param{long
}{ type
}}
330 \func{bool
}{LoadFile
}{\param{wxInputStream\&
}{ stream
},
\param{const wxString\&
}{ mimetype
}}
332 Loads an image from an input stream.
334 \wxheading{Parameters
}
336 \docparam{name
}{A filename.
337 The meaning of
{\it name
} is determined by the
{\it type
} parameter.
}
339 \docparam{stream
}{An input stream.
340 The meaning of
{\it stream
} data is determined by the
{\it type
} parameter.
}
342 \docparam{type
}{One of the following values:
346 \twocolitem{{\bf wxBITMAP
\_TYPE\_BMP}}{Load a Windows image file.
}
347 \twocolitem{{\bf wxBITMAP
\_TYPE\_GIF}}{Load a GIF image file.
}
348 \twocolitem{{\bf wxBITMAP
\_TYPE\_JPEG}}{Load a JPEG image file.
}
349 \twocolitem{{\bf wxBITMAP
\_TYPE\_PCX}}{Load a PCX image file.
}
350 \twocolitem{{\bf wxBITMAP
\_TYPE\_PNG}}{Load a PNG image file.
}
351 \twocolitem{{\bf wxBITMAP
\_TYPE\_PNM}}{Load a PNM image file.
}
354 The validity of these flags depends on the platform and wxWindows configuration.
}
356 \docparam{mimetype
}{MIME type string (for example 'image/jpeg')
}
358 \wxheading{Return value
}
360 TRUE if the operation succeeded, FALSE otherwise.
364 \helpref{wxImage::SaveFile
}{wximagesavefile
}
366 \pythonnote{In place of a single overloaded method name, wxPython
367 implements the following methods:
\par
368 \indented{2cm
}{\begin{twocollist
}
369 \twocolitem{\bf{LoadFile(filename, type)
}}{Loads an image of the given
371 \twocolitem{\bf{LoadMimeFile(filename, mimetype)
}}{Loads an image of the given
372 mimetype from a file
}
377 \membersection{wxImage::Ok
}\label{wximageok
}
379 \constfunc{bool
}{Ok
}{\void}
381 Returns TRUE if image data is present.
383 \membersection{wxImage::RemoveHandler
}
385 \func{static bool
}{RemoveHandler
}{\param{const wxString\&
}{name
}}
387 Finds the handler with the given name, and removes it. The handler
390 \docparam{name
}{The handler name.
}
392 \wxheading{Return value
}
394 TRUE if the handler was found and removed, FALSE otherwise.
398 \helpref{wxImageHandler
}{wximagehandler
}
400 \membersection{wxImage::SaveFile
}\label{wximagesavefile
}
402 \func{bool
}{SaveFile
}{\param{const wxString\&
}{name
},
\param{int
}{ type
}}
404 \func{bool
}{SaveFile
}{\param{const wxString\&
}{name
},
\param{const wxString\&
}{ mimetype
}}
406 Saves a image in the named file.
408 \func{bool
}{SaveFile
}{\param{wxOutputStream\&
}{stream
},
\param{int
}{ type
}}
410 \func{bool
}{SaveFile
}{\param{wxOutputStream\&
}{stream
},
\param{const wxString\&
}{ mimetype
}}
412 Saves a image in the given stream.
414 \wxheading{Parameters
}
416 \docparam{name
}{A filename. The meaning of
{\it name
} is determined by the
{\it type
} parameter.
}
418 \docparam{stream
}{An output stream. The meaning of
{\it stream
} is determined by the
{\it type
} parameter.
}
420 \docparam{type
}{Currently two types can be used:
424 \twocolitem{{\bf wxBITMAP
\_TYPE\_PNG}}{Save a PNG image file.
}
425 \twocolitem{{\bf wxBITMAP
\_TYPE\_JPEG}}{Save a JPEG image file.
}
428 The validity of these flags depends on the platform and wxWindows configuration
429 as well as user-added handlers.
}
431 \docparam{mimetype
}{MIME type.
}
433 \wxheading{Return value
}
435 TRUE if the operation succeeded, FALSE otherwise.
439 Depending on how wxWindows has been configured, not all formats may be available.
443 \helpref{wxImage::LoadFile
}{wximageloadfile
}
445 \pythonnote{In place of a single overloaded method name, wxPython
446 implements the following methods:
\par
447 \indented{2cm
}{\begin{twocollist
}
448 \twocolitem{\bf{SaveFile(filename, type)
}}{Saves the image using the given
449 type to the named file
}
450 \twocolitem{\bf{SaveMimeFile(filename, mimetype)
}}{Saves the image using the given
451 mimetype to the named file
}
455 \membersection{wxImage::Rescale
}\label{wximagerescale
}
457 \func{wxImage
}{Rescale
}{\param{int
}{ width
},
\param{int
}{ height
}}
459 Changes the size of the image in-place: after a call to this function, the
460 image will have the given width and height.
464 \helpref{Scale
}{wximagescale
}
466 \membersection{wxImage::Scale
}\label{wximagescale
}
468 \constfunc{wxImage
}{Scale
}{\param{int
}{ width
},
\param{int
}{ height
}}
470 Returns a scaled version of the image. This is also useful for
471 scaling bitmaps in general as the only other way to scale bitmaps
472 is to blit a wxMemoryDC into another wxMemoryDC.
474 NB: although Windows can do such scaling itself but in the GTK port, scaling
475 bitmaps is done using this routine internally.
480 // get the bitmap from somewhere
483 // rescale it to have size of
32*
32
484 if ( bmp.GetWidth() !=
32 || bmp.GetHeight() !=
32 )
487 bmp = image.Scale(
32,
32).ConvertToBitmap();
489 // another possibility:
490 image.Rescale(
32,
32);
498 \helpref{Rescale
}{wximagerescale
}
500 \membersection{wxImage::GetSubImage
}\label{wximagegetsubimage
}
502 \constfunc{wxImage
}{GetSubImage
}{\param{const wxRect&
}{rect
}}
504 Returns a sub image of the current one as long as the rect belongs entirely to
507 \membersection{wxImage::SetData
}\label{wximagesetdata
}
509 \func{void
}{SetData
}{\param{unsigned char*
}{data
}}
511 Sets the image data without performing checks. The data given must have
512 the size (width*height*
3) or results will be unexpected. Don't use this
513 method if you aren't sure you know what you are doing.
515 \membersection{wxImage::SetMask
}\label{wximagesetmask
}
517 \func{void
}{SetMask
}{\param{bool
}{ hasMask = TRUE
}}
519 Specifies whether there is a mask or not. The area of the mask is determined by the current mask colour.
521 \membersection{wxImage::SetMaskColour
}\label{wximagesetmaskcolour
}
523 \func{void
}{SetMaskColour
}{\param{unsigned char
}{red
},
\param{unsigned char
}{blue
},
\param{unsigned char
}{green
}}
525 Sets the mask colour for this image (and tells the image to use the mask).
527 \membersection{wxImage::SetRGB
}\label{wximagesetrgb
}
529 \func{void
}{SetRGB
}{\param{int
}{x
},
\param{int
}{y
},
\param{unsigned char
}{red
},
\param{unsigned char
}{blue
},
\param{unsigned char
}{green
}}
531 Sets the pixel at the given coordinate. This routine performs bounds-checks
532 for the coordinate so it can be considered a safe way to manipulate the
533 data, but in some cases this might be too slow so that the data will have to
534 be set directly. In that case you have to get that data by calling GetData().
536 \membersection{wxImage::operator $=$
}
538 \func{wxImage\&
}{operator $=$
}{\param{const wxImage\&
}{image
}}
540 Assignment operator. This operator does not copy any data, but instead
541 passes a pointer to the data in
{\it image
} and increments a reference
542 counter. It is a fast operation.
544 \wxheading{Parameters
}
546 \docparam{image
}{Image to assign.
}
548 \wxheading{Return value
}
550 Returns 'this' object.
552 \membersection{wxImage::operator $==$
}
554 \func{bool
}{operator $==$
}{\param{const wxImage\&
}{image
}}
556 Equality operator. This operator tests whether the internal data pointers are
559 \wxheading{Parameters
}
561 \docparam{image
}{Image to compare with 'this'
}
563 \wxheading{Return value
}
565 Returns TRUE if the images were effectively equal, FALSE otherwise.
567 \membersection{wxImage::operator $!=$
}
569 \func{bool
}{operator $!=$
}{\param{const wxImage\&
}{image
}}
571 Inequality operator. This operator tests whether the internal data pointers are
572 unequal (a fast test).
574 \wxheading{Parameters
}
576 \docparam{image
}{Image to compare with 'this'
}
578 \wxheading{Return value
}
580 Returns TRUE if the images were unequal, FALSE otherwise.
582 \section{\class{wxImageHandler
}}\label{wximagehandler
}
584 This is the base class for implementing image file loading/saving, and image creation from data.
585 It is used within wxImage and is not normally seen by the application.
587 If you wish to extend the capabilities of wxImage, derive a class from wxImageHandler
588 and add the handler using
\helpref{wxImage::AddHandler
}{wximageaddhandler
} in your
589 application initialisation.
591 \wxheading{Note (Legal Issue)
}
593 This software is based in part on the work of the Independent JPEG Group.
595 (Applies when wxWindows is linked with JPEG support. wxJPEGHandler uses libjpeg
598 \wxheading{Derived from
}
600 \helpref{wxObject
}{wxobject
}
602 \wxheading{Include files
}
608 \helpref{wxImage
}{wximage
}
610 \latexignore{\rtfignore{\wxheading{Members
}}}
612 \membersection{wxImageHandler::wxImageHandler
}\label{wximagehandlerconstr
}
614 \func{}{wxImageHandler
}{\void}
616 Default constructor. In your own default constructor, initialise the members
617 m
\_name, m
\_extension and m
\_type.
619 \membersection{wxImageHandler::
\destruct{wxImageHandler
}}
621 \func{}{\destruct{wxImageHandler
}}{\void}
623 Destroys the wxImageHandler object.
625 \membersection{wxImageHandler::GetName
}
627 \constfunc{wxString
}{GetName
}{\void}
629 Gets the name of this handler.
631 \membersection{wxImageHandler::GetExtension
}
633 \constfunc{wxString
}{GetExtension
}{\void}
635 Gets the file extension associated with this handler.
637 \membersection{wxImageHandler::GetType
}
639 \constfunc{long
}{GetType
}{\void}
641 Gets the image type associated with this handler.
643 \membersection{wxImageHandler::GetMimeType
}
645 \constfunc{wxString
}{GetMimeType
}{\void}
647 Gets the MIME type associated with this handler.
649 \membersection{wxImageHandler::LoadFile
}\label{wximagehandlerloadfile
}
651 \func{bool
}{LoadFile
}{\param{wxImage*
}{image
},
\param{wxInputStream\&
}{ stream
}}
653 Loads a image from a stream, putting the resulting data into
{\it image
}.
655 \wxheading{Parameters
}
657 \docparam{image
}{The image object which is to be affected by this operation.
}
659 \docparam{stream
}{Opened input stream.
660 The meaning of
{\it stream
} is determined by the
{\it type
} parameter.
}
662 \wxheading{Return value
}
664 TRUE if the operation succeeded, FALSE otherwise.
668 \helpref{wxImage::LoadFile
}{wximageloadfile
}\\
669 \helpref{wxImage::SaveFile
}{wximagesavefile
}\\
670 \helpref{wxImageHandler::SaveFile
}{wximagehandlersavefile
}
672 \membersection{wxImageHandler::SaveFile
}\label{wximagehandlersavefile
}
674 \func{bool
}{SaveFile
}{\param{wxImage*
}{image
},
\param{wxOutputStream\&
}{stream
}}
676 Saves a image in the output stream.
678 \wxheading{Parameters
}
680 \docparam{image
}{The image object which is to be affected by this operation.
}
682 \docparam{stream
}{A stream. The meaning of
{\it stream
} is determined by the
{\it type
} parameter.
}
684 \wxheading{Return value
}
686 TRUE if the operation succeeded, FALSE otherwise.
690 \helpref{wxImage::LoadFile
}{wximageloadfile
}\\
691 \helpref{wxImage::SaveFile
}{wximagesavefile
}\\
692 \helpref{wxImageHandler::LoadFile
}{wximagehandlerloadfile
}
694 \membersection{wxImageHandler::SetName
}
696 \func{void
}{SetName
}{\param{const wxString\&
}{name
}}
698 Sets the handler name.
700 \wxheading{Parameters
}
702 \docparam{name
}{Handler name.
}
704 \membersection{wxImageHandler::SetExtension
}
706 \func{void
}{SetExtension
}{\param{const wxString\&
}{extension
}}
708 Sets the handler extension.
710 \wxheading{Parameters
}
712 \docparam{extension
}{Handler extension.
}
714 \membersection{wxImageHandler::SetType
}
716 \func{void
}{SetType
}{\param{long
}{type
}}
718 Sets the handler type.
720 \wxheading{Parameters
}
722 \docparam{name
}{Handler type.
}
725 \membersection{wxImageHandler::SetMimeType
}
727 \func{void
}{SetMimeType
}{\param{const wxString\&
}{mimetype
}}
729 Sets the handler MIME type.
731 \wxheading{Parameters
}
733 \docparam{mimename
}{Handler MIME type.
}