include/SDL_mouse.h
changeset 1895 c121d94672cb
parent 1358 c71e05b4dc2e
child 2242 313112f9ac5c
equal deleted inserted replaced
1894:c69cee13dd76 1895:c121d94672cb
    18 
    18 
    19     Sam Lantinga
    19     Sam Lantinga
    20     slouken@libsdl.org
    20     slouken@libsdl.org
    21 */
    21 */
    22 
    22 
    23 /* Include file for SDL mouse event handling */
    23 /**
       
    24  * \file SDL_mouse.h
       
    25  *
       
    26  * Include file for SDL mouse event handling
       
    27  */
    24 
    28 
    25 #ifndef _SDL_mouse_h
    29 #ifndef _SDL_mouse_h
    26 #define _SDL_mouse_h
    30 #define _SDL_mouse_h
    27 
    31 
    28 #include "SDL_stdinc.h"
    32 #include "SDL_stdinc.h"
    30 #include "SDL_video.h"
    34 #include "SDL_video.h"
    31 
    35 
    32 #include "begin_code.h"
    36 #include "begin_code.h"
    33 /* Set up for C function definitions, even when using C++ */
    37 /* Set up for C function definitions, even when using C++ */
    34 #ifdef __cplusplus
    38 #ifdef __cplusplus
       
    39 /* *INDENT-OFF* */
    35 extern "C" {
    40 extern "C" {
       
    41 /* *INDENT-ON* */
    36 #endif
    42 #endif
    37 
    43 
    38 typedef struct WMcursor WMcursor;	/* Implementation dependent */
    44 typedef struct SDL_Cursor SDL_Cursor;   /* Implementation dependent */
    39 typedef struct SDL_Cursor {
       
    40 	SDL_Rect area;			/* The area of the mouse cursor */
       
    41 	Sint16 hot_x, hot_y;		/* The "tip" of the cursor */
       
    42 	Uint8 *data;			/* B/W cursor data */
       
    43 	Uint8 *mask;			/* B/W cursor mask */
       
    44 	Uint8 *save[2];			/* Place to save cursor area */
       
    45 	WMcursor *wm_cursor;		/* Window-manager cursor */
       
    46 } SDL_Cursor;
       
    47 
    45 
    48 /* Function prototypes */
    46 /* Function prototypes */
    49 /*
    47 
    50  * Retrieve the current state of the mouse.
    48 /**
       
    49  * \fn int SDL_GetNumMice(void)
       
    50  *
       
    51  * \brief Get the number of mouse input devices available.
       
    52  *
       
    53  * \sa SDL_SelectMouse()
       
    54  */
       
    55 extern DECLSPEC int SDLCALL SDL_GetNumMice(void);
       
    56 
       
    57 /**
       
    58  * \fn int SDL_SelectMouse(int index)
       
    59  *
       
    60  * \brief Set the index of the currently selected mouse.
       
    61  *
       
    62  * \return The index of the previously selected mouse.
       
    63  *
       
    64  * \note You can query the currently selected mouse by passing an index of -1.
       
    65  *
       
    66  * \sa SDL_GetNumMice()
       
    67  */
       
    68 extern DECLSPEC int SDLCALL SDL_SelectMouse(int index);
       
    69 
       
    70 /**
       
    71  * \fn SDL_WindowID SDL_GetMouseFocusWindow(void)
       
    72  *
       
    73  * \brief Get the window which currently has focus for the currently selected mouse.
       
    74  */
       
    75 extern DECLSPEC SDL_WindowID SDLCALL SDL_GetMouseFocusWindow(void);
       
    76 
       
    77 /**
       
    78  * \fn int SDL_SetRelativeMouseMode(SDL_bool enabled)
       
    79  *
       
    80  * \brief Set relative mouse mode for the currently selected mouse.
       
    81  *
       
    82  * \param enabled Whether or not to enable relative mode
       
    83  *
       
    84  * \return 0 on success, or -1 if relative mode is not supported.
       
    85  *
       
    86  * While the mouse is in relative mode, the cursor is hidden, and the
       
    87  * driver will try to report continuous motion in the current window.
       
    88  * Only relative motion events will be delivered, the mouse position
       
    89  * will not change.
       
    90  *
       
    91  * \note This function will flush any pending mouse motion.
       
    92  *
       
    93  * \sa SDL_GetRelativeMouseMode()
       
    94  */
       
    95 extern DECLSPEC int SDLCALL SDL_SetRelativeMouseMode(SDL_bool enabled);
       
    96 
       
    97 /**
       
    98  * \fn SDL_bool SDL_GetRelativeMouseMode()
       
    99  *
       
   100  * \brief Query whether relative mouse mode is enabled for the currently selected mouse.
       
   101  *
       
   102  * \sa SDL_SetRelativeMouseMode()
       
   103  */
       
   104 extern DECLSPEC SDL_bool SDLCALL SDL_GetRelativeMouseMode();
       
   105 
       
   106 /**
       
   107  * \fn Uint8 SDL_GetMouseState(int *x, int *y)
       
   108  *
       
   109  * \brief Retrieve the current state of the currently selected mouse.
       
   110  *
    51  * The current button state is returned as a button bitmask, which can
   111  * The current button state is returned as a button bitmask, which can
    52  * be tested using the SDL_BUTTON(X) macros, and x and y are set to the
   112  * be tested using the SDL_BUTTON(X) macros, and x and y are set to the
    53  * current mouse cursor position.  You can pass NULL for either x or y.
   113  * mouse cursor position relative to the focus window for the currently
       
   114  * selected mouse.  You can pass NULL for either x or y.
    54  */
   115  */
    55 extern DECLSPEC Uint8 SDLCALL SDL_GetMouseState(int *x, int *y);
   116 extern DECLSPEC Uint8 SDLCALL SDL_GetMouseState(int *x, int *y);
    56 
   117 
    57 /*
   118 /**
    58  * Retrieve the current state of the mouse.
   119  * \fn Uint8 SDL_GetRelativeMouseState(int *x, int *y)
       
   120  *
       
   121  * \brief Retrieve the state of the currently selected mouse.
       
   122  *
    59  * The current button state is returned as a button bitmask, which can
   123  * The current button state is returned as a button bitmask, which can
    60  * be tested using the SDL_BUTTON(X) macros, and x and y are set to the
   124  * be tested using the SDL_BUTTON(X) macros, and x and y are set to the
    61  * mouse deltas since the last call to SDL_GetRelativeMouseState().
   125  * mouse deltas since the last call to SDL_GetRelativeMouseState().
    62  */
   126  */
    63 extern DECLSPEC Uint8 SDLCALL SDL_GetRelativeMouseState(int *x, int *y);
   127 extern DECLSPEC Uint8 SDLCALL SDL_GetRelativeMouseState(int *x, int *y);
    64 
   128 
    65 /*
   129 /**
    66  * Set the position of the mouse cursor (generates a mouse motion event)
   130  * \fn void SDL_WarpMouseInWindow(SDL_WindowID windowID, int x, int y)
    67  */
   131  *
    68 extern DECLSPEC void SDLCALL SDL_WarpMouse(Uint16 x, Uint16 y);
   132  * \brief Moves the currently selected mouse to the given position within the window.
    69 
   133  *
    70 /*
   134  * \param windowID The window to move the mouse into, or 0 for the current mouse focus
    71  * Create a cursor using the specified data and mask (in MSB format).
   135  * \param x The x coordinate within the window
       
   136  * \param y The y coordinate within the window
       
   137  *
       
   138  * \note This function generates a mouse motion event
       
   139  */
       
   140 extern DECLSPEC void SDLCALL SDL_WarpMouseInWindow(SDL_WindowID windowID,
       
   141                                                    int x, int y);
       
   142 
       
   143 /**
       
   144  * \fn SDL_Cursor *SDL_CreateCursor (const Uint8 * data, const Uint8 * mask, int w, int h, int hot_x, int hot_y)
       
   145  *
       
   146  * \brief Create a cursor for the currently selected mouse, using the
       
   147  *        specified bitmap data and mask (in MSB format).
       
   148  *
    72  * The cursor width must be a multiple of 8 bits.
   149  * The cursor width must be a multiple of 8 bits.
    73  *
   150  *
    74  * The cursor is created in black and white according to the following:
   151  * The cursor is created in black and white according to the following:
    75  * data  mask    resulting pixel on screen
   152  * data  mask    resulting pixel on screen
    76  *  0     1       White
   153  *  0     1       White
    77  *  1     1       Black
   154  *  1     1       Black
    78  *  0     0       Transparent
   155  *  0     0       Transparent
    79  *  1     0       Inverted color if possible, black if not.
   156  *  1     0       Inverted color if possible, black if not.
    80  *
   157  *
    81  * Cursors created with this function must be freed with SDL_FreeCursor().
   158  * \sa SDL_FreeCursor()
    82  */
   159  */
    83 extern DECLSPEC SDL_Cursor * SDLCALL SDL_CreateCursor
   160 extern DECLSPEC SDL_Cursor *SDLCALL SDL_CreateCursor(const Uint8 * data,
    84 		(Uint8 *data, Uint8 *mask, int w, int h, int hot_x, int hot_y);
   161                                                      const Uint8 * mask,
    85 
   162                                                      int w, int h, int hot_x,
    86 /*
   163                                                      int hot_y);
    87  * Set the currently active cursor to the specified one.
   164 
    88  * If the cursor is currently visible, the change will be immediately 
   165 /**
    89  * represented on the display.
   166  * \fn void SDL_SetCursor(SDL_Cursor * cursor)
    90  */
   167  *
    91 extern DECLSPEC void SDLCALL SDL_SetCursor(SDL_Cursor *cursor);
   168  * \brief Set the active cursor for the currently selected mouse.
    92 
   169  *
    93 /*
   170  * \note The cursor must have been created for the selected mouse.
    94  * Returns the currently active cursor.
   171  */
    95  */
   172 extern DECLSPEC void SDLCALL SDL_SetCursor(SDL_Cursor * cursor);
    96 extern DECLSPEC SDL_Cursor * SDLCALL SDL_GetCursor(void);
   173 
    97 
   174 /**
    98 /*
   175  * \fn SDL_Cursor *SDL_GetCursor(void)
    99  * Deallocates a cursor created with SDL_CreateCursor().
   176  *
   100  */
   177  * \brief Return the active cursor for the currently selected mouse.
   101 extern DECLSPEC void SDLCALL SDL_FreeCursor(SDL_Cursor *cursor);
   178  */
   102 
   179 extern DECLSPEC SDL_Cursor *SDLCALL SDL_GetCursor(void);
   103 /*
   180 
   104  * Toggle whether or not the cursor is shown on the screen.
   181 /**
   105  * The cursor start off displayed, but can be turned off.
   182  * \fn void SDL_FreeCursor(SDL_Cursor * cursor)
   106  * SDL_ShowCursor() returns 1 if the cursor was being displayed
   183  *
   107  * before the call, or 0 if it was not.  You can query the current
   184  * \brief Frees a cursor created with SDL_CreateCursor().
   108  * state by passing a 'toggle' value of -1.
   185  *
       
   186  * \sa SDL_CreateCursor()
       
   187  */
       
   188 extern DECLSPEC void SDLCALL SDL_FreeCursor(SDL_Cursor * cursor);
       
   189 
       
   190 /**
       
   191  * \fn int SDL_ShowCursor(int toggle)
       
   192  *
       
   193  * \brief Toggle whether or not the cursor is shown for the currently selected mouse.
       
   194  *
       
   195  * \param toggle 1 to show the cursor, 0 to hide it, -1 to query the current state.
       
   196  *
       
   197  * \return 1 if the cursor is shown, or 0 if the cursor is hidden.
   109  */
   198  */
   110 extern DECLSPEC int SDLCALL SDL_ShowCursor(int toggle);
   199 extern DECLSPEC int SDLCALL SDL_ShowCursor(int toggle);
   111 
   200 
   112 /* Used as a mask when testing buttons in buttonstate
   201 /* Used as a mask when testing buttons in buttonstate
   113    Button 1:	Left mouse button
   202    Button 1:	Left mouse button
   114    Button 2:	Middle mouse button
   203    Button 2:	Middle mouse button
   115    Button 3:	Right mouse button
   204    Button 3:	Right mouse button
   116    Button 4:	Mouse wheel up	 (may also be a real button)
       
   117    Button 5:	Mouse wheel down (may also be a real button)
       
   118  */
   205  */
   119 #define SDL_BUTTON(X)		(1 << ((X)-1))
   206 #define SDL_BUTTON(X)		(1 << ((X)-1))
   120 #define SDL_BUTTON_LEFT		1
   207 #define SDL_BUTTON_LEFT		1
   121 #define SDL_BUTTON_MIDDLE	2
   208 #define SDL_BUTTON_MIDDLE	2
   122 #define SDL_BUTTON_RIGHT	3
   209 #define SDL_BUTTON_RIGHT	3
   123 #define SDL_BUTTON_WHEELUP	4
       
   124 #define SDL_BUTTON_WHEELDOWN	5
       
   125 #define SDL_BUTTON_LMASK	SDL_BUTTON(SDL_BUTTON_LEFT)
   210 #define SDL_BUTTON_LMASK	SDL_BUTTON(SDL_BUTTON_LEFT)
   126 #define SDL_BUTTON_MMASK	SDL_BUTTON(SDL_BUTTON_MIDDLE)
   211 #define SDL_BUTTON_MMASK	SDL_BUTTON(SDL_BUTTON_MIDDLE)
   127 #define SDL_BUTTON_RMASK	SDL_BUTTON(SDL_BUTTON_RIGHT)
   212 #define SDL_BUTTON_RMASK	SDL_BUTTON(SDL_BUTTON_RIGHT)
   128 
   213 
   129 
   214 
   130 /* Ends C function definitions when using C++ */
   215 /* Ends C function definitions when using C++ */
   131 #ifdef __cplusplus
   216 #ifdef __cplusplus
       
   217 /* *INDENT-OFF* */
   132 }
   218 }
       
   219 /* *INDENT-ON* */
   133 #endif
   220 #endif
   134 #include "close_code.h"
   221 #include "close_code.h"
   135 
   222 
   136 #endif /* _SDL_mouse_h */
   223 #endif /* _SDL_mouse_h */
       
   224 
       
   225 /* vi: set ts=4 sw=4 expandtab: */