Motif Widget Writer's Guide Migration Version

Motif 2.1 Widget Writer's Guide

ExmPanner

The Panner widget class

Format

#include <Exm/Panner.h>

DESCRIPTION

ExmPanner is a demonstration widget. OSF provides this widget solely to teach programmers how to write their own Motif widgets. OSF does not support this widget in any way.

ExmPanner is a Motif version of the Athena Panner widget. The source code for the ExmPanner widget illustrates how to do the following:

Write a two-dimensional navigator widget

Install the XmQTnavigator trait

In order to properly exercise the ExmPanner widget, a test application should associate ExmPanner with a scrollable widget. A scrollable widget, such as XmScrolledWindow, is one that holds the XmQTscrollFrame trait. In order to make this association, the test application must call the addNavigator trait method of the XmQTscrollFrame trait.

Once attached to a scrollable widget, the ExmPanner widget displays a rectangle floating inside its window. This rectangle is called a slider. As the user moves this slider, different parts of the scrollable widget become visible. Thus, ExmPanner is similar to an XmScrollBar widget. The primary difference is that XmScrollBar only permits navigation in one dimension, but ExmPanner permits simultaneous navigation in two dimensions.

As the user moves the ExmPanner widget, the associated scrollable widget will automatically scroll.

If ExmPanner is associated with a scrollable widget, then the scrollable widget will control the values of the ExmPannerCanvasWidth, ExmPannerCanvasHeight, ExmPannerSliderWidth, and ExmPannerSliderHeight resources. That is, a user or application cannot control the values of these resources when the ExmPanner is associated with a scrollable widget.

ExmPanner ignores the value of the ExmNsimpleShape resource of ExmSimple.

Classes

ExmPanner inherits behavior and resources from Core, XmPrimitive, and ExmSimple.

The class pointer is exmPannerWidgetClass.

The class name is ExmPanner.

New Resources

The following table defines a set of widget resources used by the programmer to specify data. The programmer can also set the resource values for the inherited classes to set attributes for this widget. To reference a resource by name or by class in a .Xdefaults file, remove the XmN, ExmN, XmC or ExmC prefix and use the remaining letters. To specify one of the defined values for a resource in a .Xdefaults file, remove the Xm or Exm prefix and use the remaining letters (in either lowercase or uppercase, but include any underscores between words). The codes in the "Access" column indicate if the given resource can be set at creation time (C), set by using XtSetValues (S), retrieved by using XtGetValues (G), or is not applicable (N/A).

ExmPanner Resource Set
Name	Class	Type	Default	Access
ExmNcanvasHeight	ExmCCanvasHeight	Dimension	0	CSG
ExmNcanvasWidth	ExmCCanvasWidth	Dimension	0	CSG
ExmNreportCallback	ExmCReportCallback	XtCallbackList	NULL	C
ExmNrubberBand	ExmCRubberBand	Boolean	false	CSG
ExmNsliderX	ExmCSliderX	Position	0	CSG
ExmNsliderY	ExmCSliderY	Position	0	CSG
ExmNsliderHeight	ExmCSliderHeight	Dimension	0	CSG
ExmNsliderWidth	ExmCSliderWidth	Dimension	0	CSG

ExmNcanvasHeight

Specifies the vertical size of the canvas.

ExmNcanvasWidth

Specifies the horizontal size of the canvas.

ExmNreportCallback

Specifies a list of callbacks that is called as a result of a Btn1Up or Btn2Up action.

ExmNrubberBand

If false, the widget holding the XmQTscrollFrame trait will pan on a Btn1Motion or Btn2Motion event. If true, the widget holding the XmQTscrollFrame trait will only pan on a Btn1Up or Btn2Up event.

ExmNsliderX

Specifies the horizontal position of the leftmost part of the slider. The horizontal position will be based on a ratio of the value of ExmNsliderX to the value of ExmNcanvasWidth.

ExmNsliderY

Specifies the starting vertical position of the leftmost part of the slider. The starting vertical position will be based on a ratio of the value of ExmNsliderX to the value of ExmNcanvasHeight.

ExmNsliderHeight

Specifies the logical height of the slider. The height will be based on a ratio of the value of ExmNsliderHeight to the value of ExmNcanvasHeight.

