Scroll Widget Class
Overview
The Scroll widget is a container widget that scrolls INT widgets so that the
scrolled child widget's annotation remains visible during scrolling. The Scroll
widget combines one or two ScrollBar widgets, a viewing area that implements a
visible window onto a portion of the scrolled child, and drawing area widgets
for displaying the scrolled child widget's title, horizontal annotation and
vertical annotation. The application controls which of the Scroll widget's
components are displayed and where they are displayed. An application that
displays more than one Scroll widget can have the multiple Scroll widgets share
one or two ScrollBar widgets so that they are scrolled simultaneously.
Scroll Children
A Scroll widget can manage the scrolling of only one child. In particular, the
Scroll widget accepts as a scrolled child an EditTable widget. The Scroll
widget creates several child widgets for displaying the annotation and for the
scrolling operation. There is a convenience function provided for accessing
these widgets so that the application can customize the layout, appearance or
behavior of the children.
Creating a Scroll Widget
An application creates a Scroll widget as a child of any container widget using
either an Xt widget creation function or the supplied convenience function,
XintCreateScroll.
Specifying Annotation and Annotation Placement
You specify the placement and how the title, horizontal and vertical annotation
will be displayed with resources defined by the scrolled child. However, you
specify the margins between the title, the annotation, the scrolled child and
the Scroll widget using resources defined by the Scroll widget. Note that you
must explicitly set the height of the horizontal annotation window(s) and the
width of the vertical annotation window(s) using Scroll resources.
Specifying Scrollbar Display Policy and Placement
Using resources, you specify whether the scroll bars will always be displayed
or if they will be displayed only when needed. You also specify where the
scroll bars will be placed using Scroll resources. You can further customize
the appearance and behavior of the scroll bars by accessing them directly using
their widget IDs which are obtained via a convenience function. If the
application has created a ScrollBar widget used by a Scroll widget, then the
application is responsible for its placement.
Specifying a 3-D look for the Viewing Areas
The viewing areas for the scrolled widget, its title, its horizontal annotation
and its vertical annotation are enclosed within Frame widgets that have a 3-D
appearance.
Synchronized Scrolling
Multiple Scroll widgets can share scrollbar(s), so that it is possible to
synchronize the scrolling of the scrolled child widgets in the horizontal
and/or vertical direction. If two scrolled child widgets that are connected to
the same scrollbar have a different height and/or width, the scrolling rate
will be proportional to the height and/or width of each child.
Connecting scrollbars to Scroll Widgets
You accomplish synchronized scrolling by using the Scroll resources,
XmNhorizontalScrollBar and XmNverticalScrollBar, to specify (at widget creation
time) that a Scroll widget is to use a specific scrollbar to control the
scrolling of its scrolled child. The shared scrollbar(s) can be XmScrollBar
widget(s) created by the application or XmScrollBar widget(s) created
automatically when a Scroll widget was created. To obtain the widget ID for a
scrollbar created by a Scroll widget use the XintScrollGetChild function. To
obtain the widget ID of the Scroll widget controlling a specific ScrollBar
widget, get the value of the ScrollBar widget's XmNuserData resource.
Inherited Behavior and Resources
The Scroll widget inherits behavior and resources from Core, Composite,
Constraint, and Manager classes.
- The class pointer is xintScrollWidgetClass.
- The class name is XintScroll.
- The header file is included as <Xint/Scroll.h>.
Specifies whether the Scroll widget includes it children into tab groups using
function XmAddTabGroup.
Specifies the height (in pixels) of the window containing the horizontal
annotation displayed below the scrolled child widget. If the child of the
Scroll widget has resource XmNautoMarginAdjust set to XintADJUST_BOTTOM, this
resource will be ignored and the viewing area height will be calculated
automatically.
When this resource is set to True, the Scroll widget will try to adjust
automatically its width, so that its viewport width exactly matches the
scrolled child width.
Specifies the margin width (in pixels) between the scrolled child widget's
viewing area and the horizontal annotation viewing areas.
Specifies the margin width (in pixels) between the Scroll widget's window
border and the horizontal annotation viewing areas.
Specifies the widget ID of a horizontal ScrollBar to be used by the Scroll
widget. If this resource is set to NULL at widget creation time, then the
Scroll widget will create a new horizontal ScrollBar widget to control the
horizontal scrolling of its scrolled child. This resource provides a mechanism
to share a horizontal scrollbar among several Scroll widgets. Note: The value
of this resource can be set after widget creation time only if the application
had specified an application created scrollbar at widget creation time.
Specifies the width (in pixels) of the viewing area containing the vertical
annotation to the left of the scrolled widget. If the child of the Scroll
widget has resource XmNautoMarginAdjust set to XintADJUST_LEFT, this resource
will be ignored and the viewing area width will be calculated automatically.
Specifies the width (in pixels) of the viewing area containing the vertical
annotation to the right of the scrolled widget. If the child of the Scroll
widget has resource XmNautoMarginAdjust set to XintADJUST_RIGHT, this resource
will be ignored and the viewing area width will be calculated automatically.
Controls when the horizontal and vertical ScrollBars will be visible. Specify
the defined integer constant XintAS_NEEDED if you want the scroll bars to be
displayed when the scrolled widget exceeds the visible viewing area in the
horizontal or vertical directions. Specify XintSTATIC if scroll bars are always
to be displayed.
Specifies the extent of the scroll bars. When set to True, scroll bars occupy
the full length of the Scroll widget window. When set to False, scroll bars are
aligned with the Scroll widget viewport.
Specifies the position of the horizontal and vertical ScrollBars. You must use
one of the following defined constants when specifying the value of this
resource:
| Resource Value | Description
|
|---|
| XintBOTTOM_RIGHT (default) | Specifies that the horizontal ScrollBar will be placed below the scrolled widget and the vertical ScrollBar will be placed to the right of the scrolled widget.
|
| XintBOTTOM_LEFT | Specifies that the horizontal ScrollBar will be placed below the scrolled widget and the vertical ScrollBar will be placed to the left of the scrolled widget.
|
| XintTOP_LEFT | Specifies that the horizontal ScrollBar will be placed above the scrolled widget and the vertical ScrollBar will be placed to the left of the scrolled widget.
|
| XintTOP_RIGHT | Specifies that the horizontal ScrollBar will be placed above the scrolled widget and the vertical ScrollBar will be placed to the right of the scrolled widget.
|
Specifies the shadow thickness (in pixels) for the Frames around the viewing are
as for the scrolled child widget, its horizontal annotation and its vertical
annotation. Usually you will specify a positive integer as the value of this
resource. Alternatively, specifying 0 causes the widget to ignore the value of
XmNshadowType. In this case, no shadow is drawn around the annotation areas and
a line of width 1 pixel is drawn around the scrolled child.
Specifies the display characteristics of the Frames around the viewing areas
for the scrolled child, its horizontal annotation and its vertical annotation.
You must use one of the following defined constants when specifying the value
of this resource:
| Resource Value | Description
|
|---|
| XintSHADOW_NONE | Specifies that no shadow is to be drawn around the annotation areas and a line of width XmNshadowThickness (pixels) will be drawn around the scrolled child.
|
| XintSHADOW_IN (default) | Specifies that the Frames are to be drawn so that they appear to be inset
|
| XintSHADOW_OUT | Specifies that the Frames are to be drawn so that they appear to be outset.
|
| XintSHADOW_ETCHED_IN | Specifies that the Frames are to be drawn with a double line etched into the window.
|
| XintSHADOW_ETCHED_OUT | Specifies that the Frames are to be drawn with a double line coming out of the window.
|
Specifies the margin height (in pixels) between the title and the horizontal
annotation window. If there is no horizontal annotation window, then the title
margin is the distance between the title and the scrolled child widget's window.
Specifies the height (in pixels) of the window containing the horizontal
annotation displayed above the scrolled child widget. If the child of the
Scroll widget has resource XmNautoMarginAdjust set to XintADJUST_TOP, this
resource will be ignored and the viewing area height will be calculated
automatically.
When this resource is set to True, the Scroll widget will try to automatically
adjust its height, so that its viewport height exactly matches the Scroll child
height.
Specifies the margin width (in pixels) between the scrolled child widget's
window border and the vertical annotation viewing areas.
Specifies the margin width (in pixels) between the vertical annotation's
viewing area and the Scroll widget's window border (or possibly, the vertical
ScrollBar).
Specifies the widget ID of a vertical ScrollBar to be used by the Scroll
widget. If this resource is set to NULL at widget creation time, the Scroll
widget will create a new vertical ScrollBar widget to control the vertical
scrolling of its scrolled child. This resource provides a mechanism to share a
vertical scrollbar among several Scroll widgets. Note: The value of this
resource can be set after widget creation time, only if the application had
specified an application created scrollbar at widget creation time.
Internal Widgets
The following table lists the named widgets contained within a Scroll widget
which are accessible to the application programmer. The appearance and
behavior of the internal widgets can be specified in a resource file using the
listed widget names.
| Name | Class | Description
|
|---|
| bottom_w | XmDrawingArea | The window where the bottom horizontal annotation is drawn.
|
| hsb | XmScrollBar | The horizontal ScrollBar.
|
| left_w | XmDrawingArea | The window where the left vertical annotation is drawn.
|
| right_w | XmDrawingArea | The window where the right vertical annotation is drawn.
|
| top_w | XmDrawingArea | The window where the top horizontal annotation is drawn.
|
| viewport | XmDrawingArea | The window where the current view of the scrolled child is drawn.
|
| vsb | XmScrollBar | The vertical ScrollBar.
|
The following components are created only when the child of the Scroll widget
is an EditTable widget with frozen rows or columns.
| Name | Class | Description
|
|---|
| bottom_frozen_w | XmDrawingArea | The window where the bottom horizontal annotation for frozen rows/columns is drawn.
|
| left_frozen_w | XmDrawingArea | The window where the left vertical annotation for frozen rows/columns is drawn.
|
| right_frozen_w | XmDrawingArea | The window where the right vertical annotation for frozen rows/columns is drawn.
|
| top_frozen_w | XmDrawingArea | The window where the top horizontal annotation for frozen rows/columns is drawn.
|
Defined Functions
The following functions are defined for creating a Scroll widget, obtaining the
widget IDs of the internal named children of a Scroll widget and scrolling to
the specified position.
XintCreateScroll creates an unmanaged Scroll widget.
Widget XintCreateScroll (...)
| Widget | parent | Parent of new Scroll widget.
|
| char * | name | Name of new Scroll widget.
|
| ArgList | arglist | List of resource/value items.
|
| Cardinal | argcount | Number of items in arglist.
|
This function returns the widget ID of a specified Scroll widget component.
Widget XintScrollGetChild (...)
| Widget | widget | The Scroll widget ID.
|
| int | child | Specifies the named child of interest as a defined integer constant.
|
You must specify child as one of the following defined integer constants.
| Defined Constant | Description
|
|---|
| XintBOTTOM_WINDOW | Bottom horizontal annotation DrawingArea widget.
|
| XintLEFT_WINDOW | Left vertical annotation DrawingArea widget.
|
| XintHORIZONTAL_SCROLLBAR | Horizontal ScrollBar widget.
|
| XintRIGHT_WINDOW | Right vertical annotation DrawingArea widget.
|
| XintTOP_WINDOW | Top horizontal annotation DrawingArea widget.
|
| XintVERTICAL_SCROLLBAR | Vertical ScrollBar widget.
|
| XintVIEWPORT | DrawingArea widget containing the current view of the scrolled child.
|
If the child of the Scroll widget is an EditTable widget, you can also specify
child as one of the following defined integer constants.
| Defined Constant | Description
|
|---|
| XintLEFT_FROZEN_WINDOW | DrawingArea widget that can contain the left row annotation for the frozen rows
|
| XintRIGHT_FROZEN_WINDOW | DrawingArea widget that can contain the right row annotation for the frozen rows
|
| XintTOP_FROZEN_WINDOW | DrawingArea widget that can contain the top column annotation for the frozen columns
|
| XintBOTTOM_FROZEN_WINDOW | DrawingArea widget that can contain the bottom column annotation for the frozen columns
|
| XintFROZEN_COLUMN_VIEWPORT | The DrawingArea widget containing the frozen columns.
|
| XintFROZEN_ROW_VIEWPORT | The DrawingArea widget containing the frozen rows.
|
| XintFROZEN_INTERSECTION_VIEWPORT | The DrawingArea widget containing the intersection of the frozen rows and columns.
|
This function forces the Scroll widget to scroll to the specified position, in
one or both directions. The function returns False if the arguments
user_x or user_y are out of range.
Boolean XintScrollScrollToPosition (...)
| Widget | widget | The Scroll widget ID.
|
| float | user_x | The horizontal coordinate where to scroll (column number if child is an EditTable).
|
| float | user_y | The vertical coordinate where to scroll (row number if child is an EditTable).
|
| float | vp_x_percent | Where to scroll as a percentage (0.0 at the left, 50.0 in the middle, etc.) Specify a negative value to disable scrolling in that direction.
|
| float | vp_y_percent | Where to scroll as a percentage (0.0 at the top, 50.0 in the middle, etc.) Specify a negative value to disable scrolling in that direction.
|