unixdev.net


Switch to SpeakEasy.net DSL

The Modular Manual Browser

Home Page
Manual: (Debian-5.0)
Page:
Section:
Apropos / Subsearch:
optional field

XkbBellEvent(3)                  XKB FUNCTIONS                 XkbBellEvent(3)



NAME
       XkbBellEvent  - Provides a function that initiates a bell event for the
       keyboard without ringing the bell

SYNOPSIS
       Bool XkbBellEvent ( display, window, percent, name )
             Display * display ;
             Window  window ;
             int  percent ;
             Atom  name ;

ARGUMENTS
       - display
              connection to the X server

       - window
              the event window, or None

       - percent,
              relative volume, which can range from -100 to 100 inclusive

       - name a bell name, or NULL

DESCRIPTION
       The core X protocol allows only applications to  explicitly  sound  the
       system  bell with a given duration, pitch, and volume. Xkb extends this
       capability by allowing clients to attach symbolic names to bells,  dis-
       able  audible bells, and receive an event whenever the keyboard bell is
       rung. For the purposes of this document, the audible bell is defined to
       be  the  system  bell,  or the default keyboard bell, as opposed to any
       other audible sound generated elsewhere in the system.  You can ask  to
       receive  XkbBellNotify events when any client rings any one of the fol-
       lowing:


       o    The default bell

       o    Any bell on an input device that can be specified by a  bell_class
            and bell_id pair

       o    Any  bell  specified only by an arbitrary name. (This is, from the
            server's point of view, merely a name, and not connected with  any
            physical  sound-generating  device.  Some  client application must
            generate the sound, or visual feedback, if any, that is associated
            with the name.)

            You  can  also ask to receive XkbBellNotify events when the server
            rings the default bell or if any client has requested events  only
            (without  the  bell sounding) for any of the bell types previously
            listed.

            You can disable audible bells on a global basis.  For  example,  a
            client that replaces the keyboard bell with some other audible cue
            might want to turn off the  AudibleBell  control  to  prevent  the
            server  from  also  generating a sound and avoid cacophony. If you
            disable audible bells and request to receive XkbBellNotify events,
            you can generate feedback different from the default bell.

            You  can, however, override the AudibleBell control by calling one
            of the functions that force the ringing of a bell in spite of  the
            setting  of  the  AudibleBell control - XkbForceDeviceBell or Xkb-
            ForceBell.  In this case the  server  does  not  generate  a  bell
            event.

            Just  as  some  keyboards can produce keyclicks to indicate when a
            key is pressed or repeating, Xkb can provide feedback for the con-
            trols  by using special beep codes. The AccessXFeedback control is
            used to configure the specific types of operations  that  generate
            feedback.

            Bell Names

            You can associate a name to an act of ringing a bell by converting
            the name to an Atom and then using this name  when  you  call  the
            functions  listed  in  this chapter. If an event is generated as a
            result, the name is then passed to all other clients interested in
            receiving  XkbBellNotify  events.  Note  that  these are arbitrary
            names and that there is no binding to any sounds.  Any  sounds  or
            other  effects (such as visual bells on the screen) must be gener-
            ated by a client application upon receipt of the bell  event  con-
            taining  the  name.  There is no default name for the default key-
            board bell. The server does generate some predefined bells for the
            AccessX controls. These named bells are shown in Table 1; the name
            is included in any bell event sent to clients that have  requested
            to receive XkbBellNotify events.


            c s l l lW(4i) l.  Table 1 Predefined Bells _ Action    Named Bell
            _   Indicator   turned    on AX_IndicatorOn    Indicator    turned
            off     AX_IndicatorOff    More   than   one   indicator   changed
            state   AX_IndicatorChange Control turned  on   AX_FeatureOn  Con-
            trol  turned  off    AX_FeatureOff  More  than one control changed
            state     AX_FeatureChange T{ SlowKeys and BounceKeys about to  be
            turned    on   or   off   T}   AX_SlowKeysWarning   SlowKeys   key
            pressed     AX_SlowKeyPress SlowKeys key accepted    AX_SlowKeyAc-
            cept  SlowKeys  key rejected    AX_SlowKeyReject Accepted SlowKeys
            key       released    AX_SlowKeyRelease       BounceKeys       key
            rejected  AX_BounceKeyReject  StickyKeys  key latched   AX_Sticky-
            Latch  StickyKeys  key  locked    AX_StickyLock   StickyKeys   key
            unlocked  AX_StickyUnlock

            Audible Bells

            Using  Xkb  you  can  generate bell events that do not necessarily
            ring the system bell. This is useful if you need to use  an  audio
            server  instead  of  the  system  beep. For example, when an audio
            client starts, it could disable the audible bell (the system bell)
            and  then  listen  for  XkbBellNotify  events.  When it receives a
            XkbBellNotify event, the audio client could then send a request to
            an audio server to play a sound.

            You  can control the audible bells feature by passing the XkbAudi-
            bleBellMask to XkbChangeEnabledControls.  If you  set  XkbAudible-
            BellMask  on,  the  server rings the system bell when a bell event
            occurs. This is the default. If you set XkbAudibleBellMask off and
            a  bell  event  occurs,  the  server does not ring the system bell
            unless you call XkbForceDeviceBell or XkbForceBell.

            Audible bells are also part of the per-client auto-reset controls.

            Bell Functions

            Use the functions described in this section to ring bells  and  to
            generate bell events.

            The  input  extension has two types of feedbacks that can generate
            bells - bell feedback and keyboard feedback. Some of the functions
            in  this  section have bell_class and bell_id parameters; set them
            as follows: Set bell_class to  BellFeedbackClass  or  KbdFeedback-
            Class.  A device can have more than one feedback of each type; set
            bell_id to the particular bell feedback of bell_class type.

            Table 2 shows the conditions that cause a  bell  to  sound  or  an
            XkbBellNotifyEvent to be generated when a bell function is called.


            c  s  s  s  l l l l l l l l.  Table 2 Bell Sounding and Bell Event
            Generating _ Function  called     AudibleBell    Server  sounds  a
            bell     Server   sends   an   XkbBellNotifyEvent   _   XkbDevice-
            Bell  On   Yes  Yes                   XkbDeviceBell  Off  No   Yes
            XkbBell   On   Yes  Yes     XkbBell   Off  No   Yes     XkbDevice-
            BellEvent  On or Off  No   Yes XkbBellEvent   On  or  Off No   Yes
            XkbDeviceForceBell  On  or  Off     Yes  No  XkbForceBell   On  or
            Off Yes  No

            If a compatible keyboard extension isn't present in the X  server,
            XkbBellEvent  immediately  returns  False. Otherwise, XkbBellEvent
            calls XkbDeviceBellEvent with the specified display, window,  per-
            cent,  and  name,  a device_spec of XkbUseCoreKbd, a bell_class of
            XkbDfltXIClass, and a bell_id of  XkbDfltXIId,  and  returns  what
            XkbDeviceBellEvent returns.

            XkbBellEvent generates a XkbBellNotify event.

            You  can call XkbBellEvent without first initializing the keyboard
            extension.

