]> git.saurik.com Git - wxWidgets.git/blobdiff - interface/cursor.h
projects / wxWidgets.git / blobdiff
? search:
summary | shortlog | log | commit | commitdiff | tree
raw | inline | side by side
Finished initial review of the rest of the [c*] interface headers.
[wxWidgets.git] / interface / cursor.h
diff --git a/interface/cursor.h b/interface/cursor.h
index ee6fc7ef0ca5921e160eb149b2b95af1302927d2..09c70fc8bbbdc832e01d2df6e96e39cb4fdf7cc8 100644 (file)
--- a/interface/cursor.h
+++ b/interface/cursor.h
@@ -12,34 +12,91 @@
 
     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
 
     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).
 
     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
 
     @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()
 */
 class wxCursor : public wxBitmap
 {
 public:
 */
 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
         @param bits
             An array of bits.
         @param maskBits
@@ -52,401 +109,120 @@ public:
             Hotspot x coordinate.
         @param hotSpotY
             Hotspot y coordinate.
             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,
     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:
+            <ul>
+            <li>wxBITMAP_TYPE_XBM - Load an X bitmap file.</li>
+            </ul>
+            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(const wxString& cursorName, long type,
              int hotSpotX = 0, int hotSpotY = 0);
+    /**
+        Constructs a cursor using a cursor identifier.
+
+        @param cursorId
+            A stock cursor identifier. May be one of the following (note that
+            not all cursors are available on all platforms):
+            - 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.)
+    */
     wxCursor(int cursorId);
     wxCursor(int 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);
     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);
     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();
 
     */
     ~wxCursor();
 
@@ -456,42 +232,17 @@ public:
     bool IsOk() const;
 
     /**
     bool IsOk() const;
 
     /**
-        Assignment operator, using @ref overview_trefcount "reference counting".
+        Assignment operator, using @ref overview_refcount "reference counting".
     */
     wxCursor operator =(const wxCursor& cursor);
 };
 
 
     */
     wxCursor operator =(const wxCursor& cursor);
 };
 
 
-/**
-    FIXME
-*/
-wxCursor Objects:
-;
-
-/**
-    FIXME
-*/
+/** @name Predefined cursors. */
+//@{
 wxCursor wxNullCursor;
 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;
+//@}
 
 
wxWidgets (Impactor)