320 lines
11 KiB
Groff
320 lines
11 KiB
Groff
|
'\" 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__)
|
||
|
|
|
||
|
|
|
||
|
|
|
||
|
|
|