fixed typo in HitTest() docs

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

diff --git a/docs/latex/wx/icon.tex b/docs/latex/wx/icon.tex
index 421d68e487f9ebb4f9e92b97bad422d3474ca214..75319cf0b138b88fe0f8bf911a28841b91816cb5 100644 (file)
--- a/docs/latex/wx/icon.tex
+++ b/docs/latex/wx/icon.tex
@@ -1,55 +1,57 @@
 \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}}}
 

-\membersection{wxIcon::wxIcon}\label{wxiconconstr}
+\membersection{wxIcon::wxIcon}\label{wxiconctor}

 
 \func{}{wxIcon}{\void}
 
 
 \func{}{wxIcon}{\void}
 


@@ -57,31 +59,36 @@ Default constructor.
 
 \func{}{wxIcon}{\param{const wxIcon\& }{icon}}
 
 
 \func{}{wxIcon}{\param{const wxIcon\& }{icon}}
 

-\func{}{wxIcon}{\param{const wxIcon* }{icon}}
-
-Copy constructors.
+Copy constructor.

 
 

-\func{}{wxIcon}{\param{void*}{ data}, \param{const int}{ type}, \param{const int}{ width}, \param{const int}{ height}, \param{const int}{ depth = -1}}
+\func{}{wxIcon}{\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.
 
 
 Creates an icon from the given data, which can be of arbitrary type.
 

-\func{}{wxIcon}{\param{const char}{ bits[]}, \param{const int}{ width}, \param{const int}{ height}\\
-  \param{const int}{ depth = 1}}
+\func{}{wxIcon}{\param{const char}{ bits[]}, \param{int}{ width}, \param{int}{ height}\\
+  \param{int}{ depth = 1}}

 
 Creates an icon from an array of bits.
 
 
 Creates an icon from an array of bits.
 

-\func{}{wxIcon}{\param{const int}{ width}, \param{const int}{ height}, \param{const int}{ depth = -1}}
+\func{}{wxIcon}{\param{int}{ width}, \param{int}{ height}, \param{int}{ depth = -1}}

 
 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{const long}{ type}}
+\func{}{wxIcon}{\param{const wxString\& }{name}, \param{wxBitmapType}{ 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.
 

+\func{}{wxIcon}{\param{const wxIconLocation\& }{loc}}
+
+Loads an icon from the specified \helpref{location}{wxiconlocation}.
+

 \wxheading{Parameters}
 
 \docparam{bits}{Specifies an array of pixel values.}
 \wxheading{Parameters}
 
 \docparam{bits}{Specifies an array of pixel values.}


@@ -90,27 +97,39 @@ 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{name}{This can refer to a resource name under MS Windows, or a filename under MS Windows and X.
 Its meaning is determined by the {\it flags} parameter.}
 
 \docparam{depth}{Specifies the depth of the icon. If this is omitted, the display depth of the
 screen is used.}
 
 \docparam{name}{This can refer to a resource name under MS Windows, or a filename under MS Windows and X.
 Its meaning is determined by the {\it flags} parameter.}
 

+\docparam{loc}{The object describing the location of the native icon, see 
+\helpref{wxIconLocation}{wxiconlocation}.}
+

 \docparam{type}{May be one of the following:
 
 \twocolwidtha{5cm}
 \begin{twocollist}
 \docparam{type}{May be one of the following:
 
 \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}
 
 \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.}
+The validity of these flags depends on the platform and wxWidgets configuration.
+If all possible wxWidgets 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}
 


@@ -129,7 +148,7 @@ X and Windows.
 
 The sixth form constructs a new icon.
 
 
 The sixth form constructs a new icon.
 

-The seventh form constructs an icon from pixmap (XPM) data, if wxWindows has been configured
+The seventh form constructs an icon from pixmap (XPM) data, if wxWidgets has been configured

 to incorporate this feature.
 
 To use this constructor, you must first include an XPM file. For
 to incorporate this feature.
 
 To use this constructor, you must first include an XPM file. For


@@ -144,17 +163,52 @@ 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}
 

-\membersection{wxIcon::\destruct{wxIcon}}
+\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 )}
+\item{Wx::Icon->newFromBits( bits, width, height, depth = 1 )}
+\item{Wx::Icon->newFromXPM( data )}
+\end{itemize}
+}
+
+\membersection{wxIcon::\destruct{wxIcon}}\label{wxicondtor}

 
 \func{}{\destruct{wxIcon}}{\void}
 
 
 \func{}{\destruct{wxIcon}}{\void}
 


@@ -164,51 +218,11 @@ destroyed at this point - only when the reference count is zero will the
 data be deleted.
 
 If the application omits to delete the icon explicitly, the icon will be
 data be deleted.
 
 If the application omits to delete the icon explicitly, the icon will be

