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