fixed another return FALSE in a function returning a pointer (patch 545046)

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

diff --git a/docs/latex/wx/icon.tex b/docs/latex/wx/icon.tex
index 87193b04c6c867e124cbea8f0acf3e3b3f4c3e78..f6e9d09dc32e9c0c51e85d222482f5fd538a313a 100644 (file)
--- a/docs/latex/wx/icon.tex
+++ b/docs/latex/wx/icon.tex
@@ -1,51 +1,53 @@
 \section{\class{wxIcon}}\label{wxicon}
 
 An icon is a small rectangular bitmap usually used for denoting a
 \section{\class{wxIcon}}\label{wxicon}
 
 An icon is a small rectangular bitmap usually used for denoting a

-minimized application.
+minimized application. It differs from a wxBitmap in always
+having a mask associated with it for transparent drawing. On some platforms,
+icons and bitmaps are implemented identically, since there is no real distinction between
+a wxBitmap with a mask and an icon; and there is no specific icon format on
+some platforms (X-based applications usually standardize on XPMs for small bitmaps
+and icons). However, some platforms (such as Windows) make the distinction, so
+a separate class is provided.
+
+\wxheading{Derived from}
+
+\helpref{wxBitmap}{wxbitmap}\\
+\helpref{wxGDIObject}{wxgdiobject}\\
+\helpref{wxObject}{wxobject}
+
+\wxheading{Include files}
+
+<wx/icon.h>
+
+\wxheading{Predefined objects}
+
+Objects:
+
+{\bf wxNullIcon}

 
 \wxheading{Remarks}
 
 
 \wxheading{Remarks}
 

-It is optional (but desirable) to associate a
-pertinent icon with a frame. Obviously icons in X and MS Windows are
-created in a different manner, and colour icons in X are difficult
-to arrange. Therefore, separate icons will be created for the different
+It is usually desirable to associate a pertinent icon with a frame. Icons
+can also be used for other purposes, for example with \helpref{wxTreeCtrl}{wxtreectrl} 
+and \helpref{wxListCtrl}{wxlistctrl}.
+
+Icons have different formats on different platforms.
+Therefore, separate icons will usually be created for the different

 environments.  Platform-specific methods for creating a {\bf wxIcon}\rtfsp
 structure are catered for, and this is an occasion where conditional
 compilation will probably be required.
 
 Note that a new icon must be created for every time the icon is to be
 environments.  Platform-specific methods for creating a {\bf wxIcon}\rtfsp
 structure are catered for, and this is an occasion where conditional
 compilation will probably be required.
 
 Note that a new icon must be created for every time the icon is to be

-used for a new window. In X, this will ensure that fresh X resources
-are allocated for this frame. In MS Windows, the icon will not be
+used for a new window. In Windows, the icon will not be

 reloaded if it has already been used. An icon allocated to a frame will
 be deleted when the frame is deleted.
 
 reloaded if it has already been used. An icon allocated to a frame will
 be deleted when the frame is deleted.
 

-The following shows the conditional compilation required to define an
-icon in X and in MS Windows. The alternative is to use the string
-version of the icon constructor, which loads a file under X and a
-resource under MS Windows, but has the disadvantage of requiring the
-X icon file to be available at run-time.
-
-\begin{verbatim}
-#ifdef wx_x
-#include "aiai.xbm"
-#endif
-#ifdef wx_msw
-  wxIcon *icon = new wxIcon("aiai");
-#endif
-#ifdef wx_x
-  wxIcon *icon = new wxIcon(aiai_bits, aiai_width, aiai_height);
-#endif
-\end{verbatim}
-
-\wxheading{Derived from}
-
-\helpref{wxBitmap}{wxbitmap}\\
-\helpref{wxGDIObject}{wxgdiobject}\\
-\helpref{wxObject}{wxobject}
+For more information please see \helpref{Bitmap and icon overview}{wxbitmapoverview}.

 
 \wxheading{See also}
 
 
 \wxheading{See also}
 

-\helpref{wxIcon overview}{wxiconoverview}, \helpref{wxDC::DrawIcon}{wxdcdrawicon}, \helpref{wxCursor}{wxcursor}
+\helpref{Bitmap and icon overview}{wxbitmapoverview}, \helpref{supported bitmap file formats}{supportedbitmapformats}, 
+\helpref{wxDC::DrawIcon}{wxdcdrawicon}, \helpref{wxCursor}{wxcursor}

 
 \latexignore{\rtfignore{\wxheading{Members}}}
 
 
 \latexignore{\rtfignore{\wxheading{Members}}}
 


