version 2.8
ginput_mouse.h
Go to the documentation of this file.
1 /*
2  * This file is subject to the terms of the GFX License. If a copy of
3  * the license was not distributed with this file, you can obtain one at:
4  *
5  * http://ugfx.org/license.html
6  */
7 
8 /**
9  * @file src/ginput/ginput_mouse.h
10  *
11  * @defgroup Mouse Mouse
12  * @ingroup GINPUT
13  *
14  * @brief Sub-Module to handle touchscreens and mices.
15  *
16  * @details Both resistive and capacitive touchscreens are supported.
17  *
18  * @pre GFX_USE_GINPUT must be set to TRUE in your gfxconf.h
19  * @pre GINPUT_NEED_MOUSE must be set to TRUE in your gfxconf.h
20  *
21  * @{
22  */
23 
24 #ifndef _GINPUT_MOUSE_H
25 #define _GINPUT_MOUSE_H
26 
27 #if GINPUT_NEED_MOUSE || defined(__DOXYGEN__)
28 
29 /*===========================================================================*/
30 /* Type definitions */
31 /*===========================================================================*/
32 
33 /* This type definition is also used by touch */
34 typedef struct GEventMouse_t {
35  GEventType type; // The type of this event (GEVENT_MOUSE or GEVENT_TOUCH)
36  coord_t x, y, z; // The position of the mouse.
37  // - For touch devices, Z is the current pressure if supported (values are device specific)
38  // - For mice, Z is the 3rd dimension if supported (values are device specific)
39  uint16_t buttons; // A bit is set if the button is down or a meta event has occurred.
40  #define GINPUT_MOUSE_BTN_MASK 0x000F // The "button is down" mask
41  #define GINPUT_MOUSE_BTN_LEFT 0x0001 // The left mouse button is currently down
42  #define GINPUT_MOUSE_BTN_RIGHT 0x0002 // The right mouse button is currently down
43  #define GINPUT_MOUSE_BTN_MIDDLE 0x0004 // The middle mouse button is currently down
44  #define GINPUT_MOUSE_BTN_4 0x0008 // The 4th mouse button is currently down
45  #define GINPUT_TOUCH_PRESSED 0x0001 // The touch surface is currently touched
46 
47  #define GMETA_MASK 0x00F0 // The "button transition" mask
48  #define GMETA_NONE 0x0000 // No "button transition" events
49  #define GMETA_MOUSE_DOWN 0x0010 // Left mouse/touch has just gone down
50  #define GMETA_MOUSE_UP 0x0020 // Left mouse/touch has just gone up
51  #define GMETA_MOUSE_CLICK 0x0040 // Left mouse/touch has just gone through a click (short down - up cycle)
52  #define GMETA_MOUSE_CXTCLICK 0x0080 // Right mouse has just been depressed or touch has gone through a long click
53 
54  #define GINPUT_MISSED_MOUSE_EVENT 0x8000 // Oops - a mouse event has previously been missed
55 
56  GDisplay * display; // The display this mouse is currently associated with.
57 } GEventMouse;
58 
59 // Mouse/Touch Listen Flags - passed to geventAddSourceToListener()
60 #define GLISTEN_MOUSEMETA 0x0001 // Create events for meta events such as CLICK and CXTCLICK
61 #define GLISTEN_MOUSEDOWNMOVES 0x0002 // Creates mouse move events when the primary mouse button is down (touch is on the surface)
62 #define GLISTEN_MOUSEUPMOVES 0x0004 // Creates mouse move events when the primary mouse button is up (touch is off the surface - if the hardware allows).
63 #define GLISTEN_MOUSENOFILTER 0x0008 // Don't filter out mouse moves where the position hasn't changed.
64 #define GLISTEN_TOUCHMETA GLISTEN_MOUSEMETA
65 #define GLISTEN_TOUCHDOWNMOVES GLISTEN_MOUSEDOWNMOVES
66 #define GLISTEN_TOUCHUPMOVES GLISTEN_MOUSEUPMOVES
67 #define GLISTEN_TOUCHNOFILTER GLISTEN_MOUSENOFILTER
68 
69 // Event types for the mouse ginput source
70 #define GEVENT_MOUSE (GEVENT_GINPUT_FIRST+0)
71 #define GEVENT_TOUCH (GEVENT_GINPUT_FIRST+1)
72 
73 // All mice
74 #define GMOUSE_ALL_INSTANCES ((unsigned)-1)
75 
76 /*===========================================================================*/
77 /* External declarations. */
78 /*===========================================================================*/
79 
80 #ifdef __cplusplus
81 extern "C" {
82 #endif
83 
84  /**
85  * @brief Get the Source handler for a mouse using the instance number
86  *
87  * @param[in] instance The mouse instance number
88  *
89  * @return The source handle of the mouse or NULL
90  * @note You can use the special value of GMOUSE_ALL_INSTANCES to
91  * get a source handle that returns events for all mice rather
92  * than a specific mouse. Using GMOUSE_ALL_INSTANCES will always
93  * return a valid spurce handle even if there are currently no mice
94  * in the system.
95  */
96  GSourceHandle ginputGetMouse(unsigned instance);
97 
98  /**
99  * @brief Should this device be in Pen mode or Finger mode
100  * @note A touch device (and even theoritically a mouse) can operate
101  * in either pen or finger mode. In finger mode typically a
102  * touch device will be far more tolerant of movement and other
103  * inaccuracies. Each driver specifies its own tolerances for
104  * pen versus finger mode.
105  *
106  * @param[in] instance The ID of the mouse input instance
107  * @param[in] on If true then finger mode is turned on.
108  */
109  void ginputSetFingerMode(unsigned instance, bool_t on);
110 
111  /**
112  * @brief Assign the display associated with the mouse
113  * @note This only needs to be called if the mouse is associated with a display
114  * other than the current default display. It must be called before
115  * @p ginputGetMouse() if the new display is to be used during the calibration
116  * process. Other than calibration the display is used for range checking,
117  * and may also be used to display a mouse pointer.
118  *
119  * @param[in] instance The ID of the mouse input instance
120  * @param[in] g The GDisplay to which this mouse belongs
121  */
122  void ginputSetMouseDisplay(unsigned instance, GDisplay *g);
123 
124  /**
125  * @brief Get the display currently associated with the mouse
126  * @return A pointer to the display
127  *
128  * @param[in] instance The ID of the mouse input instance
129  */
130  GDisplay *ginputGetMouseDisplay(unsigned instance);
131 
132  /**
133  * @brief Get the current mouse position and button status
134  * @note Unlinke a listener event, this status cannot record meta events such as
135  * "CLICK".
136  *
137  * @param[in] instance The ID of the mouse input instance
138  * @param[in] pmouse The mouse event
139  *
140  * @return FALSE on an error (eg. invalid instance)
141  */
142  bool_t ginputGetMouseStatus(unsigned instance, GEventMouse *pmouse);
143 
144  /**
145  * @brief Performs a calibration
146  *
147  * @param[in] instance The ID of the mouse input instance
148  *
149  * @return The calibration error squared if calibration fails, or 0 on success or if the driver dosen't need calibration.
150  * @note An invalid instance will also return 0.
151  */
152  uint32_t ginputCalibrateMouse(unsigned instance);
153 
154  /**
155  * @brief Load a set of mouse calibration data
156  * @return A pointer to the data or NULL on failure
157  *
158  * @param[in] instance The mouse input instance number
159  * @param[in] data Where the data should be placed
160  * @param[in] sz The size in bytes of the data to retrieve.
161  *
162  * @note This routine is provided by the user application. It is only
163  * called if GINPUT_TOUCH_USER_CALIBRATION_LOAD has been set to TRUE in the
164  * users gfxconf.h file.
165  */
166  bool_t LoadMouseCalibration(unsigned instance, void *data, size_t sz);
167 
168  /**
169  * @brief Save a set of mouse calibration data
170  * @return TRUE if the save operation was successful.
171  *
172  * @param[in] instance The mouse input instance number
173  * @param[in] data The data to save
174  * @param[in] sz The size in bytes of the data to retrieve.
175  *
176  * @note This routine is provided by the user application. It is only
177  * called if GINPUT_TOUCH_USER_CALIBRATION_SAVE has been set to TRUE in the
178  * users gfxconf.h file.
179  */
180  bool_t SaveMouseCalibration(unsigned instance, const void *data, size_t sz);
181 
182 #ifdef __cplusplus
183 }
184 #endif
185 
186 #endif /* GINPUT_NEED_MOUSE */
187 
188 #endif /* _GINPUT_MOUSE_H */
189 /** @} */
190 
uint32_t ginputCalibrateMouse(unsigned instance)
Performs a calibration.
int16_t coord_t
The type for a coordinate or length on the screen.
Definition: gdisp.h:39
bool_t ginputGetMouseStatus(unsigned instance, GEventMouse *pmouse)
Get the current mouse position and button status.
void ginputSetFingerMode(unsigned instance, bool_t on)
Should this device be in Pen mode or Finger mode.
GSourceHandle ginputGetMouse(unsigned instance)
Get the Source handler for a mouse using the instance number.
bool_t SaveMouseCalibration(unsigned instance, const void *data, size_t sz)
Save a set of mouse calibration data.
void ginputSetMouseDisplay(unsigned instance, GDisplay *g)
Assign the display associated with the mouse.
GDisplay * ginputGetMouseDisplay(unsigned instance)
Get the display currently associated with the mouse.
bool_t LoadMouseCalibration(unsigned instance, void *data, size_t sz)
Load a set of mouse calibration data.