NAME

X11::Protocol::Enhanced - bit mask enhancements for X11::Protocol

SYNOPSIS

 use X11::Protocol;
 use X11::Protocol::Enhanced;

 # just to define 'Rotation' type:
 my $X = X11::Protocol->new();
 $X->init_extension('RANDR') or die "Cannot initialize RANDR!";

 my $mask = $X->pack_mask(Rotation=>qw(Rotate_0 Reflect_X));
 my %mask = $X->unpack_mask(Rotation=>$mask);
 print "Bits set are: ",join(',',keys %mask),"\n";

DESCRIPTION

This module is used by a number of protocol extensions to enhance the enumeration and bit mask handling of the X11::Protocol(3pm) object. It does this by adding or overriding a number of methods on the X11::Protocol(3pm) module when it loads.

METHODS

X11::Protocol(3pm) does not provide a way to pack and unpack masks using symbolic constants, except for event masks. X11::Protocol::Ext::KEYBOARD uses so many masks that either we needed to define bitmap mask constants in perl, or we needed a way to pack and unpack masks. To provide this capability, the X11::Protocol::Enhanced module adds the following methods to the X11::Protocol(3pm) object:

$mask = $X->pack_mask($typename,\@constants)

Where, $typename is a symbolic constant type name like Bool or XkbControl, and \@constants is a list (array ref) of symbolic constants defined for $typename or bit numbers. pack_mask returns a numeric value representing the mask with the appropriate bits set. When \@constants is a scalar value, the value is simply returned.

This function is similar to pack_event_mask with the exception that it can be used where $typename is not equal to 'EventMask'.

pack_mask is called by the request functions in this module on may of the arguments passed into the request. Therefore, the arguments passed to the request can either be the numeric bit mask, or can be an array or hash of bit values.

%mask = $X->unpack_mask($typename,$mask)

Where, $typename is a symbolic constant type name like Bool or XkbBoolCtrl, and $mask is a numerical representation of the bit mask. The bit positions in the number are converted into a HASH where the keys of the hash are the symbolic names of the bits set to 1 or the bit number when no symbolic name for the bit appears in $typename. The value associated with the key is always 1. The HASH is returned.

If you would prefer the ARRAY form as was passed to pack_mask, this trick will do:

  %mask = $X->unpack_mask($typename,$mask);
  @mask = keys %mask;

Masks are not automatically unpacked by the event routines, nor for responses to requests. You will need to unpack returned fields yourself using this function. Refer to the specification to see which symbolic constant $typename to use when unpacking.

$mask = $X->interp_mask($typename,$mask)

Like unpack_mask, but only interprets the mask when the do_interp_mask flag is set on $X.

$num = $X->pack_enum($typename,$nameornum)

$num = $X->num($typename,$nameornum)

Where $typename is a symbolic constant type name like Bool or XkbBoolCtrl, and $nameornum is a symbolic constant name under $typename or a simple number. The number corresponding to the symbolic constant name is returned.

X11::Protocol::Enhanced also overrides the X11::Protocol(3pm) num method with this method. (The X11::Protocol(3pm) num method cannot handle special names for only a few values.>

$nameornum = $X->unpack_enum($typename,$num)

$nameornum = $X->do_interp($typename,$num)

Where $typename is a symbolic constnat type name like Bool or XkbControl, and $num is a simple number. The name corresponding ot the symbolic constant is returned if it is defined, and the number is returned otherwise.

X11::Protocol::Enhanced also overrides the X11::Protocol(3pm) do_interp method with this method. (The X11::Protocol(3pm) do_interp method cannot handle special names for only a few values.>

$nameornum = $X->interp_enum($typename,$num)

$nameornum = $X->interp($typename,$num)

Like unpack_enum, but only unpacks the enumeration when the do_interp flag is set on $X.

X11::Protocol::Enhanced also overrides the X11::Protocol(3pm) interp method with this method. (The X11::Protocol(3pm) method cannot handle special names for only a few values.)

AUTHOR

Brian Bidulock <bidulock@cpan.org>

SEE ALSO

X11::Protocol(3pm), X11::Protocol::Ext::XKEYBOARD(3pm), X11::Protocol::Ext::RANDR(3pm), X11::Protocol::Ext::SYNC(3pm).