The scrollutil::scrollableframe Command
Author: Csaba Nemethi
Keywords: scrollableframe, widget, frame, scrollable

# The `scrollutil::scrollableframe` Command

## For Scrollutil Version 1.17

### by

## Csaba Nemethi

## Contents

- Quick Reference
- Detailed Reference
- Comparison with BWidget ScrollableFrame and iwidgets::scrolledframe

Start page

## Quick Reference

NAME
  `scrollutil::scrollableframe` – Create and manipulate scrollableframe widgets
SYNOPSIS

      scrollutil::scrollableframe pathName ?options?

DESCRIPTION
STANDARD OPTIONS

      -background   -highlightbackground  -relief
      -borderwidth  -highlightcolor       -xscrollcommand
      -cursor       -highlightthickness   -yscrollcommand

WIDGET-SPECIFIC OPTIONS
  `-contentheight screenDistance`
  `-contentwidth screenDistance`
  `-fitcontentheight boolean`
  `-fitcontentwidth boolean`
  `-height screenDistance`
  `-takefocus 0|1|""|command`
  `-width screenDistance`
  `-xscrollincrement screenDistance`
  `-yscrollincrement screenDistance`
WIDGET COMMAND
  `pathName attrib ?name ?value name value ...??`
  `pathName autofillx ?boolean?`
  `pathName autofilly ?boolean?`
  `pathName autosize ?w|h|wh?`
  `pathName cget option`
  `pathName configure ?option ?value option value ...??`
  `pathName contentframe`
  `pathName hasattrib name`
  `pathName scan option args`
    `pathName scan mark x y`
    `pathName scan dragto x y ?gain?`
  `pathName see widget ?nw|ne|sw|se?`
  `pathName seerect x1 y1 x2 y2 ?nw|ne|sw|se?`
  `pathName unsetattrib name`
  `pathName xview ?args?`
    `pathName xview`
    `pathName xview units`
    `pathName xview moveto fraction`
    `pathName xview scroll number units|pages`
  `pathName yview ?args?`
    `pathName yview`
    `pathName yview units`
    `pathName yview moveto fraction`
    `pathName yview scroll number units|pages`
BINDINGS
KEYWORDS
  scrollableframe, widget, frame, scrollable

Contents Start page

## Detailed Reference

NAME
  `scrollutil::scrollableframe` – Create and manipulate scrollableframe widgets
SYNOPSIS

      scrollutil::scrollableframe pathName ?options?

DESCRIPTION
  The `scrollutil::scrollableframe` command creates a new window named `pathName` and of the class `Scrollableframe`, and makes it into a scrollableframe widget. Additional options, described below, may be specified on the command line or in the option database to configure aspects of the scrollableframe widget such as its width, height, and scrolling increments. The `scrollutil::scrollableframe` command returns its `pathName` argument. At the time this command is invoked, there must not exist a window named `pathName`, but `pathName`'s parent must exist.
  A scrollableframe is a mega-widget containing a content frame, whose dimensions may be larger than those of the widget itself. Arbitrary regions of this frame can be brought into view by scrolling, being that the scrollableframe widget supports the `-xscrollcommand` and `-yscrollcommand` configuration options and the associated Tcl command has the `xview` and `yview` subcommands. The content frame may contain any number of arbitrary widgets. In other words, the `scrollutil::scrollableframe` command implements a scrollable widget container.
  In the Scrollutil package both the scrollableframe widget and its content frame are implemented as Tk core frames, while in Scrollutil_tile they are ttk::frame widgets. The content frame can be accessed by means of the `contentframe` subcommand. Individual widgets contained in it can be made visible in the scrollableframe window with the aid of the `see` subcommand. In addition to scrolling, scrollableframe widgets also support scanning, with the aid of appropriate mouse event bindings that invoke the `scan` subcommand.
  A scrollableframe widget is typically created within a scrollarea, like in the following example:

  >     set sa [scrollutil::scrollarea ...]
  >     set sf [scrollutil::scrollableframe $sa.sf ...]
  >     $sa setwidget $sf

  >     set cf [$sf contentframe]
  >     <populate the content frame>

  >     $sf autosize w
  >     update idletasks
  >     $sf configure -height ... -yscrollincrement ...

  >     pack $sa -expand yes -fill both

  REMARK: After creating the scrollableframe widget, the `scrollutil::scrollableframe` command automatically registers it for scrolling with the mouse wheel, by passing its path name to the `scrollutil::enableScrollingByWheel` command.
