# 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 generalized to other sorts of yesorno questions.

This document describes jconfirm.tcl version 2001.02.10.

## 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@aq.org`
`http://www.aq.org/~js/`

### Copyright

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

## Overview

### Procedure

`::jstools::confirm` - present a Cancel/OK dialogue box

## ::jstools::confirm

### Usage

`::jstools::confirm` [options]

### Options

`-title` title`` (default `Confirm`)
`-text` text`` (default `Are you sure?`)
`-priority` priority`` (default `0`)
`-yesbutton` ok`` (default `OK`)
`-nobutton` cancel`` (default `Cancel`)``

### Examples

`if [::jstools::confirm \
-text "Are you sure you want to quit?"] {
exit 0
}
if [::jstools::confirm \
-priority 100 \
-text "Really create a new filesystem on $dev?"] {
exec mkfs $dev
}`

### Note

In previous versions of the library, the arguments to all the options (except for `-priority`) were automatically localized. That's no longer the case.

### 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 nonzero priority. (Depending on the question, you may also want to specify nondefault 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 panel is 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.)

`
`