NAME

X11::Xlib::Window - XID wrapper for Window

SYNOPSIS

  use X11::Xlib;
  my $display = X11::Xlib->new();
  my $window = $display->RootWindow();
         ... = $display->get_cached_window(1234);

METHODS

(see X11::Xlib::XID for inherited methods/attributes)

attributes

Calls "XGetWindowAttributes" in X11::Xlib, caches the result, and returns the instance of X11::Xlib::XWindowAttributes.

clear_all

Clear any cached value of the window so that the next access loads it fresh from the server.

get_property_list

  for ($window->get_property_list) { ... }

Returns a list of all properties available on the window. Each property is an atom dualvar that stringifies as the property name but can be passed to functions that expect the ID.

get_property

  $window->get_property($prop_atom);
  $window->get_property($prop_atom, $type_atom, $offset, $max_len);

  # {
  #   type => $atom,   # actual type of property
  #   count => 1,      # number of elements in multi-values property
  #   format => $n,    # 8/16/32 meaning 'char','short','long'
  #   remaining => $n, # bytes unread
  #   data => $bytes,  # payload, needs unpack()ed except for strings
  # }

Return a hashref describing a property, or undef if the property does not exist.

get_decoded_property

  my $prop= $window->get_decoded_property($prop_atom);
                ...->get_decoded_property($prop_atom, $type_atom);

This fetches a property and attempts to decode it into the best Perl representation. If the returned type is not known this throws an exception; you'll have to use get_property and decode it yourself.

For strings, this returns a single scalar. For decoded objects, this returns one object or an arrayref of objects. So, you always get one return value, or undef.

For conveniently unrolling this into list context, use get_decoded_property_items.

get_decoded_property_items

  my @items= $window->get_decoded_property_items($prop_atom, $type_atom=Any);
  
  # Example: dump out all properties of the window
  for my $prop ($window->get_property_list) {
    eval { say join " ", $prop, "=", $window->get_decoded_property_items($prop); }
      or say "$prop: Cant decode ".$window->get_property($prop)->{type};
  }

The return value is a list, since many properties are multi-value but many are single-value, and there's no good way to know which properties are intended as arrays with one element.

set_property

  $window->set_property($prop_atom, $type_atom, $data, $format, $count);
  $window->set_property($prop_atom, $type_atom, \@value); # for known types
  $window->set_property($prop_atom, undef);  # delete the property

In the first form, the parameters basically just go to "XChangeProperty" in X11::Xlib after supplying defaults for size and count. $item_size must be 8, 16, or 32 (which means 'long' regardless of whether long is 32 bits), and count can be given or derived from the length of $data.

In the second form, a known $type_atom may have special support for encoding an array of arguments. The arguments must be given in an array to indicate the user wants some support in packing them.

In the third form, undefined type results in the deletion of the property.

get_w_h

  my ($w, $h)= $window->get_w_h

Return width and height of the window by calling XGetGeometry. This never uses a cache and always returns the current size of the window, since often it has been altered by window managers etc.

For a cached value, just use $window->attributes->width etc.

show

  $win->show;
  $win->show(1);
  $win->show(0);  # equivalent to 'hide'

Calls XMapWindow to request that the X server display the window.

You can pass a boolean argument to conditionally call "hide" instead.

hide

Calls XUnmapWindow to request the window be hidden.

event_mask

  my $current_mask= $window->event_mask;
  $window->event_mask( $current_mask | SubstructureRedirectMask );

Get or set the event mask. Reading this value may return cached data, or else cause a call to XGetWindowAttibutes. Setting the event mask uses XSelectInput, and updates the cache.

event_mask_include

  $window->event_mask_include( @event_masks );

Read the current event mask (unless cached already), then bitwise OR it with each parameter, then set the mask on the window if anything changed.

event_mask_exclude

  $window->event_mask_exclude( @event_masks );

Read the current event mask (unless cached already), then bitwise AND NOT with each parameter, then set the mask on the window if anything changed.

set_bounding_region

  $window->set_bounding_region($region);
  $window->set_bounding_region($region, $x_ofs, $y_ofs);

Set the region for the boundary of the window, optionally offset by an (x,y) coordinate. $region may be undef or 0 to unset the region.

set_input_region

  $window->set_input_region($region);
  $window->set_input_region($region, $x_ofs, $y_ofs);

Set the input "hit" region of the window, optionally offset by an (x,y) coordinate. $region may be undef or 0 to unset the region.

SEE ALSO

X11::Xlib

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

cpanm X11::Xlib

perl -MCPAN -e shell
install X11::Xlib