ExmNsliderWidth

Specifies the logical width of the slider. The width will be based on a ratio of the value of ExmNsliderWidth to the value of ExmNcanvasWidth.

ExmSimple Resource Set
Name	Class	Type	Default	Access
ExmNsimpleShape	ExmCSimpleShape	unsigned char	ExmSHAPE_OVAL	CSG
XmNmarginHeight	XmCMarginHeight	Dimension	4	CSG
XmNmarginWidth	XmCMarginWidth	Dimension	4	CSG

XmPrimitive Resource Set
Name	Class	Type	Default	Access
XmNbottomShadowColor	XmCBottomShadowColor	Pixel	dynamic	CSG
XmNbottomShadowPixmap	XmCBottomShadowPixmap	Pixmap	XmUNSPECIFIED_PIXMAP	CSG
XmNconvertCallback	XmCCallback	XtCallbackList	NULL	C
XmNforeground	XmCForeground	Pixel	dynamic	CSG
XmNhelpCallback	XmCCallback	XtCallbackList	NULL	C
XmNhighlightColor	XmCHighlightColor	Pixel	dynamic	CSG
XmNhighlightOnEnter	XmCHighlightOnEnter	Boolean	false	CSG
XmNhighlightPixmap	XmCHighlightPixmap	Pixmap	dynamic	CSG
XmNhighlightThickness	XmCHighlightThickness	Dimension	2	CSG
XmNlayoutDirection	XmCLayoutDirection	XmDirection	dynamic	CG
XmNnavigationType	XmCNavigationType	XmNavigationType	XmSTICKY_TAB_GROUP	CSG
XmNpopupHandlerCallback	XmCCallback	XtCallbackList	NULL	C
XmNshadowThickness	XmCShadowThickness	Dimension	2	CSG
XmNtopShadowColor	XmCTopShadowColor	Pixel	dynamic	CSG
XmNtopShadowPixmap	XmCTopShadowPixmap	Pixmap	dynamic	CSG
XmNtraversalOn	XmCTraversalOn	Boolean	true	CSG
XmNunitType	XmCUnitType	unsigned char	dynamic	CSG
XmNuserData	XmCUserData	XtPointer	NULL	CSG

Core Resource Set
Name	Class	Type	Default	Access
XmNaccelerators	XmCAccelerators	XtAccelerators	dynamic	CSG
XmNancestorSensitive	XmCSensitive	Boolean	dynamic	G
XmNbackground	XmCBackground	Pixel	dynamic	CSG
XmNbackgroundPixmap	XmCPixmap	Pixmap	XmUNSPECIFIED_PIXMAP	CSG
XmNborderColor	XmCBorderColor	Pixel	XtDefaultForeground	CSG
XmNborderPixmap	XmCPixmap	Pixmap	XmUNSPECIFIED_PIXMAP	CSG
XmNborderWidth	XmCBorderWidth	Dimension	0	CSG
XmNcolormap	XmCColormap	Colormap	dynamic	CG
XmNdepth	XmCDepth	int	dynamic	CG
XmNdestroyCallback	XmCCallback	XtCallbackList	NULL	C
XmNheight	XmCHeight	Dimension	dynamic	CSG
XmNinitialResourcesPersistent	XmCInitialResourcesPersistent	Boolean	true	C
XmNmappedWhenManaged	XmCMappedWhenManaged	Boolean	true	CSG
XmNscreen	XmCScreen	Screen *	dynamic	CG
XmNsensitive	XmCSensitive	Boolean	true	CSG
XmNtranslations	XmCTranslations	XtTranslations	dynamic	CSG
XmNwidth	XmCWidth	Dimension	dynamic	CSG
XmNx	XmCPosition	Position	0	CSG
XmNy	XmCPosition	Position	0	CSG

Translations

ExmPanner provides the following translations:

Unmap:

PrimitiveUnmap()

Enter:

PrimitiveEnter()

Leave:

PrimitiveLeave()

FocusIn:

PrimitiveFocusIn()

FocusOut:

PrimitiveFocusOut()

:<Key>osfActivate:

PrimitiveParentActivate()

:<Key>osfHelp:

PrimitiveHelp()

:<Key>osfCancel:

