docs/latex/wx/image.tex

   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 \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.
   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{wxBitmap::wxBitmap(wxImage,int depth)}{wxbitmapconstr} constructor.
  12 This bitmap can then
  13 be drawn in a device context, using \helpref{wxDC::DrawBitmap}{wxdcdrawbitmap}.
  14
  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.
  17
  18 \wxheading{Alpha channel support}
  19
  20 Starting from wxWindows 2.5.0 wxImage supports alpha channel data, that is in
  21 addition to a byte for the red, green and blue colour components for each pixel
  22 it also stores a byte representing the pixel opacity. The alpha value of $0$
  23 corresponds to a transparent pixel (null opacity) while the value of $255$
  24 means that the pixel is 100\% opaque.
  25
  26 Unlike the RGB data, not all images have the alpha channel and before using
  27 \helpref{GetAlpha}{wximagegetalpha} you should check if this image contains
  28 alpha value with \helpref{HasAlpha}{wximagehasalpha}. In fact, currently only
  29 images loaded from PNG files with transparency information will have alpha
  30 channel but support for it will be added to the other formats as well (as well
  31 as support for saving images with alpha channel which is not still implemented
  32 neither).
  33
  34 \wxheading{Available image handlers}
  35
  36 The following image handlers are available. {\bf wxBMPHandler} is always
  37 installed by default. To use other image formats, install the appropriate
  38 handler with \helpref{wxImage::AddHandler}{wximageaddhandler} or
  39 \helpref{wxInitAllImageHandlers}{wxinitallimagehandlers}.
  40
  41 \twocolwidtha{5cm}%
  42 \begin{twocollist}
  43 \twocolitem{\indexit{wxBMPHandler}}{For loading and saving, always installed.}
  44 \twocolitem{\indexit{wxPNGHandler}}{For loading (including alpha support) and saving.}
  45 \twocolitem{\indexit{wxJPEGHandler}}{For loading and saving.}
  46 \twocolitem{\indexit{wxGIFHandler}}{Only for loading, due to legal issues.}
  47 \twocolitem{\indexit{wxPCXHandler}}{For loading and saving (see below).}
  48 \twocolitem{\indexit{wxPNMHandler}}{For loading and saving (see below).}
  49 \twocolitem{\indexit{wxTIFFHandler}}{For loading and saving.}
  50 \twocolitem{\indexit{wxIFFHandler}}{For loading only.}
  51 \twocolitem{\indexit{wxXPMHandler}}{For loading and saving.}
  52 \twocolitem{\indexit{wxICOHandler}}{For loading and saving.}
  53 \twocolitem{\indexit{wxCURHandler}}{For loading and saving.}
  54 \twocolitem{\indexit{wxANIHandler}}{For loading only.}
  55 \end{twocollist}
  56
  57 When saving in PCX format, {\bf wxPCXHandler} will count the number of
  58 different colours in the image; if there are 256 or less colours, it will
  59 save as 8 bit, else it will save as 24 bit.
  60
  61 Loading PNMs only works for ASCII or raw RGB images. When saving in
  62 PNM format, {\bf wxPNMHandler} will always save as raw RGB.
  63
  64 \wxheading{Derived from}
  65
  66 \helpref{wxObject}{wxobject}
  67
  68 \wxheading{Include files}
  69
  70 <wx/image.h>
  71
  72 \wxheading{See also}
  73
  74 \helpref{wxBitmap}{wxbitmap},
  75 \helpref{wxInitAllImageHandlers}{wxinitallimagehandlers}
  76
  77 \latexignore{\rtfignore{\wxheading{Members}}}
  78
  79 \membersection{wxImage::wxImage}\label{wximageconstr}
  80
  81 \func{}{wxImage}{\void}
  82
  83 Default constructor.
  84
  85 \func{}{wxImage}{\param{const wxImage\& }{image}}
  86
  87 Copy constructor.
  88
  89 \func{}{wxImage}{\param{const wxBitmap\&}{ bitmap}}
  90
  91 (Deprecated form, use \helpref{wxBitmap::ConvertToImage}{wxbitmapconverttoimage}
  92 instead.) Constructs an image from a platform-dependent bitmap. This preserves
  93 mask information so that bitmaps and images can be converted back
  94 and forth without loss in that respect.
  95
  96 \func{}{wxImage}{\param{int}{ width}, \param{int}{ height}, \param{bool}{ clear=true}}
  97
  98 Creates an image with the given width and height.  If {\it clear} is true, the new image will be initialized to black.
  99 Otherwise, the image data will be uninitialized.
 100
 101 \func{}{wxImage}{\param{int}{ width}, \param{int}{ height}, \param{unsigned char*}{ data}, \param{bool}{ static\_data=false}}
 102
 103 Creates an image from given data with the given width and height. If
 104 {\it static\_data} is true, then wxImage will not delete the actual
 105 image data in its destructor, otherwise it will free it by calling
 106 {\it free()}.
 107
 108 \func{}{wxImage}{\param{const wxString\& }{name}, \param{long}{ type = wxBITMAP\_TYPE\_ANY}, \param{int}{ index = -1}}
 109
 110 \func{}{wxImage}{\param{const wxString\& }{name}, \param{const wxString\&}{ mimetype}, \param{int}{ index = -1}}
 111
 112 Loads an image from a file.
 113
 114 \func{}{wxImage}{\param{wxInputStream\& }{stream}, \param{long}{ type = wxBITMAP\_TYPE\_ANY}, \param{int}{ index = -1}}
 115
 116 \func{}{wxImage}{\param{wxInputStream\& }{stream}, \param{const wxString\&}{ mimetype}, \param{int}{ index = -1}}
 117
 118 Loads an image from an input stream.
 119
 120 \wxheading{Parameters}
 121
 122 \docparam{width}{Specifies the width of the image.}
 123
 124 \docparam{height}{Specifies the height of the image.}
 125
 126 \docparam{name}{Name of the file from which to load the image.}
 127
 128 \docparam{stream}{Opened input stream from which to load the image. Currently, the stream must support seeking.}
 129
 130 \docparam{type}{May be one of the following:
 131
 132 \twocolwidtha{5cm}%
 133 \begin{twocollist}
 134 \twocolitem{\indexit{wxBITMAP\_TYPE\_BMP}}{Load a Windows bitmap file.}
 135 \twocolitem{\indexit{wxBITMAP\_TYPE\_GIF}}{Load a GIF bitmap file.}
 136 \twocolitem{\indexit{wxBITMAP\_TYPE\_JPEG}}{Load a JPEG bitmap file.}
 137 \twocolitem{\indexit{wxBITMAP\_TYPE\_PNG}}{Load a PNG bitmap file.}
 138 \twocolitem{\indexit{wxBITMAP\_TYPE\_PCX}}{Load a PCX bitmap file.}
 139 \twocolitem{\indexit{wxBITMAP\_TYPE\_PNM}}{Load a PNM bitmap file.}
 140 \twocolitem{\indexit{wxBITMAP\_TYPE\_TIF}}{Load a TIFF bitmap file.}
 141 \twocolitem{\indexit{wxBITMAP\_TYPE\_XPM}}{Load a XPM bitmap file.}
 142 \twocolitem{\indexit{wxBITMAP\_TYPE\_ICO}}{Load a Windows icon file (ICO).}
 143 \twocolitem{\indexit{wxBITMAP\_TYPE\_CUR}}{Load a Windows cursor file (CUR).}
 144 \twocolitem{\indexit{wxBITMAP\_TYPE\_ANI}}{Load a Windows animated cursor file (ANI).}
 145 \twocolitem{\indexit{wxBITMAP\_TYPE\_ANY}}{Will try to autodetect the format.}
 146 \end{twocollist}}
 147
 148 \docparam{mimetype}{MIME type string (for example 'image/jpeg')}
 149
 150 \docparam{index}{Index of the image to load in the case that the image file contains multiple images.
 151 This is only used by GIF, ICO and TIFF handlers. The default value (-1) means
 152 "choose the default image" and is interpreted as the first image (index=0) by
 153 the GIF and TIFF handler and as the largest and most colourful one by the ICO handler.}
 154
 155 \wxheading{Remarks}
 156
 157 Depending on how wxWindows has been configured, not all formats may be available.
 158
 159 Note: any handler other than BMP must be previously
 160 initialized with \helpref{wxImage::AddHandler}{wximageaddhandler} or
 161 \helpref{wxInitAllImageHandlers}{wxinitallimagehandlers}.
 162
 163 Note: you can use \helpref{GetOptionInt}{wximagegetoptionint} to get the
 164 hotspot for loaded cursor file:
 165 \begin{verbatim}
 166     int hotspot_x = image.GetOptionInt(wxIMAGE_OPTION_CUR_HOTSPOT_X);
 167     int hotspot_y = image.GetOptionInt(wxIMAGE_OPTION_CUR_HOTSPOT_Y);
 168
 169 \end{verbatim}
 170
 171 \wxheading{See also}
 172
 173 \helpref{wxImage::LoadFile}{wximageloadfile}
 174
 175 \pythonnote{Constructors supported by wxPython are:\par
 176 \indented{2cm}{\begin{twocollist}
 177 \twocolitem{{\bf wxImage(name, flag)}}{Loads an image from a file}
 178 \twocolitem{{\bf wxNullImage()}}{Create a null image (has no size or
 179 image data)}
 180 \twocolitem{{\bf wxEmptyImage(width, height)}}{Creates an empty image
 181 of the given size}
 182 \twocolitem{{\bf wxImageFromMime(name, mimetype}}{Creates an image from
 183 the given file of the given mimetype}
 184 \twocolitem{{\bf wxImageFromBitmap(bitmap)}}{Creates an image from a
 185 platform-dependent bitmap}
 186 \end{twocollist}}
 187 }
 188
 189 \perlnote{Constructors supported by wxPerl are:\par
 190 \begin{itemize}
 191 \item{Wx::Image->new( bitmap )}
 192 \item{Wx::Image->new( width, height )}
 193 \item{Wx::Image->new( name, type )}
 194 \item{Wx::Image->new( name, mimetype )}
 195 \end{itemize}
 196 }
 197
 198 \membersection{wxImage::\destruct{wxImage}}
 199
 200 \func{}{\destruct{wxImage}}{\void}
 201
 202 Destructor.
 203
 204 \membersection{wxImage::AddHandler}\label{wximageaddhandler}
 205
 206 \func{static void}{AddHandler}{\param{wxImageHandler*}{ handler}}
 207
 208 Adds a handler to the end of the static list of format handlers.
 209
 210 \docparam{handler}{A new image format handler object. There is usually only one instance
 211 of a given handler class in an application session.}
 212
 213 \wxheading{See also}
 214
 215 \helpref{wxImageHandler}{wximagehandler}
 216
 217 \func{bool}{CanRead}{\param{const wxString\&}{ filename}}
 218
 219 returns true if the current image handlers can read this file
 220
 221 \pythonnote{In wxPython this static method is named {\tt wxImage\_AddHandler}.}
 222 \membersection{wxImage::CleanUpHandlers}
 223
 224 \func{static void}{CleanUpHandlers}{\void}
 225
 226 Deletes all image handlers.
 227
 228 This function is called by wxWindows on exit.
 229
 230 \membersection{wxImage::ComputeHistogram}\label{wximagecomputehistogram}
 231
 232 \constfunc{unsigned long}{ComputeHistogram}{\param{wxImageHistogram\& }{histogram}}
 233
 234 Computes the histogram of the image. {\it histogram} is a reference to
 235 wxImageHistogram object. wxImageHistogram is a specialization of
 236 \helpref{wxHashMap}{wxhashmap} "template" and is defined as follows:
 237
 238 \begin{verbatim}
 239 class WXDLLEXPORT wxImageHistogramEntry
 240 {
 241 public:
 242     wxImageHistogramEntry() : index(0), value(0) {}
 243     unsigned long index;
 244     unsigned long value;
 245 };
 246
 247 WX_DECLARE_EXPORTED_HASH_MAP(unsigned long, wxImageHistogramEntry,
 248                              wxIntegerHash, wxIntegerEqual,
 249                              wxImageHistogram);
 250 \end{verbatim}
 251
 252 \wxheading{Return value}
 253
 254 Returns number of colours in the histogram.
 255
 256 \membersection{wxImage::ConvertToBitmap}\label{wximageconverttobitmap}
 257
 258 \constfunc{wxBitmap}{ConvertToBitmap}{\void}
 259
 260 Deprecated, use equivalent \helpref{wxBitmap constructor}{wxbitmapconstr}
 261 (which takes wxImage and depth as its arguments) instead.
 262
 263 \membersection{wxImage::ConvertToMono}\label{wxbitmapconverttomono}
 264
 265 \constfunc{wxImage}{ConvertToMono}{\param{unsigned char}{ r}, \param{unsigned char}{ g}, \param{unsigned char}{ b}}
 266
 267 Returns monochromatic version of the image. The returned image has white
 268 colour where the original has {\it (r,g,b)} colour and black colour
 269 everywhere else.
 270
 271 \membersection{wxImage::Copy}\label{wximagecopy}
 272
 273 \constfunc{wxImage}{Copy}{\void}
 274
 275 Returns an identical copy of the image.
 276
 277 \membersection{wxImage::Create}\label{wximagecreate}
 278
 279 \func{bool}{Create}{\param{int}{ width}, \param{int}{ height}, \param{bool}{ clear=true}}
 280
 281 Creates a fresh image.  If {\it clear} is true, the new image will be initialized to black.
 282 Otherwise, the image data will be uninitialized.
 283
 284 \wxheading{Parameters}
 285
 286 \docparam{width}{The width of the image in pixels.}
 287
 288 \docparam{height}{The height of the image in pixels.}
 289
 290 \wxheading{Return value}
 291
 292 true if the call succeeded, false otherwise.
 293
 294 \membersection{wxImage::Destroy}\label{wximagedestroy}
 295
 296 \func{bool}{Destroy}{\void}
 297
 298 Destroys the image data.
 299
 300 \membersection{wxImage::FindFirstUnusedColour}\label{wximagefindfirstunusedcolour}
 301
 302 \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}}
 303
 304 \wxheading{Parameters}
 305
 306 \docparam{r,g,b}{Pointers to variables to save the colour.}
 307
 308 \docparam{startR,startG,startB}{Initial values of the colour. Returned colour
 309 will have RGB values equal to or greater than these.}
 310
 311 Finds the first colour that is never used in the image. The search begins at
 312 given initial colour and continues by increasing R, G and B components (in this
 313 order) by 1 until an unused colour is found or the colour space exhausted.
 314
 315 \wxheading{Return value}
 316
 317 Returns false if there is no unused colour left, true on success.
 318
 319 \wxheading{Notes}
 320
 321 Note that this method involves computing the histogram, which is
 322 computationally intensive operation.
 323
 324 \membersection{wxImage::FindHandler}
 325
 326 \func{static wxImageHandler*}{FindHandler}{\param{const wxString\& }{name}}
 327
 328 Finds the handler with the given name.
 329
 330 \func{static wxImageHandler*}{FindHandler}{\param{const wxString\& }{extension}, \param{long}{ imageType}}
 331
 332 Finds the handler associated with the given extension and type.
 333
 334 \func{static wxImageHandler*}{FindHandler}{\param{long }{imageType}}
 335
 336 Finds the handler associated with the given image type.
 337
 338 \func{static wxImageHandler*}{FindHandlerMime}{\param{const wxString\& }{mimetype}}
 339
 340 Finds the handler associated with the given MIME type.
 341
 342 \docparam{name}{The handler name.}
 343
 344 \docparam{extension}{The file extension, such as ``bmp".}
 345
 346 \docparam{imageType}{The image type, such as wxBITMAP\_TYPE\_BMP.}
 347
 348 \docparam{mimetype}{MIME type.}
 349
 350 \wxheading{Return value}
 351
 352 A pointer to the handler if found, NULL otherwise.
 353
 354 \wxheading{See also}
 355
 356 \helpref{wxImageHandler}{wximagehandler}
 357
 358 \membersection{wxImage::GetAlpha}\label{wximagegetalpha}
 359
 360 \constfunc{unsigned char}{GetAlpha}{\param{int}{ x}, \param{int}{ y}}
 361
 362 Returns the alpha value for the given pixel. This function may only be called
 363 for the images with alpha channel, use \helpref{HasAlpha}{wximagehasalpha} to
 364 check for this.
 365
 366 The returned value is the {\it opacity} of the image, i.e. the value of $0$
 367 corresponds to the transparent pixels while the value of $255$ -- to the opaque
 368 ones.
 369
 370 \constfunc{unsigned char *}{GetAlpha}{\void}
 371
 372 Returns pointer to the array storing the alpha values for this image. This
 373 pointer is {\tt NULL} for the images without the alpha channel. If the image
 374 does have it, this pointer may be used to directly manipulate the alpha values
 375 which are stored as the \helpref{RGB}{wximagegetdata} ones.
 376
 377 \membersection{wxImage::GetBlue}\label{wximagegetblue}
 378
 379 \constfunc{unsigned char}{GetBlue}{\param{int}{ x}, \param{int}{ y}}
 380
 381 Returns the blue intensity at the given coordinate.
 382
 383 \membersection{wxImage::GetData}\label{wximagegetdata}
 384
 385 \constfunc{unsigned char*}{GetData}{\void}
 386
 387 Returns the image data as an array. This is most often used when doing
 388 direct image manipulation. The return value points to an array of
 389 characters in RGBRGBRGB$\ldots$ format in the top-to-bottom, left-to-right
 390 order, that is the first RGB triplet corresponds to the pixel $(0, 0)$, the
 391 second one --- to $(0, 1)$ and so on.
 392
 393 You should not delete the returned pointer nor pass it to
 394 \helpref{wxImage::SetData}{wximagesetdata}.
 395
 396 \membersection{wxImage::GetGreen}\label{wximagegetgreen}
 397
 398 \constfunc{unsigned char}{GetGreen}{\param{int}{ x}, \param{int}{ y}}
 399
 400 Returns the green intensity at the given coordinate.
 401
 402 \membersection{wxImage::GetImageCount}\label{wximagegetimagecount}
 403
 404 \func{static int}{GetImageCount}{\param{const wxString\&}{ filename}, \param{long}{ type = wxBITMAP\_TYPE\_ANY}}
 405
 406 \func{static int}{GetImageCount}{\param{wxInputStream\&}{ stream}, \param{long}{ type = wxBITMAP\_TYPE\_ANY}}
 407
 408 If the image file contains more than one image and the image handler is capable
 409 of retrieving these individually, this function will return the number of
 410 available images.
 411
 412 \docparam{name}{Name of the file to query.}
 413
 414 \docparam{stream}{Opened input stream with image data. Currently, the stream must support seeking.}
 415
 416 \docparam{type}{May be one of the following:
 417
 418 \twocolwidtha{5cm}%
 419 \begin{twocollist}
 420 \twocolitem{\indexit{wxBITMAP\_TYPE\_BMP}}{Load a Windows bitmap file.}
 421 \twocolitem{\indexit{wxBITMAP\_TYPE\_GIF}}{Load a GIF bitmap file.}
 422 \twocolitem{\indexit{wxBITMAP\_TYPE\_JPEG}}{Load a JPEG bitmap file.}
 423 \twocolitem{\indexit{wxBITMAP\_TYPE\_PNG}}{Load a PNG bitmap file.}
 424 \twocolitem{\indexit{wxBITMAP\_TYPE\_PCX}}{Load a PCX bitmap file.}
 425 \twocolitem{\indexit{wxBITMAP\_TYPE\_PNM}}{Load a PNM bitmap file.}
 426 \twocolitem{\indexit{wxBITMAP\_TYPE\_TIF}}{Load a TIFF bitmap file.}
 427 \twocolitem{\indexit{wxBITMAP\_TYPE\_XPM}}{Load a XPM bitmap file.}
 428 \twocolitem{\indexit{wxBITMAP\_TYPE\_ICO}}{Load a Windows icon file (ICO).}
 429 \twocolitem{\indexit{wxBITMAP\_TYPE\_CUR}}{Load a Windows cursor file (CUR).}
 430 \twocolitem{\indexit{wxBITMAP\_TYPE\_ANI}}{Load a Windows animated cursor file (ANI).}
 431 \twocolitem{\indexit{wxBITMAP\_TYPE\_ANY}}{Will try to autodetect the format.}
 432 \end{twocollist}}
 433
 434 \wxheading{Return value}
 435
 436 Number of available images. For most image handlers, this is 1 (exceptions
 437 are TIFF and ICO formats).
 438
 439 \membersection{wxImage::GetHandlers}
 440
 441 \func{static wxList\&}{GetHandlers}{\void}
 442
 443 Returns the static list of image format handlers.
 444
 445 \wxheading{See also}
 446
 447 \helpref{wxImageHandler}{wximagehandler}
 448
 449 \membersection{wxImage::GetHeight}\label{wximagegetheight}
 450
 451 \constfunc{int}{GetHeight}{\void}
 452
 453 Gets the height of the image in pixels.
 454
 455 \membersection{wxImage::GetMaskBlue}\label{wximagegetmaskblue}
 456
 457 \constfunc{unsigned char}{GetMaskBlue}{\void}
 458
 459 Gets the blue value of the mask colour.
 460
 461 \membersection{wxImage::GetMaskGreen}\label{wximagegetmaskgreen}
 462
 463 \constfunc{unsigned char}{GetMaskGreen}{\void}
 464
 465 Gets the green value of the mask colour.
 466
 467 \membersection{wxImage::GetMaskRed}\label{wximagegetmaskred}
 468
 469 \constfunc{unsigned char}{GetMaskRed}{\void}
 470
 471 Gets the red value of the mask colour.
 472
 473 \membersection{wxImage::GetPalette}\label{wximagegetpalette}
 474
 475 \constfunc{const wxPalette\&}{GetPalette}{\void}
 476
 477 Returns the palette associated with the image. Currently the palette is only
 478 used when converting to wxBitmap under Windows.
 479
 480 Eventually wxImage handlers will set the palette if one exists in the image file.
 481
 482 \membersection{wxImage::GetRed}\label{wximagegetred}
 483
 484 \constfunc{unsigned char}{GetRed}{\param{int}{ x}, \param{int}{ y}}
 485
 486 Returns the red intensity at the given coordinate.
 487
 488 \membersection{wxImage::GetSubImage}\label{wximagegetsubimage}
 489
 490 \constfunc{wxImage}{GetSubImage}{\param{const wxRect\&}{ rect}}
 491
 492 Returns a sub image of the current one as long as the rect belongs entirely to
 493 the image.
 494
 495 \membersection{wxImage::GetWidth}\label{wximagegetwidth}
 496
 497 \constfunc{int}{GetWidth}{\void}
 498
 499 Gets the width of the image in pixels.
 500
 501 \wxheading{See also}
 502
 503 \helpref{wxImage::GetHeight}{wximagegetheight}
 504
 505 \membersection{wxImage::HasAlpha}\label{wximagehasalpha}
 506
 507 \constfunc{bool}{HasAlpha}{\void}
 508
 509 Returns true if this image has alpha channel, false otherwise.
 510
 511 \wxheading{See also}
 512
 513 \helpref{GetAlpha}{wximagegetalpha}, \helpref{SetAlpha}{wximagesetalpha}
 514
 515 \membersection{wxImage::HasMask}\label{wximagehasmask}
 516
 517 \constfunc{bool}{HasMask}{\void}
 518
 519 Returns true if there is a mask active, false otherwise.
 520
 521 \membersection{wxImage::GetOption}\label{wximagegetoption}
 522
 523 \constfunc{wxString}{GetOption}{\param{const wxString\&}{ name}}
 524
 525 Gets a user-defined option. The function is case-insensitive to {\it name}.
 526
 527 For example, when saving as a JPEG file, the option {\bf quality} is
 528 used, which is a number between 0 and 100 (0 is terrible, 100 is very good).
 529
 530 \wxheading{See also}
 531
 532 \helpref{wxImage::SetOption}{wximagesetoption},\rtfsp
 533 \helpref{wxImage::GetOptionInt}{wximagegetoptionint},\rtfsp
 534 \helpref{wxImage::HasOption}{wximagehasoption}
 535
 536 \membersection{wxImage::GetOptionInt}\label{wximagegetoptionint}
 537
 538 \constfunc{int}{GetOptionInt}{\param{const wxString\&}{ name}}
 539
 540 Gets a user-defined option as an integer. The function is case-insensitive to {\it name}.
 541
 542 \wxheading{See also}
 543
 544 \helpref{wxImage::SetOption}{wximagesetoption},\rtfsp
 545 \helpref{wxImage::GetOption}{wximagegetoption},\rtfsp
 546 \helpref{wxImage::HasOption}{wximagehasoption}
 547
 548 \membersection{wxImage::HasOption}\label{wximagehasoption}
 549
 550 \constfunc{bool}{HasOption}{\param{const wxString\&}{ name}}
 551
 552 Returns true if the given option is present. The function is case-insensitive to {\it name}.
 553
 554 \wxheading{See also}
 555
 556 \helpref{wxImage::SetOption}{wximagesetoption},\rtfsp
 557 \helpref{wxImage::GetOption}{wximagegetoption},\rtfsp
 558 \helpref{wxImage::GetOptionInt}{wximagegetoptionint}
 559
 560 \membersection{wxImage::InitStandardHandlers}
 561
 562 \func{static void}{InitStandardHandlers}{\void}
 563
 564 Internal use only. Adds standard image format handlers. It only install BMP
 565 for the time being, which is used by wxBitmap.
 566
 567 This function is called by wxWindows on startup, and shouldn't be called by
 568 the user.
 569
 570 \wxheading{See also}
 571
 572 \helpref{wxImageHandler}{wximagehandler},
 573 \helpref{wxInitAllImageHandlers}{wxinitallimagehandlers}
 574
 575 \membersection{wxImage::InsertHandler}
 576
 577 \func{static void}{InsertHandler}{\param{wxImageHandler*}{ handler}}
 578
 579 Adds a handler at the start of the static list of format handlers.
 580
 581 \docparam{handler}{A new image format handler object. There is usually only one instance
 582 of a given handler class in an application session.}
 583
 584 \wxheading{See also}
 585
 586 \helpref{wxImageHandler}{wximagehandler}
 587
 588 \membersection{wxImage::LoadFile}\label{wximageloadfile}
 589
 590 \func{bool}{LoadFile}{\param{const wxString\&}{ name}, \param{long}{ type = wxBITMAP\_TYPE\_ANY}, \param{int}{ index = -1}}
 591
 592 \func{bool}{LoadFile}{\param{const wxString\&}{ name}, \param{const wxString\&}{ mimetype}, \param{int}{ index = -1}}
 593
 594 Loads an image from a file. If no handler type is provided, the library will
 595 try to autodetect the format.
 596
 597 \func{bool}{LoadFile}{\param{wxInputStream\&}{ stream}, \param{long}{ type}, \param{int}{ index = -1}}
 598
 599 \func{bool}{LoadFile}{\param{wxInputStream\&}{ stream}, \param{const wxString\&}{ mimetype}, \param{int}{ index = -1}}
 600
 601 Loads an image from an input stream.
 602
 603 \wxheading{Parameters}
 604
 605 \docparam{name}{Name of the file from which to load the image.}
 606
 607 \docparam{stream}{Opened input stream from which to load the image. Currently, the stream must support seeking.}
 608
 609 \docparam{type}{One of the following values:
 610
 611 \twocolwidtha{5cm}%
 612 \begin{twocollist}
 613 \twocolitem{{\bf wxBITMAP\_TYPE\_BMP}}{Load a Windows image file.}
 614 \twocolitem{{\bf wxBITMAP\_TYPE\_GIF}}{Load a GIF image file.}
 615 \twocolitem{{\bf wxBITMAP\_TYPE\_JPEG}}{Load a JPEG image file.}
 616 \twocolitem{{\bf wxBITMAP\_TYPE\_PCX}}{Load a PCX image file.}
 617 \twocolitem{{\bf wxBITMAP\_TYPE\_PNG}}{Load a PNG image file.}
 618 \twocolitem{{\bf wxBITMAP\_TYPE\_PNM}}{Load a PNM image file.}
 619 \twocolitem{{\bf wxBITMAP\_TYPE\_TIF}}{Load a TIFF image file.}
 620 \twocolitem{{\bf wxBITMAP\_TYPE\_XPM}}{Load a XPM image file.}
 621 \twocolitem{{\bf wxBITMAP\_TYPE\_ICO}}{Load a Windows icon file (ICO).}
 622 \twocolitem{{\bf wxBITMAP\_TYPE\_CUR}}{Load a Windows cursor file (CUR).}
 623 \twocolitem{\indexit{wxBITMAP\_TYPE\_ANI}}{Load a Windows animated cursor file (ANI).}
 624 \twocolitem{{\bf wxBITMAP\_TYPE\_ANY}}{Will try to autodetect the format.}
 625 \end{twocollist}}
 626
 627 \docparam{mimetype}{MIME type string (for example 'image/jpeg')}
 628
 629 \docparam{index}{Index of the image to load in the case that the image file contains multiple images.
 630 This is only used by GIF, ICO and TIFF handlers. The default value (-1) means
 631 "choose the default image" and is interpreted as the first image (index=0) by
 632 the GIF and TIFF handler and as the largest and most colourful one by the ICO handler.}
 633
 634 \wxheading{Remarks}
 635
 636 Depending on how wxWindows has been configured, not all formats may be available.
 637
 638 Note: you can use \helpref{GetOptionInt}{wximagegetoptionint} to get the
 639 hotspot for loaded cursor file:
 640 \begin{verbatim}
 641     int hotspot_x = image.GetOptionInt(wxIMAGE_OPTION_CUR_HOTSPOT_X);
 642     int hotspot_y = image.GetOptionInt(wxIMAGE_OPTION_CUR_HOTSPOT_Y);
 643
 644 \end{verbatim}
 645
 646 \wxheading{Return value}
 647
 648 true if the operation succeeded, false otherwise. If the optional index parameter is out of range,
 649 false is returned and a call to wxLogError() takes place.
 650
 651 \wxheading{See also}
 652
 653 \helpref{wxImage::SaveFile}{wximagesavefile}
 654
 655 \pythonnote{In place of a single overloaded method name, wxPython
 656 implements the following methods:\par
 657 \indented{2cm}{\begin{twocollist}
 658 \twocolitem{{\bf LoadFile(filename, type)}}{Loads an image of the given
 659 type from a file}
 660 \twocolitem{{\bf LoadMimeFile(filename, mimetype)}}{Loads an image of the given
 661 mimetype from a file}
 662 \end{twocollist}}
 663 }
 664
 665 \perlnote{Methods supported by wxPerl are:\par
 666 \begin{itemize}
 667 \item{bitmap->LoadFile( name, type )}
 668 \item{bitmap->LoadFile( name, mimetype )}
 669 \end{itemize}
 670 }
 671
 672
 673 \membersection{wxImage::Ok}\label{wximageok}
 674
 675 \constfunc{bool}{Ok}{\void}
 676
 677 Returns true if image data is present.
 678
 679 \membersection{wxImage::RemoveHandler}
 680
 681 \func{static bool}{RemoveHandler}{\param{const wxString\& }{name}}
 682
 683 Finds the handler with the given name, and removes it. The handler
 684 is not deleted.
 685
 686 \docparam{name}{The handler name.}
 687
 688 \wxheading{Return value}
 689
 690 true if the handler was found and removed, false otherwise.
 691
 692 \wxheading{See also}
 693
 694 \helpref{wxImageHandler}{wximagehandler}
 695
 696 \membersection{wxImage::SaveFile}\label{wximagesavefile}
 697
 698 \constfunc{bool}{SaveFile}{\param{const wxString\& }{name}, \param{int}{ type}}
 699
 700 \constfunc{bool}{SaveFile}{\param{const wxString\& }{name}, \param{const wxString\&}{ mimetype}}
 701
 702 Saves an image in the named file.
 703
 704 \constfunc{bool}{SaveFile}{\param{const wxString\& }{name}}
 705
 706 Saves an image in the named file. File type is determined from the extension of the
 707 file name. Note that this function may fail if the extension is not recognized! You
 708 can use one of the forms above to save images to files with non-standard extensions.
 709
 710 \constfunc{bool}{SaveFile}{\param{wxOutputStream\& }{stream}, \param{int}{ type}}
 711
 712 \constfunc{bool}{SaveFile}{\param{wxOutputStream\& }{stream}, \param{const wxString\&}{ mimetype}}
 713
 714 Saves an image in the given stream.
 715
 716 \wxheading{Parameters}
 717
 718 \docparam{name}{Name of the file to save the image to.}
 719
 720 \docparam{stream}{Opened output stream to save the image to.}
 721
 722 \docparam{type}{Currently these types can be used:
 723
 724 \twocolwidtha{5cm}%
 725 \begin{twocollist}
 726 \twocolitem{{\bf wxBITMAP\_TYPE\_BMP}}{Save a BMP image file.}
 727 \twocolitem{{\bf wxBITMAP\_TYPE\_JPEG}}{Save a JPEG image file.}
 728 \twocolitem{{\bf wxBITMAP\_TYPE\_PNG}}{Save a PNG image file.}
 729 \twocolitem{{\bf wxBITMAP\_TYPE\_PCX}}{Save a PCX image file (tries to save as 8-bit if possible, falls back to 24-bit otherwise).}
 730 \twocolitem{{\bf wxBITMAP\_TYPE\_PNM}}{Save a PNM image file (as raw RGB always).}
 731 \twocolitem{{\bf wxBITMAP\_TYPE\_TIFF}}{Save a TIFF image file.}
 732 \twocolitem{{\bf wxBITMAP\_TYPE\_XPM}}{Save a XPM image file.}
 733 \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).}
 734 \twocolitem{{\bf wxBITMAP\_TYPE\_CUR}}{Save a Windows cursor file (CUR).}
 735 \end{twocollist}}
 736
 737 \docparam{mimetype}{MIME type.}
 738
 739 \wxheading{Return value}
 740
 741 true if the operation succeeded, false otherwise.
 742
 743 \wxheading{Remarks}
 744
 745 Depending on how wxWindows has been configured, not all formats may be available.
 746
 747 Note: you can use \helpref{GetOptionInt}{wximagegetoptionint} to set the
 748 hotspot before saving an image into a cursor file (default hotspot is in
 749 the centre of the image):
 750 \begin{verbatim}
 751     image.SetOption(wxIMAGE_OPTION_CUR_HOTSPOT_X, hotspotX);
 752     image.SetOption(wxIMAGE_OPTION_CUR_HOTSPOT_Y, hotspotY);
 753
 754 \end{verbatim}
 755
 756 \wxheading{See also}
 757
 758 \helpref{wxImage::LoadFile}{wximageloadfile}
 759
 760 \pythonnote{In place of a single overloaded method name, wxPython
 761 implements the following methods:\par
 762 \indented{2cm}{\begin{twocollist}
 763 \twocolitem{{\bf SaveFile(filename, type)}}{Saves the image using the given
 764 type to the named file}
 765 \twocolitem{{\bf SaveMimeFile(filename, mimetype)}}{Saves the image using the given
 766 mimetype to the named file}
 767 \end{twocollist}}
 768 }
 769
 770 \perlnote{Methods supported by wxPerl are:\par
 771 \begin{itemize}
 772 \item{bitmap->SaveFile( name, type )}
 773 \item{bitmap->SaveFile( name, mimetype )}
 774 \end{itemize}
 775 }
 776
 777 \membersection{wxImage::Mirror}\label{wximagemirror}
 778
 779 \constfunc{wxImage}{Mirror}{\param{bool}{ horizontally = true}}
 780
 781 Returns a mirrored copy of the image. The parameter {\it horizontally}
 782 indicates the orientation.
 783
 784 \membersection{wxImage::Replace}\label{wximagereplace}
 785
 786 \func{void}{Replace}{\param{unsigned char}{ r1}, \param{unsigned char}{ g1}, \param{unsigned char}{ b1},
 787 \param{unsigned char}{ r2}, \param{unsigned char}{ g2}, \param{unsigned char}{ b2}}
 788
 789 Replaces the colour specified by {\it r1,g1,b1} by the colour {\it r2,g2,b2}.
 790
 791 \membersection{wxImage::Rescale}\label{wximagerescale}
 792
 793 \func{wxImage \&}{Rescale}{\param{int}{ width}, \param{int}{ height}}
 794
 795 Changes the size of the image in-place: after a call to this function, the
 796 image will have the given width and height.
 797
 798 Returns the (modified) image itself.
 799
 800 \wxheading{See also}
 801
 802 \helpref{Scale}{wximagescale}
 803
 804 \membersection{wxImage::Rotate}\label{wximagerotate}
 805
 806 \func{wxImage}{Rotate}{\param{double}{ angle}, \param{const wxPoint\& }{rotationCentre},
 807  \param{bool}{ interpolating = true}, \param{wxPoint*}{ offsetAfterRotation = NULL}}
 808
 809 Rotates the image about the given point, by {\it angle} radians. Passing true
 810 to {\it interpolating} results in better image quality, but is slower. If the
 811 image has a mask, then the mask colour is used for the uncovered pixels in the
 812 rotated image background. Else, black (rgb 0, 0, 0) will be used.
 813
 814 Returns the rotated image, leaving this image intact.
 815
 816 \membersection{wxImage::Rotate90}\label{wximagerotate90}
 817
 818 \constfunc{wxImage}{Rotate90}{\param{bool}{ clockwise = true}}
 819
 820 Returns a copy of the image rotated 90 degrees in the direction
 821 indicated by {\it clockwise}.
 822
 823 \membersection{wxImage::Scale}\label{wximagescale}
 824
 825 \constfunc{wxImage}{Scale}{\param{int}{ width}, \param{int}{ height}}
 826
 827 Returns a scaled version of the image. This is also useful for
 828 scaling bitmaps in general as the only other way to scale bitmaps
 829 is to blit a wxMemoryDC into another wxMemoryDC.
 830
 831 It may be mentioned that the GTK port uses this function internally
 832 to scale bitmaps when using mapping modes in wxDC.
 833
 834 Example:
 835
 836 \begin{verbatim}
 837     // get the bitmap from somewhere
 838     wxBitmap bmp = ...;
 839
 840     // rescale it to have size of 32*32
 841     if ( bmp.GetWidth() != 32 || bmp.GetHeight() != 32 )
 842     {
 843         wxImage image = bmp.ConvertToImage();
 844         bmp = wxBitmap(image.Scale(32, 32));
 845
 846         // another possibility:
 847         image.Rescale(32, 32);
 848         bmp = image;
 849     }
 850
 851 \end{verbatim}
 852
 853 \wxheading{See also}
 854
 855 \helpref{Rescale}{wximagerescale}
 856
 857 \membersection{wxImage::SetAlpha}\label{wximagesetalpha}
 858
 859 \func{void}{SetAlpha}{\param{unsigned char *}{alpha = {\tt NULL}}}
 860
 861 This function is similar to \helpref{SetData}{wximagesetdata} and has similar
 862 restrictions. The pointer passed to it may however be {\tt NULL} in which case
 863 the function will allocate the alpha array internally -- this is useful to add
 864 alpha channel data to an image which doesn't have any. If the pointer is not
 865 {\tt NULL}, it must have one byte for each image pixel and be allocated with
 866 {\tt malloc()}. wxImage takes ownership of the pointer and will free it.
 867
 868 \func{void}{SetAlpha}{\param{int }{x}, \param{int }{y}, \param{unsigned char }{alpha}}
 869
 870 Sets the alpha value for the given pixel. This function should only be called
 871 if the image has alpha channel data, use \helpref{HasAlpha}{wximagehasalpha} to
 872 check for this.
 873
 874 \membersection{wxImage::SetData}\label{wximagesetdata}
 875
 876 \func{void}{SetData}{\param{unsigned char*}{data}}
 877
 878 Sets the image data without performing checks. The data given must have
 879 the size (width*height*3) or results will be unexpected. Don't use this
 880 method if you aren't sure you know what you are doing.
 881
 882 The data must have been allocated with {\tt malloc()}, {\large {\bf NOT}} with
 883 {\tt operator new}.
 884
 885 After this call the pointer to the data is owned by the wxImage object,
 886 that will be responsible for deleting it.
 887 Do not pass to this function a pointer obtained through
 888 \helpref{wxImage::GetData}{wximagegetdata}.
 889
 890 \membersection{wxImage::SetMask}\label{wximagesetmask}
 891
 892 \func{void}{SetMask}{\param{bool}{ hasMask = true}}
 893
 894 Specifies whether there is a mask or not. The area of the mask is determined by the current mask colour.
 895
 896 \membersection{wxImage::SetMaskColour}\label{wximagesetmaskcolour}
 897
 898 \func{void}{SetMaskColour}{\param{unsigned char }{red}, \param{unsigned char }{green}, \param{unsigned char }{blue}}
 899
 900 Sets the mask colour for this image (and tells the image to use the mask).
 901
 902 \membersection{wxImage::SetMaskFromImage}\label{wximagesetmaskfromimage}
 903
 904 \func{bool}{SetMaskFromImage}{\param{const wxImage\&}{ mask}, \param{unsigned char}{ mr}, \param{unsigned char}{ mg}, \param{unsigned char}{ mb}}
 905
 906 \wxheading{Parameters}
 907
 908 \docparam{mask}{The mask image to extract mask shape from. Must have same dimensions as the image.}
 909
 910 \docparam{mr,mg,mb}{RGB value of pixels in {\it mask} that will be used to create the mask.}
 911
 912 Sets image's mask so that the pixels that have RGB value of {\it mr,mg,mb}
 913 in {\it mask} will be masked in the image. This is done by first finding an
 914 unused colour in the image, setting this colour as the mask colour and then
 915 using this colour to draw all pixels in the image who corresponding pixel
 916 in {\it mask} has given RGB value.
 917
 918 \wxheading{Return value}
 919
 920 Returns false if {\it mask} does not have same dimensions as the image or if
 921 there is no unused colour left. Returns true if the mask was successfully
 922 applied.
 923
 924 \wxheading{Notes}
 925
 926 Note that this method involves computing the histogram, which is
 927 computationally intensive operation.
 928
 929 \membersection{wxImage::SetOption}\label{wximagesetoption}
 930
 931 \func{void}{SetOption}{\param{const wxString\&}{ name}, \param{const wxString\&}{ value}}
 932
 933 \func{void}{SetOption}{\param{const wxString\&}{ name}, \param{int}{ value}}
 934
 935 Sets a user-defined option. The function is case-insensitive to {\it name}.
 936
 937 For example, when saving as a JPEG file, the option {\bf quality} is
 938 used, which is a number between 0 and 100 (0 is terrible, 100 is very good).
 939
 940 \wxheading{See also}
 941
 942 \helpref{wxImage::GetOption}{wximagegetoption},\rtfsp
 943 \helpref{wxImage::GetOptionInt}{wximagegetoptionint},\rtfsp
 944 \helpref{wxImage::HasOption}{wximagehasoption}
 945
 946 \membersection{wxImage::SetPalette}\label{wximagesetpalette}
 947
 948 \func{void}{SetPalette}{\param{const wxPalette\&}{ palette}}
 949
 950 Associates a palette with the image. The palette may be used when converting
 951 wxImage to wxBitmap (MSW only at present) or in file save operations (none as yet).
 952
 953 \membersection{wxImage::SetRGB}\label{wximagesetrgb}
 954
 955 \func{void}{SetRGB}{\param{int }{x}, \param{int }{y}, \param{unsigned char }{red}, \param{unsigned char }{green}, \param{unsigned char }{blue}}
 956
 957 Sets the pixel at the given coordinate. This routine performs bounds-checks
 958 for the coordinate so it can be considered a safe way to manipulate the
 959 data, but in some cases this might be too slow so that the data will have to
 960 be set directly. In that case you will have to get access to the image data
 961 using the \helpref{GetData}{wximagegetdata} method.
 962
 963 \membersection{wxImage::operator $=$}
 964
 965 \func{wxImage\& }{operator $=$}{\param{const wxImage\& }{image}}
 966
 967 Assignment operator. This operator does not copy any data, but instead
 968 passes a pointer to the data in {\it image} and increments a reference
 969 counter. It is a fast operation.
 970
 971 \wxheading{Parameters}
 972
 973 \docparam{image}{Image to assign.}
 974
 975 \wxheading{Return value}
 976
 977 Returns 'this' object.
 978
 979 \membersection{wxImage::operator $==$}
 980
 981 \constfunc{bool}{operator $==$}{\param{const wxImage\& }{image}}
 982
 983 Equality operator. This operator tests whether the internal data pointers are
 984 equal (a fast test).
 985
 986 \wxheading{Parameters}
 987
 988 \docparam{image}{Image to compare with 'this'}
 989
 990 \wxheading{Return value}
 991
 992 Returns true if the images were effectively equal, false otherwise.
 993
 994 \membersection{wxImage::operator $!=$}
 995
 996 \constfunc{bool}{operator $!=$}{\param{const wxImage\& }{image}}
 997
 998 Inequality operator. This operator tests whether the internal data pointers are
 999 unequal (a fast test).
