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

<!DOCTYPE HTML PUBLIC "-//IETF//DTD HTML 2.0//EN">

2

<!--

3

* t

4

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

5

6

* *

7

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

8

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

9

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

10

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

11

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

12

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

13

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

14

* *

15

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

16

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

17

* *

18

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

19

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

20

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

21

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

22

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

23

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

24

* THE USE OR OTHER DEALINGS IN THE SOFTWARE. *

25

* *

26

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

27

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

28

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

29

* authorization. *

30

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

31

* @Id: curs_mouse.3x,v 1.30 2006/12/30 23:43:34 tom Exp @

-->

<HTML>

<HEAD>

<TITLE>curs_mouse 3x</TITLE>

</HEAD>

<BODY>

<H1>curs_mouse 3x</H1>

41

<HR>

42

<PRE>

43

44

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

</PRE>

getmouse, ungetmouse, mousemask, wenclose, mouse_trafo,

52

wmouse_trafo, mouseinterval - mouse interface through

curses

</PRE>

<H2>SYNOPSIS</H2><PRE>

58

#include <curses.h>

59

60

typedef unsigned long mmask_t;

typedef struct

{

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

65

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

66

mmask_t bstate; /* button state bits */

67

}

68

MEVENT;

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);

</PRE>

<H2>DESCRIPTION</H2><PRE>

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

85

To make mouse events visible, use the mousemask function.

86

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

87

fault, no mouse events are reported. The function will

88

return a mask to indicate which of the specified mouse

89

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

90

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

91

location with the previous value of the given window's

92

mouse event mask.

93

94

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

95

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

96

Whether this happens is device-dependent.

97

98

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

Name Description

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

103

BUTTON1_PRESSED mouse button 1 down

104

BUTTON1_RELEASED mouse button 1 up

105

BUTTON1_CLICKED mouse button 1 clicked

106

BUTTON1_DOUBLE_CLICKED mouse button 1 double clicked

107

BUTTON1_TRIPLE_CLICKED mouse button 1 triple clicked

108

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

109

BUTTON2_PRESSED mouse button 2 down

110

BUTTON2_RELEASED mouse button 2 up

111

BUTTON2_CLICKED mouse button 2 clicked

112

BUTTON2_DOUBLE_CLICKED mouse button 2 double clicked

113

BUTTON2_TRIPLE_CLICKED mouse button 2 triple clicked

114

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

115

116

BUTTON3_PRESSED mouse button 3 down

117

BUTTON3_RELEASED mouse button 3 up

118

BUTTON3_CLICKED mouse button 3 clicked

119

BUTTON3_DOUBLE_CLICKED mouse button 3 double clicked

120

BUTTON3_TRIPLE_CLICKED mouse button 3 triple clicked

121

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

122

BUTTON4_PRESSED mouse button 4 down

123

BUTTON4_RELEASED mouse button 4 up

124

BUTTON4_CLICKED mouse button 4 clicked

125

BUTTON4_DOUBLE_CLICKED mouse button 4 double clicked

126

BUTTON4_TRIPLE_CLICKED mouse button 4 triple clicked

127

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

128

BUTTON5_PRESSED mouse button 5 down

129

BUTTON5_RELEASED mouse button 5 up

130

BUTTON5_CLICKED mouse button 5 clicked

131

BUTTON5_DOUBLE_CLICKED mouse button 5 double clicked

132

BUTTON5_TRIPLE_CLICKED mouse button 5 triple clicked

133

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

134

BUTTON_SHIFT shift was down during button state change

135

BUTTON_CTRL control was down during button state change

136

BUTTON_ALT alt was down during button state change

137

ALL_MOUSE_EVENTS report all button state changes

138

REPORT_MOUSE_POSITION report mouse movement

139

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

140

141

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

142

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

143

turn KEY_MOUSE as an indicator that a mouse event has been

144

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

145

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

146

mouse event is actually visible in the given window, ERR

147

otherwise. When getmouse returns OK, the data deposited

148

as y and x in the event structure coordinates will be

149

screen-relative character-cell coordinates. The returned

150

state mask will have exactly one bit set to indicate the

151

event type.

152

153

The ungetmouse function behaves analogously to ungetch.

