X-Git-Url: https://git.saurik.com/wxWidgets.git/blobdiff_plain/88b1927cb3da30ac43126d57bff6ccd5b5822c73..65baafba0e8cd74f2264b7e2f7625ff5bea84864:/docs/latex/wx/tbitmap.tex diff --git a/docs/latex/wx/tbitmap.tex b/docs/latex/wx/tbitmap.tex index 5a3ed4efac..48db4af4e4 100644 --- a/docs/latex/wx/tbitmap.tex +++ b/docs/latex/wx/tbitmap.tex @@ -11,25 +11,20 @@ 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. +using \helpref{wxDC::Blit}{wxdcblit}, or to be used as a drawing surface. 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. +All wxWidgets platforms support XPMs for small bitmaps and icons. +You may include the XPM inline as below, since it's C code, or you +can load it at run-time. \begin{verbatim} -#if defined(__WXGTK__) || defined(__WXMOTIF__) #include "mondrian.xpm" -#endif \end{verbatim} +Sometimes you wish to use a .ico resource on Windows, and XPMs on +other platforms (for example to take advantage of Windows' support for multiple icon resolutions). A macro, \helpref{wxICON}{wxiconmacro}, is available which creates an icon using an XPM on the appropriate platform, or an icon resource on Windows. @@ -68,15 +63,21 @@ wxBitmap bmp(wxBITMAP(bmpname)); \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. +platform (unlike the code above which doesn't deal with wxMac, wxX11, ...) and +are more short and clear than versions with {\tt \#ifdef}s. Even better, +use the same XPMs on all platforms. \subsection{Supported bitmap file formats}\label{supportedbitmapformats} The following lists the formats handled on different platforms. Note -that missing or partially-implemented formats can be supplemented -by using \helpref{wxImage}{wximage} to load the data, and then converting -it to wxBitmap form. +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 wxWidgets, 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} @@ -85,25 +86,23 @@ 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 PNG file (wxBITMAP\_TYPE\_PNG). Currently 4-bit (16-colour) PNG files do not load properly. \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 Windows bitmap file (wxBITMAP\_TYPE\_BMP) -\item PNG (wxBITMAP\_TYPE\_PNG). \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: +Under wxMotif and wxX11, wxBitmap may load the following formats: \begin{itemize}\itemsep=0pt -%\item Windows bitmap file (wxBITMAP\_TYPE\_BMP) -%\item PNG (wxBITMAP\_TYPE\_PNG). \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} @@ -119,17 +118,16 @@ Under Windows, wxIcon may load the following formats: Under wxGTK, wxIcon may load the following formats: \begin{itemize}\itemsep=0pt -\item PNG (wxBITMAP\_TYPE\_PNG). \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: +Under wxMotif and wxX11, wxIcon may load the following formats: \begin{itemize}\itemsep=0pt -%\item Windows bitmap file (wxBITMAP\_TYPE\_BMP) -%\item PNG (wxBITMAP\_TYPE\_PNG). \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} @@ -150,7 +148,7 @@ to stock cursors): \item None (stock cursors only). \end{itemize} -Under wxMotif, wxCursor may load the following formats: +Under wxMotif and wxX11, wxCursor may load the following formats: \begin{itemize}\itemsep=0pt \item XBM data and file (wxBITMAP\_TYPE\_XBM) @@ -166,25 +164,8 @@ 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 - #include - ... - // 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. +then call the static function \helpref{wxBitmap::AddHandler}{wxbitmapaddhandler}. -{\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). +{\bf Note:} bitmap handlers are not implemented on all platforms, and new ones rarely need +to be implemented since wxImage can be used for loading most formats, as noted earlier.