Blame - doc/html/man/curs_mouse.3x.html - android_external_libncurses

Amit Daniel Kachhap

e6a01f5

2011-07-20 11:45:59 +0530

[diff] [blame]

1

<!--

2

* t

3

****************************************************************************

Steve Kondik

ae271bc

2015-11-15 02:50:53 +0100

[diff] [blame]

4

Amit Daniel Kachhap

e6a01f5

2011-07-20 11:45:59 +0530

[diff] [blame]

5

* *

6

* Permission is hereby granted, free of charge, to any person obtaining a *

7

* copy of this software and associated documentation files (the *

8

* "Software"), to deal in the Software without restriction, including *

9

* without limitation the rights to use, copy, modify, merge, publish, *

10

* distribute, distribute with modifications, sublicense, and/or sell *

11

* copies of the Software, and to permit persons to whom the Software is *

12

* furnished to do so, subject to the following conditions: *

13

* *

14

* The above copyright notice and this permission notice shall be included *

15

* in all copies or substantial portions of the Software. *

16

* *

17

* THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS *

18

* OR IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF *

19

* MERCHANTABILITY, FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. *

20

* IN NO EVENT SHALL THE ABOVE COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, *

21

* DAMAGES OR OTHER LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR *

22

* OTHERWISE, ARISING FROM, OUT OF OR IN CONNECTION WITH THE SOFTWARE OR *

23

* THE USE OR OTHER DEALINGS IN THE SOFTWARE. *

24

* *

25

* Except as contained in this notice, the name(s) of the above copyright *

26

* holders shall not be used in advertising or otherwise to promote the *

27

* sale, use or other dealings in this Software without prior written *

28

* authorization. *

29

****************************************************************************

Steve Kondik

ae271bc

2015-11-15 02:50:53 +0100

[diff] [blame]

30

* @Id: curs_mouse.3x,v 1.42 2015/07/21 09:27:39 tom Exp @

Amit Daniel Kachhap

e6a01f5

2011-07-20 11:45:59 +0530

[diff] [blame]

31

-->

Steve Kondik

ae271bc

2015-11-15 02:50:53 +0100

[diff] [blame]

32

<!DOCTYPE html PUBLIC "-//W3C//DTD HTML 4.01//EN">

Amit Daniel Kachhap

e6a01f5

2011-07-20 11:45:59 +0530

[diff] [blame]

33

<HTML>

34

<HEAD>

Steve Kondik

ae271bc

2015-11-15 02:50:53 +0100

[diff] [blame]

35

36

Amit Daniel Kachhap

e6a01f5

2011-07-20 11:45:59 +0530

[diff] [blame]

37

<TITLE>curs_mouse 3x</TITLE>

</HEAD>

<BODY>

Steve Kondik

ae271bc

2015-11-15 02:50:53 +0100

[diff] [blame]

42

<H1 class="no-header">curs_mouse 3x</H1>

Amit Daniel Kachhap

e6a01f5

2011-07-20 11:45:59 +0530

[diff] [blame]

43

<PRE>

Amit Daniel Kachhap

e6a01f5

2011-07-20 11:45:59 +0530

[diff] [blame]

44

<A HREF="curs_mouse.3x.html">curs_mouse(3x)</A> <A HREF="curs_mouse.3x.html">curs_mouse(3x)</A>

</PRE>

Steve Kondik

ae271bc

2015-11-15 02:50:53 +0100

[diff] [blame]

50

51

has_mouse, getmouse, ungetmouse, mousemask, wenclose,

52

mouse_trafo, wmouse_trafo, mouseinterval - mouse interface

53

through curses

Amit Daniel Kachhap

e6a01f5

2011-07-20 11:45:59 +0530

[diff] [blame]

54

55

56

</PRE>

Steve Kondik

ae271bc

2015-11-15 02:50:53 +0100

[diff] [blame]

57

<H2><a name="h2-SYNOPSIS">SYNOPSIS</a></H2><PRE>

Amit Daniel Kachhap

e6a01f5

2011-07-20 11:45:59 +0530

[diff] [blame]

58

#include <curses.h>

59

60

typedef unsigned long mmask_t;

61

Steve Kondik

ae271bc

