The scrollutil::scrollsync and scrollutil::getscrollsync Commands
Author: Csaba Nemethi
Keywords: scrollsync, widget, scrolling

# The `scrollutil::scrollsync` and
`scrollutil::getscrollsync` Commands

## For Scrollutil Version 2.2

### by

## Csaba Nemethi

## Contents

- The `scrollutil::scrollsync` Command – Quick Reference
- The `scrollutil::scrollsync` Command – Detailed Reference
- The `scrollutil::getscrollsync` Command

Start page

## The `scrollutil::scrollsync` Command – Quick Reference

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

      scrollutil::scrollsync pathName ?options?

DESCRIPTION
STANDARD OPTIONS

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

WIDGET-SPECIFIC OPTIONS
  `-takefocus 0|1|""|command`
WIDGET COMMAND
  `pathName attrib ?name ?value name value ...??`
  `pathName cget option`
  `pathName configure ?option ?value option value ...??`
  `pathName hasattrib name`
  `pathName setwidgets widgetList`
  `pathName unsetattrib name`
  `pathName widgets`
  `pathName xview ?args?`
    `pathName xview`
    `pathName xview moveto fraction`
    `pathName xview scroll number units|pages`
  `pathName yview ?args?`
    `pathName yview`
    `pathName yview moveto fraction`
    `pathName yview scroll number units|pages`
BINDINGS
KEYWORDS
  scrollsync, widget, scrolling

Contents Start page

## The `scrollutil::scrollsync` Command – Detailed Reference

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

      scrollutil::scrollsync pathName ?options?

DESCRIPTION
  The `scrollutil::scrollsync` command creates a new window named `pathName` and of the class `Scrollsync`, and makes it into a scrollsync widget. Additional options, described below, may be specified on the command line or in the option database to configure aspects of the scrollsync widget such as its borderwidth and relief. The `scrollutil::scrollsync` 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 scrollsync is a mega-widget, designed for scrolling several widgets simultaneously. It is both horizontally and vertically scrollable, meaning that it supports the `-xscrollcommand` and `-yscrollcommand` configuration options and the associated Tcl command has the `xview` and `yview` subcommands. Whenever the horizontal/vertical position of the view in the window of one of the horizontally/vertically scrollable widgets contained in the list passed to the `setwidgets` subcommand of the associated Tcl command changes, the view in the windows of all the other horizontally/vertically scrollable elements of that list is automatically adjusted accordingly, thus making sure that the view's position in these windows is kept in sync.
  A scrollsync widget is typically created within a scrollarea, like in the following example:

  >     set sa [scrollutil::scrollarea ...]
  >     set ss [scrollutil::scrollsync $sa.ss ...]
  >     $sa setwidget $ss

  >     set lb1 [listbox $ss.lb1 ...]
  >     set lb2 [listbox $ss.lb2 ...]
  >     $ss setwidgets [list $lb1 $lb2]

  >     grid $lb1 $lb2 -sticky news -padx {0 2}
  >     grid rowconfigure    $ss 0   -weight 1
  >     grid columnconfigure $ss all -weight 1

  >     pack $sa -expand yes -fill both

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: | `-takefocus`
  Database Name: | `takeFocus`
  Database Class: | `TakeFocus`

  > This option determines whether the scrollsync 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 scrollsync widget itself but the first element of the widget list passed to the `setwidgets` subcommand of the associated Tcl command will receive the focus during keyboard traversal with the standard keys (`Tab` and `Shift-Tab`). The default is `0`, being that a scrollsync widget is esentially a frame containing the above-mentioned widgets.

WIDGET COMMAND
  The `scrollutil::scrollsync` 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 scrollsync 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 cget option`
    Returns the current value of the configuration option given by `option`, which may have any of the values accepted by the `scrollutil::scrollsync` 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::scrollsync` command.
  `pathName hasattrib name`
    Returns `1` if the attribute `name` exists and `0` otherwise.
  `pathName setwidgets widgetList`
    Sets the widgets in whose windows the view's position is to be kept in sync. The `widgetList` argument must be a valid list consisting of path names of existing widgets. Whenever the horizontal/vertical position of the view in the window of one of the horizontally/vertically scrollable widgets contained in this list changes, the view in the windows of all the other horizontally/vertically scrollable elements of the list will be automatically adjusted accordingly, thus making sure that the view's position in these windows is kept in sync. The return value is the argument passed to the previous successful invocation of this subcommand, or an empty list if there was no successful `setwidgets` invocation before.
    REMARK: When one of the widgets whose path name is contained in `widgetList` gets destroyed, that widget is automatically removed from the internal list of widgets in whose windows the view's position is kept in sync.
  `pathName unsetattrib name`
    Unsets the attribute `name`. Returns an empty string.
  `pathName widgets`
    Returns the argument passed to the most recent successful invocation of the `setwidgets` subcommand, or an empty list if there was no successful invocation of that subcommand yet.
  `pathName xview ?args?`
    `pathName xview`
    `pathName xview moveto fraction`
    `pathName xview scroll number units|pages`
    This command passes its arguments to the `xview` command of the current master widget for the x axis and returns the result of that command invocation. The master widget for the x axis is the element of the widget list passed to the `setwidgets` subcommand having the smallest relative view width among the horizontally scrollable widgets in that list, i.e., the least difference between the last and first elements of the two-element list returned by its `xview` command. This master widget can vary during program execution (in case of text widgets it can even change depending on the current vertical view position).
  `pathName yview ?args?`
    `pathName yview`
    `pathName yview moveto fraction`
    `pathName yview scroll number units|pages`
    This command passes its arguments to the `yview` command of the current master widget for the y axis and returns the result of that command invocation. The master widget for the y axis is the element of the widget list passed to the `setwidgets` subcommand having the smallest relative view height among the vertically scrollable widgets in that list, i.e., the least difference between the last and first elements of the two-element list returned by its `yview` command. This master widget can vary during program execution.
BINDINGS
  When a new scrollsync widget is created, it has no default event bindings: scrollsync widgets are not intended to be interactive.
KEYWORDS
  scrollsync, widget, scrolling

Contents Start page

## The `scrollutil::getscrollsync` Command

NAME
  `scrollutil::getscrollsync` – Query the scrollsync containing a given widget
SYNOPSIS

      scrollutil::gescrollsync widget

DESCRIPTION
  Returns the path name of the scrollsync into which the widget given by the `widget` argument is embedded via the scrollsync's `setwidgets` subcommand, or an empty string if there is no such scrollsync widget.
KEYWORDS
  scrollsync, widget

Contents Start page