STANDARD OPTIONS

      -background   -highlightbackground  -relief
      -borderwidth  -highlightcolor       -xscrollcommand
      -cursor       -highlightthickness   -yscrollcommand

  See the options manual entry for details on the standard Tk widget options. The `-background`, `-highlightbackground`, `-highlightcolor`, and `-highlightthickness` options are only supported by the Scrollutil package, but not by Scrollutil_tile. They have the same default values as the options of the same names for Tk frame widgets. The default values of the remaining standard options are:

      -borderwidth 0 -cursor "" -relief flat -xscrollcommand "" -yscrollcommand ""

WIDGET-SPECIFIC OPTIONS

  Command-Line Name: | `-contentheight`
  Database Name: | `contentHeight`
  Database Class: | `ContentHeight`

  > Specifies the desired height for the content frame in any of the forms acceptable to `Tk_GetPixels`. If the option's value is less than or equal to zero then the content frame's height is made just large enough to hold all its children. This option is only relevant if the value of the `-fitcontentheight` option is false; otherwise the content frame will have the same height as the scrollableframe window (excluding the latter's border and highlight rectangle, if any), regardless of the value of the `-contentheight` option. The default is `0`, which is suitable for the vast majority of applications.

  Command-Line Name: | `-contentwidth`
  Database Name: | `contentWidth`
  Database Class: | `ContentWidth`

  > Specifies the desired width for the content frame in any of the forms acceptable to `Tk_GetPixels`. If the option's value is less than or equal to zero then the content frame's width is made just large enough to hold all its children. This option is only relevant if the value of the `-fitcontentwidth` option is false; otherwise the content frame will have the same width as the scrollableframe window (excluding the latter's border and highlight rectangle, if any), regardless of the value of the `-contentwidth` option. The default is `0`, which is suitable for the vast majority of applications.

  Command-Line Name: | `-fitcontentheight`
  Database Name: | `fitContentHeight`
  Database Class: | `FitContentHeight`

  > Specifies a boolean value indicating whether or not the content frame should have the same height as the scrollableframe window (excluding the latter's border and highlight rectangle, if any). If true then the content frame's height will be kept in sync with that of the widget and the value of the `-contentheight` option will be ignored. The default is `0`.

  Command-Line Name: | `-fitcontentwidth`
  Database Name: | `fitContentWidth`
  Database Class: | `FitContentWidth`

  > Specifies a boolean value indicating whether or not the content frame should have the same width as the scrollableframe window (excluding the latter's border and highlight rectangle, if any). If true then the content frame's width will be kept in sync with that of the widget and the value of the `-contentwidth` option will be ignored. The default is `0`.

  Command-Line Name: | `-height`
  Database Name: | `height`
  Database Class: | `Height`

  > Specifies the desired height for the scrollableframe widget in any of the forms acceptable to `Tk_GetPixels`. Note that this sets the inner height, excluding the border and highlight rectangle (if any) drawn around the outside of the widget. The default is `7c`, which should be overridden with a suitable application-specific value.

  Command-Line Name: | `-takefocus`
  Database Name: | `takeFocus`
  Database Class: | `TakeFocus`

  > This option determines whether the scrollableframe widget accepts the focus during keyboard traversal. It is almost identical to the standard option of the same name (see the options manual entry for details). The only difference is that not the scrollableframe widget itself but its content frame will receive the focus during keyboard traversal with the standard keys (`Tab` and `Shift-Tab`). The default is `0`, being that a scrollableframe widget is esentially a frame used as a view for its content frame component.

  Command-Line Name: | `-width`
  Database Name: | `width`
  Database Class: | `Width`

  > Specifies the desired width for the scrollableframe widget in any of the forms acceptable to `Tk_GetPixels`. Note that this sets the inner width, excluding the border and highlight rectangle (if any) drawn around the outside of the widget. The default is `10c`, which should be overridden with a suitable application-specific value.

  Command-Line Name: | `-xscrollincrement`
  Database Name: | `xScrollIncrement`
  Database Class: | `ScrollIncrement`

  > Specifies an increment for horizontal scrolling, in any of the forms acceptable to `Tk_GetPixels`. If the value of this option is greater than zero then the horizontal view in the window will be constrained so that the x coordinate within the content frame at the left edge of the window is always an even multiple of `xScrollIncrement`; furthermore, the units for horizontal scrolling (see the `xview` subcommad) will also be `xScrollIncrement`. If the value is less than or equal to zero then the horizontal scrolling is unconstrained. The default is `0`.

  Command-Line Name: | `-yscrollincrement`
  Database Name: | `yScrollIncrement`
  Database Class: | `ScrollIncrement`

  > Specifies an increment for vertical scrolling, in any of the forms acceptable to `Tk_GetPixels`. If the value of this option is greater than zero then the vertical view in the window will be constrained so that the y coordinate within the content frame at the top edge of the window is always an even multiple of `yScrollIncrement`; furthermore, the units for vertical scrolling (see the `yview` subcommad) will also be `yScrollIncrement`. If the value is less than or equal to zero then the vertical scrolling is unconstrained. The default is `0`.

WIDGET COMMAND
  The `scrollutil::scrollableframe` command creates a new Tcl command whose name is `pathName`. This command may be used to invoke various operations on the widget. It has the following general form:

  >     pathName option ?arg arg ...?

  `option` and the `arg`s determine the exact behavior of the command. The following commands are possible for scrollableframe widgets:
  `pathName attrib ?name ?value name value ...??`
    Queries or modifies the attributes of the widget. If no `name` is specified, the command returns a list of pairs, each of which contains the name and the value of an attribute for `pathName`. If `name` is specified with no `value`, then the command returns the value of the one named attribute, or an empty string if no corresponding value exists (you can use the `hasattrib` subcommand to distinguish this case from the one that the value of an existing attribute is an empty string). If one or more `name`-`value` pairs are specified, then the command sets the given widget attribute(s) to the given value(s); in this case the return value is an empty string. Each `name` may be an arbitrary string.
  `pathName autofillx ?boolean?`
    Controls or queries whether the content frame will fill the widget's entire inner width. If the optional boolean argument is true then the command sets the `-fitcontentwidth` option to true if the content frame's requested width is less than the scrollableframe's inner width and to false otherwise. Moreover, the command makes sure that this action will be repeated whenever the content frame's requested width or the scrollableframe's inner width changes. If the optional argument is false then the command clears the flag that controls this dynamic action. In both cases, the return value is an empty string. Without the optional argument the command returns the current value of the above-mentioned flag.
  `pathName autofilly ?boolean?`
    Controls or queries whether the content frame will fill the widget's entire inner height. If the optional boolean argument is true then the command sets the `-fitcontentheight` option to true if the content frame's requested height is less than the scrollableframe's inner height and to false otherwise. Moreover, the command makes sure that this action will be repeated whenever the content frame's requested height or the scrollableframe's inner height changes. If the optional argument is false then the command clears the flag that controls this dynamic action. In both cases, the return value is an empty string. Without the optional argument the command returns the current value of the above-mentioned flag.
  `pathName autosize ?dimensions?`
    This command sets the `-width` and/or `-height` option of the scrollableframe to the requested width and/or height of its content frame, according to the optional `dimensions` argument, whose possible values are `w` (width), `h` (height), and `wh` (width and height). The default is an empty string, meaning that neither the width nor the height is explicitly requested to be set. Note that if the value of the `-fitcontentwidth` option is true then the command sets the widget's inner width to the requested width of its content frame, regardless of whether this was explicitly specified or not. Similarly, if the value of the `-fitcontentheight` option is true then the command sets the widget's inner height to the requested height of its content frame, even if this was not explicitly specified.
    REMARK: Setting the widget's inner width and/or height on behalf of this subcommand is executed as an `"after 100"` callback, to make sure that by the time the widget's width and/or height are set, the geometry management calculations in its content frame are finished.
  `pathName cget option`
    Returns the current value of the configuration option given by `option`, which may have any of the values accepted by the `scrollutil::scrollableframe` command.
  `pathName configure ?option ?value option value ...??`
    Queries or modifies the configuration options of the widget. If no `option` is specified, the command returns a list describing all of the available options for `pathName` (see `Tk_ConfigureInfo` for information on the format of this list). If `option` is specified with no `value`, then the command returns a list describing the one named option (this list will be identical to the corresponding sublist of the value returned if no `option` is specified). If one or more `option`-`value` pairs are specified, then the command modifies the given widget option(s) to have the given value(s); in this case the return value is an empty string. `option` may have any of the values accepted by the `scrollutil::scrollableframe` command.
  `pathName contentframe`
    Returns the path name of the widget's content frame.
  `pathName hasattrib name`
    Returns `1` if the attribute `name` exists and `0` otherwise.
  `pathName scan option args`
    This command is used to implement scanning on scrollableframe widgets. It has two forms, depending on `option`:
    `pathName scan mark x y`
      Records `x` and `y` and the current view in the scrollableframe window; used in conjunction with later `scan dragto` commands. Typically this command is associated with a mouse button press in the widget and `x` and `y` are the coordinates of the mouse. It returns an empty string.
    `pathName scan dragto x y ?gain?`
      This command computes the difference between its `x` and `y` arguments (which are typically mouse coordinates) and the `x` and `y` arguments to the last `scan mark` command for the widget. It then adjusts the view by `gain` times the difference in coordinates, where `gain` defaults to `10`. This command is typically associated with mouse motion events in the widget, to produce the effect of dragging the content frame at high speed through the window. The return value is an empty string.
  `pathName see widget ?corner?`
    This command adjusts the view in the scrollableframe's window so that `widget` becomes visible in it. The specified widget must be a descendant of the content frame and must have the same toplevel. In addition, it must be managed by some geometry manager (such as `grid`, `pack`, `place`, `text`, or `canvas`). The optional `corner` argument specifies which corner of `widget` should become visible if it is too large to fit into the window. The possible values are `nw` (north-west), `ne` (north-east), `sw` (south-west), and `se` (south-east). The default corner is `nw`.
    REMARK: By using this subcommand you can make the keyboard navigation in the content frame more user-friendly, like in the following example, in which `$w` is a descendant of the content frame of the scrollableframe widget `$sf` (it is assumed that `$sf` doesn't contain `%` characters):

    >     bind $w <<TraverseIn>> [list $sf see %W]

    If the widget `$w` was embedded into a scrollarea via the latter's `setwidget` subcommand, and the scrollarea in turn is a descendant of the content frame, then it is more user-friendly to bring the scrollarea into view rather than just the widget:

    >     bind $w <<TraverseIn>> [list seeScrollarea $sf %W]

    >     proc seeScrollarea {sf w} { $sf see [scrollutil::getscrollarea $w] }

  `pathName seerect x1 y1 x2 y2 ?corner?`
    This command adjusts the view in the scrollableframe's window so that the rectangle given by `x1`, `y1`, `x2`, and `y2` becomes visible in it. These coordinates are relative to the content frame and specify two diagonally opposite corners of the rectangle (which will include its upper and left edges but not its lower or right edges). The optional `corner` argument specifies which corner of the rectangle should become visible if it is too large to fit into the window. The possible values are `nw` (north-west), `ne` (north-east), `sw` (south-west), and `se` (south-east). The default corner is `nw`.
  `pathName unsetattrib name`
    Unsets the attribute `name`. Returns an empty string.
  `pathName xview ?args?`
    This command is used to query and change the horizontal position of the information displayed in the widget's window. It can take any of the following forms:
    `pathName xview`
      Returns a list containing two elements. Each element is a real fraction between `0` and `1`; together they describe the horizontal span that is visible in the window. For example, if the first element is `0.2` and the second element is `0.6` then 20% of the content frame is off-screen to the left, the middle 40% is visible in the window, and 40% of the content frame is off-screen to the right. These are the same values passed to scrollbars via the `-xscrollcommand` option.
    `pathName xview units`
      Adjusts the view in the window so that the content frame position given by `units` is displayed at the left edge of the window. This argument specifies a number of units of the `xScrollIncrement` option if it is greater than zero, or of one-tenth the window's inner width otherwise.
    `pathName xview moveto fraction`
      Adjusts the view in the window so that `fraction` of the total width of the content frame is off-screen to the left. `fraction` must be a fraction between `0` and `1`.
    `pathName xview scroll number what`
      This command shifts the view in the window left or right according to `number` and `what`. `number` must be an integer or a float; if it is a float then it is converted to an integer, rounded away from `0`. `what` must be either `units` or `pages` or an abbreviation of one of these. If `what` is `units`, the view adjusts left or right in units of the `xScrollIncrement` option if it is greater than zero, or in units of one-tenth the window's inner width otherwise. If `what` is `pages` then the view adjusts in units of nine-tenths the window's inner width. If `number` is negative then information farther to the left becomes visible; if it is positive then information farther to the right becomes visible.
  `pathName yview ?args?`
    This command is used to query and change the vertical position of the information displayed in the widget's window. It can take any of the following forms:
    `pathName yview`
      Returns a list containing two elements. Each element is a real fraction between `0` and `1`; together they describe the vertical span that is visible in the window. For example, if the first element is `0.2` and the second element is `0.6` then 20% of the content frame is off-screen to the top, the middle 40% is visible in the window, and 40% of the content frame is off-screen to the bottom. These are the same values passed to scrollbars via the `-yscrollcommand` option.
    `pathName yview units`
      Adjusts the view in the window so that the content frame position given by `units` is displayed at the top edge of the window. This argument specifies a number of units of the `yScrollIncrement` option if it is greater than zero, or of one-tenth the window's inner height otherwise.
    `pathName yview moveto fraction`
      Adjusts the view in the window so that `fraction` of the total height of the content frame is off-screen to the top. `fraction` must be a fraction between `0` and `1`.
    `pathName yview scroll number what`
      This command shifts the view in the window up or down according to `number` and `what`. `number` must be an integer or a float; if it is a float then it is converted to an integer, rounded away from `0`. `what` must be either `units` or `pages` or an abbreviation of one of these. If `what` is `units`, the view adjusts up or down in units of the `yScrollIncrement` option if it is greater than zero, or in units of one-tenth the window's inner height otherwise. If `what` is `pages` then the view adjusts in units of nine-tenths the window's inner height. If `number` is negative then information farther to the top becomes visible; if it is positive then information farther to the bottom becomes visible.
BINDINGS
  Mouse button 1 may be used for scanning. If it is pressed and dragged over the scrollableframe window, the content frame drags at high speed in the direction the mouse moves. For the duration of the scan the cursor is set to one having the shape of a pointing hand.
KEYWORDS
  scrollableframe, widget, frame, scrollable

Contents Start page

## Comparison with BWidget ScrollableFrame and iwidgets::scrolledframe

The scrollutil::scrollableframe widget was designed as a lightweight, theme-able, and full-featured replacement for BWidget ScrollableFrame and iwidgets::scrolledframe. The following table contains a comparison of the options and commands provided by the three widgets:

scrollutil::scrollableframe | BWidget ScrollableFrame | iwidgets::scrolledframe
--- | --- | ---
`-background` | `-background` | `-background`
`-borderwidth` |  | `-borderwidth`
`-cursor` |  | `-cursor`
`-contentheight` | `-areaheight` | `[pathName component canvas] \ itemconfigure frameTag -height ...`
`-contentwidth` | `-areawidth` | `[pathName component canvas] \ itemconfigure frameTag -width ...`
`-fitcontentheight` | `-constrainedheight` | `bind [pathName component canvas] <Configure> \ { %W itemconfigure frameTag -height %h }`
`-fitcontentwidth` | `-constrainedwidth` | `bind [pathName component canvas] <Configure> \ { %W itemconfigure frameTag -width %w }`
`-height` (sets the inner height, excluding the border and highlight rectangle, if any) | `-height` (inner height = total height) | `-height` (sets the total height, including the border and horizontal scrollbar, if any)
`-highlightbackground` |  |
`-highlightcolor` |  |
`-highlightthickness` |  |
`-relief` |  | `-relief`
`-takefocus` |  |
`-width` (sets the inner width, excluding the border and highlight rectangle, if any) | `-width` (inner width = total width) | `-width` (sets the total width, including the border and vertical scrollbar, if any)
`-xscrollcommand` | `-xscrollcommand` |
`-xscrollincrement` | `-xscrollincrement` | `-xscrollincrement` for `[pathName component canvas]`
`-yscrollcommand` | `-yscrollcommand` |
`-yscrollincrement` | `-yscrollincrement` | `-yscrollincrement` for `[pathName component canvas]`
`attrib` |  |
`autosize` |  |
`autofillx` |  |
`autofilly` |  |
`cget` | `cget` | `cget`
`configure` | `configure` | `configure`
`contentframe` | `getframe` | `childsite`
`hasattrib` |  |
`scan` (with mouse event bindings) |  |
`see widget ?nw|ne|sw|se?` | `see widget ?top|bottom ?left|right??` |
`seerect x1 y1 x2 y2 ?nw|ne|sw|se?` |  |
`unsetattrib` |  |
`xview` | `xview` | `xview`
`yview` | `yview` | `yview`
`xview|yview units` |  |
`xview|yview moveto 0|1` | `xview|yview moveto 0|1` | `justify left|right|top|bottom` (shortcut for `xview|yview moveto 0|1`)

REMARK 1: For the `see` command provided by the BWidget ScrollableFrame widget one cannot specify the horizontal side without the vertical one. More annoying is, however, that in the presence of a positive `-xscrollincrement` or `-yscrollincrement` value, widgets that are small enough to fit into the window are quite often just partially brought into view. In addition, the command works only for direct children of the ScrollableFrame widget's content frame.

REMARK 2: The iwidgets::scrolledframe widget has no equivalents of the scrollutil::scrollableframe options `-contentheight`, `-contentwidth`, `-fitcontentheight`, and `-fitcontentwidth`, but these can be emulated (using undocumented internal information!) as shown above. It provides a `justify` command, which is, however, just a shortcut for `xview|yview moveto 0|1`. What this widget is really missing, is a `see` command for making individual widgets visible in the window (which is important for user-friendly keyboard navigation).

Contents Start page