2015-11-15 02:50:53 +0100

[diff] [blame]

62

typedef struct {

63

short id; /* ID to distinguish multiple devices */

Amit Daniel Kachhap

e6a01f5

2011-07-20 11:45:59 +0530

[diff] [blame]

64

int x, y, z; /* event coordinates */

65

mmask_t bstate; /* button state bits */

Steve Kondik

ae271bc

2015-11-15 02:50:53 +0100

[diff] [blame]

66

} MEVENT;

67

68

bool has_mouse(void);

69

int getmouse(MEVENT *event);

70

int ungetmouse(MEVENT *event);

71

mmask_t mousemask(mmask_t newmask, mmask_t *oldmask);

72

bool wenclose(const WINDOW *win, int y, int x);

73

bool mouse_trafo(int* pY, int* pX, bool to_screen);

74

bool wmouse_trafo(const WINDOW* win, int* pY, int* pX,

75

bool to_screen);

76

int mouseinterval(int erval);

Amit Daniel Kachhap

e6a01f5

2011-07-20 11:45:59 +0530

[diff] [blame]

77

78

79

</PRE>

Steve Kondik

ae271bc

2015-11-15 02:50:53 +0100

[diff] [blame]

80

<H2><a name="h2-DESCRIPTION">DESCRIPTION</a></H2><PRE>

Amit Daniel Kachhap

e6a01f5

2011-07-20 11:45:59 +0530

[diff] [blame]

81

These functions provide an interface to mouse events from

82

<A HREF="ncurses.3x.html">ncurses(3x)</A>. Mouse events are represented by KEY_MOUSE

83

pseudo-key values in the wgetch input stream.

84

Steve Kondik

ae271bc

2015-11-15 02:50:53 +0100

[diff] [blame]

85

86

</PRE>

87

<H3><a name="h3-mousemask">mousemask</a></H3><PRE>

Amit Daniel Kachhap

e6a01f5

2011-07-20 11:45:59 +0530

[diff] [blame]

88

To make mouse events visible, use the mousemask function.

89

This will set the mouse events to be reported. By de-

90

fault, no mouse events are reported. The function will

91

return a mask to indicate which of the specified mouse

92

events can be reported; on complete failure it returns 0.

93

If oldmask is non-NULL, this function fills the indicated

94

location with the previous value of the given window's

95

mouse event mask.

96

97

As a side effect, setting a zero mousemask may turn off

98

the mouse pointer; setting a nonzero mask may turn it on.

99

Whether this happens is device-dependent.

100

Amit Daniel Kachhap

e6a01f5

2011-07-20 11:45:59 +0530

[diff] [blame]

101

Steve Kondik

ae271bc

2015-11-15 02:50:53 +0100

[diff] [blame]

102

</PRE>

103

<H3><a name="h3-Mouse-events">Mouse events</a></H3><PRE>

104

Here are the mouse event type masks which may be defined:

Amit Daniel Kachhap

e6a01f5

2011-07-20 11:45:59 +0530

[diff] [blame]

105

106

Name Description

107

---------------------------------------------------------------------

108

BUTTON1_PRESSED mouse button 1 down

109

BUTTON1_RELEASED mouse button 1 up

110

BUTTON1_CLICKED mouse button 1 clicked

111

BUTTON1_DOUBLE_CLICKED mouse button 1 double clicked

112

BUTTON1_TRIPLE_CLICKED mouse button 1 triple clicked

113

---------------------------------------------------------------------

114

BUTTON2_PRESSED mouse button 2 down

115

BUTTON2_RELEASED mouse button 2 up

116

BUTTON2_CLICKED mouse button 2 clicked

117

BUTTON2_DOUBLE_CLICKED mouse button 2 double clicked

Steve Kondik

ae271bc

2015-11-15 02:50:53 +0100

[diff] [blame]

118

119

Amit Daniel Kachhap

e6a01f5

2011-07-20 11:45:59 +0530

[diff] [blame]

120

BUTTON2_TRIPLE_CLICKED mouse button 2 triple clicked

121

---------------------------------------------------------------------

Amit Daniel Kachhap

e6a01f5

2011-07-20 11:45:59 +0530

[diff] [blame]

122

BUTTON3_PRESSED mouse button 3 down

