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