NAME

X11::Protocol::Ext::XKEYBOARD -- Perl extension module for X Keyboard Extension Protocol

SYNOPSIS

use X11::Protocol;
$x = X11::Protocol->new($ENV{DISPLAY});
$x->init_extension('XKEYBOARD') or die;

DESCRIPTION

This module is used by the X11::Protocol(3pm) module to participat in the keboard extension to the X protocol, allowing the client to control the keyboard and other input devices, per the "X Keyboard Extension Protocol Specification", a copy of which can be obtained from http://www.x.org/releases/X11R7.7/doc/kbproto/xkbproto.pdf.

This manual page does not attempt to document the protocol itself, see the specification for that. It documents the "CONSTANTS", "EVENTS" and "ERRORS" that are added to the X11::Protocol(3pm) module.

EVENTS

XKEYBOARD multiplexes one base event number with the xkb-code field. Therefore, X11::Protocol::Ext::XKEYBOARD provides the following single event type: XkbNotify, the fields of which depend on the value of the xkb_code field (which is of type XkbEventType). This field can have the value:

XkbEventType => XkbNewKeyboardNotify XkbMapNotify XkbStateNotify
    XkbControlsNotify XkbIndicatorStateNotify XkbIndicatorMapNotify
    XkbNamesNotify XkbCompatMapNotify XkbBellNotify XkbActionNotify
    XkbAccessXNotify XkbExtensionDeviceNotify

XkbNewKeyboardNotify

The unpacked XkbNewKeyboardNotify event contains the following fields in the event hash:

XkbNewKeyboardNotify => {
    xkb_code           => $code,
    time               => $time,
    deviceID           => $deviceid,
    oldDeviceID        => $deviceid,
    minKeyCode         => $keycode,
    maxKeyCode         => $keycode,
    oldMinKeyCode      => $keycode,
    oldMaxKeyCode      => $keycode,
    requestMajor       => $major,
    requestMinor       => $minor,
    changed            => $XkbNKNDetail} # mask

XkbMapNotify

The unpacked XkbMapNotify event contains the following fields in the event hash:

XkbMapNotify => {
    xkb_code           => $code,
    time               => $time,
    deviceId           => $deviceid,
    ptrBtnActions      => $XkbButMask, # 8-bit bit mask
    changed            => $XkbMapPart, # mask
    minKeyCode         => $keycode,
    maxKeyCode         => $keycode,
    firstType          => $type,
    nTypes             => $ntypes,
    firstKeySym        => $keysym,
    nKeySyms           => $nkeysyms,
    firstKeyAct        => $keyact,
    nKeyActs           => $nkeyacts,
    firstKeyBehavior   => $behave,
    nKeyBehavior       => $nbehave,
    firstKeyExplicit   => $keyexp,
    nKeyExplicit       => $nkeyexp,
    firstModMapKey     => $modmapkey,
    nModMapKeys        => $nmodmapkey,
    firstVModMapKey    => $vmodmapkey,
    nVModMapKeys       => $nvmodmapkey,
    virtualMods        => $XkbVMod}    # mask

XkbStateNotify

The unpacked XkbStateNotify event contains the following fields in the event hash:

XkbStateNotify => {
    xkb_code           => $code,
    time               => $time,
    deviceID           => $deviceid,
    mods               => $XkbKeyMask,     # mask
    baseMods           => $XkbKeyMask,     # mask
    latchedMods        => $XkbKeyMask,     # mask
    lockedMods         => $XkbKeyMask,     # mask
    group              => $XkbGroup,
    baseGroup          => $group,
    latchedGroup       => $group,
    lockedGroup        => $XkbGroup,
    compatState        => $XkbKeyMask,     # mask
    grabMods           => $XkbKeyMask,     # mask
    compatGrabMods     => $XkbKeyMask,     # mask
    lookupMods         => $XkbKeyMask,     # mask
    compatLookupMods   => $XkbKeyMask,     # mask
    ptrBtnState        => $butmask,
    changed            => $XkbStatePart,   # mask
    keycode            => $keycode,
    eventType          => $eventtype,
    requestMajor       => $major,
    requestMinor       => $minor}

XkbControlsNotify

The unpacked XkbControlsNotify event contains the following fields in the event hash:

