man/xkb/XkbForceBell.man

   1 '\" t
   2 .\" Copyright 1999 Oracle and/or its affiliates. All rights reserved.
   3 .\"
   4 .\" Permission is hereby granted, free of charge, to any person obtaining a
   5 .\" copy of this software and associated documentation files (the "Software"),
   6 .\" to deal in the Software without restriction, including without limitation
   7 .\" the rights to use, copy, modify, merge, publish, distribute, sublicense,
   8 .\" and/or sell copies of the Software, and to permit persons to whom the
   9 .\" Software is furnished to do so, subject to the following conditions:
  10 .\"
  11 .\" The above copyright notice and this permission notice (including the next
  12 .\" paragraph) shall be included in all copies or substantial portions of the
  13 .\" Software.
  14 .\"
  15 .\" THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
  16 .\" IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
  17 .\" FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT.  IN NO EVENT SHALL
  18 .\" THE AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
  19 .\" LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING
  20 .\" FROM, OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER
  21 .\" DEALINGS IN THE SOFTWARE.
  22 .\"
  23 .TH XkbForceBell __libmansuffix__ __xorgversion__ "XKB FUNCTIONS"
  24 .SH NAME
  25 XkbForceBell \- Overrides user preference settings for audible bells to ring the
  26 bell on the default keyboard
  27 .SH SYNOPSIS
  28 .HP
  29 .B Bool XkbForceBell
  30 .BI "(\^Display *" "display" "\^,"
  31 .BI "int " "percent" "\^);"
  32 .if n .ti +5n
  33 .if t .ti +.5i
  34 .SH ARGUMENTS
  35 .TP
  36 .I \- display
  37 connection to the X server
  38 .TP
  39 .I \- percent
  40 volume for the bell, which can range from -100 to 100 inclusive
  41 .SH DESCRIPTION
  42 .LP
  43 The core X protocol allows only applications to explicitly sound the system bell
  44 with a
  45 given duration, pitch, and volume. Xkb extends this capability by allowing clients
  46 to
  47 attach symbolic names to bells, disable audible bells, and receive an event whenever
  48 the
  49 keyboard bell is rung. For the purposes of this document, the
  50 .I audible
  51 bell is defined to be the system bell, or the default keyboard bell, as opposed to
  52 any
  53 other audible sound generated elsewhere in the system.
  54 You can ask to receive XkbBellNotify events when any client rings any one of the
  55 following:
  56
  57 .IP \(bu 5
  58 The default bell
  59 .IP \(bu 5
  60 Any bell on an input device that can be specified by a bell_class and bell_id pair
  61 .IP \(bu 5
  62 Any bell specified only by an arbitrary name. (This is, from the server's point of
  63 view,
  64 merely a name, and not connected with any physical sound-generating device. Some
  65 client
  66 application must generate the sound, or visual feedback, if any, that is associated
  67 with
  68 the name.)
  69
  70 .LP
  71 You can also ask to receive XkbBellNotify events when the server rings the default
  72 bell
  73 or if any client has requested events only (without the bell sounding) for any of
  74 the
  75 bell types previously listed.
  76
  77 You can disable audible bells on a global basis. For example, a client that replaces
  78 the
  79 keyboard bell with some other audible cue might want to turn off the AudibleBell
  80 control
  81 to prevent the server from also generating a sound and avoid cacophony. If you
  82 disable
  83 audible bells and request to receive XkbBellNotify events, you can generate feedback
  84 different from the default bell.
  85
  86 You can, however, override the AudibleBell control by calling one of the functions
  87 that
  88 force the ringing of a bell in spite of the setting of the AudibleBell control -
  89 .I XkbForceDeviceBell
  90 or
  91 .I XkbForceBell.
  92 In this case the server does not generate a bell event.
  93
  94 Just as some keyboards can produce keyclicks to indicate when a key is pressed or
  95 repeating, Xkb can provide feedback for the controls by using special beep codes.
  96 The
  97 AccessXFeedback control is used to configure the specific types of operations that
  98 generate feedback.
  99
 100 .B Bell Names
 101
 102 You can associate a name to an act of ringing a bell by converting the name to an
 103 Atom
 104 and then using this name when you call the functions listed in this chapter. If an
 105 event
 106 is generated as a result, the name is then passed to all other clients interested in
 107 receiving XkbBellNotify events. Note that these are arbitrary names and that there
 108 is no
 109 binding to any sounds. Any sounds or other effects (such as visual bells on the
 110 screen)
 111 must be generated by a client application upon receipt of the bell event containing
 112 the
 113 name. There is no default name for the default keyboard bell. The server does
 114 generate
 115 some predefined bells for the AccessX controls. These named bells are shown in the
 116 Table 1; the name is included in any bell event sent to clients that have requested to
 117 receive XkbBellNotify events.
 118
 119 .TS
 120 c s
 121 l l
 122 lW(4i) l.
 123 Table 1 Predefined Bells
 124 _
 125 Action  Named Bell
 126 _
 127 Indicator turned on     AX_IndicatorOn
 128 Indicator turned off    AX_IndicatorOff
 129 More than one indicator changed state   AX_IndicatorChange
 130 Control turned on       AX_FeatureOn
 131 Control turned off      AX_FeatureOff
 132 More than one control changed state     AX_FeatureChange
 133 T{
 134 SlowKeys and BounceKeys about to be turned on or off
 135 T}      AX_SlowKeysWarning
 136 SlowKeys key pressed    AX_SlowKeyPress
 137 SlowKeys key accepted   AX_SlowKeyAccept
 138 SlowKeys key rejected   AX_SlowKeyReject
 139 Accepted SlowKeys key released  AX_SlowKeyRelease
 140 BounceKeys key rejected AX_BounceKeyReject
 141 StickyKeys key latched  AX_StickyLatch
 142 StickyKeys key locked   AX_StickyLock
 143 StickyKeys key unlocked AX_StickyUnlock
 144 .TE
 145
 146 .B Audible Bells
 147
 148 Using Xkb you can generate bell events that do not necessarily ring the system bell.
 149 This
 150 is useful if you need to use an audio server instead of the system beep. For
 151 example,
 152 when an audio client starts, it could disable the audible bell (the system bell) and
 153 then
 154 listen for XkbBellNotify events. When it receives a XkbBellNotify event, the audio
 155 client
 156 could then send a request to an audio server to play a sound.
 157
 158 You can control the audible bells feature by passing the XkbAudibleBellMask to
 159 .I XkbChangeEnabledControls.
 160 If you set XkbAudibleBellMask on, the server rings the system bell when a bell event
 161 occurs. This is the default. If you set XkbAudibleBellMask off and a bell event
 162 occurs,
 163 the server does not ring the system bell unless you call
 164 .I XkbForceDeviceBell
 165 or
 166 .I XkbForceBell.
 167
 168 Audible bells are also part of the per-client auto-reset controls.
 169
 170 Bell Functions
 171
 172 Use the functions described in this section to ring bells and to generate bell
 173 events.
 174
 175 The input extension has two types of feedbacks that can generate bells - bell
 176 feedback
 177 and keyboard feedback. Some of the functions in this section have
 178 .I bell_class
 179 and
 180 .I bell_id
 181 parameters; set them as follows: Set
 182 .I bell_class
 183 to BellFeedbackClass or KbdFeedbackClass. A device can have more than one feedback
 184 of
 185 each type; set
 186 .I bell_id
 187 to the particular bell feedback of
 188 .I bell_class
 189 type.
 190
 191 Table 2 shows the conditions that cause a bell to sound or an XkbBellNotifyEvent to be generated when a bell function is
 192 called.
 193
 194 .TS
 195 c s s s
 196 l l l l
 197 l l l l.
 198 Table 2 Bell Sounding and Bell Event Generating
 199 _
 200 Function called AudibleBell     Server sounds a bell    Server sends an
 201 XkbBellNotifyEvent
 202 _
 203 XkbDeviceBell   On      Yes     Yes
 204 XkbDeviceBell   Off     No      Yes
 205 XkbBell On      Yes     Yes
 206 XkbBell Off     No      Yes
 207 XkbDeviceBellEvent      On or Off       No      Yes
 208 XkbBellEvent    On or Off       No      Yes
 209 XkbDeviceForceBell      On or Off       Yes     No
 210 XkbForceBell    On or Off       Yes     No
 211 .TE
 212
 213
 214 If a compatible keyboard extension isn't present in the X server,
 215 .I XkbForceBell
 216 calls
 217 .I XBell
 218 with the specified
 219 .I display
 220 and
 221 .I percent
 222 and returns False. Otherwise,
 223 .I XkbForceBell
 224 calls
 225 .I XkbForceDeviceBell
 226 with the specified
 227 .I display
 228 and
 229 .I percent, device_spec
 230 =XkbUseCoreKbd,
 231 .I bell_class
 232 = XkbDfltXIClass,
 233 .I bell_id
 234 = XkbDfltXIId,
 235 .I window
 236 = None, and
 237 .I name
 238 = NULL, and returns what
 239 .I XkbForceDeviceBell
 240 returns.
 241
 242 .I XkbForceBell
 243 does not cause an XkbBellNotify event.
 244
 245 You can call
 246 .I XkbBell
 247 without first initializing the keyboard extension.
 248 .SH "RETURNS VALUES"
 249 .TP 15
 250 False
 251 The
 252 .I XkbForceBell
 253 function returns False when a compatible keyboard extension isn't present in the X server.
 254 .SH STRUCTURES
 255 .LP
 256 Xkb generates XkbBellNotify events for all bells except for those resulting from
 257 calls to
 258 .I XkbForceDeviceBell
 259 and
 260 .I XkbForceBell.
 261 To receive XkbBellNotify events under all possible conditions, pass
 262 XkbBellNotifyMask in
 263 both the
 264 .I bits_to_change
 265 and
 266 .I values_for_bits
 267 parameters to
 268 .I XkbSelectEvents.
 269
 270 The XkbBellNotify event has no event details. It is either selected or it is not.
 271 However, you can call
 272 .I XkbSelectEventDetails
 273 using XkbBellNotify as the
 274 .I event_type
 275 and specifying XkbAllBellNotifyMask in
 276 .I bits_to_change
 277 and
 278 .I values_for_bits.
 279 This has the same effect as a call to
 280 .I XkbSelectEvents.
 281
 282 The structure for the XkbBellNotify event type contains:
 283 .nf
 284
 285    typedef struct _XkbBellNotify {
 286        int            type;        /\(** Xkb extension base event code */
 287        unsigned long  serial;      /\(** X server serial number for event */
 288        Bool           send_event;  /\(** True => synthetically generated */
 289        Display *      display;     /\(** server connection where event generated */
 290        Time           time;        /\(** server time when event generated */
 291        int            xkb_type;    /\(** XkbBellNotify */
 292        unsigned int   device;      /\(** Xkb device ID, will not be XkbUseCoreKbd */
 293        int            percent;     /\(** requested volume as % of max */
 294        int            pitch;       /\(** requested pitch in Hz */
 295        int            duration;    /\(** requested duration in microseconds */
 296        unsigned int   bell_class;  /\(** X input extension feedback class */
 297        unsigned int   bell_id;     /\(** X input extension feedback ID */
 298        Atom           name;        /\(** "name" of requested bell */
 299        Window         window;      /\(** window associated with event */
 300        Bool           event_only;  /\(** False -> the server did not produce a beep */
 301    } XkbBellNotifyEvent;
 302
 303 .fi
 304 If your application needs to generate visual bell feedback on the screen when it
 305 receives
 306 a bell event, use the window ID in the XkbBellNotifyEvent, if present.
 307
 308 .SH "SEE ALSO"
 309 .BR XBell (__libmansuffix__),
 310 .BR XkbBell (__libmansuffix__),
 311 .BR XkbChangeEnabledControls (__libmansuffix__),
 312 .BR XkbForceDeviceBell (__libmansuffix__),
 313 .BR XkbSelectEventDetails (__libmansuffix__),
 314 .BR XkbSelectEvents (__libmansuffix__)