X11::Protocol(3pm)

1Protocol(3)           User Contributed Perl Documentation          Protocol(3)
2
3
4

NAME

6       X11::Protocol - Perl module for the X Window System Protocol, version
7       11
8

SYNOPSIS

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

DESCRIPTION

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
24       A full description of the protocol is beyond the scope of this documen‐
25       tation; for complete information, see the X Window System Protocol, X
26       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

DISCLAIMER

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

BASIC METHODS

39       new
40
41         $x = X11::Protocol->new();
42         $x = X11::Protocol->new($display_name);
43         $x = X11::Protocol->new($connection);
44         $x = X11::Protocol->new($display_name, [$auth_type, $auth_data]);
45         $x = X11::Protocol->new($connection, [$auth_type, $auth_data]);
46
47       Open a connection to a server. $display_name should be an X display
48       name, of the form 'host:display_num.screen_num'; if no arguments are
49       supplied, the contents of the DISPLAY environment variable are used.
50       Alternatively, a pre-opened connection, of one of the X11::Proto‐
51       col::Connection classes (see X11::Protocol::Connection, X11::Proto‐
52       col::Connection::FileHandle, X11::Protocol::Connection::Socket,
53       X11::Protocol::Connection::UNIXFH, X11::Protocol::Connection::INETFH,
54       X11::Protocol::Connection::UNIXSocket, X11::Protocol::Connection::INET‐
55       Socket) can be given. The authorization data is obtained using
56       X11::Auth or the second argument. If the display is specified by $dis‐
57       play_name, rather than $connection, a choose_screen() is also per‐
58       formed, defaulting to screen 0 if the '.screen_num' of the display name
59       is not present.  Returns the new protocol object.
60
61       new_rsrc
62
63         $x->new_rsrc;
64
65       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
71       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 solu‐
79       tion, 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
85       handle_input
86
87         $x->handle_input;
88
89       Get one chunk of information from the server, and do something with it.
90       If it's an error, handle it using the protocol object's handler
91       ('error_handler' -- default is kill the program with an explanatory
92       message). If it's an event, pass it to the chosen event handler, or put
93       it in a queue if the handler is 'queue'. If it's a reply to a request,
94       save using the object's 'replies' hash for further processing.
95
96       atom_name
97
98         $name = $x->atom_name($atom);
99
100       Return the string corresponding to the atom $atom. This is similar to
101       the GetAtomName request, but caches the result for efficiency.
102
103       atom
104
105         $atom = $x->atom($name);
106
107       The inverse operation; Return the (numeric) atom corresponding to
108       $name.  This is similar to the InternAtom request, but caches the
109       result.
110
111       choose_screen
112
113         $x->choose_screen($screen_num);
114
115       Indicate that you prefer to use a particular screen of the display.
116       Per-screen information, such as 'root', 'width_in_pixels', and
117       'white_pixel' will be made available as
118
119         $x->{'root'}
120
121       instead of
122
123         $x->{'screens'}[$screen_num]{'root'}
124

SYMBOLIC CONSTANTS

126       Generally, symbolic constants used by the protocol, like 'CopyFromPar‐
127       ent' or 'PieSlice' are passed to methods as strings, and converted into
128       numbers by the module.  Their names are the same as those in the proto‐
129       col specification, including capitalization, but with hyphens ('-')
130       changed to underscores ('_') to look more perl-ish. If you want to do
131       the conversion yourself for some reason, the following methods are
132       available:
133
134       num
135
136         $num = $x->num($type, $str)
137
138       Given a string representing a constant and a string specifying what
139       type of constant it is, return the corresponding number. $type should
140       be a name like 'VisualClass' or 'GCLineStyle'. If the name is not rec‐
141       ognized, it is returned intact.
142
143       interp
144
145         $name = $x->interp($type, $num)
146
147       The inverse operation; given a number and string specifying its type,
148       return a string representing the constant.
149
150       You can disable interp() and the module's internal interpretation of
151       numbers by setting $x->{'do_interp'} to zero. Of course, this isn't
152       very useful, unless you have you own definitions for all the constants.
153
154       Here is a list of available constant types:
155
156         AccessMode, AllowEventsMode, AutoRepeatMode, BackingStore,
157         BitGravity, Bool, ChangePropertyMode, CirculateDirection,
158         CirculatePlace, Class, ClipRectangleOrdering, CloseDownMode,
159         ColormapNotifyState, CoordinateMode, CrossingNotifyDetail,
160         CrossingNotifyMode, DeviceEvent, DrawDirection, Error, EventMask,
161         Events, FocusDetail, FocusMode, GCArcMode, GCCapStyle, GCFillRule,
162         GCFillStyle, GCFunction, GCJoinStyle, GCLineStyle, GCSubwindowMode,
163         GrabStatus, HostChangeMode, HostFamily, ImageFormat,
164         InputFocusRevertTo, KeyMask, LedMode, MapState, MappingChangeStatus,
165         MappingNotifyRequest, PointerEvent, PolyShape, PropertyNotifyState,
166         Request, ScreenSaver, ScreenSaverAction, Significance, SizeClass,
167         StackMode, SyncMode, VisibilityState, VisualClass, WinGravity
168

