1\section{\class{wxBitmap}}\label{wxbitmap} 2 3%\overview{Overview}{wxbitmapoverview} 4% 5This class encapsulates the concept of a platform-dependent bitmap, 6either monochrome or colour or colour with alpha channel support. 7 8\wxheading{Derived from} 9 10\helpref{wxGDIObject}{wxgdiobject}\\ 11\helpref{wxObject}{wxobject} 12 13\wxheading{Include files} 14 15<wx/bitmap.h> 16 17\wxheading{Predefined objects} 18 19Objects: 20 21{\bf wxNullBitmap} 22 23\wxheading{See also} 24 25\helpref{wxBitmap overview}{wxbitmapoverview}, 26\helpref{supported bitmap file formats}{supportedbitmapformats}, 27\helpref{wxDC::Blit}{wxdcblit}, 28\helpref{wxIcon}{wxicon}, \helpref{wxCursor}{wxcursor}, \helpref{wxBitmap}{wxbitmap}, 29\helpref{wxMemoryDC}{wxmemorydc} 30 31\latexignore{\rtfignore{\wxheading{Members}}} 32 33\membersection{wxBitmap::wxBitmap}\label{wxbitmapctor} 34 35\func{}{wxBitmap}{\void} 36 37Default constructor. 38 39\func{}{wxBitmap}{\param{const wxBitmap\& }{bitmap}} 40 41Copy constructor, uses \helpref{reference counting}{trefcount}. 42To make a real copy, you can use: 43 44\begin{verbatim} 45 wxBitmap newBitmap = oldBitmap.GetSubBitmap( 46 wxRect(0, 0, oldBitmap.GetWidth(), oldBitmap.GetHeight())); 47\end{verbatim} 48 49\func{}{wxBitmap}{\param{const void*}{ data}, \param{int}{ type}, \param{int}{ width}, \param{int}{ height}, \param{int}{ depth = -1}} 50 51Creates a bitmap from the given data which is interpreted in platform-dependent 52manner. 53 54\func{}{wxBitmap}{\param{const char}{ bits[]}, \param{int}{ width}, \param{int}{ height}\\ 55 \param{int}{ depth = 1}} 56 57Creates a bitmap from an array of bits. 58 59You should only use this function for monochrome bitmaps ({\it depth} 1) in 60portable programs: in this case the {\it bits} parameter should contain an XBM 61image. 62 63For other bit depths, the behaviour is platform dependent: under Windows, the 64data is passed without any changes to the underlying {\tt CreateBitmap()} API. 65Under other platforms, only monochrome bitmaps may be created using this 66constructor and \helpref{wxImage}{wximage} should be used for creating colour 67bitmaps from static data. 68 69\func{}{wxBitmap}{\param{int}{ width}, \param{int}{ height}, \param{int}{ depth = -1}} 70 71Creates a new bitmap. A depth of -1 indicates the depth of the current screen 72or visual. Some platforms only support 1 for monochrome and -1 for the current 73colour setting. Beginning with version 2.5.4 of wxWidgets a depth of 32 including 74an alpha channel is supported under MSW, Mac and GTK+. 75 76\func{}{wxBitmap}{\param{const char* const*}{ bits}} 77 78Creates a bitmap from XPM data. 79 80\func{}{wxBitmap}{\param{const wxString\& }{name}, \param{wxBitmapType}{ type}} 81 82Loads a bitmap from a file or resource. 83 84\func{}{wxBitmap}{\param{const wxImage\&}{ img}, \param{int}{ depth = -1}} 85 86Creates bitmap object from the image. This has to be done 87to actually display an image as you cannot draw an image directly on a window. 88The resulting bitmap will use the provided colour depth (or that of the 89current system if depth is -1) which entails that a colour reduction has 90to take place. 91 92When in 8-bit mode (PseudoColour mode), the GTK port will use a color cube created 93on program start-up to look up colors. This ensures a very fast conversion, but 94the image quality won't be perfect (and could be better for photo images using more 95sophisticated dithering algorithms). 96 97On Windows, if there is a palette present (set with SetPalette), it will be used when 98creating the wxBitmap (most useful in 8-bit display mode). On other platforms, 99the palette is currently ignored. 100 101\wxheading{Parameters} 102 103\docparam{bits}{Specifies an array of pixel values.} 104 105\docparam{width}{Specifies the width of the bitmap.} 106 107\docparam{height}{Specifies the height of the bitmap.} 108 109\docparam{depth}{Specifies the depth of the bitmap. If this is omitted, the display depth of the 110screen is used.} 111 112\docparam{name}{This can refer to a resource name under MS Windows, or a filename under MS Windows and X. 113Its meaning is determined by the {\it type} parameter.} 114 115\docparam{type}{May be one of the following: 116 117\twocolwidtha{5cm} 118\begin{twocollist} 119\twocolitem{\indexit{wxBITMAP\_TYPE\_BMP}}{Load a Windows bitmap file.} 120\twocolitem{\indexit{wxBITMAP\_TYPE\_BMP\_RESOURCE}}{Load a Windows bitmap resource from the executable. Windows only.} 121\twocolitem{\indexit{wxBITMAP\_TYPE\_PICT\_RESOURCE}}{Load a PICT image resource from the executable. Mac OS only.} 122\twocolitem{\indexit{wxBITMAP\_TYPE\_GIF}}{Load a GIF bitmap file.} 123\twocolitem{\indexit{wxBITMAP\_TYPE\_XBM}}{Load an X bitmap file.} 124\twocolitem{\indexit{wxBITMAP\_TYPE\_XPM}}{Load an XPM bitmap file.} 125\end{twocollist} 126 127The validity of these flags depends on the platform and wxWidgets configuration. 128If all possible wxWidgets settings are used, the Windows platform supports BMP file, BMP resource, 129XPM data, and XPM. Under wxGTK, the available formats are BMP file, XPM data, XPM file, and PNG file. 130Under wxMotif, the available formats are XBM data, XBM file, XPM data, XPM file. 131 132In addition, wxBitmap can read all formats that \helpref{wxImage}{wximage} can, which currently include 133wxBITMAP\_TYPE\_JPEG, wxBITMAP\_TYPE\_TIF, wxBITMAP\_TYPE\_PNG, wxBITMAP\_TYPE\_GIF, wxBITMAP\_TYPE\_PCX, 134and wxBITMAP\_TYPE\_PNM. Of course, you must have wxImage handlers loaded. } 135 136\docparam{img}{Platform-independent wxImage object.} 137 138\wxheading{Remarks} 139 140The first form constructs a bitmap object with no data; an assignment or another member function such as Create 141or LoadFile must be called subsequently. 142 143The second and third forms provide copy constructors. Note that these do not copy the 144bitmap data, but instead a pointer to the data, keeping a reference count. They are therefore 145very efficient operations. 146 147The fourth form constructs a bitmap from data whose type and value depends on 148the value of the {\it type} argument. 149 150The fifth form constructs a (usually monochrome) bitmap from an array of pixel values, under both 151X and Windows. 152 153The sixth form constructs a new bitmap. 154 155The seventh form constructs a bitmap from pixmap (XPM) data, if wxWidgets has been configured 156to incorporate this feature. 157 158To use this constructor, you must first include an XPM file. For 159example, assuming that the file {\tt mybitmap.xpm} contains an XPM array 160of character pointers called mybitmap: 161 162\begin{verbatim} 163#include "mybitmap.xpm" 164 165... 166 167wxBitmap *bitmap = new wxBitmap(mybitmap); 168\end{verbatim} 169 170The eighth form constructs a bitmap from a file or resource. {\it name} can refer 171to a resource name under MS Windows, or a filename under MS Windows and X. 172 173Under Windows, {\it type} defaults to wxBITMAP\_TYPE\_BMP\_RESOURCE. 174Under X, {\it type} defaults to wxBITMAP\_TYPE\_XPM. 175 176\wxheading{See also} 177 178\helpref{wxBitmap::LoadFile}{wxbitmaploadfile} 179 180\pythonnote{Constructors supported by wxPython are:\par 181\indented{2cm}{\begin{twocollist} 182\twocolitem{{\bf wxBitmap(name, flag)}}{Loads a bitmap from a file} 183\twocolitem{{\bf wxEmptyBitmap(width, height, depth = -1)}}{Creates an 184empty bitmap with the given specifications} 185\twocolitem{{\bf wxBitmapFromXPMData(listOfStrings)}}{Create a bitmap 186from a Python list of strings whose contents are XPM data.} 187\twocolitem{{\bf wxBitmapFromBits(bits, width, height, 188depth=-1)}}{Create a bitmap from an array of bits contained in a 189string.} 190\twocolitem{{\bf wxBitmapFromImage(image, depth=-1)}}{Convert a 191wxImage to a wxBitmap.} 192\end{twocollist}} 193} 194 195\perlnote{Constructors supported by wxPerl are:\par 196\begin{itemize} 197\item{Wx::Bitmap->new( width, height, depth = -1 )} 198\item{Wx::Bitmap->new( name, type )} 199\item{Wx::Bitmap->new( icon )} 200\item{Wx::Bitmap->newFromBits( bits, width, height, depth = 1 )} 201\item{Wx::Bitmap->newFromXPM( data )} 202\end{itemize} 203} 204 205\membersection{wxBitmap::\destruct{wxBitmap}}\label{wxbitmapdtor} 206 207\func{}{\destruct{wxBitmap}}{\void} 208 209Destructor. 210See \helpref{reference-counted object destruction}{refcountdestruct} for more info. 211 212If the application omits to delete the bitmap explicitly, the bitmap will be 213destroyed automatically by wxWidgets when the application exits. 214 215Do not delete a bitmap that is selected into a memory device context. 216 217\membersection{wxBitmap::AddHandler}\label{wxbitmapaddhandler} 218 219\func{static void}{AddHandler}{\param{wxBitmapHandler*}{ handler}} 220 221Adds a handler to the end of the static list of format handlers. 222 223\docparam{handler}{A new bitmap format handler object. There is usually only one instance 224of a given handler class in an application session.} 225 226\wxheading{See also} 227 228\helpref{wxBitmapHandler}{wxbitmaphandler} 229 230\membersection{wxBitmap::CleanUpHandlers}\label{wxbitmapcleanuphandlers} 231 232\func{static void}{CleanUpHandlers}{\void} 233 234Deletes all bitmap handlers. 235 236This function is called by wxWidgets on exit. 237 238\membersection{wxBitmap::ConvertToImage}\label{wxbitmapconverttoimage} 239 240\func{wxImage}{ConvertToImage}{\void} 241 242Creates an image from a platform-dependent bitmap. This preserves 243mask information so that bitmaps and images can be converted back 244and forth without loss in that respect. 245 246\membersection{wxBitmap::CopyFromIcon}\label{wxbitmapcopyfromicon} 247 248\func{bool}{CopyFromIcon}{\param{const wxIcon\&}{ icon}} 249 250Creates the bitmap from an icon. 251 252\membersection{wxBitmap::Create}\label{wxbitmapcreate} 253 254\func{virtual bool}{Create}{\param{int}{ width}, \param{int}{ height}, \param{int}{ depth = -1}} 255 256Creates a fresh bitmap. If the final argument is omitted, the display depth of 257the screen is used. 258 259\func{virtual bool}{Create}{\param{const void*}{ data}, \param{int}{ type}, \param{int}{ width}, \param{int}{ height}, \param{int}{ depth = -1}} 260 261Creates a bitmap from the given data, which can be of arbitrary type. 262 263\wxheading{Parameters} 264 265\docparam{width}{The width of the bitmap in pixels.} 266 267\docparam{height}{The height of the bitmap in pixels.} 268 269\docparam{depth}{The depth of the bitmap in pixels. If this is -1, the screen depth is used.} 270 271\docparam{data}{Data whose type depends on the value of {\it type}.} 272 273\docparam{type}{A bitmap type identifier - see \helpref{wxBitmap::wxBitmap}{wxbitmapctor} for a list 274of possible values.} 275 276\wxheading{Return value} 277 278true if the call succeeded, false otherwise. 279 280\wxheading{Remarks} 281 282The first form works on all platforms. The portability of the second form depends on the 283type of data. 284 285\wxheading{See also} 286 287\helpref{wxBitmap::wxBitmap}{wxbitmapctor} 288 289\membersection{wxBitmap::FindHandler}\label{wxbitmapfindhandler} 290 291\func{static wxBitmapHandler*}{FindHandler}{\param{const wxString\& }{name}} 292 293Finds the handler with the given name. 294 295\func{static wxBitmapHandler*}{FindHandler}{\param{const wxString\& }{extension}, \param{wxBitmapType}{ bitmapType}} 296 297Finds the handler associated with the given extension and type. 298 299\func{static wxBitmapHandler*}{FindHandler}{\param{wxBitmapType }{bitmapType}} 300 301Finds the handler associated with the given bitmap type. 302 303\docparam{name}{The handler name.} 304 305\docparam{extension}{The file extension, such as ``bmp".} 306 307\docparam{bitmapType}{The bitmap type, such as wxBITMAP\_TYPE\_BMP.} 308 309\wxheading{Return value} 310 311A pointer to the handler if found, NULL otherwise. 312 313\wxheading{See also} 314 315\helpref{wxBitmapHandler}{wxbitmaphandler} 316 317\membersection{wxBitmap::GetDepth}\label{wxbitmapgetdepth} 318 319\constfunc{int}{GetDepth}{\void} 320 321Gets the colour depth of the bitmap. A value of 1 indicates a 322monochrome bitmap. 323 324\membersection{wxBitmap::GetHandlers}\label{wxbitmapgethandlers} 325 326\func{static wxList\&}{GetHandlers}{\void} 327 328Returns the static list of bitmap format handlers. 329 330\wxheading{See also} 331 332\helpref{wxBitmapHandler}{wxbitmaphandler} 333 334\membersection{wxBitmap::GetHeight}\label{wxbitmapgetheight} 335 336\constfunc{int}{GetHeight}{\void} 337 338Gets the height of the bitmap in pixels. 339 340\membersection{wxBitmap::GetPalette}\label{wxbitmapgetpalette} 341 342\constfunc{wxPalette*}{GetPalette}{\void} 343 344Gets the associated palette (if any) which may have been loaded from a file 345or set for the bitmap. 346 347\wxheading{See also} 348 349\helpref{wxPalette}{wxpalette} 350 351\membersection{wxBitmap::GetMask}\label{wxbitmapgetmask} 352 353\constfunc{wxMask*}{GetMask}{\void} 354 355Gets the associated mask (if any) which may have been loaded from a file 356or set for the bitmap. 357 358\wxheading{See also} 359 360\helpref{wxBitmap::SetMask}{wxbitmapsetmask}, \helpref{wxMask}{wxmask} 361 362\membersection{wxBitmap::GetWidth}\label{wxbitmapgetwidth} 363 364\constfunc{int}{GetWidth}{\void} 365 366Gets the width of the bitmap in pixels. 367 368\wxheading{See also} 369 370\helpref{wxBitmap::GetHeight}{wxbitmapgetheight} 371 372\membersection{wxBitmap::GetSubBitmap}\label{wxbitmapgetsubbitmap} 373 374\constfunc{wxBitmap}{GetSubBitmap}{\param{const wxRect\&}{rect}} 375 376Returns a sub bitmap of the current one as long as the rect belongs entirely to 377the bitmap. This function preserves bit depth and mask information. 378 379\membersection{wxBitmap::InitStandardHandlers}\label{wxbitmapinitstandardhandlers} 380 381\func{static void}{InitStandardHandlers}{\void} 382 383Adds the standard bitmap format handlers, which, depending on wxWidgets 384configuration, can be handlers for Windows bitmap, Windows bitmap resource, and XPM. 385 386This function is called by wxWidgets on startup. 387 388\wxheading{See also} 389 390\helpref{wxBitmapHandler}{wxbitmaphandler} 391 392\membersection{wxBitmap::InsertHandler}\label{wxbitmapinserthandler} 393 394\func{static void}{InsertHandler}{\param{wxBitmapHandler*}{ handler}} 395 396Adds a handler at the start of the static list of format handlers. 397 398\docparam{handler}{A new bitmap format handler object. There is usually only one instance 399of a given handler class in an application session.} 400 401\wxheading{See also} 402 403\helpref{wxBitmapHandler}{wxbitmaphandler} 404 405\membersection{wxBitmap::LoadFile}\label{wxbitmaploadfile} 406 407\func{bool}{LoadFile}{\param{const wxString\&}{ name}, \param{wxBitmapType}{ type}} 408 409Loads a bitmap from a file or resource. 410 411\wxheading{Parameters} 412 413\docparam{name}{Either a filename or a Windows resource name. 414The meaning of {\it name} is determined by the {\it type} parameter.} 415 416\docparam{type}{One of the following values: 417 418\twocolwidtha{5cm} 419\begin{twocollist} 420\twocolitem{{\bf wxBITMAP\_TYPE\_BMP}}{Load a Windows bitmap file.} 421\twocolitem{{\bf wxBITMAP\_TYPE\_BMP\_RESOURCE}}{Load a Windows bitmap resource from the executable.} 422\twocolitem{{\bf wxBITMAP\_TYPE\_PICT\_RESOURCE}}{Load a PICT image resource from the executable. Mac OS only.} 423\twocolitem{{\bf wxBITMAP\_TYPE\_GIF}}{Load a GIF bitmap file.} 424\twocolitem{{\bf wxBITMAP\_TYPE\_XBM}}{Load an X bitmap file.} 425\twocolitem{{\bf wxBITMAP\_TYPE\_XPM}}{Load an XPM bitmap file.} 426\end{twocollist} 427 428The validity of these flags depends on the platform and wxWidgets configuration. 429 430In addition, wxBitmap can read all formats that \helpref{wxImage}{wximage} can 431(wxBITMAP\_TYPE\_JPEG, wxBITMAP\_TYPE\_PNG, wxBITMAP\_TYPE\_GIF, wxBITMAP\_TYPE\_PCX, wxBITMAP\_TYPE\_PNM). 432(Of course you must have wxImage handlers loaded.) } 433 434\wxheading{Return value} 435 436true if the operation succeeded, false otherwise. 437 438\wxheading{Remarks} 439 440A palette may be associated with the bitmap if one exists (especially for 441colour Windows bitmaps), and if the code supports it. You can check 442if one has been created by using the \helpref{GetPalette}{wxbitmapgetpalette} member. 443 444\wxheading{See also} 445 446\helpref{wxBitmap::SaveFile}{wxbitmapsavefile} 447 448\membersection{wxBitmap::IsOk}\label{wxbitmapisok} 449 450\constfunc{bool}{IsOk}{\void} 451 452Returns true if bitmap data is present. 453 454\membersection{wxBitmap::RemoveHandler}\label{wxbitmapremovehandler} 455 456\func{static bool}{RemoveHandler}{\param{const wxString\& }{name}} 457 458Finds the handler with the given name, and removes it. The handler 459is not deleted. 460 461\docparam{name}{The handler name.} 462 463\wxheading{Return value} 464 465true if the handler was found and removed, false otherwise. 466 467\wxheading{See also} 468 469\helpref{wxBitmapHandler}{wxbitmaphandler} 470 471\membersection{wxBitmap::SaveFile}\label{wxbitmapsavefile} 472 473\func{bool}{SaveFile}{\param{const wxString\& }{name}, \param{wxBitmapType}{ type}, \param{wxPalette* }{palette = NULL}} 474 475Saves a bitmap in the named file. 476 477\wxheading{Parameters} 478 479\docparam{name}{A filename. The meaning of {\it name} is determined by the {\it type} parameter.} 480 481\docparam{type}{One of the following values: 482 483\twocolwidtha{5cm} 484\begin{twocollist} 485\twocolitem{{\bf wxBITMAP\_TYPE\_BMP}}{Save a Windows bitmap file.} 486\twocolitem{{\bf wxBITMAP\_TYPE\_GIF}}{Save a GIF bitmap file.} 487\twocolitem{{\bf wxBITMAP\_TYPE\_XBM}}{Save an X bitmap file.} 488\twocolitem{{\bf wxBITMAP\_TYPE\_XPM}}{Save an XPM bitmap file.} 489\end{twocollist} 490 491The validity of these flags depends on the platform and wxWidgets configuration. 492 493In addition, wxBitmap can save all formats that \helpref{wxImage}{wximage} can 494(wxBITMAP\_TYPE\_JPEG, wxBITMAP\_TYPE\_PNG). 495(Of course you must have wxImage handlers loaded.) } 496 497\docparam{palette}{An optional palette used for saving the bitmap.} 498% TODO: this parameter should 499%probably be eliminated; instead the app should set the palette before saving. 500 501\wxheading{Return value} 502 503true if the operation succeeded, false otherwise. 504 505\wxheading{Remarks} 506 507Depending on how wxWidgets has been configured, not all formats may be available. 508 509\wxheading{See also} 510 511\helpref{wxBitmap::LoadFile}{wxbitmaploadfile} 512 513\membersection{wxBitmap::SetDepth}\label{wxbitmapsetdepth} 514 515\func{void}{SetDepth}{\param{int }{depth}} 516 517Sets the depth member (does not affect the bitmap data). 518 519\wxheading{Parameters} 520 521\docparam{depth}{Bitmap depth.} 522 523\membersection{wxBitmap::SetHeight}\label{wxbitmapsetheight} 524 525\func{void}{SetHeight}{\param{int }{height}} 526 527Sets the height member (does not affect the bitmap data). 528 529\wxheading{Parameters} 530 531\docparam{height}{Bitmap height in pixels.} 532 533\membersection{wxBitmap::SetMask}\label{wxbitmapsetmask} 534 535\func{void}{SetMask}{\param{wxMask* }{mask}} 536 537Sets the mask for this bitmap. 538 539\wxheading{Remarks} 540 541The bitmap object owns the mask once this has been called. 542 543\wxheading{See also} 544 545\helpref{wxBitmap::GetMask}{wxbitmapgetmask}, \helpref{wxMask}{wxmask} 546 547%% VZ: this function is an implementation detail and shouldn't be documented 548%%\membersection{wxBitmap::SetOk}\label{wxbitmapsetok} 549%% 550%%\func{void}{SetOk}{\param{int }{isOk}} 551%% 552%%Sets the validity member (does not affect the bitmap data). 553%% 554%%\wxheading{Parameters} 555%% 556%%\docparam{isOk}{Validity flag.} 557 558\membersection{wxBitmap::SetPalette}\label{wxbitmapsetpalette} 559 560\func{void}{SetPalette}{\param{const wxPalette\& }{palette}} 561 562Sets the associated palette. (Not implemented under GTK+). 563 564\wxheading{Parameters} 565 566\docparam{palette}{The palette to set.} 567 568\wxheading{See also} 569 570\helpref{wxPalette}{wxpalette} 571 572\membersection{wxBitmap::SetWidth}\label{wxbitmapsetwidth} 573 574\func{void}{SetWidth}{\param{int }{width}} 575 576Sets the width member (does not affect the bitmap data). 577 578\wxheading{Parameters} 579 580\docparam{width}{Bitmap width in pixels.} 581 582\membersection{wxBitmap::operator $=$}\label{wxbitmapassign} 583 584\func{wxBitmap\& }{operator $=$}{\param{const wxBitmap\& }{bitmap}} 585 586Assignment operator, using \helpref{reference counting}{trefcount}. 587 588\wxheading{Parameters} 589 590\docparam{bitmap}{Bitmap to assign.} 591 592\wxheading{Return value} 593 594Returns 'this' object. 595 596 597