1<?xml version="1.0" encoding="UTF-8" ?> 2<!DOCTYPE chapter PUBLIC "-//OASIS//DTD DocBook XML V4.3//EN" 3 "http://www.oasis-open.org/docbook/xml/4.3/docbookx.dtd"> 4<chapter id='Bells'> 5<title>Bells</title> 6<indexterm zone="Bells"><primary>bell</primary></indexterm> 7 8<para> 9The core X protocol allows only applications to explicitly sound the system 10bell with a given duration, pitch, and volume. Xkb extends this capability by 11allowing clients to attach symbolic names to bells, disable audible bells, and 12receive an event whenever the keyboard bell is rung. For the purposes of this 13document, the 14<firstterm>audible</firstterm> 15<indexterm significance="preferred" zone="Bells"> 16<primary>audible bell</primary></indexterm> 17<indexterm significance="preferred" zone="Bells"> 18<primary>bell</primary><secondary>audible</secondary></indexterm> 19bell is defined to be the system bell, or the default keyboard bell, as 20opposed to any other audible sound generated elsewhere in the system. 21</para> 22 23 24<para> 25You can ask to receive 26<symbol>XkbBellNotify</symbol> 27events (see <link linkend="Detecting_Bells">section 9.4</link>) when any client rings any one of the following: 28</para> 29 30<itemizedlist> 31<listitem> 32 <para> 33The default bell 34 </para> 35</listitem> 36<listitem> 37 <para> 38Any bell on an input device that can be specified by a 39<structfield>bell_class</structfield> 40and 41<structfield>bell_id</structfield> 42pair 43 </para> 44</listitem> 45<listitem> 46 <para> 47Any bell specified only by an arbitrary name. (This is, from the server’s 48point of view, merely a name, and not connected with any physical 49sound-generating device. Some client application must generate the sound, or 50visual feedback, if any, that is associated with the name.) 51 </para> 52</listitem> 53</itemizedlist> 54 55<para> 56You can also ask to receive 57<symbol>XkbBellNotify</symbol> 58events when the server rings the default bell or if any client has requested 59events only (without the bell sounding) for any of the bell types previously 60listed. 61</para> 62 63<para> 64You can disable audible bells on a global basis (to set the 65<emphasis>AudibleBell</emphasis> 66control, see <xref linkend="Keyboard_Controls" />). For example, a client that replaces the keyboard 67bell with some other audible cue might want to turn off the 68<emphasis>AudibleBell</emphasis> 69control to prevent the server from also generating a sound and avoid 70cacophony. If you disable audible bells and request to receive 71<symbol>XkbBellNotify</symbol> 72events, you can generate feedback different from the default bell. 73</para> 74 75 76<para> 77You can, however, override the 78<emphasis>AudibleBell</emphasis> 79control by calling one of the functions that force the ringing of a bell in 80spite of the setting of the 81<emphasis>AudibleBell</emphasis> 82control — 83<function>XkbForceDeviceBell</function> 84or 85<function>XkbForceBell</function> 86(see <link linkend="Forcing_a_Server_Generated_Bell">section 9.3.3</link>). In this case the server does not generate a bell event. 87</para> 88 89 90<para> 91Just as some keyboards can produce keyclicks to indicate when a key is pressed 92or repeating, Xkb can provide feedback for the controls by using special beep 93codes. The 94<emphasis>AccessXFeedback</emphasis> 95control is used to configure the specific types of operations that generate 96feedback. See <link linkend="The_AccessXFeedback_Control">section 10.6.3</link> for a discussion on 97<emphasis>AccessXFeedback</emphasis> 98control. 99</para> 100 101<para> 102This chapter describes bell names, the functions used to generate named bells, 103and the events the server generates for bells. 104</para> 105 106<sect1 id='Bell_Names'> 107<title>Bell Names</title> 108 109<para> 110You can associate a name to an act of ringing a bell by converting the name to 111an Atom and then using this name when you call the functions listed in this 112chapter. If an event is generated as a result, the name is then passed to all 113other clients interested in receiving 114<symbol>XkbBellNotify</symbol> 115events. Note that these are arbitrary names and that there is no binding to 116any sounds. Any sounds or other effects (such as visual bells on the screen) 117must be generated by a client application upon receipt of the bell event 118containing the name. There is no default name for the default keyboard bell. 119The server does generate some predefined bells for the AccessX controls (see 120<link linkend="The_AccessXFeedback_Control">section 10.6.3</link>). 121These named bells are shown in <link linkend="table9.1">Table 9.1</link>; 122the name is included 123in any bell event sent to clients that have requested to receive 124<symbol>XkbBellNotify</symbol> 125events. 126</para> 127 128<table id='table9.1' frame='topbot'> 129<title>Predefined Bells</title> 130<?dbfo keep-together="always" ?> 131<tgroup cols='2' align='left' colsep='0' rowsep='0'> 132<colspec colname='c1' colwidth='1.0*'/> 133<colspec colname='c2' colwidth='1.0*'/> 134<thead> 135<row rowsep='1'> 136 <entry>Action</entry> 137 <entry>Named Bell</entry> 138</row> 139</thead> 140<tbody> 141<row> 142 <entry>Indicator turned on</entry> 143 <entry>AX_IndicatorOn</entry> 144</row> 145<row> 146 <entry>Indicator turned off</entry> 147 <entry>AX_IndicatorOff</entry> 148</row> 149<row> 150 <entry>More than one indicator changed state</entry> 151 <entry>AX_IndicatorChange</entry> 152</row> 153<row> 154 <entry>Control turned on</entry> 155 <entry>AX_FeatureOn</entry> 156</row> 157<row> 158 <entry>Control turned off</entry> 159 <entry>AX_FeatureOff</entry> 160</row> 161<row> 162 <entry>More than one control changed state</entry> 163 <entry>AX_FeatureChange</entry> 164</row> 165<row> 166 <entry>SlowKeys and BounceKeys about to be turned on or off</entry> 167 <entry>AX_SlowKeysWarning</entry> 168</row> 169<row> 170 <entry>SlowKeys key pressed</entry> 171 <entry>AX_SlowKeyPress</entry> 172</row> 173<row> 174 <entry>SlowKeys key accepted</entry> 175 <entry>AX_SlowKeyAccept</entry> 176</row> 177<row> 178 <entry>SlowKeys key rejected</entry> 179 <entry>AX_SlowKeyReject</entry> 180</row> 181<row> 182 <entry>Accepted SlowKeys key released</entry> 183 <entry>AX_SlowKeyRelease</entry> 184</row> 185<row> 186 <entry>BounceKeys key rejected</entry> 187 <entry>AX_BounceKeyReject</entry> 188</row> 189<row> 190 <entry>StickyKeys key latched</entry> 191 <entry>AX_StickyLatch</entry> 192</row> 193<row> 194 <entry>StickyKeys key locked</entry> 195 <entry>AX_StickyLock</entry> 196</row> 197<row> 198 <entry>StickyKeys key unlocked</entry> 199 <entry>AX_StickyUnlock</entry> 200 </row> 201</tbody> 202</tgroup> 203</table> 204 205</sect1> 206<sect1 id='Audible_Bells'> 207<title>Audible Bells</title> 208 209<para> 210Using Xkb you can generate bell events that do not necessarily ring the system 211bell. This is useful if you need to use an audio server instead of the system 212beep. For example, when an audio client starts, it could disable the audible 213bell (the system bell) and then listen for 214<symbol>XkbBellNotify</symbol> 215events (see <link linkend="Detecting_Bells">section 9.4</link>). When it receives a 216<symbol>XkbBellNotify</symbol> 217event, the audio client could then send a request to an audio server to play a 218sound. 219</para> 220 221 222<para> 223You can control the audible bells feature by passing the 224<symbol>XkbAudibleBellMask</symbol> 225to 226<function>XkbChangeEnabledControls</function> 227(see <link linkend="The_EnabledControls_Control">section 10.1.1</link>). If you set 228<symbol>XkbAudibleBellMask</symbol> 229on, the server rings the system bell when a bell event occurs. This is the 230default. If you set 231<symbol>XkbAudibleBellMask</symbol> 232off and a bell event occurs, the server does not ring the system bell unless 233you call 234<function>XkbForceDeviceBell</function> 235or 236<function>XkbForceBell</function> 237(see <link linkend="Forcing_a_Server_Generated_Bell">section 9.3.3</link>). 238</para> 239 240<para> 241Audible bells are also part of the per-client auto-reset controls. For more 242information on auto-reset controls, see <link linkend="The_AutoReset_Control">section 10.1.2</link>. 243</para> 244 245</sect1> 246<sect1 id='Bell_Functions'> 247<title>Bell Functions</title> 248 249<para> 250Use the functions described in this section to ring bells and to generate bell 251events. 252</para> 253 254<para> 255The input extension has two types of feedbacks that can generate bells — bell 256feedback and keyboard feedback. Some of the functions in this section have 257<structfield>bell_class</structfield> 258and 259<structfield>bell_id</structfield> 260parameters; set them as follows: Set 261<structfield>bell_class</structfield> 262to 263<symbol>BellFeedbackClass</symbol> 264or 265<symbol>KbdFeedbackClass</symbol>. 266A device can have more than one feedback of each type; set 267<structfield>bell_id</structfield> 268to the particular bell feedback of 269<structfield>bell_class</structfield> 270type. 271</para> 272 273<para> 274<link linkend="table9.2">Table 9.2</link> shows the conditions that cause 275a bell to sound or an <structname>XkbBellNotifyEvent</structname> 276to be generated when a bell function is called. 277</para> 278 279<table id='table9.2' frame='topbot'> 280<title>Bell Sounding and Bell Event Generating</title> 281<?dbfo keep-together="always" ?> 282<tgroup cols='4' align='left' colsep='0' rowsep='0'> 283<colspec colname='c1' colwidth='1.0*'/> 284<colspec colname='c2' colwidth='1.0*'/> 285<colspec colname='c3' colwidth='1.0*'/> 286<colspec colname='c4' colwidth='1.0*'/> 287<thead> 288 <row rowsep='1'> 289 <entry>Function called</entry> 290 <entry>AudibleBell</entry> 291 <entry>Server sounds a bell</entry> 292 <entry>Server sends an XkbBellNotifyEvent</entry> 293 </row> 294</thead> 295<tbody> 296<row> 297 <entry>XkbDeviceBell</entry> 298 <entry>On</entry> 299 <entry>Yes</entry> 300 <entry>Yes</entry> 301</row> 302<row> 303 <entry>XkbDeviceBell</entry> 304 <entry>Off</entry> 305 <entry>No</entry> 306 <entry>Yes</entry> 307</row> 308<row> 309 <entry>XkbBell</entry> 310 <entry>On</entry> 311 <entry>Yes</entry> 312 <entry>Yes</entry> 313</row> 314<row> 315 <entry>XkbBell</entry> 316 <entry>Off</entry> 317 <entry>No</entry> 318 <entry>Yes</entry> 319</row> 320<row> 321 <entry>XkbDeviceBellEvent</entry> 322 <entry>On or Off</entry> 323 <entry>No</entry> 324 <entry>Yes</entry> 325</row> 326<row> 327 <entry>XkbBellEvent</entry> 328 <entry>On or Off</entry> 329 <entry>No</entry> 330 <entry>Yes</entry> 331</row> 332<row> 333 <entry>XkbDeviceForceBell</entry> 334 <entry>On or Off</entry> 335 <entry>Yes</entry> 336 <entry>No</entry> 337</row> 338<row> 339 <entry>XkbForceBell</entry> 340 <entry>On or Off</entry> 341 <entry>Yes</entry> 342 <entry>No</entry> 343 </row> 344</tbody> 345</tgroup> 346</table> 347 348<sect2 id='Generating_Named_Bells'> 349<title>Generating Named Bells</title> 350 351<para> 352To ring the bell on an X input extension device or the default keyboard, use 353<function>XkbDeviceBell</function>. 354</para> 355 356<indexterm significance="preferred" zone="XkbDeviceBell"><primary><function>XkbDeviceBell</function></primary></indexterm> 357<funcsynopsis id="XkbDeviceBell"> 358 <funcprototype> 359 <funcdef>Bool <function>XkbDeviceBell</function></funcdef> 360<!-- ( 361<parameter>display, window, device_id, bell_class, bell_id, percent, name</parameter> 362) --> 363 364 <paramdef>Display *<parameter>display</parameter></paramdef> 365 <paramdef>Window <parameter>window</parameter></paramdef> 366 <paramdef>unsigned int <parameter>device_spec</parameter></paramdef> 367 <paramdef>unsigned int <parameter>bell_class</parameter></paramdef> 368 <paramdef>unsigned int <parameter>bell_id</parameter></paramdef> 369 <paramdef>int <parameter>percent</parameter></paramdef> 370 <paramdef>Atom <parameter>name</parameter></paramdef> 371 </funcprototype> 372</funcsynopsis> 373<variablelist> 374 <varlistentry> 375 <term> 376 <parameter>display</parameter> 377 </term> 378 <listitem> 379 <para> 380 connection to the X server 381 </para> 382 </listitem> 383 </varlistentry> 384 <varlistentry> 385 <term> 386 <parameter>window</parameter> 387 </term> 388 <listitem> 389 <para> 390 window for which the bell is generated, or None 391 </para> 392 </listitem> 393 </varlistentry> 394 <varlistentry> 395 <term> 396 <parameter>device_spec</parameter> 397 </term> 398 <listitem> 399 <para> 400 device ID, or <symbol>XkbUseCoreKbd</symbol> 401 </para> 402 </listitem> 403 </varlistentry> 404 <varlistentry> 405 <term> 406 <parameter>bell_class</parameter> 407 </term> 408 <listitem> 409 <para> 410 X input extension bell class of the bell to be rung 411 </para> 412 </listitem> 413 </varlistentry> 414 <varlistentry> 415 <term> 416 <parameter>bell_id</parameter> 417 </term> 418 <listitem> 419 <para> 420 X input extension bell ID of the bell to be rung 421 </para> 422 </listitem> 423 </varlistentry> 424 <varlistentry> 425 <term> 426 <parameter>percent</parameter> 427 </term> 428 <listitem> 429 <para> 430 bell volume, from −100 to 100 inclusive 431 </para> 432 </listitem> 433 </varlistentry> 434 <varlistentry> 435 <term> 436 <parameter>name</parameter> 437 </term> 438 <listitem> 439 <para> 440 a name for the bell, or <symbol>NULL</symbol> 441 </para> 442 </listitem> 443 </varlistentry> 444</variablelist> 445 446<para> 447Set 448<parameter>percent</parameter> 449to be the volume relative to the base volume for the keyboard as described for 450<function>XBell</function>. 451</para> 452 453<para> 454Note that 455<parameter>bell_class</parameter> 456and 457<parameter>bell_id</parameter> 458indicate the bell to physically ring. 459<parameter>name</parameter> 460is simply an arbitrary moniker for the client application’s use. 461</para> 462 463<para> 464To determine the current feedback settings of an extension input device, use 465<function>XGetFeedbackControl</function>. 466See <olink targetdoc='inputlib' targetptr='Controlling_Device_Feedback'>the 467X input extension documentation</olink> for more information on 468<function>XGetFeedbackControl</function> 469and related data structures. 470</para> 471 472<para> 473If a compatible keyboard extension is not present in the X server, 474<function>XkbDeviceBell</function> 475immediately returns 476<symbol>False</symbol>. 477Otherwise, 478<function>XkbDeviceBell</function> 479rings the bell as specified for the display and keyboard device and returns 480<symbol>True</symbol>. 481If you have disabled the audible bell, the server does not ring the system 482bell, although it does generate a 483<symbol>XkbBellNotify</symbol> 484event. 485</para> 486 487<para> 488You can call 489<function>XkbDeviceBell</function> 490without first initializing the keyboard extension. 491</para> 492 493<para> 494As a convenience function, Xkb provides a function to ring the bell on the 495default keyboard: 496<function>XkbBell</function>. 497</para> 498 499<indexterm significance="preferred" zone="XkbBell"><primary><function>XkbBell</function></primary></indexterm> 500<funcsynopsis id="XkbBell"> 501 <funcprototype> 502 <funcdef>Bool <function>XkbBell</function></funcdef> 503<!-- ( 504<parameter>display, window, percent, name</parameter> 505) --> 506 507 <paramdef>Display *<parameter>display</parameter></paramdef> 508 <paramdef>Window <parameter>window</parameter></paramdef> 509 <paramdef>int <parameter>percent</parameter></paramdef> 510 <paramdef>Atom <parameter>name</parameter></paramdef> 511 </funcprototype> 512</funcsynopsis> 513<variablelist> 514 <varlistentry> 515 <term> 516 <parameter>display</parameter> 517 </term> 518 <listitem> 519 <para> 520 connection to the X server 521 </para> 522 </listitem> 523 </varlistentry> 524 <varlistentry> 525 <term> 526 <parameter>window</parameter> 527 </term> 528 <listitem> 529 <para> 530 event window, or None 531 </para> 532 </listitem> 533 </varlistentry> 534 <varlistentry> 535 <term> 536 <parameter>percent</parameter> 537 </term> 538 <listitem> 539 <para> 540 relative volume, which can range from −100 to 100 inclusive 541 </para> 542 </listitem> 543 </varlistentry> 544 <varlistentry> 545 <term> 546 <parameter>name</parameter> 547 </term> 548 <listitem> 549 <para> 550 a bell name, or <symbol>NULL</symbol> 551 </para> 552 </listitem> 553 </varlistentry> 554</variablelist> 555 556<para> 557If a compatible keyboard extension isn’t present in the X server, 558<function>XkbBell</function> 559calls 560<function>XBell</function> 561with the specified 562<parameter>display</parameter> 563and 564<parameter>percent</parameter>, 565and returns 566<symbol>False</symbol>. 567Otherwise, 568<function>XkbBell</function> 569calls 570<function>XkbDeviceBell</function> 571with the specified 572<parameter>display</parameter>, 573<parameter>window</parameter>, 574<parameter>percent</parameter>, 575and 576<parameter>name</parameter>, 577a 578<structfield>device_spec</structfield> 579of 580<symbol>XkbUseCoreKbd</symbol>, 581a 582<structfield>bell_class</structfield> 583of 584<symbol>XkbDfltXIClass</symbol>, 585and a 586<structfield>bell_id</structfield> 587of 588<symbol>XkbDfltXIId</symbol>, 589and returns 590<symbol>True</symbol>. 591</para> 592 593<para> 594If you have disabled the audible bell, the server does not ring the system 595bell, although it does generate a 596<symbol>XkbBellNotify</symbol> 597event. 598</para> 599 600<para> 601You can call 602<function>XkbBell</function> 603without first initializing the keyboard extension. 604</para> 605 606</sect2> 607<sect2 id='Generating_Named_Bell_Events'> 608<title>Generating Named Bell Events</title> 609 610<para> 611Using Xkb, you can also generate a named bell event that does not ring any 612bell. This allows you to do things such as generate events when your 613application starts. 614</para> 615 616<para> 617For example, if an audio client listens for these types of bells, it can 618produce a <quote>whoosh</quote> sound when it receives a named bell event to indicate a 619client just started. In this manner, applications can generate start-up 620feedback and not worry about producing annoying beeps if an audio server is not 621running. 622</para> 623 624 625<para> 626To cause a bell event for an X input extension device or for the keyboard, 627without ringing the corresponding bell, use 628<function>XkbDeviceBellEvent</function>. 629</para> 630 631<indexterm significance="preferred" zone="XkbDeviceBellEvent"><primary><function>XkbDeviceBellEvent</function></primary></indexterm> 632<funcsynopsis id="XkbDeviceBellEvent"> 633 <funcprototype> 634 <funcdef>Bool <function>XkbDeviceBellEvent</function></funcdef> 635<!-- ( 636<parameter>display, window, device_spec, bell_class, bell_id, percent, name</parameter> 637) --> 638 639 <paramdef>Display *<parameter>display</parameter></paramdef> 640 <paramdef>Window <parameter>window</parameter></paramdef> 641 <paramdef>unsigned int <parameter>device_spec</parameter></paramdef> 642 <paramdef>unsigned int <parameter>bell_class</parameter></paramdef> 643 <paramdef>unsigned int <parameter>bell_id</parameter></paramdef> 644 <paramdef>int <parameter>percent</parameter></paramdef> 645 <paramdef>Atom <parameter>name</parameter></paramdef> 646 </funcprototype> 647</funcsynopsis> 648<variablelist> 649 <varlistentry> 650 <term> 651 <parameter>display</parameter> 652 </term> 653 <listitem> 654 <para> 655 connection to the X server 656 </para> 657 </listitem> 658 </varlistentry> 659 <varlistentry> 660 <term> 661 <parameter>window</parameter> 662 </term> 663 <listitem> 664 <para> 665 event window, or None 666 </para> 667 </listitem> 668 </varlistentry> 669 <varlistentry> 670 <term> 671 <parameter>device_spec</parameter> 672 </term> 673 <listitem> 674 <para> 675 device ID, or <symbol>XkbUseCoreKbd</symbol> 676 </para> 677 </listitem> 678 </varlistentry> 679 <varlistentry> 680 <term> 681 <parameter>bell_class</parameter> 682 </term> 683 <listitem> 684 <para> 685 input extension bell class for the event 686 </para> 687 </listitem> 688 </varlistentry> 689 <varlistentry> 690 <term> 691 <parameter>bell_id</parameter> 692 </term> 693 <listitem> 694 <para> 695 input extension bell ID for the event 696 </para> 697 </listitem> 698 </varlistentry> 699 <varlistentry> 700 <term> 701 <parameter>percent</parameter> 702 </term> 703 <listitem> 704 <para> 705 volume for the bell, which can range from −100 to 100 inclusive 706 </para> 707 </listitem> 708 </varlistentry> 709 <varlistentry> 710 <term> 711 <parameter>name</parameter> 712 </term> 713 <listitem> 714 <para> 715 a bell name, or <symbol>NULL</symbol> 716 </para> 717 </listitem> 718 </varlistentry> 719</variablelist> 720 721<para> 722If a compatible keyboard extension isn’t present in the X server, 723<function>XkbDeviceBellEvent</function> 724immediately returns 725<symbol>False</symbol>. 726Otherwise, 727<function>XkbDeviceBellEvent</function> 728causes an 729<symbol>XkbBellNotify</symbol> 730event to be sent to all interested clients and returns 731<symbol>True</symbol>. 732Set 733<parameter>percent</parameter> 734to be the volume relative to the base volume for the keyboard as described for 735<function>XBell</function>. 736</para> 737 738 739<para> 740In addition, 741<function>XkbDeviceBellEvent</function> 742may generate 743<type>Atom</type> 744protocol errors as well as 745<symbol>XkbBellNotify</symbol> 746events. You can call 747<function>XkbBell</function> 748without first initializing the keyboard extension. 749</para> 750 751 752<para> 753As a convenience function, Xkb provides a function to cause a bell event for 754the keyboard without ringing the bell: 755<function>XkbBellEvent</function>. 756</para> 757 758 759<indexterm significance="preferred" zone="XkbBellEvent"><primary><function>XkbBellEvent</function></primary></indexterm> 760<funcsynopsis id="XkbBellEvent"> 761 <funcprototype> 762 <funcdef>Bool <function>XkbBellEvent</function></funcdef> 763<!-- ( 764<parameter>display, window, percent, name</parameter> 765) --> 766 767 <paramdef>Display *<parameter>display</parameter></paramdef> 768 <paramdef>Window <parameter>window</parameter></paramdef> 769 <paramdef>int <parameter>percent</parameter></paramdef> 770 <paramdef>Atom <parameter>name</parameter></paramdef> 771 </funcprototype> 772</funcsynopsis> 773<variablelist> 774 <varlistentry> 775 <term> 776 <parameter>display</parameter> 777 </term> 778 <listitem> 779 <para> 780 connection to the X server 781 </para> 782 </listitem> 783 </varlistentry> 784 <varlistentry> 785 <term> 786 <parameter>window</parameter> 787 </term> 788 <listitem> 789 <para> 790 the event window, or None 791 </para> 792 </listitem> 793 </varlistentry> 794 <varlistentry> 795 <term> 796 <parameter>percent</parameter> 797 </term> 798 <listitem> 799 <para> 800 relative volume, which can range from −100 to 100 inclusive 801 </para> 802 </listitem> 803 </varlistentry> 804 <varlistentry> 805 <term> 806 <parameter>name</parameter> 807 </term> 808 <listitem> 809 <para> 810 a bell name, or <symbol>NULL</symbol> 811 </para> 812 </listitem> 813 </varlistentry> 814</variablelist> 815 816<para> 817If a compatible keyboard extension isn’t present in the X server, 818<function>XkbBellEvent</function> 819immediately returns 820<symbol>False</symbol>. 821Otherwise, 822<function>XkbBellEvent</function> 823calls 824<function>XkbDeviceBellEvent</function> 825with the specified 826<parameter>display</parameter>, 827<parameter>window</parameter>, 828<parameter>percent</parameter>, 829and 830<parameter>name</parameter>, 831a 832<structfield>device_spec</structfield> 833of 834<symbol>XkbUseCoreKbd</symbol>, 835a 836<structfield>bell_class</structfield> 837of 838<symbol>XkbDfltXIClass</symbol>, 839and a 840<structfield>bell_id</structfield> 841of 842<symbol>XkbDfltXIId</symbol>, 843and returns what 844<function>XkbDeviceBellEvent</function> 845returns. 846</para> 847 848<para> 849<function>XkbBellEvent</function> 850generates a <symbol>XkbBellNotify</symbol> 851event. 852</para> 853 854 855<para> 856You can call 857<function>XkbBellEvent</function> 858without first initializing the keyboard extension. 859</para> 860 861</sect2> 862<sect2 id='Forcing_a_Server_Generated_Bell'> 863<title>Forcing a Server-Generated Bell</title> 864 865<para> 866To ring the bell on any keyboard, overriding user preference settings for 867audible bells, use <function>XkbForceDeviceBell</function>. 868</para> 869 870<indexterm significance="preferred" zone="XkbForceDeviceBell"><primary><function>XkbForceDeviceBell</function></primary></indexterm> 871<funcsynopsis id="XkbForceDeviceBell"> 872 <funcprototype> 873 <funcdef>Bool <function>XkbForceDeviceBell</function></funcdef> 874<!-- ( 875<parameter>display, window, device_spec, bell_class, bell_id, percent</parameter> 876) --> 877 878 <paramdef>Display *<parameter>display</parameter></paramdef> 879 <paramdef>Window <parameter>window</parameter></paramdef> 880 <paramdef>unsigned int <parameter>device_spec</parameter></paramdef> 881 <paramdef>unsigned int <parameter>bell_class</parameter></paramdef> 882 <paramdef>unsigned int <parameter>bell_id</parameter></paramdef> 883 <paramdef>int <parameter>percent</parameter></paramdef> 884 </funcprototype> 885</funcsynopsis> 886<variablelist> 887 <varlistentry> 888 <term> 889 <parameter>display</parameter> 890 </term> 891 <listitem> 892 <para> 893 connection to the X server 894 </para> 895 </listitem> 896 </varlistentry> 897 <varlistentry> 898 <term> 899 <parameter>window</parameter> 900 </term> 901 <listitem> 902 <para> 903 event window, or None 904 </para> 905 </listitem> 906 </varlistentry> 907 <varlistentry> 908 <term> 909 <parameter>device_spec</parameter> 910 </term> 911 <listitem> 912 <para> 913 device ID, or <symbol>XkbUseCoreKbd</symbol> 914 </para> 915 </listitem> 916 </varlistentry> 917 <varlistentry> 918 <term> 919 <parameter>bell_class</parameter> 920 </term> 921 <listitem> 922 <para> 923 input extension class of the bell to be rung 924 </para> 925 </listitem> 926 </varlistentry> 927 <varlistentry> 928 <term> 929 <parameter>bell_id</parameter> 930 </term> 931 <listitem> 932 <para> 933 input extension ID of the bell to be rung 934 </para> 935 </listitem> 936 </varlistentry> 937 <varlistentry> 938 <term> 939 <parameter>percent</parameter> 940 </term> 941 <listitem> 942 <para> 943 relative volume, which can range from −100 to 100 inclusive 944 </para> 945 </listitem> 946 </varlistentry> 947</variablelist> 948 949<para> 950If a compatible keyboard extension isn’t present in the X server, 951<function>XkbForceDeviceBell</function> 952immediately returns 953<symbol>False</symbol>. 954Otherwise, 955<function>XkbForceDeviceBell</function> 956rings the bell as specified for the display and keyboard device and returns 957<symbol>True</symbol>. 958Set 959<parameter>percent</parameter> 960to be the volume relative to the base volume for the keyboard as described for 961<function>XBell</function>. 962There is no 963<structfield>name</structfield> 964parameter because 965<function>XkbForceDeviceBell</function> 966does not cause an 967<symbol>XkbBellNotify</symbol> 968event. 969</para> 970 971<para> 972You can call 973<function>XkbBell</function> 974without first initializing the keyboard extension. 975</para> 976 977<para> 978To ring the bell on the default keyboard, overriding user preference settings 979for audible bells, use 980<function>XkbForceBell</function>. 981</para> 982 983<indexterm significance="preferred" zone="XkbForceBell"><primary><function>XkbForceBell</function></primary></indexterm> 984<funcsynopsis id="XkbForceBell"> 985 <funcprototype> 986 <funcdef>Bool <function>XkbForceBell</function></funcdef> 987<!-- ( 988<parameter>display, percent)</parameter> --> 989 990 <paramdef>Display *<parameter>display</parameter></paramdef> 991 <paramdef>int <parameter>percent</parameter></paramdef> 992 </funcprototype> 993</funcsynopsis> 994<variablelist> 995 <varlistentry> 996 <term> 997 <parameter>display</parameter> 998 </term> 999 <listitem> 1000 <para> 1001 connection to the X server 1002 </para> 1003 </listitem> 1004 </varlistentry> 1005 <varlistentry> 1006 <term> 1007 <parameter>percent</parameter> 1008 </term> 1009 <listitem> 1010 <para> 1011 volume for the bell, which can range from −100 to 100 inclusive 1012 </para> 1013 </listitem> 1014 </varlistentry> 1015</variablelist> 1016 1017<para> 1018If a compatible keyboard extension isn’t present in the X server, 1019<function>XkbForceBell</function> 1020calls 1021<function>XBell</function> 1022with the specified 1023<parameter>display</parameter> 1024and 1025<parameter>percent</parameter> 1026and returns 1027<symbol>False</symbol>. 1028Otherwise, 1029<function>XkbForceBell</function> 1030calls 1031<function>XkbForceDeviceBell</function> 1032with the specified 1033<parameter>display</parameter> 1034and 1035<parameter>percent</parameter>, 1036<structfield>device_spec</structfield> 1037= 1038<symbol>XkbUseCoreKbd</symbol>, 1039<structfield>bell_class</structfield> 1040= 1041<symbol>XkbDfltXIClass</symbol>, 1042<structfield>bell_id</structfield> 1043= 1044<symbol>XkbDfltXIId</symbol>, 1045<structfield>window</structfield> 1046= None, and 1047<structfield>name</structfield> 1048= 1049<symbol>NULL</symbol>, 1050and returns what 1051<function>XkbForceDeviceBell</function> 1052returns. 1053</para> 1054 1055<para> 1056<function>XkbForceBell</function> 1057does not cause an 1058<symbol>XkbBellNotify</symbol> 1059event. 1060</para> 1061 1062<para> 1063You can call 1064<function>XkbBell</function> 1065without first initializing the keyboard extension. 1066</para> 1067 1068</sect2> 1069</sect1> 1070<sect1 id='Detecting_Bells'> 1071<title>Detecting Bells</title> 1072 1073<para> 1074Xkb generates 1075<symbol>XkbBellNotify</symbol> 1076events for all bells except for those resulting from calls to 1077<function>XkbForceDeviceBell</function> 1078and 1079<function>XkbForceBell</function>. 1080To receive 1081<symbol>XkbBellNotify</symbol> 1082events under all possible conditions, pass 1083<symbol>XkbBellNotifyMask</symbol> 1084in both the 1085<parameter>bits_to_change</parameter> 1086and 1087<parameter>values_for_bits</parameter> 1088parameters to 1089<function>XkbSelectEvents</function> 1090(see <link linkend="Selecting_Xkb_Events">section 4.3</link>). 1091</para> 1092 1093<para> 1094The 1095<symbol>XkbBellNotify</symbol> 1096event has no event details. It is either selected or it is not. However, you 1097can call 1098<function>XkbSelectEventDetails</function> 1099using 1100<symbol>XkbBellNotify</symbol> 1101as the 1102<structfield>event_type</structfield> 1103and specifying 1104<symbol>XkbAllBellEventsMask</symbol> 1105in 1106<parameter>bits_to_change</parameter> 1107and 1108<parameter>values_for_bits</parameter>. 1109This has the same effect as a call to 1110<function>XkbSelectEvents</function>. 1111</para> 1112 1113<para> 1114The structure for the 1115<symbol>XkbBellNotify</symbol> 1116event type contains: 1117 1118<programlisting> 1119typedef struct _XkbBellNotify { 1120 int type; /* Xkb extension base event code */ 1121 unsigned long serial; /* X server serial number for event */ 1122 Bool send_event; /* <symbol>True</symbol> ⇒ synthetically generated */ 1123 Display * display; /* server connection where event generated */ 1124 Time time; /* server time when event generated */ 1125 int xkb_type; /* <symbol>XkbBellNotify</symbol> */ 1126 unsigned int device; /* Xkb device ID, will not be <symbol>XkbUseCoreKbd</symbol> */ 1127 int percent; /* requested volume as % of max */ 1128 int pitch; /* requested pitch in Hz */ 1129 int duration; /* requested duration in microseconds */ 1130 unsigned int bell_class; /* X input extension feedback class */ 1131 unsigned int bell_id; /* X input extension feedback ID */ 1132 Atom name; /* "name" of requested bell */ 1133 Window window; /* window associated with event */ 1134 Bool event_only; /* <symbol>False</symbol> → the server did not produce a beep */ 1135} <structname>XkbBellNotifyEvent</structname>; 1136</programlisting></para> 1137 1138<para> 1139If your application needs to generate visual bell feedback on the screen when 1140it receives a bell event, use the window ID in the 1141<structname>XkbBellNotifyEvent</structname>, 1142if present. 1143</para> 1144 1145</sect1> 1146</chapter> 1147