154

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

155

sociates with that event the given state data and screen-

156

relative character-cell coordinates.

157

158

The wenclose function tests whether a given pair of

159

screen-relative character-cell coordinates is enclosed by

160

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

161

wise. It is useful for determining what subset of the

162

screen windows enclose the location of a mouse event.

163

164

The wmouse_trafo function transforms a given pair of coor-

165

dinates from stdscr-relative coordinates to coordinates

166

relative to the given window or vice versa. Please remem-

167

ber, that stdscr-relative coordinates are not always iden-

168

tical to window-relative coordinates due to the mechanism

169

to reserve lines on top or bottom of the screen for other

170

purposes (see the ripoffline() and slk_init calls, for ex-

171

ample). If the parameter to_screen is TRUE, the pointers

172

pY, pX must reference the coordinates of a location inside

173

the window win. They are converted to window-relative co-

174

ordinates and returned through the pointers. If the con-

175

version was successful, the function returns TRUE. If one

176

of the parameters was NULL or the location is not inside

177

the window, FALSE is returned. If to_screen is FALSE, the

178

pointers pY, pX must reference window-relative coordi-

179

nates. They are converted to stdscr-relative coordinates

180

if the window win encloses this point. In this case the

181

function returns TRUE. If one of the parameters is NULL

182

or the point is not inside the window, FALSE is returned.

183

Please notice, that the referenced coordinates are only

184

replaced by the converted coordinates if the transforma-

185

tion was successful.

186

187

The mouse_trafo function performs the same translation as

188

wmouse_trafo, using stdscr for win.

189

190

The mouseinterval function sets the maximum time (in thou-

191

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

192

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

193

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

194

tion returns the previous interval value. Use mouseinter-

195

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

196

default is one sixth of a second.

197

198

Note that mouse events will be ignored when input is in

199

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

200

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

201

str that expects a linefeed for input-loop termination.

</PRE>

<H2>RETURN VALUE</H2><PRE>

206

getmouse and ungetmouse return the integer ERR upon fail-

207

ure or OK upon successful completion.

208

209

getmouse

210

returns an error. If no mouse driver was ini-

211

tialized, or if the mask parameter is zero,

212

213

ungetmouse

214

returns an error if the FIFO is full.

215

216

mousemask returns the mask of reportable events.

217

218

mouseinterval returns the previous interval value, unless

219

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

220

turns the maximum interval value (166).

221

222

wenclose and wmouse_trafo are boolean functions returning

223

TRUE or FALSE depending on their test result.

</PRE>

<H2>PORTABILITY</H2><PRE>

228

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

229

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

230

version of curses.

231

232

The feature macro NCURSES_MOUSE_VERSION is provided so the

233

preprocessor can be used to test whether these features

234

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

235

NCURSES_MOUSE_VERSION will be incremented. These values

236

for NCURSES_MOUSE_VERSION may be specified when configur-

237

ing ncurses:

238

239

1 has definitions for reserved events. The mask

240

uses 28 bits.

241

242

2 adds definitions for button 5, removes the defi-

243

nitions for reserved events. The mask uses 29

244

bits.

245

246

The order of the MEVENT structure members is not guaran-

247

teed. Additional fields may be added to the structure in

248

the future.

249

250

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

251

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

252

cific drivers including

253

Alessandro Rubini's gpm server.

254

FreeBSD sysmouse

255

OS/2 EMX

256

If you are using an unsupported configuration, mouse

257

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

258

mask function will always return 0).

259

260

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

261

in the xterm mouse driver to control the way the terminal

262

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

263

not found, corresponds to private mode 1000 of xterm:

264

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

265

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

266

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

267

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

gloves.

</PRE>

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

274

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

275

Instead, the xterm mouse report sequence will appear in

276

the string read.

277

278

Mouse events under xterm will not be detected correctly in

279

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

280

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

281

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

282

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

283

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

284

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

285

286

Because there are no standard terminal responses that

287

would serve to identify terminals which support the xterm

288

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

289

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

290

the terminal description, then the terminal may send mouse

events.

</PRE>

<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>.

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

</PRE>

<HR>

Man(1) output converted with

</ADDRESS>

</BODY>

</HTML>