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