XkbControlsNotify => {
    xkb_code           => $code,
    time               => $time,
    deviceID           => $deviceid,
    numGroups          => $numgroups,
    changedControls    => $XkbControl,     # mask
    enabledControls    => $XkbBoolCtrl,    # mask
    enabledControlChanges => $XkbBoolCtrl, # mask
    keycode            => $keycode,
    eventType          => $eventttype,
    requestMajor       => $major,
    requestMinor       => $minor}

XkbIndicatorStateNotify

The unpacked XkbIndicatorStateNotify event contains the following fields in the event hash:

XkbIndicatorStateNotify => {
    xkb_code           => $code,
    time               => $time,
    deviceID           => $deviceid,
    state              => $XkbIndicator, # 32-bit bit mask
    stateChanged       => $XkbIndicator} # 32-bit bit mask

XkbIndicatorMapNotify

The unpacked XkbIndicatorMapNotify event contains the following fields in the event hash:

XkbIndicatorMapNotify => {
    xkb_code           => $code,
    time               => $time,
    deviceID           => $deviceid,
    state              => $XkbIndicator, # 32-bit bit mask
    mapChanged         => $XkbIndicator} # 32-bit bit mask

XkbNamesNotify

The unpacked XkbNamesNotify event contains the following fields in the event hash:

XkbNamesNotify => {
    xkb_code           => $code,
    time               => $time,
    deviceID           => $deviceid,
    changed            => $XkbNameDetail,  # mask
    firstType          => $type,
    nTypes             => $ntypes,
    firstLevelName     => $level,
    nLevelNames        => $nlevels,
    nRadioGroups       => $ngroups,
    nKeyAliases        => $naliases,
    changedGroupNames  => $XkbKbGroup,     # mask
    changedVirtualMods => $XkbVMod,        # mask
    firstKey           => $keycode,
    nKeys              => $nkeys,
    changedIndicators  => $XkbIndicator}   # 32-bit bit mask

XkbCompatMapNotify

The unpacked XkbCompatMapNotify event contains the following fields in the event hash:

XkbCompatMapNotify => {
    xkb_code           => $code,
    time               => $time,
    deviceID           => $deviceid,
    changedGroups      => $XkbKbGroup,     # mask
    firstSI            => $firstsi,
    nSI                => $nsi,
    nTotalSI           => $ntotalsi}

XkbBellNotify

The unpacked XkbBellNotify event contains the following fields in the event hash:

XkbBellNotify => {
    xkb_code           => $code,
    time               => $time,
    deviceID           => $deviceid,
    bellClass          => $XkbBellClassResult,
    bellID             => $bellid,
    percent            => $percent,
    pitch              => $pitch,
    duration           => $duration,
    bell_name          => $atom,  # 'name' would conflict
    window             => $window,
    eventOnly          => $Bool}

XkbActionMessage

The unpacked XkbActionMessage event contains the following fields in the event hash:

XkbActionMessage => {
    xkb_code           => $code,
    time               => $time,
    deviceID           => $deviceid,
    keycode            => $keycode,
    press              => $Bool,
    keyEventFollows    => $Bool,
    mods               => $XkbKeyMask,     # mask
    group              => $XkbGroup,
    message            => $message}

XkbAcessXNotify

The unpacked XkbAcessXNotify event contains the following fields in the event hash:

XkbAcessXNotify => {
    xkb_code           => $code,
    time               => $time,
    deviceID           => $deviceid,
    keycode            => $keycode,
    detail             => $XkbAXNDetail,   # mask
    slowKeysDelay      => $delay,
    debounceDelay      => $delay}

XkbExtensionDeviceNotify

The unpacked XkbExtensionDeviceNotify event contains the following fields in the event hash:

XkbExtensionDeviceNotify => {
    xkb_code           => $code,
    time               => $time,
    deviceID           => $deviceid,
    reason             => $XkbXIDetail,    # mask
    ledClass           => $XkbLEDClassResult,
    ledID              => $ledid,
    ledsDefined        => $XkbIndicator,   # 32-bit bit mask
    ledState           => $XkbIndicator,   # 32-bit bit mask
    firstButton        => $button,
    nButtons           => $nbuttons,
    supported          => $XkbXIFeature,   # mask
    unsupported        => $XkbXIFeature}   # mask

CONSTANTS

