diff options
Diffstat (limited to 'libXaw/spec/Toggle')
| -rw-r--r-- | libXaw/spec/Toggle | 370 |
1 files changed, 0 insertions, 370 deletions
diff --git a/libXaw/spec/Toggle b/libXaw/spec/Toggle deleted file mode 100644 index 12a605bd2..000000000 --- a/libXaw/spec/Toggle +++ /dev/null @@ -1,370 +0,0 @@ -.\" $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. - |