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