ccaaf5b083
git-svn-id: https://svn.wxwidgets.org/svn/wx/wxWidgets/trunk@4651 c3d73ce0-8a6f-49c7-b76d-6d57e0e08775
193 lines
7.2 KiB
TeX
193 lines
7.2 KiB
TeX
\section{Bitmaps and icons overview}\label{wxbitmapoverview}
|
|
|
|
Classes: \helpref{wxBitmap}{wxbitmap}, \helpref{wxBitmapHandler}{wxbitmaphandler}, \helpref{wxIcon}{wxicon}, \helpref{wxCursor}{wxcursor}.
|
|
|
|
The wxBitmap class encapsulates the concept of a platform-dependent bitmap,
|
|
either monochrome or colour. Platform-specific methods for creating a
|
|
wxBitmap object from an existing file are catered for, and
|
|
this is an occasion where conditional compilation will sometimes be
|
|
required.
|
|
|
|
A bitmap created dynamically or loaded from a file can be selected
|
|
into a memory device context (instance of \helpref{wxMemoryDC}{wxmemorydc}). This
|
|
enables the bitmap to be copied to a window or memory device context
|
|
using \helpref{wxDC::Blit}{wxdcblit}, or to be used as a drawing surface. The {\bf
|
|
wxToolBarSimple} class is implemented using bitmaps, and the toolbar demo
|
|
shows one of the toolbar bitmaps being used for drawing a miniature
|
|
version of the graphic which appears on the main window.
|
|
|
|
See \helpref{wxMemoryDC}{wxmemorydc} for an example of drawing onto a bitmap.
|
|
|
|
The following shows the conditional compilation required to load a
|
|
bitmap under Unix and in Windows. The alternative is to use the string
|
|
version of the bitmap constructor, which loads a file under Unix and a
|
|
resource or file under Windows, but has the disadvantage of requiring the
|
|
XPM icon file to be available at run-time.
|
|
|
|
\begin{verbatim}
|
|
#if defined(__WXGTK__) || defined(__WXMOTIF__)
|
|
#include "mondrian.xpm"
|
|
#endif
|
|
\end{verbatim}
|
|
|
|
A macro, \helpref{wxICON}{wxiconmacro}, is available which creates an icon using an XPM
|
|
on the appropriate platform, or an icon resource on Windows.
|
|
|
|
\begin{verbatim}
|
|
wxIcon icon(wxICON(mondrian));
|
|
|
|
// Equivalent to:
|
|
|
|
#if defined(__WXGTK__) || defined(__WXMOTIF__)
|
|
wxIcon icon(mondrian_xpm);
|
|
#endif
|
|
|
|
#if defined(__WXMSW__)
|
|
wxIcon icon("mondrian");
|
|
#endif
|
|
\end{verbatim}
|
|
|
|
There is also a corresponding \helpref{wxBITMAP}{wxbitmapmacro} macro which allows
|
|
to create the bitmaps in much the same way as \helpref{wxICON}{wxiconmacro} creates
|
|
icons. It assumes that bitmaps live in resources under Windows or OS2 and XPM
|
|
files under all other platforms (for XPMs, the corresponding file must be
|
|
included before this macro is used, of course, and the name of the bitmap
|
|
should be the same as the resource name under Windows with {\tt \_xpm}
|
|
suffix). For example:
|
|
|
|
\begin{verbatim}
|
|
// an easy and portable way to create a bitmap
|
|
wxBitmap bmp(wxBITMAP(bmpname));
|
|
|
|
// which is roughly equivalent to the following
|
|
#if defined(__WXMSW__) || defined(__WXPM__)
|
|
wxBitmap bmp("bmpname", wxBITMAP_TYPE_RESOURCE);
|
|
#else // Unix
|
|
wxBitmap bmp(bmpname_xpm, wxBITMAP_TYPE_XPM);
|
|
#endif
|
|
\end{verbatim}
|
|
|
|
You should always use wxICON and wxBITMAP macros because they work for any
|
|
platform (unlike the code above which doesn't deal with wxMac, wxBe, ...) and
|
|
are more short and clear than versions with {\tt #ifdef}s.
|
|
|
|
\subsection{Supported bitmap file formats}\label{supportedbitmapformats}
|
|
|
|
The following lists the formats handled on different platforms. Note
|
|
that missing or partially-implemented formats are automatically supplemented
|
|
by the \helpref{wxImage}{wximage} to load the data, and then converting
|
|
it to wxBitmap form. Note that using wxImage is the preferred way to
|
|
load images in wxWindows, with the exception of resources (XPM-files or
|
|
native Windows resources). Writing an image format handler for wxImage
|
|
is also far easier than writing one for wxBitmap, because wxImage has
|
|
exactly one format on all platforms wheras wxBitmap can store pixel data
|
|
very differently, depending on colour depths and platform.
|
|
|
|
\wxheading{wxBitmap}
|
|
|
|
Under Windows, wxBitmap may load the following formats:
|
|
|
|
\begin{itemize}\itemsep=0pt
|
|
\item Windows bitmap resource (wxBITMAP\_TYPE\_BMP\_RESOURCE)
|
|
\item Windows bitmap file (wxBITMAP\_TYPE\_BMP)
|
|
\item XPM data and file (wxBITMAP\_TYPE\_XPM)
|
|
\item All formats that are supported by the \helpref{wxImage}{wximage} class.
|
|
\end{itemize}
|
|
|
|
Under wxGTK, wxBitmap may load the following formats:
|
|
|
|
\begin{itemize}\itemsep=0pt
|
|
\item XPM data and file (wxBITMAP\_TYPE\_XPM)
|
|
\item All formats that are supported by the \helpref{wxImage}{wximage} class.
|
|
\end{itemize}
|
|
|
|
Under wxMotif, wxBitmap may load the following formats:
|
|
|
|
\begin{itemize}\itemsep=0pt
|
|
\item XBM data and file (wxBITMAP\_TYPE\_XBM)
|
|
\item XPM data and file (wxBITMAP\_TYPE\_XPM)
|
|
\item All formats that are supported by the \helpref{wxImage}{wximage} class.
|
|
\end{itemize}
|
|
|
|
\wxheading{wxIcon}
|
|
|
|
Under Windows, wxIcon may load the following formats:
|
|
|
|
\begin{itemize}\itemsep=0pt
|
|
\item Windows icon resource (wxBITMAP\_TYPE\_ICO\_RESOURCE)
|
|
\item Windows icon file (wxBITMAP\_TYPE\_ICO)
|
|
\item XPM data and file (wxBITMAP\_TYPE\_XPM)
|
|
\end{itemize}
|
|
|
|
Under wxGTK, wxIcon may load the following formats:
|
|
|
|
\begin{itemize}\itemsep=0pt
|
|
\item XPM data and file (wxBITMAP\_TYPE\_XPM)
|
|
\item All formats that are supported by the \helpref{wxImage}{wximage} class.
|
|
\end{itemize}
|
|
|
|
Under wxMotif, wxIcon may load the following formats:
|
|
|
|
\begin{itemize}\itemsep=0pt
|
|
\item XBM data and file (wxBITMAP\_TYPE\_XBM)
|
|
\item XPM data and file (wxBITMAP\_TYPE\_XPM)
|
|
\item All formats that are supported by the \helpref{wxImage}{wximage} class (?).
|
|
\end{itemize}
|
|
|
|
\wxheading{wxCursor}
|
|
|
|
Under Windows, wxCursor may load the following formats:
|
|
|
|
\begin{itemize}\itemsep=0pt
|
|
\item Windows cursor resource (wxBITMAP\_TYPE\_CUR\_RESOURCE)
|
|
\item Windows cursor file (wxBITMAP\_TYPE\_CUR)
|
|
\item Windows icon file (wxBITMAP\_TYPE\_ICO)
|
|
\item Windows bitmap file (wxBITMAP\_TYPE\_BMP)
|
|
\end{itemize}
|
|
|
|
Under wxGTK, wxCursor may load the following formats (in additional
|
|
to stock cursors):
|
|
|
|
\begin{itemize}\itemsep=0pt
|
|
\item None (stock cursors only).
|
|
\end{itemize}
|
|
|
|
Under wxMotif, wxCursor may load the following formats:
|
|
|
|
\begin{itemize}\itemsep=0pt
|
|
\item XBM data and file (wxBITMAP\_TYPE\_XBM)
|
|
\end{itemize}
|
|
|
|
\subsection{Bitmap format handlers}\label{bitmaphandlers}
|
|
|
|
To provide extensibility, the functionality for loading and saving bitmap formats
|
|
is not implemented in the wxBitmap class, but in a number of handler classes,
|
|
derived from wxBitmapHandler. There is a static list of handlers which wxBitmap
|
|
examines when a file load/save operation is requested. Some handlers are provided as standard, but if you
|
|
have special requirements, you may wish to initialise the wxBitmap class with
|
|
some extra handlers which you write yourself or receive from a third party.
|
|
|
|
To add a handler object to wxBitmap, your application needs to include the header which implements it, and
|
|
then call the static function \helpref{wxBitmap::AddHandler}{wxbitmapaddhandler}. For example:
|
|
|
|
{\small
|
|
\begin{verbatim}
|
|
#include <wx/pnghand.h>
|
|
#include <wx/xpmhand.h>
|
|
...
|
|
// Initialisation
|
|
wxBitmap::AddHandler(new wxPNGFileHandler);
|
|
wxBitmap::AddHandler(new wxXPMFileHandler);
|
|
wxBitmap::AddHandler(new wxXPMDataHandler);
|
|
...
|
|
\end{verbatim}
|
|
}
|
|
|
|
Assuming the handlers have been written correctly, you should now be able to load and save PNG files
|
|
and XPM files using the usual wxBitmap API.
|
|
|
|
{\bf Note:} bitmap handlers are not implemented on all platforms. Currently, the above is only necessary on
|
|
Windows, to save the extra overhead of formats that may not be necessary (if you don't use them, they
|
|
are not linked into the executable). Unix platforms have PNG and XPM capability built-in (where supported).
|
|
|