X-Git-Url: https://git.saurik.com/wxWidgets.git/blobdiff_plain/a660d684eda27638bca0384b2058911a31c8e845..8dba8632c5bcd64724e2e9e2d40e295555a0cb86:/docs/latex/wx/tbitmap.tex diff --git a/docs/latex/wx/tbitmap.tex b/docs/latex/wx/tbitmap.tex index ce20413d8e..a5ed114011 100644 --- a/docs/latex/wx/tbitmap.tex +++ b/docs/latex/wx/tbitmap.tex @@ -1,4 +1,4 @@ -\section{Bitmaps overview}\label{wxbitmapoverview} +\section{Bitmaps and icons overview}\label{wxbitmapoverview} Classes: \helpref{wxBitmap}{wxbitmap}, \helpref{wxBitmapHandler}{wxbitmaphandler}, \helpref{wxIcon}{wxicon}, \helpref{wxCursor}{wxcursor}. @@ -10,49 +10,155 @@ 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 canvas or memory device context +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 canvas. +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 in X and in Windows 3. The alternative is to use the string -version of the bitmap constructor, which loads a file under X and a -resource under Windows 3, but has the disadvantage of requiring the -X icon file to be available at run-time. +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} -#ifdef wx_x -#include "aiai.xbm" +#if defined(__WXGTK__) || defined(__WXMOTIF__) +#include "mondrian.xpm" #endif -#ifdef wx_msw - wxIcon *icon = new wxBitmap("aiai"); +\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 -#ifdef wx_x - wxIcon *icon = new wxBitmap(aiai_bits, aiai_width, aiai_height); + +#if defined(__WXMSW__) +wxIcon icon("mondrian"); #endif \end{verbatim} -\subsection{Loading bitmaps: further information} +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 whereas 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} -There is provision for a number of bitmap -formats via the standard wxBitmap class. These facilities can -be enabled or disabled using settings in wx\_setup.h. +Under wxGTK, wxBitmap may load the following formats: -XPM colour pixmaps may be loaded and saved under Windows and X, with -some restrictions imposed by the lack of colourmap facility when -using XPM files. The user may elect to use XPM files as a cross-platform -stabdard, or translate between XPM and BMP files using a suitable -utility. +\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} -Also, under Windows, DIBs (device independent bitmaps with extension BMP) -may be dynamically loaded and saved. Under X, GIF and BMP files may be -loaded but not saved. +Under wxMotif, wxBitmap may load the following formats: -\subsection{Bitmap format handlers} +\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, @@ -66,20 +172,23 @@ then call the static function \helpref{wxBitmap::AddHandler}{wxbitmapaddhandler} {\small \begin{verbatim} - #include "JPEGBitmapHandler.h" + #include ... // Initialisation - wxBitmap::AddHandler(new wxJPEGBitmapHandler); + wxBitmap::AddHandler(new wxXPMFileHandler); + wxBitmap::AddHandler(new wxXPMDataHandler); ... \end{verbatim} } -Assuming wxJPEGBitmapHandler has been written correctly, you should now be able to load and save JPEG files -using the usual wxBitmap API. - -To see how bitmap handlers are implemented, please look at the files {\tt bitmap.h} and {\tt bitmap.cpp}. +Assuming the handlers have been written correctly, you should now be able to load and save +XPM files using the usual wxBitmap API. -\subsection{wxIcon overview}\label{wxiconoverview} +{\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 XPM capability built-in (where supported). -TODO. +Also, just because a handler (such as a PNG handler) is not present does not mean that +wxBitmap does not support that file format. If wxBitmap fails to find a suitable handler, +the file-loading capabilities of wxImage are used instead.