X-Git-Url: https://git.saurik.com/wxWidgets.git/blobdiff_plain/a660d684eda27638bca0384b2058911a31c8e845..d3e78bab3ea46183c22a5f0484b931a99b897636:/docs/latex/wx/icon.tex diff --git a/docs/latex/wx/icon.tex b/docs/latex/wx/icon.tex index 421d68e487..4a7243fa00 100644 --- 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 -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} + + + +\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}}} @@ -57,31 +59,36 @@ Default constructor. \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. -\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. -\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. +\func{}{wxIcon}{\param{char**}{ bits}} + \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{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.} @@ -90,27 +97,39 @@ Loads an icon from a file or resource. \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} @@ -144,16 +163,51 @@ of character pointers called mybitmap: 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} @@ -168,46 +222,6 @@ 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{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} \constfunc{int}{GetDepth}{\void} @@ -233,7 +247,7 @@ Gets the width of the icon in pixels. \membersection{wxIcon::LoadFile}\label{wxiconloadfile} -\func{bool}{LoadFile}{\param{const wxString\&}{ name}, \param{const long}{ type}} +\func{bool}{LoadFile}{\param{const wxString\&}{ name}, \param{long}{ type}} Loads an icon from a file or resource. @@ -257,7 +271,7 @@ The validity of these flags depends on the platform and wxWindows configuration. \wxheading{Return value} -TRUE if the operation succeeded, FALSE otherwise. +true if the operation succeeded, false otherwise. \wxheading{See also} @@ -267,7 +281,7 @@ TRUE if the operation succeeded, FALSE otherwise. \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} @@ -292,12 +306,11 @@ Saves an icon in the named file. 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} @@ -377,7 +390,7 @@ equal (a fast test). \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 $!=$} @@ -392,6 +405,6 @@ unequal (a fast test). \wxheading{Return value} -Returns TRUE if the icons were unequal, FALSE otherwise. +Returns true if the icons were unequal, false otherwise.