371 lines
12 KiB
Plaintext
371 lines
12 KiB
Plaintext
.\" $Xorg: Toggle,v 1.3 2000/08/17 19:42:29 cpqbld Exp $
|
|
.NH 2
|
|
Toggle Widget
|
|
.XS
|
|
Toggle Widget
|
|
.XE
|
|
.IN "Toggle widget" "" "@DEF@"
|
|
.Ds 0
|
|
.TA 2.0i
|
|
.ta 2.0i
|
|
.sp
|
|
Application Header file <Xaw/Toggle.h>
|
|
.IN "Toggle.h" ""
|
|
Class Header file <Xaw/ToggleP.h>
|
|
.IN "ToggleP.h" ""
|
|
Class toggleWidgetClass
|
|
.IN "toggleWidgetClass" ""
|
|
Class Name Toggle
|
|
.IN "Toggle widget" "class name"
|
|
Superclass Command
|
|
.sp
|
|
.De
|
|
.LP
|
|
The Toggle widget is an area, often rectangular,
|
|
that displays a graphic. The graphic may be a text
|
|
string containing multiple lines of characters in an 8
|
|
bit or 16 bit character set (to be displayed with a
|
|
\fIfont\fP), or in a multi-byte encoding (for use with
|
|
a \fIfontset\fP). The graphic may also be a bitmap or
|
|
pixmap.
|
|
.LP
|
|
This widget maintains a Boolean state (e.g.
|
|
True/False or On/Off) and changes state whenever it is selected. When
|
|
the pointer is on the Toggle widget, the Toggle widget may become highlighted by
|
|
drawing a rectangle around its perimeter. This highlighting indicates
|
|
that the Toggle widget is ready for selection. When pointer button 1 is
|
|
pressed and released, the Toggle widget indicates that it has changed
|
|
state by reversing its foreground and background colors, and its
|
|
\fBnotify\fP action is invoked, calling all functions on its callback
|
|
list. If the pointer is moved off of the widget before the pointer button is
|
|
released, the Toggle widget reverts to its previous foreground and background
|
|
colors, and releasing the pointer button has no effect. This behavior allows
|
|
the user to cancel the operation.
|
|
.LP
|
|
Toggle widgets may also be part of a ``radio group.'' A radio group is a
|
|
.IN "Radio groups" ""
|
|
.IN "Radio button" ""
|
|
.IN "Toggle widget" "used in radio groups"
|
|
list of at least two Toggle widgets in which no more than one Toggle may
|
|
be set at
|
|
any time. A radio group is identified by the widget ID of any one of
|
|
its members. The convenience routine \fBXawToggleGetCurrent\fP will
|
|
return information about the Toggle widget in the radio group.
|
|
.LP
|
|
Toggle widget state is preserved across changes in sensitivity.
|
|
.NH 3
|
|
Resources
|
|
.LP
|
|
When creating a Toggle widget instance, the following resources are
|
|
retrieved from the argument list or from the resource database:
|
|
.LP
|
|
.IN "Toggle widget" "resources"
|
|
.TS H
|
|
expand;
|
|
lw(1i) lw(1i) lw(1i) lw(.5i) lw(2i).
|
|
_
|
|
.sp 3p
|
|
.TB
|
|
Name Class Type Notes Default Value
|
|
.sp 3p
|
|
_
|
|
.TH
|
|
.R
|
|
.sp 3p
|
|
accelerators Accelerators AcceleratorTable NULL
|
|
ancestorSensitive AncestorSensitive Boolean D True
|
|
background Background Pixel XtDefaultBackground
|
|
backgroundPixmap Pixmap Pixmap XtUnspecifiedPixmap
|
|
bitmap Bitmap Pixmap None
|
|
borderColor BorderColor Pixel XtDefaultForeground
|
|
borderPixmap Pixmap Pixmap XtUnspecifiedPixmap
|
|
borderWidth BorderWidth Dimension 1
|
|
callback Callback XtCallbackList NULL
|
|
colormap Colormap Colormap Parent's Colormap
|
|
cornerRoundPercent CornerRoundPercent Dimension 25
|
|
cursor Cursor Cursor None
|
|
cursorName Cursor String NULL
|
|
depth Depth int C Parent's Depth
|
|
destroyCallback Callback XtCallbackList NULL
|
|
encoding Encoding UnsignedChar XawTextEncoding8bit
|
|
font Font XFontStruct XtDefaultFont
|
|
fontSet FontSet XFontSet XtDefaultFontSet
|
|
foreground Foreground Pixel XtDefaultForeground
|
|
height Height Dimension A graphic height + 2 * \fBinternalHeight\fP
|
|
highlightThickness Thickness Dimension A 2 (0 if Shaped)
|
|
insensitiveBorder Insensitive Pixmap GreyPixmap
|
|
internalHeight Height Dimension 2
|
|
internalWidth Width Dimension 4
|
|
international International Boolean C False
|
|
justify Justify Justify XtJustifyCenter (center)
|
|
label Label String name of widget
|
|
leftBitmap LeftBitmap Bitmap None
|
|
mappedWhenManaged MappedWhenManaged Boolean True
|
|
pointerColor Foreground Pixel XtDefaultForeground
|
|
pointerColorBackground Background Pixel XtDefaultBackground
|
|
radioData RadioData Pointer Name of widget
|
|
radioGroup Widget Widget No radio group
|
|
resize Resize Boolean True
|
|
screen Screen Screen R Parent's Screen
|
|
sensitive Sensitive Boolean True
|
|
shapeStype ShapeStyle ShapeStyle Rectangle
|
|
state State Boolean Off
|
|
translations Translations TranslationTable See below
|
|
width Width Dimension A graphic width + 2 * \fBinternalWidth\fP
|
|
x Position Position 0
|
|
y Position Position 0
|
|
.sp 3p
|
|
_
|
|
.TE
|
|
.Ac
|
|
.As
|
|
.Bg
|
|
.Gp
|
|
.Bm
|
|
.Bc
|
|
.Bp
|
|
.Bw
|
|
.Cb
|
|
.Cm
|
|
.Cr
|
|
.Cu
|
|
.Cn
|
|
.Dp
|
|
.Dc
|
|
.Le
|
|
.Lf
|
|
.Ls
|
|
.Lg
|
|
.Hw
|
|
.Ht
|
|
.Ib
|
|
.Ih
|
|
.In
|
|
.Ju
|
|
.La
|
|
.Ll
|
|
.Mm
|
|
.Pf
|
|
.Pb
|
|
.IP \fBradioData\fP 1.5i
|
|
Specifies the data that will be returned by \fBXawToggleGetCurrent\fP
|
|
when this is the currently \fIset\fP widget in the radio group. This
|
|
value is also used to identify the Toggle that will be set by a call to
|
|
\fBXawToggleSetCurrent\fP. The value NULL will be returned by
|
|
\fBXawToggleGetCurrent\fP if no widget in a radio group is currently
|
|
set. Programmers must not specify NULL (or Zero) as \fBradioData\fP.
|
|
.IP \fBradioGroup\fP 1.5i
|
|
Specifies another Toggle widget that is in the radio group to which this
|
|
Toggle widget should be added. A radio group is a group of at least two Toggle
|
|
widgets, only one of which may be \fIset\fP at a time. If this value is
|
|
NULL (the default) then the Toggle will not be part of any radio group
|
|
and can change state without affecting any other Toggle widgets. If the
|
|
widget specified in this resource is not already in a radio group then a
|
|
new radio group will be created containing these two Toggle widgets. No
|
|
Toggle widget can be in multiple radio groups. The behavior of a radio
|
|
group of one toggle is undefined. A converter is registered which will
|
|
convert widget names to widgets without caching.
|
|
.Re
|
|
.Sc
|
|
.Se
|
|
.Ss
|
|
.IP \fBstate\fP
|
|
Specifies whether the Toggle widget is set (\fBTrue\fP) or unset
|
|
(\fBFalse\fP).
|
|
.Tr
|
|
.Xy
|
|
.NH 3
|
|
Toggle Actions
|
|
.IN "Toggle widget" "actions"
|
|
.LP
|
|
The Toggle widget supports the following actions:
|
|
.IP \(bu 5
|
|
Switching the Toggle widget between the foreground and background
|
|
colors with \fBset\fP and \fBunset\fP and \fBtoggle\fP
|
|
.IP \(bu 5
|
|
Processing application callbacks with \fBnotify\fP
|
|
.IP \(bu 5
|
|
Switching the internal border between highlighted
|
|
and unhighlighted states with \fBhighlight\fP and \fBunhighlight\fP
|
|
.LP
|
|
The following are the default translation bindings used by the
|
|
Toggle widget:
|
|
.IN "Toggle widget" "default translation table"
|
|
.LP
|
|
.sp
|
|
.Ds 0
|
|
.TA .5i 2.25i
|
|
.ta .5i 2.25i
|
|
<EnterWindow>: highlight(Always)
|
|
<LeaveWindow>: unhighlight(\|)
|
|
<Btn1Down>,<Btn1Up>: toggle(\|) notify(\|)
|
|
.De
|
|
.NH 3
|
|
Toggle Actions
|
|
.LP
|
|
The full list of actions supported by Toggle is:
|
|
.IP \fBhighlight\fP(\fIcondition\fP) 1.5i
|
|
Displays the internal highlight border in the color (\fBforeground\fP
|
|
or \fBbackground\fP ) that contrasts with the interior color of the
|
|
Toggle widget. The conditions \fBWhenUnset\fP and \fBAlways\fP are
|
|
understood by this action procedure. If no argument is passed then
|
|
\fBWhenUnset\fP is assumed.
|
|
.IP \fBunhighlight\fP(\|) 1.5i
|
|
Displays the internal highlight border in the color (\fBforeground\fP
|
|
or \fBbackground\fP ) that matches the interior color of the
|
|
Toggle widget.
|
|
.IP \fBset\fP(\|) 1.5i
|
|
Enters the \fIset\fP state, in which \fBnotify\fP is possible. This
|
|
action causes the Toggle widget to display its interior in the
|
|
\fBforeground\fP color. The label or bitmap is displayed in the
|
|
\fBbackground\fP color.
|
|
.IP \fBunset\fP(\|) 1.5i
|
|
Cancels the \fIset\fP state and displays the interior of the Toggle widget in the
|
|
\fBbackground\fP color. The label or bitmap is displayed in the
|
|
\fBforeground\fP color.
|
|
.IP \fBtoggle\fP(\|) 1.5i
|
|
Changes the current state of the Toggle widget, causing to be set
|
|
if it was previously unset, and unset if it was previously set.
|
|
If the widget is to be set, and is in a radio group then this procedure may
|
|
unset another Toggle widget causing all routines on its callback list
|
|
to be invoked. The callback routines for the Toggle that
|
|
is to be unset will be called before the one that is to be set.
|
|
.IP \fBreset\fP(\|) 1.5i
|
|
Cancels any \fBset\fP or \fBhighlight\fP and displays the interior of the
|
|
Toggle widget in the \fBbackground\fP color, with the label displayed in the
|
|
\fBforeground\fP color.
|
|
.IP \fBnotify\fP(\|) 1.5i
|
|
When the Toggle widget is in the \fBset\fP state this action calls all functions in
|
|
the callback list named by the \fBcallback\fP resource. The value of
|
|
the call_data argument in these callback functions is undefined.
|
|
.LP
|
|
.NT
|
|
When a bitmap of depth greater that one (1) is specified the
|
|
\fIset\fP(), \fIunset\fP(), and \fIreset\fP() actions have no effect,
|
|
since there are no foreground and background colors used in a
|
|
multi-plane pixmap.
|
|
.NE
|
|
.NH 3
|
|
Radio Groups
|
|
.IN "Radio groups"
|
|
.LP
|
|
There are typically two types of radio groups desired by applications.
|
|
The default translations for the Toggle widget implement a "zero or one
|
|
.IN "Radio groups" "zero or one of many"
|
|
of many" radio group. This means that there may be no more than one
|
|
Toggle widget active, but there need not be any Toggle widgets active.
|
|
.LP
|
|
The other type of radio group is "one of many" and has the more strict
|
|
.IN "Radio groups" "one of many"
|
|
policy that there will always be exactly one radio button active.
|
|
Toggle widgets can be used to provide this interface with a slight
|
|
modification to the translation table of each Toggle in the group.
|
|
.Ds 0
|
|
.TA .5i 2.25i
|
|
.ta .5i 2.25i
|
|
.sp
|
|
<EnterWindow>: highlight(Always)
|
|
<LeaveWindow>: unhighlight(\|)
|
|
<Btn1Down>,<Btn1Up>: set(\|) notify(\|)
|
|
.sp
|
|
.De
|
|
This translation table will not allow any Toggle to be \fIunset\fP
|
|
except as a result of another Toggle becoming \fIset\fP. It is
|
|
the application programmer's responsibility to choose an initial
|
|
state for the radio group by setting the \fBstate\fP resource of one of
|
|
its member widgets to \fBTrue\fP.
|
|
.NH 3
|
|
Convenience Routines
|
|
.LP
|
|
The following functions allow easy access to the Toggle widget's radio
|
|
group functionality.
|
|
.NH 4
|
|
Changing the Toggle's Radio Group.
|
|
.LP
|
|
To enable an application to change the Toggle's radio group, add
|
|
the Toggle to a radio group, or remove the Toggle from a radio group, use
|
|
\fBXawToggleChangeRadioGroup\fP.
|
|
.IN "XawToggleChangeRadioGroup" "" "@DEF@"
|
|
.FD
|
|
void XawToggleChangeRadioGroup(\fIw\fP, \fIradio_group\fP)
|
|
.br
|
|
Widget \fIw\fP, \fIradio_group\fP;
|
|
.FN
|
|
.IP \fIw\fP 1i
|
|
Specifies the Toggle widget.
|
|
.IP \fIradio_group\fP 1i
|
|
Specifies any Toggle in the new radio group. If NULL then the Toggle
|
|
will be removed from any radio group of which it is a member.
|
|
.LP
|
|
If a Toggle is already \fIset\fP in the new radio group,
|
|
and the Toggle to be added is also \fIset\fP then the previously
|
|
\fIset\fP Toggle in the radio group is \fIunset\fP and its callback
|
|
procedures are invoked.
|
|
.SH
|
|
Finding the Currently selected Toggle in a radio group of Toggles
|
|
.LP
|
|
To find the currently selected Toggle in a radio group of Toggle widgets
|
|
use
|
|
\fBXawToggleGetCurrent\fP.
|
|
.IN "XawToggleGetCurrent" "" "@DEF@"
|
|
.FD
|
|
XtPointer XawToggleGetCurrent(\fIradio_group\fP);
|
|
.br
|
|
Widget \fIradio_group\fP;
|
|
.FN
|
|
.IP \fIradio_group\fP 1i
|
|
Specifies any Toggle widget in the radio group.
|
|
.LP
|
|
The value returned by this function is the
|
|
.PN radioData
|
|
of the Toggle in this radio group that is currently set. The default
|
|
value for
|
|
.PN radioData
|
|
is the name of that Toggle widget. If no Toggle is set in the radio
|
|
group specified then NULL is returned.
|
|
.SH
|
|
Changing the Toggle that is set in a radio group.
|
|
.LP
|
|
To change the Toggle that is currently set in a radio group use
|
|
\fBXawToggleSetCurrent\fP.
|
|
.IN "XawToggleSetCurrent" "" "@DEF@"
|
|
.FD
|
|
void XawToggleSetCurrent(\fIradio_group\fP, \fIradio_data\fP);
|
|
.br
|
|
Widget \fIradio_group\fP;
|
|
XtPointer \fIradio_data\fP;
|
|
.FN
|
|
.IP \fIradio_group\fP 1i
|
|
Specifies any Toggle widget in the radio group.
|
|
.IP \fIradio_data\fP 1i
|
|
Specifies the
|
|
.PN radioData
|
|
identifying the Toggle that should be set in the radio group specified
|
|
by the \fIradio_group\fP argument.
|
|
.LP
|
|
\fBXawToggleSetCurrent\fP locates the Toggle widget to be set by
|
|
matching \fIradio_data\fP against the \fBradioData\fP for each Toggle in
|
|
the radio group. If none match, \fBXawToggleSetCurrent\fP returns
|
|
without making any changes. If more than one Toggle matches,
|
|
\fBXawToggleSetCurrent\fP will choose a Toggle to set arbitrarily. If
|
|
this causes any Toggle widgets to change state, all routines in their
|
|
callback lists will be invoked. The callback routines for a Toggle that
|
|
is to be unset will be called before the one that is to be set.
|
|
.SH
|
|
Unsetting all Toggles in a radio group.
|
|
.LP
|
|
To unset all Toggle widgets in a radio group use
|
|
\fBXawToggleUnsetCurrent\fP.
|
|
.IN "XawToggleUnsetCurrent" "" "@DEF@"
|
|
.FD
|
|
void XawToggleUnsetCurrent(\fIradio_group\fP);
|
|
.br
|
|
Widget \fIradio_group\fP;
|
|
.FN
|
|
.IP \fIradio_group\fP 1i
|
|
Specifies any Toggle widget in the radio group.
|
|
.LP
|
|
If this causes a Toggle widget to change state, all routines on its
|
|
callback list will be invoked.
|
|
|