]> git.saurik.com Git - wxWidgets.git/blame - docs/latex/wx/tbitmap.tex
Small fixes for Tex2RTF but alas, we still get memory problems.
[wxWidgets.git] / docs / latex / wx / tbitmap.tex
CommitLineData
2fd284a4 1\section{Bitmaps and icons overview}\label{wxbitmapoverview}
a660d684
KB
2
3Classes: \helpref{wxBitmap}{wxbitmap}, \helpref{wxBitmapHandler}{wxbitmaphandler}, \helpref{wxIcon}{wxicon}, \helpref{wxCursor}{wxcursor}.
4
5The wxBitmap class encapsulates the concept of a platform-dependent bitmap,
6either monochrome or colour. Platform-specific methods for creating a
7wxBitmap object from an existing file are catered for, and
8this is an occasion where conditional compilation will sometimes be
9required.
10
11A bitmap created dynamically or loaded from a file can be selected
12into a memory device context (instance of \helpref{wxMemoryDC}{wxmemorydc}). This
fe604ccd 13enables the bitmap to be copied to a window or memory device context
a660d684
KB
14using \helpref{wxDC::Blit}{wxdcblit}, or to be used as a drawing surface. The {\bf
15wxToolBarSimple} class is implemented using bitmaps, and the toolbar demo
16shows one of the toolbar bitmaps being used for drawing a miniature
fe604ccd 17version of the graphic which appears on the main window.
a660d684
KB
18
19See \helpref{wxMemoryDC}{wxmemorydc} for an example of drawing onto a bitmap.
20
21The following shows the conditional compilation required to load a
2fd284a4
JS
22bitmap under Unix and in Windows. The alternative is to use the string
23version of the bitmap constructor, which loads a file under Unix and a
24resource or file under Windows, but has the disadvantage of requiring the
25XPM icon file to be available at run-time.
a660d684
KB
26
27\begin{verbatim}
2fd284a4
JS
28#if defined(__WXGTK__) || defined(__WXMOTIF__)
29#include "mondrian.xpm"
a660d684 30#endif
2fd284a4
JS
31\end{verbatim}
32
88b1927c 33A macro, \helpref{wxICON}{wxiconmacro}, is available which creates an icon using an XPM
2fd284a4
JS
34on the appropriate platform, or an icon resource on Windows.
35
36\begin{verbatim}
37wxIcon icon(wxICON(mondrian));
38
39// Equivalent to:
40
41#if defined(__WXGTK__) || defined(__WXMOTIF__)
42wxIcon icon(mondrian_xpm);
a660d684 43#endif
2fd284a4
JS
44
45#if defined(__WXMSW__)
46wxIcon icon("mondrian");
a660d684
KB
47#endif
48\end{verbatim}
49
88b1927c
JS
50There is also a corresponding \helpref{wxBITMAP}{wxbitmapmacro} macro which allows
51to create the bitmaps in much the same way as \helpref{wxICON}{wxiconmacro} creates
0c5d3e1c
VZ
52icons. It assumes that bitmaps live in resources under Windows or OS2 and XPM
53files under all other platforms (for XPMs, the corresponding file must be
54included before this macro is used, of course, and the name of the bitmap
55should be the same as the resource name under Windows with {\tt \_xpm}
56suffix). For example:
57
58\begin{verbatim}
59// an easy and portable way to create a bitmap
60wxBitmap bmp(wxBITMAP(bmpname));
61
62// which is roughly equivalent to the following
63#if defined(__WXMSW__) || defined(__WXPM__)
64 wxBitmap bmp("bmpname", wxBITMAP_TYPE_RESOURCE);
65#else // Unix
66 wxBitmap bmp(bmpname_xpm, wxBITMAP_TYPE_XPM);
67#endif
68\end{verbatim}
69
70You should always use wxICON and wxBITMAP macros because they work for any
71platform (unlike the code above which doesn't deal with wxMac, wxBe, ...) and
605d715d 72are more short and clear than versions with {\tt \#ifdef}s.
0c5d3e1c 73
2fd284a4
JS
74\subsection{Supported bitmap file formats}\label{supportedbitmapformats}
75
76The following lists the formats handled on different platforms. Note
ccaaf5b0
RR
77that missing or partially-implemented formats are automatically supplemented
78by the \helpref{wxImage}{wximage} to load the data, and then converting
79it to wxBitmap form. Note that using wxImage is the preferred way to
80load images in wxWindows, with the exception of resources (XPM-files or
81native Windows resources). Writing an image format handler for wxImage
82is also far easier than writing one for wxBitmap, because wxImage has
83exactly one format on all platforms wheras wxBitmap can store pixel data
84very differently, depending on colour depths and platform.
2fd284a4
JS
85
86\wxheading{wxBitmap}
87
88Under Windows, wxBitmap may load the following formats:
89
90\begin{itemize}\itemsep=0pt
91\item Windows bitmap resource (wxBITMAP\_TYPE\_BMP\_RESOURCE)
92\item Windows bitmap file (wxBITMAP\_TYPE\_BMP)
2fd284a4 93\item XPM data and file (wxBITMAP\_TYPE\_XPM)
ccaaf5b0 94\item All formats that are supported by the \helpref{wxImage}{wximage} class.
2fd284a4
JS
95\end{itemize}
96
97Under wxGTK, wxBitmap may load the following formats:
98
99\begin{itemize}\itemsep=0pt
2fd284a4 100\item XPM data and file (wxBITMAP\_TYPE\_XPM)
ccaaf5b0 101\item All formats that are supported by the \helpref{wxImage}{wximage} class.
2fd284a4
JS
102\end{itemize}
103
104Under wxMotif, wxBitmap may load the following formats:
a660d684 105
2fd284a4 106\begin{itemize}\itemsep=0pt
2fd284a4
JS
107\item XBM data and file (wxBITMAP\_TYPE\_XBM)
108\item XPM data and file (wxBITMAP\_TYPE\_XPM)
ccaaf5b0 109\item All formats that are supported by the \helpref{wxImage}{wximage} class.
2fd284a4 110\end{itemize}
a660d684 111
2fd284a4 112\wxheading{wxIcon}
a660d684 113
2fd284a4 114Under Windows, wxIcon may load the following formats:
a660d684 115
2fd284a4
JS
116\begin{itemize}\itemsep=0pt
117\item Windows icon resource (wxBITMAP\_TYPE\_ICO\_RESOURCE)
118\item Windows icon file (wxBITMAP\_TYPE\_ICO)
119\item XPM data and file (wxBITMAP\_TYPE\_XPM)
120\end{itemize}
121
122Under wxGTK, wxIcon may load the following formats:
123
124\begin{itemize}\itemsep=0pt
2fd284a4 125\item XPM data and file (wxBITMAP\_TYPE\_XPM)
ccaaf5b0 126\item All formats that are supported by the \helpref{wxImage}{wximage} class.
2fd284a4
JS
127\end{itemize}
128
129Under wxMotif, wxIcon may load the following formats:
130
131\begin{itemize}\itemsep=0pt
2fd284a4
JS
132\item XBM data and file (wxBITMAP\_TYPE\_XBM)
133\item XPM data and file (wxBITMAP\_TYPE\_XPM)
ccaaf5b0 134\item All formats that are supported by the \helpref{wxImage}{wximage} class (?).
2fd284a4
JS
135\end{itemize}
136
137\wxheading{wxCursor}
138
139Under Windows, wxCursor may load the following formats:
140
141\begin{itemize}\itemsep=0pt
142\item Windows cursor resource (wxBITMAP\_TYPE\_CUR\_RESOURCE)
143\item Windows cursor file (wxBITMAP\_TYPE\_CUR)
144\item Windows icon file (wxBITMAP\_TYPE\_ICO)
145\item Windows bitmap file (wxBITMAP\_TYPE\_BMP)
146\end{itemize}
147
148Under wxGTK, wxCursor may load the following formats (in additional
149to stock cursors):
150
151\begin{itemize}\itemsep=0pt
152\item None (stock cursors only).
153\end{itemize}
154
155Under wxMotif, wxCursor may load the following formats:
156
157\begin{itemize}\itemsep=0pt
158\item XBM data and file (wxBITMAP\_TYPE\_XBM)
159\end{itemize}
160
161\subsection{Bitmap format handlers}\label{bitmaphandlers}
a660d684
KB
162
163To provide extensibility, the functionality for loading and saving bitmap formats
164is not implemented in the wxBitmap class, but in a number of handler classes,
165derived from wxBitmapHandler. There is a static list of handlers which wxBitmap
166examines when a file load/save operation is requested. Some handlers are provided as standard, but if you
167have special requirements, you may wish to initialise the wxBitmap class with
168some extra handlers which you write yourself or receive from a third party.
169
170To add a handler object to wxBitmap, your application needs to include the header which implements it, and
171then call the static function \helpref{wxBitmap::AddHandler}{wxbitmapaddhandler}. For example:
172
173{\small
174\begin{verbatim}
2fd284a4
JS
175 #include <wx/pnghand.h>
176 #include <wx/xpmhand.h>
a660d684
KB
177 ...
178 // Initialisation
2fd284a4
JS
179 wxBitmap::AddHandler(new wxPNGFileHandler);
180 wxBitmap::AddHandler(new wxXPMFileHandler);
181 wxBitmap::AddHandler(new wxXPMDataHandler);
a660d684
KB
182 ...
183\end{verbatim}
184}
185
2fd284a4
JS
186Assuming the handlers have been written correctly, you should now be able to load and save PNG files
187and XPM files using the usual wxBitmap API.
a660d684 188
2fd284a4
JS
189{\bf Note:} bitmap handlers are not implemented on all platforms. Currently, the above is only necessary on
190Windows, to save the extra overhead of formats that may not be necessary (if you don't use them, they
191are not linked into the executable). Unix platforms have PNG and XPM capability built-in (where supported).
a660d684 192