1000
1001 \wxheading{Parameters}
1002
1003 \docparam{image}{Image to compare with 'this'}
1004
1005 \wxheading{Return value}
1006
1007 Returns true if the images were unequal, false otherwise.
1008
1009 \section{\class{wxImageHandler}}\label{wximagehandler}
1010
1011 This is the base class for implementing image file loading/saving, and image creation from data.
1012 It is used within wxImage and is not normally seen by the application.
1013
1014 If you wish to extend the capabilities of wxImage, derive a class from wxImageHandler
1015 and add the handler using \helpref{wxImage::AddHandler}{wximageaddhandler} in your
1016 application initialisation.
1017
1018 \wxheading{Note (Legal Issue)}
1019
1020 This software is based in part on the work of the Independent JPEG Group.
1021
1022 (Applies when wxWindows is linked with JPEG support. wxJPEGHandler uses libjpeg
1023 created by IJG.)
1024
1025 \wxheading{Derived from}
1026
1027 \helpref{wxObject}{wxobject}
1028
1029 \wxheading{Include files}
1030
1031 <wx/image.h>
1032
1033 \wxheading{See also}
1034
1035 \helpref{wxImage}{wximage},
1036 \helpref{wxInitAllImageHandlers}{wxinitallimagehandlers}
1037
1038 \latexignore{\rtfignore{\wxheading{Members}}}
1039
1040 \membersection{wxImageHandler::wxImageHandler}\label{wximagehandlerconstr}
1041
1042 \func{}{wxImageHandler}{\void}
1043
1044 Default constructor. In your own default constructor, initialise the members
1045 m\_name, m\_extension and m\_type.
1046
1047 \membersection{wxImageHandler::\destruct{wxImageHandler}}
1048
1049 \func{}{\destruct{wxImageHandler}}{\void}
1050
1051 Destroys the wxImageHandler object.
1052
1053 \membersection{wxImageHandler::GetName}
1054
1055 \constfunc{wxString}{GetName}{\void}
1056
1057 Gets the name of this handler.
1058
1059 \membersection{wxImageHandler::GetExtension}
1060
1061 \constfunc{wxString}{GetExtension}{\void}
1062
1063 Gets the file extension associated with this handler.
1064
1065 \membersection{wxImageHandler::GetImageCount}\label{wximagehandlergetimagecount}
1066
1067 \func{int}{GetImageCount}{\param{wxInputStream\&}{ stream}}
1068
1069 If the image file contains more than one image and the image handler is capable
1070 of retrieving these individually, this function will return the number of
1071 available images.
1072
1073 \docparam{stream}{Opened input stream for reading image data. Currently, the stream must support seeking.}
1074
1075 \wxheading{Return value}
1076
1077 Number of available images. For most image handlers, this is 1 (exceptions
1078 are TIFF and ICO formats).
1079
1080 \membersection{wxImageHandler::GetType}
1081
1082 \constfunc{long}{GetType}{\void}
1083
1084 Gets the image type associated with this handler.
1085
1086 \membersection{wxImageHandler::GetMimeType}
1087
1088 \constfunc{wxString}{GetMimeType}{\void}
1089
1090 Gets the MIME type associated with this handler.
1091
1092 \membersection{wxImageHandler::LoadFile}\label{wximagehandlerloadfile}
1093
1094 \func{bool}{LoadFile}{\param{wxImage* }{image}, \param{wxInputStream\&}{ stream}, \param{bool}{ verbose=true}, \param{int}{ index=0}}
1095
1096 Loads a image from a stream, putting the resulting data into {\it image}. If the image file contains
1097 more than one image and the image handler is capable of retrieving these individually, {\it index}
1098 indicates which image to read from the stream.
1099
1100 \wxheading{Parameters}
1101
1102 \docparam{image}{The image object which is to be affected by this operation.}
1103
1104 \docparam{stream}{Opened input stream for reading image data.}
1105
1106 \docparam{verbose}{If set to true, errors reported by the image handler will produce wxLogMessages.}
1107
1108 \docparam{index}{The index of the image in the file (starting from zero).}
1109
1110 \wxheading{Return value}
1111
1112 true if the operation succeeded, false otherwise.
1113
1114 \wxheading{See also}
1115
1116 \helpref{wxImage::LoadFile}{wximageloadfile},
1117 \helpref{wxImage::SaveFile}{wximagesavefile},
1118 \helpref{wxImageHandler::SaveFile}{wximagehandlersavefile}
1119
1120 \membersection{wxImageHandler::SaveFile}\label{wximagehandlersavefile}
1121
1122 \func{bool}{SaveFile}{\param{wxImage* }{image}, \param{wxOutputStream\& }{stream}}
1123
1124 Saves a image in the output stream.
1125
1126 \wxheading{Parameters}
1127
1128 \docparam{image}{The image object which is to be affected by this operation.}
1129
1130 \docparam{stream}{Opened output stream for writing the data.}
1131
1132 \wxheading{Return value}
1133
1134 true if the operation succeeded, false otherwise.
1135
1136 \wxheading{See also}
1137
1138 \helpref{wxImage::LoadFile}{wximageloadfile},
1139 \helpref{wxImage::SaveFile}{wximagesavefile},
1140 \helpref{wxImageHandler::LoadFile}{wximagehandlerloadfile}
1141
1142 \membersection{wxImageHandler::SetName}
1143
1144 \func{void}{SetName}{\param{const wxString\& }{name}}
1145
1146 Sets the handler name.
1147
1148 \wxheading{Parameters}
1149
1150 \docparam{name}{Handler name.}
1151
1152 \membersection{wxImageHandler::SetExtension}
1153
1154 \func{void}{SetExtension}{\param{const wxString\& }{extension}}
1155
1156 Sets the handler extension.
1157
1158 \wxheading{Parameters}
1159
1160 \docparam{extension}{Handler extension.}
1161
1162 \membersection{wxImageHandler::SetMimeType}\label{wximagehandlersetmimetype}
1163
1164 \func{void}{SetMimeType}{\param{const wxString\& }{mimetype}}
1165
1166 Sets the handler MIME type.
1167
1168 \wxheading{Parameters}
1169
1170 \docparam{mimename}{Handler MIME type.}
1171
1172 \membersection{wxImageHandler::SetType}
1173
1174 \func{void}{SetType}{\param{long }{type}}
1175
1176 Sets the handler type.
1177
1178 \wxheading{Parameters}
1179
1180 \docparam{name}{Handler type.}
1181