1 \section{\class{wxBitmap
}}\label{wxbitmap
}
3 %\overview{Overview}{wxbitmapoverview}
5 This class encapsulates the concept of a platform-dependent bitmap,
6 either monochrome or colour.
8 \wxheading{Derived from
}
10 \helpref{wxGDIObject
}{wxgdiobject
}\\
11 \helpref{wxObject
}{wxobject
}
13 \wxheading{Include files
}
19 \helpref{wxBitmap overview
}{wxbitmapoverview
},
20 \helpref{supported bitmap file formats
}{supportedbitmapformats
},
21 \helpref{wxDC::Blit
}{wxdcblit
},
22 \helpref{wxIcon
}{wxicon
},
\helpref{wxCursor
}{wxcursor
},
\helpref{wxBitmap
}{wxbitmap
},
23 \helpref{wxMemoryDC
}{wxmemorydc
}
25 \latexignore{\rtfignore{\wxheading{Members
}}}
27 \membersection{wxBitmap::wxBitmap
}\label{wxbitmapconstr
}
29 \func{}{wxBitmap
}{\void}
33 \func{}{wxBitmap
}{\param{const wxBitmap\&
}{bitmap
}}
37 \func{}{wxBitmap
}{\param{void*
}{ data
},
\param{int
}{ type
},
\param{int
}{ width
},
\param{int
}{ height
},
\param{int
}{ depth = -
1}}
39 Creates a bitmap from the given data, which can be of arbitrary type.
41 \func{}{wxBitmap
}{\param{const char
}{ bits
[]},
\param{int
}{ width
},
\param{int
}{ height
}\\
42 \param{int
}{ depth =
1}}
44 Creates a bitmap from an array of bits.
46 \func{}{wxBitmap
}{\param{int
}{ width
},
\param{int
}{ height
},
\param{int
}{ depth = -
1}}
50 \func{}{wxBitmap
}{\param{const char**
}{ bits
}}
52 Creates a bitmap from XPM data.
54 \func{}{wxBitmap
}{\param{const wxString\&
}{name
},
\param{long
}{ type
}}
56 Loads a bitmap from a file or resource.
58 \wxheading{Parameters
}
60 \docparam{bits
}{Specifies an array of pixel values.
}
62 \docparam{width
}{Specifies the width of the bitmap.
}
64 \docparam{height
}{Specifies the height of the bitmap.
}
66 \docparam{depth
}{Specifies the depth of the bitmap. If this is omitted, the display depth of the
69 \docparam{name
}{This can refer to a resource name under MS Windows, or a filename under MS Windows and X.
70 Its meaning is determined by the
{\it type
} parameter.
}
72 \docparam{type
}{May be one of the following:
76 \twocolitem{{\bf \indexit{wxBITMAP
\_TYPE\_BMP}}}{Load a Windows bitmap file.
}
77 \twocolitem{{\bf \indexit{wxBITMAP
\_TYPE\_BMP\_RESOURCE}}}{Load a Windows bitmap from the resource database.
}
78 \twocolitem{{\bf \indexit{wxBITMAP
\_TYPE\_GIF}}}{Load a GIF bitmap file.
}
79 \twocolitem{{\bf \indexit{wxBITMAP
\_TYPE\_XBM}}}{Load an X bitmap file.
}
80 \twocolitem{{\bf \indexit{wxBITMAP
\_TYPE\_XPM}}}{Load an XPM bitmap file.
}
81 \twocolitem{{\bf \indexit{wxBITMAP
\_TYPE\_RESOURCE}}}{Load a Windows resource name.
}
84 The validity of these flags depends on the platform and wxWindows configuration.
85 If all possible wxWindows settings are used, the Windows platform supports BMP file, BMP resource,
86 XPM data, and XPM. Under wxGTK, the available formats are BMP file, XPM data, XPM file, and PNG file.
87 Under wxMotif, the available formats are XBM data, XBM file, XPM data, XPM file.
}
91 The first form constructs a bitmap object with no data; an assignment or another member function such as Create
92 or LoadFile must be called subsequently.
94 The second and third forms provide copy constructors. Note that these do not copy the
95 bitmap data, but instead a pointer to the data, keeping a reference count. They are therefore
96 very efficient operations.
98 The fourth form constructs a bitmap from data whose type and value depends on
99 the value of the
{\it type
} argument.
101 The fifth form constructs a (usually monochrome) bitmap from an array of pixel values, under both
104 The sixth form constructs a new bitmap.
106 The seventh form constructs a bitmap from pixmap (XPM) data, if wxWindows has been configured
107 to incorporate this feature.
109 To use this constructor, you must first include an XPM file. For
110 example, assuming that the file
{\tt mybitmap.xpm
} contains an XPM array
111 of character pointers called mybitmap:
114 #include "mybitmap.xpm"
118 wxBitmap *bitmap = new wxBitmap(mybitmap);
121 The eighth form constructs a bitmap from a file or resource.
{\it name
} can refer
122 to a resource name under MS Windows, or a filename under MS Windows and X.
124 Under Windows,
{\it type
} defaults to wxBITMAP
\_TYPE\_BMP\_RESOURCE.
125 Under X,
{\it type
} defaults to wxBITMAP
\_TYPE\_XPM.
129 \helpref{wxBitmap::LoadFile
}{wxbitmaploadfile
}
131 \membersection{wxBitmap::
\destruct{wxBitmap
}}
133 \func{}{\destruct{wxBitmap
}}{\void}
135 Destroys the wxBitmap object and possibly the underlying bitmap data.
136 Because reference counting is used, the bitmap may not actually be
137 destroyed at this point - only when the reference count is zero will the
140 If the application omits to delete the bitmap explicitly, the bitmap will be
141 destroyed automatically by wxWindows when the application exits.
143 Do not delete a bitmap that is selected into a memory device context.
145 \membersection{wxBitmap::AddHandler
}\label{wxbitmapaddhandler
}
147 \func{static void
}{AddHandler
}{\param{wxBitmapHandler*
}{ handler
}}
149 Adds a handler to the end of the static list of format handlers.
151 \docparam{handler
}{A new bitmap format handler object. There is usually only one instance
152 of a given handler class in an application session.
}
156 \helpref{wxBitmapHandler
}{wxbitmaphandler
}
158 \membersection{wxBitmap::CleanUpHandlers
}
160 \func{static void
}{CleanUpHandlers
}{\void}
162 Deletes all bitmap handlers.
164 This function is called by wxWindows on exit.
166 \membersection{wxBitmap::Create
}
168 \func{virtual bool
}{Create
}{\param{int
}{ width
},
\param{int
}{ height
},
\param{int
}{ depth = -
1}}
170 Creates a fresh bitmap. If the final argument is omitted, the display depth of
173 \func{virtual bool
}{Create
}{\param{void*
}{ data
},
\param{int
}{ type
},
\param{int
}{ width
},
\param{int
}{ height
},
\param{int
}{ depth = -
1}}
175 Creates a bitmap from the given data, which can be of arbitrary type.
177 \wxheading{Parameters
}
179 \docparam{width
}{The width of the bitmap in pixels.
}
181 \docparam{height
}{The height of the bitmap in pixels.
}
183 \docparam{depth
}{The depth of the bitmap in pixels. If this is -
1, the screen depth is used.
}
185 \docparam{data
}{Data whose type depends on the value of
{\it type
}.
}
187 \docparam{type
}{A bitmap type identifier - see
\helpref{wxBitmap::wxBitmap
}{wxbitmapconstr
} for a list
190 \wxheading{Return value
}
192 TRUE if the call succeeded, FALSE otherwise.
196 The first form works on all platforms. The portability of the second form depends on the
201 \helpref{wxBitmap::wxBitmap
}{wxbitmapconstr
}
203 \membersection{wxBitmap::FindHandler
}
205 \func{static wxBitmapHandler*
}{FindHandler
}{\param{const wxString\&
}{name
}}
207 Finds the handler with the given name.
209 \func{static wxBitmapHandler*
}{FindHandler
}{\param{const wxString\&
}{extension
},
\param{long
}{ bitmapType
}}
211 Finds the handler associated with the given extension and type.
213 \func{static wxBitmapHandler*
}{FindHandler
}{\param{long
}{bitmapType
}}
215 Finds the handler associated with the given bitmap type.
217 \docparam{name
}{The handler name.
}
219 \docparam{extension
}{The file extension, such as ``bmp".
}
221 \docparam{bitmapType
}{The bitmap type, such as wxBITMAP
\_TYPE\_BMP.
}
223 \wxheading{Return value
}
225 A pointer to the handler if found, NULL otherwise.
229 \helpref{wxBitmapHandler
}{wxbitmaphandler
}
231 \membersection{wxBitmap::GetDepth
}
233 \constfunc{int
}{GetDepth
}{\void}
235 Gets the colour depth of the bitmap. A value of
1 indicates a
238 \membersection{wxBitmap::GetHandlers
}
240 \func{static wxList\&
}{GetHandlers
}{\void}
242 Returns the static list of bitmap format handlers.
246 \helpref{wxBitmapHandler
}{wxbitmaphandler
}
248 \membersection{wxBitmap::GetHeight
}\label{wxbitmapgetheight
}
250 \constfunc{int
}{GetHeight
}{\void}
252 Gets the height of the bitmap in pixels.
254 \membersection{wxBitmap::GetPalette
}\label{wxbitmapgetpalette
}
256 \constfunc{wxPalette*
}{GetPalette
}{\void}
258 Gets the associated palette (if any) which may have been loaded from a file
259 or set for the bitmap.
263 \helpref{wxPalette
}{wxpalette
}
265 \membersection{wxBitmap::GetMask
}\label{wxbitmapgetmask
}
267 \constfunc{wxMask*
}{GetMask
}{\void}
269 Gets the associated mask (if any) which may have been loaded from a file
270 or set for the bitmap.
274 \helpref{wxBitmap::SetMask
}{wxbitmapsetmask
},
\helpref{wxMask
}{wxmask
}
276 \membersection{wxBitmap::GetWidth
}\label{wxbitmapgetwidth
}
278 \constfunc{int
}{GetWidth
}{\void}
280 Gets the width of the bitmap in pixels.
284 \helpref{wxBitmap::GetHeight
}{wxbitmapgetheight
}
286 \membersection{wxBitmap::InitStandardHandlers
}
288 \func{static void
}{InitStandardHandlers
}{\void}
290 Adds the standard bitmap format handlers, which, depending on wxWindows
291 configuration, can be handlers for Windows bitmap, Windows bitmap resource, and XPM.
293 This function is called by wxWindows on startup.
297 \helpref{wxBitmapHandler
}{wxbitmaphandler
}
299 \membersection{wxBitmap::InsertHandler
}
301 \func{static void
}{InsertHandler
}{\param{wxBitmapHandler*
}{ handler
}}
303 Adds a handler at the start of the static list of format handlers.
305 \docparam{handler
}{A new bitmap format handler object. There is usually only one instance
306 of a given handler class in an application session.
}
310 \helpref{wxBitmapHandler
}{wxbitmaphandler
}
312 \membersection{wxBitmap::LoadFile
}\label{wxbitmaploadfile
}
314 \func{bool
}{LoadFile
}{\param{const wxString\&
}{ name
},
\param{long
}{ type
}}
316 Loads a bitmap from a file or resource.
318 \wxheading{Parameters
}
320 \docparam{name
}{Either a filename or a Windows resource name.
321 The meaning of
{\it name
} is determined by the
{\it type
} parameter.
}
323 \docparam{type
}{One of the following values:
327 \twocolitem{{\bf wxBITMAP
\_TYPE\_BMP}}{Load a Windows bitmap file.
}
328 \twocolitem{{\bf wxBITMAP
\_TYPE\_BMP\_RESOURCE}}{Load a Windows bitmap from the resource database.
}
329 \twocolitem{{\bf wxBITMAP
\_TYPE\_GIF}}{Load a GIF bitmap file.
}
330 \twocolitem{{\bf wxBITMAP
\_TYPE\_XBM}}{Load an X bitmap file.
}
331 \twocolitem{{\bf wxBITMAP
\_TYPE\_XPM}}{Load an XPM bitmap file.
}
334 The validity of these flags depends on the platform and wxWindows configuration.
}
336 \wxheading{Return value
}
338 TRUE if the operation succeeded, FALSE otherwise.
342 A palette may be associated with the bitmap if one exists (especially for
343 colour Windows bitmaps), and if the code supports it. You can check
344 if one has been created by using the
\helpref{GetPalette
}{wxbitmapgetpalette
} member.
348 \helpref{wxBitmap::SaveFile
}{wxbitmapsavefile
}
350 \membersection{wxBitmap::Ok
}\label{wxbitmapok
}
352 \constfunc{bool
}{Ok
}{\void}
354 Returns TRUE if bitmap data is present.
356 \membersection{wxBitmap::RemoveHandler
}
358 \func{static bool
}{RemoveHandler
}{\param{const wxString\&
}{name
}}
360 Finds the handler with the given name, and removes it. The handler
363 \docparam{name
}{The handler name.
}
365 \wxheading{Return value
}
367 TRUE if the handler was found and removed, FALSE otherwise.
371 \helpref{wxBitmapHandler
}{wxbitmaphandler
}
373 \membersection{wxBitmap::SaveFile
}\label{wxbitmapsavefile
}
375 \func{bool
}{SaveFile
}{\param{const wxString\&
}{name
},
\param{int
}{ type
},
\param{wxPalette*
}{palette = NULL
}}
377 Saves a bitmap in the named file.
379 \wxheading{Parameters
}
381 \docparam{name
}{A filename. The meaning of
{\it name
} is determined by the
{\it type
} parameter.
}
383 \docparam{type
}{One of the following values:
387 \twocolitem{{\bf wxBITMAP
\_TYPE\_BMP}}{Save a Windows bitmap file.
}
388 \twocolitem{{\bf wxBITMAP
\_TYPE\_GIF}}{Save a GIF bitmap file.
}
389 \twocolitem{{\bf wxBITMAP
\_TYPE\_XBM}}{Save an X bitmap file.
}
390 \twocolitem{{\bf wxBITMAP
\_TYPE\_XPM}}{Save an XPM bitmap file.
}
393 The validity of these flags depends on the platform and wxWindows configuration.
}
395 \docparam{palette
}{An optional palette used for saving the bitmap.
}
396 % TODO: this parameter should
397 %probably be eliminated; instead the app should set the palette before saving.
399 \wxheading{Return value
}
401 TRUE if the operation succeeded, FALSE otherwise.
405 Depending on how wxWindows has been configured, not all formats may be available.
409 \helpref{wxBitmap::LoadFile
}{wxbitmaploadfile
}
411 \membersection{wxBitmap::SetDepth
}\label{wxbitmapsetdepth
}
413 \func{void
}{SetDepth
}{\param{int
}{depth
}}
415 Sets the depth member (does not affect the bitmap data).
417 \wxheading{Parameters
}
419 \docparam{depth
}{Bitmap depth.
}
421 \membersection{wxBitmap::SetHeight
}\label{wxbitmapsetheight
}
423 \func{void
}{SetHeight
}{\param{int
}{height
}}
425 Sets the height member (does not affect the bitmap data).
427 \wxheading{Parameters
}
429 \docparam{height
}{Bitmap height in pixels.
}
431 \membersection{wxBitmap::SetMask
}\label{wxbitmapsetmask
}
433 \func{void
}{SetMask
}{\param{wxMask*
}{mask
}}
435 Sets the mask for this bitmap.
439 The bitmap object owns the mask once this has been called.
443 \helpref{wxBitmap::GetMask
}{wxbitmapgetmask
},
\helpref{wxMask
}{wxmask
}
445 \membersection{wxBitmap::SetOk
}
447 \func{void
}{SetOk
}{\param{int
}{isOk
}}
449 Sets the validity member (does not affect the bitmap data).
451 \wxheading{Parameters
}
453 \docparam{isOk
}{Validity flag.
}
455 \membersection{wxBitmap::SetPalette
}\label{wxbitmapsetpalette
}
457 \func{void
}{SetPalette
}{\param{wxPalette*
}{palette
}}
459 Sets the associated palette: it will be deleted in the wxBitmap
460 destructor, so if you do not wish it to be deleted automatically,
461 reset the palette to NULL before the bitmap is deleted.
463 \wxheading{Parameters
}
465 \docparam{palette
}{The palette to set.
}
469 The bitmap object owns the palette once this has been called.
473 \helpref{wxPalette
}{wxpalette
}
475 \membersection{wxBitmap::SetWidth
}
477 \func{void
}{SetWidth
}{\param{int
}{width
}}
479 Sets the width member (does not affect the bitmap data).
481 \wxheading{Parameters
}
483 \docparam{width
}{Bitmap width in pixels.
}
485 \membersection{wxBitmap::operator $=$
}
487 \func{wxBitmap\&
}{operator $=$
}{\param{const wxBitmap\&
}{bitmap
}}
489 Assignment operator. This operator does not copy any data, but instead
490 passes a pointer to the data in
{\it bitmap
} and increments a reference
491 counter. It is a fast operation.
493 \wxheading{Parameters
}
495 \docparam{bitmap
}{Bitmap to assign.
}
497 \wxheading{Return value
}
499 Returns 'this' object.
501 \membersection{wxBitmap::operator $==$
}
503 \func{bool
}{operator $==$
}{\param{const wxBitmap\&
}{bitmap
}}
505 Equality operator. This operator tests whether the internal data pointers are
508 \wxheading{Parameters
}
510 \docparam{bitmap
}{Bitmap to compare with 'this'
}
512 \wxheading{Return value
}
514 Returns TRUE if the bitmaps were effectively equal, FALSE otherwise.
516 \membersection{wxBitmap::operator $!=$
}
518 \func{bool
}{operator $!=$
}{\param{const wxBitmap\&
}{bitmap
}}
520 Inequality operator. This operator tests whether the internal data pointers are
521 unequal (a fast test).
523 \wxheading{Parameters
}
525 \docparam{bitmap
}{Bitmap to compare with 'this'
}
527 \wxheading{Return value
}
529 Returns TRUE if the bitmaps were unequal, FALSE otherwise.
531 \section{\class{wxBitmapHandler
}}\label{wxbitmaphandler
}
533 \overview{Overview
}{wxbitmapoverview
}
535 This is the base class for implementing bitmap file loading/saving, and bitmap creation from data.
536 It is used within wxBitmap and is not normally seen by the application.
538 If you wish to extend the capabilities of wxBitmap, derive a class from wxBitmapHandler
539 and add the handler using
\helpref{wxBitmap::AddHandler
}{wxbitmapaddhandler
} in your
540 application initialisation.
542 \wxheading{Derived from
}
544 \helpref{wxObject
}{wxobject
}
546 \wxheading{Include files
}
552 \helpref{wxBitmap
}{wxbitmap
},
\helpref{wxIcon
}{wxicon
},
\helpref{wxCursor
}{wxcursor
}
554 \latexignore{\rtfignore{\wxheading{Members
}}}
556 \membersection{wxBitmapHandler::wxBitmapHandler
}\label{wxbitmaphandlerconstr
}
558 \func{}{wxBitmapHandler
}{\void}
560 Default constructor. In your own default constructor, initialise the members
561 m
\_name, m
\_extension and m
\_type.
563 \membersection{wxBitmapHandler::
\destruct{wxBitmapHandler
}}
565 \func{}{\destruct{wxBitmapHandler
}}{\void}
567 Destroys the wxBitmapHandler object.
569 \membersection{wxBitmapHandler::Create
}
571 \func{virtual bool
}{Create
}{\param{wxBitmap*
}{bitmap
},
\param{void*
}{ data
},
\param{int
}{ type
},
\param{int
}{ width
},
\param{int
}{ height
},
\param{int
}{ depth = -
1}}
573 Creates a bitmap from the given data, which can be of arbitrary type. The wxBitmap object
{\it bitmap
} is
574 manipulated by this function.
576 \wxheading{Parameters
}
578 \docparam{bitmap
}{The wxBitmap object.
}
580 \docparam{width
}{The width of the bitmap in pixels.
}
582 \docparam{height
}{The height of the bitmap in pixels.
}
584 \docparam{depth
}{The depth of the bitmap in pixels. If this is -
1, the screen depth is used.
}
586 \docparam{data
}{Data whose type depends on the value of
{\it type
}.
}
588 \docparam{type
}{A bitmap type identifier - see
\helpref{wxBitmapHandler::wxBitmapHandler
}{wxbitmapconstr
} for a list
591 \wxheading{Return value
}
593 TRUE if the call succeeded, FALSE otherwise (the default).
595 \membersection{wxBitmapHandler::GetName
}
597 \constfunc{wxString
}{GetName
}{\void}
599 Gets the name of this handler.
601 \membersection{wxBitmapHandler::GetExtension
}
603 \constfunc{wxString
}{GetExtension
}{\void}
605 Gets the file extension associated with this handler.
607 \membersection{wxBitmapHandler::GetType
}
609 \constfunc{long
}{GetType
}{\void}
611 Gets the bitmap type associated with this handler.
613 \membersection{wxBitmapHandler::LoadFile
}\label{wxbitmaphandlerloadfile
}
615 \func{bool
}{LoadFile
}{\param{wxBitmap*
}{bitmap
},
\param{const wxString\&
}{ name
},
\param{long
}{ type
}}
617 Loads a bitmap from a file or resource, putting the resulting data into
{\it bitmap
}.
619 \wxheading{Parameters
}
621 \docparam{bitmap
}{The bitmap object which is to be affected by this operation.
}
623 \docparam{name
}{Either a filename or a Windows resource name.
624 The meaning of
{\it name
} is determined by the
{\it type
} parameter.
}
626 \docparam{type
}{See
\helpref{wxBitmap::wxBitmap
}{wxbitmapconstr
} for values this can take.
}
628 \wxheading{Return value
}
630 TRUE if the operation succeeded, FALSE otherwise.
634 \helpref{wxBitmap::LoadFile
}{wxbitmaploadfile
}\\
635 \helpref{wxBitmap::SaveFile
}{wxbitmapsavefile
}\\
636 \helpref{wxBitmapHandler::SaveFile
}{wxbitmaphandlersavefile
}
638 \membersection{wxBitmapHandler::SaveFile
}\label{wxbitmaphandlersavefile
}
640 \func{bool
}{SaveFile
}{\param{wxBitmap*
}{bitmap
},
\param{const wxString\&
}{name
},
\param{int
}{ type
},
\param{wxPalette*
}{palette = NULL
}}
642 Saves a bitmap in the named file.
644 \wxheading{Parameters
}
646 \docparam{bitmap
}{The bitmap object which is to be affected by this operation.
}
648 \docparam{name
}{A filename. The meaning of
{\it name
} is determined by the
{\it type
} parameter.
}
650 \docparam{type
}{See
\helpref{wxBitmap::wxBitmap
}{wxbitmapconstr
} for values this can take.
}
652 \docparam{palette
}{An optional palette used for saving the bitmap.
}
654 \wxheading{Return value
}
656 TRUE if the operation succeeded, FALSE otherwise.
660 \helpref{wxBitmap::LoadFile
}{wxbitmaploadfile
}\\
661 \helpref{wxBitmap::SaveFile
}{wxbitmapsavefile
}\\
662 \helpref{wxBitmapHandler::LoadFile
}{wxbitmaphandlerloadfile
}
664 \membersection{wxBitmapHandler::SetName
}
666 \func{void
}{SetName
}{\param{const wxString\&
}{name
}}
668 Sets the handler name.
670 \wxheading{Parameters
}
672 \docparam{name
}{Handler name.
}
674 \membersection{wxBitmapHandler::SetExtension
}
676 \func{void
}{SetExtension
}{\param{const wxString\&
}{extension
}}
678 Sets the handler extension.
680 \wxheading{Parameters
}
682 \docparam{extension
}{Handler extension.
}
684 \membersection{wxBitmapHandler::SetType
}
686 \func{void
}{SetType
}{\param{long
}{type
}}
688 Sets the handler type.
690 \wxheading{Parameters
}
692 \docparam{name
}{Handler type.
}