Changed documentation const convention for non-objects; added some manual files

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

\section{\class{wxIcon}}\label{wxicon}

An icon is a small rectangular bitmap usually used for denoting a
minimized application.

\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
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
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}

\wxheading{See also}

\helpref{wxIcon overview}{wxiconoverview}, \helpref{wxDC::DrawIcon}{wxdcdrawicon}, \helpref{wxCursor}{wxcursor}

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

\membersection{wxIcon::wxIcon}\label{wxiconconstr}

\func{}{wxIcon}{\void}

Default constructor.

\func{}{wxIcon}{\param{const wxIcon\& }{icon}}

\func{}{wxIcon}{\param{const wxIcon* }{icon}}

Copy constructors.

\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.

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

Creates an icon from an array of bits.

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

Creates a new icon.

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

Creates an icon from XPM data.

\func{}{wxIcon}{\param{const wxString\& }{name}, \param{long}{ type}}

Loads an icon from a file or resource.

\wxheading{Parameters}

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

\docparam{width}{Specifies the width of the icon.}

\docparam{height}{Specifies the height of the icon.}

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

\wxheading{Remarks}

The first form constructs an icon object with no data; an assignment or another member function such as Create
or LoadFile must be called subsequently.

The second and third forms provide copy constructors. Note that these do not copy the
icon data, but instead a pointer to the data, keeping a reference count. They are therefore
very efficient operations.

The fourth form constructs an icon from data whose type and value depends on
the value of the {\it type} argument.

The fifth form constructs a (usually monochrome) icon from an array of pixel values, under both
X and Windows.

The sixth form constructs a new icon.

The seventh form constructs an icon from pixmap (XPM) data, if wxWindows has been configured
to incorporate this feature.

To use this constructor, you must first include an XPM file. For
example, assuming that the file {\tt mybitmap.xpm} contains an XPM array
of character pointers called mybitmap:

\begin{verbatim}
#include "mybitmap.xpm"

...

wxIcon *icon = new wxIcon(mybitmap);
\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.

\wxheading{See also}

\helpref{wxIcon::LoadFile}{wxiconloadfile}

\membersection{wxIcon::\destruct{wxIcon}}

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

Destroys the wxIcon object and possibly the underlying icon data.
Because reference counting is used, the icon may not actually be
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
destroyed automatically by wxWindows when the application exits.

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}

Gets the colour depth of the icon. A value of 1 indicates a
monochrome icon.

\membersection{wxIcon::GetHeight}\label{wxicongetheight}

\constfunc{int}{GetHeight}{\void}

Gets the height of the icon in pixels.

\membersection{wxIcon::GetWidth}\label{wxicongetwidth}

\constfunc{int}{GetWidth}{\void}

Gets the width of the icon in pixels.

\wxheading{See also}

\helpref{wxIcon::GetHeight}{wxicongetheight}

\membersection{wxIcon::LoadFile}\label{wxiconloadfile}

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

Loads an icon from a file or resource.

\wxheading{Parameters}

\docparam{name}{Either a filename or a Windows resource name.
The meaning of {\it name} is determined by the {\it type} parameter.}

\docparam{type}{One of the following values:

\twocolwidtha{5cm}
\begin{twocollist}
\twocolitem{{\bf wxBITMAP\_TYPE\_ICO}}{Load a Windows icon file.}
\twocolitem{{\bf wxBITMAP\_TYPE\_ICO\_RESOURCE}}{Load a Windows icon from the resource database.}
\twocolitem{{\bf wxBITMAP\_TYPE\_GIF}}{Load a GIF bitmap file.}
\twocolitem{{\bf wxBITMAP\_TYPE\_XBM}}{Load an X bitmap file.}
\twocolitem{{\bf wxBITMAP\_TYPE\_XPM}}{Load an XPM bitmap file.}
\end{twocollist}

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

\wxheading{Return value}

TRUE if the operation succeeded, FALSE otherwise.

\wxheading{See also}

\helpref{wxIcon::wxIcon}{wxiconconstr}

\membersection{wxIcon::Ok}\label{wxiconok}

\constfunc{bool}{Ok}{\void}

Returns TRUE if icon data is present.

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

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

Saves an icon in the named file.

\wxheading{Parameters}

\docparam{name}{A filename. The meaning of {\it name} is determined by the {\it type} parameter.}

\docparam{type}{One of the following values:

\twocolwidtha{5cm}
\begin{twocollist}
\twocolitem{{\bf wxBITMAP\_TYPE\_ICO}}{Save a Windows icon file.}
%\twocolitem{{\bf wxBITMAP\_TYPE\_GIF}}{Save a GIF icon file.}
%\twocolitem{{\bf wxBITMAP\_TYPE\_XBM}}{Save an X bitmap file.}
\twocolitem{{\bf wxBITMAP\_TYPE\_XPM}}{Save an XPM bitmap file.}
\end{twocollist}

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.}

\wxheading{Return value}

TRUE if the operation succeeded, FALSE otherwise.

\wxheading{Remarks}

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

\wxheading{See also}

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

\membersection{wxIcon::SetDepth}\label{wxiconsetdepth}

\func{void}{SetDepth}{\param{int }{depth}}

Sets the depth member (does not affect the icon data).

\wxheading{Parameters}

\docparam{depth}{Icon depth.}

\membersection{wxIcon::SetHeight}\label{wxiconsetheight}

\func{void}{SetHeight}{\param{int }{height}}

Sets the height member (does not affect the icon data).

\wxheading{Parameters}

\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}

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

Sets the width member (does not affect the icon data).

\wxheading{Parameters}

\docparam{width}{Icon width in pixels.}

\membersection{wxIcon::operator $=$}

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

Assignment operator. This operator does not copy any data, but instead
passes a pointer to the data in {\it icon} and increments a reference
counter. It is a fast operation.

\wxheading{Parameters}

\docparam{icon}{Icon to assign.}

\wxheading{Return value}

Returns 'this' object.

\membersection{wxIcon::operator $==$}

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

Equality operator. This operator tests whether the internal data pointers are
equal (a fast test).

\wxheading{Parameters}

\docparam{icon}{Icon to compare with 'this'}

\wxheading{Return value}

Returns TRUE if the icons were effectively equal, FALSE otherwise.

\membersection{wxIcon::operator $!=$}

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

Inequality operator. This operator tests whether the internal data pointers are
unequal (a fast test).

\wxheading{Parameters}

\docparam{icon}{Icon to compare with 'this'}

\wxheading{Return value}

Returns TRUE if the icons were unequal, FALSE otherwise.