aboutsummaryrefslogtreecommitdiff
path: root/libXaw/spec/Toggle
diff options
context:
space:
mode:
authormarha <marha@users.sourceforge.net>2009-11-06 06:59:46 +0000
committermarha <marha@users.sourceforge.net>2009-11-06 06:59:46 +0000
commitace7902333b6f61aab5a6035dbcb222763bff186 (patch)
tree28445e829d5f04c8d79bda2514be37d5fb29738e /libXaw/spec/Toggle
parentc9179017c7e70703b7cac46c2df8b950506319e0 (diff)
downloadvcxsrv-ace7902333b6f61aab5a6035dbcb222763bff186.tar.gz
vcxsrv-ace7902333b6f61aab5a6035dbcb222763bff186.tar.bz2
vcxsrv-ace7902333b6f61aab5a6035dbcb222763bff186.zip
Added libXaw-1.0.7
Diffstat (limited to 'libXaw/spec/Toggle')
-rw-r--r--libXaw/spec/Toggle370
1 files changed, 370 insertions, 0 deletions
diff --git a/libXaw/spec/Toggle b/libXaw/spec/Toggle
new file mode 100644
index 000000000..12a605bd2
--- /dev/null
+++ b/libXaw/spec/Toggle
@@ -0,0 +1,370 @@
+.\" $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.
+