-destroyed automatically by wxWindows when the application exits.
+destroyed automatically by wxWidgets 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{const int}{ width}, \param{const int}{ height}, \param{const 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{const int}{ type}, \param{const int}{ width}, \param{const int}{ height}, \param{const 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}
+\membersection{wxIcon::GetDepth}\label{wxicongetdepth}

 
 \constfunc{int}{GetDepth}{\void}
 
 
 \constfunc{int}{GetDepth}{\void}
 


@@ -233,7 +247,7 @@ Gets the width of the icon in pixels.
 
 \membersection{wxIcon::LoadFile}\label{wxiconloadfile}
 
 
 \membersection{wxIcon::LoadFile}\label{wxiconloadfile}
 

-\func{bool}{LoadFile}{\param{const wxString\&}{ name}, \param{const long}{ type}}
+\func{bool}{LoadFile}{\param{const wxString\&}{ name}, \param{wxBitmapType}{ type}}

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


@@ -253,26 +267,26 @@ The meaning of {\it name} is determined by the {\it type} parameter.}
 \twocolitem{{\bf wxBITMAP\_TYPE\_XPM}}{Load an XPM bitmap file.}
 \end{twocollist}
 
 \twocolitem{{\bf wxBITMAP\_TYPE\_XPM}}{Load an XPM bitmap file.}
 \end{twocollist}
 

-The validity of these flags depends on the platform and wxWindows configuration.}
+The validity of these flags depends on the platform and wxWidgets configuration.}

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

-TRUE if the operation succeeded, FALSE otherwise.
+true if the operation succeeded, false otherwise.

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

-\helpref{wxIcon::wxIcon}{wxiconconstr}
+\helpref{wxIcon::wxIcon}{wxiconctor}

 
 \membersection{wxIcon::Ok}\label{wxiconok}
 
 \constfunc{bool}{Ok}{\void}
 
 
 \membersection{wxIcon::Ok}\label{wxiconok}
 
 \constfunc{bool}{Ok}{\void}
 

-Returns TRUE if icon data is present.
+Returns true if icon data is present.

 
 \begin{comment}
 \membersection{wxIcon::SaveFile}\label{wxiconsavefile}
 
 
 \begin{comment}
 \membersection{wxIcon::SaveFile}\label{wxiconsavefile}
 

-\func{bool}{SaveFile}{\param{const wxString\& }{name}, \param{int}{ type}, \param{wxPalette* }{palette = NULL}}
+\func{bool}{SaveFile}{\param{const wxString\& }{name}, \param{wxBitmapType}{ type}, \param{wxPalette* }{palette = NULL}}

 
 Saves an icon in the named file.
 
 
 Saves an icon in the named file.
 


@@ -290,18 +304,17 @@ Saves an icon in the named file.
 \twocolitem{{\bf wxBITMAP\_TYPE\_XPM}}{Save an XPM bitmap file.}
 \end{twocollist}
 
 \twocolitem{{\bf wxBITMAP\_TYPE\_XPM}}{Save an XPM bitmap file.}
 \end{twocollist}
 

-The validity of these flags depends on the platform and wxWindows configuration.}
+The validity of these flags depends on the platform and wxWidgets 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}
 

-TRUE if the operation succeeded, FALSE otherwise.
+true if the operation succeeded, false otherwise.

 
 \wxheading{Remarks}
 
 
 \wxheading{Remarks}
 

-Depending on how wxWindows has been configured, not all formats may be available.
+Depending on how wxWidgets has been configured, not all formats may be available.

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


@@ -328,17 +341,7 @@ Sets the height member (does not affect the icon data).
 
 \docparam{height}{Icon height in pixels.}
 
 
 \docparam{height}{Icon height in pixels.}
 

-\membersection{wxIcon::SetOk}
-
-\func{void}{SetOk}{\param{int }{isOk}}
-
-Sets the validity member (does not affect the icon data).
-
-\wxheading{Parameters}
-
-\docparam{isOk}{Validity flag.}
-
-\membersection{wxIcon::SetWidth}
+\membersection{wxIcon::SetWidth}\label{wxiconsetwidth}

 
 \func{void}{SetWidth}{\param{int }{width}}
 
 
 \func{void}{SetWidth}{\param{int }{width}}
 


@@ -348,7 +351,7 @@ Sets the width member (does not affect the icon data).
 
 \docparam{width}{Icon width in pixels.}
 
 
 \docparam{width}{Icon width in pixels.}
 

-\membersection{wxIcon::operator $=$}
+\membersection{wxIcon::operator $=$}\label{wxiconassign}

 
 \func{wxIcon\& }{operator $=$}{\param{const wxIcon\& }{icon}}
 
 
 \func{wxIcon\& }{operator $=$}{\param{const wxIcon\& }{icon}}
 


@@ -364,7 +367,7 @@ counter. It is a fast operation.
 
 Returns 'this' object.
 
 
 Returns 'this' object.
 

-\membersection{wxIcon::operator $==$}
+\membersection{wxIcon::operator $==$}\label{wxiconequal}

 
 \func{bool}{operator $==$}{\param{const wxIcon\& }{icon}}
 
 
 \func{bool}{operator $==$}{\param{const wxIcon\& }{icon}}
 


@@ -377,9 +380,9 @@ equal (a fast test).
 
 \wxheading{Return value}
 
 
 \wxheading{Return value}
 

-Returns TRUE if the icons were effectively equal, FALSE otherwise.
+Returns true if the icons were effectively equal, false otherwise.

 
 

-\membersection{wxIcon::operator $!=$}
+\membersection{wxIcon::operator $!=$}\label{wxiconnotequal}

 
 \func{bool}{operator $!=$}{\param{const wxIcon\& }{icon}}
 
 
 \func{bool}{operator $!=$}{\param{const wxIcon\& }{icon}}
 


@@ -392,6 +395,6 @@ unequal (a fast test).
 
 \wxheading{Return value}
 
 
 \wxheading{Return value}
 

-Returns TRUE if the icons were unequal, FALSE otherwise.
+Returns true if the icons were unequal, false otherwise.