X11::Xlib - Low-level access to the X11 library
# C-style use X11::Xlib ':all'; my $display = XOpenDisplay($conn_string); XTestFakeMotionEvent($display, undef, 50, 50); XFlush($display); # or, Object-Oriented perl style: use X11::Xlib; my $display= X11::Xlib->new($conn_string); # shortcut for X11::Xlib::Display->new $display->fake_motion(undef, 50, 50) $display->flush; # Remap Caps_Lock to a Smiley face use X11::Xlib; my $display= X11::Xlib->new; my $caps_code= $display->keymap->find_keycode('Caps_lock') // 0x42; $display->keymap->modmap_del_codes(lock => $caps_code); $display->keymap->keymap->[$caps_code]= [("U263A") x 4]; $display->keymap->save;
This module provides low-level access to Xlib functions.
This includes access to some X11 extensions like the X11 test library (Xtst).
If you import the Xlib functions directly, or call them as methods on an instance of X11::Xlib, you get a near-C experience where you are required to manage the lifespan of resources, XIDs are integers instead of objects, and the library does not make any attempt to keep you from passing bad data to Xlib.
If you instead create a X11::Xlib::Display object and call all your methods on that, you get a more friendly wrapper around Xlib that helps you manage resource lifespan, wraps XIDs with perl objects, and does some sanity checking on the state of the library when you call methods.
The X11::Xlib connection is a hashref with a few attributes and methods independent of Xlib.
Boolean flag that determines whether the destructor will call "XCloseDisplay". Defaults to true for connections returned by "XOpenDisplay".
# Global error handler X11::Xlib::on_error(\&my_callback); # Per-connection error handler my $display= X11::Xlib->new; $display->on_error(\&my_callback); sub my_callback { my ($display, $event)= @_; ... }
By default, Xlib aborts the program on a fatal error. Use this method to install an error-handling callback to gracefully catch and deal with errors. On non-fatal errors, $event will be the error event from the server. On fatal errors, $event will be undef. You can also install a handler on an individual connection. On a nonfatal error, both the connection and global error handlers are invoked. On a fatal error, all error handlers are invoked.
$event
undef
Setting a value for this attribute automatically installs the Xlib error handler, which is not enabled by default.
Note that this callback is called from XS context, so your exceptions will not travel up the stack. Also note that on Xlib fatal errors, you cannot call any more Xlib functions on the current connection, or on any connection at all once the callback returns.
Be sure to read notes under "ERROR HANDLING"
This is an alias for X11::Xlib::Display->new, to help encourage use of the object oriented interface.
X11::Xlib::Display->new
Most functions can be called as methods on the Xlib connection object, since this is usually the first argument. Every Xlib function listed below can be exported, and you can grab them all with
use X11::Xlib ':functions';
Sets up Xlib in a thread-safe manner, which basically means wrapping each Xlib method with a mutex. After this call, multiple threads may access the same Display connection without application-level synchronization. If used, this must be the first Xlib call in the whole program, which can be inconvenient if you don't know in advance which other modules you are using. While perl scripts are typically single-threaded, you might still require this if you call into other libraries that create their own threads and also access Xlib.
Returns true if multithread initialization succeeded. If it fails, you probably should abort. (and then fix your program so that it is the first Xlib function called)
Assuming XInitThreads succeeded, this will lock the Xlib mutex so you can run multiple calls uninterrupted.
Release the lock taken by "XLockDisplay".
my $conn_string= X11::Xlib::XDisplayName(); my $conn_string= X11::Xlib::XDisplayName( $str );
Returns the official connection string Xlib will use if you were to call XOpenDisplay($str).
XOpenDisplay($str)
my $display= X11::Xlib::XOpenDisplay($connection_string);
Instantiate a new (C-level) "Display" instance. This object contains the connection to the X11 display. This will be an instance of X11::Xlib. The X11::Xlib::Display object constructor is recommended instead.
X11::Xlib
The $connection_string variable specifies the display string to open. ("host:display.screen", or often ":0" to connect to the only screen of the only display on localhost) If unset, Xlib uses the $DISPLAY environment variable.
$connection_string
"host:display.screen"
":0"
localhost
$DISPLAY
If the handle goes out of scope, its destructor calls XCloseDisplay, unless you already called XCloseDisplay or the X connection was lost. (Be sure to read the notes on "ERROR HANDLING")
XCloseDisplay
XCloseDisplay($display); # or, just: undef $display
Close a handle returned by XOpenDisplay. You do not need to call this method since the handle's destructor does it for you, unless you want to forcibly stop communicating with X and can't track down your references. Once closed, all further Xlib calls on the handle will die with an exception.
XOpenDisplay
my $fh= IO::Handle->new_from_fd( $display->ConnectionNumber, 'w+' );
Return the file descriptor (integer) of the socket connected to the server. This is useful for select/poll designs. (See also: "wait_event" in X11::Xlib::Display)
$name= XServerVendor($display);
Return the vendor string from the X Server.
$version= XVendorRelease($display);
Return the version number from the server (packed into a single integer)
XSetCloseDownMode($display, $close_mode)
Determines what resources are freed upon disconnect. See X11 documentation.
The X11 server maintains an enumeration of strings, called Atoms. By enumerating the strings, it allows small integers to be exchanged instead of variable-length identifiers, which makes parsing the protocol more efficient for both sides. However clients need to look up (or create) the relevant atoms before they can be used. Be careful when creating atoms; they remain until the server is restarted.
my $atom_value= XInternAtom($display, $atom_name, $only_existing);
Get the value of a named atom. If $only_existing is true and the atom does not already exist on the server, this function returns 0. (which is not a valid atom value)
$only_existing
my $atoms_array= XInternAtoms($display, \@atom_names, $only_existing);
Same as above, but look up multiple atoms at once, for round-trip efficiency. The returned array will always be the same length as @atom_names, but will have 0 for any atom value that did not exist if $only_existing was true.
@atom_names
my $name= XGetAtomName($display, $atom_value);
Return the name of an atom. If the atom is not defined this generates a protocol error (can be caught by /on_error handler) and returns undef.
/on_error
my $names_array= XGetAtomNames($display, \@atom_values);
Same as above, but look up multiple atoms at once, for round-trip efficiency. If any atom does not exist, this generates a protocol error, but if you catch the error then this function will return an array the same length as @atom_values with undef for each atom that did not exist.
@atom_values
Most of these functions return an "XEvent" by way of an "out" parameter that gets overwritten during the call, in the style of C. The variable receiving the event does not need to be initialized.
my $count= XQLength($display);
Return number of events already in the incoming queue, without trying to read more.
my $count= XPending($display);
Return number of events in incoming queue after performing a flush and a read.
my $count= XEventsQueued($display, $mode);
$mode is one of QueuedAlready, QueuedAfterFlush, or QueuedAfterReading. QueuedAlready simply returns the queue size. QueuedAfterReading performs a read, then returns the count. QueuedAfterFlush performs a flush and a read, then returns the count.
$mode
XNextEvent($display, my $event_return) ... # event scalar is populated with event
You probably don't want this. It blocks forever until an event arrives, even ignoring signals. I added it for completeness. See "wait_event" in X11::Xlib::Display for a more perl-ish interface.
if ( XCheckMaskEvent($display, $event_mask, my $event_return) ) ... if ( XCheckTypedEvent($display, $event_type, my $event_return) ) ... if ( XCheckWindowEvent($display, $event_mask, $window, my $event_return) ) ... if ( XCheckTypedWindowEvent($display, $event_type, $window, my $event_return) ) ...
Each of these variations checks whether there is a matching event received from the server and not yet extracted form the message queue. If so, it stores the event into $event_return and returns true. Else it returns false without blocking.
$event_return
(Xlib also has another variant that uses a callback to choose which message to extract, but I did not implement that because it seemed like a pain and probably nobody would use it.)
XSendEvent($display, $window, $propagate, $event_mask, $xevent) or die "Xlib hates us";
Send an XEvent to the server, to be re-dispatched however appropriate.
XPutBackEvent($display, $xevent)
Push an XEvent back onto your own incoming queue. This can presumably put arbitrarily bogus events onto your own queue since it returns void.
XFlush($display)
Push any queued messages to the X11 server. Some Xlib calls perform an implied flush of the queue, while others don't. If you are wondering why nothing happened when you called an XTest function, this is why.
XSync($display); XSync($display, $discard);
Force a round trip to the server to process all pending messages and receive the responses (or errors). A true value for the second argument will wipe your incoming event queue.
XSelectInput($display, $window, $event_mask)
Change the event mask for a window. Note that event masks are per-client, so one client can listen to a window with a different mask than a second client listening to the same window.
my $error_description= XGetErrorText($display, $error_code);
my $msg= XGetErrorDatabaseText($display, $name, $message, $default_string);
$name indicates what sort of thing to look up. $message is a stringified code of some sort. Yes this is really weird for a C API.
my $msg= XGetErrorDatabaseText($display, 'XProtoError', $error_code, $default); my $msg= sprintf( XGetErrorDatabaseText($display, 'XlibMessage', 'MajorCode', "Request Major Code %d"), $event->request_code ); my $message= XGetErrorDatabaseText($display, 'XRequest', $request_code);
Just use "summarize" in X11::Xlib::XEvent on an XErrorEvent and save yourself the trouble.
Xlib provides opaque "Display" and "Screen" structs which have locally- stored attributes, but which you must use method calls to access. For each attribute of a screen, there are four separate ways to access it:
DisplayFoo($display, $screen_num); # C Macro like ->{screens}[$screen_num]{foo} XDisplayFoo($display, $screen_num); # External linked function from Xlib FooOfScreen($screen_pointer); # C Macro like ->{foo} XFooOfScreen($screen_pointer); # External linked function from Xlib
Since screen pointers become invalid when the Display is closed, I decided not to expose them, and since DisplayFoo and XDisplayFoo are identical I decided to only implement the first since it makes one less symbol to link from Xlib.
So, if you grab some sample code from somewhere and wonder where those functions went, drop the leading X and do a quick search on this page.
my $n= ScreenCount($display);
Return number of configured "Screen"s of this display.
Returns the default screen number of the display
my $w= DisplayWidth($display, $screen); my $h= DisplayHeight($display, $screen); # use instead of WidthOfScreen, HeightOfScreen
Return the width or height of screen number $screen. You can omit the $screen parameter to use the default screen of your Display connection.
$screen
my $w= DisplayWidthMM($display, $screen); my $h= DisplayHeightMM($display, $screen); # use instead of WidthMMOfScreen, HeightMMOfScreen
Return the physical width or height (in millimeters) of screen number $screen. You can omit the screen number to use the default screen of the display.
my $xid= RootWindow($display, $screen)
Return the XID of the X11 root window. $screen is optional, and defaults to the default screen of your connection. If you want a Window object, call this method on X11::Xlib::Display.
my $visual= DefaultVisual($display, $screen); # use instead of DefaultVisualOfScreen
Screen is optional and defaults to the default screen of your connection. This returns a "Visual", not a "XVisualInfo".
my $bits_per_pixel= DefaultDepth($display, $screen); # use instead of DefaultDepthOfScreen, DisplayPlanes, PlanesOfScreen
Return bits-per-pixel of the root window of a screen. If you omit $screen it uses the default screen.
Default color map of the display
Default graphics context of the display
XMatchVisualInfo($display, $screen, $depth, $class, my $xvisualinfo_return) or die "Don't have one of those";
Loads the details of a "Visual" into the final argument, which must be an "XVisualInfo" (or undefined, to create one)
Returns true if it found a matching visual.
my @info_structs= XGetVisualInfo($display, $mask, $xvis_template);
Returns a list of "XVisualInfo" each describing an available "Visual" which matches the template you provided. (which is also an XVisualInfo)
XVisualInfo
$mask can be any combination of:
$mask
VisualIDMask VisualScreenMask VisualDepthMask VisualClassMask VisualRedMaskMask VisualGreenMaskMask VisualBlueMaskMask VisualColormapSizeMask VisualBitsPerRGBMask VisualAllMask
each describing a field of X11::Xlib::XVisualInfo which is relevant to your search.
my $vis_id= XVisualIDFromVisual($visual); # or, assuming $visual is blessed, my $vis_id= $visual->id;
Pull the visual ID out of the opaque object $visual.
If what you wanted was actually the "XVisualInfo" for a $visual, then try:
$visual
my ($vis_info)= GetVisualInfo($display, VisualIDMask, { visualid => $vis_id }); # or with Display object: $display->visual_by_id($vis_id);
my $xid= XCreateColormap($display, $rootwindow, $visual, $alloc_flag); # or 99% of the time my $xid= XCreateColormap($display, RootWindow($display), DefaultVisual($display), AllocNone); # and thus these are the defaults my $xid= XCreateColormap($display);
Create a "Colormap". The $visual is a "Visual" object, and the $alloc_flag is either AllocNone or AllocAll.
$alloc_flag
AllocNone
AllocAll
XFreeColormap($display, $colormap);
Delete a "Colormap", and set the colormap to None for any window that was using it.
None
XInstallColormap XUninstallColormap, XListInstalledColormaps XGetWMColormapWindows XSetWMColormapWindows, XSetWindowColormap XAllocColor XStoreColors XFreeColors XAllocColorPlanes XAllocNamedColor XQueryColors XCopyColormapAndFree
If anyone actually needs palette graphics anymore, send me a patch :-)
my $xid= XCreatePixmap($display, $drawable, $width, $height, $depth);
The $drawable parameter is just used to determine the screen. You probably want to pass either DefaultRootWindow($display) or the window you are creating the pixmap for.
$drawable
DefaultRootWindow($display)
XFreePixmap($display, $pixmap);
my $pixmap_xid= XCreateBitmapFromData($display, $drawable, $data, $width, $height);
First, be aware that in X11, a "bitmap" is literally a "Bit" "Map" (1 bit per pixel).
The $drawable determines which screen the pixmap is created for. The $data is a string of bytes.
$data
The $data should technically be opaque, written by another X11 function after having rendering graphics to a pixmap or something, but since those are not implemented here yet, you'll just have to know the format.
my $pixmap_xid= XCreatePixmapFromBitmapData($display, $drawable, $data, $width, $height, $fg, $bg, $depth);
This function uses a bitmap (1 bit per pixel) and a foreground and background color to build a pixmap of those two colors. It's basically upscaling color from monochrome to $depth.
$depth
my $wnd_xid= XCreateWindow( $display, $parent_window, # such as DefaultRootWindow() $x, $y, $width, $height, $border_width, $color_depth, # such as $visual_info->depth or DefaultDepth($display) $class, # InputOutput, InputOnly, or CopyFromParent $visual, # such as $visual_info->visual or DefaultVisual($display) $attr_mask, # indicates which fields of \%attrs are initialized \%attrs # struct XSetWindowAttributes or hashref of its fields );
The parameters the probably need more explanation are $visual and %attrs.
%attrs
$visual is a "Visual". You probably either want to use the default visual of the screen ("DefaultVisual") or look up your own visual using "XGetVisualInfo" or "XMatchVisualInfo" (which is a "VisualInfo", and has an attribute ->visual). In the second case, you should also pass $visual_info->depth as the $depth parameter, and create a matching "Colormap" which you pass via the \%attrs parameter.
->visual
$visual_info->depth
\%attrs
Since this function did not have nearly enough parameters for the imaginations of the Xlib creators, they added the full X11::Xlib::XSetWindowAttributes structure as a final argument. But to save you the trouble of setting all those fields, they added an $attr_mask to indicate which fields you are using. Simply OR together the constants listed in that struct. If $attr_mask is zero, then \%attrs may be undef.
$attr_mask
The window is initially unmapped (i.e. hidden). See "XMapWindow"
my $wnd_xid= XCreateSimpleWindow( $display, $parent_window, $x, $y, $width, $height, $border_width, $border_color, $background_color );
This function basically creates a "child window", clipped to its parent, with all the same visual configuration.
It is initially unmapped. See "XMapWindow".
XMapWindow($display, $window);
Ask the X server to show a window. This call is asynchronous and you should call "XFlush" if you want it to appear immediately. The window will only appear if the parent window is also mapped. The server sends back a MapNotify event if the Window event mask allows it, and if a variety of other conditions are met. It's really pretty complicated and you should read the official docs.
XUnmapWindow($display, $window);
Hide a window.
$bool= XGetGeometry($display, $drawable, my $root_out, my $x_out, my $y_out, my $width_out, my $height_out, my $border_width_out, my $color_depth_out); # or more perl-ish ($root, $x, $y, $width, $height, $border_width, $color_depth) = XGetGeometry($display, $drawable) or die "XGetGeometry failed";
$bool= XTranslateCoordinates($display, $src_win, $dst_win, $src_x, $src_y, my $dst_x_out, my $dst_y_out, my $child_out); # or more perl-ish ($x, $y, $child)= XTranslateCoordinates($display, $src_win, $dst_win, $src_x, $src_y) or die;
my $bool= XGetWindowAttributes($display, $window, $attrs_out);
Populate $attrs_out, which should be an undefined variable or a buffer or an instance of X11::Xlib::XWindowAttributes. If it returns false, $attrs_out remains unchanged.
$attrs_out
XChangeWindowAttributes($display, $window, $valuemask, \%XSetWindowAttributes)
Apply one or more fields of the X11::Xlib::XSetWindowAttributes struct to the specified window. $valuemask is a ORed combination of the flags listed for that struct.
$valuemask
XSetWindowBackground($display, $window, $background_pixel)
Set the background pixel color (integer) for the window.
XSetWindowBackgroundPixmap($display, $window, $background_pixmap)
XSetWindowBorder($display, $window, $border_pixel)
XSetWindowBorderPixmap($display, $window, $border_pixmap)
XSetWindowColormap($display, $window, $colormap)
XDefineCursor($display, $window, $cursor)
XUndefineCursor($display, $window)
XReparentWindow($display, $wnd, $new_parent, $x, $y);
Unmap, change parent, and remap $wnd to be a child of $parent. The X and Y arguments set the new location of the window relative to the parent client space.
$wnd
$parent
XConfigureWindow($display, $window, $mask, \%XWindowChanges);
Set the size, position, border, and stacking order of a window. X11::Xlib::XWindowChanges can be passed as an object or plain hashref. $mask is an ORed combination of the constants listed in the documentation for that struct, indicating which fields have been initialized.
XMoveWindow($display, $window, $x, $y);
XResizeWindow($display, $window, $width, $height)
XMoveResizeWindow($display, $window, $x, $y, $width, $height)
XSetWindowBorderWidth($display, $window, $border_width)
my ($root, $parent, @children)= XQueryTree($display, $window);
Return windows related to $window. Child windows are returned in bottom-to-top stacking order. Returns an empty list if it fails.
$window
XRaiseWindow($display, $window);
Move window to front of stacking order.
XLowerWindow($display, $window);
Move window to back of stacking order.
XCirculateSubwindows($display, $parent_window, $direction);
For the child windows of the given window, either bring the back-most to the front (direction == RaiseLowest), or the front-most to the back (direction == LowerHighest).
direction == RaiseLowest
direction == LowerHighest
(Note: use this instead of XCirculateSubwindowsUp or XCirculateSubwindowsDown)
XRestackWindows($display, \@windows);
Reset the stacking order of the specified windows, from front to back.
my @prop_atoms= XListProperties($display, $window); print "Window has these properties: ".join(", ", @{ XGetAtomNames($display, \@prop_atoms, 1) });
Returns an arrayref of all defined properties on the specified window.
my $success= XGetWindowProperty($display, $wnd, $prop_atom, $offset, $length, $delete, $req_type, my $actual_type, my $actual_format, my $nitems, my $bytes_after, my $data);
Welcome to the wonderful world of X11 Window Properties! You pick the property using $prop_atom (see "XInternAtom") and then request some range of the bytes that compose it (using $offset*4 and $length*4, which are a count of 4-byte units, not bytes) request to delete it with $delete, request the resource be given to you as $req_type (also an Atom), and then receive all the actual values in the last 5 variables.
$prop_atom
$offset
$length
$delete
$req_type
$actual_format is either 8, 16, or 32 indicating the multiplier for $nitems. But you can just check length($data) to save time.
$actual_format
$nitems
length($data)
The details are complicated enough you should go read the X11 docs, but a quick example is:
my $netwmname= XInternAtom($display, "_NET_WM_NAME"); my $type_utf8= XInternAtom($display, "UTF8_STRING"); if (XGetWindowProperty($display, $wnd, $netwmname, 0, 32, 0, $type_utf8, my $actual_type, my $actual_format, my $n, my $remaining, my $data) ) { say $data; # should check $actual_type, but it's probably readable text. say "window title was longer than 128 bytes" if $remaining > 0; }
XChangeProperty($display, $wnd, $prop_atom, $type_atom, $format, $mode, $data, $nitems);
$prop_atom determines what property is being written. $type_atom declares the logical type of the data. $format is 8, 16, or 32 to determine the word size of the data (used by X server for endian swapping). $mode is one of: PropModeReplace, PropModePrepend, PropModeAppend. $data is a scalar that must be at least as long as $nitems * $format bits.
$type_atom
$format
PropModeReplace
PropModePrepend
PropModeAppend
XDeleteProperty($display, $window, $prop_atom);
Deletes the property from the window if it exists. No error is raised if it does not exist.
my @atoms= XGetWMProtocols($display, $wnd);
Returns a list of protocols (identifiers, represented as atoms) which the owner of this window claims to support. If a protocol's atom is in this list then you can send that sort of ClientMessage events to this window.
XSetWMProtocols($display, $wnd, \@procol_atoms) or die "Failed to set WM_PROTOCOLS";
Set the list of protocols you want to respond to for this window. For example, to advertise support for standard "close" events:
my $close_atom= XInternAtrom($display, "WM_DELETE_WINDOW", 0); XSetWMProtocols($display, $window, [ $close_atom ]);
my ($hints_out, $supplied_fields_out); XGetWMNormalHints($display, $window, $hints_out, $supplied_fields_out) or warn "Doesn't have WM hints";
If a window has Window Manager Normal Hints defined on it, this function will store them into the $hints_out variable (which will become a X11::Xlib::XSizeHints if it was not already). It will also set the bits of $supplied_fields_out to indicate which fields the X11 server knows about. This is different from the bits in $hints_out->flags that indicate which individual fields are defined for this window.
$hints_out
$supplied_fields_out
$hints_out->flags
XSetWMNormalHints($display, $window, $hints);
Set window manager hints for the specified window. $hints is an instance of X11::Xlib::XSizeHints, or a hashref of its fields. Note that the ->flags member of this struct will be initialized for you if you pass a hashref, according to what fields exist in the hashref.
$hints
->flags
XGetWMSizeHints($display, $window, $hints_out, $supplied_fields_out, $prop_atom);
Request the attribute $prop_atom from the $window. If it exists and is an XSizeHints type, the variable $hints_out will be filled with the struct fields, and $supplied_fields_out will be set to a bit mask of which fields were available.
XSetWMSizeHints($display, $window, $hints, $prop_atom);
Write value of type XSizeHints to the named property of the window. $hints should be a XSizeHints object, or packed buffer containing the fields of one.
XDestroyWindow($display, $window);
Unmap and destroy a window.
These methods create fake server-wide input events, useful for automated testing. They are available through the XTest extension. Currently this extension is a mandatory requirement for installing this module, and so these functions are always available.
Don't forget to call "XFlush" after these methods, if you want the events to happen immediately.
XTestFakeMotionEvent($display, $screen, $x, $y, $EventSendDelay)
Fake a mouse movement to position $x,$y on screen number $screen.
$x
$y
The optional $EventSendDelay parameter specifies the number of milliseconds to wait before sending the event. The default is 10 milliseconds.
$EventSendDelay
XTestFakeButtonEvent($display, $button, $pressed, $EventSendDelay)
Simulate an action on mouse button number $button. $pressed indicates whether the button should be pressed (true) or released (false).
$button
$pressed
XTestFakeKeyEvent($display, $kc, $pressed, $EventSendDelay)
Simulate a event on any key on the keyboard. $kc is the key code (8 to 255), and $pressed indicates if the key was pressed or released.
$kc
See "EXAMPLES" in X11::Xlib::Keymap.
These utility functions help identify and convert KeySym values, and do not depend on a connection to an X server.
my $ident= XKeysymToString($keysym)
Return the ASCII identifier of the KeySym (as in X11/keysym.h) minus the leading "XK_" prefix, or undef of that fails for some reason.
XKeysymToString is the exact reverse of XStringToKeysym.
XKeysymToString
XStringToKeysym
my $keysym= XStringToKeysym($string)
Return the keysym number for the symbolic identifier $string. (as per X11/keysym.h, minus the XK_ prefix)
$string
XStringToKeysym is the reverse of XKeysymToString.
my $keysym= codepoint_to_keysym(ord($char));
Convert a Unicode codepoint to a KeySym value. This is not a true Xlib function, but fills a gap in the API since Xlib is pretty weak on Unicode handling. Every normal Unicode codepoint has a keysym value, but if you pass an invalid codepoint you will get undef.
my $cp= keysym_to_codepoint($keysym); my $char= defined $cp? chr($cp) : undef;
Convert a KeySym to a Unicode codepoint. Many KeySyms (like F1, Control, etc) do not have any character associated with them, and will return undef. Again, not actually part of Xlib, but provided here for convenience.
Like "codepoint_to_keysym" example above, but takes a string from which it calls ord() on the first character. Returns undef if the string does not have a first character.
Like "keysym_to_codepoint" example above, but returns a string if there is a valid codepoint, and undef otherwise.
XConvertCase($keysym, $lowercase_out, $uppercase_out);
Return the lowercase and uppercase KeySym values for $keysym.
$keysym
IsFunctionKey($keysym)
Return true if $keysym is a function key (F1 .. F35)
IsKeypadKey($keysym)
Return true if $keysym is on numeric keypad.
IsMiscFunctionKey($keysym)
Return true if key is... no clue :/ and not documented anywhere??
IsModifierKey($keysym)
Return true if $keysym is a modifier key (Shift, Alt).
IsPFKey($keysym)
Xlib docs are fun. No mention of what "PF" might be.
IsPrivateKeypadKey($keysym)
True for vendor-private key codes.
XSetInputFocus($display, $wnd_focus, $revert_to, $time);
Change input focus and set last-focus-time if $time is after the current last-focus-time and before the current time of the X server.
$time
$time can be CurrentTime to use the X server's clock.
$wnd_focus can be None to discard all keyboard input until a new window is focused, or PointerRoot to actively track the root window of whatever screen the pointer moves to.
$wnd_focus
Once the target window becomes unviewable, the $revert_to setting takes effect, and can be RevertToParent, RevertToPointerRoot, or RevertToNone.
$revert_to
RevertToParent
RevertToPointerRoot
RevertToNone
XQueryKeymap($display)
Return a list of the key codes currently pressed on the keyboard.
$bool= XGrabKeyboard($display, $window, $owner_events, $pointer_mode, $keyboard_mode, $timestamp)
Direct focus to the specified window. See X11 docs.
XUngrabKeyboard($display, $timestamp)
XGrabKey($display, $keycode, $modifiers, $window, $owner_events, $pointer_mode, $keyboard_mode)
Register a window to receive any matching key events, optionally hiding them from the normal target window.
$keycode is the keyboard scan code to watch for, or AnyKey. $modifiers is a bit mask combined from ControlMask, LockMask, Mod1Mask, Mod2Mask, Mod3Mask, Mod4Mask, Mod5Mask, ShiftMask, or the special mask AnyModifier which means any or none of the modifiers. $window is the XID or X11::Xlib::Window to direct events toward. $owner_events is a boolean of whether to also let the normal target of the key event receive them. $pointer_mode and $keyboard_mode are either GrabModeSync or GrabModeAsync.
$keycode
AnyKey
$modifiers
ControlMask
LockMask
Mod1Mask
Mod2Mask
Mod3Mask
Mod4Mask
Mod5Mask
ShiftMask
AnyModifier
$owner_events
$pointer_mode
$keyboard_mode
GrabModeSync
GrabModeAsync
XUngrabKey($display, $keycode, $modifiers, $window)
Cancel a grab registered by "XGrabKey".
$bool= XGrabPointer($display, $window, $owner_events, $event_mask, $pointer_mode, keyboard_mode, confine_to, cursor, timestamp)
XUngrabPointer(dpy, timestamp)
XGrabButton($display, $button, $modifiers, $window, $owner_events, $event_mask, $pointer_mode, $keyboard_mode, $confine_to, $cursor)
XUngrabButton($display, $button, $modifiers, $window)
XQueryPointer($display, $window, my $root_out, my $child_out, my $root_x_out, my $root_y_out, my $win_x_out, my $win_y_out, my $mask_out); # or more perl-like: ($root, $child, $root_x, $root_y, $win_x, $win_y, $mask) = XQueryPointer($display, $window);
Return information about the current location of the pointer. The native API returns the values into parameters, but this implementation offers them as a returned list, if you only pass the window argument.
XWarpPointer($display, $src_win, $dest_win, $src_x, $src_y, $src_width, $src_height, $dest_x, $dest_y)
Move pointer to $dest_win ($dest_x, $dest_y), or relative to current position if $dest_win is undefined. If the $src_* parameters are defined, the move only occurs if the cursor is currently within that rectangle of that window.
$dest_win
($dest_x, $dest_y)
$src_*
XAllowEvents($display, $event_mode, $timestamp)
If grab modes used above are GrabModeSync then further X11 input processing is halted until you call this function. See X11 docs.
XDisplayKeycodes($display, my $min_code_out, my $max_code_out);
Returns the minimum keycode and maximum keycode into the supplied scalars. Minimum is never less than 8 and maximum is never greater than 255.
XGetKeyboardMapping($display, $keycode, $count)
Return an array of KeySym numbers corresponding to $count key codes, starting at $keycode.
$count
Each position in the per-key array corresponds to a combination of key modifiers (Shift, Lock, Mode). The X11 server may return a variable number of codes per key, which you can determine by dividing the total number of values returned by this function by the $count.
For a more perl-friendly interface, see "load_keymap". For object-oriented access, see X11::Xlib::Keymap.
XChangeKeyboardMapping($display, $first_keycode, $keysym_per_keycode, \@keysyms, $num_codes); # Best explained with an example... # KeySym in 0x20..0x7E map directly from Latin1 my @keycodes= ( ord('a'), ord('A'), ord('a'), ord('A'), # want to assign these KeySym to KeyCode 38 ord('s'), ord('S'), ord('s'), ord('S'), # and these to KeyCode 39 ); XChangeKeyboardMapping($display, 38, 4, \@keycodes, scalar @keycodes);
Update some/all of the KeySyms attached to one or more KeyCodes. In the example above, only the first 4 KeySyms of each KeyCode will be changed. Specify a larger number of $keysym_per_keycode to overwrite more of them.
$keysym_per_keycode
For a more perl-friendly interface, see "save_keymap". For object-oriented access, see X11::Xlib::Keymap.
my $keymap= load_keymap($display, $symbolic, $min_key, $max_key); my $keymap= load_keymap($display, $symbolic); # all keys my $keymap= load_keymap($display); # all keys, symbolic=2
This is a wrapper around "XGetKeyboardMapping" which returns an arrayref of arrayrefs, and also translates KeySym values into KeySym names or Unicode characters. If $symbolic is 0, the elements of the arrays are KeySym numbers. If $symbolic is 1, the elements are the KeySym name (or integers, if a name is not available). If $symbolic is 2, the elements are characters for every KeySym that can be unambiguously represented by a character, else KeySym names, else integers.
$symbolic
The minimum KeyCode of an X server is never below 8. If you omit $min_key it defaults to 0, and so the returned array will always have at least 8 undef values at the start. This minor waste allows you to index into the array directly with a KeyCode.
$min_key
save_keymap($display, \@keymap, $min_key, $max_key); save_keymap($display, \@keymap); # to update all keycodes
This is a wrapper around "XChangeKeyboardMapping" that accepts the same array-of-arrays returned by "load_keymap". The first element of the array is assumed to be $min_key unless the array is longer than $max_key in which case the array is assumed to start at 0 and you are requesting that only elements ($min_key .. $max_key) be sent to the X server.
$max_key
($min_key .. $max_key)
Each element of the inner array can be an integer KeySym, or a KeySym name recognized by "XStringToKeysym", or a single Unicode character. If the KeySym is an integer, it must be at least two integer digits, which all real KeySyms should be (other than NoSymbol which has the value 0, and should be represented by undef) to avoid ambiguity with the characters of the number keys. i.e. "4" means "the KeySym for the character 4" rather than the KeySym value 4.
NoSymbol
my $mapping= XGetModifierMapping($display);
Return an arrayref of 8 arrayrefs, one for each modifier group. The inner arrayrefs can contain a variable number of key codes which belong to the modifier group. See X11::Xlib::Keymap for an explanation.
XSetModifierMapping($display, \@modifiers);
@modifiers is an array of 8 arrayrefs, each holding the set of key codes that are part of the modifier. This is the same format as returned by XGetModifierMapping.
@modifiers
XGetModifierMapping
XRefreshKeyboardMapping($mapping_event);
Given a XMappingEvent, reload the internal Xlib cache for the parts of the keymap or modmap which have changed.
The functions below (using the internal Xlib cache) are an alternative to processing the keymap directly.
XLookupString($key_event, $text_out, $keycode_out);
Given a XKeyEvent, translate the key code and modifiers vs. the internal Xlib cached keymap/modmap and write the text name of the key into $text_out. This will either be a name of a key, or the character the key normally generates in a Latin-1 environment. If $keycode_out is given, it will be overwritten with the numeric value of the KeySym.
$text_out
$keycode_out
(If you want to do more than Latin-1, see X11::Xlib::Keymap for utilities to manipulate the keymap directly.)
my $keycode= XKeysymToKeycode($display, $keysym)
Return the key code corresponding to $keysym in the current mapping.
XBell($display, $percent)
Make the X server emit a sound.
XGetKeyboardControl($display, my $state_out);
Returns a XKeyboardState record in $state_out.
$led_mask= $display->keyboard_leds;
Shortcut for reading the led_mask field of XKeyboardState of a call to XGetKeyboardControl.
This is an optional extension. If you have Xcomposite available when this module was installed, then the following functions will be available. None of these functions are exportable.
sudo apt-get install libxcomposite-dev # Debian/Mint/Ubuntu sudo yum install libXcomposite-devel # Fedora/RHEL
my $version_integer= X11::Xlib::XCompositeVersion() if X11::Xlib->can('XCompositeVersion');
my ($event_base, $error_base)= $display->XCompositeQueryExtension if $display->can('XCompositeQueryExtension');
my ($major, $minor)= $display->XCompositeQueryVersion if $display->can('XCompositeQueryVersion');
$display->XCompositeRedirectWindow($window, $update);
$display->XCompositeRedirectSubwindows($window, $update);
$display->XCompositeUnredirectWindow($window, $update);
$display->XCompositeUnredirectSubwindows($window, $update);
my $XserverRegion= $display->XCompositeCreateRegionFromBorderClip($window);
my $pixmap= $display->XCompositeNameWindowPixmap($window);
my $window= $display->XCompositeGetOverlayWindow($window);
$display->XCompositeReleaseOverlayWindow($window);
This is an optional extension. If you have XFixes available when this module was installed, the following functions will be available:
($event_base, $error_base)= $display->XFixesQueryExtension() if $display->can('XFixesQueryExtension');
($major, $minor)= $display->XFixesQueryVersion() if $display->can('XFixesQueryVersion');
$ver= X11::Xlib::XFixesVersion();
The local client library version, independent of the server.
$region_xid= XFixesCreateRegion($display, \@rects);
Given an arrayref of XRectangle, returns the union of all those rects as an XserverRegion (server-side XID). If you want an XserverRegion object, use the method of the Display object.
XFixesDestroyRegion($display, $region);
XFixesSetWindowShapeRegion($display, $window, $shape_kind, $x_ofs, $y_ofs, $region);
Alter the shape of a window (either ShapeInput or ShapeBounding) to match the given region at an offset. The shape is a copy of the region, and does not hold a reference to it. By setting the input shape to an empty region, and using a Visual with alpha channel, you can make a top-level transparent window that does not intercept input events.
ShapeInput
ShapeBounding
This is an optional extension. If you have Xrender available when this module was installed, then the following functions will be available. None of these functions are exportable.
sudo apt-get install libxrender-dev # Debian/Mint/Ubuntu sudo yum install libXrender-devel # Fedora/RHEL
my ($event_base, $error_base)= $display->XRenderQueryExtension() if $display->can('XRenderQueryExtension');
my ($major, $minor)= $display->XRenderQueryVersion() if $display->can('XRenderQueryVersion');
my $pfmt= $display->XRenderFindVisualFormat( $visual );
Takes a X11::Xlib::Visual, and returns a X11::Xlib::XRenderPictFormat.
XLib has a massive number of symbolic constants. This module has an incomplete list, but you can export all of them with
use X11::Xlib ':constants';
You can also export only the named groups that you require, like:
use X11::Xlib qw/ :const_event :const_visual /;
:const_cmap
AllocAll AllocNone
:const_error
BadAccess BadAlloc BadAtom BadColor BadCursor BadDrawable BadFont BadGC BadIDChoice BadImplementation BadLength BadMatch BadName BadPixmap BadRequest BadValue BadWindow Success
BadAccess
BadAlloc
BadAtom
BadColor
BadCursor
BadDrawable
BadFont
BadGC
BadIDChoice
BadImplementation
BadLength
BadMatch
BadName
BadPixmap
BadRequest
BadValue
BadWindow
Success
:const_event
ButtonPress ButtonRelease CirculateNotify ClientMessage ColormapNotify ConfigureNotify CreateNotify DestroyNotify EnterNotify Expose FocusIn FocusOut GraphicsExpose GravityNotify KeyPress KeyRelease KeymapNotify LeaveNotify MapNotify MapRequest MappingNotify MotionNotify NoExpose PropertyNotify ReparentNotify ResizeRequest SelectionClear SelectionNotify SelectionRequest UnmapNotify VisibilityNotify
ButtonPress
ButtonRelease
CirculateNotify
ClientMessage
ColormapNotify
ConfigureNotify
CreateNotify
DestroyNotify
EnterNotify
Expose
FocusIn
FocusOut
GraphicsExpose
GravityNotify
KeyPress
KeyRelease
KeymapNotify
LeaveNotify
MapNotify
MapRequest
MappingNotify
MotionNotify
NoExpose
PropertyNotify
ReparentNotify
ResizeRequest
SelectionClear
SelectionNotify
SelectionRequest
UnmapNotify
VisibilityNotify
:const_event_mask
Button1MotionMask Button2MotionMask Button3MotionMask Button4MotionMask Button5MotionMask ButtonMotionMask ButtonPressMask ButtonReleaseMask ColormapChangeMask EnterWindowMask ExposureMask FocusChangeMask KeyPressMask KeyReleaseMask KeymapStateMask LeaveWindowMask NoEventMask OwnerGrabButtonMask PointerMotionHintMask PointerMotionMask PropertyChangeMask ResizeRedirectMask StructureNotifyMask SubstructureNotifyMask SubstructureRedirectMask VisibilityChangeMask
Button1MotionMask
Button2MotionMask
Button3MotionMask
Button4MotionMask
Button5MotionMask
ButtonMotionMask
ButtonPressMask
ButtonReleaseMask
ColormapChangeMask
EnterWindowMask
ExposureMask
FocusChangeMask
KeyPressMask
KeyReleaseMask
KeymapStateMask
LeaveWindowMask
NoEventMask
OwnerGrabButtonMask
PointerMotionHintMask
PointerMotionMask
PropertyChangeMask
ResizeRedirectMask
StructureNotifyMask
SubstructureNotifyMask
SubstructureRedirectMask
VisibilityChangeMask
:const_ext_composite
CompositeRedirectAutomatic CompositeRedirectManual
CompositeRedirectAutomatic
CompositeRedirectManual
:const_ext_shape
ShapeBounding ShapeClip ShapeInput ShapeIntersect ShapeInvert ShapeSet ShapeSubtract ShapeUnion
ShapeClip
ShapeIntersect
ShapeInvert
ShapeSet
ShapeSubtract
ShapeUnion
:const_input
AnyKey AnyModifier AsyncBoth AsyncKeyboard AsyncPointer Button1Mask Button2Mask Button3Mask Button4Mask Button5Mask ControlMask GrabModeAsync GrabModeSync LockMask Mod1Mask Mod2Mask Mod3Mask Mod4Mask Mod5Mask NoSymbol PointerRoot ReplayKeyboard ReplayPointer RevertToNone RevertToParent RevertToPointerRoot ShiftMask SyncBoth SyncKeyboard SyncPointer XK_VoidSymbol
AsyncBoth
AsyncKeyboard
AsyncPointer
Button1Mask
Button2Mask
Button3Mask
Button4Mask
Button5Mask
PointerRoot
ReplayKeyboard
ReplayPointer
SyncBoth
SyncKeyboard
SyncPointer
XK_VoidSymbol
:const_sizehint
PAspect PBaseSize PMaxSize PMinSize PPosition PResizeInc PSize PWinGravity USPosition USSize
PAspect
PBaseSize
PMaxSize
PMinSize
PPosition
PResizeInc
PSize
PWinGravity
USPosition
USSize
:const_visual
VisualAllMask VisualBitsPerRGBMask VisualBlueMaskMask VisualClassMask VisualColormapSizeMask VisualDepthMask VisualGreenMaskMask VisualIDMask VisualRedMaskMask VisualScreenMask
VisualAllMask
VisualBitsPerRGBMask
VisualBlueMaskMask
VisualClassMask
VisualColormapSizeMask
VisualDepthMask
VisualGreenMaskMask
VisualIDMask
VisualRedMaskMask
VisualScreenMask
:const_win
Above AnyPropertyType Below BottomIf CenterGravity CopyFromParent EastGravity ForgetGravity InputOnly InputOutput LowerHighest NorthEastGravity NorthGravity NorthWestGravity Opposite PropModeAppend PropModePrepend PropModeReplace RaiseLowest SouthEastGravity SouthGravity SouthWestGravity StaticGravity TopIf UnmapGravity WestGravity
Above
AnyPropertyType
Below
BottomIf
CenterGravity
CopyFromParent
EastGravity
ForgetGravity
InputOnly
InputOutput
LowerHighest
NorthEastGravity
NorthGravity
NorthWestGravity
Opposite
RaiseLowest
SouthEastGravity
SouthGravity
SouthWestGravity
StaticGravity
TopIf
UnmapGravity
WestGravity
:const_winattr
CWBackPixel CWBackPixmap CWBackingPixel CWBackingPlanes CWBackingStore CWBitGravity CWBorderPixel CWBorderPixmap CWBorderWidth CWColormap CWCursor CWDontPropagate CWEventMask CWHeight CWOverrideRedirect CWSaveUnder CWSibling CWStackMode CWWidth CWWinGravity CWX CWY
CWBackPixel
CWBackPixmap
CWBackingPixel
CWBackingPlanes
CWBackingStore
CWBitGravity
CWBorderPixel
CWBorderPixmap
CWBorderWidth
CWColormap
CWCursor
CWDontPropagate
CWEventMask
CWHeight
CWOverrideRedirect
CWSaveUnder
CWSibling
CWStackMode
CWWidth
CWWinGravity
CWX
CWY
:const_x
Xlib has a lot of C structs. Most of them do not have much "depth" (i.e. pointers to further nested structs) and so I chose to represent them as simple blessed scalar refs to a byte string. This gives you the ability to pack new values into the struct which might not be known by this module, and keeps the object relatively lightweight. Most also have a pack and unpack method which convert from/to a hashref. Sometimes however these structs do contain a raw pointer value, and so you should take extreme care if you do modify the bytes.
pack
unpack
Xlib also has a lot of opaque pointers where they just give you a pointer and some methods to access it without any explanation of its inner fields. I represent these with the matching Perl feature for blessed opaque references, so the only way to interact with the pointer value is through XS code. In each case, when the object goes out of scope, this library calls any appropriate "Free" function.
Finally, there are lots of objects which exist on the server, and Xlib just gives you a number ("XID") to refer to them when making future requests. Windows are the most common example. Since these are simple integers, and can be shared among any program connected to the same display, this module allows a mix of simple scalar values or blessed objects when calling any function that expects an XID. The blessed objects derive from X11::Xlib::XID.
XID
Most supported structures have their own package with further documentation, but here is a quick list:
Represents a connection to an X11 server. Xlib provides an opaque pointer Display* on which you can call methods. These are represented by this package, X11::Xlib. The X11::Xlib::Display package provides a more perl-ish interface and some helper methods to "DWIM".
Display*
The Xlib Screen* is not exported by this module, since most methods that use a Screen* have a matching method that uses a Display*. If you are using the object-oriented Display you then get Screen objects for convenience, but they are just a wrapper around the Display and screen number instead of screen pointer.
Screen*
An opaque pointer describing binary representation of pixels for some mode of the display. There's probably only one in use on the entire display (i.e. RGBA) but Xlib makes you look it up and pass it around to various functions.
A more useful struct describing a Visual. See X11::Xlib::XVisualInfo.
A struct that can hold any sort of message sent to/from the server. The struct is a union of many other structs, which you can read about in X11::Xlib::XEvent.
An XID referencing what used to be a palette for 8-bit graphics but which is now mostly a useless appendage to be passed to "XCreateWindow". When using the object-oriented Display, these are wrapped by X11::Xlib::Colormap.
Display
An XID referencing a rectangular pixel buffer. Has dimensions and color depth and is bound to a "Screen". Can be used for copying images, or tiling. When using the object-oriented Display, these are wrapped by X11::Xlib::Pixmap.
An XID referencing a Window. Used for painting, event/input delivery, and having data tagged to them. Not abused nearly as much as the Win32 API abuses its Window structures. See X11::Xlib::Window for details.
Error handling in Xlib is pretty bad. The first problem is that non-fatal errors are reported asynchronously in an API masquerading as if they were synchronous function calls. This is mildly annoying. This library eases the pain by giving you a nice XEvent object to work with, and the ability to deliver the errors to a callback on your display or window object.
The second much larger problem is that fatal errors (like losing the connection to the server) cause a mandatory termination of the host program. Seriously. The default behavior of Xlib is to print a message and abort, but even if you install the C error handler to try to gracefully recover, when the error handler returns Xlib still kills your program. Under normal circumstances you would have to perform all cleanup with your stack tied up through Xlib, but this library cheats by using croak (longjmp) to escape the callback and let you wrap up your script in a normal manner. However, after a fatal error Xlib's internal state could be damaged, so it is unsafe to make any more Xlib calls. This library tries to help enforce that by invalidating all the connection objects.
longjmp
If you really need your program to keep running your best bet is to state-dump to shared memory and then exec() a fresh copy of your script and reload the dumped state. Or use XCB instead of Xlib.
exec()
Xlib libraries are found on most graphical Unixes, but you might lack the header files needed for this module. Try the following:
sudo apt-get install libxtst-dev # and you probably want the optional deps, too sudo apt-get install libxcomposite-dev libxrender-dev libxfixes-dev
sudo yum install libXtst-devel # and you probably want the optional deps, too sudo yum install libXcomposite-devel libXrender-devel libXfixes-devel
This module provides a higher-level API for X input simulation and testing.
Functions provided by X11/Xlib are mostly included in the Gtk2 binding, but through the GTK API and perl objects.
Pure-perl implementation of the X11 protocol.
This module still only covers a small fraction of the Xlib API. Patches are welcome :)
Olivier Thauvin, <nanardon@nanardon.zarb.org>
Michael Conrad, <mike@nrdvana.net>
Mohammad S Anwar <mohammad.anwar@yahoo.com>
Mark Davies <eslafgh@users.noreply.github.com>
Paul Seyfert <pseyfert.mathphys@gmail.com>
Ethan Straffin <ethanstraffin@gmail.com>
Sergei Zhmylev <zhmylove@cpan.org>
H.Merijn Brand <hmbrand@cpan.org>
Copyright (C) 2009-2010 by Olivier Thauvin
Copyright (C) 2017-2023 by Michael Conrad
This library is free software; you can redistribute it and/or modify it under the same terms as Perl itself, either Perl version 5.10.0 or, at your option, any later version of Perl 5 you may have available.
To install X11::Xlib, copy and paste the appropriate command in to your terminal.
cpanm
cpanm X11::Xlib
CPAN shell
perl -MCPAN -e shell install X11::Xlib
For more information on module installation, please visit the detailed CPAN module installation guide.