an example).
A single cursor object may be used in many windows (any subwindow type).
-The wxWindows convention is to set the cursor for a window, as in X,
+The wxWidgets convention is to set the cursor for a window, as in X,
rather than to set it globally as in MS Windows, although a
global \helpref{::wxSetCursor}{wxsetcursor} is also available for MS Windows use.
\helpref{wxGDIObject}{wxgdiobject}\\
\helpref{wxObject}{wxobject}
+\wxheading{Include files}
+
+<wx/cursor.h>
+
+\wxheading{Library}
+
+\helpref{wxCore}{librarieslist}
+
+\wxheading{Predefined objects}
+
+Objects:
+
+{\bf wxNullCursor}
+
+Pointers:
+
+{\bf wxSTANDARD\_CURSOR\\
+wxHOURGLASS\_CURSOR\\
+wxCROSS\_CURSOR}
+
\wxheading{See also}
\helpref{wxBitmap}{wxbitmap}, \helpref{wxIcon}{wxicon}, \helpref{wxWindow::SetCursor}{wxwindowsetcursor},\rtfsp
\latexignore{\rtfignore{\wxheading{Members}}}
-\membersection{wxCursor::wxCursor}\label{wxcursorconstr}
+\membersection{wxCursor::wxCursor}\label{wxcursorctor}
\func{}{wxCursor}{\void}
Default constructor.
-\func{}{wxCursor}{\param{const char}{ bits[]}, \param{const int }{width},
- \param{const int }{ height}, \param{const int }{hotSpotX=-1}, \param{const int }{hotSpotY=-1}, \param{const char }{maskBits[]=NULL}}
+\func{}{wxCursor}{\param{const char}{ bits[]}, \param{int }{width},
+ \param{int }{ height}, \param{int }{hotSpotX=-1}, \param{int }{hotSpotY=-1}, \param{const char }{maskBits[]=NULL},
+ \param{wxColour*}{ fg=NULL}, \param{wxColour*}{ bg=NULL}}
-Constructs a cursor by passing an array of bits (Motif and Xt only). {\it maskBits} is used only under Motif.
+Constructs a cursor by passing an array of bits (Motif and GTK+ only). {\it maskBits} is used only under
+Motif and GTK+. The parameters {\it fg} and {\it bg} are only present on GTK+, and force the
+cursor to use particular background and foreground colours.
If either {\it hotSpotX} or {\it hotSpotY} is -1, the hotspot will be the centre of the cursor image (Motif only).
-\func{}{wxCursor}{\param{const wxString\& }{cursorName}, \param{const long }{type}, \param{const int }{hotSpotX=0}, \param{const int }{hotSpotY=0}}
+\func{}{wxCursor}{\param{const wxString\& }{cursorName}, \param{long }{type}, \param{int }{hotSpotX=0}, \param{int }{hotSpotY=0}}
Constructs a cursor by passing a string resource name or filename.
+On MacOS when specifying a string resource name, first the color cursors 'crsr' and then the black/white cursors 'CURS' in the resource chain are scanned through.
+
{\it hotSpotX} and {\it hotSpotY} are currently only used under Windows when loading from an
icon file, to specify the cursor hotspot relative to the top left of the image.
-\func{}{wxCursor}{\param{const int}{ cursorId}}
+\func{}{wxCursor}{\param{int}{ cursorId}}
Constructs a cursor using a cursor identifier.
-\func{}{wxCursor}{\param{const wxCursor\&}{ cursor}}
+\func{}{wxCursor}{\param{const wxImage\&}{ image}}
+
+Constructs a cursor from a wxImage. If cursor are monochrome on the current
+platform, colors with the RGB elements all greater than 127 will be foreground,
+colors less than this background. The mask (if any) will be used to specify the
+transparent area.
-Copy constructor. This uses reference counting so is a cheap operation.
+In wxMSW the foreground will be white and the background black. If the cursor
+is larger than 32x32 it is resized.
-\func{}{wxCursor}{\param{const wxCursor*}{ cursor}}
+In wxGTK, colour cursors and alpha channel are supported (starting from GTK+
+2.2). Otherwise the two most frequent colors will be used for foreground and
+background. In any case, the cursor will be displayed at the size of the image.
-Copy constructor. This uses reference counting so is a cheap operation.
+In wxMac, if the cursor is larger than 16x16 it is resized and currently only
+shown as black/white (mask respected).
+
+\func{}{wxCursor}{\param{const wxCursor\&}{ cursor}}
+
+Copy constructor, uses \helpref{reference counting}{trefcount}.
\wxheading{Parameters}
\docparam{hotSpotY}{Hotspot y coordinate.}
\docparam{type}{Icon type to load. Under Motif, {\it type} defaults to {\bf wxBITMAP\_TYPE\_XBM}. Under Windows,
-it defaults to {\bf wxBITMAP\_TYPE\_CUR\_RESOURCE}.
+it defaults to {\bf wxBITMAP\_TYPE\_CUR\_RESOURCE}. Under MacOS, it defaults to {\bf wxBITMAP\_TYPE\_MACCURSOR\_RESOURCE}.
Under X, the permitted cursor types are:
\twocolwidtha{6cm}
\begin{twocollist}\itemsep=0pt
\twocolitem{\windowstyle{wxBITMAP\_TYPE\_CUR}}{Load a cursor from a .cur cursor file (only if USE\_RESOURCE\_LOADING\_IN\_MSW
-is enabled in wx\_setup.h).}
+is enabled in setup.h).}
\twocolitem{\windowstyle{wxBITMAP\_TYPE\_CUR\_RESOURCE}}{Load a Windows resource (as specified in the .rc file).}
\twocolitem{\windowstyle{wxBITMAP\_TYPE\_ICO}}{Load a cursor from a .ico icon file (only if USE\_RESOURCE\_LOADING\_IN\_MSW
-is enabled in wx\_setup.h). Specify {\it hotSpotX} and {\it hotSpotY}.}
+is enabled in setup.h). Specify {\it hotSpotX} and {\it hotSpotY}.}
\end{twocollist}}
\docparam{cursorId}{A stock cursor identifier. May be one of:
\twocolwidtha{6cm}
\begin{twocollist}\itemsep=0pt
\twocolitem{{\bf wxCURSOR\_ARROW}}{A standard arrow cursor.}
+\twocolitem{{\bf wxCURSOR\_RIGHT\_ARROW}}{A standard arrow cursor
+pointing to the right.}
+\twocolitem{{\bf wxCURSOR\_BLANK}}{Transparent cursor.}
\twocolitem{{\bf wxCURSOR\_BULLSEYE}}{Bullseye cursor.}
\twocolitem{{\bf wxCURSOR\_CHAR}}{Rectangular character cursor.}
\twocolitem{{\bf wxCURSOR\_CROSS}}{A cross cursor.}
\twocolitem{{\bf wxCURSOR\_SPRAYCAN}}{A spraycan cursor.}
\twocolitem{{\bf wxCURSOR\_WAIT}}{A wait cursor.}
\twocolitem{{\bf wxCURSOR\_WATCH}}{A watch cursor.}
+\twocolitem{{\bf wxCURSOR\_ARROWWAIT}}{A cursor with both an arrow and
+an hourglass, (windows.)}
\end{twocollist}\twocolwidtha{5cm}
Note that not all cursors are available on all platforms.}
\docparam{cursor}{Pointer or reference to a cursor to copy.}
-\membersection{wxCursor::\destruct{wxCursor}}
+\pythonnote{Constructors supported by wxPython are:\par
+\indented{2cm}{\begin{twocollist}
+\twocolitem{{\bf wxCursor(name, flags, hotSpotX=0,
+hotSpotY=0)}}{Constructs a cursor from a filename}
+\twocolitem{{\bf wxStockCursor(id)}}{Constructs a stock cursor }
+\end{twocollist}}
+}
+
+\perlnote{Constructors supported by wxPerl are:\par
+\begin{itemize}
+\item{Wx::Cursor->new( name, type, hotSpotX = 0, hotSpotY = 0 )}
+\item{Wx::Cursor->new( id )}
+\item{Wx::Cursor->new( image )}
+\item{Wx::Cursor->newData( bits, width, height, hotSpotX = -1, hotSpotY = -1, maskBits = 0 )}
+\end{itemize}
+}
+
+\wxheading{Example}
+
+The following is an example of creating a
+cursor from 32x32 bitmap data ({\tt down\_bits}) and a mask
+({\tt down\_mask}) where 1 is black and 0 is white for
+the bits, and 1 is opaque and 0 is transparent for
+the mask. It works on Windows and GTK+.
+
+\begin{verbatim}
+static char down_bits[] = { 255, 255, 255, 255, 31,
+ 255, 255, 255, 31, 255, 255, 255, 31, 255, 255, 255,
+ 31, 255, 255, 255, 31, 255, 255, 255, 31, 255, 255,
+ 255, 31, 255, 255, 255, 31, 255, 255, 255, 25, 243,
+ 255, 255, 19, 249, 255, 255, 7, 252, 255, 255, 15, 254,
+ 255, 255, 31, 255, 255, 255, 191, 255, 255, 255, 255,
+ 255, 255, 255, 255, 255, 255, 255, 255, 255, 255, 255,
+ 255, 255, 255, 255, 255, 255, 255, 255, 255, 255, 255,
+ 255, 255, 255, 255, 255, 255, 255, 255, 255, 255, 255,
+ 255, 255, 255, 255, 255, 255, 255, 255, 255, 255, 255,
+ 255, 255, 255, 255, 255, 255, 255, 255, 255, 255, 255,
+ 255, 255, 255, 255, 255, 255, 255, 255, 255, 255, 255,
+ 255 };
+
+static char down_mask[] = { 240, 1, 0, 0, 240, 1,
+ 0, 0, 240, 1, 0, 0, 240, 1, 0, 0, 240, 1, 0, 0, 240, 1,
+ 0, 0, 240, 1, 0, 0, 240, 1, 0, 0, 255, 31, 0, 0, 255,
+ 31, 0, 0, 254, 15, 0, 0, 252, 7, 0, 0, 248, 3, 0, 0,
+ 240, 1, 0, 0, 224, 0, 0, 0, 64, 0, 0, 0, 0, 0, 0, 0, 0,
+ 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0,
+ 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0,
+ 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0,
+ 0, 0, 0, 0, 0 };
+
+#ifdef __WXMSW__
+wxBitmap down_bitmap(down_bits, 32, 32);
+wxBitmap down_mask_bitmap(down_mask, 32, 32);
+
+down_bitmap.SetMask(new wxMask(down_mask_bitmap));
+wxImage down_image = down_bitmap.ConvertToImage();
+down_image.SetOption(wxIMAGE_OPTION_CUR_HOTSPOT_X, 6);
+down_image.SetOption(wxIMAGE_OPTION_CUR_HOTSPOT_Y, 14);
+wxCursor down_cursor = wxCursor(down_image);
+#else
+wxCursor down_cursor = wxCursor(down_bits, 32, 32,
+ 6, 14, down_mask, wxWHITE, wxBLACK);
+#endif
+\end{verbatim}
+
+\membersection{wxCursor::\destruct{wxCursor}}\label{wxcursordtor}
\func{}{\destruct{wxCursor}}{\void}
-Destroys the cursor. A cursor can be reused for more
+Destroys the cursor.
+See \helpref{reference-counted object destruction}{refcountdestruct} for more info.
+
+A cursor can be reused for more
than one window, and does not get destroyed when the window is
-destroyed. wxWindows destroys all cursors on application exit, although
-it's best to clean them up explicitly.
+destroyed. wxWidgets destroys all cursors on application exit, although
+it is best to clean them up explicitly.
-\membersection{wxCursor::Ok}\label{wxcursorok}
+\membersection{wxCursor::IsOk}\label{wxcursorisok}
-\constfunc{bool}{Ok}{\void}
+\constfunc{bool}{IsOk}{\void}
-Returns TRUE if cursor data is present.
+Returns true if cursor data is present.
\membersection{wxCursor::operator $=$}\label{wxcursorassignment}
\func{wxCursor\&}{operator $=$}{\param{const wxCursor\& }{cursor}}
-Assignment operator, using reference counting. Returns a reference
-to `this'.
-
-\membersection{wxCursor::operator $==$}\label{wxcursorequals}
-
-\func{bool}{operator $==$}{\param{const wxCursor\& }{cursor}}
-
-Equality operator. Two cursors are equal if they contain pointers
-to the same underlying cursor data. It does not compare each attribute,
-so two independently-created cursors using the same parameters will
-fail the test.
-
-\membersection{wxCursor::operator $!=$}\label{wxcursornotequals}
-
-\func{bool}{operator $!=$}{\param{const wxCursor\& }{cursor}}
-
-Inequality operator. Two cursors are not equal if they contain pointers
-to different underlying cursor data. It does not compare each attribute.
-
+Assignment operator, using \helpref{reference counting}{trefcount}.
projects / wxWidgets.git / blobdiff