Merge branch 'master' of ssh://tz.otcshare.org/profile/base/libXi
[platform/upstream/libXi.git] / man / XSendExtensionEvent.man
1 '\" t
2 .\"     Title: xsendextensionevent
3 .\"    Author: [FIXME: author] [see http://docbook.sf.net/el/author]
4 .\" Generator: DocBook XSL Stylesheets v1.76.1 <http://docbook.sf.net/>
5 .\"      Date: 09/23/2011
6 .\"    Manual: [FIXME: manual]
7 .\"    Source: [FIXME: source]
8 .\"  Language: English
9 .\"
10 .TH "XSENDEXTENSIONEVENT" "libmansuffix" "09/23/2011" "[FIXME: source]" "[FIXME: manual]"
11 .\" -----------------------------------------------------------------
12 .\" * Define some portability stuff
13 .\" -----------------------------------------------------------------
14 .\" ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
15 .\" http://bugs.debian.org/507673
16 .\" http://lists.gnu.org/archive/html/groff/2009-02/msg00013.html
17 .\" ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
18 .ie \n(.g .ds Aq \(aq
19 .el       .ds Aq '
20 .\" -----------------------------------------------------------------
21 .\" * set default formatting
22 .\" -----------------------------------------------------------------
23 .\" disable hyphenation
24 .nh
25 .\" disable justification (adjust text to left margin only)
26 .ad l
27 .\" -----------------------------------------------------------------
28 .\" * MAIN CONTENT STARTS HERE *
29 .\" -----------------------------------------------------------------
30 .SH "NAME"
31 XSendExtensionEvent \- send input extension events to a client
32 .SH "SYNOPSIS"
33 .sp
34 .nf
35 #include <X11/extensions/XInput\&.h>
36 .fi
37 .sp
38 .nf
39 Status XSendExtensionEvent( Display *display,
40                             XDevice *device,
41                             Window destination,
42                             Bool propagate,
43                             int event_count,
44                             XEventClass *event_list,
45                             XEvent *event_send);
46 .fi
47 .sp
48 .nf
49 display
50        Specifies the connection to the X server\&.
51 .fi
52 .sp
53 .nf
54 device
55        Specifies the device from which the events are to be
56        sent\&.
57 .fi
58 .sp
59 .nf
60 destination
61        Specifies the window the event is to be sent to\&. You can
62        pass window id, PointerWindow,or InputFocus\&.
63 .fi
64 .sp
65 .nf
66 propagate
67        Specifies a Boolean value that is either True or False\&.
68 .fi
69 .sp
70 .nf
71 event_count
72        Specifies the count of XEventClasses in event_list\&.
73 .fi
74 .sp
75 .nf
76 event_list
77        Specifies the list of event selections to be used\&.
78 .fi
79 .sp
80 .nf
81 event_send
82        Specifies a pointer to the event that is to be sent\&.
83 .fi
84 .SH "DESCRIPTION"
85 .sp
86 .if n \{\
87 .RS 4
88 .\}
89 .nf
90 The XSendExtensionEvent request identifies the destination
91 window, determines which clients should receive the specified
92 events, and ignores any active grabs\&. This request requires you
93 to pass an event class list\&. For a discussion of the valid
94 event class names, see XOpenDevice(libmansuffix) This
95 request uses the w argument to identify the destination window
96 as follows:
97   * If w is PointerWindow,the destination window is the window
98     that contains the pointer\&.
99   * If w is InputFocusand if the focus window contains the
100     pointer,the destination window is the window that contains
101     the pointer; otherwise, the destination window is the focus
102     window\&.
103 .fi
104 .if n \{\
105 .RE
106 .\}
107 .sp
108 .if n \{\
109 .RS 4
110 .\}
111 .nf
112 To determine which clients should receive the specified events,
113 XSendExtensionEventuses the propagate argument as follows:
114   * If event_list is the empty set,the event is sent to the
115     client that created the destination window\&. If that client
116     no longer exists,no event is sent\&.
117   * If propagate is False,the event is sent to every client
118     selecting on destination any of the eventtypes specified by
119     the event_list array\&.
120   * If propagate is Trueand no clients have selected on
121     destination any ofthe events specified by the event_list
122     array,the destination is replaced with theclosest ancestor
123     of destination for which some client has selected atype
124     specified by the event\-list array and for which no
125     interveningwindow has that type in
126     itsdo\-not\-propagate\-mask\&. If no such window exists or if
127     the window isan ancestor of the focus window and
128     InputFocuswas originally specifiedas the destination, the
129     event is not sent to any clients\&. Otherwise, the event is
130     reported to every client selecting on the finaldestination
131     any of the events specified in the event_list array\&.
132 .fi
133 .if n \{\
134 .RE
135 .\}
136 .sp
137 .if n \{\
138 .RS 4
139 .\}
140 .nf
141 The event in the XEventstructure must be one of the events
142 defined by the input extension (or a BadValueerror results) so
143 that the X server can correctly byte\-swapthe contents as
144 necessary\&. The contents of the event areotherwise unaltered and
145 unchecked by the X server except to force send_event to Truein
146 the forwarded event and to set the serial number in the event
147 correctly\&.
148 .fi
149 .if n \{\
150 .RE
151 .\}
152 .sp
153 .if n \{\
154 .RS 4
155 .\}
156 .nf
157 XSendExtensionEventreturns zero if the conversion to wire
158 protocol format failedand returns nonzero
159 otherwise\&.XSendExtensionEventcan generate BadClass, BadDevice,
160 BadValue, and BadWindow errors\&.
161 .fi
162 .if n \{\
163 .RE
164 .\}
165 .SH "DIAGNOSTICS"
166 .sp
167 .if n \{\
168 .RS 4
169 .\}
170 .nf
171 BadDevice
172        An invalid device was specified\&. The specified device
173        does not exist or has not been opened by this client via
174        XOpenInputDevice\&. This error may also occur if the
175        specified device is the X keyboard or X pointer device\&.
176 .fi
177 .if n \{\
178 .RE
179 .\}
180 .sp
181 .if n \{\
182 .RS 4
183 .\}
184 .nf
185 BadValue
186        Some numeric value falls outside the range of values
187        accepted by the request\&. Unless a specific range is
188        specified for an argument, the full range defined by the
189        argument\*(Aqs type is accepted\&. Any argument defined as a
190        set of alternatives can generate this error\&.
191 .fi
192 .if n \{\
193 .RE
194 .\}
195 .sp
196 .if n \{\
197 .RS 4
198 .\}
199 .nf
200 BadWindow
201        A value for a Window argument does not name a defined
202        window\&.
203 .fi
204 .if n \{\
205 .RE
206 .\}