123

BUTTON3_RELEASED mouse button 3 up

124

BUTTON3_CLICKED mouse button 3 clicked

125

BUTTON3_DOUBLE_CLICKED mouse button 3 double clicked

126

BUTTON3_TRIPLE_CLICKED mouse button 3 triple clicked

127

---------------------------------------------------------------------

128

BUTTON4_PRESSED mouse button 4 down

129

BUTTON4_RELEASED mouse button 4 up

130

BUTTON4_CLICKED mouse button 4 clicked

131

BUTTON4_DOUBLE_CLICKED mouse button 4 double clicked

132

BUTTON4_TRIPLE_CLICKED mouse button 4 triple clicked

133

---------------------------------------------------------------------

134

BUTTON5_PRESSED mouse button 5 down

135

BUTTON5_RELEASED mouse button 5 up

136

BUTTON5_CLICKED mouse button 5 clicked

137

BUTTON5_DOUBLE_CLICKED mouse button 5 double clicked

138

BUTTON5_TRIPLE_CLICKED mouse button 5 triple clicked

139

---------------------------------------------------------------------

140

BUTTON_SHIFT shift was down during button state change

141

BUTTON_CTRL control was down during button state change

142

BUTTON_ALT alt was down during button state change

143

ALL_MOUSE_EVENTS report all button state changes

144

REPORT_MOUSE_POSITION report mouse movement

145

---------------------------------------------------------------------

146

Steve Kondik

ae271bc

2015-11-15 02:50:53 +0100

[diff] [blame]

147

148

</PRE>

149

<H3><a name="h3-getmouse">getmouse</a></H3><PRE>

150

Once a class of mouse events has been made visible in a

Amit Daniel Kachhap

e6a01f5

2011-07-20 11:45:59 +0530

[diff] [blame]

151

window, calling the wgetch function on that window may re-

152

turn KEY_MOUSE as an indicator that a mouse event has been

153

queued. To read the event data and pop the event off the

154

queue, call getmouse. This function will return OK if a

155

mouse event is actually visible in the given window, ERR

156

otherwise. When getmouse returns OK, the data deposited

157

as y and x in the event structure coordinates will be

158

screen-relative character-cell coordinates. The returned

159

state mask will have exactly one bit set to indicate the

Steve Kondik

ae271bc

2015-11-15 02:50:53 +0100

[diff] [blame]

160

event type. The corresponding data in the queue is marked

161

invalid. A subsequent call to getmouse will retrieve the

162

next older item from the queue.

Amit Daniel Kachhap

e6a01f5

2011-07-20 11:45:59 +0530

[diff] [blame]

163

Steve Kondik

ae271bc

2015-11-15 02:50:53 +0100

[diff] [blame]

164

165

</PRE>

166

<H3><a name="h3-ungetmouse">ungetmouse</a></H3><PRE>

Amit Daniel Kachhap

e6a01f5

2011-07-20 11:45:59 +0530

[diff] [blame]

167

The ungetmouse function behaves analogously to ungetch.

168

It pushes a KEY_MOUSE event onto the input queue, and as-

169

sociates with that event the given state data and screen-

170

relative character-cell coordinates.

171

Steve Kondik

ae271bc

2015-11-15 02:50:53 +0100

[diff] [blame]

172

173

</PRE>

174

<H3><a name="h3-wenclose">wenclose</a></H3><PRE>

Amit Daniel Kachhap

e6a01f5

2011-07-20 11:45:59 +0530

[diff] [blame]

175

The wenclose function tests whether a given pair of

176

screen-relative character-cell coordinates is enclosed by

Steve Kondik

ae271bc

2015-11-15 02:50:53 +0100

[diff] [blame]

177

a given window, returning TRUE if it is and FALSE other-

Amit Daniel Kachhap

e6a01f5

2011-07-20 11:45:59 +0530

[diff] [blame]

178

wise. It is useful for determining what subset of the

179

screen windows enclose the location of a mouse event.

180

Steve Kondik

ae271bc

2015-11-15 02:50:53 +0100

[diff] [blame]

181

182

</PRE>

183

<H3><a name="h3-wmouse_trafo">wmouse_trafo</a></H3><PRE>

