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

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         $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
46       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
62   new_rsrc
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
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
85   handle_input
86         $x->handle_input;
87
88       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
95   atom_name
96         $name = $x->atom_name($atom);
97
98       Return the string corresponding to the atom $atom. This is similar to
99       the GetAtomName request, but caches the result for efficiency.
100
101   atom
102         $atom = $x->atom($name);
103
104       The inverse operation; Return the (numeric) atom corresponding to
105       $name.  This is similar to the InternAtom request, but caches the
106       result.
107
108   choose_screen
109         $x->choose_screen($screen_num);
110
111       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
115         $x->{'root'}
116
117       instead of
118
119         $x->{'screens'}[$screen_num]{'root'}
120

SYMBOLIC CONSTANTS

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
130   num
131         $num = $x->num($type, $str)
132
133       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
138   interp
139         $name = $x->interp($type, $num)
140
141       The inverse operation; given a number and string specifying its type,
142       return a string representing the constant.
143
144       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
148       Here is a list of available constant types:
149
150         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

SERVER INFORMATION

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
168         $x->{'release_number'}
169
170       or, for object oriented True Believers, using a method:
171
172         $x->release_number
173
174       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
177       Here is an example of what the object's information might look like:
178
179         '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

REQUESTS

238   request
239         $x->request('CreateWindow', ...);
240         $x->req('CreateWindow', ...);
241         $x->CreateWindow(...);
242
243       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
247   robust_req
248         $x->robust_req('CreateWindow', ...);
249
250       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
260   add_reply
261         $x->add_reply($sequence_num, \$var);
262
263       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
266   delete_reply
267         $x->delete_reply($sequence_num);
268
269       Delete the entry in 'replies' for the specified reply. (This should be
270       done after the reply is received).
271
272   send
273         $x->send('CreateWindow', ...);
274
275       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
279   unpack_reply
280         $x->unpack_reply('GetWindowAttributes', $data);
281
282       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
286       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
298         $x->CreateWindow($wid, $parent, $class, $depth, $visual, ($x, $y),
299                          $width, $height, $border_width,
300                          'attribute' => $value, ...)
301
302         $x->ChangeWindowAttributes($window, 'attribute' => $value, ...)
303
304         $x->GetWindowAttributes($window)
305         =>
306         ('backing_store' => $backing_store, ...)
307
308       This is an example of a return value that is meant to be assigned to a
309       hash.
310
311         $x->DestroyWindow($win)
312
313         $x->DestroySubwindows($win)
314
315         $x->ChangeSaveSet($window, $mode)
316
317         $x->ReparentWindow($win, $parent, ($x, $y))
318
319         $x->MapWindow($win)
320
321         $x->MapSubwindows($win)
322
323         $x->UnmapWindow($win)
324
325         $x->UnmapSubwindows($win)
326
327         $x->ConfigureWindow($win, 'attribute' => $value, ...)
328
329         $x->CirculateWindow($win, $direction)
330
331       Note that this request actually circulates the subwindows of $win, not
332       the window itself.
333
334         $x->GetGeometry($drawable)
335         =>
336         ('root' => $root, ...)
337
338         $x->QueryTree($win)
339         =>
340         ($root, $parent, @kids)
341
342         $x->InternAtom($name, $only_if_exists)
343         =>
344         $atom
345
346         $x->GetAtomName($atom)
347         =>
348         $name
349
350         $x->ChangeProperty($window, $property, $type, $format, $mode, $data)
351
352         $x->DeleteProperty($win, $atom)
353
354         $x->GetProperty($window, $property, $type, $offset, $length, $delete)
355         =>
356         ($value, $type, $format, $bytes_after)
357
358       Notice that the value comes first, so you can easily ignore the rest.
359
360         $x->ListProperties($window)
361         =>
362         (@atoms)
363
364         $x->SetSelectionOwner($selection, $owner, $time)
365
366         $x->GetSelectionOwner($selection)
367         =>
368         $owner
369
370         $x->ConvertSelection($selection, $target, $property, $requestor, $time)
371
372         $x->SendEvent($destination, $propagate, $event_mask, $event)
373
374       The $event argument should be the result of a pack_event() (see
375       "EVENTS")
376
377         $x->GrabPointer($grab_window, $owner_events, $event_mask,
378                         $pointer_mode, $keyboard_mode, $confine_to,
379                         $cursor, $time)
380         =>
381         $status
382
383         $x->UngrabPointer($time)
384
385         $x->GrabButton($modifiers, $button, $grab_window, $owner_events,
386                        $event_mask, $pointer_mode, $keyboard_mode,
387                        $confine_to, $cursor)
388
389         $x->UngrabButton($modifiers, $button, $grab_window)
390
391         $x->ChangeActivePointerGrab($event_mask, $cursor, $time)
392
393         $x->GrabKeyboard($grab_window, $owner_events, $pointer_mode,
394                          $keyboard_mode, $time)
395         =>
396         $status
397
398         $x->UngrabKeyboard($time)
399
400         $x->GrabKey($key, $modifiers, $grab_window, $owner_events,
401                     $pointer_mode, $keyboard_mode)
402
403         $x->UngrabKey($key, $modifiers, $grab_window)
404
405         $x->AllowEvents($mode, $time)
406
407         $x->GrabServer
408
409         $x->UngrabServer
410
411         $x->QueryPointer($window)
412         =>
413         ('root' => $root, ...)
414
415         $x->GetMotionEvents($start, $stop, $window)
416         =>
417         ([$time, ($x, $y)], [$time, ($x, $y)], ...)
418
419         $x->TranslateCoordinates($src_window, $dst_window, $src_x, $src_y)
420         =>
421         ($same_screen, $child, $dst_x, $dst_y)
422
423         $x->WarpPointer($src_window, $dst_window, $src_x, $src_y, $src_width,
424                         $src_height, $dst_x, $dst_y)
425
426         $x->SetInputFocus($focus, $revert_to, $time)
427
428         $x->GetInputFocus
429         =>
430         ($focus, $revert_to)
431
432         $x->QueryKeymap
433         =>
434         $keys
435
436       $keys is a bit vector, so you should use vec() to read it.
437
438         $x->OpenFont($fid, $name)
439
440         $x->CloseFont($font)
441
442         $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
457         $x->QueryTextExtents($font, $string)
458         =>
459         ('draw_direction' => $draw_direction, ...)
460
461         $x->ListFonts($pattern, $max_names)
462         =>
463         @names
464
465         $x->ListFontsWithInfo($pattern, $max_names)
466         =>
467         ({'name' => $name, ...}, {'name' => $name, ...}, ...)
468
469       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
477         $x->SetFontPath(@strings)
478
479         $x->GetFontPath
480         =>
481         @strings
482
483         $x->CreatePixmap($pixmap, $drawable, $depth, $width, $height)
484
485         $x->FreePixmap($pixmap)
486
487         $x->CreateGC($cid, $drawable, 'attribute' => $value, ...)
488
489         $x->ChangeGC($gc, 'attribute' => $value, ...)
490
491         $x->CopyGC($src, $dest, 'attribute', 'attribute', ...)
492
493         $x->SetDashes($gc, $dash_offset, (@dashes))
494
495         $x->SetClipRectangles($gc, ($clip_x_origin, $clip_y_origin),
496                               $ordering, [$x, $y, $width, $height], ...)
497
498         $x->ClearArea($window, ($x, $y), $width, $height, $exposures)
499
500         $x->CopyArea($src_drawable, $dst_drawable, $gc, ($src_x, $src_y),
501                      $width, $height, ($dst_x, $dst_y))
502
503         $x->CopyPlane($src_drawable, $dst_drawable, $gc, ($src_x, $src_y),
504                       $width, $height, ($dst_x, $dst_y), $bit_plane)
505
506         $x->PolyPoint($drawable, $gc, $coordinate_mode,
507                       ($x, $y), ($x, $y), ...)
508
509         $x->PolyLine($drawable, $gc, $coordinate_mode,
510                      ($x, $y), ($x, $y), ...)
511
512         $x->PolySegment($drawable, $gc, ($x, $y) => ($x, $y),
513                         ($x, $y) => ($x, $y), ...)
514
515         $x->PolyRectangle($drawable, $gc,
516                           [($x, $y), $width, $height], ...)
517
518         $x->PolyArc($drawable, $gc,
519                     [($x, $y), $width, $height, $angle1, $angle2], ...)
520
521         $x->FillPoly($drawable, $gc, $shape, $coordinate_mode,
522                      ($x, $y), ...)
523
524         $x->PolyFillRectangle($drawable, $gc,
525                               [($x, $y), $width, $height], ...)
526
527         $x->PolyFillArc($drawable, $gc,
528                         [($x, $y), $width, $height, $angle1, $angle2], ...)
529
530         $x->PutImage($drawable, $gc, $depth, $width, $height,
531                      ($dst_x, $dst_y), $left_pad, $format, $data)
532
533       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
537         $x->GetImage($drawable, ($x, $y), $width, $height, $plane_mask,
538                      $format)
539
540         $x->PolyText8($drawable, $gc, ($x, $y),
541                       ($font OR [$delta, $string]), ...)
542
543         $x->PolyText16($drawable, $gc, ($x, $y),
544                        ($font OR [$delta, $string]), ...)
545
546         $x->ImageText8($drawable, $gc, ($x, $y), $string)
547
548         $x->ImageText16($drawable, $gc, ($x, $y), $string)
549
550         $x->CreateColormap($mid, $visual, $window, $alloc)
551
552         $x->FreeColormap($cmap)
553
554         $x->CopyColormapAndFree($mid, $src_cmap)
555
556         $x->InstallColormap($cmap)
557
558         $x->UninstallColormap($cmap)
559
560         $x->ListInstalledColormaps($window)
561         =>
562         @cmaps
563
564         $x->AllocColor($cmap, ($red, $green, $blue))
565         =>
566         ($pixel, ($red, $green, $blue))
567
568         $x->AllocNamedColor($cmap, $name)
569         =>
570         ($pixel, ($exact_red, $exact_green, $exact_blue),
571          ($visual_red, $visual_green, $visual_blue))
572
573         $x->AllocColorCells($cmap, $colors, $planes, $contiguous)
574         =>
575         ([@pixels], [@masks])
576
577         $x->AllocColorPlanes($cmap, $colors, ($reds, $greens, $blues),
578                              $contiguous)
579         =>
580         (($red_mask, $green_mask, $blue_mask), @pixels)
581
582         $x->FreeColors($cmap, $plane_mask, @pixels)
583
584         $x->StoreColors($cmap, [$pixel, $red, $green, $blue, $do_mask], ...)
585
586       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
590         $x->StoreNamedColor($cmap, $pixel, $name, $do_mask)
591
592       $do_mask has the same interpretation as above, but is mandatory.
593
594         $x->QueryColors($cmap, @pixels)
595         =>
596         ([$red, $green, $blue], ...)
597
598         $x->LookupColor($cmap, $name)
599         =>
600         (($exact_red, $exact_green, $exact_blue),
601          ($visual_red, $visual_green, $visual_blue))
602
603         $x->CreateCursor($cid, $source, $mask,
604                          ($fore_red, $fore_green, $fore_blue),
605                          ($back_red, $back_green, $back_blue),
606                          ($x, $y))
607
608         $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
613         $x->FreeCursor($cursor)
614
615         $x->RecolorCursor($cursor, ($fore_red, $fore_green, $fore_blue),
616                           ($back_red, $back_green, $back_blue))
617
618         $x->QueryBestSize($class, $drawable, $width, $height)
619         =>
620         ($width, $height)
621
622         $x->QueryExtension($name)
623         =>
624         ($major_opcode, $first_event, $first_error)
625
626       If the extension is not present, an empty list is returned.
627
628         $x->ListExtensions
629         =>
630         (@names)
631
632         $x->ChangeKeyboardMapping($first_keycode, $keysysms_per_keycode,
633                                   @keysyms)
634
635         $x->GetKeyboardMapping($first_keycode, $count)
636         =>
637         ($keysysms_per_keycode, [$keysym, ...], [$keysym, ...], ...)
638
639         $x->ChangeKeyboardControl('attribute' => $value, ...)
640
641         $x->GetKeyboardControl
642         =>
643         ('global_auto_repeat' => $global_auto_repeat, ...)
644
645         $x->Bell($percent)
646
647         $x->ChangePointerControl($do_acceleration, $do_threshold,
648                                  $acceleration_numerator,
649                                  $acceleration_denominator, $threshold)
650
651         $x->GetPointerControl
652         =>
653         ($acceleration_numerator, $acceleration_denominator, $threshold)
654
655         $x->SetScreenSaver($timeout, $interval, $prefer_blanking,
656                            $allow_exposures)
657
658         $x->GetScreenSaver
659         =>
660         ($timeout, $interval, $prefer_blanking, $allow_exposures)
661
662         $x->ChangeHosts($mode, $host_family, $host_address)
663
664         $x->ListHosts
665         =>
666         ($mode, [$family, $host], ...)
667
668         $x->SetAccessControl($mode)
669
670         $x->SetCloseDownMode($mode)
671
672         $x->KillClient($resource)
673
674         $x->RotateProperties($win, $delta, @props)
675
676         $x->ForceScreenSaver($mode)
677
678         $x->SetPointerMapping(@map)
679         =>
680         $status
681
682         $x->GetPointerMapping
683         =>
684         @map
685
686         $x->SetModifierMapping(@keycodes)
687         =>
688         $status
689
690         $x->GetModiferMapping
691         =>
692         @keycodes
693
694         $x->NoOperation($length)
695
696       $length specifies the length of the entire useless request, in four
697       byte units, and is optional.
698

