X-Git-Url: https://git.saurik.com/wxWidgets.git/blobdiff_plain/06d20283afba5439c8a2c1b3b7cd3390541da52d..63415a4212c12ba53f5ca48d16b80bf3bb297a1e:/docs/latex/wx/cursor.tex diff --git a/docs/latex/wx/cursor.tex b/docs/latex/wx/cursor.tex index 9e5d0f41a3..a6f8fceed5 100644 --- a/docs/latex/wx/cursor.tex +++ b/docs/latex/wx/cursor.tex @@ -10,7 +10,7 @@ conditional compilation will probably be required (see \helpref{wxIcon}{wxicon} 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. @@ -24,6 +24,18 @@ global \helpref{::wxSetCursor}{wxsetcursor} is also available for MS Windows use +\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 @@ -31,16 +43,19 @@ global \helpref{::wxSetCursor}{wxsetcursor} is also available for MS Windows use \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{int }{width}, - \param{int }{ height}, \param{int }{hotSpotX=-1}, \param{int }{hotSpotY=-1}, \param{const char }{maskBits[]=NULL}} + \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). @@ -48,6 +63,8 @@ If either {\it hotSpotX} or {\it hotSpotY} is -1, the hotspot will be the centre 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. @@ -55,9 +72,26 @@ icon file, to specify the cursor hotspot relative to the top left of the image. Constructs a cursor using a cursor identifier. +\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. + +In wxMSW the foreground will be white and the background black. If the cursor +is larger than 32x32 it is resized. + +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. + +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. This uses reference counting so is a cheap operation. +Copy constructor, uses \helpref{reference counting}{trefcount}. \wxheading{Parameters} @@ -74,7 +108,7 @@ Copy constructor. This uses reference counting so is a cheap operation. \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: @@ -88,10 +122,10 @@ 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 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: @@ -99,6 +133,9 @@ is enabled in wx\_setup.h). Specify {\it hotSpotX} and {\it hotSpotY}.} \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.} @@ -122,6 +159,8 @@ is enabled in wx\_setup.h). Specify {\it hotSpotX} and {\it hotSpotY}.} \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.} @@ -130,48 +169,90 @@ Note that not all cursors are available on all platforms.} \pythonnote{Constructors supported by wxPython are:\par \indented{2cm}{\begin{twocollist} -\twocolitem{\bf{wxCursor(name, flags, hotSpotX=0, +\twocolitem{{\bf wxCursor(name, flags, hotSpotX=0, hotSpotY=0)}}{Constructs a cursor from a filename} -\twocolitem{\bf{wxStockCursor(id)}}{Constructs a stock cursor } +\twocolitem{{\bf wxStockCursor(id)}}{Constructs a stock cursor } \end{twocollist}} } -\membersection{wxCursor::\destruct{wxCursor}} +\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}.