Amit Daniel Kachhap

e6a01f5

2011-07-20 11:45:59 +0530

[diff] [blame]

184

The wmouse_trafo function transforms a given pair of coor-

185

dinates from stdscr-relative coordinates to coordinates

Steve Kondik

ae271bc

2015-11-15 02:50:53 +0100

[diff] [blame]

186

relative to the given window or vice versa. The resulting

187

stdscr-relative coordinates are not always identical to

188

window-relative coordinates due to the mechanism to re-

189

serve lines on top or bottom of the screen for other pur-

190

poses (see the ripoffline and slk_init calls, for exam-

191

ple).

Amit Daniel Kachhap

e6a01f5

2011-07-20 11:45:59 +0530

[diff] [blame]

192

Steve Kondik

ae271bc

2015-11-15 02:50:53 +0100

[diff] [blame]

193

o If the parameter to_screen is TRUE, the pointers pY,

194

pX must reference the coordinates of a location inside

195

the window win. They are converted to window-relative

196

coordinates and returned through the pointers. If the

197

conversion was successful, the function returns TRUE.

198

199

o If one of the parameters was NULL or the location is

200

not inside the window, FALSE is returned.

201

202

o If to_screen is FALSE, the pointers pY, pX must refer-

203

ence window-relative coordinates. They are converted

204

to stdscr-relative coordinates if the window win en-

205

closes this point. In this case the function returns

206

TRUE.

207

208

o If one of the parameters is NULL or the point is not

209

inside the window, FALSE is returned. The referenced

210

coordinates are only replaced by the converted coordi-

211

nates if the transformation was successful.

</PRE>

<H3><a name="h3-mouse_trafo">mouse_trafo</a></H3><PRE>

Amit Daniel Kachhap

e6a01f5

2011-07-20 11:45:59 +0530

[diff] [blame]

216

The mouse_trafo function performs the same translation as

217

wmouse_trafo, using stdscr for win.

218

Steve Kondik

ae271bc

2015-11-15 02:50:53 +0100

[diff] [blame]

219

220

</PRE>

221

<H3><a name="h3-mouseinterval">mouseinterval</a></H3><PRE>

Amit Daniel Kachhap

e6a01f5

2011-07-20 11:45:59 +0530

[diff] [blame]

222

The mouseinterval function sets the maximum time (in thou-

223

sands of a second) that can elapse between press and re-

224

lease events for them to be recognized as a click. Use

225

mouseinterval(0) to disable click resolution. This func-

226

tion returns the previous interval value. Use mouseinter-

227

val(-1) to obtain the interval without altering it. The

228

default is one sixth of a second.

229

Steve Kondik

ae271bc

2015-11-15 02:50:53 +0100

[diff] [blame]

230

231

</PRE>

232

<H3><a name="h3-has_mouse">has_mouse</a></H3><PRE>

233

The has_mouse function returns TRUE if the mouse driver

234

has been successfully initialized.

235

236

Note that mouse events will be ignored when input is in

Amit Daniel Kachhap

e6a01f5

2011-07-20 11:45:59 +0530

[diff] [blame]

237

cooked mode, and will cause an error beep when cooked mode

Steve Kondik

ae271bc

2015-11-15 02:50:53 +0100

[diff] [blame]

238

is being simulated in a window by a function such as get-

Amit Daniel Kachhap

e6a01f5

2011-07-20 11:45:59 +0530

[diff] [blame]

239

str that expects a linefeed for input-loop termination.

240

241

242

</PRE>

Steve Kondik

ae271bc

2015-11-15 02:50:53 +0100

[diff] [blame]

243

<H2><a name="h2-RETURN-VALUE">RETURN VALUE</a></H2><PRE>

244

getmouse and ungetmouse return the integer ERR upon fail-

245

ure or OK upon successful completion:

Amit Daniel Kachhap

e6a01f5

2011-07-20 11:45:59 +0530

[diff] [blame]

246

Steve Kondik

ae271bc

2015-11-15 02:50:53 +0100

[diff] [blame]

247

getmouse

248

returns an error.

Amit Daniel Kachhap

e6a01f5

2011-07-20 11:45:59 +0530

[diff] [blame]

249

Steve Kondik

