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