X11::Protocol::Ext::XKEYBOARD provides the following constants: (some are enums, some are masks, some are both)

XkbEventType => XkbNewKeyboardNotify XkbMapNotify
    XkbStateNotify XkbControlsNotify XkbIndicatorStateNotify
    XkbIndicatorMapNotify XkbNamesNotify XkbCompatMapNotify
    XkbBellNotify XkbActionMessage XkbAcessXNotify
    XkbExtensionDeviceNotify
XkbKeyMask => Shift Lock Control Mod1 Mod2 Mod3 Mod4 Mod5
XkbButMask => Button0 Button1 Button2 Button3
              Button4 Button5 Button6 Button7
XkbNKNDetail => Keycodes Geometry DeviceID
XkbAXNDetail => SKPress SKAccept SKReject SKRelease BKAccept
    BKReject AXKWarning
XkbMapPart => KeyTypes KeySyms ModifierMap ExplicitComponents
    KeyActions KeyBehaviors VirtualMods VirtualModMap
XkbStatePart => ModifierState ModifierBase ModifierLatch
    ModifierLock GroupState GroupBase GroupLatch GroupLock
    CompatState GrabModes CompatGrabMods LookupMods
    CompatLookupMods PointerButtons
XkbBoolCtrl => RepeatKeys SlowKeys BounceKeys StickyKeys
    MouseKeys MouseKeysAccel AccessXKeys AccessXTimeoutMask
    AccessXFeedbackMask AudibleBellMask Overlay1Mask
    Overlay2Mask IgnoreGroupLockMask
XkbControl => RepeatKeys SlowKeys BounceKeys StickyKeys
    MouseKeys MouseKeysAccel AccessXKeys AccessXTimeoutMask
    AccessXFeedbackMask AudibleBellMask Overlay1Mask
    Overlay2Mask IgnoreGroupLockMask GroupsWrap InternalMods
    IgnoreLockMods PerKeyRepeat ControlsEnabled
XkbAXFBOpt => SKPress SKAccept Feature SlowWarn Indicator
    StickyKeys SKRelease SKReject BKReject DumbBell
XkbAXSKOpt => TwoKeys LatchToLock
XkbAXOption => SKPress SKAccept Feature SlowWarn Indicator
    StickKeys TwoKeys LatchToLock SKRelease SKReject BKReject
    DumbBell
XkbDeviceSpec => UseCoreKbd UseCorePtr
XkbLEDClassResult => KbdFeedbackClass LedFeedbackClass
XkbLEDClassSpec => KbdFeedbackClass LedFeedbackClass
    DfltXIClass AllXIClasses
XkbBellClassResult => KbdFeedbackClass BellFeedbackClass
XkbBellClassSpec => KbdFeedbackClass BellFeedbackClass
    DfltXIClass
XkbIDSpec => DfltXIId
XkbIDResult => DfltXIId XINone
XkbMultiIDSpec => DfltXIId AllXIIds
XkbGroup => Group1 Group2 Group3 Group4
XkbGroups => Group1 Group2 Group3 Group4 AnyGroup AllGroups
XkbKbGroup => Group1 Group2 Group3 Group4
XkbKbGroups => Group1 Group2 Group3 Group4 AnyGroup
XkbGroupsWrap => ClampIntoRange RedirectIntoRange
XkbVModsHigh => vmod8 vmod9 vmod10 vmod11 vmod12 vmod13
    vmod14 vmod15
XkbVModsLow => vmod0 vmod1 vmod2 vmod3 vmod4 vmod5 vmod6 vmod7
XkbVMod => vmod0 vmod1 vmod2 vmod3 vmod4 vmod5 vmod6 vmod7
    vmod8 vmod9 vmod10 vmod11 vmod12 vmod13 vmod14 vmod15
    vmod16
XkbExplicit => KeyType1 KeyType2 KeyType3 KeyType4 Interpret
    AutoRepeat Behavior VModMap
XkbSymInterpMatch => LevelOneOnly Operation
XkbIMFlag => LEDDrivesKB NoAutomatic NoExplicit
XkbIMModsWhich => UseBase UseLatched UseLocked UseEffective
    UseCompat
XkbIMGroupsWhich => UseBase UseLatched UseLocked UseEffective
    UseCompat
