\helpref{wxGDIObject}{wxgdiobject}\\
\helpref{wxObject}{wxobject}
+\wxheading{Include file}
+
+<wx/bitmap.h>
+
+\wxheading{Predefined objects}
+
+Objects:
+
+{\bf wxNullBitmap}
+
\wxheading{See also}
-\helpref{wxBitmap overview}{wxbitmapoverview}, \helpref{wxDC::Blit}{wxdcblit}, \helpref{wxIcon}{wxicon}, \helpref{wxCursor}{wxcursor}, \helpref{wxMemoryDC}{wxmemorydc}
+\helpref{wxBitmap overview}{wxbitmapoverview},
+\helpref{supported bitmap file formats}{supportedbitmapformats},
+\helpref{wxDC::Blit}{wxdcblit},
+\helpref{wxIcon}{wxicon}, \helpref{wxCursor}{wxcursor}, \helpref{wxBitmap}{wxbitmap},
+\helpref{wxMemoryDC}{wxmemorydc}
\latexignore{\rtfignore{\wxheading{Members}}}
\func{}{wxBitmap}{\param{const wxBitmap\& }{bitmap}}
-\func{}{wxBitmap}{\param{const wxBitmap* }{bitmap}}
+Copy constructor.
-Copy constructors.
+\func{}{wxBitmap}{\param{void*}{ data}, \param{int}{ type}, \param{int}{ width}, \param{int}{ height}, \param{int}{ depth = -1}}
-\func{}{wxBitmap}{\param{void*}{ data}, \param{const int}{ type}, \param{const int}{ width}, \param{const int}{ height}, \param{const int}{ depth = -1}}
+Creates a bitmap from the given data which is interpreted in platform-dependent
+manner.
-Creates a bitmap from the given data, which can be of arbitrary type.
-
-\func{}{wxBitmap}{\param{const char}{ bits[]}, \param{const int}{ width}, \param{const int}{ height}\\
- \param{const int}{ depth = 1}}
+\func{}{wxBitmap}{\param{const char}{ bits[]}, \param{int}{ width}, \param{int}{ height}\\
+ \param{int}{ depth = 1}}
Creates a bitmap from an array of bits.
-\func{}{wxBitmap}{\param{const int}{ width}, \param{const int}{ height}, \param{const int}{ depth = -1}}
+You should only use this function for monochrome bitmaps ({\it depth} 1) in
+portable programs: in this case the {\it bits} parameter should contain an XBM
+image.
+
+For other bit depths, the behaviour is platform dependent: under Windows, the
+data is passed without any changes to the underlying {\tt CreateBitmap()} API.
+Under other platforms, only monochrome bitmaps may be created using this
+constructor and \helpref{wxImage}{wximage} should be used for creating colour
+bitmaps from static data.
+
+\func{}{wxBitmap}{\param{int}{ width}, \param{int}{ height}, \param{int}{ depth = -1}}
-Creates a new bitmap.
+Creates a new bitmap. A depth of -1 indicates the depth of the current screen
+or visual. Some platforms only support 1 for monochrome and -1 for the current
+colour setting.
\func{}{wxBitmap}{\param{const char**}{ bits}}
Creates a bitmap from XPM data.
-\func{}{wxBitmap}{\param{const wxString\& }{name}, \param{const long}{ type}}
+\func{}{wxBitmap}{\param{const wxString\& }{name}, \param{long}{ type}}
Loads a bitmap from a file or resource.
+\func{}{wxBitmap}{\param{const wxImage\&}{ img}, \param{int}{ depth = -1}}
+
+Creates bitmap object from the image. This has to be done
+to actually display an image as you cannot draw an image directly on a window.
+The resulting bitmap will use the provided colour depth (or that of the
+current system if depth is -1) which entails that a colour reduction has
+to take place.
+
+When in 8-bit mode (PseudoColour mode), the GTK port will use a color cube created
+on program start-up to look up colors. This ensures a very fast conversion, but
+the image quality won't be perfect (and could be better for photo images using more
+sophisticated dithering algorithms).
+
+On Windows, if there is a palette present (set with SetPalette), it will be used when
+creating the wxBitmap (most useful in 8-bit display mode). On other platforms,
+the palette is currently ignored.
+
\wxheading{Parameters}
\docparam{bits}{Specifies an array of pixel values.}
screen is used.}
\docparam{name}{This can refer to a resource name under MS Windows, or a filename under MS Windows and X.
-Its meaning is determined by the {\it flags} parameter.}
+Its meaning is determined by the {\it type} parameter.}
\docparam{type}{May be one of the following:
\twocolwidtha{5cm}
\begin{twocollist}
-\twocolitem{{\bf \indexit{wxBITMAP\_TYPE\_BMP}}}{Load a Windows bitmap file.}
-\twocolitem{{\bf \indexit{wxBITMAP\_TYPE\_BMP\_RESOURCE}}}{Load a Windows bitmap from the resource database.}
-\twocolitem{{\bf \indexit{wxBITMAP\_TYPE\_GIF}}}{Load a GIF bitmap file.}
-\twocolitem{{\bf \indexit{wxBITMAP\_TYPE\_XBM}}}{Load an X bitmap file.}
-\twocolitem{{\bf \indexit{wxBITMAP\_TYPE\_XPM}}}{Load an XPM bitmap file.}
-\twocolitem{{\bf \indexit{wxBITMAP\_TYPE\_RESOURCE}}}{Load a Windows resource name.}
+\twocolitem{\indexit{wxBITMAP\_TYPE\_BMP}}{Load a Windows bitmap file.}
+\twocolitem{\indexit{wxBITMAP\_TYPE\_BMP\_RESOURCE}}{Load a Windows bitmap from the resource database.}
+\twocolitem{\indexit{wxBITMAP\_TYPE\_GIF}}{Load a GIF bitmap file.}
+\twocolitem{\indexit{wxBITMAP\_TYPE\_XBM}}{Load an X bitmap file.}
+\twocolitem{\indexit{wxBITMAP\_TYPE\_XPM}}{Load an XPM bitmap file.}
+\twocolitem{\indexit{wxBITMAP\_TYPE\_RESOURCE}}{Load a Windows resource name.}
\end{twocollist}
-The validity of these flags depends on the platform and wxWindows configuration.
-If all possible wxWindows settings are used, the Windows platform supports BMP, BMP\_RESOURCE,
-XPM\_DATA, and XPM. Under X, the available formats are BMP, GIF, XBM, and XPM.}
+The validity of these flags depends on the platform and wxWidgets configuration.
+If all possible wxWidgets settings are used, the Windows platform supports BMP file, BMP resource,
+XPM data, and XPM. Under wxGTK, the available formats are BMP file, XPM data, XPM file, and PNG file.
+Under wxMotif, the available formats are XBM data, XBM file, XPM data, XPM file.
+
+In addition, wxBitmap can read all formats that \helpref{wxImage}{wximage} can, which currently include
+wxBITMAP\_TYPE\_JPEG, wxBITMAP\_TYPE\_TIF, wxBITMAP\_TYPE\_PNG, wxBITMAP\_TYPE\_GIF, wxBITMAP\_TYPE\_PCX,
+and wxBITMAP\_TYPE\_PNM. Of course, you must have wxImage handlers loaded. }
+
+\docparam{img}{Platform-independent wxImage object.}
\wxheading{Remarks}
The sixth form constructs a new bitmap.
-The seventh form constructs a bitmap from pixmap (XPM) data, if wxWindows has been configured
+The seventh form constructs a bitmap from pixmap (XPM) data, if wxWidgets has been configured
to incorporate this feature.
To use this constructor, you must first include an XPM file. For
to a resource name under MS Windows, or a filename under MS Windows and X.
Under Windows, {\it type} defaults to wxBITMAP\_TYPE\_BMP\_RESOURCE.
-Under X, {\it type} defaults to wxBITMAP\_TYPE\_XBM.
+Under X, {\it type} defaults to wxBITMAP\_TYPE\_XPM.
\wxheading{See also}
\helpref{wxBitmap::LoadFile}{wxbitmaploadfile}
+\pythonnote{Constructors supported by wxPython are:\par
+\indented{2cm}{\begin{twocollist}
+\twocolitem{{\bf wxBitmap(name, flag)}}{Loads a bitmap from a file}
+\twocolitem{{\bf wxEmptyBitmap(width, height, depth = -1)}}{Creates an
+empty bitmap with the given specifications}
+\twocolitem{{\bf wxBitmapFromXPMData(listOfStrings)}}{Create a bitmap
+from a Python list of strings whose contents are XPM data.}
+\twocolitem{{\bf wxBitmapFromBits(bits, width, height,
+depth=-1)}}{Create a bitmap from an array of bits contained in a
+string.}
+\twocolitem{{\bf wxBitmapFromImage(image, depth=-1)}}{Convert a
+wxImage to a wxBitmap.}
+\end{twocollist}}
+}
+
+\perlnote{Constructors supported by wxPerl are:\par
+\begin{itemize}
+\item{Wx::Bitmap->new( width, height, depth = -1 )}
+\item{Wx::Bitmap->new( name, type )}
+\item{Wx::Bitmap->new( icon )}
+\item{Wx::Bitmap->newFromBits( bits, width, height, depth = 1 )}
+\item{Wx::Bitmap->newFromXPM( data )}
+\end{itemize}
+}
+
\membersection{wxBitmap::\destruct{wxBitmap}}
\func{}{\destruct{wxBitmap}}{\void}
data be deleted.
If the application omits to delete the bitmap explicitly, the bitmap will be
-destroyed automatically by wxWindows when the application exits.
+destroyed automatically by wxWidgets when the application exits.
Do not delete a bitmap that is selected into a memory device context.
Deletes all bitmap handlers.
-This function is called by wxWindows on exit.
+This function is called by wxWidgets on exit.
+
+\membersection{wxBitmap::ConvertToImage}\label{wxbitmapconverttoimage}
-\membersection{wxBitmap::Create}
+\func{wxImage}{ConvertToImage}{\void}
-\func{virtual bool}{Create}{\param{const int}{ width}, \param{const int}{ height}, \param{const int}{ depth = -1}}
+Creates an image from a platform-dependent bitmap. This preserves
+mask information so that bitmaps and images can be converted back
+and forth without loss in that respect.
+
+\membersection{wxBitmap::CopyFromIcon}\label{wxbitmapcopyfromicon}
+
+\func{bool}{CopyFromIcon}{\param{const wxIcon\&}{ icon}}
+
+Creates the bitmap from an icon.
+
+\membersection{wxBitmap::Create}\label{wxbitmapcreate}
+
+\func{virtual bool}{Create}{\param{int}{ width}, \param{int}{ height}, \param{int}{ depth = -1}}
Creates a fresh bitmap. If the final argument is omitted, the display depth of
the screen is used.
-\func{virtual bool}{Create}{\param{void*}{ data}, \param{const int}{ type}, \param{const int}{ width}, \param{const int}{ height}, \param{const int}{ depth = -1}}
+\func{virtual bool}{Create}{\param{void*}{ data}, \param{int}{ type}, \param{int}{ width}, \param{int}{ height}, \param{int}{ depth = -1}}
Creates a bitmap from the given data, which can be of arbitrary type.
\wxheading{Return value}
-TRUE if the call succeeded, FALSE otherwise.
+true if the call succeeded, false otherwise.
\wxheading{Remarks}
\constfunc{wxMask*}{GetMask}{\void}
-Gets the associated mask if any) which may have been loaded from a file
+Gets the associated mask (if any) which may have been loaded from a file
or set for the bitmap.
\wxheading{See also}
\helpref{wxBitmap::GetHeight}{wxbitmapgetheight}
+\membersection{wxBitmap::GetSubBitmap}\label{wxbitmapgetsubbitmap}
+
+\constfunc{wxBitmap}{GetSubBitmap}{\param{const wxRect\&}{rect}}
+
+Returns a sub bitmap of the current one as long as the rect belongs entirely to
+the bitmap. This function preserves bit depth and mask information.
+
\membersection{wxBitmap::InitStandardHandlers}
\func{static void}{InitStandardHandlers}{\void}
-Adds the standard bitmap format handlers, which, depending on wxWindows
+Adds the standard bitmap format handlers, which, depending on wxWidgets
configuration, can be handlers for Windows bitmap, Windows bitmap resource, and XPM.
-This function is called by wxWindows on startup.
+This function is called by wxWidgets on startup.
\wxheading{See also}
\membersection{wxBitmap::LoadFile}\label{wxbitmaploadfile}
-\func{bool}{LoadFile}{\param{const wxString\&}{ name}, \param{const long}{ type}}
+\func{bool}{LoadFile}{\param{const wxString\&}{ name}, \param{long}{ type}}
Loads a bitmap from a file or resource.
\twocolitem{{\bf wxBITMAP\_TYPE\_XPM}}{Load an XPM bitmap file.}
\end{twocollist}
-The validity of these flags depends on the platform and wxWindows configuration.}
+The validity of these flags depends on the platform and wxWidgets configuration.
+
+In addition, wxBitmap can read all formats that \helpref{wxImage}{wximage} can
+(wxBITMAP\_TYPE\_JPEG, wxBITMAP\_TYPE\_PNG, wxBITMAP\_TYPE\_GIF, wxBITMAP\_TYPE\_PCX, wxBITMAP\_TYPE\_PNM).
+(Of course you must have wxImage handlers loaded.) }
\wxheading{Return value}
-TRUE if the operation succeeded, FALSE otherwise.
+true if the operation succeeded, false otherwise.
\wxheading{Remarks}
\constfunc{bool}{Ok}{\void}
-Returns TRUE if bitmap data is present.
+Returns true if bitmap data is present.
\membersection{wxBitmap::RemoveHandler}
\wxheading{Return value}
-TRUE if the handler was found and removed, FALSE otherwise.
+true if the handler was found and removed, false otherwise.
\wxheading{See also}
\twocolitem{{\bf wxBITMAP\_TYPE\_XPM}}{Save an XPM bitmap file.}
\end{twocollist}
-The validity of these flags depends on the platform and wxWindows configuration.}
+The validity of these flags depends on the platform and wxWidgets configuration.
-\docparam{palette}{An optional palette used for saving the bitmap. TODO: this parameter should
-probably be eliminated; instead the app should set the palette before saving.}
+In addition, wxBitmap can save all formats that \helpref{wxImage}{wximage} can
+(wxBITMAP\_TYPE\_JPEG, wxBITMAP\_TYPE\_PNG).
+(Of course you must have wxImage handlers loaded.) }
+
+\docparam{palette}{An optional palette used for saving the bitmap.}
+% TODO: this parameter should
+%probably be eliminated; instead the app should set the palette before saving.
\wxheading{Return value}
-TRUE if the operation succeeded, FALSE otherwise.
+true if the operation succeeded, false otherwise.
\wxheading{Remarks}
-Depending on how wxWindows has been configured, not all formats may be available.
+Depending on how wxWidgets has been configured, not all formats may be available.
\wxheading{See also}
\helpref{wxBitmap::GetMask}{wxbitmapgetmask}, \helpref{wxMask}{wxmask}
-\membersection{wxBitmap::SetOk}
-
-\func{void}{SetOk}{\param{int }{isOk}}
-
-Sets the validity member (does not affect the bitmap data).
-
-\wxheading{Parameters}
-
-\docparam{isOk}{Validity flag.}
+%% VZ: this function is an implementation detail and shouldn't be documented
+%%\membersection{wxBitmap::SetOk}
+%%
+%%\func{void}{SetOk}{\param{int }{isOk}}
+%%
+%%Sets the validity member (does not affect the bitmap data).
+%%
+%%\wxheading{Parameters}
+%%
+%%\docparam{isOk}{Validity flag.}
\membersection{wxBitmap::SetPalette}\label{wxbitmapsetpalette}
-\func{void}{SetPalette}{\param{wxPalette* }{palette}}
+\func{void}{SetPalette}{\param{const wxPalette\& }{palette}}
-Sets the associated palette: it will be deleted in the wxBitmap
-destructor, so if you do not wish it to be deleted automatically,
-reset the palette to NULL before the bitmap is deleted.
+Sets the associated palette.
\wxheading{Parameters}
\docparam{palette}{The palette to set.}
-\wxheading{Remarks}
-
-The bitmap object owns the palette once this has been called.
-
\wxheading{See also}
\helpref{wxPalette}{wxpalette}
\wxheading{Return value}
-Returns TRUE if the bitmaps were effectively equal, FALSE otherwise.
+Returns true if the bitmaps were effectively equal, false otherwise.
\membersection{wxBitmap::operator $!=$}
\wxheading{Return value}
-Returns TRUE if the bitmaps were unequal, FALSE otherwise.
-
-\section{\class{wxBitmapHandler}}\label{wxbitmaphandler}
-
-\overview{Overview}{wxbitmapoverview}
-
-This is the base class for implementing bitmap file loading/saving, and bitmap creation from data.
-It is used within wxBitmap and is not normally seen by the application.
-
-If you wish to extend the capabilities of wxBitmap, derive a class from wxBitmapHandler
-and add the handler using \helpref{wxBitmap::AddHandler}{wxbitmapaddhandler} in your
-application initialisation.
-
-\wxheading{Derived from}
-
-\helpref{wxObject}{wxobject}
-
-\wxheading{See also}
-
-\helpref{wxBitmap}{wxbitmap}, \helpref{wxIcon}{wxicon}, \helpref{wxCursor}{wxcursor}
-
-\latexignore{\rtfignore{\wxheading{Members}}}
-
-\membersection{wxBitmapHandler::wxBitmapHandler}\label{wxbitmaphandlerconstr}
-
-\func{}{wxBitmapHandler}{\void}
-
-Default constructor. In your own default constructor, initialise the members
-m\_name, m\_extension and m\_type.
-
-\membersection{wxBitmapHandler::\destruct{wxBitmapHandler}}
-
-\func{}{\destruct{wxBitmapHandler}}{\void}
-
-Destroys the wxBitmapHandler object.
-
-\membersection{wxBitmapHandler::Create}
-
-\func{virtual bool}{Create}{\param{wxBitmap* }{bitmap}, \param{void*}{ data}, \param{const int}{ type}, \param{const int}{ width}, \param{const int}{ height}, \param{const int}{ depth = -1}}
-
-Creates a bitmap from the given data, which can be of arbitrary type. The wxBitmap object {\it bitmap} is
-manipulated by this function.
-
-\wxheading{Parameters}
-
-\docparam{bitmap}{The wxBitmap object.}
-
-\docparam{width}{The width of the bitmap in pixels.}
-
-\docparam{height}{The height of the bitmap in pixels.}
-
-\docparam{depth}{The depth of the bitmap in pixels. If this is -1, the screen depth is used.}
-
-\docparam{data}{Data whose type depends on the value of {\it type}.}
-
-\docparam{type}{A bitmap type identifier - see \helpref{wxBitmapHandler::wxBitmapHandler}{wxbitmapconstr} for a list
-of possible values.}
-
-\wxheading{Return value}
-
-TRUE if the call succeeded, FALSE otherwise (the default).
-
-\membersection{wxBitmapHandler::GetName}
-
-\constfunc{wxString}{GetName}{\void}
-
-Gets the name of this handler.
-
-\membersection{wxBitmapHandler::GetExtension}
-
-\constfunc{wxString}{GetExtension}{\void}
-
-Gets the file extension associated with this handler.
-
-\membersection{wxBitmapHandler::GetType}
-
-\constfunc{long}{GetType}{\void}
-
-Gets the bitmap type associated with this handler.
-
-\membersection{wxBitmapHandler::LoadFile}\label{wxbitmaphandlerloadfile}
-
-\func{bool}{LoadFile}{\param{wxBitmap* }{bitmap}, \param{const wxString\&}{ name}, \param{const long}{ type}}
-
-Loads a bitmap from a file or resource, putting the resulting data into {\it bitmap}.
-
-\wxheading{Parameters}
-
-\docparam{bitmap}{The bitmap object which is to be affected by this operation.}
-
-\docparam{name}{Either a filename or a Windows resource name.
-The meaning of {\it name} is determined by the {\it type} parameter.}
-
-\docparam{type}{See \helpref{wxBitmap::wxBitmap}{wxbitmapconstr} for values this can take.}
-
-\wxheading{Return value}
-
-TRUE if the operation succeeded, FALSE otherwise.
-
-\wxheading{See also}
-
-\helpref{wxBitmap::LoadFile}{wxbitmaploadfile}\\
-\helpref{wxBitmap::SaveFile}{wxbitmapsavefile}\\
-\helpref{wxBitmapHandler::SaveFile}{wxbitmaphandlersavefile}
-
-\membersection{wxBitmapHandler::SaveFile}\label{wxbitmaphandlersavefile}
-
-\func{bool}{SaveFile}{\param{wxBitmap* }{bitmap}, \param{const wxString\& }{name}, \param{int}{ type}, \param{wxPalette* }{palette = NULL}}
-
-Saves a bitmap in the named file.
-
-\wxheading{Parameters}
-
-\docparam{bitmap}{The bitmap object which is to be affected by this operation.}
-
-\docparam{name}{A filename. The meaning of {\it name} is determined by the {\it type} parameter.}
-
-\docparam{type}{See \helpref{wxBitmap::wxBitmap}{wxbitmapconstr} for values this can take.}
-
-\docparam{palette}{An optional palette used for saving the bitmap. TODO: this parameter should
-probably be eliminated; instead the app should set the palette before saving.}
-
-\wxheading{Return value}
-
-TRUE if the operation succeeded, FALSE otherwise.
-
-\wxheading{See also}
-
-\helpref{wxBitmap::LoadFile}{wxbitmaploadfile}\\
-\helpref{wxBitmap::SaveFile}{wxbitmapsavefile}\\
-\helpref{wxBitmapHandler::LoadFile}{wxbitmaphandlerloadfile}
-
-\membersection{wxBitmapHandler::SetName}
-
-\func{void}{SetName}{\param{const wxString\& }{name}}
-
-Sets the handler name.
-
-\wxheading{Parameters}
-
-\docparam{name}{Handler name.}
-
-\membersection{wxBitmapHandler::SetExtension}
-
-\func{void}{SetExtension}{\param{const wxString\& }{extension}}
-
-Sets the handler extension.
-
-\wxheading{Parameters}
-
-\docparam{extension}{Handler extension.}
-
-\membersection{wxBitmapHandler::SetType}
-
-\func{void}{SetType}{\param{long }{type}}
-
-Sets the handler type.
-
-\wxheading{Parameters}
-
-\docparam{name}{Handler type.}
-
+Returns true if the bitmaps were unequal, false otherwise.
projects / wxWidgets.git / blobdiff