diff options
Diffstat (limited to 'libX11/man/xkb/XkbForceDeviceBell.man')
| -rw-r--r-- | libX11/man/xkb/XkbForceDeviceBell.man | 319 |
1 files changed, 319 insertions, 0 deletions
diff --git a/libX11/man/xkb/XkbForceDeviceBell.man b/libX11/man/xkb/XkbForceDeviceBell.man new file mode 100644 index 000000000..6842aa696 --- /dev/null +++ b/libX11/man/xkb/XkbForceDeviceBell.man @@ -0,0 +1,319 @@ +'\" t +.\" Copyright (c) 1999 - Sun Microsystems, Inc. +.\" All rights reserved. +.\" +.\" Permission is hereby granted, free of charge, to any person obtaining a +.\" copy of this software and associated documentation files (the +.\" "Software"), to deal in the Software without restriction, including +.\" without limitation the rights to use, copy, modify, merge, publish, +.\" distribute, and/or sell copies of the Software, and to permit persons +.\" to whom the Software is furnished to do so, provided that the above +.\" copyright notice(s) and this permission notice appear in all copies of +.\" the Software and that both the above copyright notice(s) and this +.\" permission notice appear in supporting documentation. +.\" +.\" THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS +.\" OR IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF +.\" MERCHANTABILITY, FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT +.\" OF THIRD PARTY RIGHTS. IN NO EVENT SHALL THE COPYRIGHT HOLDER OR +.\" HOLDERS INCLUDED IN THIS NOTICE BE LIABLE FOR ANY CLAIM, OR ANY SPECIAL +.\" INDIRECT OR CONSEQUENTIAL DAMAGES, OR ANY DAMAGES WHATSOEVER RESULTING +.\" FROM LOSS OF USE, DATA OR PROFITS, WHETHER IN AN ACTION OF CONTRACT, +.\" NEGLIGENCE OR OTHER TORTIOUS ACTION, ARISING OUT OF OR IN CONNECTION +.\" WITH THE USE OR PERFORMANCE OF THIS SOFTWARE. +.\" +.\" Except as contained in this notice, the name of a copyright holder +.\" shall not be used in advertising or otherwise to promote the sale, use +.\" or other dealings in this Software without prior written authorization +.\" of the copyright holder. +.\" +.TH XkbForceDeviceBell __libmansuffix__ __xorgversion__ "XKB FUNCTIONS" +.SH NAME +XkbForceDeviceBell \- Rings the bell on any keyboard, overriding user preference +settings for audible bells +.SH SYNOPSIS +.B Bool XkbForceDeviceBell +( +.I display, +.I window, +.I device_spec, +.I bell_class, +.I bell_id, +.I percent +) +.br + Display *\fI display \fP\^; +.br + Window \fI window \fP\^; +.br + unsigned int \fI device_spec \fP\^; +.br + unsigned int \fI bell_class \fP\^; +.br + unsigned int \fI bell_id \fP\^; +.br + int \fI percent \fP\^; +.if n .ti +5n +.if t .ti +.5i +.SH ARGUMENTS +.TP +.I \- display +connection to the X server +.TP +.I \- window +event window, or None +.TP +.I \- device_spec +device ID, or XkbUseCoreKbd +.TP +.I \- bell_class +input extension class of the bell to be rung +.TP +.I \- bell_id +input extension ID of the bell to be rung +.TP +.I \- percent +relative volume, which can range from -100 to 100 inclusive +.SH DESCRIPTION +.LP +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 +.I 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 +following: + +.IP \(bu 5 +The default bell +.IP \(bu 5 +Any bell on an input device that can be specified by a bell_class and bell_id pair +.IP \(bu 5 +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.) + +.LP +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 - +.I XkbForceDeviceBell +or +.I XkbForceBell. +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. + +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. 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. + +.TS +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 +Control 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_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 +.TE + +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 XkbAudibleBellMask to +.I XkbChangeEnabledControls. +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 +.I XkbForceDeviceBell +or +.I 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 +.I bell_class +and +.I bell_id +parameters; set them as follows: Set +.I bell_class +to BellFeedbackClass or KbdFeedbackClass. A device can have more than one feedback of each type; +set +.I bell_id +to the particular bell feedback of +.I 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. + +.TS +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 +_ +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 +.TE + + +If a compatible keyboard extension isn't present in the X server, +.I XkbForceDeviceBell +immediately returns False. Otherwise, +.I XkbForceDeviceBell +rings the bell as specified for the display and keyboard device and returns +True. Set +.I percent +to be the volume relative to the base volume for the keyboard as described for +.I XBell. + +There is no +.I name +parameter because +.I XkbForceDeviceBell +does not cause an XkbBellNotify event. + +You can call +.I XkbBell +without first initializing the keyboard extension. +.SH STRUCTURES +.LP +Xkb generates XkbBellNotify events for all bells except for those resulting from +calls to +.I XkbForceDeviceBell +and +.I XkbForceBell. +To receive XkbBellNotify events under all possible conditions, pass +XkbBellNotifyMask in +both the +.I bits_to_change +and +.I values_for_bits +parameters to +.I XkbSelectEvents. + +The XkbBellNotify event has no event details. It is either selected or it is not. +However, you can call +.I XkbSelectEventDetails +using XkbBellNotify as the +.I event_type +and specifying XkbAllBellNotifyMask in +.I bits_to_change +and +.I values_for_bits. +This has the same effect as a call to +.I XkbSelectEvents. + +The structure for the XkbBellNotify event type contains: +.nf + + 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; + +.fi +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. +.SH "SEE ALSO" +.BR XBell (3X11), +.BR XkbBell (__libmansuffix__), +.BR XkbBellNotify (__libmansuffix__), +.BR XkbChangeEnabledControls (__libmansuffix__), +.BR XkbDeviceBell (__libmansuffix__), +.BR XkbForceBell (__libmansuffix__), +.BR XkbForceDeviceBell (__libmansuffix__), +.BR XkbSelectEventDetails (__libmansuffix__), +.BR XkbSelectEvents (__libmansuffix__) + + + + |