WINDETECT(n)

NAME
windetect - Tk window detection library

SYNOPSIS

package require windetect
::windetect::configure ?option value? ?option value?
::windetect::detect ?state?
::windetect::exit

DESCRIPTION

The package windetect is a library that provides the detection functionality for tracking windows in a Tk application using the mouse pointer. Each time a new window shows up under the mouse pointer, windetect reports the following data: the pathname of the detected window and the screen coordinates of the mouse pointer. The reporting mechanism is a callback command, to which these data are passed as parameters.

This package is meant to be loaded into the interpreter which executes the code for the GUI whose windows need to be detected (the client interpreter). Immediately after being loaded, the detection functionality is not yet active; it needs to be explicitly activated with the command ::windetect::detect on.

The commands in the package windetect are encapsulated inside the namespace ::windetect. This namespace does not export its commands; fully qualified command names have to be used.

REQUIREMENTS

Package windetect requires Tk 8.5 or newer. The package has been tested on Linux and MS Windows. The macOS operating system is not supported.

COMMAND SYNTAX

::windetect::configure ?option value? ?option value?
    Queries or modifies settings for the behaviour of windetect. If no options are supplied, the current settings for all configurable options are returned. If a single option name is supplied, then the setting for that particular option is returned. If one or more option-value pairs are supplied, then the options are set to the newly supplied values.

    The following options are supported:

    -callback cmdprefix
        Defines the callback command that is called when a new window is detected. The actual command called is the command prefix cmdprefix, with the following three extra arguments appended:

            • the pathname of the newly detected window

            • the x coordinate of the mouse pointer relative to the root window

            • the y coordinate of the mouse pointer relative to the root window

        Therefore, the programmer needs to ensure that the callback command accepts at least three arguments additionally to what has been specified with the cmdprefix argument.

        By default the package uses a callback command which writes the values for these three variables to stdout.

    -delay ms
        Defines the time interval between successive reporting events, also called the reporting delay. This delay causes detection events that occur in quick succession to be skipped from reporting. Detection events that occur in quick succession have two different causes:

            • the mouse pointer is moved comparatively swiftly over a GUI, traversing multiple windows in a short time frame

            • virtual crossings (see the manual page for bind for what this means). In this case it doesn't matter how swift or slow the mouse pointer moves across a GUI because the screen distance between the detected windows is zero.

        Especially in the latter case, the time between successive detection events is very short.

        Skipping detection events that occur in quick succession, spares the user from a possible overload of information. On the other hand, if the delay is chosen too long, the reporting process may miss relevant detection events, especially on systems that behave slowly. The option -delay allows the user to customize the reporting delay, depending on the informational needs of the user and the performance of the computer system.

        The default value for ms is 50. If set to zero, reporting will occur for each detection event, including virtual crossings.

::windetect::detect ?state?
    Activates or deactivates the detection functionality, depending the value of state. Valid values for state are on and off. If no argument is supplied, the current detection state is returned. The initial state after loading the package is off.

::windetect::exit
    Deactivates detection functionality, removes the ::windetect namespace, and removes the package from the interpreter.

TESTING

The test script provided with the windetect distribution only exercises calls to the commands in this package. The correctness and usefulness of the detection functionality while tracking windows in a GUI is tested by the related package wintrackgui.

AUTHOR

Erik Leunissen

SEE ALSO

bind(n), wintrackgui(n)

KEYWORDS

Detect and report windows under the mouse pointer.

LICENSE

Copyright © 2020 Erik Leunissen.

Licensed under the Apache License, Version 2.0 (the "License"); you may not use this file except in compliance with the License. You may obtain a copy of the License at:

http://www.apache.org/licenses/LICENSE-2.0

Unless required by applicable law or agreed to in writing, software distributed under the License is distributed on an "AS IS" BASIS, WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied. See the License for the specific language governing permissions and limitations under the License.