µGFX  2.9
version 2.9
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.io/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 GFXON in your gfxconf.h
19  * @pre GINPUT_NEED_MOUSE must be set to GFXON 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  gCoord 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  gU16 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 /**
81  * @brief Get the Source handler for a mouse using the instance number
82  *
83  * @param[in] instance The mouse instance number
84  *
85  * @return The source handle of the mouse or NULL
86  * @note You can use the special value of GMOUSE_ALL_INSTANCES to
87  * get a source handle that returns events for all mice rather
88  * than a specific mouse. Using GMOUSE_ALL_INSTANCES will always
89  * return a valid spurce handle even if there are currently no mice
90  * in the system.
91  */
92 GSourceHandle ginputGetMouse(unsigned instance);
93 
94 /**
95  * @brief Should this device be in Pen mode or Finger mode
96  * @note A touch device (and even theoritically a mouse) can operate
97  * in either pen or finger mode. In finger mode typically a
98  * touch device will be far more tolerant of movement and other
99  * inaccuracies. Each driver specifies its own tolerances for
100  * pen versus finger mode.
101  *
102  * @param[in] instance The ID of the mouse input instance
103  * @param[in] on If true then finger mode is turned on.
104  */
105 void ginputSetFingerMode(unsigned instance, gBool on);
106 
107 /**
108  * @brief Assign the display associated with the mouse
109  * @note This only needs to be called if the mouse is associated with a display
110  * other than the current default display. It must be called before
111  * @p ginputGetMouse() if the new display is to be used during the calibration
112  * process. Other than calibration the display is used for range checking,
113  * and may also be used to display a mouse pointer.
114  *
115  * @param[in] instance The ID of the mouse input instance
116  * @param[in] g The GDisplay to which this mouse belongs
117  */
118 void ginputSetMouseDisplay(unsigned instance, GDisplay *g);
119 
120 /**
121  * @brief Get the display currently associated with the mouse
122  * @return A pointer to the display
123  *
124  * @param[in] instance The ID of the mouse input instance
125  */
126 GDisplay *ginputGetMouseDisplay(unsigned instance);
127 
128 /**
129  * @brief Get the current mouse position and button status
130  * @note Unlinke a listener event, this status cannot record meta events such as
131  * "CLICK".
132  *
133  * @param[in] instance The ID of the mouse input instance
134  * @param[in] pmouse The mouse event
135  *
136  * @return gFalse on an error (eg. invalid instance)
137  */
138 gBool ginputGetMouseStatus(unsigned instance, GEventMouse *pmouse);
139 
140 /**
141  * @brief Performs a calibration
142  *
143  * @param[in] instance The ID of the mouse input instance
144  *
145  * @return The calibration error squared if calibration fails, or 0 on success or if the driver dosen't need calibration.
146  * @note An invalid instance will also return 0.
147  */
148 gU32 ginputCalibrateMouse(unsigned instance);
149 
150 /**
151  * @brief Load a set of mouse calibration data
152  * @return A pointer to the data or NULL on failure
153  *
154  * @param[in] instance The mouse input instance number
155  * @param[in] data Where the data should be placed
156  * @param[in] sz The size in bytes of the data to retrieve.
157  *
158  * @note This routine is provided by the user application. It is only
159  * called if GINPUT_TOUCH_USER_CALIBRATION_LOAD has been set to GFXON in the
160  * users gfxconf.h file.
161  */
162 gBool LoadMouseCalibration(unsigned instance, void *data, gMemSize sz);
163 
164 /**
165  * @brief Save a set of mouse calibration data
166  * @return gTrue if the save operation was successful.
167  *
168  * @param[in] instance The mouse input instance number
169  * @param[in] data The data to save
170  * @param[in] sz The size in bytes of the data to retrieve.
171  *
172  * @note This routine is provided by the user application. It is only
173  * called if GINPUT_TOUCH_USER_CALIBRATION_SAVE has been set to GFXON in the
174  * users gfxconf.h file.
175  */
176 gBool SaveMouseCalibration(unsigned instance, const void *data, gMemSize sz);
177 
178 #endif /* GINPUT_NEED_MOUSE */
179 
180 #endif /* _GINPUT_MOUSE_H */
181 /** @} */
182 
gI16 gCoord
The type for a coordinate or length on the screen.
Definition: gdisp.h:39
GDisplay * ginputGetMouseDisplay(unsigned instance)
Get the display currently associated with the mouse.
gBool ginputGetMouseStatus(unsigned instance, GEventMouse *pmouse)
Get the current mouse position and button status.
gBool SaveMouseCalibration(unsigned instance, const void *data, gMemSize sz)
Save a set of mouse calibration data.
void ginputSetMouseDisplay(unsigned instance, GDisplay *g)
Assign the display associated with the mouse.
gBool LoadMouseCalibration(unsigned instance, void *data, gMemSize sz)
Load a set of mouse calibration data.
GSourceHandle ginputGetMouse(unsigned instance)
Get the Source handler for a mouse using the instance number.
void ginputSetFingerMode(unsigned instance, gBool on)
Should this device be in Pen mode or Finger mode.
gU32 ginputCalibrateMouse(unsigned instance)
Performs a calibration.