Title

jconfirm.tcl

Introduction

The jconfirm.tcl library is distributed as part of the jstools package. It consists of a single procedure which provides a panel designed to ask the user to confirm an action, but which can be generalised to other sorts of yes­or­no questions.

This document describes jconfirm.tcl version 4.0/4.0.

Usage

Accessing the Library

In order to use the jconfirm.tcl library, it (and any other libraries it depends on) must be in your Tcl auto_path, described in tclvars(n). Information about how to arrange that, and other conventions common to the jstools libraries, is in the Usage section of The jstools Libraries.

Credits and Copyright

Author

Jay Sekora

js@calumet.org

http://shore.net/~js/

Copyright

The library is copyright © 1992-1995 by Jay Sekora, but may be freely redistributed under the conditions at the top of the file.

Overview

Procedure

j:confirm - present a Cancel/OK dialogue box

j:confirm

Usage

j:confirm [options]

Options

-title title (localisable, default Confirm)

-text text (localisable, default Are you sure?)

-priority priority (default 0)

-yesbutton ok (localisable, default OK)

-nobutton cancel (localisable, default Cancel)

Examples

if [j:confirm -text "Are you sure you want to quit?"] {

exit 0

}

if [j:confirm \

-priority 100 \

-text "Really create a new filesystem on $dev?"] {

exec mkfs $dev

}

Description

This procedure lets you ask yes/no questions. It creates a dialogue box with the message text and two buttons labelled ok and cancel. It returns 1 (true) if the user clicks the button marked ok, and 0 (false) if the user clicks the button marked cancel. Thus it can conveniently be used in if statements.

The -priority option and the global variable J_PREFS(confirm) interact to determine whether the panel will be displayed at all. If J_PREFS(confirm) is false, and priority is 0 (the default), the procedure will return 1 immediately, without displaying the panel. You should leave priority 0 when you simply want to confirm an action the user has requested. In combination with the jstools preferences mechanism and j:global_pref_panel, this lets experienced or adventuresome users turn off such confirmation. When you have a question that represents a real choice, rather than just a confirmation - or you really, really want to make sure the user confirms the action - you should specify a non­zero priority. (Depending on the question, you may also want to specify non­default labels for the buttons.) In the future, I expect to let users choose a threshold priority value between 1 and 100 to determine whether a particular confirmation panel is displayed, so you should use 100 for any confirmation panel that absolutely must be displayed.

If title is specified, it will be the title of the panel, for use by the window manager.

Bugs and Limitations

The priority mechanism is insufficiently general.

There are lots of cases where it makes sense to guard in some way against stray mouse clicks or accidental keypresses, but where bringing up a new toplevel panelis overkill.

Future Directions

The user should be able to specify how important a confirmation panel needs to be in order actually to be displayed. (Perhaps there should be several scales - for instance, one for how dangerous an action is, one for how unusual an action is, etc.)