X11::Xlib::Display - Object-Oriented behavior for X11::Xlib
This subclass of X11::Xlib provides perl-ish Object-Oriented behavior for the API of Xlib. Calling methods like XCreateWindow return Window objects instead of integer XIDs. It also contains a number of friendly helper methods that wrap the Xlib API in a more intuitive manner.
Return the file handle to the X11 connection. Useful for select.
select
for (0 .. $display->screen_count - 1) { ... }
Number of screens available on this display. Note that this is an antiquated concept of a "screen" and is always 1 on modern desktop systems, no matter how many monitors you have connected. Adding support for the xrandr extension is a TODO.
1
my $screen= $display->screen(); # alias for $display->default_screen my $screen= $display->screen(3); # get some specific screen
Get a X11::Xlib::Screen object, to query per-screen attributes.
Number of the default screen
Alias for $display->screen( $display->default_screen_num ).
$display->screen( $display->default_screen_num )
$display->on_error(sub { my ($display, $event)= @_; if ($event) { # inspect $event (instance of XEvent) and handle/log as appropriate } else { # Fatal Xlib error, perform cleanup and prepare for program exit } });
See "on_error" in X11::Xlib.
my $display= X11::Xlib::Display->new(); # uses $ENV{DISPLAY} my $display= X11::Xlib::Display->new( $connect_string ); my $display= X11::Xlib::Display->new( connect => $connect_string, %attributes );
Create a new connection to an X11 server.
If you pass a single non-hashref argument, it is given to XOpenDisplay. If you omit the connect_string, it uses $ENV{DISPLAY}.
$ENV{DISPLAY}
If you pass a list or hashref of arguments, you can specify the connection string as connect.
connect
If the call to XOpenDisplay fails, this constructor dies.
XOpenDisplay
my $event= $display->wait_event( window => $window, event_type => $type, event_mask => $mask, timeout => $seconds, loop => $bool_keep_trying, );
Each argument is optional. If you specify window, it will only return events for that window. If you specify event_mask, it will limit which types of event can be returned. if you specify event_type, then only that type of event can be returned.
window
event_mask
event_type
timeout is a number of seconds (can be fractional) to wait for a matching event. If timeout is zero, the function acts like XCheckEvent and returns immediately. If timeout is not specified the function will wait indefinitely. However, the wait is always interrupted by pending data from the X11 server, or signals, so in practice the wait won't be very long and you should call it in an appropriate loop. Or, if you want this module to take care of that detail, add "loop => 1" to the arguments and then wait_event will wait up to the full timeout before returning false.
timeout
XCheckEvent
Returns an X11::Xlib::XEvent on success, or undef on timeout or interruption.
$display->send_event( $xevent, window => $wnd, propagate => $bool, event_mask => $mask );
propogate defaults to true. window defaults to the window field of the event. event_mask must be specified but eventually I want to have it auto- calculate from the event type.
propogate
$display->putback_event($event);
"unget" or "unshift" an event back onto your own message queue.
Push any queued messages to the X server.
Push any queued messages to the X server and wait for all replies.
Push any queued messages to the server, wait for replies, and then delete the entire input event queue.
$display->warp_pointer($dest_win, $dest_x, $dest_y); $display->warp_pointer($dest_win, $dest_x, $dest_y, $src_win, $src_rect);
Move the pointer to ($dest_x,$dest_y) relative to $dest_win, or relative to current position if $dest_win is undef. If the $src_ parameters are defined, the operation only proceeds if the pointer is currently within that rectangle of the source window. If the width or height of the rectangle are zero, they are treated as the remaining width/height of the window beyond the (x,y).
($dest_x,$dest_y)
$dest_win
$src_
$src_rect can be given as [ $x, $y, $width, $height ] or an object with those attributes, such as X11::Xlib::XRectangle.
$src_rect
[ $x, $y, $width, $height ]
$display->fake_motion($screen, $x, $y, $send_delay = 10);
Generate a fake motion event on the server, optionally waiting $send_delay milliseconds. If $screen is -1, it references the screen which the mouse is currently on.
$send_delay
$screen
$display->fake_button($button_number, $is_press, $send_delay = 10);
Generate a fake mouse button press or release.
$display->fake_key($key_code, $is_press, $send_delay = 10);
Generate a fake key press or release. See "EXAMPLES" in X11::Xlib::Keymap.
my $atom= $display->atom('UTF8_STRING'); my @list= $display->atom(@names); say $_ for $display->atom(1..50);
This is a wrapper around XInternAtom and XGetAtomName which operates on lists and returns dualvar values that show a helpful string for debugging but still work in numeric contexts. It only finds existing atoms, returning undef for each element that was not found.
undef
Note that the direction of the lookup (name to number, or number to name) depends on whether the item is declared as an integer and/or matches /^[0-9]+\z/.
/^[0-9]+\z/
Like atom, but creates any atoms that did not exist. However, it still expects that strings matching /^[0-9]+\z/ are intended for reverse lookup, and cannot be used to create atoms whose names are digits. (X server allows names that are numbers, but it seems like a bad idea)
atom
The following convenience methods pass-through to the default screen object:
my $info= $display->visual_info(); # for default visual of default screen my $info= $display->visual_info($visual); my $info= $display->visual_info($visual_id);
Returns a X11::Xlib::XVisualInfo for the specified visual, or undef if none was found. See "Visual" in X11::Xlib for an explanation of the different types of object.
my $info= $display->match_visual_info($screen_num, $color_depth, $class) or die "No matching visual";
Search for a visual on $scren_num that matches the color depth and class.
$scren_num
# Search all visuals... my @infos= $display->search_visual_info( visualid => $id, screen => $screen, depth => $depth, class => $class, red_mask => $mask, green_mask => $mask, blue_mask => $mask, colormap_size => $size, bits_per_rgb => $n, );
Search for a visual by any of its X11::Xlib::XVisualInfo members. You can specify as many or as few fields as you like.
Same as "XGetVisualInfo" in X11::Xlib, but when called as a method the returned structs contain a display attribute referencing the current Display object.
display
my $cmap= $display->new_colormap($rootwindow, $visual, $alloc_flag);
Creates a new Colormap on the server, and wraps it with a X11::Xlib::Colormap object to track its lifespan. If the object goes out of scope it calls XFreeColormap.
$rootwindow defaults to the root window of the default screen. $visual defaults to the visual of the root window. $allocFlag defaults to AllocNone.
$rootwindow
$visual
$allocFlag
AllocNone
my $pix= $display->new_pixmap($drawable, $width, $height, $color_depth);
Create a new Pixmap on the server, and wrap it with a X11::Xlib::Pixmap object to track its lifespan. If the object goes out of scope it calls XFreePixmap.
$drawable's only purpose is to determine which screen to use, and so it may also be a Screen object. $width $height and $color_depth should be self-explanatory.
$drawable
$width
$height
$color_depth
my $win= $display->new_window( parent => $window, class => $input_type, visual => $visual, colormap => $colormap, depth => $color_depth, event_mask => $mask, do_not_propagate_mask => $mask, override_redirect => $bool, x => $x, y => $y, width => $n_pix, height => $n_pix, min_width => $n_pix, min_height => $n_pix, max_width => $n_pix, max_height => $n_pix, width_inc => $n_pix, height_inc => $n_pix, min_aspect_x => $numerator, min_aspect_y => $denominator, max_aspect_x => $numerator, max_aspect_y => $denominator, base_width => $width, base_height => $height, bit_gravity => $val, win_gravity => $val, cursor => $cursor, border_width => $n_pix, background_pixmap => $pixmap, background_pixel => $color_int, border_pixmap => $pixmap, border_pixel => $color_int, backing_store => $val, backing_planes => $n_planes, backing_pixel => $color_int, save_under => $bool, );
This method takes any argument to the XCreateWindow function and also any of the fields of the X11::Xlib::XSetWindowAttributes struct or X11::Xlib::XSizeHints. This saves you the trouble of calculating the attribute mask, and of a second call to SetWMNormalHints if you wanted to set those fields.
It first calls "XCreateWindow", which returns an XID, then wraps it with a X11::Xlib::Window object (which calls XDestroyWindow if it goes out of scope), then calls SetWMNormalHints if you specified any of those fields.
XDestroyWindow
SetWMNormalHints
my $keymap= $display->keymap; # lazy-loaded instance of X11::Xlib::Keymap
X11 Operates on keyboard scan codes, and leaves interpreting them to the client. The server holds a mapping table of scan codes and modifiers which all clients share and can modify as needed, though the X server never uses the table itself. The details are hairy enough that I moved them to their own module. See X11::Xlib::Keymap for details.
The first time you access keymap it fetches the tables from the server. The tables may change on the fly, so you should watch for MappingNotify events to know when to reload the keymap.
keymap
Note that if you only need Latin-1 translation of key codes, you can just use "XLookupString" in X11::Xlib and "XRefreshKeyboardMapping" in X11::Xlib to have Xlib do all the heavy lifting.
my $bits= $display->keyboard_leds; printf("LED 1 is %s\n", $bits & 1? "lit" : "not lit");
Return an integer mask value for the currently-lit keyboard LEDs. Each LED gets one bit of the integer, starting from the least significant. (The docs make no mention of the meaning of each LED)
The Display object keeps weak references to the wrapper objects it creates so that if you fetch the same resource again, you get the same object instance as last time. These methods are made public so that you can get the same behavior when working with XIDs that were not already wrapped by this module.
There is also a cache of wrapper objects of the opaque pointers allocated for a display. This cache is private.
my $obj= $display->get_cached_xobj( $xid, $class, @new_args );
If $xid already references an object, return that object. Else create a new object of type $class and initialize it with the list of arguments. If $class is not given it defaults to X11::Xlib::XID.
$xid
$class
my $colormap= $display->get_cached_colormap($xid, @new_args);
Shortcut for "get_cached_xobj" that implies a class of X11::Xlib::Colormap
The following X11::Xlib functions return Colomap objects when called as methods on a Display object:
my $pixmap= $display->get_cached_pixmap($xid, @new_args);
Shortcut for "get_cached_xobj" that implies a class of X11::Xlib::Pixmap
The following X11::Xlib functions return Pixmap objects when called as methods of a Display object:
my $window= $display->get_cached_window($xid, @new_args);
Shortcut for "get_cached_xobj" that implies a class of X11::Xlib::Window
The following X11::Xlib functions return Window objects when called as methods of a Display object:
my $window= $display->get_cached_region($xid, @new_args);
Shortcut for "get_cached_xobj" that implies a class of X11::Xlib::XserverRegion.
The following X11::Xlib functions return XserverRegion objects when called as methods of a Display object:
Olivier Thauvin, <nanardon@nanardon.zarb.org>
Michael Conrad, <mike@nrdvana.net>
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.