diff options
Diffstat (limited to 'vendor/x11iraf/obm/ObmW/Scrollbar.man')
| -rw-r--r-- | vendor/x11iraf/obm/ObmW/Scrollbar.man | 812 |
1 files changed, 812 insertions, 0 deletions
diff --git a/vendor/x11iraf/obm/ObmW/Scrollbar.man b/vendor/x11iraf/obm/ObmW/Scrollbar.man new file mode 100644 index 00000000..46c2b29f --- /dev/null +++ b/vendor/x11iraf/obm/ObmW/Scrollbar.man @@ -0,0 +1,812 @@ +.\"remove .ig hn for full docs +.de hi +.ig eh +.. +.de eh +.. +.TH "" 3 "" "Version 3.0" "Free Widget Foundation" +.SH NAME +XfwfScrollbar +.SH DESCRIPTION +The scrollbar widget helps the user to view data that is too large +to be displayed all at once. They are often used through a +ScrolledWindow (see there), where they are put next to and/or below +the widget that contains the data. The scrollbar controls which part +is visible. By manipulating the scrollbar the user can move (`scroll') +the data within the other widget. + +A scrollbar consists of two arrows placed at each end of a rectangle, +either at the top and bottom or at the left and right. The former is +called a vertical scrollbar, the latter a horizontal one. A smaller +rectangle, called the thumb or slider, is placed within the larger +one. It can move up and down (vertical scrollbar) or left/right +(horizontal scrollbar). Clicking an arrow moves the data in that +direction. Pressing the mouse button on an arrow and holding it, moves +the data by small increments as long as the mouse button is down. +Dragging the slider moves the data proportionally with the slider, +either along with the movement of the mouse, or all at once when the +mouse button is released. Pressing the mouse button onthe rectangle +outside the slider moves the data in larger increments. + +The ratio of the slider size to the scroll region size typically +corresponds to the relationship between the size of the visible data +and the total size of the data. For example, if 10 percent of the +data is visible, the slider typically occupies 10 percent of the +scroll region. This provides the user with a visual clue to the size +of the invisible data. + +The scrollbar widget can be configured as either horizontal or +vertical. It is made up of two XfwfArrow widgets and an XfwfSlider2 +widget. Therefore, many of the scrollbar's resources are actually +resources for these, nameless, widgets. The scrollbar has the +same callback list as the slider. + +.SS "Public variables" + +.ps-2 +.TS +center box; +cBsss +lB|lB|lB|lB +l|l|l|l. +XfwfScrollbar +Name Class Type Default +XtNvertical XtCVertical Boolean True +XtNscrollCallback XtCScrollCallback Callback NULL +XtNscrollResponse XtCScrollResponse XTCallbackProc scroll_response +XtNinitialDelay XtCInitialDelay Cardinal 500 +XtNrepeatDelay XtCRepeatDelay Cardinal 50 +XtNincrement XtCIncrement Float "0.05" +XtNscrollbarForeground XtCScrollbarForeground Pixel copy_background +XtNshadow XtCShadow Dimension 2 +XtNminsize XtCMinsize Dimension 20 + +.TE +.ps + +.TP +.I "XtNvertical" +The orientation of the scrollbar is set with the \fIvertical\fP +resource. \fITrue\fP means vertical, \fIFalse\fP horizontal. This resource may +only be set during initialization. Any changes via \fIXtVaSetValues\fP +result in a warning and are then ignored. + + + +.hi + +.nf +Boolean vertical = True +.fi + +.eh + +.TP +.I "XtNscrollCallback" +The user can interact with the scrollbar in many ways, but there is +only a single callback list: \fIscrollCallback\fP. The callback uses the +\fIcall_data\fP parameter to pass a pointer to an \fIXfwfScrollInfo\fP +structure: \fIstruct {XfwfSReason reason; XfwfSFlags flags; float vpos, +vsize, hpos, hsize;}\fP The \fIflags\fP field is a bitwise combination of +\fIXFWF_VPOS\fP, \fIXFWF_HPOS\fP, \fIXFWF_VSIZE\fP and \fIXFWF_HSIZE\fP. The +structure contains a field \fIreason\fP, which can have the following +values (there exist other values, but they are not used by the +scrollbar): + +\item{-} \fIXfwfSUp\fP: if the user clicked (or holds) the up arrow. +\item{-} \fIXfwfSLeft\fP: ditto left arrow. +\item{-} \fIXfwfSDown\fP: ditto down arrow. +\item{-} \fIXfwfSRight\fP: ditto right arrow. +\item{-} \fIXfwfSPageUp\fP: ditto area above thumb. +\item{-} \fIXfwfSPageDown\fP: ditto area below thumb. +\item{-} \fIXfwfSPageLeft\fP: ditto area left of thumb. +\item{-} \fIXfwfSPageRight\fP: ditto area right of thumb. +\item{-} \fIXfwfSDrag\fP: if the user drags the thumb. +\item{-} \fIXfwfSMove\fP: if the user stops dragging the thumb. + +The other four fields contain the new position of the thumb, as +numbers between 0.0 and 1.0 inclusive. In the case of drag and drop +actions, the position and size reflect the thumb's {\em actual} +position at the end of the dragging. In the other cases, the position +is the {\em suggested} new position. In these latter cases, the +callback routine should compute the new position and use a call to the +function in the \fIScrollResponse\fP resource (or, more conveniently, to +\fIXfwfSetScrollbar\fP) to update the scrollbar. + + + +.hi + +.nf +<Callback> XtCallbackList scrollCallback = NULL +.fi + +.eh + +.TP +.I "XtNscrollResponse" +The standard way to update the scrollbar is with a call to the +function that is knwon as the \fIscrollResponse\fP function. To get a +pointer to that function, you should use \fIXtGetValues\fP or +\fIXtVaGetValues\fP on the \fIXtNscrollResponse\fP resource. But from an +application it might be easier to use the \fIXfwfSetScrollbar\fP +convenience function instead. + +The \fIscrollResponse\fP routine has the same format as a callback +procedure. The first argument is a widget, this argument is ignored. +The second argument is \fIXtPointer client_data\fP, it must point to the +scrollbar that is to be updated. The third argument is \fIXtPointer +call_data\fP, it must be a pointer to an \fIXfwfScrollInfo\fP structure (see +above). + + + +.hi + +.nf +XtCallbackProc scrollResponse = scroll_response +.fi + +.eh + +.TP +.I "XtNinitialDelay" +When the user presses and then holds the mouse button on an arrow or +on an area outside the thumb, the scrollbar waits some milliseconds +before it starts repeating the callbacks. + + + +.hi + +.nf +Cardinal initialDelay = 500 +.fi + +.eh + +.TP +.I "XtNrepeatDelay" +Between repeated calls to the callback routines, the scrollbar will +wait a few milliseconds. + + + +.hi + +.nf +Cardinal repeatDelay = 50 +.fi + +.eh + +.TP +.I "XtNincrement" +Some widgets may be simple enough that they can scroll a fixed +amount whenever the user clicks on one of the arrow buttons. If that +is the case, they can let the scrollbar compute the new position. It +will be passed in the \fIXfwfScrollInfo\fP structure as the suggested new +position. Any receiver is free to ignore the suggestion, however. The +default is to add or subtract 0.05. + + + +.hi + +.nf +float increment = <String>"0.05" +.fi + +.eh + +.TP +.I "XtNscrollbarForeground" +The color of the arrow and the thumb also determines the color of +the 3D shadow, at least if \fIshadowScheme\fP is set to \fIXfwfAuto\fP, as it +is by default. The default value is determined dynamically, it is +copied from the \fIbackground\fP resource. + + + +.hi + +.nf +Pixel scrollbarForeground = <CallProc>copy_background +.fi + +.eh + +.TP +.I "XtNshadow" +The width of the arrow's and thumb's shadow is by default 2 pixels. + + + +.hi + +.nf +Dimension shadow = 2 +.fi + +.eh + +.TP +.I "XtNminsize" +The minimum size of the thumb is by default 20 pixels. It can be set +with the \fIminsize\fP resource. + + + +.hi + +.nf +Dimension minsize = 20 +.fi + +.eh + +.TP +.I "XtNframeWidth" +The slider and the two arrows frame will be forced to 0 pixels. The +only frame is that of the whole scrollbar. The default frame width is +changed from 0 to 2. + + + +.hi + +.nf + frameWidth = 2 +.fi + +.eh + +.TP +.I "XtNframeType" +The default frame type is now \fIXfwfSunken\fP. + + + +.hi + +.nf + frameType = XfwfSunken +.fi + +.eh + +.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 \fIXfwfSetScrollbar\fP convenience function can be used to set the +position and size of a scrollbar. The two arguments must be between +0.0 and 1.0 (inclusive). + +.nf +XfwfSetScrollbar( $, double pos, double size) +.fi + +.hi +{ + if (! XtIsSubclass($, xfwfScrollbarWidgetClass)) + XtError("XfwfSetScrollbar called with incorrect widget type"); + if (pos < 0.0 || pos > 1.0 || size < 0.0 || size > 1.0) + XtError("XfwfSetScrollbar called with incorrect arguments"); + if ($vertical) { + XfwfResizeThumb($slider, 1.0, size); + XfwfMoveThumb($slider, 0.0, pos); + } else { + XfwfResizeThumb($slider, size, 1.0); + XfwfMoveThumb($slider, pos, 0.0); + } +} +.eh + +.hi +.SS "Actions" + +.TP +.I "Scroll + +The following action is not used by default, but it is defined here, +because someone might want to bind it to keys. For example, the +subclasses \fIXfwfVScrollbar\fP and \fIXfwfHScrollbar\fP do that. + +.hi + +.nf +void Scroll($, XEvent* event, String* params, Cardinal* num_params) +{ + XfwfScrollInfo info; + + XfwfGetThumb($slider, info); + info.reason = XfwfCvtStringToScrollReason(params[0]); + switch (info.reason) { + case XfwfSUp: + info.flags = XFWF_VPOS; + info.vpos = max(0.0, info.vpos - $increment); + break; + case XfwfSDown: + info.flags = XFWF_VPOS; + info.vpos = min(1.0, info.vpos + $increment); + break; + case XfwfSLeft: + info.flags = XFWF_HPOS; + info.hpos = max(0.0, info.hpos - $increment); + break; + case XfwfSRight: + info.flags = XFWF_HPOS; + info.hpos = min(1.0, info.hpos + $increment); + break; + case XfwfSPageUp: + info.flags = XFWF_VPOS; + info.vpos = max(0.0, info.vpos - info.vsize); + break; + case XfwfSPageDown: + info.flags = XFWF_VPOS; + info.vpos = min(1.0, info.vpos + info.vsize); + break; + case XfwfSPageLeft: + info.flags = XFWF_HPOS; + info.hpos = max(0.0, info.hpos - info.hsize); + break; + case XfwfSPageRight: + info.flags = XFWF_HPOS; + info.hpos = min(1.0, info.hpos + info.hsize); + break; + case XfwfSTop: + info.flags = XFWF_VPOS; + info.vpos = 0.0; + break; + case XfwfSBottom: + info.flags = XFWF_VPOS; + info.vpos = 1.0; + break; + case XfwfSLeftSide: + info.flags = XFWF_HPOS; + info.hpos = 0.0; + break; + case XfwfSRightSide: + info.flags = XFWF_HPOS; + info.hpos = 1.0; + break; + default: break; /* Not understood */ + } + XtCallCallbackList($, $scrollCallback, info); +} +.fi + +.eh + +.hi + +.hi +.SH "Importss" + +.nf + +.B incl + <Xfwf/Arrow.h> +.fi + +.nf + +.B incl + <Xfwf/Slider2.h> +.fi + +.nf + +.B incl + <stdio.h> +.fi + +.hi + +.hi +.SS "Private variables" + +The three children of the scrollbar are stored in private variables. + + + +.nf +Widget arrow1 +.fi + +.nf +Widget arrow2 +.fi + +.nf +Widget slider +.fi + +During the \fIinitialize\fP method, the variable \fIinitializing\fP will be +\fITrue\fP, so that \fIinsert_child\fP can check whether a child should be +inserted or not. + + + +.nf +Boolean initializing +.fi + +The \fIscrollResponse\fP function of the Slider2 that implements the +thumb is stored in a private variable. + + + +.nf +XtCallbackProc slider_scroll +.fi + +.hi + +.hi +.SS "Methods" + +The \fIinitialize\fP method creates the three widgets that make up the +scrollbar: two arrows and a slider. It sets the resources of these +widgets and redirects the callbacks. + +.nf +initialize(Widget request, $, ArgList args, Cardinal * num_args) +{ + Position x, y, xa2, xslider, ya2, yslider; + Dimension w, h, wa, ha, wslider, hslider; + + $initializing = True; + $compute_inside($, x, y, w, h); + if ($vertical) { + ha = wa = wslider = w; + xa2 = xslider = x; + hslider = (h - 2*ha > 0) ? h - 2*ha : 10; + yslider = y + ha; + ya2 = yslider + hslider; + } else { + wa = ha = hslider = h; + ya2 = yslider = y; + wslider = (w - 2*wa > 0) ? w - 2*wa : 10; + xslider = x + wa; + xa2 = xslider + wslider; + } + $arrow1 = XtVaCreateManagedWidget + ("_arrow1", xfwfArrowWidgetClass, $, + XtNx, x, + XtNy, y, + XtNwidth, wa, + XtNheight, ha, + XtNframeWidth, 0, + XtNforeground, $scrollbarForeground, + XtNinitialDelay, $initialDelay, + XtNrepeatDelay, $repeatDelay, + XtNtraversalOn, False, + XtNhighlightThickness, 0, + XtNdirection, $vertical?XfwfTop:XfwfLeft, + XtNouterOffset, 0, + XtNborderWidth, 0, + NULL); + XtAddCallback($arrow1, XtNcallback, up, $); + $arrow2 = XtVaCreateManagedWidget + ("_arrow2", xfwfArrowWidgetClass, $, + XtNx, xa2, + XtNy, ya2, + XtNwidth, wa, + XtNheight, ha, + XtNframeWidth, 0, + XtNforeground, $scrollbarForeground, + XtNinitialDelay, $initialDelay, + XtNrepeatDelay, $repeatDelay, + XtNtraversalOn, False, + XtNhighlightThickness, 0, + XtNdirection, $vertical?XfwfBottom:XfwfRight, + XtNouterOffset, 0, + XtNborderWidth, 0, + NULL); + XtAddCallback($arrow2, XtNcallback, down, $); + $slider = XtVaCreateManagedWidget + ("_slider", xfwfSlider2WidgetClass, $, + XtNx, xslider, + XtNy, yslider, + XtNwidth, wslider, + XtNheight, hslider, + XtNthumbColor, $scrollbarForeground, + XtNframeWidth, 0, + XtNinitialDelay, $initialDelay, + XtNrepeatDelay, $repeatDelay, + XtNtraversalOn, False, + XtNhighlightThickness, 0, + XtNouterOffset, 0, + XtNborderWidth, 0, + NULL); + XtAddCallback($slider, XtNscrollCallback, thumbscroll, $); + XtVaGetValues($slider, XtNscrollResponse, $slider_scroll, NULL); + $initializing = False; +} +.fi + +When the scrollbar is resized, the children must be resized also. + +.nf +resize($) +{ + Position x, y, xa2, xslider, ya2, yslider; + Dimension w, h, wa, ha, wslider, hslider; + + $compute_inside($, x, y, w, h); + if ($vertical) { + wa = wslider = w; + xa2 = xslider = x; + ha = 2 * (wa + 1)/3; + hslider = (h - 2*ha > 0) ? h - 2*ha : 10; + yslider = y + ha; + ya2 = yslider + hslider; + } else { + ha = hslider = h; + ya2 = yslider = y; + wa = 2 * (ha + 1)/3; + wslider = (w - 2*wa > 0) ? w - 2*wa : 10; + xslider = x + wa; + xa2 = xslider + wslider; + } + XtConfigureWidget($arrow1, x, y, wa, ha, 0); + XtConfigureWidget($arrow2, xa2, ya2, wa, ha, 0); + XtConfigureWidget($slider, xslider, yslider, wslider, hslider, 0); +} +.fi + +\fIinsert_child\fP is redefined here only to be able to give a warning +when a child is inserted beyond the three that are created in the +\fIinitialize\fP method. + +.nf +insert_child(Widget child) +{ + if ($initializing) + #insert_child(child); + else { + char s[500]; + (void)sprintf(s, "Cannot add children to a scrollbar (\\"%s\\"->\\"%s\\")", + XtName(child), XtName($)); + XtWarning(s); + } +} +.fi + +The \fIset_values\fP method passes resource values on to the three +children. + +.nf +Boolean set_values(Widget old, Widget request, $, ArgList args, Cardinal * num_args) +{ + if ($old$vertical != $vertical) { + XtWarning("Cannot change the \\"vertical\\" resource of a scrollbar\\n"); + $vertical = $old$vertical; + } + if ($old$scrollbarForeground != $scrollbarForeground) { + XtVaSetValues($slider, XtNthumbColor, $scrollbarForeground, NULL); + XtVaSetValues($arrow1, XtNforeground, $scrollbarForeground, NULL); + XtVaSetValues($arrow2, XtNforeground, $scrollbarForeground, NULL); + } + if ($old$shadow != $shadow) { + XtVaSetValues($slider, XtNthumbFrameWidth, $shadow, NULL); + XtVaSetValues($arrow1, XtNarrowShadow, $shadow, NULL); + XtVaSetValues($arrow2, XtNarrowShadow, $shadow, NULL); + } + if ($old$minsize != $minsize) { + XtVaSetValues($slider, XtNminsize, $minsize, NULL); + } + return False; +} +.fi + +The \fIscroll_response\fP method is accessed via the \fIscrollResponse\fP +resource. It is passed the scrollbar itself as the \fIclient_data\fP +argument and a pointer to an \fIXfwfScrollInfo\fP record as \fIcall_data\fP. + +The scrollbar passes on the call to the Slider2 widget that is +managing the thumb. + +.nf +scroll_response(Widget wdg, XtPointer client_data, XtPointer call_data) +{ + Widget $ = (Widget) client_data; + + $slider_scroll(wdg, $slider, call_data); +} +.fi + +.hi + +.hi +.SH "Utilities" + +.nf +char rcsid[] = "$Header: Scrollbar.w,v 1.1 92/11/02 14:08:00 bert Exp $" +.fi + +The \fIup\fP routine is a callback for the first arrow. It invokes the +scrollbar's callback. + +.nf +up(Widget arrow, XtPointer client_data, XtPointer call_data) +{ + Widget $ = (Widget) client_data; + XfwfScrollInfo info; + + XfwfGetThumb($slider, info); + if ($vertical) { + info.reason = XfwfSUp; + info.flags = XFWF_VPOS; + info.vpos = max(0.0, info.vpos - $increment); + } else { + info.reason = XfwfSLeft; + info.flags = XFWF_HPOS; + info.hpos = max(0.0, info.hpos - $increment); + } + XtCallCallbackList($, $scrollCallback, info); +} +.fi + +The \fIdown\fP routine is the callback for the second arrow. It invokes the +scrollbar's callback. + +.nf +down(Widget arrow, XtPointer client_data, XtPointer call_data) +{ + Widget $ = (Widget) client_data; + XfwfScrollInfo info; + + XfwfGetThumb($slider, info); + if ($vertical) { + info.reason = XfwfSDown; + info.flags = XFWF_VPOS; + info.vpos = min(1.0, info.vpos + $increment); + } else { + info.reason = XfwfSRight; + info.flags = XFWF_HPOS; + info.hpos = min(1.0, info.hpos + $increment); + } + XtCallCallbackList($, $scrollCallback, info); +} +.fi + +The \fIthumbscroll\fP routine is the callback for the scroll callback of +the slider. It invokes the scrollbar's \fIscrollCallback\fP, after making +sure that only appropriate position information is passed. (The +Slider2 might pass horizontal position where only vertical position is +relevant, and vice versa.) + +.nf +thumbscroll(Widget w, XtPointer client_data, XtPointer call_data) +{ + Widget $ = (Widget) client_data; + XfwfScrollInfo *info = (XfwfScrollInfo*) call_data; + + if ($vertical) + info->flags = XFWF_VPOS; + else + info->flags = XFWF_HPOS; + XtCallCallbackList($, $scrollCallback, info); +} +.fi + +The \fIcopy_background\fP routine is resource default procedure. It is +called to initialize the default value of the \fIforeground\fP resource. + +.nf +copy_background($, int offset, XrmValue * value) +{ + value->addr = (XtPointer) $background_pixel; +} +.fi + +.hi |