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 GIF, 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 GIF and 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 GIF, 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 GIF and 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. If the optional index parameter is out of range,
 592 FALSE is returned and a call to wxLogError() takes place.
 593
 594 \wxheading{See also}
 595
 596 \helpref{wxImage::SaveFile}{wximagesavefile}
 597
 598 \pythonnote{In place of a single overloaded method name, wxPython
 599 implements the following methods:\par
 600 \indented{2cm}{\begin{twocollist}
 601 \twocolitem{{\bf LoadFile(filename, type)}}{Loads an image of the given
 602 type from a file}
 603 \twocolitem{{\bf LoadMimeFile(filename, mimetype)}}{Loads an image of the given
 604 mimetype from a file}
 605 \end{twocollist}}
 606 }
 607
 608 \perlnote{Methods supported by wxPerl are:\par
 609 \begin{itemize}
 610 \item{bitmap->LoadFile( name, type )}
 611 \item{bitmap->LoadFile( name, mimetype )}
 612 \end{itemize}
 613 }
 614
 615
 616 \membersection{wxImage::Ok}\label{wximageok}
 617
 618 \constfunc{bool}{Ok}{\void}
 619
 620 Returns TRUE if image data is present.
 621
 622 \membersection{wxImage::RemoveHandler}
 623
 624 \func{static bool}{RemoveHandler}{\param{const wxString\& }{name}}
 625
 626 Finds the handler with the given name, and removes it. The handler
 627 is not deleted.
 628
 629 \docparam{name}{The handler name.}
 630
 631 \wxheading{Return value}
 632
 633 TRUE if the handler was found and removed, FALSE otherwise.
 634
 635 \wxheading{See also}
 636
 637 \helpref{wxImageHandler}{wximagehandler}
 638
 639 \membersection{wxImage::SaveFile}\label{wximagesavefile}
 640
 641 \constfunc{bool}{SaveFile}{\param{const wxString\& }{name}, \param{int}{ type}}
 642
 643 \constfunc{bool}{SaveFile}{\param{const wxString\& }{name}, \param{const wxString\&}{ mimetype}}
 644
 645 Saves a image in the named file.
 646
 647 \constfunc{bool}{SaveFile}{\param{wxOutputStream\& }{stream}, \param{int}{ type}}
 648
 649 \constfunc{bool}{SaveFile}{\param{wxOutputStream\& }{stream}, \param{const wxString\&}{ mimetype}}
 650
 651 Saves a image in the given stream.
 652
 653 \wxheading{Parameters}
 654
 655 \docparam{name}{Name of the file to save the image to.}
 656
 657 \docparam{stream}{Opened output stream to save the image to.}
 658
 659 \docparam{type}{Currently three types can be used:
 660
 661 \twocolwidtha{5cm}%
 662 \begin{twocollist}
 663 \twocolitem{{\bf wxBITMAP\_TYPE\_JPEG}}{Save a JPEG image file.}
 664 \twocolitem{{\bf wxBITMAP\_TYPE\_PNG}}{Save a PNG image file.}
 665 \twocolitem{{\bf wxBITMAP\_TYPE\_PCX}}{Save a PCX image file (tries to save as 8-bit if possible, falls back to 24-bit otherwise).}
 666 \twocolitem{{\bf wxBITMAP\_TYPE\_PNM}}{Save a PNM image file (as raw RGB always).}
 667 \twocolitem{{\bf wxBITMAP\_TYPE\_TIFF}}{Save a TIFF image file.}
 668 \twocolitem{{\bf wxBITMAP\_TYPE\_XPM}}{Save a XPM image file.}
 669 \twocolitem{{\bf wxBITMAP\_TYPE\_ICO}}{Save a ICO image file. }
 670 \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).}
 671 \twocolitem{{\bf wxBITMAP\_TYPE\_CUR}}{Save a Windows cursor file (CUR).}
 672 \end{twocollist}}
 673
 674 \docparam{mimetype}{MIME type.}
 675
 676 \wxheading{Return value}
 677
 678 TRUE if the operation succeeded, FALSE otherwise.
 679
 680 \wxheading{Remarks}
 681
 682 Depending on how wxWindows has been configured, not all formats may be available.
 683
 684 Note: you can use \helpref{GetOptionInt}{wximagegetoptionint} to set the
 685 hotspot before saving an image into a cursor file (default hotspot is in
 686 the centre of the image):
 687 \begin{verbatim}
 688     image.SetOption(wxIMAGE_OPTION_CUR_HOTSPOT_X, hotspotX);
 689     image.SetOption(wxIMAGE_OPTION_CUR_HOTSPOT_Y, hotspotY);
 690
 691 \end{verbatim}
 692
 693 \wxheading{See also}
 694
 695 \helpref{wxImage::LoadFile}{wximageloadfile}
 696
 697 \pythonnote{In place of a single overloaded method name, wxPython
 698 implements the following methods:\par
 699 \indented{2cm}{\begin{twocollist}
 700 \twocolitem{{\bf SaveFile(filename, type)}}{Saves the image using the given
 701 type to the named file}
 702 \twocolitem{{\bf SaveMimeFile(filename, mimetype)}}{Saves the image using the given
 703 mimetype to the named file}
 704 \end{twocollist}}
 705 }
 706
 707 \perlnote{Methods supported by wxPerl are:\par
 708 \begin{itemize}
 709 \item{bitmap->SaveFile( name, type )}
 710 \item{bitmap->SaveFile( name, mimetype )}
 711 \end{itemize}
 712 }
 713
 714 \membersection{wxImage::Mirror}\label{wximagemirror}
 715
 716 \constfunc{wxImage}{Mirror}{\param{bool}{ horizontally = TRUE}}
 717
 718 Returns a mirrored copy of the image. The parameter {\it horizontally}
 719 indicates the orientation.
 720
 721 \membersection{wxImage::Replace}\label{wximagereplace}
 722
 723 \func{void}{Replace}{\param{unsigned char}{ r1}, \param{unsigned char}{ g1}, \param{unsigned char}{ b1},
 724 \param{unsigned char}{ r2}, \param{unsigned char}{ g2}, \param{unsigned char}{ b2}}
 725
 726 Replaces the colour specified by {\it r1,g1,b1} by the colour {\it r2,g2,b2}.
 727
 728 \membersection{wxImage::Rescale}\label{wximagerescale}
 729
 730 \func{wxImage \&}{Rescale}{\param{int}{ width}, \param{int}{ height}}
 731
 732 Changes the size of the image in-place: after a call to this function, the
 733 image will have the given width and height.
 734
 735 Returns the (modified) image itself.
 736
 737 \wxheading{See also}
 738
 739 \helpref{Scale}{wximagescale}
 740
 741 \membersection{wxImage::Rotate}\label{wximagerotate}
 742
 743 \func{wxImage}{Rotate}{\param{double}{ angle}, \param{const wxPoint\& }{rotationCentre},
 744  \param{bool}{ interpolating = TRUE}, \param{wxPoint*}{ offsetAfterRotation = NULL}}
 745
 746 Rotates the image about the given point, by {\it angle} radians. Passing TRUE
 747 to {\it interpolating} results in better image quality, but is slower. If the
 748 image has a mask, then the mask colour is used for the uncovered pixels in the
 749 rotated image background. Else, black (rgb 0, 0, 0) will be used.
 750
 751 Returns the rotated image, leaving this image intact.
 752
 753 \membersection{wxImage::Rotate90}\label{wximagerotate90}
 754
 755 \constfunc{wxImage}{Rotate90}{\param{bool}{ clockwise = TRUE}}
 756
 757 Returns a copy of the image rotated 90 degrees in the direction
 758 indicated by {\it clockwise}.
 759
 760 \membersection{wxImage::Scale}\label{wximagescale}
 761
 762 \constfunc{wxImage}{Scale}{\param{int}{ width}, \param{int}{ height}}
 763
 764 Returns a scaled version of the image. This is also useful for
 765 scaling bitmaps in general as the only other way to scale bitmaps
 766 is to blit a wxMemoryDC into another wxMemoryDC.
 767
 768 It may be mentioned that the GTK port uses this function internally
 769 to scale bitmaps when using mapping modes in wxDC.
 770
 771 Example:
 772
 773 \begin{verbatim}
 774     // get the bitmap from somewhere
 775     wxBitmap bmp = ...;
 776
 777     // rescale it to have size of 32*32
 778     if ( bmp.GetWidth() != 32 || bmp.GetHeight() != 32 )
 779     {
 780         wxImage image(bmp);
 781         bmp = wxBitmap(image.Scale(32, 32));
 782
 783         // another possibility:
 784         image.Rescale(32, 32);
 785         bmp = image;
 786     }
 787
 788 \end{verbatim}
 789
 790 \wxheading{See also}
 791
 792 \helpref{Rescale}{wximagerescale}
 793
 794 \membersection{wxImage::SetData}\label{wximagesetdata}
 795
 796 \func{void}{SetData}{\param{unsigned char*}{data}}
 797
 798 Sets the image data without performing checks. The data given must have
 799 the size (width*height*3) or results will be unexpected. Don't use this
 800 method if you aren't sure you know what you are doing.
 801
 802 \membersection{wxImage::SetMask}\label{wximagesetmask}
 803
 804 \func{void}{SetMask}{\param{bool}{ hasMask = TRUE}}
 805
 806 Specifies whether there is a mask or not. The area of the mask is determined by the current mask colour.
 807
 808 \membersection{wxImage::SetMaskColour}\label{wximagesetmaskcolour}
 809
 810 \func{void}{SetMaskColour}{\param{unsigned char }{red}, \param{unsigned char }{blue}, \param{unsigned char }{green}}
 811
 812 Sets the mask colour for this image (and tells the image to use the mask).
 813
 814 \membersection{wxImage::SetMaskFromImage}\label{wximagesetmaskfromimage}
 815
 816 \func{bool}{SetMaskFromImage}{\param{const wxImage\&}{ mask}, \param{unsigned char}{ mr}, \param{unsigned char}{ mg}, \param{unsigned char}{ mb}}
 817
 818 \wxheading{Parameters}
 819
 820 \docparam{mask}{The mask image to extract mask shape from. Must have same dimensions as the image.}
 821
 822 \docparam{mr,mg,mb}{RGB value of pixels in {\it mask} that will be used to create the mask.}
 823
 824 Sets image's mask so that the pixels that have RGB value of {\it mr,mg,mb}
 825 in {\it mask} will be masked in the image. This is done by first finding an
 826 unused colour in the image, setting this colour as the mask colour and then
 827 using this colour to draw all pixels in the image who corresponding pixel
 828 in {\it mask} has given RGB value.
 829
 830 \wxheading{Return value}
 831
 832 Returns FALSE if {\it mask} does not have same dimensions as the image or if
 833 there is no unused colour left. Returns TRUE if the mask was successfully
 834 applied.
 835
 836 \wxheading{Notes}
 837
 838 Note that this method involves computing the histogram, which is
 839 computationally intensive operation.
 840
 841 \membersection{wxImage::SetOption}\label{wximagesetoption}
 842
 843 \func{void}{SetOption}{\param{const wxString\&}{ name}, \param{const wxString\&}{ value}}
 844
 845 \func{void}{SetOption}{\param{const wxString\&}{ name}, \param{int}{ value}}
 846
 847 Sets a user-defined option. The function is case-insensitive to {\it name}.
 848
 849 For example, when saving as a JPEG file, the option {\bf quality} is
 850 used, which is a number between 0 and 100 (0 is terrible, 100 is very good).
 851
 852 \wxheading{See also}
 853
 854 \helpref{wxImage::GetOption}{wximagegetoption},\rtfsp
 855 \helpref{wxImage::GetOptionInt}{wximagegetoptionint},\rtfsp
 856 \helpref{wxImage::HasOption}{wximagehasoption}
 857
 858 \membersection{wxImage::SetPalette}\label{wximagesetpalette}
 859
 860 \func{void}{SetPalette}{\param{const wxPalette\&}{ palette}}
 861
 862 Associates a palette with the image. The palette may be used when converting
 863 wxImage to wxBitmap (MSW only at present) or in file save operations (none as yet).
 864
 865 \membersection{wxImage::SetRGB}\label{wximagesetrgb}
 866
 867 \func{void}{SetRGB}{\param{int }{x}, \param{int }{y}, \param{unsigned char }{red}, \param{unsigned char }{green}, \param{unsigned char }{blue}}
 868
 869 Sets the pixel at the given coordinate. This routine performs bounds-checks
 870 for the coordinate so it can be considered a safe way to manipulate the
 871 data, but in some cases this might be too slow so that the data will have to
 872 be set directly. In that case you will have to get access to the image data
 873 using the \helpref{GetData}{wximagegetdata} method.
 874
 875 \membersection{wxImage::operator $=$}
 876
 877 \func{wxImage\& }{operator $=$}{\param{const wxImage\& }{image}}
 878
 879 Assignment operator. This operator does not copy any data, but instead
 880 passes a pointer to the data in {\it image} and increments a reference
 881 counter. It is a fast operation.
 882
 883 \wxheading{Parameters}
 884
 885 \docparam{image}{Image to assign.}
 886
 887 \wxheading{Return value}
 888
 889 Returns 'this' object.
 890
 891 \membersection{wxImage::operator $==$}
 892
 893 \func{bool}{operator $==$}{\param{const wxImage\& }{image}}
 894
 895 Equality operator. This operator tests whether the internal data pointers are
 896 equal (a fast test).
 897
 898 \wxheading{Parameters}
 899
 900 \docparam{image}{Image to compare with 'this'}
 901
 902 \wxheading{Return value}
 903
 904 Returns TRUE if the images were effectively equal, FALSE otherwise.
 905
 906 \membersection{wxImage::operator $!=$}
 907
 908 \func{bool}{operator $!=$}{\param{const wxImage\& }{image}}
 909
 910 Inequality operator. This operator tests whether the internal data pointers are
 911 unequal (a fast test).
 912
 913 \wxheading{Parameters}
 914
 915 \docparam{image}{Image to compare with 'this'}
 916
 917 \wxheading{Return value}
 918
 919 Returns TRUE if the images were unequal, FALSE otherwise.
 920
 921 \section{\class{wxImageHandler}}\label{wximagehandler}
 922
 923 This is the base class for implementing image file loading/saving, and image creation from data.
 924 It is used within wxImage and is not normally seen by the application.
 925
 926 If you wish to extend the capabilities of wxImage, derive a class from wxImageHandler
 927 and add the handler using \helpref{wxImage::AddHandler}{wximageaddhandler} in your
 928 application initialisation.
 929
 930 \wxheading{Note (Legal Issue)}
 931
 932 This software is based in part on the work of the Independent JPEG Group.
 933
 934 (Applies when wxWindows is linked with JPEG support. wxJPEGHandler uses libjpeg
 935 created by IJG.)
 936
 937 \wxheading{Derived from}
 938
 939 \helpref{wxObject}{wxobject}
 940
 941 \wxheading{Include files}
 942
 943 <wx/image.h>
 944
 945 \wxheading{See also}
 946
 947 \helpref{wxImage}{wximage},
 948 \helpref{wxInitAllImageHandlers}{wxinitallimagehandlers}
 949
 950 \latexignore{\rtfignore{\wxheading{Members}}}
 951
 952 \membersection{wxImageHandler::wxImageHandler}\label{wximagehandlerconstr}
 953
 954 \func{}{wxImageHandler}{\void}
 955
 956 Default constructor. In your own default constructor, initialise the members
 957 m\_name, m\_extension and m\_type.
 958
 959 \membersection{wxImageHandler::\destruct{wxImageHandler}}
 960
 961 \func{}{\destruct{wxImageHandler}}{\void}
 962
 963 Destroys the wxImageHandler object.
 964
 965 \membersection{wxImageHandler::GetName}
 966
 967 \constfunc{wxString}{GetName}{\void}
 968
 969 Gets the name of this handler.
 970
 971 \membersection{wxImageHandler::GetExtension}
 972
 973 \constfunc{wxString}{GetExtension}{\void}
 974
 975 Gets the file extension associated with this handler.
 976
 977 \membersection{wxImageHandler::GetImageCount}\label{wximagehandlergetimagecount}
 978
 979 \func{int}{GetImageCount}{\param{wxInputStream\&}{ stream}}
 980
 981 If the image file contains more than one image and the image handler is capable
 982 of retrieving these individually, this function will return the number of
 983 available images.
 984
 985 \docparam{stream}{Opened input stream for reading image data. Currently, the stream must support seeking.}
 986
 987 \wxheading{Return value}
 988
 989 Number of available images. For most image handlers, this is 1 (exceptions
 990 are TIFF and ICO formats).
 991
 992 \membersection{wxImageHandler::GetType}
 993
 994 \constfunc{long}{GetType}{\void}
 995
 996 Gets the image type associated with this handler.
 997
 998 \membersection{wxImageHandler::GetMimeType}
 999