EVENTS

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
708         %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
714   pack_event_mask
715         $mask = $x->pack_event_mask('ButtonPress', 'KeyPress', 'Exposure');
716
717       Make an event mask (suitable as the 'event_mask' of a window) from a
718       list of strings specifying event types.
719
720   unpack_event_mask
721         @event_types = $x->unpack_event_mask($mask);
722
723       The inverse operation; convert an event mask obtained from the server
724       into a list of names of event categories.
725
726   dequeue_event
727         %event = $x->dequeue_event;
728
729       If there is an event waiting in the queue, return it.
730
731   next_event
732         %event = $x->next_event;
733
734       Like Xlib's XNextEvent(), this function is equivalent to
735
736         $x->handle_input until %event = dequeue_event;
737
738   pack_event
739         $data = $x->pack_event(%event);
740
741       Given an event in hash form, pack it into a string. This is only useful
742       as an argument to SendEvent().
743
744   unpack_event
745         %event = $x->unpack_event($data);
746
747       The inverse operation; given the raw data for an event (32 bytes),
748       unpack it into hash form. Normally, this is done automatically.
749

EXTENSIONS

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
757         $x->{'ext'}{$extension_name}
758
759       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
764   init_extension
765         $x->init_extension($name);
766
767       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
772   init_extensions
773         $x->init_extensions;
774
775       Initialize protocol extensions. This does a ListExtensions request,
776       then calls init_extension() for each extension that the server
777       supports.
778

