X-Git-Url: https://git.saurik.com/wxWidgets.git/blobdiff_plain/e54c96f187f46c06bd36be8cd52b35c19884aa2b..7977b62ae2b56a4ef73ea37659031d96d49f3333:/interface/cursor.h?ds=sidebyside diff --git a/interface/cursor.h b/interface/cursor.h index ee6fc7ef0c..7ffa1fdf10 100644 --- a/interface/cursor.h +++ b/interface/cursor.h @@ -12,34 +12,92 @@ 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 @b wxCursor - object are catered for, and this is an occasion where - conditional compilation will probably be required (see wxIcon for - an example). + 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 wxCursor + object are catered for, and this is an occasion where conditional + compilation will probably be required (see wxIcon for an example). A single cursor object may be used in many windows (any subwindow type). - 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 ::wxSetCursor is also available for MS Windows use. + 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 wxSetCursor() + function is also available for MS Windows use. + + @section cursor_custom Creating a Custom Cursor + + The following is an example of creating a cursor from 32x32 bitmap data + (down_bits) and a mask (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+. + + @code + 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 + @endcode @library{wxcore} @category{gdi} @stdobjects - ::Objects:, ::wxNullCursor, ::Pointers:, ::wxSTANDARD_CURSOR, - ::wxHOURGLASS_CURSOR, ::wxCROSS_CURSOR, + - ::wxNullCursor + - ::wxSTANDARD_CURSOR + - ::wxHOURGLASS_CURSOR + - ::wxCROSS_CURSOR - @see wxBitmap, wxIcon, wxWindow::SetCursor, ::wxSetCursor + @see wxBitmap, wxIcon, wxWindow::SetCursor(), wxSetCursor(), + ::wxStockCursor */ class wxCursor : public wxBitmap { public: - //@{ /** - Copy constructor, uses @ref overview_trefcount "reference counting". - + Default constructor. + */ + wxCursor(); + /** + Constructs a cursor by passing an array of bits (Motif and GTK+ only). + @a maskBits is used only under Motif and GTK+. The parameters @a fg and + @a bg are only present on GTK+, and force the cursor to use particular + background and foreground colours. + + If either @a hotSpotX or @a hotSpotY is -1, the hotspot will be the + centre of the cursor image (Motif only). + @param bits An array of bits. @param maskBits @@ -52,401 +110,87 @@ public: Hotspot x coordinate. @param hotSpotY Hotspot y coordinate. - @param type - Icon type to load. Under Motif, type defaults to wxBITMAP_TYPE_XBM. Under - Windows, - it defaults to wxBITMAP_TYPE_CUR_RESOURCE. Under MacOS, it defaults to - wxBITMAP_TYPE_MACCURSOR_RESOURCE. - Under X, the permitted cursor types are: - - - - - - - - wxBITMAP_TYPE_XBM - - - - - Load an X bitmap file. - - - - - - Under Windows, the permitted types are: - - - - - - - - wxBITMAP_TYPE_CUR - - - - - Load a cursor from a .cur cursor file (only if USE_RESOURCE_LOADING_IN_MSW - is enabled in setup.h). - - - - - - wxBITMAP_TYPE_CUR_RESOURCE - - - - - Load a Windows resource (as specified in the .rc file). - - - - - - wxBITMAP_TYPE_ICO - - - - - Load a cursor from a .ico icon file (only if USE_RESOURCE_LOADING_IN_MSW - is enabled in setup.h). Specify hotSpotX and hotSpotY. - @param cursorId - A stock cursor identifier. May be one of: - - - - - - - - wxCURSOR_ARROW - - - - - A standard arrow cursor. - - - - - - wxCURSOR_RIGHT_ARROW - - - - - A standard arrow cursor - pointing to the right. - - - - - - wxCURSOR_BLANK - - - - - Transparent cursor. - - - - - - wxCURSOR_BULLSEYE - - - - - Bullseye cursor. - - - - - - wxCURSOR_CHAR - - - - - Rectangular character cursor. - - - - - - wxCURSOR_CROSS - - - - - A cross cursor. - - - - - - wxCURSOR_HAND - - - - - A hand cursor. - - - - - - wxCURSOR_IBEAM - - - - - An I-beam cursor (vertical line). - - - - - - wxCURSOR_LEFT_BUTTON - - - - - Represents a mouse with the left button depressed. - - - - - - wxCURSOR_MAGNIFIER - - - - - A magnifier icon. - - - - - - wxCURSOR_MIDDLE_BUTTON - - - - - Represents a mouse with the middle button depressed. - - - - - - wxCURSOR_NO_ENTRY - - - - - A no-entry sign cursor. - - - - - - wxCURSOR_PAINT_BRUSH - - - - - A paintbrush cursor. - - - - - - wxCURSOR_PENCIL - - - - - A pencil cursor. - - - - - - wxCURSOR_POINT_LEFT - - - - - A cursor that points left. - - - - - - wxCURSOR_POINT_RIGHT - - - - - A cursor that points right. - - - - - - wxCURSOR_QUESTION_ARROW - - - - - An arrow and question mark. - - - - - - wxCURSOR_RIGHT_BUTTON - - - - - Represents a mouse with the right button depressed. - - - - - - wxCURSOR_SIZENESW - - - - - A sizing cursor pointing NE-SW. - - - - - - wxCURSOR_SIZENS - - - - - A sizing cursor pointing N-S. - - - - - - wxCURSOR_SIZENWSE - - - - - A sizing cursor pointing NW-SE. - - - - - - wxCURSOR_SIZEWE - - - - - A sizing cursor pointing W-E. - - - - - - wxCURSOR_SIZING - - - - - A general sizing cursor. - - - - - - wxCURSOR_SPRAYCAN - - - - - A spraycan cursor. - - - - - - wxCURSOR_WAIT - - - - - A wait cursor. - - - - - - wxCURSOR_WATCH - - - - - A watch cursor. - - - - - - wxCURSOR_ARROWWAIT - - - - - A cursor with both an arrow and - an hourglass, (windows.) - - - - - - Note that not all cursors are available on all platforms. - @param cursor - Pointer or reference to a cursor to copy. */ - wxCursor(); wxCursor(const char bits[], int width, int height, int hotSpotX = -1, int hotSpotY = -1, const char maskBits[] = NULL, - wxColour* fg = NULL, - wxColour* bg = NULL); + wxColour* fg = NULL, wxColour* bg = NULL); + /** + 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. + + @a hotSpotX and @a 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. + + @param type + Icon type to load. Under Motif, type defaults to wxBITMAP_TYPE_XBM. + Under Windows, it defaults to wxBITMAP_TYPE_CUR_RESOURCE. Under + MacOS, it defaults to wxBITMAP_TYPE_MACCURSOR_RESOURCE. + Under X, the permitted cursor types are: + + Under Windows, the permitted types are: + - wxBITMAP_TYPE_CUR - Load a cursor from a .cur cursor file (only + if USE_RESOURCE_LOADING_IN_MSW is enabled in + setup.h). + - wxBITMAP_TYPE_CUR_RESOURCE - Load a Windows resource (as + specified in the .rc file). + - wxBITMAP_TYPE_ICO - Load a cursor from a .ico icon file (only if + USE_RESOURCE_LOADING_IN_MSW is enabled in + setup.h). Specify @a hotSpotX and @a hotSpotY. + @param hotSpotX + Hotspot x coordinate. + @param hotSpotY + Hotspot y coordinate. + */ wxCursor(const wxString& cursorName, long type, int hotSpotX = 0, int hotSpotY = 0); - wxCursor(int cursorId); + /** + Constructs a cursor using a cursor identifier. + + @param cursorId + A stock cursor identifier. See ::wxStockCursor. + */ + wxCursor(wxStockCursor cursorId); + /** + 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). + */ wxCursor(const wxImage& image); + /** + Copy constructor, uses @ref overview_refcount "reference counting". + + @param cursor + Pointer or reference to a cursor to copy. + */ wxCursor(const wxCursor& cursor); - //@} /** - Destroys the cursor. - See @ref overview_refcountdestruct "reference-counted object destruction" for - more info. - A cursor can be reused for more - than one window, and does not get destroyed when the window is - destroyed. wxWidgets destroys all cursors on application exit, although - it is best to clean them up explicitly. + Destroys the cursor. See + @ref overview_refcount_destruct "reference-counted object destruction" + for more info. + + A cursor can be reused for more than one window, and does not get + destroyed when the window is destroyed. wxWidgets destroys all cursors + on application exit, although it is best to clean them up explicitly. */ ~wxCursor(); @@ -456,42 +200,21 @@ public: bool IsOk() const; /** - Assignment operator, using @ref overview_trefcount "reference counting". + Assignment operator, using @ref overview_refcount "reference counting". */ wxCursor operator =(const wxCursor& cursor); }; /** - FIXME -*/ -wxCursor Objects: -; + @name Predefined cursors. -/** - FIXME + @see wxStockCursor */ +//@{ wxCursor wxNullCursor; - -/** - FIXME -*/ -wxCursor Pointers: -; - -/** - FIXME -*/ -wxCursor wxSTANDARD_CURSOR; - -/** - FIXME -*/ -wxCursor wxHOURGLASS_CURSOR; - -/** - FIXME -*/ -wxCursor wxCROSS_CURSOR; - +wxCursor* wxSTANDARD_CURSOR; +wxCursor* wxHOURGLASS_CURSOR; +wxCursor* wxCROSS_CURSOR; +//@}