diff options
Diffstat (limited to 'vendor/x11iraf/obm/ObmW/Group.man')
| -rw-r--r-- | vendor/x11iraf/obm/ObmW/Group.man | 723 |
1 files changed, 723 insertions, 0 deletions
diff --git a/vendor/x11iraf/obm/ObmW/Group.man b/vendor/x11iraf/obm/ObmW/Group.man new file mode 100644 index 00000000..7d3900bf --- /dev/null +++ b/vendor/x11iraf/obm/ObmW/Group.man @@ -0,0 +1,723 @@ +.\"remove .ig hn for full docs +.de hi +.ig eh +.. +.de eh +.. +.TH "" 3 "" "Version 3.0" "Free Widget Foundation" +.SH NAME +XfwfGroup +.SH DESCRIPTION +The Group widget is a subclass of RowCol, which means that it +arranges its children in rows and columns. (See the RowCol widget for +the resources that influence the layout.) The Group widget adds two +things to the capabilities already present in RowCol, namely a label +in the upper left hand corner and the ability to make a number of +Toggle buttons act as radio buttons. + +The label is a short, one line piece of text, that is displayed over +the border in the top left corner. The border is interupted at that +point. Since this works best with `ledged' or `chiseled' border +types, the default border is \fIXfwfChiseled\fP. + +The special support for radio buttons works as follows: when a child +is added the Group widget checks if it is of class \fIXfwfToggle\fP or a +subclass thereof. If so, the Group widget installs a callback in it. +When the toggle button is then activated, the Group widget determines +which other buttons need to be turned off. All toggle buttons are +given an implicit number. The first one to be added is number 0. + +There are three selection styles, settable through the +\fIselectionStyle\fP resource: + +1) `single' (\fIXfwfSingleSelection\fP) means that at most one of the +toggle buttons may be on, but it is possible that they are all off. +When one of the buttons is turned on, all others are turned off +automatically. The resource \fIselection\fP holds the number of the button +that is on, or -1 if they are all off. + +2) `one' (\fIXfwfOneSelection\fP) means that at all times exactly one +button is turned on. It is not possible to turn buttons off, except by +toggling another one to on. The resource \fIselection\fP holds the number +of the button that is currently on. + +3) `multi' or `multiple' (\fIXfwfMultipleSelection\fP) means that any +number of buttons may be on. No buttons are turned off automatically. +The resource \fIselection\fP has one bit set for each button that is on. +Thus, if buttons 1, 4 and 5 are on, the value of \fIselection\fP is (1<<1 ++ 1<<4 + 1<<5 =) 0x62. Note that this limits the number of buttons +that is recorded in \fIselection\fP to the first 32. It is still possible +to have more buttons, but the application will then have to use +callbacks or other means to keep track of the toggle buttons. + +4) `none' (\fIXfwfNoSelection\fP) turns off any special handling of toggle +buttons. The value of the \fIselection\fP resource is undefined. + +Applications may of course install callbacks on the toggle buttons, +but a simpler way is to attach to the \fIactivateCallback\fP of the Group +widget itself, or use no callback at all and simply inspect the +\fIselection\fP resource when needed. + +It is recommended that application visually differentiate between +selection styles. One way would be to use different graphics in the +toggle buttons, e.g., the Motif convention that radiobuttons have an +empty or colored diamond, and non-exclusive toggles a square. +Suitable icons are already defined by the Common widget. + +.SS "Public variables" + +.ps-2 +.TS +center box; +cBsss +lB|lB|lB|lB +l|l|l|l. +XfwfGroup +Name Class Type Default +XtNlabel XtCLabel String NULL +XtNfont XtCFont FontStruct XtDefaultFont +XtNforeground XtCForeground Pixel XtDefaultForeground +XtNselectionStyle XtCSelectionStyle SelectionType XfwfSingleSelection +XtNselection XtCSelection Long 0 +XtNactivate XtCActivate Callback NULL + +.TE +.ps + +.TP +.I "XtNlabel" +The label must be a single line. It is displayed superimposed on the +frame, in the upper lefthand corner. Currently, it must be simple +string in a single font. + + + +.hi + +.nf +String label = NULL +.fi + +.eh + +.TP +.I "XtNfont" +The font for the label is set with \fIfont\fP. + + + +.hi + +.nf +<FontStruct> XFontStruct * font = <String>XtDefaultFont +.fi + +.eh + +.TP +.I "XtNforeground" +The foreground color is the color used to draw the text. + + + +.hi + +.nf +Pixel foreground = <String>XtDefaultForeground +.fi + +.eh + +.TP +.I "XtNselectionStyle" +The \fIselectionStyle\fP resource determines how the Group widget treats +the child widgets that are of class \fIXfwfToggle\fP or a subclass +thereof. The possible values are \fIXfwfNoSelection\fP, +\fIXfwfSingleSelection\fP (default), \fIXfwfOneSelection\fP and +\fIXfwfMultipleSelection\fP. The meaning is as explained above. There is a +converter from strings, that recognizes the strings `no', `none', +`single', `one', `multi', and `multiple', in upper or lower case. + + + +.hi + +.nf +SelectionType selectionStyle = XfwfSingleSelection +.fi + +.eh + +.TP +.I "XtNselection" +The resource \fIselection\fP holds the state of the toggle buttons (if +any). If \fIselectionType = XfwfSingleSelection\fP or \fIXfwfOneSelection\fP, +it holds the number of the buttons that is currently on, or -1 if they +are all off. If \fIselectionType = XfwfMultipleSelection\fP, it is a +bitmap with one bit set for each button that is on. (See the +introduction above for more information.) + +The value can also be set (e.g., through \fIXtSetValues\fP); the result is +that the corresponding toggle buttons will be turned on or off. + + + +.hi + +.nf +long selection = 0 +.fi + +.eh + +.TP +.I "XtNactivate" +The callback \fIactivate\fP can be used by applications that want to be +informed of any change to the state of the toggle buttons as soon as +it happens. Other applications can simply use \fIXtGetValues\fP to get the +value of the \fIselection\fP resource. The callback will be called with +the value of \fIselection\fP as \fIcall_data\fP argument. + + + +.hi + +.nf +<Callback> XtCallbackList activate = NULL +.fi + +.eh + +.TP +.I "XtNframeType" +The default border type is different from that of its superclass +RowCol. It is set to \fIXfwfChiseled\fP because that is the conventional +border type around radio buttons, and because it looks better when +there is a label superimposed on it. + + + +.hi + +.nf +FrameType frameType = XfwfChiseled +.fi + +.eh + +.TP +.I "XtNinnerOffset" +The default value for \fIinnerOffset\fP is set to 3 pixels, which makes +it a little bit more likely that the descenders of the label will stay +visible. + + + +.hi + +.nf + innerOffset = 3 +.fi + +.eh + +.ps-2 +.TS +center box; +cBsss +lB|lB|lB|lB +l|l|l|l. +XfwfRowCol +Name Class Type Default +XtNstoreByRow XtCStoreByRow Boolean True +XtNrows XtCRows Int 0 +XtNcolumns XtCColumns Int 0 +XtNalignment XtCAlignment Alignment XfwfTopLeft +XtNshrinkToFit XtCShrinkToFit Boolean False + +.TE +.ps + +.ps-2 +.TS +center box; +cBsss +lB|lB|lB|lB +l|l|l|l. +XfwfBoard +Name Class Type Default +XtNabs_x XtCAbs_x Position 0 +XtNrel_x XtCRel_x Float "0.0" +XtNabs_y XtCAbs_y Position 0 +XtNrel_y XtCRel_y Float "0.0" +XtNabs_width XtCAbs_width Position 0 +XtNrel_width XtCRel_width Float "1.0" +XtNabs_height XtCAbs_height Position 0 +XtNrel_height XtCRel_height Float "1.0" +XtNhunit XtCHunit Float "1.0" +XtNvunit XtCVunit Float "1.0" +XtNlocation XtCLocation String NULL + +.TE +.ps + +.ps-2 +.TS +center box; +cBsss +lB|lB|lB|lB +l|l|l|l. +XfwfFrame +Name Class Type Default +XtNcursor XtCCursor Cursor None +XtNframeType XtCFrameType FrameType XfwfRaised +XtNframeWidth XtCFrameWidth Dimension 0 +XtNouterOffset XtCOuterOffset Dimension 0 +XtNinnerOffset XtCInnerOffset Dimension 0 +XtNshadowScheme XtCShadowScheme ShadowScheme XfwfAuto +XtNtopShadowColor XtCTopShadowColor Pixel compute_topcolor +XtNbottomShadowColor XtCBottomShadowColor Pixel compute_bottomcolor +XtNtopShadowStipple XtCTopShadowStipple Bitmap NULL +XtNbottomShadowStipple XtCBottomShadowStipple Bitmap NULL + +.TE +.ps + +.ps-2 +.TS +center box; +cBsss +lB|lB|lB|lB +l|l|l|l. +XfwfCommon +Name Class Type Default +XtNtraversalOn XtCTraversalOn Boolean True +XtNhighlightThickness XtCHighlightThickness Dimension 2 +XtNhighlightColor XtCHighlightColor Pixel XtDefaultForeground +XtNhighlightPixmap XtCHighlightPixmap Pixmap None +XtNnextTop XtCNextTop Callback NULL +XtNuserData XtCUserData Pointer NULL + +.TE +.ps + +.ps-2 +.TS +center box; +cBsss +lB|lB|lB|lB +l|l|l|l. +Composite +Name Class Type Default +XtNchildren XtCChildren WidgetList NULL +insertPosition XtCInsertPosition XTOrderProc NULL +numChildren XtCNumChildren Cardinal 0 + +.TE +.ps + +.ps-2 +.TS +center box; +cBsss +lB|lB|lB|lB +l|l|l|l. +Core +Name Class Type Default +XtNx XtCX Position 0 +XtNy XtCY Position 0 +XtNwidth XtCWidth Dimension 0 +XtNheight XtCHeight Dimension 0 +borderWidth XtCBorderWidth Dimension 0 +XtNcolormap XtCColormap Colormap NULL +XtNdepth XtCDepth Int 0 +destroyCallback XtCDestroyCallback XTCallbackList NULL +XtNsensitive XtCSensitive Boolean True +XtNtm XtCTm XTTMRec NULL +ancestorSensitive XtCAncestorSensitive Boolean False +accelerators XtCAccelerators XTTranslations NULL +borderColor XtCBorderColor Pixel 0 +borderPixmap XtCBorderPixmap Pixmap NULL +background XtCBackground Pixel 0 +backgroundPixmap XtCBackgroundPixmap Pixmap NULL +mappedWhenManaged XtCMappedWhenManaged Boolean True +XtNscreen XtCScreen Screen * NULL + +.TE +.ps + +.SS "Exports" + +The \fISelectionType\fP type is exported to the public header file. + + + +.nf + +.B type + SelectionType = enum { + XfwfNoSelection, XfwfSingleSelection, + XfwfOneSelection, XfwfMultipleSelection } +.fi + +.hi +.SH "Importss" + +.nf + +.B incl + <Xfwf/Toggle.h> +.fi + +.nf + +.B incl + <stdio.h> +.fi + +.nf + +.B incl + <X11/Xmu/Converters.h> +.fi + +.nf + +.B incl + <Xfwf/Converters.h> +.fi + +.hi + +.hi +.SS "Private variables" + +The GC is used for the text. + + + +.nf +GC textgc +.fi + +The private variable \fItoggle_ord\fP holds the number that will be +assigned to the next child that is a toggle button. The first toggle +will be number 0. + + + +.nf +Cardinal toggle_ord +.fi + +.hi + +.hi +.SS "Methods" + +The type converter from String to SelectionType is installed here. + +.nf +class_initialize() +{ + XtAddConverter(XtRString, XtRLong, XmuCvtStringToLong, NULL, 0); + XtSetTypeConverter(XtRLong, XtRString, XfwfCvtLongToString, + NULL, 0, XtCacheNone, NULL); + XtSetTypeConverter(XtRString, XtRSelectionType, cvtStringToSelectionType, + NULL, 0, XtCacheNone, NULL); + XtSetTypeConverter(XtRSelectionType, XtRString, cvtSelectionTypeToString, + NULL, 0, XtCacheNone, NULL); +} +.fi + +The \fIinitialize\fP method initializes the private variables. + +.nf +initialize(Widget request, $, ArgList args, Cardinal * num_args) +{ + $toggle_ord = 0; + $textgc = NULL; + make_textgc($); + if ($selectionStyle == XfwfOneSelection $selection == -1L) { + XtWarning + ("Illegal combination of selectionStyle and selection resources"); + $selection = 0; + } +} +.fi + +The \fIset_values\fP method has to deal with changes in \fIlabel\fP, \fIfont\fP, +\fIselectionType\fP or \fIselection\fP. A change in \fIselection\fP or +\fIselectionType\fP means that all toggle buttons must be set to on or off +according to the new values. + +.nf +Boolean set_values(Widget old, Widget request, $, ArgList args, Cardinal * num_args) +{ + Boolean need_redraw = False; + + if ($old$label != $label) { + XtFree($old$label); + $label = XtNewString($label); + need_redraw = True; + } + if ($font != $old$font) { + make_textgc($); + if ($label != NULL) need_redraw = True; + } + if ($old$selection != $selection + || $old$selectionStyle != $selectionStyle) { + if ($selectionStyle == XfwfOneSelection $selection == -1L) + $selection = 0; + set_toggles($); + } + return need_redraw; +} +.fi + +The \fIexpose\fP method first calls the \fIexpose\fP method of its +superclass -- which basically just draws the frame -- and then adds +the label to it. + +.nf +expose($, XEvent * event, Region region) +{ + Dimension w, h; + Position x, y; + + if (! XtIsRealized($)) return; + #expose($, event, region); + $compute_inside($, x, y, w, h); + XDrawImageString(XtDisplay($), XtWindow($), $textgc, x + 3, + y - $innerOffset, $label, strlen($label)); +} +.fi + +When a child is added, the Group widget checks to see if it is a +Toggle button. If it is, and the \fIselectionStyle\fP resource is not +\fIXfwfNoSelection\fP, then the toggle button is assigned a number and two +callbacks are installed in it. The callbacks' task is to record any +changes in the state of the togle button in the Group widget's +\fIselection\fP resource and also to make sure that no more and no fewer +buttons are turned on then is allowed by the \fIselectionStyle\fP. + +It doesn't matter whether the new child is managed or not: any child +that is (a subclass of) an XfwfToggle button gets two callbacks and a +number. + +The \fIon\fP resource of the new child is also set in accordance with the +current value of the Group's \fIselection\fP resource. + +.nf +insert_child(Widget child) +{ + #insert_child(child); + if ($selectionStyle != XfwfNoSelection + XtIsSubclass(child, xfwfToggleWidgetClass)) { + XtAddCallback(child, XtNonCallback, on_cb, (XtPointer) $toggle_ord); + XtAddCallback(child, XtNoffCallback, off_cb, (XtPointer) $toggle_ord); + switch ($selectionStyle) { + case XfwfOneSelection: + case XfwfSingleSelection: + XtVaSetValues(child, XtNon, $toggle_ord == $selection, NULL); + break; + case XfwfMultipleSelection: + XtVaSetValues(child, XtNon, + ($selection (1L<<$toggle_ord)) != 0, NULL); + break; + default: ; + } + $toggle_ord++; + } +} +.fi + +.hi + +.hi +.SH "Utilities" + +The \fImake_textgc\fP routine creates the GC for the text. + +.nf +make_textgc($) +{ + XtGCMask mask; + XGCValues values; + + if ($textgc != NULL) XtReleaseGC($, $textgc); + values.background = $background_pixel; + values.foreground = $foreground; + values.font = $font->fid; + mask = GCFont | GCBackground | GCForeground; + $textgc = XtGetGC($, mask, values); +} +.fi + +The task of the \fIon_cb\fP callback function is to record the changed +state of the toggle button and maybe turn off other toggle buttons. +When the new value of \fIselection\fP is computed, the \fIactivate\fP +callbacks are called. + +.nf +on_cb(Widget toggle, XtPointer client_data, XtPointer call_data) +{ + Widget $ = XtParent(toggle); + Cardinal toggle_ord = (Cardinal) client_data; + Cardinal t, i, bits = sizeof($selection) * 8; + + switch ($selectionStyle) { + case XfwfMultipleSelection: + if (toggle_ord < bits) $selection |= 1L << toggle_ord; + break; + case XfwfSingleSelection: + case XfwfOneSelection: + if ($selection != -1L) + for (t = 0, i = 0; i < $num_children; i++) + if (XtIsSubclass($children[i], xfwfToggleWidgetClass)) { + if ($selection == t) { + XtVaSetValues($children[i], XtNon, False, NULL); + break; + } + t++; + } + $selection = toggle_ord; + break; + default: ; + } + XtCallCallbackList($, $activate, (XtPointer) $selection); +} +.fi + +The task of the \fIoff_cb\fP callback function is to update the +\fIselection\fP resource and check if turning off the toggle button is +allowed. If the \fIselectionStyle\fP is \fIXfwfOneSelection\fP, toggles cannot +be turned off, except by turning on another one. + +.nf +off_cb(Widget toggle, XtPointer client_data, XtPointer call_data) +{ + Widget $ = XtParent(toggle); + Cardinal toggle_ord = (Cardinal) client_data; + Cardinal t, i, bits = sizeof($selection) * 8; + + switch ($selectionStyle) { + case XfwfOneSelection: + XtVaSetValues(toggle, XtNon, True, NULL); /* Undo */ + break; + case XfwfSingleSelection: + $selection = -1L; /* Nothing selected */ + break; + case XfwfMultipleSelection: + if (toggle_ord < bits) $selection = ~(1L << toggle_ord); + break; + default: ; + } + XtCallCallbackList($, $activate, (XtPointer) $selection); +} +.fi + +The function \fIset_toggles\fP is used when the \fIselection\fP resource or +the \fIselectionStyle\fP resource changes. It inspects all child widgets +in turn and turns toggles on or off according to the values of these +two resources. + +.nf +set_toggles($) +{ + Cardinal i, t; + + for (t = 0, i = 0; i < $num_children; i++) + if (XtIsSubclass($children[i], xfwfToggleWidgetClass)) { + switch ($selectionStyle) { + case XfwfNoSelection: + break; + case XfwfSingleSelection: + case XfwfOneSelection: + XtVaSetValues($children[i], XtNon, t == $selection, NULL); + break; + case XfwfMultipleSelection: + XtVaSetValues($children[i], + XtNon, ($selection (1L<<t)) != 0, NULL); + break; + } + t++; + } +} +.fi + +\fIcvtStringToSelectionType\fP converts the strings `no', `none', +`single', `one', `multi' and `multiple'. Case doesn't matter. + +\fBdef\fP done(type, value) = +do { + if (to->addr != NULL) { + if (to->size < sizeof(type)) { + to->size = sizeof(type); + return False; + } + *(type*)(to->addr) = (value); + } else { + static type static_val; + static_val = (value); + to->addr = (XtPointer)static_val; + } + to->size = sizeof(type); + return True; + }while (0 ) + +.nf +Boolean cvtStringToSelectionType(Display * display, XrmValuePtr args, Cardinal * num_args, XrmValuePtr from, XrmValuePtr to, XtPointer * converter_data) +{ + String s = (String) from->addr; + + if (*num_args != 0) + XtAppErrorMsg(XtDisplayToApplicationContext(display), + "cvtStringToSelectionType", "wrongParameters", + "XtToolkitError", + "String to SelectionType conversion needs no arguments", + (String*) NULL, (Cardinal*) NULL); + + if (XmuCompareISOLatin1(s, "no") == 0) + done(SelectionType, XfwfNoSelection); + if (XmuCompareISOLatin1(s, "none") == 0) + done(SelectionType, XfwfNoSelection); + if (XmuCompareISOLatin1(s, "single") == 0) + done(SelectionType, XfwfSingleSelection); + if (XmuCompareISOLatin1(s, "one") == 0) + done(SelectionType, XfwfOneSelection); + if (XmuCompareISOLatin1(s, "multi") == 0) + done(SelectionType, XfwfMultipleSelection); + if (XmuCompareISOLatin1(s, "multiple") == 0) + done(SelectionType, XfwfMultipleSelection); + + XtDisplayStringConversionWarning(display, s, XtRSelectionType); + done(SelectionType, XfwfSingleSelection); +} +.fi + +A converter in the opposite direction. + +.nf +Boolean cvtSelectionTypeToString(Display * display, XrmValuePtr args, Cardinal * num_args, XrmValuePtr from, XrmValuePtr to, XtPointer * converter_data) +{ + char s[30]; + + if (*num_args != 0) + XtAppErrorMsg(XtDisplayToApplicationContext(display), + "cvtStringToSelectionStyle", "wrongParameters", + "XtToolkitError", + "String to SelectionStyle conversion needs no arguments", + (String*) NULL, (Cardinal*) NULL); + switch (*((SelectionType*) from->addr)) { + case XfwfNoSelection: done(String, "none"); + case XfwfSingleSelection: done(String, "single"); + case XfwfOneSelection: done(String, "one"); + case XfwfMultipleSelection: done(String, "multiple"); + } + XtDisplayStringConversionWarning(display, s, XtRSelectionType); + done(String, "none"); +} +.fi + +.hi |