Commands for Mouse Wheel Event Handling
in Scrollable Widget Containers

For Scrollutil Version 1.0

by

Csaba Nemethi

csaba.nemethi@t-online.de

Contents

Start page


The scrollutil::createWheelEventBindings Command

NAME
scrollutil::createWheelEventBindings – Create mouse wheel event bindings
SYNOPSIS
scrollutil::createWheelEventBindings ?tag tag ...?
DESCRIPTION
Creates mouse wheel event bindings for the specified binding tags such that if the widget under the pointer is (a descendant of) one of the scrollable widget containers registered via scrollutil::enableScrollingByWheel then these events will trigger a scrolling of that widget container.  Each tag argument must be all or the path name of an existing toplevel widget (including ".").
REMARK 1:  The reason for restricting the tag arguments to all and path names of existing toplevel widgets rather than supporting also tags like "BwScrollableFrame" (for BWidget ScrollableFrame) or "Scrolledframe" (for iwidgets::scrolledframe) is that the mouse wheel events should trigger a scrolling of the widget container under the pointer not only if the widget under the pointer is the widget container itself but also if it is a descendant of the latter (remember that for each window, the path name of its nearest toplevel ancestor and the tag all are contained in the window's default list of binding tags).
REMARK 2:  The mouse wheel events along the vertical axis are <MouseWheel> on Windows, <MouseWheel> and <Option-MouseWheel> on Mac OS X, and <MouseWheel>, <Button-4> and <Button-5> on X11 (where <MouseWheel> is not triggered by the X server, but can be produced using  event generate).  The mouse wheel events along the horizontal axis are <Shift-MouseWheel> on Windows, <Shift-MouseWheel> and <Shift-Option-MouseWheel> on Mac OS X, and <Shift-MouseWheel>, <Shift-Button-4> and <Shift-Button-5> on X11 (where <Shift-MouseWheel> is not triggered by the X server, but can be produced using  event generate).
KEYWORDS
mouse wheel event, binding, scrolling, scrollable widget container

Contents     Start page


The scrollutil::enableScrollingByWheel Command

NAME
scrollutil::enableScrollingByWheel – Register scrollable widget containers for scrolling by the mouse wheel
SYNOPSIS
scrollutil::enableScrollingByWheel ?scrollableWidgetContainer scrollableWidgetContainer ...?
DESCRIPTION
Adds the specified scrollable widget containers to the internal list of widget containers that are registered for scrolling by the mouse wheel event bindings created by the scrollutil::createWheelEventBindings command.
REMARK:  When a scrollable widget container whose path name was passed to this command gets destroyed, it is automatically removed from the above-mentioned internal list of registered widget containers.
KEYWORDS
mouse wheel event, binding, scrolling, scrollable widget container

Contents     Start page


The scrollutil::adaptWheelEventHandling Command

NAME
scrollutil::adaptWheelEventHandling – Adapt mouse wheel event handling
SYNOPSIS
scrollutil::adaptWheelEventHandling ?widget widget ...?
DESCRIPTION
For each widget argument, the command performs the following actions:
REMARK 1:  This command is designed to be invoked for widgets that have mouse wheel event bindings and are descendants of a scrollable widget container (although it does no harm if it is called for other widgets, too).  The Tk and tile widgets having class bindings for mouse wheel events are: listbox, scrollbar (but not ttk::scrollbar), text, ttk::combobox, ttk::spinbox, and ttk::treeview.  Examples of widgets with binding tags other than their class names that have mouse wheel event bindings are tablelist widgets as well as the entry components of mentry widgets of type "Date", "Time", "DateTime", "IPAddr", and "IPv6Addr" (for Mentry versions 3.2 and above).
REMARK 2:  Invoking this command for widgets that have mouse wheel event bindings and are descendants of a scrollable widget container is essential for a user-friendly mouse wheel event handling in scrollable widget containers.  Without this step the mouse wheel events would scroll both the listbox, text, ttk::treeview, or tablelist widget under the pointer and the widget container to whose descendants the latter belongs, or they would select the next/previous value in the ttk::combobox or ttk::spinbox under the pointer in addition to scrolling the widget container.
KEYWORDS
mouse wheel event, binding, event handling, scrolling, scrollable widget container, focus

Contents     Start page


The scrollutil::setFocusCheckWindow Command

NAME
scrollutil::setFocusCheckWindow – Set the "focus check window"
SYNOPSIS
scrollutil::setFocusCheckWindow widget ?widget ...? otherWidget
DESCRIPTION
For each widget argument, the command sets the associated "focus check window" to otherWidget.  This is the window to be used in the binding scripts for the tag WheeleventRedir instead of the widget when checking whether the focus is on/inside or outside that window.  For each widget argument, otherWidget must be an ancestor of or identical to widget.
REMARK 1:  When a widget whose path name was passed to this command as one of its widget arguments gets destroyed, the association between the widget and its "focus check window" is automatically removed.
REMARK 2:  This command comes in handy if for some widgets you want to make the focus check within the binding scripts for the tag WheeleventRedir less restrictive.  For example, if the widget under the pointer is an entry component of a mentry me of type "Date", "Time", "DateTime", "IPAddr", or "IPv6Addr" and the focus is on any of its siblings, then the mouse wheel events sent to this entry should be handled by the mentry widget rather than scrolling the widget container that is an ascendant of the mentry.  You can achieve this by invoking
set entryList [$me entries]
eval scrollutil::adaptWheelEventHandling  $entryList
eval scrollutil::setFocusCheckWindow      $entryList [list $me]
With Tcl/Tk 8.5 or above, you can use the more compact form
set entryList [$me entries]
scrollutil::adaptWheelEventHandling  {*}$entryList
scrollutil::setFocusCheckWindow      {*}$entryList $me
KEYWORDS
binding, focus, "focus check window"

Contents     Start page


The scrollutil::focusCheckWindow Command

NAME
scrollutil::focusCheckWindow – Query the "focus check window"
SYNOPSIS
scrollutil::focusCheckWindow widget
DESCRIPTION
Returns the path name of the "focus check window" associated with the widget argument.  This is the window that is used in the binding scripts for the tag WheeleventRedir instead of the widget when checking whether the focus is on/inside or outside that window.  If the command scrollutil::setFocusCheckWindow was not invoked for widget then the return value is widget itself.
KEYWORDS
binding, focus, "focus check window"

Contents     Start page