98b100e271
Jay Berkenbilt git-svn-id: https://svn.wxwidgets.org/svn/wx/wxWidgets/trunk@25642 c3d73ce0-8a6f-49c7-b76d-6d57e0e08775
267 lines
10 KiB
TeX
267 lines
10 KiB
TeX
\section{\class{wxCursor}}\label{wxcursor}
|
|
|
|
A cursor is a small bitmap usually used for denoting where the mouse
|
|
pointer is, with a picture that might indicate the interpretation of a
|
|
mouse click. As with icons, cursors in X and MS Windows are created
|
|
in a different manner. Therefore, separate cursors will be created for the
|
|
different environments. Platform-specific methods for creating a {\bf
|
|
wxCursor} object are catered for, and this is an occasion where
|
|
conditional compilation will probably be required (see \helpref{wxIcon}{wxicon} for
|
|
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,
|
|
rather than to set it globally as in MS Windows, although a
|
|
global \helpref{::wxSetCursor}{wxsetcursor} is also available for MS Windows use.
|
|
|
|
\wxheading{Derived from}
|
|
|
|
\helpref{wxBitmap}{wxbitmap}\\
|
|
\helpref{wxGDIObject}{wxgdiobject}\\
|
|
\helpref{wxObject}{wxobject}
|
|
|
|
\wxheading{Include files}
|
|
|
|
<wx/cursor.h>
|
|
|
|
\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
|
|
\helpref{::wxSetCursor}{wxsetcursor}
|
|
|
|
\latexignore{\rtfignore{\wxheading{Members}}}
|
|
|
|
\membersection{wxCursor::wxCursor}\label{wxcursorconstr}
|
|
|
|
\func{}{wxCursor}{\void}
|
|
|
|
Default constructor.
|
|
|
|
\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 GTK+ only). {\it maskBits} is used only under
|
|
Motif and GTK+. The parameters {\it fg} and {\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{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{int}{ cursorId}}
|
|
|
|
Constructs a cursor using a cursor identifier.
|
|
|
|
\func{}{wxCursor}{\param{const wxImage\&}{ image}}
|
|
|
|
Constructs a cursor from a wxImage. The cursor is monochrome, colors with the RGB elements all greater
|
|
than 127 will be foreground, colors less than this background. The mask (if any) will be used as transparent.
|
|
|
|
In MSW the foreground will be white and the background black. The cursor is resized to 32x32
|
|
In GTK, the two most frequent colors will be used for foreground and background. The cursor will be displayed
|
|
at the size of the image.
|
|
On MacOS the cursor is resized to 16x16 and currently only shown as black/white (mask respected).
|
|
|
|
\func{}{wxCursor}{\param{const wxCursor\&}{ cursor}}
|
|
|
|
Copy constructor. This uses reference counting so is a cheap operation.
|
|
|
|
\wxheading{Parameters}
|
|
|
|
\docparam{bits}{An array of bits.}
|
|
|
|
\docparam{maskBits}{Bits for a mask bitmap.}
|
|
|
|
\docparam{width}{Cursor width.}
|
|
|
|
\docparam{height}{Cursor height.}
|
|
|
|
\docparam{hotSpotX}{Hotspot x coordinate.}
|
|
|
|
\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}. 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\_XBM}}{Load an X bitmap file.}
|
|
\end{twocollist}
|
|
|
|
Under Windows, the permitted 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 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 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\_HAND}}{A hand cursor.}
|
|
\twocolitem{{\bf wxCURSOR\_IBEAM}}{An I-beam cursor (vertical line).}
|
|
\twocolitem{{\bf wxCURSOR\_LEFT\_BUTTON}}{Represents a mouse with the left button depressed.}
|
|
\twocolitem{{\bf wxCURSOR\_MAGNIFIER}}{A magnifier icon.}
|
|
\twocolitem{{\bf wxCURSOR\_MIDDLE\_BUTTON}}{Represents a mouse with the middle button depressed.}
|
|
\twocolitem{{\bf wxCURSOR\_NO\_ENTRY}}{A no-entry sign cursor.}
|
|
\twocolitem{{\bf wxCURSOR\_PAINT\_BRUSH}}{A paintbrush cursor.}
|
|
\twocolitem{{\bf wxCURSOR\_PENCIL}}{A pencil cursor.}
|
|
\twocolitem{{\bf wxCURSOR\_POINT\_LEFT}}{A cursor that points left.}
|
|
\twocolitem{{\bf wxCURSOR\_POINT\_RIGHT}}{A cursor that points right.}
|
|
\twocolitem{{\bf wxCURSOR\_QUESTION\_ARROW}}{An arrow and question mark.}
|
|
\twocolitem{{\bf wxCURSOR\_RIGHT\_BUTTON}}{Represents a mouse with the right button depressed.}
|
|
\twocolitem{{\bf wxCURSOR\_SIZENESW}}{A sizing cursor pointing NE-SW.}
|
|
\twocolitem{{\bf wxCURSOR\_SIZENS}}{A sizing cursor pointing N-S.}
|
|
\twocolitem{{\bf wxCURSOR\_SIZENWSE}}{A sizing cursor pointing NW-SE.}
|
|
\twocolitem{{\bf wxCURSOR\_SIZEWE}}{A sizing cursor pointing W-E.}
|
|
\twocolitem{{\bf wxCURSOR\_SIZING}}{A general sizing 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.}
|
|
|
|
\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}}
|
|
|
|
\func{}{\destruct{wxCursor}}{\void}
|
|
|
|
Destroys the cursor. 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 is best to clean them up explicitly.
|
|
|
|
\membersection{wxCursor::Ok}\label{wxcursorok}
|
|
|
|
\constfunc{bool}{Ok}{\void}
|
|
|
|
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.
|
|
|
|
|