1Protocol(3) User Contributed Perl Documentation Protocol(3)
2
6 X11::Protocol - Perl module for the X Window System Protocol, version
7 11
8
10 use X11::Protocol;
11 $x = X11::Protocol->new();
12 $win = $x->new_rsrc;
13 $x->CreateWindow($win, $x->root, 'InputOutput',
14 $x->root_depth, 'CopyFromParent',
15 ($x_coord, $y_coord), $width,
16 $height, $border_w);
17 ...
18
20 X11::Protocol is a client-side interface to the X11 Protocol (see X(1)
21 for information about X11), allowing perl programs to display windows
22 and graphics on X11 servers.
23 A full description of the protocol is beyond the scope of this
25 documentation; for complete information, see the X Window System
26 Protocol, X Version 11, available as Postscript or *roff source from
27 "ftp://ftp.x.org", or Volume 0: X Protocol Reference Manual of O'Reilly
28 & Associates's series of books about X (ISBN 1-56592-083-X,
29 "http://www.oreilly.com"), which contains most of the same information.
30
32 ``The protocol contains many management mechanisms that are not
33 intended for normal applications. Not all mechanisms are needed to
34 build a particular user interface. It is important to keep in mind
35 that the protocol is intended to provide mechanism, not policy.'' --
36 Robert W. Scheifler
37
39 new
40 $x = X11::Protocol->new();
41 $x = X11::Protocol->new($display_name);
42 $x = X11::Protocol->new($connection);
43 $x = X11::Protocol->new($display_name, [$auth_type, $auth_data]);
44 $x = X11::Protocol->new($connection, [$auth_type, $auth_data]);
45 Open a connection to a server. $display_name should be an X display
47 name, of the form 'host:display_num.screen_num'; if no arguments are
48 supplied, the contents of the DISPLAY environment variable are used.
49 Alternatively, a pre-opened connection, of one of the
50 X11::Protocol::Connection classes (see X11::Protocol::Connection,
51 X11::Protocol::Connection::FileHandle,
52 X11::Protocol::Connection::Socket, X11::Protocol::Connection::UNIXFH,
53 X11::Protocol::Connection::INETFH,
54 X11::Protocol::Connection::UNIXSocket,
55 X11::Protocol::Connection::INETSocket) can be given. The authorization
56 data is obtained using X11::Auth or the second argument. If the display
57 is specified by $display_name, rather than $connection, a
58 choose_screen() is also performed, defaulting to screen 0 if the
59 '.screen_num' of the display name is not present. Returns the new
60 protocol object.
61 new_rsrc
63 $x->new_rsrc;
64 Returns a new resource identifier. A unique resource ID is required for
66 every object that the server creates on behalf of the client: windows,
67 fonts, cursors, etc. (IDs are chosen by the client instead of the
68 server for efficiency -- the client doesn't have to wait for the server
69 to acknowledge the creation before starting to use the object).
70 Note that the total number of available resource IDs, while large, is
72 finite. Beginning from the establishment of a connection, resource IDs
73 are allocated sequentially from a range whose size is server dependent
74 (commonly 2**21, about 2 million). If this limit is reached and the
75 server does not support the XC_MISC extension, subsequent calls to
76 new_rsrc will croak. If the server does support this extension, the
77 module will attempt to request a new range of free IDs from the server.
78 This should allow the program to continue, but it is an imperfect
79 solution, as over time the set of available IDs may fragment, requiring
80 increasingly frequent round-trip range requests from the server. For
81 long-running programs, the best approach may be to keep track of free
82 IDs as resources are destroyed. In the current version, however, no
83 special support is provided for this.
84 handle_input
86 $x->handle_input;
87 Get one chunk of information from the server, and do something with it.
89 If it's an error, handle it using the protocol object's handler
90 ('error_handler' -- default is kill the program with an explanatory
91 message). If it's an event, pass it to the chosen event handler, or put
92 it in a queue if the handler is 'queue'. If it's a reply to a request,
93 save using the object's 'replies' hash for further processing.
94 atom_name
96 $name = $x->atom_name($atom);
97 Return the string corresponding to the atom $atom. This is similar to
99 the GetAtomName request, but caches the result for efficiency.
100 atom
102 $atom = $x->atom($name);
103 The inverse operation; Return the (numeric) atom corresponding to
105 $name. This is similar to the InternAtom request, but caches the
106 result.
107 choose_screen
109 $x->choose_screen($screen_num);
110 Indicate that you prefer to use a particular screen of the display.
112 Per-screen information, such as 'root', 'width_in_pixels', and
113 'white_pixel' will be made available as
114 $x->{'root'}
116 instead of
118 $x->{'screens'}[$screen_num]{'root'}
120
122 Generally, symbolic constants used by the protocol, like
123 'CopyFromParent' or 'PieSlice' are passed to methods as strings, and
124 converted into numbers by the module. Their names are the same as
125 those in the protocol specification, including capitalization, but with
126 hyphens ('-') changed to underscores ('_') to look more perl-ish. If
127 you want to do the conversion yourself for some reason, the following
128 methods are available:
129 num
131 $num = $x->num($type, $str)
132 Given a string representing a constant and a string specifying what
134 type of constant it is, return the corresponding number. $type should
135 be a name like 'VisualClass' or 'GCLineStyle'. If the name is not
136 recognized, it is returned intact.
137 interp
139 $name = $x->interp($type, $num)
140 The inverse operation; given a number and string specifying its type,
142 return a string representing the constant.
143 You can disable interp() and the module's internal interpretation of
145 numbers by setting $x->{'do_interp'} to zero. Of course, this isn't
146 very useful, unless you have you own definitions for all the constants.
147 Here is a list of available constant types:
149 AccessMode, AllowEventsMode, AutoRepeatMode, BackingStore,
151 BitGravity, Bool, ChangePropertyMode, CirculateDirection,
152 CirculatePlace, Class, ClipRectangleOrdering, CloseDownMode,
153 ColormapNotifyState, CoordinateMode, CrossingNotifyDetail,
154 CrossingNotifyMode, DeviceEvent, DrawDirection, Error, EventMask,
155 Events, FocusDetail, FocusMode, GCArcMode, GCCapStyle, GCFillRule,
156 GCFillStyle, GCFunction, GCJoinStyle, GCLineStyle, GCSubwindowMode,
157 GrabStatus, HostChangeMode, HostFamily, ImageFormat,
158 InputFocusRevertTo, KeyMask, LedMode, MapState, MappingChangeStatus,
159 MappingNotifyRequest, PointerEvent, PolyShape, PropertyNotifyState,
160 Request, ScreenSaver, ScreenSaverAction, Significance, SizeClass,
161 StackMode, SyncMode, VisibilityState, VisualClass, WinGravity
162
164 At connection time, the server sends a large amount of information
165 about itself to the client. This information is stored in the protocol
166 object for future reference. It can be read directly, like
167 $x->{'release_number'}
169 or, for object oriented True Believers, using a method:
171 $x->release_number
173 The method method also has a one argument form for setting variables,
175 but it isn't really useful for some of the more complex structures.
176 Here is an example of what the object's information might look like:
178 'connection' => X11::Connection::UNIXSocket(0x814526fd),
180 'byte_order' => 'l',
181 'protocol_major_version' => 11,
182 'protocol_minor_version' => 0,
183 'authorization_protocol_name' => 'MIT-MAGIC-COOKIE-1',
184 'release_number' => 3110,
185 'resource_id_base' => 0x1c000002,
186 'motion_buffer_size' => 0,
187 'maximum_request_length' => 65535, # units of 4 bytes
188 'image_byte_order' => 'LeastSiginificant',
189 'bitmap_bit_order' => 'LeastSiginificant',
190 'bitmap_scanline_unit' => 32,
191 'bitmap_scanline_pad' => 32,
192 'min_keycode' => 8,
193 'max_keycode' => 134,
194 'vendor' => 'The XFree86 Project, Inc',
195 'pixmap_formats' => {1 => {'bits_per_pixel' => 1,
196 'scanline_pad' => 32},
197 8 => {'bits_per_pixel' => 8,
198 'scanline_pad' => 32}},
199 'screens' => [{'root' => 43, 'width_in_pixels' => 800,
200 'height_in_pixels' => 600,
201 'width_in_millimeters' => 271,
202 'height_in_millimeters' => 203,
203 'root_depth' => 8,
204 'root_visual' => 34,
205 'default_colormap' => 33,
206 'white_pixel' => 0, 'black_pixel' => 1,
207 'min_installed_maps' => 1,
208 'max_installed_maps' => 1,
209 'backing_stores' => 'Always',
210 'save_unders' => 1,
211 'current_input_masks' => 0x58003d,
212 'allowed_depths' =>
213 [{'depth' => 1, 'visuals' => []},
214 {'depth' => 8, 'visuals' => [
215 {'visual_id' => 34, 'blue_mask' => 0,
216 'green_mask' => 0, 'red_mask' => 0,
217 'class' => 'PseudoColor',
218 'bits_per_rgb_value' => 6,
219 'colormap_entries' => 256},
220 {'visual_id' => 35, 'blue_mask' => 0xc0,
221 'green_mask' => 0x38, 'red_mask' => 0x7,
222 'class' => 'DirectColor',
223 'bits_per_rgb_value' => 6,
224 'colormap_entries' => 8}, ...]}]],
225 'visuals' => {34 => {'depth' => 8, 'class' => 'PseudoColor',
226 'red_mask' => 0, 'green_mask' => 0,
227 'blue_mask'=> 0, 'bits_per_rgb_value' => 6,
228 'colormap_entries' => 256},
229 35 => {'depth' => 8, 'class' => 'DirectColor',
230 'red_mask' => 0x7, 'green_mask' => 0x38,
231 'blue_mask'=> 0xc0, 'bits_per_rgb_value' => 6,
232 'colormap_entries' => 8}, ...}
233 'error_handler' => &\X11::Protocol::default_error_handler,
234 'event_handler' => sub {},
235 'do_interp' => 1
236
238 request
239 $x->request('CreateWindow', ...);
240 $x->req('CreateWindow', ...);
241 $x->CreateWindow(...);
242 Send a protocol request to the server, and get the reply, if any. For
244 names of and information about individual requests, see below and/or
245 the protocol reference manual.
246 robust_req
248 $x->robust_req('CreateWindow', ...);
249 Like request(), but if the server returns an error, return the error
251 information rather than calling the error handler (which by default
252 just croaks). If the request succeeds, returns an array reference
253 containing whatever request() would have. Otherwise, returns the error
254 type, the major and minor opcodes of the failed request, and the extra
255 error information, if any. Note that even if the request normally
256 wouldn't have a reply, this method still has to wait for a round-trip
257 time to see whether an error occurred. If you're concerned about
258 performance, you should design your error handling to be asynchronous.
259 add_reply
261 $x->add_reply($sequence_num, \$var);
262 Add a stub for an expected reply to the object's 'replies' hash. When a
264 reply numbered $sequence_num comes, it will be stored in $var.
265 delete_reply
267 $x->delete_reply($sequence_num);
268 Delete the entry in 'replies' for the specified reply. (This should be
270 done after the reply is received).
271 send
273 $x->send('CreateWindow', ...);
274 Send a request, but do not wait for a reply. You must handle the reply,
276 if any, yourself, using add_reply(), handle_input(), delete_reply(),
277 and unpack_reply(), generally in that order.
278 unpack_reply
280 $x->unpack_reply('GetWindowAttributes', $data);
281 Interpret the raw reply data $data, according to the reply format for
283 the named request. Returns data in the same format as
284 "request($request_name, ...)".
285 This section includes only a short calling summary for each request;
287 for full descriptions, see the protocol standard. Argument order is
288 usually the same as listed in the spec, but you generally don't have to
289 pass lengths of strings or arrays, since perl keeps track. Symbolic
290 constants are generally passed as strings. Most replies are returned as
291 lists, but when there are many values, a hash is used. Lists usually
292 come last; when there is more than one, each is passed by reference. In
293 lists of multi-part structures, each element is a list ref. Parenthesis
294 are inserted in arg lists for clarity, but are optional. Requests are
295 listed in order by major opcode, so related requests are usually close
296 together. Replies follow the '=>'.
297 $x->CreateWindow($wid, $parent, $class, $depth, $visual, ($x, $y),
299 $width, $height, $border_width,
300 'attribute' => $value, ...)
301 $x->ChangeWindowAttributes($window, 'attribute' => $value, ...)
303 $x->GetWindowAttributes($window)
305 =>
306 ('backing_store' => $backing_store, ...)
307 This is an example of a return value that is meant to be assigned to a
309 hash.
310 $x->DestroyWindow($win)
312 $x->DestroySubwindows($win)
314 $x->ChangeSaveSet($window, $mode)
316 $x->ReparentWindow($win, $parent, ($x, $y))
318 $x->MapWindow($win)
320 $x->MapSubwindows($win)
322 $x->UnmapWindow($win)
324 $x->UnmapSubwindows($win)
326 $x->ConfigureWindow($win, 'attribute' => $value, ...)
328 $x->CirculateWindow($win, $direction)
330 Note that this request actually circulates the subwindows of $win, not
332 the window itself.
333 $x->GetGeometry($drawable)
335 =>
336 ('root' => $root, ...)
337 $x->QueryTree($win)
339 =>
340 ($root, $parent, @kids)
341 $x->InternAtom($name, $only_if_exists)
343 =>
344 $atom
345 $x->GetAtomName($atom)
347 =>
348 $name
349 $x->ChangeProperty($window, $property, $type, $format, $mode, $data)
351 $x->DeleteProperty($win, $atom)
353 $x->GetProperty($window, $property, $type, $offset, $length, $delete)
355 =>
356 ($value, $type, $format, $bytes_after)
357 Notice that the value comes first, so you can easily ignore the rest.
359 $x->ListProperties($window)
361 =>
362 (@atoms)
363 $x->SetSelectionOwner($selection, $owner, $time)
365 $x->GetSelectionOwner($selection)
367 =>
368 $owner
369 $x->ConvertSelection($selection, $target, $property, $requestor, $time)
371 $x->SendEvent($destination, $propagate, $event_mask, $event)
373 The $event argument should be the result of a pack_event() (see
375 "EVENTS")
376 $x->GrabPointer($grab_window, $owner_events, $event_mask,
378 $pointer_mode, $keyboard_mode, $confine_to,
379 $cursor, $time)
380 =>
381 $status
382 $x->UngrabPointer($time)
384 $x->GrabButton($modifiers, $button, $grab_window, $owner_events,
386 $event_mask, $pointer_mode, $keyboard_mode,
387 $confine_to, $cursor)
388 $x->UngrabButton($modifiers, $button, $grab_window)
390 $x->ChangeActivePointerGrab($event_mask, $cursor, $time)
392 $x->GrabKeyboard($grab_window, $owner_events, $pointer_mode,
394 $keyboard_mode, $time)
395 =>
396 $status
397 $x->UngrabKeyboard($time)
399 $x->GrabKey($key, $modifiers, $grab_window, $owner_events,
401 $pointer_mode, $keyboard_mode)
402 $x->UngrabKey($key, $modifiers, $grab_window)
404 $x->AllowEvents($mode, $time)
406 $x->GrabServer
408 $x->UngrabServer
410 $x->QueryPointer($window)
412 =>
413 ('root' => $root, ...)
414 $x->GetMotionEvents($start, $stop, $window)
416 =>
417 ([$time, ($x, $y)], [$time, ($x, $y)], ...)
418 $x->TranslateCoordinates($src_window, $dst_window, $src_x, $src_y)
420 =>
421 ($same_screen, $child, $dst_x, $dst_y)
422 $x->WarpPointer($src_window, $dst_window, $src_x, $src_y, $src_width,
424 $src_height, $dst_x, $dst_y)
425 $x->SetInputFocus($focus, $revert_to, $time)
427 $x->GetInputFocus
429 =>
430 ($focus, $revert_to)
431 $x->QueryKeymap
433 =>
434 $keys
435 $keys is a bit vector, so you should use vec() to read it.
437 $x->OpenFont($fid, $name)
439 $x->CloseFont($font)
441 $x->QueryFont($font)
443 =>
444 ('min_char_or_byte2' => $min_char_or_byte2,
445 ...,
446 'min_bounds' =>
447 [$left_side_bearing, $right_side_bearing, $character_width, $ascent,
448 $descent, $attributes],
449 ...,
450 'char_infos' =>
451 [[$left_side_bearing, $right_side_bearing, $character_width, $ascent,
452 $descent, $attributes],
453 ...],
454 'properties' => {$prop => $value, ...}
455 )
456 $x->QueryTextExtents($font, $string)
458 =>
459 ('draw_direction' => $draw_direction, ...)
460 $x->ListFonts($pattern, $max_names)
462 =>
463 @names
464 $x->ListFontsWithInfo($pattern, $max_names)
466 =>
467 ({'name' => $name, ...}, {'name' => $name, ...}, ...)
468 The information in each hash is the same as the the information
470 returned by QueryFont, but without per-character size information. This
471 request is special in that it is the only request that can have more
472 than one reply. This means you should probably only use request() with
473 it, not send(), as the reply counting is complicated. Luckily, you
474 never need this request anyway, as its function is completely
475 duplicated by other requests.
476 $x->SetFontPath(@strings)
478 $x->GetFontPath
480 =>
481 @strings
482 $x->CreatePixmap($pixmap, $drawable, $depth, $width, $height)
484 $x->FreePixmap($pixmap)
486 $x->CreateGC($cid, $drawable, 'attribute' => $value, ...)
488 $x->ChangeGC($gc, 'attribute' => $value, ...)
490 $x->CopyGC($src, $dest, 'attribute', 'attribute', ...)
492 $x->SetDashes($gc, $dash_offset, (@dashes))
494 $x->SetClipRectangles($gc, ($clip_x_origin, $clip_y_origin),
496 $ordering, [$x, $y, $width, $height], ...)
497 $x->ClearArea($window, ($x, $y), $width, $height, $exposures)
499 $x->CopyArea($src_drawable, $dst_drawable, $gc, ($src_x, $src_y),
501 $width, $height, ($dst_x, $dst_y))
502 $x->CopyPlane($src_drawable, $dst_drawable, $gc, ($src_x, $src_y),
504 $width, $height, ($dst_x, $dst_y), $bit_plane)
505 $x->PolyPoint($drawable, $gc, $coordinate_mode,
507 ($x, $y), ($x, $y), ...)
508 $x->PolyLine($drawable, $gc, $coordinate_mode,
510 ($x, $y), ($x, $y), ...)
511 $x->PolySegment($drawable, $gc, ($x, $y) => ($x, $y),
513 ($x, $y) => ($x, $y), ...)
514 $x->PolyRectangle($drawable, $gc,
516 [($x, $y), $width, $height], ...)
517 $x->PolyArc($drawable, $gc,
519 [($x, $y), $width, $height, $angle1, $angle2], ...)
520 $x->FillPoly($drawable, $gc, $shape, $coordinate_mode,
522 ($x, $y), ...)
523 $x->PolyFillRectangle($drawable, $gc,
525 [($x, $y), $width, $height], ...)
526 $x->PolyFillArc($drawable, $gc,
528 [($x, $y), $width, $height, $angle1, $angle2], ...)
529 $x->PutImage($drawable, $gc, $depth, $width, $height,
531 ($dst_x, $dst_y), $left_pad, $format, $data)
532 Currently, the module has no code to handle the various bitmap formats
534 that the server might specify. Therefore, this request will not work
535 portably without a lot of work.
536 $x->GetImage($drawable, ($x, $y), $width, $height, $plane_mask,
538 $format)
539 $x->PolyText8($drawable, $gc, ($x, $y),
541 ($font OR [$delta, $string]), ...)
542 $x->PolyText16($drawable, $gc, ($x, $y),
544 ($font OR [$delta, $string]), ...)
545 $x->ImageText8($drawable, $gc, ($x, $y), $string)
547 $x->ImageText16($drawable, $gc, ($x, $y), $string)
549 $x->CreateColormap($mid, $visual, $window, $alloc)
551 $x->FreeColormap($cmap)
553 $x->CopyColormapAndFree($mid, $src_cmap)
555 $x->InstallColormap($cmap)
557 $x->UninstallColormap($cmap)
559 $x->ListInstalledColormaps($window)
561 =>
562 @cmaps
563 $x->AllocColor($cmap, ($red, $green, $blue))
565 =>
566 ($pixel, ($red, $green, $blue))
567 $x->AllocNamedColor($cmap, $name)
569 =>
570 ($pixel, ($exact_red, $exact_green, $exact_blue),
571 ($visual_red, $visual_green, $visual_blue))
572 $x->AllocColorCells($cmap, $colors, $planes, $contiguous)
574 =>
575 ([@pixels], [@masks])
576 $x->AllocColorPlanes($cmap, $colors, ($reds, $greens, $blues),
578 $contiguous)
579 =>
580 (($red_mask, $green_mask, $blue_mask), @pixels)
581 $x->FreeColors($cmap, $plane_mask, @pixels)
583 $x->StoreColors($cmap, [$pixel, $red, $green, $blue, $do_mask], ...)
585 The 1, 2, and 4 bits in $do_mask are do-red, do-green, and do-blue.
587 $do_mask can be omitted, defaulting to 7, the usual case -- change the
588 whole color.
589 $x->StoreNamedColor($cmap, $pixel, $name, $do_mask)
591 $do_mask has the same interpretation as above, but is mandatory.
593 $x->QueryColors($cmap, @pixels)
595 =>
596 ([$red, $green, $blue], ...)
597 $x->LookupColor($cmap, $name)
599 =>
600 (($exact_red, $exact_green, $exact_blue),
601 ($visual_red, $visual_green, $visual_blue))
602 $x->CreateCursor($cid, $source, $mask,
604 ($fore_red, $fore_green, $fore_blue),
605 ($back_red, $back_green, $back_blue),
606 ($x, $y))
607 $x->CreateGlyphCursor($cid, $source_font, $mask_font,
609 $source_char, $mask_char,
610 ($fore_red, $fore_green, $fore_blue),
611 ($back_red, $back_green, $back_blue))
612 $x->FreeCursor($cursor)
614 $x->RecolorCursor($cursor, ($fore_red, $fore_green, $fore_blue),
616 ($back_red, $back_green, $back_blue))
617 $x->QueryBestSize($class, $drawable, $width, $height)
619 =>
620 ($width, $height)
621 $x->QueryExtension($name)
623 =>
624 ($major_opcode, $first_event, $first_error)
625 If the extension is not present, an empty list is returned.
627 $x->ListExtensions
629 =>
630 (@names)
631 $x->ChangeKeyboardMapping($first_keycode, $keysysms_per_keycode,
633 @keysyms)
634 $x->GetKeyboardMapping($first_keycode, $count)
636 =>
637 ($keysysms_per_keycode, [$keysym, ...], [$keysym, ...], ...)
638 $x->ChangeKeyboardControl('attribute' => $value, ...)
640 $x->GetKeyboardControl
642 =>
643 ('global_auto_repeat' => $global_auto_repeat, ...)
644 $x->Bell($percent)
646 $x->ChangePointerControl($do_acceleration, $do_threshold,
648 $acceleration_numerator,
649 $acceleration_denominator, $threshold)
650 $x->GetPointerControl
652 =>
653 ($acceleration_numerator, $acceleration_denominator, $threshold)
654 $x->SetScreenSaver($timeout, $interval, $prefer_blanking,
656 $allow_exposures)
657 $x->GetScreenSaver
659 =>
660 ($timeout, $interval, $prefer_blanking, $allow_exposures)
661 $x->ChangeHosts($mode, $host_family, $host_address)
663 $x->ListHosts
665 =>
666 ($mode, [$family, $host], ...)
667 $x->SetAccessControl($mode)
669 $x->SetCloseDownMode($mode)
671 $x->KillClient($resource)
673 $x->RotateProperties($win, $delta, @props)
675 $x->ForceScreenSaver($mode)
677 $x->SetPointerMapping(@map)
679 =>
680 $status
681 $x->GetPointerMapping
683 =>
684 @map
685 $x->SetModifierMapping(@keycodes)
687 =>
688 $status
689 $x->GetModiferMapping
691 =>
692 @keycodes
693 $x->NoOperation($length)
695 $length specifies the length of the entire useless request, in four
697 byte units, and is optional.
698
700 To receive events, first set the 'event_mask' attribute on a window to
701 indicate what types of events you desire (see "pack_event_mask"). Then,
702 set the protocol object's 'event_handler' to a subroutine reference
703 that will handle the events. Alternatively, set 'event_handler' to
704 'queue', and retrieve events using dequeue_event() or next_event(). In
705 both cases, events are returned as a hash. For instance, a typical
706 MotionNotify event might look like this:
707 %event = ('name' => 'MotionNotify', 'sequence_number' => 12,
709 'state' => 0, 'event' => 58720256, 'root' => 43,
710 'child' => None, 'same_screen' => 1, 'time' => 966080746,
711 'detail' => 'Normal', 'event_x' => 10, 'event_y' => 3,
712 'code' => 6, 'root_x' => 319, 'root_y' => 235)
713 pack_event_mask
715 $mask = $x->pack_event_mask('ButtonPress', 'KeyPress', 'Exposure');
716 Make an event mask (suitable as the 'event_mask' of a window) from a
718 list of strings specifying event types.
719 unpack_event_mask
721 @event_types = $x->unpack_event_mask($mask);
722 The inverse operation; convert an event mask obtained from the server
724 into a list of names of event categories.
725 dequeue_event
727 %event = $x->dequeue_event;
728 If there is an event waiting in the queue, return it.
730 next_event
732 %event = $x->next_event;
733 Like Xlib's XNextEvent(), this function is equivalent to
735 $x->handle_input until %event = dequeue_event;
737 pack_event
739 $data = $x->pack_event(%event);
740 Given an event in hash form, pack it into a string. This is only useful
742 as an argument to SendEvent().
743 unpack_event
745 %event = $x->unpack_event($data);
746 The inverse operation; given the raw data for an event (32 bytes),
748 unpack it into hash form. Normally, this is done automatically.
749
751 Protocol extensions add new requests, event types, and error types to
752 the protocol. Support for them is compartmentalized in modules in the
753 X11::Protocol::Ext:: hierarchy. For an example, see
754 X11::Protocol::Ext::SHAPE. You can tell if the module has loaded an
755 extension by looking at
756 $x->{'ext'}{$extension_name}
758 If the extension has been initialized, this value will be an array
760 reference, [$major_request_number, $first_event_number,
761 $first_error_number, $obj], where $obj is an object containing
762 information private to the extension.
763 init_extension
765 $x->init_extension($name);
766 Initialize an extension: query the server to find the extension's
768 request number, then load the corresponding module. Returns 0 if the
769 server does not support the named extension, or if no module to
770 interface with it exists.
771 init_extensions
773 $x->init_extensions;
774 Initialize protocol extensions. This does a ListExtensions request,
776 then calls init_extension() for each extension that the server
777 supports.
778
780 Internally, the X11::Protocol module is table driven. All an extension
781 has to do is to add new add entries to the protocol object's tables. An
782 extension module should "use X11::Protocol", and should define an new()
783 method
784 X11::Protocol::Ext::NAME
786 ->new($x, $request_num, $event_num, $error_num)
787 where $x is the protocol object and $request_num, $event_num and
789 $error_num are the values returned by QueryExtension().
790 The new() method should add new types of constant like
792 $x->{'ext_const'}{'ConstantType'} = ['Constant', 'Constant', ...]
794 and set up the corresponding name to number translation hashes like
796 $x->{'ext_const_num'}{'ConstantType'} =
798 {make_num_hash($x->{'ext_const'}{'ConstantType'})}
799 Event names go in
801 $x->{'ext_const'}{'Events'}[$event_number]
803 while specifications for event contents go in
805 $x->{'ext_event'}[$event_number]
807 each element of which is either "[\&unpack_sub, \&pack_sub]" or
809 "[$pack_format, $field, $field, ...]", where each $field is 'name',
810 "['name', 'const_type']", or "['name', ['special_name_for_zero',
811 'special_name_for_one']]", where 'special_name_for_one' is optional.
812 Finally,
814 $x->{'ext_request'}{$major_request_number}
816 should be an array of arrays, with each array either "[$name,
818 \&packit]" or "[$name, \&packit, \&unpackit]", and
819 $x->{'ext_request_num'}{$request_name}
821 should be initialized with "[$minor_num, $major_num]" for each request
823 the extension defines. For examples of code that does all of this, look
824 at X11::Protocol::Ext::SHAPE.
825 X11::Protocol exports several functions that might be useful in
827 extensions (note that these are not methods).
828 padding
830 $p = padding $x;
831 Given an integer, compute the number need to round it up to a multiple
833 of 4. For instance, padding(5) is 3.
834 pad
836 $p = pad $str;
837 Given a string, return the number of extra bytes needed to make a
839 multiple of 4. Equivalent to "padding(length($str))".
840 padded
842 $data = pack(padded($str), $str);
843 Return a format string, suitable for pack(), for a string padded to a
845 multiple of 4 bytes. For instance, "pack(padded('Hello'), 'Hello')"
846 gives "Hello\0\0\0".
847 hexi
849 $str = hexi $n;
850 Format a number in hexidecimal, and add a "0x" to the front.
852 make_num_hash
854 %hash = make_num_hash(['A', 'B', 'C']);
855 Given a reference to a list of strings, return a hash mapping the
857 strings onto numbers representing their position in the list, as used
858 by "$x->{'ext_const_num'}".
859
861 This module is too big (~2500 lines), too slow (10 sec to load on a
862 slow machine), too inefficient (request args are copied several times),
863 and takes up too much memory (3000K for basicwin).
864 If you have more than 65535 replies outstanding at once, sequence
866 numbers can collide.
867 The protocol is too complex.
869
871 Stephen McCamant <SMCCAM@cpan.org>.
872
874 perl(1), X(1), X11::Keysyms, X11::Protocol::Ext::SHAPE,
875 X11::Protocol::Ext::BIG_REQUESTS, X11::Protocol::Ext::XC_MISC,
876 X11::Protocol::Ext::DPMS, X11::Protocol::Ext::XFree86_Misc, X11::Auth,
877 X Window System Protocol (X Version 11), Inter-Client Communications
878 Conventions Manual, X Logical Font Description Conventions.
879perl v5.32.1 2021-01-27 Protocol(3)