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 This class is currently only available under GTK and Windows.
15 \wxheading{Derived from
}
17 \helpref{wxObject
}{wxobject
}
21 \helpref{wxBitmap
}{wxbitmap
}
23 \latexignore{\rtfignore{\wxheading{Members
}}}
25 \membersection{wxImage::wxImage
}\label{wximageconstr
}
27 \func{}{wxImage
}{\void}
31 \func{}{wxImage
}{\param{const wxImage\&
}{image
}}
35 \func{}{wxImage
}{\param{const wxBitmap\&
}{ bitmap
}}
37 Constructs an image from a platform-dependent bitmap. This preserves
38 mask information so that bitmaps and images can be converted back
39 and forth without loss in that respect.
41 \func{}{wxImage
}{\param{int
}{ width
},
\param{int
}{ height
}}
43 Creates an image with the given width and height.
45 \func{}{wxImage
}{\param{const wxString\&
}{name
},
\param{long
}{ type = wxBITMAP
\_TYPE\_PNG}}
47 Loads an image from a file.
49 \func{}{wxImage
}{\param{wxInputStream\&
}{stream
},
\param{long
}{ type = wxBITMAP
\_TYPE\_PNG}}
51 Loads an image from an input stream.
53 \wxheading{Parameters
}
55 \docparam{width
}{Specifies the width of the image.
}
57 \docparam{height
}{Specifies the height of the image.
}
59 \docparam{name
}{This refers to an image filename. Its meaning is determined by the
{\it type
} parameter.
}
61 \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).
}
63 \docparam{type
}{May be one of the following:
67 \twocolitem{{\bf \indexit{wxBITMAP
\_TYPE\_BMP}}}{Load a Windows bitmap file.
}
68 \twocolitem{{\bf \indexit{wxBITMAP
\_TYPE\_PNG}}}{Load a PNG bitmap file.
}
71 The validity of these flags depends on the platform and wxWindows configuration.
72 If all possible wxWindows settings are used, the loading a BMP (Windows bitmap) file
73 and a PNG (portable network graphics) file is supported on all platforms that
78 \helpref{wxImage::LoadFile
}{wximageloadfile
}
80 \membersection{wxImage::
\destruct{wxImage
}}
82 \func{}{\destruct{wxImage
}}{\void}
86 \membersection{wxImage::AddHandler
}\label{wximageaddhandler
}
88 \func{static void
}{AddHandler
}{\param{wxImageHandler*
}{ handler
}}
90 Adds a handler to the end of the static list of format handlers.
92 \docparam{handler
}{A new image format handler object. There is usually only one instance
93 of a given handler class in an application session.
}
97 \helpref{wxImageHandler
}{wximagehandler
}
99 \membersection{wxImage::CleanUpHandlers
}
101 \func{static void
}{CleanUpHandlers
}{\void}
103 Deletes all image handlers.
105 This function is called by wxWindows on exit.
107 \membersection{wxImage::ConvertToBitmap
}\label{wximageconverttobitmap
}
109 \constfunc{wxBitmap
}{ConvertToBitmap
}{\void}
111 Converts the image to a platform-specific bitmap object. This has to be done
112 to actually display an image as you cannot draw an image directly on a window.
113 The resulting bitmap will use the colour depth of the current system which entails
114 that a (crude) colour reduction has to take place. When in
8-bit mode, this
115 routine will use a
color cube created on program start-up to look up colors.
116 Still, the image quality won't be perfect for photo images.
118 \membersection{wxImage::Create
}\label{wximagecreate
}
120 \func{bool
}{Create
}{\param{int
}{ width
},
\param{int
}{ height
}}
122 Creates a fresh image.
124 \wxheading{Parameters
}
126 \docparam{width
}{The width of the image in pixels.
}
128 \docparam{height
}{The height of the image in pixels.
}
130 \wxheading{Return value
}
132 TRUE if the call succeeded, FALSE otherwise.
134 \membersection{wxImage::Destroy
}\label{wximagedestroy
}
136 \func{bool
}{Destroy
}{\void}
138 Destroys the image data.
140 \membersection{wxImage::FindHandler
}
142 \func{static wxImageHandler*
}{FindHandler
}{\param{const wxString\&
}{name
}}
144 Finds the handler with the given name.
146 \func{static wxImageHandler*
}{FindHandler
}{\param{const wxString\&
}{extension
},
\param{long
}{ imageType
}}
148 Finds the handler associated with the given extension and type.
150 \func{static wxImageHandler*
}{FindHandler
}{\param{long
}{imageType
}}
152 Finds the handler associated with the given image type.
154 \docparam{name
}{The handler name.
}
156 \docparam{extension
}{The file extension, such as ``bmp".
}
158 \docparam{imageType
}{The image type, such as wxBITMAP
\_TYPE\_BMP.
}
160 \wxheading{Return value
}
162 A pointer to the handler if found, NULL otherwise.
166 \helpref{wxImageHandler
}{wximagehandler
}
168 \membersection{wxImage::GetBlue
}\label{wximagegetblue
}
170 \constfunc{unsigned char
}{GetBlue
}{\param{int
}{ x
},
\param{int
}{ y
}}
172 Returns the blue intensity at the given coordinate.
174 \membersection{wxImage::GetData
}\label{wximagegetdata
}
176 \constfunc{unsigned char*
}{GetData
}{\void}
178 Returns the image data as an array. This is most often used when doing
179 direct image manipulation. The return value points to an array of
180 chararcters in RGBGBRGB... format.
182 \membersection{wxImage::GetGreen
}\label{wximagegetgreen
}
184 \constfunc{unsigned char
}{GetGreen
}{\param{int
}{ x
},
\param{int
}{ y
}}
186 Returns the green intensity at the given coordinate.
188 \membersection{wxImage::GetRed
}\label{wximagegetred
}
190 \constfunc{unsigned char
}{GetRed
}{\param{int
}{ x
},
\param{int
}{ y
}}
192 Returns the red intensity at the given coordinate.
194 \membersection{wxImage::GetHandlers
}
196 \func{static wxList\&
}{GetHandlers
}{\void}
198 Returns the static list of image format handlers.
202 \helpref{wxImageHandler
}{wximagehandler
}
204 \membersection{wxImage::GetHeight
}\label{wximagegetheight
}
206 \constfunc{int
}{GetHeight
}{\void}
208 Gets the height of the image in pixels.
210 \membersection{wxImage::GetMaskBlue
}\label{wximagegetmaskblue
}
212 \constfunc{unsigned char
}{GetMaskBlue
}{\void}
214 Gets the blue value of the mask colour.
216 \membersection{wxImage::GetMaskGreen
}\label{wximagegetmaskgreen
}
218 \constfunc{unsigned char
}{GetMaskGreen
}{\void}
220 Gets the green value of the mask colour.
222 \membersection{wxImage::GetMaskRed
}\label{wximagegetmaskred
}
224 \constfunc{unsigned char
}{GetMaskRed
}{\void}
226 Gets the red value of the mask colour.
228 \membersection{wxImage::GetWidth
}\label{wximagegetwidth
}
230 \constfunc{int
}{GetWidth
}{\void}
232 Gets the width of the image in pixels.
236 \helpref{wxImage::GetHeight
}{wximagegetheight
}
238 \membersection{wxImage::HasMask
}\label{wximagehasmask
}
240 \constfunc{bool
}{HasMask
}{\void}
242 Returns TRUE if there is a mask active, FALSE otherwise.
244 \membersection{wxImage::InitStandardHandlers
}
246 \func{static void
}{InitStandardHandlers
}{\void}
248 Adds the standard image format handlers, which, depending on wxWindows
249 configuration, can be handlers for Windows BMP (loading) and PNG
250 (loading and saving) file formats.
252 This function is called by wxWindows on startup.
256 \helpref{wxImageHandler
}{wximagehandler
}
258 \membersection{wxImage::InsertHandler
}
260 \func{static void
}{InsertHandler
}{\param{wxImageHandler*
}{ handler
}}
262 Adds a handler at the start of the static list of format handlers.
264 \docparam{handler
}{A new image format handler object. There is usually only one instance
265 of a given handler class in an application session.
}
269 \helpref{wxImageHandler
}{wximagehandler
}
271 \membersection{wxImage::LoadFile
}\label{wximageloadfile
}
273 \func{bool
}{LoadFile
}{\param{const wxString\&
}{ name
},
\param{long
}{ type
}}
275 Loads an image from a file.
277 \func{bool
}{LoadFile
}{\param{wxInputStream\&
}{ stream
},
\param{long
}{ type
}}
279 Loads an image from an input stream.
281 \wxheading{Parameters
}
283 \docparam{name
}{A filename.
284 The meaning of
{\it name
} is determined by the
{\it type
} parameter.
}
286 \docparam{stream
}{An input stream.
287 The meaning of
{\it stream
} data is determined by the
{\it type
} parameter.
}
289 \docparam{type
}{One of the following values:
293 \twocolitem{{\bf wxBITMAP
\_TYPE\_BMP}}{Load a Windows image file.
}
294 \twocolitem{{\bf wxBITMAP
\_TYPE\_PNG}}{Load a PNG image file.
}
297 The validity of these flags depends on the platform and wxWindows configuration.
}
299 \wxheading{Return value
}
301 TRUE if the operation succeeded, FALSE otherwise.
305 \helpref{wxImage::SaveFile
}{wximagesavefile
}
307 \membersection{wxImage::Ok
}\label{wximageok
}
309 \constfunc{bool
}{Ok
}{\void}
311 Returns TRUE if image data is present.
313 \membersection{wxImage::RemoveHandler
}
315 \func{static bool
}{RemoveHandler
}{\param{const wxString\&
}{name
}}
317 Finds the handler with the given name, and removes it. The handler
320 \docparam{name
}{The handler name.
}
322 \wxheading{Return value
}
324 TRUE if the handler was found and removed, FALSE otherwise.
328 \helpref{wxImageHandler
}{wximagehandler
}
330 \membersection{wxImage::SaveFile
}\label{wximagesavefile
}
332 \func{bool
}{SaveFile
}{\param{const wxString\&
}{name
},
\param{int
}{ type
}}
334 Saves a image in the named file.
336 \func{bool
}{SaveFile
}{\param{wxOutputStream\&
}{stream
},
\param{int
}{ type
}}
338 Saves a image in the given stream.
340 \wxheading{Parameters
}
342 \docparam{name
}{A filename. The meaning of
{\it name
} is determined by the
{\it type
} parameter.
}
344 \docparam{stream
}{An output stream. The meaning of
{\it stream
} is determined by the
{\it type
} parameter.
}
346 \docparam{type
}{Currently only one type can be used:
350 \twocolitem{{\bf wxBITMAP
\_TYPE\_PNG}}{Save a PNG image file.
}
353 The validity of these flags depends on the platform and wxWindows configuration
354 as well as user-added handlers.
}
356 \wxheading{Return value
}
358 TRUE if the operation succeeded, FALSE otherwise.
362 Depending on how wxWindows has been configured, not all formats may be available.
366 \helpref{wxImage::LoadFile
}{wximageloadfile
}
368 \membersection{wxImage::Scale
}\label{wximagescale
}
370 \func{wxImage
}{Scale
}{\param{int
}{ width
},
\param{int
}{ height
}}
372 Returns a scaled version of the image. This is also useful for
373 scaling bitmaps in general as the only other way to scale bitmaps
374 is do blit a wxMemoryDC into another wxMemoryDC. Windows can such scaling
375 itself, but on GTK scaling bitmaps is done using this routine
378 \membersection{wxImage::SetData
}\label{wximagesetdata
}
380 \func{void
}{SetData
}{\param{unsigned char*
}{data
}}
382 Sets the image data without performing checks. The data given must have
383 the size (width*height*
3) or results will be unexpected. Don't use this
384 method if you aren't sure you know what you are doing.
386 \membersection{wxImage::SetMask
}\label{wximagesetmask
}
388 \func{void
}{SetMask
}{\param{bool
}{ hasMask = TRUE
}}
390 Specifies whether there is a mask or not. The area of the mask is determined by the current mask colour.
392 \membersection{wxImage::SetMaskColour
}\label{wximagesetmaskcolour
}
394 \func{void
}{SetMaskColour
}{\param{unsigned char
}{red
},
\param{unsigned char
}{blue
},
\param{unsigned char
}{green
}}
396 Sets the mask colour for this image.
398 \membersection{wxImage::SetRGB
}\label{wximagesetrgb
}
400 \func{void
}{SetRGB
}{\param{int
}{x
},
\param{int
}{y
},
\param{unsigned char
}{red
},
\param{unsigned char
}{blue
},
\param{unsigned char
}{green
}}
402 Sets the pixel at the given coordinate. This routine performs bounds-checks
403 for the coordinate so it can be considered a safe way to manipulate the
404 data, but in some cases this might be too slow so that the data will have to
405 be set directly. In that case you have to get that data by calling GetData().
407 \membersection{wxImage::operator $=$
}
409 \func{wxImage\&
}{operator $=$
}{\param{const wxImage\&
}{image
}}
411 Assignment operator. This operator does not copy any data, but instead
412 passes a pointer to the data in
{\it image
} and increments a reference
413 counter. It is a fast operation.
415 \wxheading{Parameters
}
417 \docparam{image
}{Image to assign.
}
419 \wxheading{Return value
}
421 Returns 'this' object.
423 \membersection{wxImage::operator $==$
}
425 \func{bool
}{operator $==$
}{\param{const wxImage\&
}{image
}}
427 Equality operator. This operator tests whether the internal data pointers are
430 \wxheading{Parameters
}
432 \docparam{image
}{Image to compare with 'this'
}
434 \wxheading{Return value
}
436 Returns TRUE if the images were effectively equal, FALSE otherwise.
438 \membersection{wxImage::operator $!=$
}
440 \func{bool
}{operator $!=$
}{\param{const wxImage\&
}{image
}}
442 Inequality operator. This operator tests whether the internal data pointers are
443 unequal (a fast test).
445 \wxheading{Parameters
}
447 \docparam{image
}{Image to compare with 'this'
}
449 \wxheading{Return value
}
451 Returns TRUE if the images were unequal, FALSE otherwise.
453 \section{\class{wxImageHandler
}}\label{wximagehandler
}
455 This is the base class for implementing image file loading/saving, and image creation from data.
456 It is used within wxImage and is not normally seen by the application.
458 If you wish to extend the capabilities of wxImage, derive a class from wxImageHandler
459 and add the handler using
\helpref{wxImage::AddHandler
}{wximageaddhandler
} in your
460 application initialisation.
462 \wxheading{Derived from
}
464 \helpref{wxObject
}{wxobject
}
468 \helpref{wxImage
}{wximage
}
470 \latexignore{\rtfignore{\wxheading{Members
}}}
472 \membersection{wxImageHandler::wxImageHandler
}\label{wximagehandlerconstr
}
474 \func{}{wxImageHandler
}{\void}
476 Default constructor. In your own default constructor, initialise the members
477 m
\_name, m
\_extension and m
\_type.
479 \membersection{wxImageHandler::
\destruct{wxImageHandler
}}
481 \func{}{\destruct{wxImageHandler
}}{\void}
483 Destroys the wxImageHandler object.
485 \membersection{wxImageHandler::GetName
}
487 \constfunc{wxString
}{GetName
}{\void}
489 Gets the name of this handler.
491 \membersection{wxImageHandler::GetExtension
}
493 \constfunc{wxString
}{GetExtension
}{\void}
495 Gets the file extension associated with this handler.
497 \membersection{wxImageHandler::GetType
}
499 \constfunc{long
}{GetType
}{\void}
501 Gets the image type associated with this handler.
503 \membersection{wxImageHandler::LoadFile
}\label{wximagehandlerloadfile
}
505 \func{bool
}{LoadFile
}{\param{wxImage*
}{image
},
\param{wxInputStream\&
}{ stream
}}
507 Loads a image from a stream, putting the resulting data into
{\it image
}.
509 \wxheading{Parameters
}
511 \docparam{image
}{The image object which is to be affected by this operation.
}
513 \docparam{stream
}{Opened input stream.
514 The meaning of
{\it stream
} is determined by the
{\it type
} parameter.
}
516 \wxheading{Return value
}
518 TRUE if the operation succeeded, FALSE otherwise.
522 \helpref{wxImage::LoadFile
}{wximageloadfile
}\\
523 \helpref{wxImage::SaveFile
}{wximagesavefile
}\\
524 \helpref{wxImageHandler::SaveFile
}{wximagehandlersavefile
}
526 \membersection{wxImageHandler::SaveFile
}\label{wximagehandlersavefile
}
528 \func{bool
}{SaveFile
}{\param{wxImage*
}{image
},
\param{wxOutputStream\&
}{stream
}}
530 Saves a image in the output stream.
532 \wxheading{Parameters
}
534 \docparam{image
}{The image object which is to be affected by this operation.
}
536 \docparam{stream
}{A stream. The meaning of
{\it stream
} is determined by the
{\it type
} parameter.
}
538 \wxheading{Return value
}
540 TRUE if the operation succeeded, FALSE otherwise.
544 \helpref{wxImage::LoadFile
}{wximageloadfile
}\\
545 \helpref{wxImage::SaveFile
}{wximagesavefile
}\\
546 \helpref{wxImageHandler::LoadFile
}{wximagehandlerloadfile
}
548 \membersection{wxImageHandler::SetName
}
550 \func{void
}{SetName
}{\param{const wxString\&
}{name
}}
552 Sets the handler name.
554 \wxheading{Parameters
}
556 \docparam{name
}{Handler name.
}
558 \membersection{wxImageHandler::SetExtension
}
560 \func{void
}{SetExtension
}{\param{const wxString\&
}{extension
}}
562 Sets the handler extension.
564 \wxheading{Parameters
}
566 \docparam{extension
}{Handler extension.
}
568 \membersection{wxImageHandler::SetType
}
570 \func{void
}{SetType
}{\param{long
}{type
}}
572 Sets the handler type.
574 \wxheading{Parameters
}
576 \docparam{name
}{Handler type.
}