The Panner Widget
Author: Roland Krause 2002, roland_krause@freenet.de
Description: Documentation to XawPlus

### _________________________________________________________XawPlus

### The Panner Widget

Application Header file Class Header file Class Class Name Superclass | <X11/XawPlus/Panner.h> <X11/XawPlus/PannerP.h> pannerWidgetClass Panner Simple

The Panner widget represents a rectangular region (called the ``canvas'') of which only a smaller, enclosed rectangular region (called the ``slider'') by is visible at any given time. It 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 continuously whenever the slider moves or discretely whenever the slider has been given a new location.

### Differences between Xaw and XawPlus

Since the 3D extensions of Simple are inserted, the Panner widget has the additional resources highlightColor, shadowColor and buttonBorderWidth. The color resources and the border width resource are used to display a three dimensional styled slider. The default background color is now grey75.

The backgroundStipple, lineWidth, rubberBand, shadowThickness and foreground resources are not longer used. The old shadowColor resource is replaced by Simple with a different meaning.

The set() action is not supported by the XawPlus version of this widget.

### Resources

When creating a Panner widget instance, the following resources are retrieved from the argument list of XtSetValues() or XtVaSetValues() or from the resource database:

Name | Class | Type | Default Value
OBJECT: |  |  |
destroyCallback | Callback | Pointer | NULL
RECTANGLE: |  |  |
borderWidth height sensitive width x y | BorderWidth Height Sensitive Width Position Position | Dimension Dimension Boolean Dimension Position Position | 0 12 True 12 0 0
CORE: |  |  |
border background mappedWhenManaged | BorderColor Background MappedWhenManaged | Pixel Pixel Boolean | XtDefaultForeground grey75 True
SIMPLE: |  |  |
cursor cursorName pointerColor pointerColorBackground insensitiveBorder international highlightColor shadowColor buttonBorderWidth | Cursor Cursor Foreground Background Insensitive International Background Background Width | Cursor String Pixel Pixel Pixmap Boolean Pixel Pixel Dimension | None NULL XtDefaultForeground XtDefaultBackground NULL False grey90 grey40 2
PANNER: |  |  |
allowOff canvasWidth canvasHeight defaultScale internalSpace reportCallback resize sliderX sliderY sliderWidth sliderHeight | AllowOff CanvasWidth CanvasHeight DefaultScale InternalSpace ReportCallback Resize SliderX SliderY SliderWidth SliderHeight | Boolean Dimension Dimension Dimension Dimension XtCallbackList Boolean Position Position Dimension Dimension | FALSE 0 0 8 percent 4 NULL TRUE 0 0 0 0

allowOff | Whether to allow the edges of the slider to go off the edges of the canvas.
canvasHeight canvasWidth | The size of the canvas.
defaultScale | The percentage size that the Panner widget should have relative to the size of the canvas.
internalSpace | The width of internal border in pixels between a slider representing the full size of the canvas and the edge of the Panner widget.
reportCallback | All functions on this callback list are called when the notify action is invoked. See the Panner Actions section for details.
resize | Whether or not to resize the panner whenever the canvas size is changed so that the defaultScale is maintained.
sliderX sliderY | The location of the slider in the coordinates of the canvas.
sliderHeight sliderWidth | The size of the slider.

### Panner 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 slider.
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 -0.5) followed by either p indicating pages (slider sizes), or c indicating canvas sizes. Thus, page(+0, +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.
notify() | This action informs the application of the slider's current position by invoking the reportCallback functions registered by the application.

The default bindings for Panner are:

<Btn1Down>: <Btn1Motion>: <Btn1Up>: <Btn2Down>: <Key>space: <Key>Delete: <Key>BackSpace: <Key>Left: <Key>Right: <Key>Up: <Key>Down: <Key>Home: | start() move() notify(), stop() abort() page(1p, 1p) page(-1p, -1p) page(-1p, -1p) page(-0.5p, 0) page(0.5p, 0) page(0, -0.5p) page(0, 0.5p) page(0, 0)

### Panner Callbacks

The functions registered on the reportCallback list are invoked by the notify action as follows:

> void ReportProc(panner, client_data, report)
> Widget panner;
> XtPointer client_data;
> XtPointer report; /* (XawPannerReport *) */

> panner | Specifies the Panner widget.
> client_data | Specifies the client data.
> report | Specifies a pointer to an XawPannerReport structure containing the location and size of the slider and the size of the canvas.

### XawPlus_________________________________________________________