SERVER INFORMATION

170       At connection time, the server sends a large amount of information
171       about itself to the client. This information is stored in the protocol
172       object for future reference. It can be read directly, like
173
174         $x->{'release_number'}
175
176       or, for object oriented True Believers, using a method:
177
178         $x->release_number
179
180       The method method also has a one argument form for setting variables,
181       but it isn't really useful for some of the more complex structures.
182
183       Here is an example of what the object's information might look like:
184
185         'connection' => X11::Connection::UNIXSocket(0x814526fd),
186         'byte_order' => 'l',
187         'protocol_major_version' => 11,
188         'protocol_minor_version' => 0,
189         'authorization_protocol_name' => 'MIT-MAGIC-COOKIE-1',
190         'release_number' => 3110,
191         'resource_id_base' => 0x1c000002,
192         'motion_buffer_size' => 0,
193         'maximum_request_length' => 65535, # units of 4 bytes
194         'image_byte_order' => 'LeastSiginificant',
195         'bitmap_bit_order' => 'LeastSiginificant',
196         'bitmap_scanline_unit' => 32,
197         'bitmap_scanline_pad' => 32,
198         'min_keycode' => 8,
199         'max_keycode' => 134,
200         'vendor' => 'The XFree86 Project, Inc',
201         'pixmap_formats' => {1 => {'bits_per_pixel' => 1,
202                                    'scanline_pad' => 32},
203                              8 => {'bits_per_pixel' => 8,
204                                    'scanline_pad' => 32}},
205         'screens' => [{'root' => 43, 'width_in_pixels' => 800,
206                        'height_in_pixels' => 600,
207                        'width_in_millimeters' => 271,
208                        'height_in_millimeters' => 203,
209                        'root_depth' => 8,
210                        'root_visual' => 34,
211                        'default_colormap' => 33,
212                        'white_pixel' => 0, 'black_pixel' => 1,
213                        'min_installed_maps' => 1,
214                        'max_installed_maps' => 1,
215                        'backing_stores' => 'Always',
216                        'save_unders' => 1,
217                        'current_input_masks' => 0x58003d,
218                        'allowed_depths' =>
219                           [{'depth' => 1, 'visuals' => []},
220                            {'depth' => 8, 'visuals' => [
221                               {'visual_id' => 34, 'blue_mask' => 0,
222                                'green_mask' => 0, 'red_mask' => 0,
223                                'class' => 'PseudoColor',
224                                'bits_per_rgb_value' => 6,
225                                'colormap_entries' => 256},
226                               {'visual_id' => 35, 'blue_mask' => 0xc0,
227                                'green_mask' => 0x38, 'red_mask' => 0x7,
228                                'class' => 'DirectColor',
229                                'bits_per_rgb_value' => 6,
230                                'colormap_entries' => 8}, ...]}]],
231         'visuals' => {34 => {'depth' => 8, 'class' => 'PseudoColor',
232                              'red_mask' => 0, 'green_mask' => 0,
233                              'blue_mask'=> 0, 'bits_per_rgb_value' => 6,
234                              'colormap_entries' => 256},
235                       35 => {'depth' => 8, 'class' => 'DirectColor',
236                              'red_mask' => 0x7, 'green_mask' => 0x38,
237                              'blue_mask'=> 0xc0, 'bits_per_rgb_value' => 6,
238                              'colormap_entries' => 8}, ...}
239         'error_handler' => &\X11::Protocol::default_error_handler,
240         'event_handler' => sub {},
241         'do_interp' => 1
242

REQUESTS

244       request
245
246         $x->request('CreateWindow', ...);
247         $x->req('CreateWindow', ...);
248         $x->CreateWindow(...);
249
250       Send a protocol request to the server, and get the reply, if any. For
251       names of and information about individual requests, see below and/or
252       the protocol reference manual.
253
254       robust_req
255
256         $x->robust_req('CreateWindow', ...);
257
258       Like request(), but if the server returns an error, return the error
259       information rather than calling the error handler (which by default
260       just croaks). If the request succeeds, returns an array reference con‐
261       taining whatever request() would have. Otherwise, returns the error
262       type, the major and minor opcodes of the failed request, and the extra
263       error information, if any. Note that even if the request normally
264       wouldn't have a reply, this method still has to wait for a round-trip
265       time to see whether an error occurred. If you're concerned about per‐
266       formance, you should design your error handling to be asynchronous.
267
268       add_reply
269
270         $x->add_reply($sequence_num, \$var);
271
272       Add a stub for an expected reply to the object's 'replies' hash. When a
273       reply numbered $sequence_num comes, it will be stored in $var.
274
275       delete_reply
276
277         $x->delete_reply($sequence_num);
278
279       Delete the entry in 'replies' for the specified reply. (This should be
280       done after the reply is received).
281
282       send
283
284         $x->send('CreateWindow', ...);
285
286       Send a request, but do not wait for a reply. You must handle the reply,
287       if any, yourself, using add_reply(), handle_input(), delete_reply(),
288       and unpack_reply(), generally in that order.
289
290       unpack_reply
291
292         $x->unpack_reply('GetWindowAttributes', $data);
293
294       Interpret the raw reply data $data, according to the reply format for
295       the named request. Returns data in the same format as
296       "request($request_name, ...)".
297
298       This section includes only a short calling summary for each request;
299       for full descriptions, see the protocol standard. Argument order is
300       usually the same as listed in the spec, but you generally don't have to
301       pass lengths of strings or arrays, since perl keeps track. Symbolic
302       constants are generally passed as strings. Most replies are returned as
303       lists, but when there are many values, a hash is used. Lists usually
304       come last; when there is more than one, each is passed by reference. In
305       lists of multi-part structures, each element is a list ref. Parenthesis
306       are inserted in arg lists for clarity, but are optional. Requests are
307       listed in order by major opcode, so related requests are usually close
308       together. Replies follow the '=>'.
309
310         $x->CreateWindow($wid, $parent, $class, $depth, $visual, ($x, $y),
311                          $width, $height, $border_width,
312                          'attribute' => $value, ...)
313
314         $x->ChangeWindowAttributes($window, 'attribute' => $value, ...)
315
316         $x->GetWindowAttributes($window)
317         =>
318         ('backing_store' => $backing_store, ...)
319
320       This is an example of a return value that is meant to be assigned to a
321       hash.
322
323         $x->DestroyWindow($win)
324
325         $x->DestroySubwindows($win)
326
327         $x->ChangeSaveSet($window, $mode)
328
329         $x->ReparentWindow($win, $parent, ($x, $y))
330
331         $x->MapWindow($win)
332
333         $x->MapSubwindows($win)
334
335         $x->UnmapWindow($win)
336
337         $x->UnmapSubwindows($win)
338
339         $x->ConfigureWindow($win, 'attribute' => $value, ...)
340
341         $x->CirculateWindow($win, $direction)
342
343       Note that this request actually circulates the subwindows of $win, not
344       the window itself.
345
346         $x->GetGeometry($drawable)
347         =>
348         ('root' => $root, ...)
349
350         $x->QueryTree($win)
351         =>
352         ($root, $parent, @kids)
353
354         $x->InternAtom($name, $only_if_exists)
355         =>
356         $atom
357
358         $x->GetAtomName($atom)
359         =>
360         $name
361
362         $x->ChangeProperty($window, $property, $type, $format, $mode, $data)
363
364         $x->DeleteProperty($win, $atom)
365
366         $x->GetProperty($window, $property, $type, $offset, $length, $delete)
367         =>
368         ($value, $type, $format, $bytes_after)
369
370       Notice that the value comes first, so you can easily ignore the rest.
371
372         $x->ListProperties($window)
373         =>
374         (@atoms)
375
376         $x->SetSelectionOwner($selection, $owner, $time)
377
378         $x->GetSelectionOwner($selection)
379         =>
380         $owner
381
382         $x->ConvertSelection($selection, $target, $property, $requestor, $time)
383
384         $x->SendEvent($destination, $propagate, $event_mask, $event)
385
386       The $event argument should be the result of a pack_event() (see
387       "EVENTS")
388
389         $x->GrabPointer($grab_window, $owner_events, $event_mask,
390                         $pointer_mode, $keyboard_mode, $confine_to,
391                         $cursor, $time)
392         =>
393         $status
394
395         $x->UngrabPointer($time)
396
397         $x->GrabButton($modifiers, $button, $grab_window, $owner_events,
398                        $event_mask, $pointer_mode, $keyboard_mode,
399                        $confine_to, $cursor)
400
401         $x->UngrabButton($modifiers, $button, $grab_window)
402
403         $x->ChangeActivePointerGrab($event_mask, $cursor, $time)
404
405         $x->GrabKeyboard($grab_window, $owner_events, $pointer_mode,
406                          $keyboard_mode, $time)
407         =>
408         $status
409
410         $x->UngrabKeyboard($time)
411
412         $x->GrabKey($key, $modifiers, $grab_window, $owner_events,
413                     $pointer_mode, $keyboard_mode)
414
415         $x->UngrabKey($key, $modifiers, $grab_window)
416
417         $x->AllowEvents($mode, $time)
418
419         $x->GrabServer
420
421         $x->UngrabServer
422
423         $x->QueryPointer($window)
424         =>
425         ('root' => $root, ...)
426
427         $x->GetMotionEvents($start, $stop, $window)
428         =>
429         ([$time, ($x, $y)], [$time, ($x, $y)], ...)
430
431         $x->TranslateCoordinates($src_window, $dst_window, $src_x, $src_y)
432         =>
433         ($same_screen, $child, $dst_x, $dst_y)
434
435         $x->WarpPointer($src_window, $dst_window, $src_x, $src_y, $src_width,
436                         $src_height, $dst_x, $dst_y)
437
438         $x->SetInputFocus($focus, $revert_to, $time)
439
440         $x->GetInputFocus
441         =>
442         ($focus, $revert_to)
443
444         $x->QueryKeymap
445         =>
446         $keys
447
448       $keys is a bit vector, so you should use vec() to read it.
449
450         $x->OpenFont($fid, $name)
451
452         $x->CloseFont($font)
453
454         $x->QueryFont($font)
455         =>
456         ('min_char_or_byte2' => $min_char_or_byte2,
457          ...,
458          'min_bounds' =>
459          [$left_side_bearing, $right_side_bearing, $character_width, $ascent,
460           $descent, $attributes],
461          ...,
462          'char_infos' =>
463          [[$left_side_bearing, $right_side_bearing, $character_width, $ascent,
464            $descent, $attributes],
465           ...],
466          'properties' => {$prop => $value, ...}
467          )
468
469         $x->QueryTextExtents($font, $string)
470         =>
471         ('draw_direction' => $draw_direction, ...)
472
473         $x->ListFonts($pattern, $max_names)
474         =>
475         @names
476
477         $x->ListFontsWithInfo($pattern, $max_names)
478         =>
479         ({'name' => $name, ...}, {'name' => $name, ...}, ...)
480
481       The information in each hash is the same as the the information
482       returned by QueryFont, but without per-character size information. This
483       request is special in that it is the only request that can have more
484       than one reply.  This means you should probably only use request() with
485       it, not send(), as the reply counting is complicated. Luckily, you
486       never need this request anyway, as its function is completely dupli‐
487       cated by other requests.
488
489         $x->SetFontPath(@strings)
490
491         $x->GetFontPath
492         =>
493         @strings
494
495         $x->CreatePixmap($pixmap, $drawable, $depth, $width, $height)
496
497         $x->FreePixmap($pixmap)
498
499         $x->CreateGC($cid, $drawable, 'attribute' => $value, ...)
500
501         $x->ChangeGC($gc, 'attribute' => $value, ...)
502
503         $x->CopyGC($src, $dest, 'attribute', 'attribute', ...)
504
505         $x->SetDashes($gc, $dash_offset, (@dashes))
506
507         $x->SetClipRectangles($gc, ($clip_x_origin, $clip_y_origin),
508                               $ordering, [$x, $y, $width, $height], ...)
509
510         $x->ClearArea($window, ($x, $y), $width, $height, $exposures)
511
512         $x->CopyArea($src_drawable, $dst_drawable, $gc, ($src_x, $src_y),
513                      $width, $height, ($dst_x, $dst_y))
514
515         $x->CopyPlane($src_drawable, $dst_drawable, $gc, ($src_x, $src_y),
516                       $width, $height, ($dst_x, $dst_y), $bit_plane)
517
518         $x->PolyPoint($drawable, $gc, $coordinate_mode,
519                       ($x, $y), ($x, $y), ...)
520
521         $x->PolyLine($drawable, $gc, $coordinate_mode,
522                      ($x, $y), ($x, $y), ...)
523
524         $x->PolySegment($drawable, $gc, ($x, $y) => ($x, $y),
525                         ($x, $y) => ($x, $y), ...)
526
527         $x->PolyRectangle($drawable, $gc,
528                           [($x, $y), $width, $height], ...)
529
530         $x->PolyArc($drawable, $gc,
531                     [($x, $y), $width, $height, $angle1, $angle2], ...)
532
533         $x->FillPoly($drawable, $gc, $shape, $coordinate_mode,
534                      ($x, $y), ...)
535
536         $x->PolyFillRectangle($drawable, $gc,
537                               [($x, $y), $width, $height], ...)
538
539         $x->PolyFillArc($drawable, $gc,
540                         [($x, $y), $width, $height, $angle1, $angle2], ...)
541
542         $x->PutImage($drawable, $gc, $depth, $width, $height,
543                      ($dst_x, $dst_y), $left_pad, $format, $data)
544
545       Currently, the module has no code to handle the various bitmap formats
546       that the server might specify. Therefore, this request will not work
547       portably without a lot of work.
548
549         $x->GetImage($drawable, ($x, $y), $width, $height, $plane_mask,
550                      $format)
551
552         $x->PolyText8($drawable, $gc, ($x, $y),
553                       ($font OR [$delta, $string]), ...)
554
555         $x->PolyText16($drawable, $gc, ($x, $y),
556                        ($font OR [$delta, $string]), ...)
557
558         $x->ImageText8($drawable, $gc, ($x, $y), $string)
559
560         $x->ImageText16($drawable, $gc, ($x, $y), $string)
561
562         $x->CreateColormap($mid, $visual, $window, $alloc)
563
564         $x->FreeColormap($cmap)
565
566         $x->CopyColormapAndFree($mid, $src_cmap)
567
568         $x->InstallColormap($cmap)
569
570         $x->UninstallColormap($cmap)
571
572         $x->ListInstalledColormaps($window)
573         =>
574         @cmaps
575
576         $x->AllocColor($cmap, ($red, $green, $blue))
577         =>
578         ($pixel, ($red, $green, $blue))
579
580         $x->AllocNamedColor($cmap, $name)
581         =>
582         ($pixel, ($exact_red, $exact_green, $exact_blue),
583          ($visual_red, $visual_green, $visual_blue))
584
585         $x->AllocColorCells($cmap, $colors, $planes, $contiguous)
586         =>
587         ([@pixels], [@masks])
588
589         $x->AllocColorPlanes($cmap, $colors, ($reds, $greens, $blues),
590                              $contiguous)
591         =>
592         (($red_mask, $green_mask, $blue_mask), @pixels)
593
594         $x->FreeColors($cmap, $plane_mask, @pixels)
595
596         $x->StoreColors($cmap, [$pixel, $red, $green, $blue, $do_mask], ...)
597
598       The 1, 2, and 4 bits in $do_mask are do-red, do-green, and do-blue.
599       $do_mask can be omitted, defaulting to 7, the usual case -- change the
600       whole color.
601
602         $x->StoreNamedColor($cmap, $pixel, $name, $do_mask)
603
604       $do_mask has the same interpretation as above, but is mandatory.
605
606         $x->QueryColors($cmap, @pixels)
607         =>
608         ([$red, $green, $blue], ...)
609
610         $x->LookupColor($cmap, $name)
611         =>
612         (($exact_red, $exact_green, $exact_blue),
613          ($visual_red, $visual_green, $visual_blue))
614
615         $x->CreateCursor($cid, $source, $mask,
616                          ($fore_red, $fore_green, $fore_blue),
617                          ($back_red, $back_green, $back_blue),
618                          ($x, $y))
619
620         $x->CreateGlyphCursor($cid, $source_font, $mask_font,
621                               $source_char, $mask_char,
622                               ($fore_red, $fore_green, $fore_blue),
623                               ($back_red, $back_green, $back_blue))
624
625         $x->FreeCursor($cursor)
626
627         $x->RecolorCursor($cursor, ($fore_red, $fore_green, $fore_blue),
628                           ($back_red, $back_green, $back_blue))
629
630         $x->QueryBestSize($class, $drawable, $width, $height)
631         =>
632         ($width, $height)
633
634         $x->QueryExtension($name)
635         =>
636         ($major_opcode, $first_event, $first_error)
637
638       If the extension is not present, an empty list is returned.
639
640         $x->ListExtensions
641         =>
642         (@names)
643
644         $x->ChangeKeyboardMapping($first_keycode, $keysysms_per_keycode,
645                                   @keysyms)
646
647         $x->GetKeyboardMapping($first_keycode, $count)
648         =>
649         ($keysysms_per_keycode, [$keysym, ...], [$keysym, ...], ...)
650
651         $x->ChangeKeyboardControl('attribute' => $value, ...)
652
653         $x->GetKeyboardControl
654         =>
655         ('global_auto_repeat' => $global_auto_repeat, ...)
656
657         $x->Bell($percent)
658
659         $x->ChangePointerControl($do_acceleration, $do_threshold,
660                                  $acceleration_numerator,
661                                  $acceleration_denominator, $threshold)
662
663         $x->GetPointerControl
664         =>
665         ($acceleration_numerator, $acceleration_denominator, $threshold)
666
667         $x->SetScreenSaver($timeout, $interval, $prefer_blanking,
668                            $allow_exposures)
669
670         $x->GetScreenSaver
671         =>
672         ($timeout, $interval, $prefer_blanking, $allow_exposures)
673
674         $x->ChangeHosts($mode, $host_family, $host_address)
675
676         $x->ListHosts
677         =>
678         ($mode, [$family, $host], ...)
679
680         $x->SetAccessControl($mode)
681
682         $x->SetCloseDownMode($mode)
683
684         $x->KillClient($resource)
685
686         $x->RotateProperties($win, $delta, @props)
687
688         $x->ForceScreenSaver($mode)
689
690         $x->SetPointerMapping(@map)
691         =>
692         $status
693
694         $x->GetPointerMapping
695         =>
696         @map
697
698         $x->SetModifierMapping(@keycodes)
699         =>
700         $status
701
702         $x->GetModiferMapping
703         =>
704         @keycodes
705
706         $x->NoOperation($length)
707
708       $length specifies the length of the entire useless request, in four
709       byte units, and is optional.
710

EVENTS

712       To receive events, first set the 'event_mask' attribute on a window to
713       indicate what types of events you desire (see "pack_event_mask"). Then,
714       set the protocol object's 'event_handler' to a subroutine reference
715       that will handle the events. Alternatively, set 'event_handler' to
716       'queue', and retrieve events using dequeue_event() or next_event(). In
717       both cases, events are returned as a hash. For instance, a typical
718       MotionNotify event might look like this:
719
720         %event = ('name' => 'MotionNotify', 'sequence_number' => 12,
721                   'state' => 0, 'event' => 58720256, 'root' => 43,
722                   'child' => None, 'same_screen' => 1, 'time' => 966080746,
723                   'detail' => 'Normal', 'event_x' => 10, 'event_y' => 3,
724                   'code' => 6, 'root_x' => 319, 'root_y' => 235)
725
726       pack_event_mask
727
728         $mask = $x->pack_event_mask('ButtonPress', 'KeyPress', 'Exposure');
729
730       Make an event mask (suitable as the 'event_mask' of a window) from a
731       list of strings specifying event types.
732
733       unpack_event_mask
734
735         @event_types = $x->unpack_event_mask($mask);
736
737       The inverse operation; convert an event mask obtained from the server
738       into a list of names of event categories.
739
740       dequeue_event
741
742         %event = $x->dequeue_event;
743
744       If there is an event waiting in the queue, return it.
745
746       next_event
747
748         %event = $x->next_event;
749
750       Like Xlib's XNextEvent(), this function is equivalent to
751
752         $x->handle_input until %event = dequeue_event;
753
754       pack_event
755
756         $data = $x->pack_event(%event);
757
758       Given an event in hash form, pack it into a string. This is only useful
759       as an argument to SendEvent().
760
761       unpack_event
762
763         %event = $x->unpack_event($data);
764
765       The inverse operation; given the raw data for an event (32 bytes),
766       unpack it into hash form. Normally, this is done automatically.
767

EXTENSIONS

769       Protocol extensions add new requests, event types, and error types to
770       the protocol. Support for them is compartmentalized in modules in the
771       X11::Protocol::Ext:: hierarchy. For an example, see X11::Proto‐
772       col::Ext::SHAPE. You can tell if the module has loaded an extension by
773       looking at
774
775         $x->{'ext'}{$extension_name}
776
777       If the extension has been initialized, this value will be an array ref‐
778       erence, [$major_request_number, $first_event_number, $first_error_num‐
779       ber, $obj], where $obj is an object containing information private to
780       the extension.
781
782       init_extension
783
784         $x->init_extension($name);
785
786       Initialize an extension: query the server to find the extension's
787       request number, then load the corresponding module. Returns 0 if the
788       server does not support the named extension, or if no module to inter‐
789       face with it exists.
790
791       init_extensions
792
793         $x->init_extensions;
794
795       Initialize protocol extensions. This does a ListExtensions request,
796       then calls init_extension() for each extension that the server sup‐
797       ports.
798

WRITING EXTENSIONS

800       Internally, the X11::Protocol module is table driven. All an extension
801       has to do is to add new add entries to the protocol object's tables. An
802       extension module should "use X11::Protocol", and should define an new()
803       method
804
805         X11::Protocol::Ext::NAME
806           ->new($x, $request_num, $event_num, $error_num)
807
808       where $x is the protocol object and $request_num, $event_num and
809       $error_num are the values returned by QueryExtension().
810
811       The new() method should add new types of constant like
812
813         $x->{'ext_const'}{'ConstantType'} = ['Constant', 'Constant', ...]
814
815       and set up the corresponding name to number translation hashes like
816
817         $x->{'ext_const_num'}{'ConstantType'} =
818           {make_num_hash($x->{'ext_const'}{'ConstantType'})}
819
820       Event names go in
821
822         $x->{'ext_const'}{'Events'}[$event_number]
823
824       while specifications for event contents go in
825
826         $x->{'ext_event'}[$event_number]
827
828       each element of which is either "[\&unpack_sub, \&pack_sub]" or
829       "[$pack_format, $field, $field, ...]", where each $field is 'name',
830       "['name', 'const_type']", or "['name', ['special_name_for_zero', 'spe‐
831       cial_name_for_one']]", where 'special_name_for_one' is optional.
832
833       Finally,
834
835         $x->{'ext_request'}{$major_request_number}
836
837       should be an array of arrays, with each array either "[$name,
838       \&packit]" or "[$name, \&packit, \&unpackit]", and
839
840         $x->{'ext_request_num'}{$request_name}
841
842       should be initialized with "[$minor_num, $major_num]" for each request
843       the extension defines. For examples of code that does all of this, look
844       at X11::Protocol::Ext::SHAPE.
845
846       X11::Protocol exports several functions that might be useful in exten‐
847       sions (note that these are not methods).
848
849       padding
850
851         $p = padding $x;
852
853       Given an integer, compute the number need to round it up to a multiple
854       of 4.  For instance, padding(5) is 3.
855
856       pad
857
858         $p = pad $str;
859
860       Given a string, return the number of extra bytes needed to make a mul‐
861       tiple of 4. Equivalent to "padding(length($str))".
862
863       padded
864
865         $data = pack(padded($str), $str);
866
867       Return a format string, suitable for pack(), for a string padded to a
868       multiple of 4 bytes. For instance, "pack(padded('Hello'), 'Hello')"
869       gives "Hello\0\0\0".
870
871       hexi
872
873         $str = hexi $n;
874
875       Format a number in hexidecimal, and add a "0x" to the front.
876
877       make_num_hash
878
879         %hash = make_num_hash(['A', 'B', 'C']);
880
881       Given a reference to a list of strings, return a hash mapping the
882       strings onto numbers representing their position in the list, as used
883       by "$x->{'ext_const_num'}".
884

BUGS

886       This module is too big (~2500 lines), too slow (10 sec to load on a
887       slow machine), too inefficient (request args are copied several times),
888       and takes up too much memory (3000K for basicwin).
889
890       If you have more than 65535 replies outstanding at once, sequence num‐
891       bers can collide.
892
893       The protocol is too complex.
894

AUTHOR

896       Stephen McCamant <SMCCAM@cpan.org>.
897