A fix for attribrute sorting, but it's still broken if there are

[wxWidgets.git] / docs / latex / wx / tbitmap.tex

diff --git a/docs/latex/wx/tbitmap.tex b/docs/latex/wx/tbitmap.tex
index ce20413d8ecc64f38ffa93c8474500950dae83b0..a5ed1140118d37b965f02255c006c56fd5d1240a 100644 (file)
--- 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}.
 
 
 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
 
 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
 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
 
 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}
 
 \begin{verbatim}

-#ifdef wx_x
-#include "aiai.xbm"
+#if defined(__WXGTK__) || defined(__WXMOTIF__)
+#include "mondrian.xpm"

 #endif
 #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
 #endif

-#ifdef wx_x
-  wxIcon *icon = new wxBitmap(aiai_bits, aiai_width, aiai_height);
+
+#if defined(__WXMSW__)
+wxIcon icon("mondrian");

 #endif
 \end{verbatim}
 
 #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,
 
 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}
 
 {\small
 \begin{verbatim}

-  #include "JPEGBitmapHandler.h"
+  #include <wx/xpmhand.h>

   ...
   // Initialisation
   ...
   // Initialisation

-  wxBitmap::AddHandler(new wxJPEGBitmapHandler);
+  wxBitmap::AddHandler(new wxXPMFileHandler);
+  wxBitmap::AddHandler(new wxXPMDataHandler);

   ...
 \end{verbatim}
 }
 
   ...
 \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.