From 16b53769eba7d5d8249a217aa29287d72b7713c2 Mon Sep 17 00:00:00 2001 From: marha Date: Wed, 14 Sep 2011 14:23:18 +0200 Subject: libX11 git update 14 sep 2011 --- libX11/specs/XKB/ch09.xml | 1060 +++++++++++++++++++++++++++++++++++++++++++++ 1 file changed, 1060 insertions(+) create mode 100644 libX11/specs/XKB/ch09.xml (limited to 'libX11/specs/XKB/ch09.xml') diff --git a/libX11/specs/XKB/ch09.xml b/libX11/specs/XKB/ch09.xml new file mode 100644 index 000000000..d04669a12 --- /dev/null +++ b/libX11/specs/XKB/ch09.xml @@ -0,0 +1,1060 @@ + +Bells + + +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, disable 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 (see section 9.4) when any client rings any one of the following: + + + + + +The default bell + + + + +Any bell on an input device that can be specified by a +bell_class + and +bell_id + pair + + + + +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 (to set the +AudibleBell + control, see Chapter 10). 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 +XkbForceBell + (see section 9.3.3). 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 controls by using special beep +codes. The +AccessXFeedback + control is used to configure the specific types of operations that generate +feedback. See section 10.6.3 for a discussion on +AccessXFeedback + control. + + + +This chapter describes bell names, the functions used to generate named bells, +and the events the server generates for bells. + + + +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 generated by a client application upon receipt of the bell event +containing the name. There is no default name for the default keyboard bell. +The server does generate some predefined bells for the AccessX controls (see +section 10.6.3). These named bells are shown in Table 9.1; the name is included +in any bell event sent to clients that have requested to receive +XkbBellNotify + events. + + + +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 + + + Control turned off + AX_FeatureOff + + + More than one control changed state + AX_FeatureChange + + + SlowKeys and BounceKeys about to be turned on or off + AX_SlowKeysWarning + + + SlowKeys key pressed + AX_SlowKeyPress + + + SlowKeys key accepted + AX_SlowKeyAccept + + + SlowKeys key rejected + AX_SlowKeyReject + + + Accepted SlowKeys key released + AX_SlowKeyRelease + + + BounceKeys key rejected + AX_BounceKeyReject + + + StickyKeys key latched + AX_StickyLatch + + + 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 (see section 9.4). 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 +XkbAudibleBellMask + to +XkbChangeEnabledControls + (see section 10.1.1). If you set +XkbAudibleBellMask + 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 + (see section 9.3.3). + + + +Audible bells are also part of the per-client auto-reset controls. For more +information on auto-reset controls, see section 10.1.2. + + + + +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 +KbdFeedbackClass +. A device can have more than one feedback of each type; set +bell_id + to the particular bell feedback of +bell_class + type. + + + +Table 9.2 shows the conditions that cause a bell to sound or an +XkbBellNotifyEvent + to be generated when a bell function is called. + + + +Bell Sounding and Bell Event Generating + + + + + + + + Function called + AudibleBell + Server sounds a bell + Server sends an XkbBellNotifyEvent + + + + + XkbDeviceBell + On + Yes + Yes + + + XkbDeviceBell + Off + No + Yes + + + XkbBell + On + Yes + Yes + + + XkbBell + Off + No + Yes + + + XkbDeviceBellEvent + On or Off + No + Yes + + + XkbBellEvent + On or Off + No + Yes + + + XkbDeviceForceBell + On or Off + Yes + No + + + XkbForceBell + On or Off + Yes + No + + + +
+ + +Generating Named Bells + + +To ring the bell on an X input extension device or the default keyboard, use + +XkbDeviceBell. + + + + + + + + +Bool +XkbDeviceBell +( +display, window, device_id, bell_class, bell_id, percent, name +) + + + + +Display * + display +; /* connection to the X server */ + + + + +Window + window +; /* window for which the bell is generated, or None */ + + + + +unsigned int +device_spec +; /* device ID, or +XkbUseCoreKbd + */ + + + + +unsigned int +bell_class +; /* X input extension bell class of the bell to be rung */ + + + + +unsigned int +bell_id +; /* X input extension bell ID of the bell to be rung */ + + + + +int +percent +; /* bell volume, from -100 to 100 inclusive */ + + + + +Atom +name +; /* a name for the bell, or +NULL + */ + + + + + + + +Set +percent + to be the volume relative to the base volume for the keyboard as described for + +XBell. + + + +Note that +bell_class + and +bell_id + indicate the bell to physically ring. +name + is simply an arbitrary moniker for the client application’s use. + + + +To determine the current feedback settings of an extension input device, use + +XGetFeedbackControl +. See the X input extension documentation 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. + + + +As a convenience function, Xkb provides a function to ring the bell on the +default keyboard: +XkbBell. + + + + + + + + +Bool +XkbBell +( +display, window, percent, name +) + + + + +Display * +display +; /* connection to the X server */ + + + + +Window + window +; /* event window, or None*/ + + + + +int + percent +; /* relative volume, which can range from -100 to 100 inclusive */ + + + + +Atom + name +; /* a bell name, or +NULL + */ + + + + + + + +If a compatible keyboard extension isn’t present in the X server, +XkbBell + calls +XBell +with the specified +display + and +percent +, and returns +False +. Otherwise, +XkbBell +calls +XkbDeviceBell + with the specified +display, window, percent, +and +name +, a +device_spec + of +XkbUseCoreKbd +, a +bell_class +of +XkbDfltXIClass +, and a +bell_id +of +XkbDfltXIId, + 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 +XkbBell + without first initializing the keyboard extension. + + + + +Generating Named Bell Events + + +Using Xkb, you can also generate a named bell event that does not ring any +bell. This allows you to do things such as generate events when your +application starts. + + + +For example, if an audio client listens for these types of bells, it can +produce a "whoosh" sound when it receives a named bell event to indicate a +client just started. In this manner, applications can generate start-up +feedback and not worry about producing annoying beeps if an audio server is not +running. + + + + +To cause a bell event for an X input extension device or for the keyboard, +without ringing the corresponding bell, use +XkbDeviceBellEvent. + + + + + + + + +Bool +XkbDeviceBellEvent +( +display, window, device_spec, bell_class, bell_id, percent, name +) + + + + +Display * +display +; /* connection to the X server */ + + + + +Window +window +; /* event window, or None*/ + + + + +unsigned int +device_spec +; /* device ID, or +XkbUseCoreKbd + */ + + + + +unsigned int +bell_class; + /* input extension bell class for the event */ + + + + +unsigned int +bell_id +; /* input extension bell ID for the event */ + + + + +int +percent +; /* volume for the bell, which can range from -100 to 100 inclusive */ + + + + +Atom +name +; /* a bell name, or +NULL + */ + + + + + + + +If a compatible keyboard extension isn’t present in the X server, +XkbDeviceBellEvent + immediately returns +False +. Otherwise, +XkbDeviceBellEvent + causes an +XkbBellNotify + event to be sent to all interested clients and returns +True +. Set +percent + to be the volume relative to the base volume for the keyboard as described for +XBell. + + + + +In addition, +XkbDeviceBellEvent + may generate +Atom + protocol errors as well as +XkbBellNotify + events. You can call +XkbBell + without first initializing the keyboard extension. + + + + +As a convenience function, Xkb provides a function to cause a bell event for +the keyboard without ringing the bell: +XkbBellEvent. + + + + + + + + + +Bool +XkbBellEvent +( +display, window, percent, name +) + + + + +Display * +display +; /* connection to the X server */ + + + + +Window +window +; /* the event window, or None */ + + + + +int +percent +; /* relative volume, which can range from -100 to 100 inclusive */ + + + + +Atom +name +; /* a bell name, or +NULL + */ + + + + + + + +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, percent, +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. + + + + +Forcing a Server-Generated Bell + + +To ring the bell on any keyboard, overriding user preference settings for +audible bells, use XkbForceDeviceBell. + + + + + + + + +Bool +XkbForceDeviceBell +( +display, window, device_spec, bell_class, bell_id, percent +) + + + + +Display * +display +; /* connection to the X server */ + + + + +Window +window +; /* event window, or None */ + + + + +unsigned int +device_spec +; /* device ID, or +XkbUseCoreKbd + */ + + + + +unsigned int +bell_class +; /* input extension class of the bell to be rung */ + + + + +unsigned int +bell_id +; /* input extension ID of the bell to be rung */ + + + + +int +percent +; /* relative volume, which can range from -100 to 100 inclusive */ + + + + + + + +If a compatible keyboard extension isn’t present in the X server, +XkbForceDeviceBell + immediately returns +False +. Otherwise, +XkbForceDeviceBell +rings the bell as specified for the display and keyboard device and returns + +True +. Set +percent + to be the volume relative to the base volume for the keyboard as described for + +XBell +. There is no +name + parameter because +XkbForceDeviceBell +does not cause an +XkbBellNotify + event. + + + +You can call +XkbBell + without first initializing the keyboard extension. + + + +To ring the bell on the default keyboard, overriding user preference settings +for audible bells, use +XkbForceBell. + + + + + + + + +Bool +XkbForceBell +( +display, percent) + + + + +Display * +display +; /* connection to the X server */ + + + + +int +percent +; /* volume for the bell, which can range from -100 to 100 inclusive */ + + + + + + + +If a compatible keyboard extension isn’t present in the X server, +XkbForceBell + calls +XBell +with the specified +display + and +percent + and returns +False +. Otherwise, +XkbForceBell +calls +XkbForceDeviceBell + with the specified +display +and + percent +, +device_spec + = +XkbUseCoreKbd +, +bell_class += +XkbDfltXIClass +, +bell_id += +XkbDfltXIId, + +window + = None, and +name + = +NULL +, and returns what + XkbForceDeviceBell + returns. + + + + +XkbForceBell +does not cause an +XkbBellNotify + event. + + + +You can call +XkbBell + without first initializing the keyboard extension. + + + + + +Detecting Bells + + +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 + parameters to +XkbSelectEvents + (see section 4.3). + + + +The +XkbBellNotify + event has no event details. It is either selected or it is not. However, you +can call +XkbSelectEventDetails + using +XkbBellNotify + 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 +XkbBellNotifyEvent +, if present. + + + + -- cgit v1.2.3