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