@@ -72,11 +74,14 @@ Creates an icon from an array of bits.
 
 Creates a new icon.
 
 
 Creates a new icon.
 

+\func{}{wxIcon}{\param{char**}{ bits}}
+

 \func{}{wxIcon}{\param{const char**}{ bits}}
 
 Creates an icon from XPM data.
 
 \func{}{wxIcon}{\param{const char**}{ bits}}
 
 Creates an icon from XPM data.
 

-\func{}{wxIcon}{\param{const wxString\& }{name}, \param{long}{ type}}
+\func{}{wxIcon}{\param{const wxString\& }{name}, \param{long}{ type},
+  \param{int}{ desiredWidth = -1}, \param{int}{ desiredHeight = -1}}

 
 Loads an icon from a file or resource.
 
 
 Loads an icon from a file or resource.
 


@@ -88,6 +93,14 @@ Loads an icon from a file or resource.
 
 \docparam{height}{Specifies the height of the icon.}
 
 
 \docparam{height}{Specifies the height of the icon.}
 

+\docparam{desiredWidth}{Specifies the desired width of the icon. This
+parameter only has an effect in Windows (32-bit) where icon resources can contain
+several icons of different sizes.}
+
+\docparam{desiredWidth}{Specifies the desired height of the icon. This
+parameter only has an effect in Windows (32-bit) where icon resources can contain
+several icons of different sizes.}
+

 \docparam{depth}{Specifies the depth of the icon. If this is omitted, the display depth of the
 screen is used.}
 
 \docparam{depth}{Specifies the depth of the icon. If this is omitted, the display depth of the
 screen is used.}
 


@@ -98,17 +111,18 @@ Its meaning is determined by the {\it flags} parameter.}
 
 \twocolwidtha{5cm}
 \begin{twocollist}
 
 \twocolwidtha{5cm}
 \begin{twocollist}

-\twocolitem{{\bf \indexit{wxBITMAP\_TYPE\_ICO}}}{Load a Windows icon file.}
-\twocolitem{{\bf \indexit{wxBITMAP\_TYPE\_ICO\_RESOURCE}}}{Load a Windows icon from the resource database.}
-\twocolitem{{\bf \indexit{wxBITMAP\_TYPE\_GIF}}}{Load a GIF bitmap file.}
-\twocolitem{{\bf \indexit{wxBITMAP\_TYPE\_XBM}}}{Load an X bitmap file.}
-\twocolitem{{\bf \indexit{wxBITMAP\_TYPE\_XPM}}}{Load an XPM bitmap file.}
-%\twocolitem{{\bf \indexit{wxBITMAP\_TYPE\_RESOURCE}}}{Load a Windows resource name.}
+\twocolitem{\indexit{wxBITMAP\_TYPE\_ICO}}{Load a Windows icon file.}
+\twocolitem{\indexit{wxBITMAP\_TYPE\_ICO\_RESOURCE}}{Load a Windows icon from the resource database.}
+\twocolitem{\indexit{wxBITMAP\_TYPE\_GIF}}{Load a GIF bitmap file.}
+\twocolitem{\indexit{wxBITMAP\_TYPE\_XBM}}{Load an X bitmap file.}
+\twocolitem{\indexit{wxBITMAP\_TYPE\_XPM}}{Load an XPM bitmap file.}
+%\twocolitem{\indexit{wxBITMAP\_TYPE\_RESOURCE}}{Load a Windows resource name.}

 \end{twocollist}
 
 The validity of these flags depends on the platform and wxWindows configuration.
 \end{twocollist}
 
 The validity of these flags depends on the platform and wxWindows configuration.

-If all possible wxWindows settings are used, the Windows platform supports ICO, ICO\_RESOURCE,
-XPM\_DATA, and XPM. Under X, the available formats are BMP, GIF, XBM, and XPM.}
+If all possible wxWindows settings are used, the Windows platform supports ICO file, ICO resource,
+XPM data, and XPM file. Under wxGTK, the available formats are BMP file, XPM data, XPM file, and PNG file.
+Under wxMotif, the available formats are XBM data, XBM file, XPM data, XPM file.}

 
 \wxheading{Remarks}
 
 
 \wxheading{Remarks}
 


