diff options
Diffstat (limited to 'libXaw/spec/Toggle')
| -rw-r--r-- | libXaw/spec/Toggle | 370 |
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. + |