home *** CD-ROM | disk | FTP | other *** search
/ Chip 2000 May / Chip_2000-05_cd1.bin / zkuste / Perl / ActivePerl-5.6.0.613.msi / 䆊䌷䈹䈙䏵-䞅䞆䞀㡆䞃䄦䠥 / _de99f2f79b58edfdc9d67de10e10fa02 < prev    next >
Text File  |  2000-03-23  |  37KB  |  934 lines
  1.  
  2. <HTML>
  3. <HEAD>
  4. <TITLE>X11::Protocol - Perl module for the X Window System Protocol, version 11</TITLE>
  5. <LINK REL="stylesheet" HREF="../../../Active.css" TYPE="text/css">
  6. <LINK REV="made" HREF="mailto:">
  7. </HEAD>
  8.  
  9. <BODY>
  10. <TABLE BORDER=0 CELLPADDING=0 CELLSPACING=0 WIDTH=100%>
  11. <TR><TD CLASS=block VALIGN=MIDDLE WIDTH=100% BGCOLOR="#cccccc">
  12. <STRONG><P CLASS=block> X11::Protocol - Perl module for the X Window System Protocol, version 11</P></STRONG>
  13. </TD></TR>
  14. </TABLE>
  15.  
  16. <A NAME="__index__"></A>
  17. <!-- INDEX BEGIN -->
  18.  
  19. <UL>
  20.  
  21.     <LI><A HREF="#name">NAME</A></LI><LI><A HREF="#supportedplatforms">SUPPORTED PLATFORMS</A></LI>
  22.  
  23.     <LI><A HREF="#synopsis">SYNOPSIS</A></LI>
  24.     <LI><A HREF="#description">DESCRIPTION</A></LI>
  25.     <LI><A HREF="#disclaimer">DISCLAIMER</A></LI>
  26.     <LI><A HREF="#basic methods">BASIC METHODS</A></LI>
  27.     <UL>
  28.  
  29.         <LI><A HREF="#new">new</A></LI>
  30.         <LI><A HREF="#new_rsrc">new_rsrc</A></LI>
  31.         <LI><A HREF="#handle_input">handle_input</A></LI>
  32.         <LI><A HREF="#atom_name">atom_name</A></LI>
  33.         <LI><A HREF="#atom">atom</A></LI>
  34.         <LI><A HREF="#choose_screen">choose_screen</A></LI>
  35.     </UL>
  36.  
  37.     <LI><A HREF="#symbolic constants">SYMBOLIC CONSTANTS</A></LI>
  38.     <UL>
  39.  
  40.         <LI><A HREF="#num">num</A></LI>
  41.         <LI><A HREF="#interp">interp</A></LI>
  42.     </UL>
  43.  
  44.     <LI><A HREF="#server information">SERVER INFORMATION</A></LI>
  45.     <LI><A HREF="#requests">REQUESTS</A></LI>
  46.     <UL>
  47.  
  48.         <LI><A HREF="#request">request</A></LI>
  49.         <LI><A HREF="#add_reply">add_reply</A></LI>
  50.         <LI><A HREF="#delete_reply">delete_reply</A></LI>
  51.         <LI><A HREF="#send">send</A></LI>
  52.         <LI><A HREF="#unpack_reply">unpack_reply</A></LI>
  53.     </UL>
  54.  
  55.     <LI><A HREF="#events">EVENTS</A></LI>
  56.     <UL>
  57.  
  58.         <LI><A HREF="#pack_event_mask">pack_event_mask</A></LI>
  59.         <LI><A HREF="#unpack_event_mask">unpack_event_mask</A></LI>
  60.         <LI><A HREF="#dequeue_event">dequeue_event</A></LI>
  61.         <LI><A HREF="#next_event">next_event</A></LI>
  62.         <LI><A HREF="#pack_event">pack_event</A></LI>
  63.         <LI><A HREF="#unpack_event">unpack_event</A></LI>
  64.     </UL>
  65.  
  66.     <LI><A HREF="#extensions">EXTENSIONS</A></LI>
  67.     <UL>
  68.  
  69.         <LI><A HREF="#init_extension">init_extension</A></LI>
  70.         <LI><A HREF="#init_extensions">init_extensions</A></LI>
  71.     </UL>
  72.  
  73.     <LI><A HREF="#writing extensions">WRITING EXTENSIONS</A></LI>
  74.     <UL>
  75.  
  76.         <LI><A HREF="#padding">padding</A></LI>
  77.         <LI><A HREF="#pad">pad</A></LI>
  78.         <LI><A HREF="#padded">padded</A></LI>
  79.         <LI><A HREF="#hexi">hexi</A></LI>
  80.         <LI><A HREF="#make_num_hash">make_num_hash</A></LI>
  81.     </UL>
  82.  
  83.     <LI><A HREF="#bugs">BUGS</A></LI>
  84.     <LI><A HREF="#author">AUTHOR</A></LI>
  85.     <LI><A HREF="#see also">SEE ALSO</A></LI>
  86. </UL>
  87. <!-- INDEX END -->
  88.  
  89. <HR>
  90. <P>
  91. <H1><A NAME="name">NAME</A></H1>
  92. <P>X11::Protocol - Perl module for the X Window System Protocol, version 11</P>
  93. <P>
  94. <HR>
  95. <H1><A NAME="supportedplatforms">SUPPORTED PLATFORMS</A></H1>
  96. <UL>
  97. <LI>Linux</LI>
  98. <LI>Solaris</LI>
  99. </UL>
  100. <HR>
  101. <H1><A NAME="synopsis">SYNOPSIS</A></H1>
  102. <PRE>
  103.   use X11::Protocol;
  104.   $x = X11::Protocol->new();
  105.   $win = $x->new_rsrc;
  106.   $x->CreateWindow($win, $x->root, 'InputOutput',
  107.                    $x->root_depth, 'CopyFromParent',
  108.                    ($x_coord, $y_coord), $width,
  109.                    $height, $border_w);  
  110.   ...</PRE>
  111. <P>
  112. <HR>
  113. <H1><A NAME="description">DESCRIPTION</A></H1>
  114. <P>X11::Protocol is a client-side interface to the X11 Protocol (see <CODE>X(1)</CODE> for
  115. information about X11), allowing perl programs to display windows and
  116. graphics on X11 servers.</P>
  117. <P>A full description of the protocol is beyond the scope of this documentation;
  118. for complete information, see the <EM>X Window System Protocol, X Version 11</EM>,
  119. available as Postscript or *roff source from <CODE>ftp://ftp.x.org</CODE>, or
  120. <EM>Volume 0: X Protocol Reference Manual</EM> of O'Reilly & Associates's series of
  121. books about X (ISBN 1-56592-083-X, <CODE>http://www.oreilly.com</CODE>), which contains
  122. most of the same information.</P>
  123. <P>
  124. <HR>
  125. <H1><A NAME="disclaimer">DISCLAIMER</A></H1>
  126. <P>``The protocol contains many management mechanisms that are
  127. not intended for normal applications.  Not all mechanisms
  128. are needed to build a particular user interface.  It is
  129. important to keep in mind that the protocol is intended to
  130. provide mechanism, not policy.'' -- Robert W. Scheifler</P>
  131. <P>
  132. <HR>
  133. <H1><A NAME="basic methods">BASIC METHODS</A></H1>
  134. <P>
  135. <H2><A NAME="new">new</A></H2>
  136. <PRE>
  137.   $x = X11::Protocol->new();
  138.   $x = X11::Protocol->new($display_name);
  139.   $x = X11::Protocol->new($connection);
  140.   $x = X11::Protocol->new($display_name, [$auth_type, $auth_data]);
  141.   $x = X11::Protocol->new($connection, [$auth_type, $auth_data]);</PRE>
  142. <P>Open a connection to a server. $display_name should be an X display
  143. name, of the form 'host:display_num.screen_num'; if no arguments are
  144. supplied, the contents of the DISPLAY environment variable are
  145. used. Alternatively, a pre-opened connection, of one of the
  146. X11::Protocol::Connection classes (see
  147. <A HREF="../../../site/lib/X11/Protocol/Connection.html">the X11::Protocol::Connection manpage</A>,
  148. <A HREF="../../../site/lib/X11/Protocol/Connection/FileHandle.html">the X11::Protocol::Connection::FileHandle manpage</A>,
  149. <A HREF="../../../site/lib/X11/Protocol/Connection/Socket.html">the X11::Protocol::Connection::Socket manpage</A>,
  150. <A HREF="../../../site/lib/X11/Protocol/Connection/UNIXFH.html">the X11::Protocol::Connection::UNIXFH manpage</A>,
  151. <A HREF="../../../site/lib/X11/Protocol/Connection/INETFH.html">the X11::Protocol::Connection::INETFH manpage</A>,
  152. <A HREF="../../../site/lib/X11/Protocol/Connection/UNIXSocket.html">the X11::Protocol::Connection::UNIXSocket manpage</A>,
  153. <A HREF="../../../site/lib/X11/Protocol/Connection/INETSocket.html">the X11::Protocol::Connection::INETSocket manpage</A>) can be given. The
  154. authorization data is obtained using X11::Auth or the second
  155. argument. If the display is specified by $display_name, rather than
  156. $connection, a <CODE>choose_screen()</CODE> is also performed, defaulting to screen
  157. 0 if the '.screen_num' of the display name is not present.  Returns
  158. the new protocol object.</P>
  159. <P>
  160. <H2><A NAME="new_rsrc">new_rsrc</A></H2>
  161. <PRE>
  162.   $x->new_rsrc;</PRE>
  163. <P>Returns a new resource identifier. A unique resource ID is required for every
  164. object that the server creates on behalf of the client: windows, fonts,
  165. cursors, etc. (IDs are chosen by the client instead of the server for
  166. efficiency -- the client doesn't have to wait for the server to acknowledge
  167. the creation before starting to use the object).</P>
  168. <P>
  169. <H2><A NAME="handle_input">handle_input</A></H2>
  170. <PRE>
  171.   $x->handle_input;</PRE>
  172. <P>Get one chunk of information from the server, and do something with it. If it's
  173. an error, handle it using the protocol object's handler ('error_handler'
  174. -- default is kill the program with an explanatory message). If it's an event,
  175. pass it to the chosen event handler, or put it in a queue if the handler is
  176. 'queue'. If it's a reply to a request, save using the object's 'replies' hash
  177. for further processing.</P>
  178. <P>
  179. <H2><A NAME="atom_name">atom_name</A></H2>
  180. <PRE>
  181.   $name = $x->atom_name($atom);</PRE>
  182. <P>Return the string corresponding to the atom $atom. This is similar to the
  183. GetAtomName request, but caches the result for efficiency.</P>
  184. <P>
  185. <H2><A NAME="atom">atom</A></H2>
  186. <PRE>
  187.   $atom = $x->atom($name);</PRE>
  188. <P>The inverse operation; Return the (numeric) atom correspoding to $name.
  189. This is similar to the InternAtom request, but caches the result.</P>
  190. <P>
  191. <H2><A NAME="choose_screen">choose_screen</A></H2>
  192. <PRE>
  193.   $x->choose_screen($screen_num);</PRE>
  194. <P>Indicate that you prefer to use a particular screen of the display. Per-screen
  195. information, such as 'root', 'width_in_pixels', and 'white_pixel' will be
  196. made avaliable as</P>
  197. <PRE>
  198.   $x->{'root'}</PRE>
  199. <P>instead of</P>
  200. <PRE>
  201.   $x->{'screens'}[$screen_num]{'root'}</PRE>
  202. <P>
  203. <HR>
  204. <H1><A NAME="symbolic constants">SYMBOLIC CONSTANTS</A></H1>
  205. <P>Generally, symbolic constants used by the protocol, like 'CopyFromParent'
  206. or 'PieSlice' are passed to methods as strings, and
  207. converted into numbers by the module.  Their names are the same as
  208. those in the protocol specification, including capitalization, but
  209. with hyphens ('-') changed to underscores ('_') to look more
  210. perl-ish. If you want to do the conversion yourself for some reason,
  211. the following methods are avaliable:</P>
  212. <P>
  213. <H2><A NAME="num">num</A></H2>
  214. <PRE>
  215.   $num = $x->num($type, $str)</PRE>
  216. <P>Given a string representing a constant and a string specifying what
  217. type of constant it is, return the corresponding number. $type should
  218. be a name like 'VisualClass' or 'GCLineStyle'. If the name is not
  219. recognized, it is returned intact.</P>
  220. <P>
  221. <H2><A NAME="interp">interp</A></H2>
  222. <PRE>
  223.   $name = $x->interp($type, $num)</PRE>
  224. <P>The inverse operation; given a number and string specifying its type, return
  225. a string representing the constant.</P>
  226. <P>You can disable <CODE>interp()</CODE> and the module's internal interpretation of
  227. numbers by setting $x->{'do_interp'} to zero. Of course, this isn't
  228. very useful, unless you have you own definitions for all the
  229. constants.</P>
  230. <P>Here is a list of available constant types:</P>
  231. <PRE>
  232.   AccessMode, AllowEventsMode, AutoRepeatMode, BackingStore,
  233.   BitGravity, Bool, ChangePropertyMode, CirculateDirection,
  234.   CirculatePlace, Class, ClipRectangleOrdering, CloseDownMode,
  235.   ColormapNotifyState, CoordinateMode, CrossingNotifyDetail,
  236.   CrossingNotifyMode, DeviceEvent, DrawDirection, Error, EventMask,
  237.   Events, FocusDetail, FocusMode, GCArcMode, GCCapStyle, GCFillRule,
  238.   GCFillStyle, GCFunction, GCJoinStyle, GCLineStyle, GCSubwindowMode,
  239.   GrabStatus, HostChangeMode, HostFamily, ImageFormat,
  240.   InputFocusRevertTo, KeyMask, LedMode, MapState, MappingChangeStatus,
  241.   MappingNotifyRequest, PointerEvent, PolyShape, PropertyNotifyState,
  242.   Request, ScreenSaver, ScreenSaverAction, Significance, SizeClass,
  243.   StackMode, SyncMode, VisibilityState, VisualClass, WinGravity</PRE>
  244. <P>
  245. <HR>
  246. <H1><A NAME="server information">SERVER INFORMATION</A></H1>
  247. <P>At connection time, the server sends a large amount of information about
  248. itself to the client. This information is stored in the protocol object
  249. for future reference. It can be read directly, like</P>
  250. <PRE>
  251.   $x->{'release_number'}</PRE>
  252. <P>or, for object oriented True Believers, using a method:</P>
  253. <PRE>
  254.   $x->release_number</PRE>
  255. <P>The method method also has a one argument form for setting variables, but
  256. it isn't really useful for some of the more complex structures.</P>
  257. <P>Here is an example of what the object's information might look like:</P>
  258. <PRE>
  259.   'connection' => X11::Connection::UNIXSocket(0x814526fd),
  260.   'byte_order' => 'l',
  261.   'protocol_major_version' => 11,
  262.   'protocol_minor_version' => 0,
  263.   'authorization_protocol_name' => 'MIT-MAGIC-COOKIE-1',
  264.   'release_number' => 3110,
  265.   'resource_id_base' => 0x1c000002,
  266.   'motion_buffer_size' => 0,
  267.   'maximum_request_length' => 65535, # units of 4 bytes
  268.   'image_byte_order' => 'LeastSiginificant',
  269.   'bitmap_bit_order' => 'LeastSiginificant',
  270.   'bitmap_scanline_unit' => 32,
  271.   'bitmap_scanline_pad' => 32,
  272.   'min_keycode' => 8,
  273.   'max_keycode' => 134,
  274.   'vendor' => 'The XFree86 Project, Inc',
  275.   'pixmap_formats' => {1 => {'bits_per_pixel' => 1,
  276.                              'scanline_pad' => 32},
  277.                        8 => {'bits_per_pixel' => 8,
  278.                              'scanline_pad' => 32}},
  279.   'screens' => [{'root' => 43, 'width_in_pixels' => 800,
  280.                  'height_in_pixels' => 600,
  281.                  'width_in_millimeters' => 271,
  282.                  'height_in_millmerters' => 203,
  283.                  'root_depth' => 8,
  284.                  'root_visual' => 34,
  285.                  'default_colormap' => 33,
  286.                  'white_pixel' => 0, 'black_pixel' => 1,
  287.                  'min_installed_maps' => 1,
  288.                  'max_installed_maps' => 1,
  289.                  'backing_stores' => 'Always',
  290.                  'save_unders' => 1,
  291.                  'current_input_masks' => 0x58003d,
  292.                  'allowed_depths' =>
  293.                     [{'depth' => 1, 'visuals' => []},
  294.                      {'depth' => 8, 'visuals' => [
  295.                         {'visual_id' => 34, 'blue_mask' => 0,
  296.                          'green_mask' => 0, 'red_mask' => 0, 
  297.                          'class' => 'PseudoColor',
  298.                          'bits_per_rgb_value' => 6,
  299.                          'colormap_entries' => 256},
  300.                         {'visual_id' => 35, 'blue_mask' => 0xc0,
  301.                          'green_mask' => 0x38, 'red_mask' => 0x7, 
  302.                          'class' => 'DirectColor',
  303.                          'bits_per_rgb_value' => 6,
  304.                          'colormap_entries' => 8}, ...]}]],
  305.   'visuals' => {34 => {'depth' => 8, 'class' => 'PseudoColor',
  306.                        'red_mask' => 0, 'green_mask' => 0,
  307.                        'blue_mask'=> 0, 'bits_per_rgb_value' => 6,
  308.                        'colormap_entries' => 256},
  309.                 35 => {'depth' => 8, 'class' => 'DirectColor',
  310.                        'red_mask' => 0x7, 'green_mask' => 0x38,
  311.                        'blue_mask'=> 0xc0, 'bits_per_rgb_value' => 6,
  312.                        'colormap_entries' => 8}, ...}
  313.   'error_handler' => &\X11::Protocol::default_error_handler,
  314.   'event_handler' => sub {},
  315.   'do_interp' => 1</PRE>
  316. <P>
  317. <HR>
  318. <H1><A NAME="requests">REQUESTS</A></H1>
  319. <P>
  320. <H2><A NAME="request">request</A></H2>
  321. <PRE>
  322.   $x->request('CreateWindow', ...);
  323.   $x->req('CreateWindow', ...);
  324.   $x->CreateWindow(...);</PRE>
  325. <P>Send a protocol request to the server, and get the reply. For names of and 
  326. information about individual requests, see below and/or
  327. the protocol reference manual.</P>
  328. <P>
  329. <H2><A NAME="add_reply">add_reply</A></H2>
  330. <PRE>
  331.   $x->add_reply($sequence_num, \$var);</PRE>
  332. <P>Add a stub for an expected reply to the object's 'replies' hash. When a reply
  333. numbered $sequence_num comes, it will be stored in $var.</P>
  334. <P>
  335. <H2><A NAME="delete_reply">delete_reply</A></H2>
  336. <PRE>
  337.   $x->delete_reply($sequence_num);</PRE>
  338. <P>Delete the entry in 'replies' for the specified reply. (This should be done
  339. after the reply is recieved).</P>
  340. <P>
  341. <H2><A NAME="send">send</A></H2>
  342. <PRE>
  343.   $x->send('CreateWindow', ...);</PRE>
  344. <P>Send a request, but do not wait for a reply. You must handle the reply, if any,
  345. yourself, using add_reply(), handle_input(), delete_reply(), and
  346. unpack_reply(), generally in that order.</P>
  347. <P>
  348. <H2><A NAME="unpack_reply">unpack_reply</A></H2>
  349. <PRE>
  350.   $x->unpack_reply('GetWindowAttributes', $data);</PRE>
  351. <P>Interpret the raw reply data $data, according to the reply format for the named
  352. request. Returns data in the same format as <CODE>request($request_name, ...)</CODE>.</P>
  353. <P>This section includes only a short calling summary for each request; for
  354. full descriptions, see the protocol standard. Argument order is usually the
  355. same as listed in the spec, but you generally don't have to pass lengths of
  356. strings or arrays, since perl keeps track. Symbolic constants are generally
  357. passed as strings. Most replies are returned as lists, but when there are
  358. many values, a hash is used. Lists usually come last; when there is more than
  359. one, each is passed by reference. In lists of multi-part structures, each
  360. element is a list ref. Parenthesis are inserted in arg lists for clarity,
  361. but are optional. Requests are listed in order by major opcode, so related
  362. requests are usually close together. Replies follow the '=>'.</P>
  363. <PRE>
  364.   $x->CreateWindow($wid, $parent, $class, $depth, $visual, ($x, $y),
  365.                    $width, $height, $border_width,
  366.                    'attribute' => $value, ...)</PRE>
  367. <PRE>
  368.   $x->ChangeWindowAttributes($window, 'attribute' => $value, ...)</PRE>
  369. <PRE>
  370.   $x->GetWindowAttributes($window)
  371.   =>
  372.   ('backing_store' => $backing_store, ...)</PRE>
  373. <P>This is an example of a return value that is meant to be assigned to a hash.</P>
  374. <PRE>
  375.   $x->DestroyWindow($win)</PRE>
  376. <PRE>
  377.   $x->DestroySubwindows($win)</PRE>
  378. <PRE>
  379.   $x->ChangeSaveSet($window, $mode)</PRE>
  380. <PRE>
  381.   $x->ReparentWindow($win, $parent, ($x, $y))</PRE>
  382. <PRE>
  383.   $x->MapWindow($win)</PRE>
  384. <PRE>
  385.   $x->MapSubwindows($win)</PRE>
  386. <PRE>
  387.   $x->UnmapWindow($win)</PRE>
  388. <PRE>
  389.   $x->UnmapSubwindows($win)</PRE>
  390. <PRE>
  391.   $x->ConfigureWindow($win, 'attribute' => $value, ...)</PRE>
  392. <PRE>
  393.   $x->CirculateWindow($win, $direction)</PRE>
  394. <P>Note that this request actually circulates the subwindows of $win,
  395. not the window itself.</P>
  396. <PRE>
  397.   $x->GetGeometry($drawable)
  398.   =>
  399.   ('root' => $root, ...)</PRE>
  400. <PRE>
  401.   $x->QueryTree($win)
  402.   =>
  403.   ($root, $parent, @kids)</PRE>
  404. <PRE>
  405.   $x->InternAtom($name, $only_if_exists)
  406.   =>
  407.   $atom</PRE>
  408. <PRE>
  409.   $x->GetAtomName($atom)
  410.   =>
  411.   $name</PRE>
  412. <PRE>
  413.   $x->ChangeProperty($window, $property, $type, $format, $mode, $data)</PRE>
  414. <PRE>
  415.   $x->DeleteProperty($win, $atom)</PRE>
  416. <PRE>
  417.   $x->GetProperty($window, $property, $type, $offset, $length, $delete)
  418.   =>
  419.   ($value, $type, $format, $bytes_after)</PRE>
  420. <P>Notice that the value comes first, so you can easily ignore the rest.</P>
  421. <PRE>
  422.   $x->ListProperties($window)
  423.   =>
  424.   (@atoms)</PRE>
  425. <PRE>
  426.   $x->SetSelectionOwner($selection, $owner, $time)</PRE>
  427. <PRE>
  428.   $x->GetSelectionOwner($selection)
  429.   =>
  430.   $owner</PRE>
  431. <PRE>
  432.   $x->ConvertSelection($selection, $target, $property, $requestor, $time)</PRE>
  433. <PRE>
  434.   $x->SendEvent($destination, $propagate, $event_mask, $event)</PRE>
  435. <P>The $event argument should be the result of a <CODE>pack_event()</CODE> (see <A HREF="#events">EVENTS</A>)</P>
  436. <PRE>
  437.   $x->GrabPointer($grab_window, $owner_events, $event_mask,
  438.                   $pointer_mode, $keyboard_mode, $confine_to,
  439.                   $cursor, $time)
  440.   =>
  441.   $status</PRE>
  442. <PRE>
  443.   $x->UngrabPointer($time)</PRE>
  444. <PRE>
  445.   $x->GrabButton($modifiers, $button, $grab_window, $owner_events,
  446.                  $event_mask, $pointer_mode, $keyboard_mode,
  447.                  $confine_to, $cursor)</PRE>
  448. <PRE>
  449.   $x->UngrabButton($modifiers, $button, $grab_window)</PRE>
  450. <PRE>
  451.   $x->ChangeActivePointerGrab($event_mask, $cursor, $time)</PRE>
  452. <PRE>
  453.   $x->GrabKeyboard($grab_window, $owner_events, $pointer_mode,
  454.                    $keyboard_mode, $time)
  455.   =>
  456.   $status</PRE>
  457. <PRE>
  458.   $x->UngrabKeyboard($time)</PRE>
  459. <PRE>
  460.   $x->GrabKey($key, $modifiers, $grab_window, $owner_events,
  461.               $pointer_mode, $keyboard_mode)</PRE>
  462. <PRE>
  463.   $x->UngrabKey($key, $modifiers, $grab_window)</PRE>
  464. <PRE>
  465.   $x->AllowEvents($mode, $time)</PRE>
  466. <PRE>
  467.   $x->GrabServer</PRE>
  468. <PRE>
  469.   $x->UngrabServer</PRE>
  470. <PRE>
  471.   $x->QueryPointer($window)
  472.   =>
  473.   ('root' => $root, ...)</PRE>
  474. <PRE>
  475.   $x->GetMotionEvents($start, $stop, $window)
  476.   =>
  477.   ([$time, ($x, $y)], [$time, ($x, $y)], ...)</PRE>
  478. <PRE>
  479.   $x->TranslateCoordinates($src_window, $dst_window, $src_x, $src_y)
  480.   =>
  481.   ($same_screen, $child, $dst_x, $dst_y)</PRE>
  482. <PRE>
  483.   $x->WarpPointer($src_window, $dst_window, $src_x, $src_y, $src_width,
  484.                   $src_height, $dst_x, $dst_y)</PRE>
  485. <PRE>
  486.   $x->SetInputFocus($focus, $revert_to, $time)</PRE>
  487. <PRE>
  488.   $x->GetInputFocus
  489.   =>
  490.   ($focus, $revert_to)</PRE>
  491. <PRE>
  492.   $x->QueryKeymap
  493.   =>
  494.   $keys</PRE>
  495. <P>$keys is a bit vector, so you should use <A HREF="../../../lib/Pod/perlfunc.html#item_vec"><CODE>vec()</CODE></A> to read it.</P>
  496. <PRE>
  497.   $x->OpenFont($fid, $name)</PRE>
  498. <PRE>
  499.   $x->CloseFont($font)</PRE>
  500. <PRE>
  501.   $x->QueryFont($font)
  502.   =>
  503.   ('min_char_or_byte2' => $min_char_or_byte2,
  504.    ..., 
  505.    'min_bounds' =>
  506.    [$left_side_bearing, $right_side_bearing, $character_width, $ascent,
  507.     $descent, $attributes],
  508.    ...,
  509.    'char_infos' =>
  510.    [[$left_side_bearing, $right_side_bearing, $character_width, $ascent,
  511.      $descent, $attributes], 
  512.     ...], 
  513.    'properties' => {$prop => $value, ...}
  514.    )</PRE>
  515. <PRE>
  516.   $x->QueryTextExtents($font, $string)
  517.   =>
  518.   ('draw_direction' => $draw_direction, ...)</PRE>
  519. <PRE>
  520.   $x->ListFonts($pattern, $max_names)
  521.   =>
  522.   @names</PRE>
  523. <PRE>
  524.   $x->ListFontsWithInfo($pattern, $max_names)
  525.   =>
  526.   ({'name' => $name, ...}, {'name' => $name, ...}, ...)</PRE>
  527. <P>The information in each hash is the same as the the information returned by
  528. QueryFont, but without per-character size information. This request is
  529. special in that it is the only request that can have more than one reply.
  530. This means you should probably only use <CODE>request()</CODE> with it, not send(), as
  531. the reply counting is complicated. Luckily, you never need this request
  532. anyway, as its function is completely duplicated by other requests.</P>
  533. <PRE>
  534.   $x->SetFontPath(@strings)</PRE>
  535. <PRE>
  536.   $x->GetFontPath
  537.   =>
  538.   @strings</PRE>
  539. <PRE>
  540.   $x->CreatePixmap($pixmap, $drawable, $depth, $width, $height)</PRE>
  541. <PRE>
  542.   $x->FreePixmap($pixmap)</PRE>
  543. <PRE>
  544.   $x->CreateGC($cid, $drawable, 'attribute' => $value, ...)</PRE>
  545. <PRE>
  546.   $x->ChangeGC($gc, 'attribute' => $value, ...)</PRE>
  547. <PRE>
  548.   $x->CopyGC($src, $dest, 'attribute', 'attribute', ...)</PRE>
  549. <PRE>
  550.   $x->SetDashes($gc, $dash_offset, (@dashes))</PRE>
  551. <PRE>
  552.   $x->SetClipRectangles($gc, ($clip_x_origin, $clip_y_origin),
  553.                         $ordering, [$x, $y, $width, $height], ...)</PRE>
  554. <PRE>
  555.   $x->ClearArea($window, ($x, $y), $width, $height, $exposures)</PRE>
  556. <PRE>
  557.   $x->CopyArea($src_drawable, $dst_drawable, $gc, ($src_x, $src_y),
  558.                $width, $height, ($dst_x, $dst_y))</PRE>
  559. <PRE>
  560.   $x->CopyPlane($src_drawable, $dst_drawable, $gc, ($src_x, $src_y),
  561.                 $width, $height, ($dst_x, $dst_y), $bit_plane)</PRE>
  562. <PRE>
  563.   $x->PolyPoint($drawable, $gc, $coordinate_mode,
  564.                 ($x, $y), ($x, $y), ...)</PRE>
  565. <PRE>
  566.   $x->PolyLine($drawable, $gc, $coordinate_mode,
  567.                ($x, $y), ($x, $y), ...)</PRE>
  568. <PRE>
  569.   $x->PolySegment($drawable, $gc, ($x, $y) => ($x, $y),
  570.                   ($x, $y) => ($x, $y), ...)</PRE>
  571. <PRE>
  572.   $x->PolyRectangle($drawable, $gc,
  573.                     [($x, $y), $width, $height], ...)</PRE>
  574. <PRE>
  575.   $x->PolyArc($drawable, $gc,
  576.               [($x, $y), $width, $height, $angle1, $angle2], ...)</PRE>
  577. <PRE>
  578.   $x->FillPoly($drawable, $gc, $shape, $coordinate_mode,
  579.                ($x, $y), ...)</PRE>
  580. <PRE>
  581.   $x->PolyFillRectangle($drawable, $gc,
  582.                         [($x, $y), $width, $height], ...)</PRE>
  583. <PRE>
  584.   $x->PolyFillArc($drawable, $gc,
  585.                   [($x, $y), $width, $height, $angle1, $angle2], ...)</PRE>
  586. <PRE>
  587.   $x->PutImage($drawable, $gc, $depth, $width, $height,
  588.                ($dst_x, $dst_y), $left_pad, $format, $data)</PRE>
  589. <P>Currently, the module has no code to handle the various bitmap formats that
  590. the server might specify. Therefore, this request will not work portably
  591. without a lot of work.</P>
  592. <PRE>
  593.   $x->GetImage($drawable, ($x, $y), $width, $height, $plane_mask,
  594.                $format)</PRE>
  595. <PRE>
  596.   $x->PolyText8($drawable, $gc, ($x, $y),
  597.                 ($font OR [$delta, $string]), ...)</PRE>
  598. <PRE>
  599.   $x->PolyText16($drawable, $gc, ($x, $y),
  600.                  ($font OR [$delta, $string]), ...)</PRE>
  601. <PRE>
  602.   $x->ImageText8($drawable, $gc, ($x, $y), $string)</PRE>
  603. <PRE>
  604.   $x->ImageText16($drawable, $gc, ($x, $y), $string)</PRE>
  605. <PRE>
  606.   $x->CreateColormap($mid, $visual, $window, $alloc)</PRE>
  607. <PRE>
  608.   $x->FreeColormap($cmap)</PRE>
  609. <PRE>
  610.   $x->CopyColormapAndFree($mid, $src_cmap)</PRE>
  611. <PRE>
  612.   $x->InstallColormap($cmap)</PRE>
  613. <PRE>
  614.   $x->UninstallColormap($cmap)</PRE>
  615. <PRE>
  616.   $x->ListInstalledColormaps($window)
  617.   =>
  618.   @cmaps</PRE>
  619. <PRE>
  620.   $x->AllocColor($cmap, ($red, $green, $blue))
  621.   =>
  622.   ($pixel, ($red, $green, $blue))</PRE>
  623. <PRE>
  624.   $x->AllocNamedColor($cmap, $name)
  625.   =>
  626.   ($pixel, ($exact_red, $exact_green, $exact_blue),
  627.    ($visual_red, $visual_green, $visual_blue))</PRE>
  628. <PRE>
  629.   $x->AllocColorCells($cmap, $colors, $planes, $contiguous)
  630.   =>
  631.   ([@pixels], [@masks])</PRE>
  632. <PRE>
  633.   $x->AllocColorPlanes($cmap, $colors, ($reds, $greens, $blues),
  634.                        $contiguous)
  635.   =>
  636.   (($red_mask, $green_mask, $blue_mask), @pixels)</PRE>
  637. <PRE>
  638.   $x->FreeColors($cmap, $plane_mask, @pixels)</PRE>
  639. <PRE>
  640.   $x->StoreColors($cmap, [$pixel, $red, $green, $blue, $do_mask], ...)</PRE>
  641. <P>The 1, 2, and 4 bits in $mask are do-red, do-green, and do-blue. $mask can
  642. be omitted, defaulting to 7, the usual case -- change the whole color.</P>
  643. <PRE>
  644.   $x->StoreNamedColor($cmap, $pixel, $name, $do_mask)</PRE>
  645. <P>$do_mask has the same interpretation as above, but is mandatory.</P>
  646. <PRE>
  647.   $x->QueryColors($cmap, @pixels)
  648.   =>
  649.   ([$red, $green, $blue], ...)</PRE>
  650. <PRE>
  651.   $x->LookupColor($cmap, $name)
  652.   =>
  653.   (($exact_red, $exact_green, $exact_blue),
  654.    ($visual_red, $visual_green, $visual_blue))</PRE>
  655. <PRE>
  656.   $x->CreateCursor($cid, $source, $mask,
  657.                    ($fore_red, $fore_green, $fore_blue),
  658.                    ($back_red, $back_green, $back_blue),
  659.                    ($x, $y))</PRE>
  660. <PRE>
  661.   $x->CreateGlyphCursor($cid, $source_font, $mask_font,
  662.                         $source_char, $mask_char,
  663.                         ($fore_red, $fore_green, $fore_blue),
  664.                         ($back_red, $back_green, $back_blue))
  665. </PRE>
  666. <PRE>
  667.  
  668.   $x->FreeCursor($cursor)</PRE>
  669. <PRE>
  670.   $x->RecolorCursor($cursor, ($fore_red, $fore_green, $fore_blue),
  671.                     ($back_red, $back_green, $back_blue))</PRE>
  672. <PRE>
  673.   $x->QueryBestSize($class, $drawable, $width, $height)
  674.   =>
  675.   ($width, $height)</PRE>
  676. <PRE>
  677.   $x->QueryExtension($name)
  678.   =>
  679.   ($major_opcode, $first_event, $first_error)</PRE>
  680. <P>If the extension is not present, an empty list is returned.</P>
  681. <PRE>
  682.   $x->ListExtensions
  683.   =>
  684.   (@names)</PRE>
  685. <PRE>
  686.   $x->ChangeModifierMapping($first_keycode, $keysysms_per_keycode,
  687.                             @keysyms)</PRE>
  688. <PRE>
  689.   $x->GetKeyboardMapping($first_keycode, $count)
  690.   =>
  691.   ($keysysms_per_keycode, [$keysym, ...], [$keysym, ...], ...)</PRE>
  692. <PRE>
  693.   $x->ChangeKeyboardControl('attribute' => $value, ...)</PRE>
  694. <PRE>
  695.   $x->GetKeyboardControl
  696.   =>
  697.   ('global_auto_repeat' => $global_auto_repeat, ...)</PRE>
  698. <PRE>
  699.   $x->Bell($percent)</PRE>
  700. <PRE>
  701.   $x->ChangePointerControl($do_acceleration, $do_threshold,
  702.                            $acceleration_numerator,
  703.                            $acceleration_denominator, $threshold)</PRE>
  704. <PRE>
  705.   $x->GetPointerControl
  706.   =>
  707.   ($accerleration_numerator, $acceleration_denominator, $threshold)</PRE>
  708. <PRE>
  709.   $x->SetScreenSaver($timeout, $interval, $prefer_blanking,
  710.                      $allow_exposures)</PRE>
  711. <PRE>
  712.   $x->GetScreenSaver
  713.   =>
  714.   ($timeout, $interval, $prefer_blanking, $allow_exposures)</PRE>
  715. <PRE>
  716.   $x->ChangeHosts($mode, $host_family, $host_address)</PRE>
  717. <PRE>
  718.   $x->ListHosts
  719.   =>
  720.   ($mode, [$family, $host], ...)</PRE>
  721. <PRE>
  722.   $x->SetAccessControl($mode)</PRE>
  723. <PRE>
  724.   $x->SetCloseDownMode($mode)</PRE>
  725. <PRE>
  726.   $x->KillClient($resource)</PRE>
  727. <PRE>
  728.   $x->RotateProperties($win, $delta, @props)</PRE>
  729. <PRE>
  730.   $x->ForceScreenSaver($mode)</PRE>
  731. <PRE>
  732.   $x->SetPointerMapping(@map)
  733.   =>
  734.   $status</PRE>
  735. <PRE>
  736.   $x->GetPointerMapping
  737.   =>
  738.   @map</PRE>
  739. <PRE>
  740.   $x->SetModifierMapping(@keycodes)
  741.   =>
  742.   $status</PRE>
  743. <PRE>
  744.   $x->GetModiferMapping
  745.   =>
  746.   @keycodes</PRE>
  747. <PRE>
  748.   $x->NoOperation($length)</PRE>
  749. <P>$length specifies the length of the entire useless request, in four byte units,
  750. and is optional.</P>
  751. <P>
  752. <HR>
  753. <H1><A NAME="events">EVENTS</A></H1>
  754. <P>To receive events, first set the 'event_mask' attribute on a window to
  755. indicate what types of events you desire (see
  756. <A HREF="#pack_event_mask">pack_event_mask</A>). Then, set the protocol object's 'event_handler'
  757. to a subroutine reference that will handle the events. Alternatively,
  758. set 'event_handler' to 'queue', and retrieve events using
  759. dequeue_event(). In both cases, events are returned as a hash. For
  760. instance, a typical MotionNotify event might look like this:</P>
  761. <PRE>
  762.   %event = ('name' => 'MotionNotify', 'sequence_number' => 12,
  763.             'state' => 0, 'event' => 58720256, 'root' => 43,
  764.             'child' => None, 'same_screen' => 1, 'time' => 966080746,
  765.             'detail' => 'Normal', 'event_x' => 10, 'event_y' => 3,
  766.             'code' => 6, 'root_x' => 319, 'root_y' => 235)</PRE>
  767. <P>
  768. <H2><A NAME="pack_event_mask">pack_event_mask</A></H2>
  769. <PRE>
  770.   $mask = $x->pack_event_mask('ButtonPress', 'KeyPress', 'Exposure');</PRE>
  771. <P>Make an event mask (suitable as the 'event_mask' of a window) from a list
  772. of strings specifying event types.</P>
  773. <P>
  774. <H2><A NAME="unpack_event_mask">unpack_event_mask</A></H2>
  775. <PRE>
  776.   @event_types = $x->unpack_event_mask($mask);</PRE>
  777. <P>The inverse operation; convert an event mask obtained from the server into a
  778. list of names of event categories.</P>
  779. <P>
  780. <H2><A NAME="dequeue_event">dequeue_event</A></H2>
  781. <PRE>
  782.   %event = $x->dequeue_event;</PRE>
  783. <P>If there is an event waiting in the queue, return it.</P>
  784. <P>
  785. <H2><A NAME="next_event">next_event</A></H2>
  786. <PRE>
  787.   %event = $x->next_event;</PRE>
  788. <P>Like Xlib's XNextEvent(), this function is equivalent to</P>
  789. <PRE>
  790.   $x->handle_input until %event = dequeue_event;</PRE>
  791. <P>
  792. <H2><A NAME="pack_event">pack_event</A></H2>
  793. <PRE>
  794.   $data = $x->pack_event(%event);</PRE>
  795. <P>Given an event in hash form, pack it into a string. This is only useful as
  796. an argument to SendEvent().</P>
  797. <P>
  798. <H2><A NAME="unpack_event">unpack_event</A></H2>
  799. <PRE>
  800.   %event = $x->unpack_event($data);</PRE>
  801. <P>The inverse operation; given the raw data for an event (32 bytes), unpack it
  802. into hash form. Normally, this is done automatically.</P>
  803. <P>
  804. <HR>
  805. <H1><A NAME="extensions">EXTENSIONS</A></H1>
  806. <P>Protocol extensions add new requests, event types, and error types to
  807. the protocol. Support for them is compartmentalized in modules in the
  808. X11::Protocol::Ext:: hierarchy. For an example, see
  809. <A HREF="../../../X11/Protocol/Ext:SHAPE.html">the X11::Protocol::Ext:SHAPE manpage</A>. You can tell if the module has loaded an
  810. extension by looking at</P>
  811. <PRE>
  812.   $x->{'ext'}{$extension_name}</PRE>
  813. <P>If the extension has been initialized, this value will be an array reference,
  814. [$major_request_number, $first_event_number, $first_error_number, $obj], where
  815. $obj is an object containing information private to the extension.</P>
  816. <P>
  817. <H2><A NAME="init_extension">init_extension</A></H2>
  818. <PRE>
  819.   $x->init_extension($name);</PRE>
  820. <P>Initialize an extension: query the server to find the extension's request
  821. number, then load the corresponding module. Returns 0 if the server does
  822. not support the named extension, or if no module to interface with it exists.</P>
  823. <P>
  824. <H2><A NAME="init_extensions">init_extensions</A></H2>
  825. <PRE>
  826.   $x->init_extensions;</PRE>
  827. <P>Initialize protocol extensions. This does a ListExtensions request, then calls
  828. <CODE>init_extension()</CODE> for each extension that the server supports.</P>
  829. <P>
  830. <HR>
  831. <H1><A NAME="writing extensions">WRITING EXTENSIONS</A></H1>
  832. <P>Internally, the X11::Protocol module is table driven. All an extension has to
  833. do is to add new add entries to the protocol object's tables. An extension
  834. module should <CODE>use X11::Protocol</CODE>, and should define an <CODE>new()</CODE> method</P>
  835. <PRE>
  836.   X11::Protocol::Ext::NAME
  837.     ->new($x, $request_num, $event_num, $error_num)</PRE>
  838. <P>where $x is the protocol object and $request_num, $event_num and $error_num
  839. are the values returned by QueryExtension().</P>
  840. <P>The <CODE>new()</CODE> method should add new types of constant like</P>
  841. <PRE>
  842.   $x->{'ext_const'}{'ConstantType'} = ['Constant', 'Constant', ...]</PRE>
  843. <P>and set up the corresponding name to number translation hashes like</P>
  844. <PRE>
  845.   $x->{'ext_const_num'}{'ConstType'} =
  846.     {make_num_hash($x->{'ext_const'}{'ConstType'})}</PRE>
  847. <P>Event names go in</P>
  848. <PRE>
  849.   $x->{'ext_const'}{'Events'}[$event_number]</PRE>
  850. <P>while specifications for event contents go in</P>
  851. <PRE>
  852.   $x->{'ext_event'}[$event_number]</PRE>
  853. <P>each element of which is either <CODE>[\&unpack_sub, \&pack_sub]</CODE> or
  854. <CODE>[$pack_format, $field, $field, ...]</CODE>, where each $field is <CODE>'name'</CODE>,
  855. <CODE>['name', 'const_type']</CODE>, or <CODE>['name', ['special_name_for_zero',
  856. 'special_name_for_one']]</CODE>, where <CODE>'special_name_for_one'</CODE> is optional.</P>
  857. <P>Finally,</P>
  858. <PRE>
  859.   $x->{'ext_request'}{$major_request_number}</PRE>
  860. <P>should be an array of arrays, with each array either <CODE>[$name, \&packit]</CODE> or
  861. <CODE>[$name, \&packit, \&unpackit]</CODE>, and</P>
  862. <PRE>
  863.   $x->{'ext_request_num'}{$request_name}</PRE>
  864. <P>should be initialized with <CODE>[$minor_num, $major_num]</CODE> for each request the
  865. extension defines. For examples of code that does all of this, look at
  866. X11::Protocol::Ext::SHAPE.</P>
  867. <P>X11::Protocol exports several functions that might be useful in extensions
  868. (note that these are <EM>not</EM> methods).</P>
  869. <P>
  870. <H2><A NAME="padding">padding</A></H2>
  871. <PRE>
  872.   $p = padding $x;</PRE>
  873. <P>Given an integer, compute the number need to round it up to a multiple of 4.
  874. For instance, <CODE>padding(5)</CODE> is 3.</P>
  875. <P>
  876. <H2><A NAME="pad">pad</A></H2>
  877. <PRE>
  878.   $p = pad $str;</PRE>
  879. <P>Given a string, return the number of extra bytes needed to make a multiple
  880. of 4. Equivalent to <CODE>padding(length($str))</CODE>.</P>
  881. <P>
  882. <H2><A NAME="padded">padded</A></H2>
  883. <PRE>
  884.   $data = pack(padded($str), $str);</PRE>
  885. <P>Return a format string, suitable for pack(), for a string padded to a multiple
  886. of 4 bytes. For instance, <A HREF="../../../lib/Pod/perlfunc.html#item_pack"><CODE>pack(padded('Hello'), 'Hello')</CODE></A> gives
  887. <CODE>"Hello\0\0\0"</CODE>.</P>
  888. <P>
  889. <H2><A NAME="hexi">hexi</A></H2>
  890. <PRE>
  891.   $str = hexi $n;</PRE>
  892. <P>Format a number in hexidecimal, and add a ``0x'' to the front.</P>
  893. <P>
  894. <H2><A NAME="make_num_hash">make_num_hash</A></H2>
  895. <PRE>
  896.   %hash = make_num_hash(['A', 'B', 'C']);</PRE>
  897. <P>Given a reference to a list of strings, return a hash mapping the strings onto
  898. numbers representing their position in the list, as used by
  899. <CODE>$x->{'ext_const_num'}</CODE>.</P>
  900. <P>
  901. <HR>
  902. <H1><A NAME="bugs">BUGS</A></H1>
  903. <P>This module is too big (~2500 lines), too slow (10 sec to load on a slow
  904. machine), too inefficient (request args are copied several times), and takes
  905. up too much memory (3000K for basicwin).</P>
  906. <P>If you have more than 65535 replies outstanding at once, sequence numbers
  907. can collide.</P>
  908. <P>The protocol is too complex.</P>
  909. <P>
  910. <HR>
  911. <H1><A NAME="author">AUTHOR</A></H1>
  912. <P>Stephen McCamant <<A HREF="mailto:alias@mcs.com">alias@mcs.com</A>>.</P>
  913. <P>
  914. <HR>
  915. <H1><A NAME="see also">SEE ALSO</A></H1>
  916. <P><EM>perl(1)</EM>,
  917. <EM>X(1)</EM>, 
  918. <A HREF="../../../site/lib/X11/Keysyms.html">the X11::Keysyms manpage</A>, 
  919. <A HREF="../../../site/lib/X11/Protocol/Ext/SHAPE.html">the X11::Protocol::Ext::SHAPE manpage</A>,
  920. <A HREF="../../../site/lib/X11/Protocol/Ext/BIG_REQUESTS.html">the X11::Protocol::Ext::BIG_REQUESTS manpage</A>,
  921. <A HREF="../../../site/lib/X11/Auth.html">the X11::Auth manpage</A>,
  922. <EM>X Window System Protocol (X Version 11)</EM>,
  923. <EM>Inter-Client Communications Conventions Manual</EM>,
  924. <EM>X Logical Font Description Conventions</EM>.</P>
  925. <TABLE BORDER=0 CELLPADDING=0 CELLSPACING=0 WIDTH=100%>
  926. <TR><TD CLASS=block VALIGN=MIDDLE WIDTH=100% BGCOLOR="#cccccc">
  927. <STRONG><P CLASS=block> X11::Protocol - Perl module for the X Window System Protocol, version 11</P></STRONG>
  928. </TD></TR>
  929. </TABLE>
  930.  
  931. </BODY>
  932.  
  933. </HTML>
  934.