MF_BYCOMMAND is zero so don't try to test it

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

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

-#if defined(__WXGTK__) || defined(__WXMOTIF__)

 #include "mondrian.xpm"
 #include "mondrian.xpm"

-#endif

 \end{verbatim}
 
 \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.
 
 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
 \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
 
 \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}
 
 
 \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)
 \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 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
 \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 XPM data and file (wxBITMAP\_TYPE\_XPM)

+\item All formats that are supported by the \helpref{wxImage}{wximage} class.

 \end{itemize}
 
 \end{itemize}
 

-Under wxMotif, wxBitmap may load the following formats:
+Under wxMotif and wxX11, wxBitmap may load the following formats:

 
 \begin{itemize}\itemsep=0pt
 
 \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 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}
 \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
 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 XPM data and file (wxBITMAP\_TYPE\_XPM)

+\item All formats that are supported by the \helpref{wxImage}{wximage} class.

 \end{itemize}
 
 \end{itemize}
 

-Under wxMotif, wxIcon may load the following formats:
+Under wxMotif and wxX11, wxIcon may load the following formats:

 
 \begin{itemize}\itemsep=0pt
 
 \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 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}
 \end{itemize}
 
 \wxheading{wxCursor}


@@ -150,7 +148,7 @@ to stock cursors):
 \item None (stock cursors only).
 \end{itemize}
 
 \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)
 
 \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
 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.
+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.