ExmPannerAbort()

~s ~c ~m ~a <Btn1Down>:

ExmPannerStart(1)

~s ~c ~m ~a <Btn1Motion>:

ExmPannerMove()

~s ~c ~m ~a <Btn1Up>:

ExmPannerNotify() ExmPannerStop()

~s ~c ~m ~a <Btn2Down>:

ExmPannerStart(2)

~s ~c ~m ~a <Btn2Motion>:

ExmPannerMove()

~s ~c ~m ~a <Btn2Up>:

ExmPannerNotify() ExmPannerStop()

:<Key>space:

ExmPannerSet(rubberband,toggle)

:<Key>osfPageUp:

ExmPannerPage(+0, -1p)

:c <Key>osfPageUp:

ExmPannerPage(+0, -1c)

:<Key>osfPageDown:

ExmPannerPage(+0, +1p)

:c <Key>osfPageDown:

ExmPannerPage(+0, +1c)

:<Key>osfPageLeft:

ExmPannerPage(-1p, +0)

:c <Key>osfPageLeft:

ExmPannerPage(-1c, +0)

:<Key>osfPageRight:

ExmPannerPage(+1p, +0)

:c <Key>osfPageRight:

ExmPannerPage(+1c, +0)

:<Key>osfLeft:

ExmPannerPage(-1, +0)

:c <Key>osfLeft:

ExmPannerPage(-1p, +0)

:<Key>osfRight:

ExmPannerPage(+1, +0)

:c <Key>osfRight:

ExmPannerPage(+1p, +0)

:<Key>osfUp:

ExmPannerPage(+0, -1)

:c <Key>osfUp:

ExmPannerPage(+0, -1p)

:<Key>osfDown:

ExmPannerPage(+0, +1)

:c <Key>osfDown:

ExmPannerPage(+0, +1p)

:<Key>osfEndLine:

ExmPannerPage(+1c, +1c)

:<Key>osfBeginLine:

ExmPannerPage(0,0)

~s ~m ~a <Key>Return:

PrimitiveParentActivate()

s ~m ~a <Key>Tab:

PrimitivePrevTabGroup()

~m ~a <Key>Tab:

PrimitiveNextTabGroup()

Action Routines

All the actions that begin with the Primitive prefix are defined by the XmPrimitive widget. (See the XmPrimitive(3) reference page of the Motif Programmer's Reference for details.) The actions defined by ExmPanner are as follows:

ExmPannerAbort() :

Discontinues whatever pan operation is currently in progress. Returns the slider to the position it held when ExmPannerStart was invoked.

ExmPannerMove() :

If ExmNrubberBand is false, this action moves the outline of the slider. If ExmNrubberBand is true, this action moves the slider itself.

ExmPannerNotify() :

Calls the callbacks for XmNreportCallback.

ExmPannerPage( x,y):

Moves the slider in two dimensions. The first argument represents movement in the x dimension and the second argument represents the movement in the y dimension. Each argument must consist of an integer, optionally followed by the suffix p or c. A positive value classnameizes a move down or right. A negative value classnameizes a move up or left. The p suffix classnameizes "page." A page is defined as the slider size in that dimension. So, for example, if the slider height is 10 pixels, then a y argument of --2p moves the slider up 2 pages, which is 20 pixels. The c suffix classnameizes "canvas". The coordinates of the upper left of the canvas are (0c,0c), while the lower right of the canvas is at (1c,1c). If the argument does not contain a suffix, then the argument is interpreted as a relative pixel move. For example, a y argument of --40 moves the slider 40 pixels up from its current position.

ExmPannerSet( resource,value):

Sets the value of the XmNrubberBand resource to value. That is, the first argument must be XmNrubberBand and the second argument must be On, Off, or Toggle.

ExmPannerStart() :

Signals the start of a pan operation. This routine merely initializes several fields of the callback structure; this routine does not move the slider or perform any panning operations.

ExmPannerStop() :

Signals the end of the current pan operation.

Virtual Bindings

The bindings for virtual keys are vendor specific. For information about bindings for virtual buttons and keys, see VirtualBindings(3).

RELATED

Core(3), ExmCommandButton(3), ExmMenuButton(3), ExmSimple(3), and XmPrimitive(3).