\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}
-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
-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.
-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}
-\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}}}
\func{}{wxIcon}{\param{const wxIcon\& }{icon}}
-\func{}{wxIcon}{\param{const wxIcon* }{icon}}
-
-Copy constructors.
+Copy constructor.
\func{}{wxIcon}{\param{void*}{ data}, \param{int}{ type}, \param{int}{ width}, \param{int}{ height}, \param{int}{ depth = -1}}
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 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.
+\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.}
\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{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}
-\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.
-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}
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.
-Under X, {\it type} defaults to wxBITMAP\_TYPE\_XBM.
+Under X, {\it type} defaults to wxBITMAP\_TYPE\_XPM.
\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}
+\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}}
\func{}{\destruct{wxIcon}}{\void}
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}
\wxheading{Return value}
-TRUE if the operation succeeded, FALSE otherwise.
+true if the operation succeeded, false otherwise.
\wxheading{See also}
\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}
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}
-TRUE if the operation succeeded, FALSE otherwise.
+true if the operation succeeded, false otherwise.
\wxheading{Remarks}
\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 $!=$}
\wxheading{Return value}
-Returns TRUE if the icons were unequal, FALSE otherwise.
+Returns true if the icons were unequal, false otherwise.
projects / wxWidgets.git / blobdiff