\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{supported bitmap file formats}{supportedbitmapformats},
-\helpref{wxDC::Blit}{wxdcblit},
-\helpref{wxIcon}{wxicon}, \helpref{wxCursor}{wxcursor}, \helpref{wxBitmap}{wxbitmap},
+\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{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.
+Creates a bitmap from the given data which is interpreted in platform-dependent
+manner.
\func{}{wxBitmap}{\param{const char}{ bits[]}, \param{int}{ width}, \param{int}{ height}\\
\param{int}{ depth = 1}}
Creates a bitmap from an array of bits.
+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}}
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.}
\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 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.}
+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}
\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}
This function is called by wxWindows on exit.
-\membersection{wxBitmap::Create}
+\membersection{wxBitmap::ConvertToImage}\label{wxbitmapconverttoimage}
+
+\func{wxImage}{ConvertToImage}{\void}
+
+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}}
\wxheading{Return value}
-TRUE if the call succeeded, FALSE otherwise.
+true if the call succeeded, false otherwise.
\wxheading{Remarks}
\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}
\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 wxWindows 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 wxWindows configuration.
+
+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.}
+\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}
\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{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. 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{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