unixdev.net


Switch to SpeakEasy.net DSL

The Modular Manual Browser

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

XkbDeviceBell(3)                 XKB FUNCTIONS                XkbDeviceBell(3)



NAME
       XkbDeviceBell  -  Rings  the bell on an X input extension device or the
       default keyboard

SYNOPSIS
       Bool XkbDeviceBell ( display, window, device_spec, bell_class, bell_id,
       percent, name )
             Display * display ;
             Window  window ;
             unsigned int  device_spec ;
             unsigned int  bell_class ;
             unsigned int  bell_id ;
             int  percent ;
             Atom  name ;

ARGUMENTS
       - display
              connection to the X server

       - window
              window for which the bell is generated, or None

       - device_spec
              device ID, or XkbUseCoreKbd

       - bell_class
              X input extension bell class of the bell to be rung

       - bell_id
              X input extension bell ID of the bell to be rung

       - percent
              bell volume, from -100 to 100 inclusive

       - name a name for the bell, 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 the 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.

            The  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

            Set  percent  to be the volume relative to the base volume for the
            keyboard as described for .I XBell.

            Note that bell_class and bell_id indicate the bell  to  physically
            ring.  name is simply an arbitrary moniker for the client applica-
            tion's use.

            To determine the current feedback settings of an  extension  input
            device,  use XGetFeedbackControl.  See the X input extension docu-
            mentation for more information on XGetFeedbackControl and  related
            data structures.

            If a compatible keyboard extension is not present in the X server,
            XkbDeviceBell immediately returns False. Otherwise,  XkbDeviceBell
            rings  the  bell  as specified for the display and keyboard device
            and returns True. If you  have  disabled  the  audible  bell,  the
            server  does not ring the system bell, although it does generate a
            XkbBellNotify event.

            You can call XkbDeviceBell without first initializing the keyboard
            extension.

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
       XBell(3X11),  XkbBellNotify(3), XkbChangeEnabledControls(3), XkbDevice-
       Bell(3),   XkbForceBell(3),   XkbForceDeviceBell(3),   XGetFeedbackCon-
       trol(3), XkbSelectEvents(3)




X Version 11                     libX11 1.1.5                 XkbDeviceBell(3)