1000 \constfunc{wxString}{GetMimeType}{\void}
1001
1002 Gets the MIME type associated with this handler.
1003
1004 \membersection{wxImageHandler::LoadFile}\label{wximagehandlerloadfile}
1005
1006 \func{bool}{LoadFile}{\param{wxImage* }{image}, \param{wxInputStream\&}{ stream}, \param{bool}{ verbose=TRUE}, \param{int}{ index=0}}
1007
1008 Loads a image from a stream, putting the resulting data into {\it image}. If the image file contains
1009 more than one image and the image handler is capable of retrieving these individually, {\it index}
1010 indicates which image to read from the stream.
1011
1012 \wxheading{Parameters}
1013
1014 \docparam{image}{The image object which is to be affected by this operation.}
1015
1016 \docparam{stream}{Opened input stream for reading image data.}
1017
1018 \docparam{verbose}{If set to TRUE, errors reported by the image handler will produce wxLogMessages.}
1019
1020 \docparam{index}{The index of the image in the file (starting from zero).}
1021
1022 \wxheading{Return value}
1023
1024 TRUE if the operation succeeded, FALSE otherwise.
1025
1026 \wxheading{See also}
1027
1028 \helpref{wxImage::LoadFile}{wximageloadfile},
1029 \helpref{wxImage::SaveFile}{wximagesavefile},
1030 \helpref{wxImageHandler::SaveFile}{wximagehandlersavefile}
1031
1032 \membersection{wxImageHandler::SaveFile}\label{wximagehandlersavefile}
1033
1034 \func{bool}{SaveFile}{\param{wxImage* }{image}, \param{wxOutputStream\& }{stream}}
1035
1036 Saves a image in the output stream.
1037
1038 \wxheading{Parameters}
1039
1040 \docparam{image}{The image object which is to be affected by this operation.}
1041
1042 \docparam{stream}{Opened output stream for writing the data.}
1043
1044 \wxheading{Return value}
1045
1046 TRUE if the operation succeeded, FALSE otherwise.
1047
1048 \wxheading{See also}
1049
1050 \helpref{wxImage::LoadFile}{wximageloadfile},
1051 \helpref{wxImage::SaveFile}{wximagesavefile},
1052 \helpref{wxImageHandler::LoadFile}{wximagehandlerloadfile}
1053
1054 \membersection{wxImageHandler::SetName}
1055
1056 \func{void}{SetName}{\param{const wxString\& }{name}}
1057
1058 Sets the handler name.
1059
1060 \wxheading{Parameters}
1061
1062 \docparam{name}{Handler name.}
1063
1064 \membersection{wxImageHandler::SetExtension}
1065
1066 \func{void}{SetExtension}{\param{const wxString\& }{extension}}
1067
1068 Sets the handler extension.
1069
1070 \wxheading{Parameters}
1071
1072 \docparam{extension}{Handler extension.}
1073
1074 \membersection{wxImageHandler::SetMimeType}\label{wximagehandlersetmimetype}
1075
1076 \func{void}{SetMimeType}{\param{const wxString\& }{mimetype}}
1077
1078 Sets the handler MIME type.
1079
1080 \wxheading{Parameters}
1081
1082 \docparam{mimename}{Handler MIME type.}
1083
1084 \membersection{wxImageHandler::SetType}
1085
1086 \func{void}{SetType}{\param{long }{type}}
1087
1088 Sets the handler type.
1089
1090 \wxheading{Parameters}
1091
1092 \docparam{name}{Handler type.}
1093