XkbCMDetail => SymInterp GroupCompat
XkbNamesDetail => KeycodesName GeometryName SymbolsName
    PhysSymbolsName TypesName CompatName KeyTypeNames
    KTLevelNames IndicatorNames KeyNames KeyAliases
    VirtualModNames GroupNames RGNames
XkbGBNDetail => Types CompatMap ClientSymbols ServerSymbols
    IndicatorMaps KeyNames Geometry OtherNames
XkbXIExtDevFeature => ButtonActions IndicatorNames
    IndicatorMaps IndicatorState
XkbXIFeature => Keyboards ButtonActions IndicatorNames
    IndicatorMaps IndicatorState
XkbXIDetail => Keyboards ButtonActions IndicatorNames
    IndicatorMaps IndicatorState UnsupportedFeature
XkbPerClientFlag => DetectableAutorepeat GrabsUseXKBState
    AutoResetControls LookupStateWhenGrabbed
    SendEventUsesXKBState

ERRORS

X11::Protocol::Ext::XKEYBOARD provides the following bad resource errors: Keyboard

REQUESTS

X11::Protocol::Ext::KEYBOARD provides the folloing requests:

$X->XkbUseExtension($major,$minor)
=>
($supported,$major,$minor)
 $X->XkbSelectEvents($deviceSpec,
         $XkbEventType=>'clear',            # to clear events
         $XkbEventType=>'selectAll,         # to select all events
	 $XkbEventType=>[$affect,$details], # filtered events
         ... )

     $deviceSpec => $XkbDeviceSpec
     $affects    => $bitmask # see spec for type
     $details    => $bitmask # see spec for type

     $bit is event type bit name or bit number
$X->XkbBell($deviceSpec, $bellClass, $bellID, $percent, $forceSound,
        $eventOnly, $pitch, $duration, $name, $window)
$X->XkbGetState($deviceSpec)
=>
($deviceID, $mods, $baseMods, $latchedMods, $lockedMods, $group,
        $lockedGroup, $baseGroup, $latchedGroup, $compatState,
        $grabMods, $compatGrabMods, $lookupMods, $compatLookupMods,
        $ptrBtnState)
$X->XkbLatchLockState($deviceSpec, $affectModLocks, $modLocks,
        $lockGroup, $groupLock, $affectModLatches, $modLatches,
        $latchGroup, $groupLatch)
   
    $affectModLocks    => $XkbKeyMask  # mask
    $modLock           => $XkbKeyMask  # mask
    $lockGroup         => $Bool
    $groupLock         => $XkbGroup
    $affectModLatches  => $XkbKeyMask  # mask
    $modLatches        => $XkbKeyMask  # mask
    $latchGroup        => $Bool
    $groupLatch        => $bitmask     # 16-bit bit mask
$X->XkbGetControls($deviceSpec)
=>
($deviceID, $mouseKeysDfltBtn, $numGroups, $groupsWrap,
        $internalMods_mask, $ignoreLockMods_mask,
        $interalMods_realMods, $ignoreLockMods_realMods,
        $internalMods_vmods, $ignoreLockMods_vmods, $repeatDelay,
        $repeatInterval, $slowKeysDelay, $debounceDelay,
        $mouseKeysDelay, $mouseKeysInterval, $mouseKeysTimeToMax,
        $mouseKeysMaxSpeed, $mouseKeysCurve, $accessXOptions,
        $accessXTimeout, $accessXTimeoutOptionsMask,
        $accessXTimeoutOptionValues, $accessXTimeoutMask,
        $accessXTimeoutValues, $enabledControls, $perKeyRepeat)

    $deviceSpec                    => $XkbDeviceSpec
    $internalMods_mask             => $XkbKeyMask  # mask
    $ignoreLockMods_mask           => $XkbKeyMask  # mask
    $internalMods_realMods         => $XkbKeyMask  # mask
    $ignoreLockMods_realMods       => $XkbKeyMask  # mask
    $internalMods_vmods            => $XkbVMod     # mask
    $ignoreLockMods_vmods          => $XkbVMod     # mask
    $accessXOptions                => #XkbAXOption # mask
    $accessXTimeoutOptionsMask     => $XkbAXOption # mask
    $accessXTimeoutOptionsValues   => $XkbAXOption # mask
    $accessXTimeoutMask            => $XkbBoolCtrl # mask
    $accessXTimeoutValues          => $XkbBoolCtrl # mask
    $enabledControls               => $XkbBoolCtrl # mask
