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