NAME
Panner widget − a "scrollbar" for two dimensions.
SYNOPSIS
Public Headers:<X11/StringDefs.h> <X11/Xaw/Panner.h>
Private Header:<X11/Xaw/PannerP.h>
Class Name:Panner
Class Pointer:pannerWidgetClass
Instantiation:widget = XtCreateWidget(name, pannerWidgetClass, ...)
CLASS HIERARCHY
Core → Simple → Panner
AVAILABILITY
Release 5 and later.
DESCRIPTION
The Panner widget is conceptually a two-dimensional scrollbar. It displays a rectangle within a rectangle—the inner rectangle (the "slider") represents the visible portion of a larger area (the "canvas") represented by the outer rectangle. The size of the inner rectangle represents the size of the visible area relative to the whole, and its position indicates the relative position of the visible area within the whole. The user may drag the inner rectangle with the mouse (or use keyboard arrow keys) to pan through the large diagram or document (or whatever) that is being displayed. The Panner widget is typically used with a Porthole widget to scroll a third widget in two dimensions.
When a Panner is created, it is drawn with the slider in a contrasting color. The slider may be moved around the canvas by pressing, dragging, and then releasing Button1. While scrolling is in progress, the application receives notification through callback procedures which it may use to update any associated widgets. Notification may be done either as the slider is dragged, or only when the slider is released.
RESOURCES
When creating a Panner widget instance, the following resources are retrieved from the argument list or from the resource database:
| Name | Type | Default | Description | |||
| XtNaccelerators | AcceleratorTable | NULL | Accelerators for this widget. | |||
| XtNallowOff | Boolean | False | Whether the slider can go beyond the edges. | |||
| XtNancestor− Sensitive |
Boolean | True | Sensitivity state of the ancestors of this widget. | |||
| XtNbackground | Pixel | XtDefault− Background |
Window background color. | |||
| XtNbackgroundPixmap | Pixmap | XtUnspecified− Pixmap |
Window background pixmap. | |||
| XtNbackgroundStipple | String | NULL | Background pattern. | |||
| XtNbitmap | Pixmap | None | Pixmap to display in place of the label. | |||
| XtNborderColor | Pixel | XtDefault− Foreground |
Window border color. | |||
| XtNborderPixmap | Pixmap | XtUnspecified− Pixmap |
Window border pixmap. | |||
| XtNborderWidth | Dimension | 1 | Width of button border. | |||
| XtNcanvasHeight | Dimension | 0 | Height of the canvas to pan. | |||
| XtNcanvasWidth | Dimension | 0 | Width of the canvas to pan. | |||
| XtNcolormap | Colormap | Parent’s colormap. | Colormap that this widget will use. | |||
| XtNcursor | Cursor | None | Pointer cursor. | |||
| XtNcursorName | String | NULL | A cursor glyph name. | |||
| XtNdefaultScale | Dimension | 8 | Panner size as % of canvas. | |||
| XtNdepth | int | Parent’s depth. | Depth of this widget’s window. | |||
| XtNdestroyCallback | XtCallbackList | NULL | Callbacks for XtDestroyWidget. | |||
| XtNforeground | Pixel | XtDefault− | ||||
| Foreground | Widget foreground color. | |||||
| XtNheight | Dimension | 0 | Widget height. | |||
| XtNinsensitiveBorder | Pixmap | Gray pixmap. | Border when not sensitive. | |||
| XtNinternalSpace | Dimension | 4 | Margin around slider. | |||
| XtNlineWidth | Dimension | 0 | Width of rubberband lines. | |||
| XtNmappedWhen− Managed |
Boolean | TRUE | Whether XtMapWidget is automatic. | |||
| XtNpointerColor | Pixel | XtDefault− | ||||
| Foreground | Cursor foreground color. | |||||
| XtNpointerColor− Background |
Pixel | XtDefault− | ||||
| Background | Cursor background color. | |||||
| XtNreportCallback | XtCallbackList | NULL | Callback for panner motion. | |||
| XtNresize | Boolean | True | Whether to resize Panner with canvas. | |||
| XtNrubberBand | Boolean | False | Whether to do continuous scrolling. | |||
| XtNscreen | Screen | Parent’s screen. | Screen on which this widget is displayed: this is not a settable resource. | |||
| XtNsensitive | Boolean | TRUE | Whether widget receives input. | |||
| XtNshadowColor | Pixel | XtDefault− | ||||
| Foreground | Color of thumb shadow. | |||||
| XtNshadowThickness | Dimension | 2 | Width of thumb shadow. | |||
| XtNsliderX | Position | 0 | X location of thumb. | |||
| XtNsliderY | Position | 0 | Y location of thumb. | |||
| XtNsliderHeight | Dimension | 0 | Thumb height. | |||
| XtNsliderWidth | Dimension | 0 | Thumb width. | |||
| XtNtranslations | Translation− Table |
See below. | Event-to-action translations. | |||
| XtNwidth | Dimension | 0 | Widget width. | |||
| XtNx | Position | 0 | x-coordinate in pixels. | |||
| XtNy | Position | 0 | y-coordinate in pixels. | |||
The new resources (not inherited from superclasses) available to the Repeater widget are:
XtNallowOff
Whether to allow the edges of the slider to go off the edges of the canvas.
XtNbackgroundStipple
The name of a bitmap pattern to be used as the background for the area representing the canvas.
XtNcanvasHeight
The height of the canvas.
XtNcanvasWidth
The width of the canvas.
XtNdefaultScale
The percentage size that the Panner widget should have relative to the size of the canvas.
XtNforeground
The slider foreground color.
XtNinternalSpace
The width of internal border in pixels between a slider representing the full size of the canvas and the edge of the Panner widget.
XtNlineWidth
The width of the lines in the rubberbanding rectangle when rubberbanding is in effect instead of continuous scrolling. The default is 0.
XtNreportCallback
All functions on this callback list are called when the slider is moved.
XtNresize
Whether or not to resize the panner whenever the canvas size is changed so that the XtNdefaultScale is maintained.
XtNrubberBand
Whether or not scrolling should be discrete (only moving a rubberbanded rectangle until the scrolling is done) or continuous (moving the slider itself). This controls whether or not the move action procedure also invokes the notify action procedure.
XtNshadowColor
The color of the shadow underneath the slider.
XtNshadowThickness
The width of the shadow underneath the slider.
XtNsliderX
The X location of the slider in the coordinates of the canvas.
XtNsliderY
The Y location of the slider in the coordinates of the canvas.
XtNsliderHeight
The height of the slider.
XtNsliderWidth
The width of the slider.
TRANSLATIONS AND ACTIONS
The actions supported by the Panner widget are:
start()
This action begins movement of the slider.
stop()
This action ends movement of the slider.
abort()
This action ends movement of the slider and restores it to the position it held when the start action was invoked.
move()
This action moves the outline of the slider (if the XtNrubberBand resource is True) or the slider itself (by invoking the notify action procedure).
page(xamount,yamount)
This action moves the slider by the specified amounts. The format for the amounts is a signed or unsigned floating-point number (e.g., +1.0 or −.5) followed by either "p" indicating pages (slider sizes), or "c" indicating canvas sizes. A signed number indicates a relative coordinate and an unsigned number indicates an absolute coordinate. Thus, page(+0,+.5p) represents vertical movement down one-half the height of the slider and page(0,0) represents moving to the upper left corner of the canvas. This action causes the callbacks on the XtNreportCallback list to be invoked.
notify()
This action informs the application of the slider’s current position by invoking the XtNreportCallback functions registered by the application.
set(what,value)
This action changes the behavior of the Panner. The what argument must currently be the string "rubberband" and controls the value of the XtNrubberBand resource. The value argument may have one of the values "on," "off," or "toggle."
The default bindings for Panner are: <Btn1Down>:start() <Btn1Motion>: move() <Btn1Up>: notify() stop() <Btn2Down>: abort() <Key>KP_Enter: set(rubberband,toggle) <Key>space: page(+1p,+1p) <Key>Delete: page(−1p,−1p) <Key>BackSpace: page(−1p,−1p) <Key>Left: page(−.5p,+0) <Key>Right: page(+.5p,+0) <Key>Up: page(+0,−.5p) <Key>Down: page(+0,+.5p) <Key>Home: page(0,0)
CALLBACK STRUCTURES
The functions registered on the XtNreportCallback list are invoked by the notify action with a call_data argument which is a pointer to a structure of type XawPannerReport: /∗
∗ XawPannerReport - this structure is used by the reportCallback of the
∗ Panner, Porthole, Viewport, and Scrollbar widgets to report its
∗ position. All fields must be filled in, although the changed field
∗ may be used as a hint as to which fields have been altered since the
∗ last report.
∗/ typedef struct {
unsigned int changed;/∗ mask, see below ∗/
Position slider_x, slider_y;/∗ location of slider within outer ∗/
Dimension slider_width, slider_height; /∗ size of slider ∗/
Dimension canvas_width, canvas_height; /∗ size of canvas ∗/ } XawPannerReport;
#define XawPRSliderX(1 << 0) #define XawPRSliderY(1 << 1) #define XawPRSliderWidth (1 << 2) #define XawPRSliderHeight (1 << 3) #define XawPRCanvasWidth (1 << 4) #define XawPRCanvasHeight (1 << 5) #define XawPRAll (63) /∗ union of above ∗/
PUBLIC FUNCTIONS
No public functions defined.
SEE ALSO
Porthole, Simple.