ae271bc

2015-11-15 02:50:53 +0100

[diff] [blame]

250

o If no mouse driver was initialized, or if the mask

251

parameter is zero,

252

253

o It also returns an error if no more events remain

in the queue.

ungetmouse

returns an error if the FIFO is full.

Amit Daniel Kachhap

e6a01f5

2011-07-20 11:45:59 +0530

[diff] [blame]

258

259

mousemask returns the mask of reportable events.

260

261

mouseinterval returns the previous interval value, unless

262

the terminal was not initialized. In that case, it re-

263

turns the maximum interval value (166).

264

265

wenclose and wmouse_trafo are boolean functions returning

266

TRUE or FALSE depending on their test result.

267

268

269

</PRE>

Steve Kondik

ae271bc

2015-11-15 02:50:53 +0100

[diff] [blame]

270

<H2><a name="h2-PORTABILITY">PORTABILITY</a></H2><PRE>

Amit Daniel Kachhap

e6a01f5

2011-07-20 11:45:59 +0530

[diff] [blame]

271

These calls were designed for <A HREF="ncurses.3x.html">ncurses(3x)</A>, and are not

272

found in SVr4 curses, 4.4BSD curses, or any other previous

273

version of curses.

274

275

The feature macro NCURSES_MOUSE_VERSION is provided so the

276

preprocessor can be used to test whether these features

277

are present. If the interface is changed, the value of

278

NCURSES_MOUSE_VERSION will be incremented. These values

279

for NCURSES_MOUSE_VERSION may be specified when configur-

280

ing ncurses:

281

Steve Kondik

ae271bc

2015-11-15 02:50:53 +0100

[diff] [blame]

282

1 has definitions for reserved events. The mask uses

283

28 bits.

Amit Daniel Kachhap

e6a01f5

2011-07-20 11:45:59 +0530

[diff] [blame]

284

Steve Kondik

ae271bc

2015-11-15 02:50:53 +0100

[diff] [blame]

285

2 adds definitions for button 5, removes the defini-

286

tions for reserved events. The mask uses 29 bits.

Amit Daniel Kachhap

e6a01f5

2011-07-20 11:45:59 +0530

[diff] [blame]

287

Steve Kondik

ae271bc

2015-11-15 02:50:53 +0100

[diff] [blame]

288

The order of the MEVENT structure members is not guaran-

289

teed. Additional fields may be added to the structure in

Amit Daniel Kachhap

e6a01f5

2011-07-20 11:45:59 +0530

[diff] [blame]

290

the future.

291

Steve Kondik

ae271bc

2015-11-15 02:50:53 +0100

[diff] [blame]

292

Under <A HREF="ncurses.3x.html">ncurses(3x)</A>, these calls are implemented using ei-

293

ther xterm's built-in mouse-tracking API or platform-spe-

Amit Daniel Kachhap

e6a01f5

2011-07-20 11:45:59 +0530

[diff] [blame]

294

cific drivers including

Steve Kondik

ae271bc

2015-11-15 02:50:53 +0100

[diff] [blame]

295

296

o Alessandro Rubini's gpm server

o FreeBSD sysmouse

o OS/2 EMX

If you are using an unsupported configuration, mouse

303

events will not be visible to <A HREF="ncurses.3x.html">ncurses(3x)</A> (and the mouse-

Amit Daniel Kachhap

e6a01f5

2011-07-20 11:45:59 +0530

[diff] [blame]

304

mask function will always return 0).

305

Steve Kondik

ae271bc

2015-11-15 02:50:53 +0100

[diff] [blame]

306

If the terminfo entry contains a XM string, this is used

307

in the xterm mouse driver to control the way the terminal

Amit Daniel Kachhap

e6a01f5

2011-07-20 11:45:59 +0530

[diff] [blame]

308

is initialized for mouse operation. The default, if XM is

309

not found, corresponds to private mode 1000 of xterm:

Steve Kondik

ae271bc

2015-11-15 02:50:53 +0100

[diff] [blame]

310

311

