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 the constructor taking a wxBitmap object. 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 wxDC. Instead, a platform-specific
  10 wxBitmap object must be created from it, and that bitmap drawn on the wxDC, using
  11 wxDC::DrawBitmap.
  12
  13 \wxheading{Derived from}
  14
  15 \helpref{wxObject}{wxobject}
  16
  17 \wxheading{See also}
  18
  19 \helpref{wxBitmap}{wxbitmap}
  20
  21 \latexignore{\rtfignore{\wxheading{Members}}}
  22
  23 \membersection{wxImage::wxImage}\label{wximageconstr}
  24
  25 \func{}{wxImage}{\void}
  26
  27 Default constructor.
  28
  29 \func{}{wxImage}{\param{const wxImage\& }{image}}
  30
  31 Copy constructor.
  32
  33 \func{}{wxImage}{\param{const wxBitmap\&}{ bitmap}}
  34
  35 Constructs an image from a platform-dependent bitmap. This preserves
  36 mask information so that bitmaps and images can be converted back
  37 and forth without loss in that respect.
  38
  39 \func{}{wxImage}{\param{int}{ width}, \param{int}{ height}}
  40
  41 Creates an image with the given width and height.
  42
  43 \func{}{wxImage}{\param{const wxString\& }{name}, \param{long}{ type = wxBITMAP\_TYPE\_PNG}}
  44
  45 Loads an image from a file.
  46
  47 \func{}{wxImage}{\param{wxInputStream\& }{stream}, \param{long}{ type = wxBITMAP\_TYPE\_PNG}}
  48
  49 Loads an image from an input stream.
  50
  51 \wxheading{Parameters}
  52
  53 \docparam{width}{Specifies the width of the image.}
  54
  55 \docparam{height}{Specifies the height of the image.}
  56
  57 \docparam{name}{This refers to an image filename. Its meaning is determined by the {\it type} parameter.}
  58
  59 \docparam{stream}{This refers to an input stream. Its meaning is determined by the {\it type} parameter. It is equal to loading from file except that you provide opened stream (file, HTTP or any other custom class).}
  60
  61 \docparam{type}{May be one of the following:
  62
  63 \twocolwidtha{5cm}%
  64 \begin{twocollist}
  65 \twocolitem{{\bf \indexit{wxBITMAP\_TYPE\_BMP}}}{Load a Windows bitmap file.}
  66 \twocolitem{{\bf \indexit{wxBITMAP\_TYPE\_PNG}}}{Load a PNG bitmap file.}
  67 \end{twocollist}
  68
  69 The validity of these flags depends on the platform and wxWindows configuration.
  70 If all possible wxWindows settings are used, the loading a BMP (Windows bitmap) file
  71 and a PNG (portable network graphics) file is supported on all platforms that
  72 implement wxImage.}
  73
  74 \wxheading{See also}
  75
  76 \helpref{wxImage::LoadFile}{wximageloadfile}
  77
  78 \membersection{wxImage::\destruct{wxImage}}
  79
  80 \func{}{\destruct{wxImage}}{\void}
  81
  82 Destructor.
  83
  84 \membersection{wxImage::AddHandler}\label{wximageaddhandler}
  85
  86 \func{static void}{AddHandler}{\param{wxImageHandler*}{ handler}}
  87
  88 Adds a handler to the end of the static list of format handlers.
  89
  90 \docparam{handler}{A new image format handler object. There is usually only one instance
  91 of a given handler class in an application session.}
  92
  93 \wxheading{See also}
  94
  95 \helpref{wxImageHandler}{wximagehandler}
  96
  97 \membersection{wxImage::CleanUpHandlers}
  98
  99 \func{static void}{CleanUpHandlers}{\void}
 100
 101 Deletes all image handlers.
 102
 103 This function is called by wxWindows on exit.
 104
 105 \membersection{wxImage::ConvertToBitmap}\label{wximageconverttobitmap}
 106
 107 \constfunc{wxBitmap}{ConvertToBitmap}{\void}
 108
 109 Converts the image to a platform-specific bitmap object. This has to be done
 110 to actually display an image as you cannot draw an image directly on a window.
 111 The resulting bitmap will use the colour depth of the current system which entails
 112 that a (crude) colour reduction has to take place. When in 8-bit mode, this
 113 routine will use a color cube created on program start-up to look up colors.
 114 Still, the image quality won't be perfect for photo images.
 115
 116 \membersection{wxImage::Create}\label{wximagecreate}
 117
 118 \func{bool}{Create}{\param{int}{ width}, \param{int}{ height}}
 119
 120 Creates a fresh image.
 121
 122 \wxheading{Parameters}
 123
 124 \docparam{width}{The width of the image in pixels.}
 125
 126 \docparam{height}{The height of the image in pixels.}
 127
 128 \wxheading{Return value}
 129
 130 TRUE if the call succeeded, FALSE otherwise.
 131
 132 \membersection{wxImage::Destroy}\label{wximagedestroy}
 133
 134 \func{bool}{Destroy}{\void}
 135
 136 Destroys the image data.
 137
 138 \membersection{wxImage::FindHandler}
 139
 140 \func{static wxImageHandler*}{FindHandler}{\param{const wxString\& }{name}}
 141
 142 Finds the handler with the given name.
 143
 144 \func{static wxImageHandler*}{FindHandler}{\param{const wxString\& }{extension}, \param{long}{ imageType}}
 145
 146 Finds the handler associated with the given extension and type.
 147
 148 \func{static wxImageHandler*}{FindHandler}{\param{long }{imageType}}
 149
 150 Finds the handler associated with the given image type.
 151
 152 \docparam{name}{The handler name.}
 153
 154 \docparam{extension}{The file extension, such as ``bmp".}
 155
 156 \docparam{imageType}{The image type, such as wxBITMAP\_TYPE\_BMP.}
 157
 158 \wxheading{Return value}
 159
 160 A pointer to the handler if found, NULL otherwise.
 161
 162 \wxheading{See also}
 163
 164 \helpref{wxImageHandler}{wximagehandler}
 165
 166 \membersection{wxImage::GetBlue}\label{wximagegetblue}
 167
 168 \constfunc{unsigned char}{GetBlue}{\param{int}{ x}, \param{int}{ y}}
 169
 170 Returns the blue intensity at the given coordinate.
 171
 172 \membersection{wxImage::GetData}\label{wximagegetdata}
 173
 174 \constfunc{unsigned char*}{GetData}{\void}
 175
 176 Returns the image data as an array. This is most often used when doing
 177 direct image manipulation. The return value points to an array of
 178 chararcters in RGBGBRGB... format.
 179
 180 \membersection{wxImage::GetGreen}\label{wximagegetgreen}
 181
 182 \constfunc{unsigned char}{GetGreen}{\param{int}{ x}, \param{int}{ y}}
 183
 184 Returns the green intensity at the given coordinate.
 185
 186 \membersection{wxImage::GetRed}\label{wximagegetred}
 187
 188 \constfunc{unsigned char}{GetRed}{\param{int}{ x}, \param{int}{ y}}
 189
 190 Returns the red intensity at the given coordinate.
 191
 192 \membersection{wxImage::GetHandlers}
 193
 194 \func{static wxList\&}{GetHandlers}{\void}
 195
 196 Returns the static list of image format handlers.
 197
 198 \wxheading{See also}
 199
 200 \helpref{wxImageHandler}{wximagehandler}
 201
 202 \membersection{wxImage::GetHeight}\label{wximagegetheight}
 203
 204 \constfunc{int}{GetHeight}{\void}
 205
 206 Gets the height of the image in pixels.
 207
 208 \membersection{wxImage::GetMaskBlue}\label{wximagegetmaskblue}
 209
 210 \constfunc{unsigned char}{GetMaskBlue}{\void}
 211
 212 Gets the blue value of the mask colour.
 213
 214 \membersection{wxImage::GetMaskGreen}\label{wximagegetmaskgreen}
 215
 216 \constfunc{unsigned char}{GetMaskGreen}{\void}
 217
 218 Gets the green value of the mask colour.
 219
 220 \membersection{wxImage::GetMaskRed}\label{wximagegetmaskred}
 221
 222 \constfunc{unsigned char}{GetMaskRed}{\void}
 223
 224 Gets the red value of the mask colour.
 225
 226 \membersection{wxImage::GetWidth}\label{wximagegetwidth}
 227
 228 \constfunc{int}{GetWidth}{\void}
 229
 230 Gets the width of the image in pixels.
 231
 232 \wxheading{See also}
 233
 234 \helpref{wxImage::GetHeight}{wximagegetheight}
 235
 236 \membersection{wxImage::HasMask}\label{wximagehasmask}
 237
 238 \constfunc{bool}{HasMask}{\void}
 239
 240 Returns TRUE if there is a mask active, FALSE otherwise.
 241
 242 \membersection{wxImage::InitStandardHandlers}
 243
 244 \func{static void}{InitStandardHandlers}{\void}
 245
 246 Adds the standard image format handlers, which, depending on wxWindows
 247 configuration, can be handlers for Windows BMP (loading) and PNG
 248 (loading and saving) file formats.
 249
 250 This function is called by wxWindows on startup.
 251
 252 \wxheading{See also}
 253
 254 \helpref{wxImageHandler}{wximagehandler}
 255
 256 \membersection{wxImage::InsertHandler}
 257
 258 \func{static void}{InsertHandler}{\param{wxImageHandler*}{ handler}}
 259
 260 Adds a handler at the start of the static list of format handlers.
 261
 262 \docparam{handler}{A new image format handler object. There is usually only one instance
 263 of a given handler class in an application session.}
 264
 265 \wxheading{See also}
 266
 267 \helpref{wxImageHandler}{wximagehandler}
 268
 269 \membersection{wxImage::LoadFile}\label{wximageloadfile}
 270
 271 \func{bool}{LoadFile}{\param{const wxString\&}{ name}, \param{long}{ type}}
 272
 273 Loads an image from a file.
 274
 275 \func{bool}{LoadFile}{\param{wxInputStream\&}{ stream}, \param{long}{ type}}
 276
 277 Loads an image from an input stream.
 278
 279 \wxheading{Parameters}
 280
 281 \docparam{name}{A filename.
 282 The meaning of {\it name} is determined by the {\it type} parameter.}
 283
 284 \docparam{stream}{An input stream.
 285 The meaning of {\it stream} data is determined by the {\it type} parameter.}
 286
 287 \docparam{type}{One of the following values:
 288
 289 \twocolwidtha{5cm}%
 290 \begin{twocollist}
 291 \twocolitem{{\bf wxBITMAP\_TYPE\_BMP}}{Load a Windows image file.}
 292 \twocolitem{{\bf wxBITMAP\_TYPE\_PNG}}{Load a PNG image file.}
 293 \end{twocollist}
 294
 295 The validity of these flags depends on the platform and wxWindows configuration.}
 296
 297 \wxheading{Return value}
 298
 299 TRUE if the operation succeeded, FALSE otherwise.
 300
 301 \wxheading{See also}
 302
 303 \helpref{wxImage::SaveFile}{wximagesavefile}
 304
 305 \membersection{wxImage::Ok}\label{wximageok}
 306
 307 \constfunc{bool}{Ok}{\void}
 308
 309 Returns TRUE if image data is present.
 310
 311 \membersection{wxImage::RemoveHandler}
 312
 313 \func{static bool}{RemoveHandler}{\param{const wxString\& }{name}}
 314
 315 Finds the handler with the given name, and removes it. The handler
 316 is not deleted.
 317
 318 \docparam{name}{The handler name.}
 319
 320 \wxheading{Return value}
 321
 322 TRUE if the handler was found and removed, FALSE otherwise.
 323
 324 \wxheading{See also}
 325
 326 \helpref{wxImageHandler}{wximagehandler}
 327
 328 \membersection{wxImage::SaveFile}\label{wximagesavefile}
 329
 330 \func{bool}{SaveFile}{\param{const wxString\& }{name}, \param{int}{ type}}
 331
 332 Saves a image in the named file.
 333
 334 \func{bool}{SaveFile}{\param{wxOutputStream\& }{stream}, \param{int}{ type}}
 335
 336 Saves a image in the given stream.
 337
 338 \wxheading{Parameters}
 339
 340 \docparam{name}{A filename. The meaning of {\it name} is determined by the {\it type} parameter.}
 341
 342 \docparam{stream}{An output stream. The meaning of {\it stream} is determined by the {\it type} parameter.}
 343
 344 \docparam{type}{Currently only one type can be used:
 345
 346 \twocolwidtha{5cm}%
 347 \begin{twocollist}
 348 \twocolitem{{\bf wxBITMAP\_TYPE\_PNG}}{Save a PNG image file.}
 349 \end{twocollist}
 350
 351 The validity of these flags depends on the platform and wxWindows configuration
 352 as well as user-added handlers.}
 353
 354 \wxheading{Return value}
 355
 356 TRUE if the operation succeeded, FALSE otherwise.
 357
 358 \wxheading{Remarks}
 359
 360 Depending on how wxWindows has been configured, not all formats may be available.
 361
 362 \wxheading{See also}
 363
 364 \helpref{wxImage::LoadFile}{wximageloadfile}
 365
 366 \membersection{wxImage::Scale}\label{wximagescale}
 367
 368 \func{wxImage}{Scale}{\param{int}{ width}, \param{int}{ height}}
 369
 370 Returns a scaled version of the image. This is also useful for
 371 scaling bitmaps in general as the only other way to scale bitmaps
 372 is to blit a wxMemoryDC into another wxMemoryDC. Windows can do such
 373 scaling itself but in the GTK port, scaling bitmaps is done using
 374 this routine internally.
 375
 376 \membersection{wxImage::SetData}\label{wximagesetdata}
 377
 378 \func{void}{SetData}{\param{unsigned char*}{data}}
 379
 380 Sets the image data without performing checks. The data given must have
 381 the size (width*height*3) or results will be unexpected. Don't use this
 382 method if you aren't sure you know what you are doing.
 383
 384 \membersection{wxImage::SetMask}\label{wximagesetmask}
 385
 386 \func{void}{SetMask}{\param{bool}{ hasMask = TRUE}}
 387
 388 Specifies whether there is a mask or not. The area of the mask is determined by the current mask colour.
 389
 390 \membersection{wxImage::SetMaskColour}\label{wximagesetmaskcolour}
 391
 392 \func{void}{SetMaskColour}{\param{unsigned char }{red}, \param{unsigned char }{blue}, \param{unsigned char }{green}}
 393
 394 Sets the mask colour for this image (and tells the image to use the mask).
 395
 396 \membersection{wxImage::SetRGB}\label{wximagesetrgb}
 397
 398 \func{void}{SetRGB}{\param{int }{x}, \param{int }{y}, \param{unsigned char }{red}, \param{unsigned char }{blue}, \param{unsigned char }{green}}
 399
 400 Sets the pixel at the given coordinate. This routine performs bounds-checks
 401 for the coordinate so it can be considered a safe way to manipulate the
 402 data, but in some cases this might be too slow so that the data will have to
 403 be set directly. In that case you have to get that data by calling GetData().
 404
 405 \membersection{wxImage::operator $=$}
 406
 407 \func{wxImage\& }{operator $=$}{\param{const wxImage\& }{image}}
 408
 409 Assignment operator. This operator does not copy any data, but instead
 410 passes a pointer to the data in {\it image} and increments a reference
 411 counter. It is a fast operation.
 412
 413 \wxheading{Parameters}
 414
 415 \docparam{image}{Image to assign.}
 416
 417 \wxheading{Return value}
 418
 419 Returns 'this' object.
 420
 421 \membersection{wxImage::operator $==$}
 422
 423 \func{bool}{operator $==$}{\param{const wxImage\& }{image}}
 424
 425 Equality operator. This operator tests whether the internal data pointers are
 426 equal (a fast test).
 427
 428 \wxheading{Parameters}
 429
 430 \docparam{image}{Image to compare with 'this'}
 431
 432 \wxheading{Return value}
 433
 434 Returns TRUE if the images were effectively equal, FALSE otherwise.
 435
 436 \membersection{wxImage::operator $!=$}
 437
 438 \func{bool}{operator $!=$}{\param{const wxImage\& }{image}}
 439
 440 Inequality operator. This operator tests whether the internal data pointers are
 441 unequal (a fast test).
 442
 443 \wxheading{Parameters}
 444
 445 \docparam{image}{Image to compare with 'this'}
 446
 447 \wxheading{Return value}
 448
 449 Returns TRUE if the images were unequal, FALSE otherwise.
 450
 451 \section{\class{wxImageHandler}}\label{wximagehandler}
 452
 453 This is the base class for implementing image file loading/saving, and image creation from data.
 454 It is used within wxImage and is not normally seen by the application.
 455
 456 If you wish to extend the capabilities of wxImage, derive a class from wxImageHandler
 457 and add the handler using \helpref{wxImage::AddHandler}{wximageaddhandler} in your
 458 application initialisation.
 459
 460 \wxheading{Derived from}
 461
 462 \helpref{wxObject}{wxobject}
 463
 464 \wxheading{See also}
 465
 466 \helpref{wxImage}{wximage}
 467
 468 \latexignore{\rtfignore{\wxheading{Members}}}
 469
 470 \membersection{wxImageHandler::wxImageHandler}\label{wximagehandlerconstr}
 471
 472 \func{}{wxImageHandler}{\void}
 473
 474 Default constructor. In your own default constructor, initialise the members
 475 m\_name, m\_extension and m\_type.
 476
 477 \membersection{wxImageHandler::\destruct{wxImageHandler}}
 478
 479 \func{}{\destruct{wxImageHandler}}{\void}
 480
 481 Destroys the wxImageHandler object.
 482
 483 \membersection{wxImageHandler::GetName}
 484
 485 \constfunc{wxString}{GetName}{\void}
 486
 487 Gets the name of this handler.
 488
 489 \membersection{wxImageHandler::GetExtension}
 490
 491 \constfunc{wxString}{GetExtension}{\void}
 492
 493 Gets the file extension associated with this handler.
 494
 495 \membersection{wxImageHandler::GetType}
 496
 497 \constfunc{long}{GetType}{\void}
 498
 499 Gets the image type associated with this handler.
 500
 501 \membersection{wxImageHandler::LoadFile}\label{wximagehandlerloadfile}
 502
 503 \func{bool}{LoadFile}{\param{wxImage* }{image}, \param{wxInputStream\&}{ stream}}
 504
 505 Loads a image from a stream, putting the resulting data into {\it image}.
 506
 507 \wxheading{Parameters}
 508
 509 \docparam{image}{The image object which is to be affected by this operation.}
 510
 511 \docparam{stream}{Opened input stream.
 512 The meaning of {\it stream} is determined by the {\it type} parameter.}
 513
 514 \wxheading{Return value}
 515
 516 TRUE if the operation succeeded, FALSE otherwise.
 517
 518 \wxheading{See also}
 519
 520 \helpref{wxImage::LoadFile}{wximageloadfile}\\
 521 \helpref{wxImage::SaveFile}{wximagesavefile}\\
 522 \helpref{wxImageHandler::SaveFile}{wximagehandlersavefile}
 523
 524 \membersection{wxImageHandler::SaveFile}\label{wximagehandlersavefile}
 525
 526 \func{bool}{SaveFile}{\param{wxImage* }{image}, \param{wxOutputStream\& }{stream}}
 527
 528 Saves a image in the output stream.
 529
 530 \wxheading{Parameters}
 531
 532 \docparam{image}{The image object which is to be affected by this operation.}
 533
 534 \docparam{stream}{A stream. The meaning of {\it stream} is determined by the {\it type} parameter.}
 535
 536 \wxheading{Return value}
 537
 538 TRUE if the operation succeeded, FALSE otherwise.
 539
 540 \wxheading{See also}
 541
 542 \helpref{wxImage::LoadFile}{wximageloadfile}\\
 543 \helpref{wxImage::SaveFile}{wximagesavefile}\\
 544 \helpref{wxImageHandler::LoadFile}{wximagehandlerloadfile}
 545
 546 \membersection{wxImageHandler::SetName}
 547
 548 \func{void}{SetName}{\param{const wxString\& }{name}}
 549
 550 Sets the handler name.
 551
 552 \wxheading{Parameters}
 553
 554 \docparam{name}{Handler name.}
 555
 556 \membersection{wxImageHandler::SetExtension}
 557
 558 \func{void}{SetExtension}{\param{const wxString\& }{extension}}
 559
 560 Sets the handler extension.
 561
 562 \wxheading{Parameters}
 563
 564 \docparam{extension}{Handler extension.}
 565
 566 \membersection{wxImageHandler::SetType}
 567
 568 \func{void}{SetType}{\param{long }{type}}
 569
 570 Sets the handler type.
 571
 572 \wxheading{Parameters}
 573
 574 \docparam{name}{Handler type.}
 575