$X->XkbSetControls($deviceSpec, $affectInternalRealMods,
       $internalRealMods, $affectIgnoreLockRealMods,
       $ignoreLockRealMods, $affectInternalVirtualMods,
       $internalVirtualMods, $affectIgnoreLockVirtualMods,
       $ignoreLockVirtualMods, $mouseKeysDfltBtn, $groupsWrap,
       $accessXOptions, $affectEnabledControls, $enabledControls,
       $changeControls, $repeatDelay, $repeatInterval, $slowKeysDelay,
       $debounceDelay, $mouseKeysDelay, $mouseKeysInterval,
       $mouseKeysTimeToMax, $mouseKeysMaxSpeed, $mouseKeysCurve
       $accessXTimeout, $accessXTimeoutMask, $accessXTimeoutValues,
       $accessXTimeoutOptionsMask, $accessXTimeoutOptionsValues,
       $perKeyRepeat)

   $deviceSpec                     => $XkbDeviceSpec
   $affectInternalRealMods         => $XkbKeyMask  # mask
   $internalRealMods               => $XkbKeyMask  # mask
   $affectIgnoreLockRealMods       => $XkbKeyMask  # mask
   $ignoreLockRealMods             => $XkbKeyMask  # mask
   $affectInternalVirualMods       => $XkbVMod     # mask
   $internalVirualMods             => $XkbVMod     # mask
   $affectIgnoreLockVirtualMods    => $XkbVMod     # mask
   $ignoreLockVirtualMods          => $XkbVMod     # mask
   $accessXOptions                 => $XkbAXOption # mask
   $enabledControls                => $XkbBoolCtrl # mask
   $changeControls                 => $XkbControl  # mask
   $accessXTimeoutMask             => $XkbBoolCtrl # mask
   $accessXTimeoutValues           => $XkbBoolCtrl # mask
   $accessXTimeoutOptionsMask      => $XkbAXOption # mask
   $accessXTimeoutOptionsValues    => $XkbAXOption # mask
$X->XkbGetMap($deviceSpec, $full, $partial, $firstType, $nTypes,
        $firstKeySym, $nKeySyms, $firstKeyAction, $nKeyActions,
        $firstKeyBehavior, $nKeyBehaviours, $virtualMods,
        $firstKeyExplicit, $nKeyExplicit, $firstModMapKey,
        $nModMapKeys, $firstVModMapKey, $nVModMapKeys)
=>
($deviceID, $minKeyCode, $maxKeyCode, $present, $firstType, $nTypes,
        $totalTypes, $firstKeySym, $nKeySyms, $firstKeyAction,
        $totalActions, $nKeyActions, $firstKeyBehavior, $nKeyBehaviors,
        $totalKeyBehaviors, $firstKeyExplicit, $nKeyExplicit,
        $totalKeyExplicit, $firstModMapKey, $nModMapKeys,
        $totalModMapKeys, $firstVModMapKey, $nVModMapKeys,
        $totalVModMapKeys, $virtualMods, XkbKeyTypes=>$typesRtrn,
        XkbKeySyms=>$symsRtrn, XkbKeyActions=>[$actsRtrn,...],
        XkbKeyBehaviors=>$behaviorsRtrn, XkbVirtualMods=>$vmodsRtrn,
        XkbExplicitComponents=>$explicitRtrn,
        XkbModifierMap=>$modmapRtrn, XkbVirtualModMap=>$vmodMapRtrn)

    $typesRtrn     => [ $keytype, ... ]
    $keytype       => [ $mods_mask, $mods_mods, $mods_vmods,
                        $numLevels, $hasPreserve, [$map,...],
                        [$preserve,...] ]
    $map           => [ $active, $mods_mask, $level, $mods_mods,
                        $mods_vmods ]
    $preserve      => [ $moddef, ... ]

    $symsRtrn      => [ $keysym, ... ]
    $keysym        => [ [ @ktIndex[0..3] ], $groupInfo, $width,
                        [ $sym, ... ] ]

    $actsRtrn      => [ $act, ... ]

    $behaviorsRtrn => [ $behavior, ... ]
    $behavior      => [ $keycode, $behaviors ]

    $vmodsRtrn     => [ $vmod, ... ]

    $explicitRtrn  => [ $explicit, ... ]
    $explicit      => [ $keycode, $explicits ]

    $modmapRtrn    => [ $modmap, ... ]
    $modmap        => [ $keycode, $mods ]

    $vmodmapRtrn   => [ $vmodmap, ... ]
    $vmodmap       => [ $keycode, $vmods ]
