[ Previous | Next | Contents | Glossary | Home | Search ]
Motif 2.1 Widget Writer's Guide


The Panner widget class


#include <Exm/Panner.h>


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:

  1. Write a two-dimensional navigator widget

  2. 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.

  3. 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

    Specifies the vertical size of the canvas.

    Specifies the horizontal size of the canvas.

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

    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.

    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.

    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.

    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.

    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


    ExmPanner provides the following translations:









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

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

    ~s ~c ~m ~a <Btn1Up>:
    ExmPannerNotify() ExmPannerStop()

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

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

    ~s ~c ~m ~a <Btn2Up>:
    ExmPannerNotify() ExmPannerStop()


    ExmPannerPage(+0, -1p)

    :c <Key>osfPageUp:
    ExmPannerPage(+0, -1c)

    ExmPannerPage(+0, +1p)

    :c <Key>osfPageDown:
    ExmPannerPage(+0, +1c)

    ExmPannerPage(-1p, +0)

    :c <Key>osfPageLeft:
    ExmPannerPage(-1c, +0)

    ExmPannerPage(+1p, +0)

    :c <Key>osfPageRight:
    ExmPannerPage(+1c, +0)

    ExmPannerPage(-1, +0)

    :c <Key>osfLeft:
    ExmPannerPage(-1p, +0)

    ExmPannerPage(+1, +0)

    :c <Key>osfRight:
    ExmPannerPage(+1p, +0)

    ExmPannerPage(+0, -1)

    :c <Key>osfUp:
    ExmPannerPage(+0, -1p)

    ExmPannerPage(+0, +1)

    :c <Key>osfDown:
    ExmPannerPage(+0, +1p)

    ExmPannerPage(+1c, +1c)


    ~s ~m ~a <Key>Return:

    s ~m ~a <Key>Tab:

    ~m ~a <Key>Tab:

    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).


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

    [ Previous | Next | Contents | Glossary | Home | Search ]