@@ -142,16 +156,49 @@ of character pointers called mybitmap:
 wxIcon *icon = new wxIcon(mybitmap);
 \end{verbatim}
 
 wxIcon *icon = new wxIcon(mybitmap);
 \end{verbatim}
 

+A macro, wxICON, 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
+
+#if defined(__WXMSW__)
+wxIcon icon("mondrian");
+#endif
+\end{verbatim}
+

 The eighth form constructs an icon from a file or resource. {\it name} can refer
 to a resource name under MS Windows, or a filename under MS Windows and X.
 
 Under Windows, {\it type} defaults to wxBITMAP\_TYPE\_ICO\_RESOURCE.
 The eighth form constructs an icon from a file or resource. {\it name} can refer
 to a resource name under MS Windows, or a filename under MS Windows and X.
 
 Under Windows, {\it type} defaults to wxBITMAP\_TYPE\_ICO\_RESOURCE.

-Under X, {\it type} defaults to wxBITMAP\_TYPE\_XBM.
+Under X, {\it type} defaults to wxBITMAP\_TYPE\_XPM.

 
 \wxheading{See also}
 
 
 \wxheading{See also}
 

+
+\membersection{wxIcon::CopyFromBitmap}\label{wxiconcopyfrombitmap}
+
+\func{void}{CopyFromBitmap}{\param{const wxBitmap\&}{ bmp}}
+
+Copies {\it bmp} bitmap to this icon. Under MS Windows the bitmap
+must have mask colour set.
+
+

 \helpref{wxIcon::LoadFile}{wxiconloadfile}
 
 \helpref{wxIcon::LoadFile}{wxiconloadfile}
 

+\perlnote{Constructors supported by wxPerl are:\par
+\begin{itemize}
+\item{Wx::Icon->new( width, height, depth = -1 )}
+\item{Wx::Icon->new( name, type, desiredWidth = -1, desiredHeight = -1 )}
+\end{itemize}
+}
+

 \membersection{wxIcon::\destruct{wxIcon}}
 
 \func{}{\destruct{wxIcon}}{\void}
 \membersection{wxIcon::\destruct{wxIcon}}
 
 \func{}{\destruct{wxIcon}}{\void}


@@ -166,46 +213,6 @@ destroyed automatically by wxWindows when the application exits.
 
 Do not delete an icon that is selected into a memory device context.
 
 
 Do not delete an icon that is selected into a memory device context.
 

-\begin{comment}
-\membersection{wxIcon::Create}\label{wxiconcreate}
-
-\func{virtual bool}{Create}{\param{int}{ width}, \param{int}{ height}, \param{int}{ depth = -1}}
-
-Creates a fresh icon. If the final argument is omitted, the display depth of
-the screen is used.
-
-\func{virtual bool}{Create}{\param{void*}{ data}, \param{int}{ type}, \param{int}{ width}, \param{int}{ height}, \param{int}{ depth = -1}}
-
-Creates an icon from the given data, which can be of arbitrary type.
-
-\wxheading{Parameters}
-
-\docparam{width}{The width of the icon in pixels.}
-
-\docparam{height}{The height of the icon in pixels.}
-
-\docparam{depth}{The depth of the icon in pixels. If this is -1, the screen depth is used.}
-
-\docparam{data}{Data whose type depends on the value of {\it type}.}
-
-\docparam{type}{An icon type identifier - see \helpref{wxIcon::wxIcon}{wxiconconstr} for a list
-of possible values.}
-
-\wxheading{Return value}
-
-TRUE if the call succeeded, FALSE otherwise.
-
-\wxheading{Remarks}
-
-The first form works on all platforms. The portability of the second form depends on the
-type of data.
-
-\wxheading{See also}
-
-\helpref{wxIcon::wxIcon}{wxiconconstr}
-
-\end{comment}
-

 \membersection{wxIcon::GetDepth}
 
 \constfunc{int}{GetDepth}{\void}
 \membersection{wxIcon::GetDepth}
 
 \constfunc{int}{GetDepth}{\void}


@@ -290,8 +297,7 @@ Saves an icon in the named file.
 
 The validity of these flags depends on the platform and wxWindows configuration.}
 
 
 The validity of these flags depends on the platform and wxWindows configuration.}
 

-\docparam{palette}{An optional palette used for saving the icon. TODO: this parameter should
-probably be eliminated; instead the app should set the palette before saving.}
+\docparam{palette}{An optional palette used for saving the icon.}

 
 \wxheading{Return value}
 
 
 \wxheading{Return value}