$X->XkbSetMap(...)
        too complex (not implemented yet)
$X->XkbGetCompatMap(...)
        too complex (not implemented yet)
$X->XkbSetCompatMap(...)
        too complex (not implemented yet)
$X->GetIndicatorState($deviceSpec)
=> 
($deviceID, $state)

    $deviceSpec => $XkbDeviceSpec
$X->GetIndicatorMap($deviceSpec, $which)
=> 
($deviceID, $which, $realIndicators, $maps)

    $deviceSpec => $XkbDeviceSpec

    $maps => [ $map, ... ]
    $map  => [ $flags, $whichGroups, $groups, $whichMods,
               $mods, $realMods, $vmods, $ctrls ]
$X->SetIndicatorMap($deviceSpec,$which, $maps)

    $deviceSpec => $XkbDeviceSpec

    $maps => [ $map, ... ]
    $map  => [ $flags, $whichGroups, $groups, $whichMods,
               $mods, $realMods, $vmods, $ctrls ]
$X->GetNamedIndicator($deviceSpec, $ledClass, $ledID, $indicator)
=>
($deviceID, $indicator, $found, $on, $realIndicator, $ndx,
        $map, $supported)

    $deviceSpec => $XkbDeviceSpec

    $map => [ $flags, $whichGroups, $groups, $whichMods,
              $mods, $realMods, $vmods, $ctrls ]
$X->XkbSetNamedIndicator->($deviceSpec, $ledClass, $ledID,
        $indicator, $setState, $on, $setMap, $createMap, $map)

    $deviceSpec => $XkbDeviceSpec

    $map => [ $flags, $whichGroups, $groups, $whichMods,
              $mods, $realMods, $vmods, $ctrls ]
$X->XkbGetNames(...)
        too complex (not implemented yet)
$X->XkbSetNames(...)
        too complex (not implemented yet)
$X->XkbGetGeometry(...)
        too complex (not implemented yet)
$X->XkbSetGeometry(...)
        too complex (not implemented yet)
$X->XkbPerClientFlags($deviceSpec, $change, $value, $ctrlsToChange,
        $autoCtrls, $autoCtrlValues)
=>
($deviceID, $supported, $value, $autoCtrls, $autoCtrlValues)

    $deviceSpec     => $XkbDeviceSpec
    $change         => $XkbPerClientFlag    # mask
    $value          => $XkbPerClientFlag    # mask
    $ctrlsToChange  => $XkbBoolCtrl         # mask
    $autoCtrls      => $XkbBoolCtrl         # mask
    $autoCtrlValues => $XkbBoolCtrl         # mask
 $X->XkbListComponents($deviceSpec, $maxNames, $keymaps, $keycodes,
	 $types, $compatMap, $symbols, $geometry)
 =>
 ($deviceID, $keymaps, $keycodes, $types, $compatMaps, $symbols,
  $geometries, $extra)

     $keymaps	 => [ $kblisting, ... ]
     $keycodes	 => [ $kblisting, ... ]
     $types	 => [ $kblisting, ... ]
     $compatMaps => [ $kblisting, ... ]
     $symbols	 => [ $kblisting, ... ]

     $kblisting => [ $flags, $string ]
$X->XkbGetKbdByName(...)
        too complex (not implemented yet)
$X->XkbGetDeviceInfo(...)
        too complex (not implemented yet)
$X->XkbSetDeviceInfo(...)
        too complex (not implemented yet)
$X->XkbSetDebuggingFlags(...)
        not useful (not implemented)

BUGS

This modue has not been tested exhaustively and will likely fail when anything special is attempted.

Many requests are not implemented yet due to their high complexity. (I really only needed XkbGetControls and XkbSetControls.)

AUTHOR

Brian Bidulock <bidulock@cpan.org>.

SEE ALSO

perl(1), X11::Protocol(3pm), The X Keyboard Extension: Protocol Specification, Protocol Version 1.0/Document Revision 1.0 (X Consortium Standard)