connection_fh

screen_count

   for (0 .. $display->screen_count - 1) { ... }

Number of screens available on this display.

screen

   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.

default_screen_num

default_screen

on_error

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

new

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

If you pass a list or hashref of arguments, you can specify the connection string as "connect".

If the call to "XOpenDisplay" fails, this constructor dies.

COMMUNICATION/EVENT

  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.

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

Returns an X11::Xlib::XEvent on success, or undef on timeout or interruption.

send_event

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

putback_event

  $display->putback_event($event);

"un-get" or "unshift" an event back onto your own message queue.

flush

Push any queued messages to the X server.

flush_sync

Push any queued messages to the X server and wait for all replies.

flush_sync_discard

Push any queued messages to the server, wait for replies, and then delete the entire input event queue.

fake_motion

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

fake_button

  $display->fake_button($button_number, $is_press, $send_delay = 10);

Generate a fake mouse button press or release.

fake_key

  $display->fake_key($key_code, $is_press, $send_delay = 10);

Generate a fake key press or release. See "EXAMPLES" in X11::Xlib::Keymap.

SCREEN

• root_window
• width
• height
• width_mm
• height_mm
• visual
• depth
• colormap

VISUAL/COLORMAP

  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.

match_visual_info

  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.

search_visual_info

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

RESOURCE CREATION

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

new_pixmap

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

new_window

  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.

XCreateWindow

Like "XCreateWindow" in X11::Xlib, but returns a X11::Xlib::Window object.

XCreateSimpleWindow

Like X11::Xlib::XCreateSimpleWindow, but returns a X11::Xlib::Window object.

INPUT

  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.

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.

keyboard_leds

  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)

CACHE MANAGEMENT

There is also a cache of wrapper objects of the opaque pointers allocated for a display. This cache is private.

get_cached_xobj

  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.

get_cached_colormap

  my $colormap= $display->get_cached_colormap($xid, @new_args);

Shortcut for "get_cached_xobj" that implies a class of X11::Xlib::Colormap

get_cached_pixmap

  my $pixmap= $display->get_cached_pixmap($xid, @new_args);

Shortcut for "get_cached_xobj" that implies a class of X11::Xlib::Pixmap

get_cached_window

  my $window= $display->get_cached_window($xid, @new_args);

Shortcut for "get_cached_xobj" that implies a class of X11::Xlib::Window