WRITING EXTENSIONS

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
785         X11::Protocol::Ext::NAME
786           ->new($x, $request_num, $event_num, $error_num)
787
788       where $x is the protocol object and $request_num, $event_num and
789       $error_num are the values returned by QueryExtension().
790
791       The new() method should add new types of constant like
792
793         $x->{'ext_const'}{'ConstantType'} = ['Constant', 'Constant', ...]
794
795       and set up the corresponding name to number translation hashes like
796
797         $x->{'ext_const_num'}{'ConstantType'} =
798           {make_num_hash($x->{'ext_const'}{'ConstantType'})}
799
800       Event names go in
801
802         $x->{'ext_const'}{'Events'}[$event_number]
803
804       while specifications for event contents go in
805
806         $x->{'ext_event'}[$event_number]
807
808       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
813       Finally,
814
815         $x->{'ext_request'}{$major_request_number}
816
817       should be an array of arrays, with each array either "[$name,
818       \&packit]" or "[$name, \&packit, \&unpackit]", and
819
820         $x->{'ext_request_num'}{$request_name}
821
822       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
826       X11::Protocol exports several functions that might be useful in
827       extensions (note that these are not methods).
828
829   padding
830         $p = padding $x;
831
832       Given an integer, compute the number need to round it up to a multiple
833       of 4.  For instance, padding(5) is 3.
834
835   pad
836         $p = pad $str;
837
838       Given a string, return the number of extra bytes needed to make a
839       multiple of 4. Equivalent to "padding(length($str))".
840
841   padded
842         $data = pack(padded($str), $str);
843
844       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
848   hexi
849         $str = hexi $n;
850
851       Format a number in hexidecimal, and add a "0x" to the front.
852
853   make_num_hash
854         %hash = make_num_hash(['A', 'B', 'C']);
855
856       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

BUGS

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
865       If you have more than 65535 replies outstanding at once, sequence
866       numbers can collide.
867
868       The protocol is too complex.
869

AUTHOR

871       Stephen McCamant <SMCCAM@cpan.org>.
872

SEE ALSO

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.
879
880
881
882perl v5.38.0                      2023-07-21                       Protocol(3)
Impressum