\E[?1000%?%p1%{1}%=%th%el%;

312

313

The z member in the event structure is not presently used.

314

It is intended for use with touch screens (which may be

Amit Daniel Kachhap

e6a01f5

2011-07-20 11:45:59 +0530

[diff] [blame]

315

pressure-sensitive) or with 3D-mice/trackballs/power

316

gloves.

317

Steve Kondik

ae271bc

2015-11-15 02:50:53 +0100

[diff] [blame]

318

The ALL_MOUSE_EVENTS class does not include RE-

319

PORT_MOUSE_POSITION. They are distinct. For example, in

320

xterm, wheel/scrolling mice send position reports as a se-

321

quence of presses of buttons 4 or 5 without matching but-

322

ton-releases.

323

Amit Daniel Kachhap

e6a01f5

2011-07-20 11:45:59 +0530

[diff] [blame]

324

325

</PRE>

Steve Kondik

ae271bc

2015-11-15 02:50:53 +0100

[diff] [blame]

326

327

Mouse events under xterm will not in fact be ignored dur-

328

ing cooked mode, if they have been enabled by mousemask.

329

Instead, the xterm mouse report sequence will appear in

Amit Daniel Kachhap

e6a01f5

2011-07-20 11:45:59 +0530

[diff] [blame]

330

the string read.

331

332

Mouse events under xterm will not be detected correctly in

Steve Kondik

ae271bc

2015-11-15 02:50:53 +0100

[diff] [blame]

333

a window with its keypad bit off, since they are inter-

334

preted as a variety of function key. Your terminfo de-

335

scription should have kmous set to "\E[M" (the beginning

336

of the response from xterm for mouse clicks). Other val-

337

ues for kmous are permitted, but under the same assump-

Amit Daniel Kachhap

e6a01f5

2011-07-20 11:45:59 +0530

[diff] [blame]

338

tion, i.e., it is the beginning of the response.

339

Steve Kondik

ae271bc

2015-11-15 02:50:53 +0100

[diff] [blame]

340

Because there are no standard terminal responses that

341

would serve to identify terminals which support the xterm

342

mouse protocol, ncurses assumes that if your $TERM envi-

343

ronment variable contains "xterm", or kmous is defined in

Amit Daniel Kachhap

e6a01f5

2011-07-20 11:45:59 +0530

[diff] [blame]

344

the terminal description, then the terminal may send mouse

events.

</PRE>

Steve Kondik

ae271bc

2015-11-15 02:50:53 +0100

[diff] [blame]

349

350

<A HREF="ncurses.3x.html">curses(3x)</A>, <A HREF="curs_kernel.3x.html">curs_kernel(3x)</A>, <A HREF="curs_slk.3x.html">curs_slk(3x)</A>, curs_vari-

351

<A HREF="curs_variables.3x.html">ables(3x)</A>.

Amit Daniel Kachhap

e6a01f5

2011-07-20 11:45:59 +0530

[diff] [blame]

<A HREF="curs_mouse.3x.html">curs_mouse(3x)</A>

356

</PRE>

Steve Kondik

ae271bc

2015-11-15 02:50:53 +0100

[diff] [blame]

<ul>

<li><a href="#h2-SYNOPSIS">SYNOPSIS</a></li>

361

<li><a href="#h2-DESCRIPTION">DESCRIPTION</a>

362

<ul>

363

<li><a href="#h3-mousemask">mousemask</a></li>

364

<li><a href="#h3-Mouse-events">Mouse events</a></li>

365

<li><a href="#h3-getmouse">getmouse</a></li>

366

<li><a href="#h3-ungetmouse">ungetmouse</a></li>

367

<li><a href="#h3-wenclose">wenclose</a></li>

368

<li><a href="#h3-wmouse_trafo">wmouse_trafo</a></li>

369

<li><a href="#h3-mouse_trafo">mouse_trafo</a></li>

370

<li><a href="#h3-mouseinterval">mouseinterval</a></li>

371

<li><a href="#h3-has_mouse">has_mouse</a></li>

372

</ul>

373

</li>

374

<li><a href="#h2-RETURN-VALUE">RETURN VALUE</a></li>

375

<li><a href="#h2-PORTABILITY">PORTABILITY</a></li>

</ul>

</div>

Amit Daniel Kachhap

e6a01f5

2011-07-20 11:45:59 +0530

[diff] [blame]

380

</BODY>

381

</HTML>