RETURN VALUES
       False          The XkbBellEvent immediately returns False, if a compat-
                      ible keyboard extension isn't present in the X server.

STRUCTURES
       Xkb  generates  XkbBellNotify  events  for  all  bells except for those
       resulting  from  calls  to  XkbForceDeviceBell  and  XkbForceBell.   To
       receive  XkbBellNotify  events  under  all  possible  conditions,  pass
       XkbBellNotifyMask in both the bits_to_change and values_for_bits param-
       eters to XkbSelectEvents.

       The  XkbBellNotify event has no event details. It is either selected or
       it is not.  However, you can call XkbSelectEventDetails using  XkbBell-
       Notify   as  the  event_type  and  specifying  XkbAllBellNotifyMask  in
       bits_to_change and values_for_bits.  This has the same effect as a call
       to XkbSelectEvents.

       The structure for the XkbBellNotify event type contains:

          typedef struct _XkbBellNotify {
              int            type;        /* Xkb extension base event code */
              unsigned long  serial;      /* X server serial number for event */
              Bool           send_event;  /* True => synthetically generated */
              Display *      display;     /* server connection where event generated */
              Time           time;        /* server time when event generated */
              int            xkb_type;    /* XkbBellNotify */
              unsigned int   device;      /* Xkb device ID, will not be XkbUseCoreKbd
       */
              int            percent;     /* requested volume as % of max */
              int            pitch;       /* requested pitch in Hz */
              int            duration;    /* requested duration in microseconds */
              unsigned int   bell_class;  /* X input extension feedback class */
              unsigned int   bell_id;     /* X input extension feedback ID */
              Atom           name;        /* "name" of requested bell */
              Window         window;      /* window associated with event */
              Bool           event_only;  /* False -> the server did not produce a beep
       */
          } XkbBellNotifyEvent;

       If  your  application  needs  to  generate  visual bell feedback on the
       screen when it receives a bell event, use the window ID in the XkbBell-
       NotifyEvent, if present.


SEE ALSO
       XkbChangeEnabledControls(3),   XkbDeviceBellEvent(3),  XkbForceBell(3),
       XkbForceDeviceBell(3), XkbSelectEventDetails(3), XkbSelectEvents(3)






X Version 11                     libX11 1.1.5                  XkbBellEvent(3)