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