Skip site navigation (1)Skip section navigation (2)

FreeBSD Manual Pages

  
 
  

home | help
X11::Xlib::Display(3) User Contributed Perl DocumentationX11::Xlib::Display(3)

NAME
       X11::Xlib::Display - Object-Oriented behavior for X11::Xlib

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

ATTRIBUTES
   connection_fh
       Return the file handle to the X11 connection.  Useful for "select".

   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
       Number of the default screen

   default_screen
       Alias for "$display->screen( $display->default_screen_num )".

   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.

METHODS
   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
       wait_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
       The following convenience methods pass-through to the default screen
       object:

       o   root_window

       o   width

       o   height

       o   width_mm

       o   height_mm

       o   visual

       o   depth

       o   colormap

   VISUAL/COLORMAP
       visual_info

	 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
       new_colormap

	 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
       keymap

	 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
       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 weren't
       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.

       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

AUTHOR
       Olivier Thauvin,	<nanardon@nanardon.zarb.org>

       Michael Conrad, <mike@nrdvana.net>

COPYRIGHT AND LICENSE
       Copyright (C) 2009-2010 by Olivier Thauvin

       Copyright (C) 2017 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.

perl v5.32.1			  2018-06-06		 X11::Xlib::Display(3)

NAME | DESCRIPTION | ATTRIBUTES | METHODS | AUTHOR | COPYRIGHT AND LICENSE

Want to link to this manual page? Use this URL:
<https://www.freebsd.org/cgi/man.cgi?query=X11::Xlib::Display&sektion=3&manpath=FreeBSD+13.1-RELEASE+and+Ports>

home | help