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