Tcl Library Source Code

Documentation
Login
Bounty program for improvements to Tcl and certain Tcl packages.


[ Main Table Of Contents | Table Of Contents | Keyword Index | Categories | Modules | Applications ]

NAME

hook - Hooks

Table Of Contents

SYNOPSIS

package require Tcl 8.5
package require hook ?0.1?

hook bind ?subject? ?hook? ?observer? ?cmdPrefix?
hook call subject hook ?args...?
hook forget object
hook cget option
hook configure option value ...

DESCRIPTION

This package provides the hook ensemble command, which implements the Subject/Observer pattern. It allows subjects, which may be modules, objects, widgets, and so forth, to synchronously call hooks which may be bound to an arbitrary number of subscribers, called observers. A subject may call any number of distinct hooks, and any number of observers can bind callbacks to a particular hook called by a particular subject. Hook bindings can be queried and deleted.

This man page is intended to be a reference only.

Concepts

Introduction

Tcl modules usually send notifications to other modules in two ways: via Tk events, and via callback options like the text widget's -yscrollcommand option. Tk events are available only in Tk, and callback options require tight coupling between the modules sending and receiving the notification.

Loose coupling between sender and receiver is often desirable, however. In Model/View/Controller terms, a View can send a command (stemming from user input) to the Controller, which updates the Model. The Model can then call a hook to which all relevant Views subscribe. The Model is decoupled from the Views, and indeed need not know whether any Views actually exist. At present, Tcl/Tk has no standard mechanism for implementing loose coupling of this kind. This package defines a new command, hook, which implements just such a mechanism.

Bindings

The hook command manages a collection of hook bindings. A hook binding has four elements:

  1. A subject: the name of the entity that will be calling the hook.

  2. The hook itself. A hook usually reflects some occurrence in the life of the subject that other entities might care to know about. A hook has a name, and may also have arguments. Hook names are arbitrary strings. Each subject must document the names and arguments of the hooks it can call.

  3. The name of the observer that wishes to receive the hook from the subject.

  4. A command prefix to which the hook arguments will be appended when the binding is executed.

Subjects and observers

For convenience, this document collectively refers to subjects and observers as objects, while placing no requirements on how these objects are actually implemented. An object can be a TclOO or Snit or XOTcl object, a Tcl command, a namespace, a module, a pseudo-object managed by some other object (as tags are managed by the Tk text widget) or simply a well-known name.

Subject and observer names are arbitrary strings; however, as hook might be used at the package level, it's necessary to have conventions that avoid name collisions between packages written by different people.

Therefore, any subject or observer name used in core or package level code should look like a Tcl command name, and should be defined in a namespace owned by the package. Consider, for example, an ensemble command ::foo that creates a set of pseudo-objects and uses hook to send notifications. The pseudo-objects have names that are not commands and exist in their own namespace, rather like file handles do. To avoid name collisions with subjects defined by other packages, users of hook, these ::foo handles should have names like ::foo::1, ::foo::2, and so on.

Because object names are arbitrary strings, application code can use whatever additional conventions are dictated by the needs of the application.

Reference

Hook provides the following commands:

Example

The ::model module calls the hook in response to commands that change the model's data:

hook call ::model <Update>

The .view megawidget displays the model state, and needs to know about model updates. Consequently, it subscribes to the ::model's hook.

hook bind ::model <Update> .view [list .view ModelUpdate]

When the ::model calls the hook, the .views ModelUpdate subcommand will be called.

Later the .view megawidget is destroyed. In its destructor, it tells the hook that it no longer exists:

hook forget .view

All bindings involving .view are deleted.

Credits

Hook has been designed and implemented by William H. Duquette.

Bugs, Ideas, Feedback

This document, and the package it describes, will undoubtedly contain bugs and other problems. Please report such in the category hook of the Tcllib Trackers. Please also report any ideas for enhancements you may have for either package and/or documentation.

When proposing code changes, please provide unified diffs, i.e the output of diff -u.

Note further that attachments are strongly preferred over inlined patches. Attachments can be made by going to the Edit form of the ticket immediately after its creation, and then using the left-most button in the secondary navigation bar.

SEE ALSO

uevent(n)

KEYWORDS

callback, event, hook, observer, producer, publisher, subject, subscriber, uevent

CATEGORY

Programming tools

COPYRIGHT

Copyright © 2010, by William H. Duquette