# Wcb Command Reference

## For Wcb Version 3.7

### by

## Csaba Nemethi

## Contents

- The `wcb::callback` Command
- The `wcb::cbappend` Command
- The `wcb::cbprepend` Command
- The `wcb::cancel` Command
- The `wcb::canceled` Command
- The `wcb::extend` Command
- The `wcb::replace` Command
- The `wcb::pathname` Command
- The `wcb::changeEntryText` Command
- The `wcb::postInsertEntryLen` Command
- The `wcb::postInsertEntryText` Command
- The `wcb::postDeleteEntryText` Command
- Before-`insert` Callbacks for entry, spinbox, and combobox Widgets
- Before-`insert` Callbacks for text and ctext Widgets

Start page

## The `wcb::callback` Command

NAME
  `wcb::callback` – Retrieve, set, and remove widget callbacks
SYNOPSIS

      wcb::callback widgetName before|after option ?callback callback ...?

DESCRIPTION
  Retrieves, sets, or removes the callbacks for the Tk or tile entry, BWidget Entry, Tk or tile spinbox, tile combobox, listbox, tablelist, tile treeview, text, or ctext widget `widgetName`, the argument `before` or `after`, and the command corresponding to `option`. The values of the `option` argument can be:
  - `insert`, `delete`, or `motion`, for a Tk or tile entry, BWidget Entry, Tk or tile spinbox, tile combobox, text, or ctext widget;
  - `replace`, for a text or ctext widget;
  - `activate`, for a listbox, tablelist, or tile treeview widget;
  - `selset` or `selclear`, for a listbox, tablelist, tile treeview, text, or ctext widget;
  - `seladd` or `seltoggle`, for a tile treeview widget;
  - `activatecell`, `cellselset`, or `cellselclear`, for a tablelist widget.
  If no arguments after the `option` parameter are specified, then the procedure just returns the current before- or after-callback list, respectively, for the given widget operation.
  Otherwise:

  - If at least one of the arguments following the `option` parameter is a nonempty string, then:

    - if called for the first time for this widget with at least one nonempty argument following the `option` parameter, then the procedure renames the Tcl command `widgetName` to `_widgetName` and builds a new procedure `widgetName`, in which the execution of the widget operations associated with the above values of `option` is preceded by invocations of the corresponding before-callbacks and followed by calls to the corresponding after-callbacks, in the global scope;
    - it sets the callback list to the one built from these arguments and returns the new list.
  - If all arguments following the `option` parameter are empty, then the procedure unregisters all the corresponding before- or after-callbacks for the given widget and returns an empty string.
  When a callback is invoked, the name of the original Tcl command for the widget `widgetName` as well as the command arguments are automatically appended to it as parameters.
  The following table shows the widget subcommands corresponding to the above values of `option`, together with the arguments of these subcommands:

  Widget | `option` | Subcommand | Arguments
  --- | --- | --- | ---
  Tk entry, ttk::entry, BWidget Entry, Tk spinbox, ttk::spinbox, or ttk::combobox | `insert` | `insert` | `index string`
  `delete` | `delete` | `from ?to?`
  `motion` | `icursor` | `index`
  listbox | `activate` | `activate` | `index`
  `selset` | `selection set` | `first ?last?`
  `selclear` | `selection clear` | `first ?last?`
  tablelist::tablelist | `activate` | `activate` | `index`
  `selset` | `selection set` | `first ?last?`
  `selclear` | `selection clear` | `first ?last?`
  `activatecell` | `activatecell` | `cellIndex`
  `cellselset` | `cellselection set` | `first ?last?`
  `cellselclear` | `cellselection clear` | `first ?last?`
  ttk::treeview | `activate` | `focus` | `item`
  `selset` | `selection set` | `itemList`
  `seladd` | `selection add` | `itemList`
  `selclear` | `selection remove` | `itemList`
  `seltoggle` | `selection toggle` | `itemList`
  text or ctext | `insert` | `insert` | `index string ?tagList string tagList ...?`
  `delete` | `delete` | `from ?to?`
  `replace` | `replace` | `from to string ?tagList string tagList ...?`
  `motion` | `mark set insert` | `index`
  `selset` | `tag add sel` | `from ?to from to ...?`
  `selclear` | `tag remove sel` | `from ?to from to ...?`

  REMARKS:
  1. You may abbreviate the words `before`, `after`, `insert`, `delete`, `replace`, `motion`, and `activate` (the latter not for tablelist widgets) to a minimum of one character. Similarly, the first four characters of the words `selset`, `selclear`, `seladd`, and `seltoggle`, the first eight characters of `cellselset` and `cellselclear`, and the first nine characters of `activatecell` are sufficient for Wcb to recognize these options.
  2. After a successful invocation of this command with at least one nonempty callback following the `option` argument, you can use either the new procedure `widgetName` or the original Tcl command `_widgetName` to perform any valid operation on the widget `widgetName`. Use the old Tcl command `_widgetName` if you want to prevent the callbacks from being invoked when executing the respective widget subcommand.
  3. When destroying a widget `widgetName` for which `wcb::callback` has replaced the corresponding Tcl command with a new procedure, the original command `_widgetName` is deleted automatically by the Tcl interpreter (this is not true in the case of a BWidget Entry, tablelist, or ctext widget). The new widget procedure `widgetName` would persist, but Wcb arranges for it to be deleted from within a cleanup script bound to the `<Destroy>` event. This cleanup script is associated with a binding tag called `WcbCleanup`, which is appended to the list of binding tags of the widget the first time when registering some callbacks for it. (In the case of a BWidget Entry, tablelist, or ctext widget, this script also deletes the original Tcl command `_widgetName`.)
  4. The cleanup script mentioned above also unregisters all callbacks defined for `widgetName`, thus ensuring that a widget with the same path created later will not inherit them from the widget just deleted (this can be important in some applications). For this reason, you should be careful not to remove `WcbCleanup` from the list of binding tags of the given widget!
KEYWORDS
  callback, widget, Tk entry, tile entry, BWidget Entry, Tk spinbox, tile spinbox, tile combobox, listbox, tablelist, tile treeview, text, ctext

Contents Start page

## The `wcb::cbappend` Command

NAME
  `wcb::cbappend` – Append to a callback list
SYNOPSIS

      wcb::cbappend widgetName before|after option ?callback callback ...?

DESCRIPTION
  This command is almost identical to `wcb::callback`. The only difference is that `wcb::cbappend` appends the arguments specified after the `option` parameter to the current callback list (if present), while `wcb::callback` replaces the old callbacks with these arguments.
KEYWORDS
  callback, append, widget

Contents Start page

## The `wcb::cbprepend` Command

NAME
  `wcb::cbprepend` – Prepend to a callback list
SYNOPSIS

      wcb::cbprepend widgetName before|after option ?callback callback ...?

DESCRIPTION
  This command is almost identical to `wcb::callback`. The only difference is that `wcb::cbprepend` prepends the arguments specified after the `option` parameter to the current callback list (if present), while `wcb::callback` replaces the old callbacks with these arguments.
KEYWORDS
  callback, prepend, widget

Contents Start page

## The `wcb::cancel` Command

NAME
  `wcb::cancel` – Cancel a widget command
SYNOPSIS

      wcb::cancel ?script?

DESCRIPTION
  This procedure is designed to be invoked from a before-callback for a widget command. It cancels the execution of that command and of the remaining callbacks, and evaluates the `script` argument in the global scope. If this argument is not specified, it defaults to the `bell` command.
  The return value is the one obtained from `script` if this argument is specified and nonempty. Otherwise, the command returns an empty string.
KEYWORDS
  cancel, command, widget

Contents Start page

## The `wcb::canceled` Command

NAME
  `wcb::canceled` – Query the canceled status of a widget command
SYNOPSIS

      wcb::canceled widgetName option

DESCRIPTION
  Returns the value `1` if the most recent invocation of the widget operation corresponding to `widgetName` and `option` has been aborted by some before-callback by invoking `wcb::cancel`; otherwise, the return value is `0`. The arguments must fulfil the same restrictions as in the case of the `wcb::callback` command.
KEYWORDS
  cancel, command, widget

Contents Start page

## The `wcb::extend` Command

NAME
  `wcb::extend` – Extend the argument list of a widget command
SYNOPSIS

      wcb::extend ?arg arg ...?

DESCRIPTION
  This procedure is designed to be invoked from a before-callback for a widget command. It appends the values given in the optional `arg` parameters to the argument list of that command. The new argument list will be passed to the remaining callbacks for that command, too.
  This procedure simply passes its parameters to the `lappend` command, called for the argument list of the respective widget operation.
KEYWORDS
  extend, argument, command, widget

Contents Start page

## The `wcb::replace` Command

NAME
  `wcb::replace` – Replace arguments of a widget command with new ones
SYNOPSIS

      wcb::replace first last ?arg arg ...?

DESCRIPTION
  This procedure is designed to be invoked from a before-callback for a widget command. It replaces the arguments having the indices `first` through `last` of that command with the optional `arg` parameters. The new argument list will be passed to the remaining callbacks for that command, too. The arguments are numbered from `0` (see the table in the description of the `wcb::callback` command).
  This procedure simply passes its parameters to the `lreplace` command, called for the argument list of the respective widget operation.
KEYWORDS
  replace, argument, command, widget

Contents Start page

## The `wcb::pathname` Command

NAME
  `wcb::pathname` – Query the path name of the widget corresponding to a Tcl command name
SYNOPSIS

      wcb::pathname origCmd

DESCRIPTION
  This procedure returns the path name of the widget corresponding to the Tcl command name `origCmd` passed to a callback.
  When a before- or after-callback for a widget is invoked, the name of the original Tcl command associated with that widget is automatically appended to it as parameter. This procedure can be used within a callback to derive the path name of the widget from the command name passed to the callback as argument. It simply returns the string range obtained from `origCmd` by removing the `"::_"` prefix.
KEYWORDS
  path name, command, widget

Contents Start page

## The `wcb::changeEntryText` Command

NAME
  `wcb::changeEntryText` – Change the text of a Tk or tile entry, BWidget Entry, Tk or tile spinbox, or tile combobox widget
SYNOPSIS

      wcb::changeEntryText widgetName string

DESCRIPTION
  Replaces the text of the Tk or tile entry, BWidget Entry, Tk or tile spinbox, or tile combobox widget `widgetName` with `string`, by using the `delete` and `insert` operations. If the first subcommand is canceled by some before-`delete` callback then the procedure returns without inserting the new text; if the second operation is canceled by some before-`insert` callback then the command restores the original contents of the widget.
  The procedure keeps the position of the insertion cursor. The return value is `1` on success and `0` on failure, i.e., if one of the attempted operations was canceled by some before-callback.
KEYWORDS
  Tk entry, tile entry, BWidget Entry, Tk spinbox, tile spinbox, tile combobox, widget

Contents Start page

## The `wcb::postInsertEntryLen` Command

NAME
  `wcb::postInsertEntryLen` – Query the would-be length of the text in a Tk or tile entry, BWidget Entry, Tk or tile spinbox, or tile combobox widget after text insertion
SYNOPSIS

      wcb::postInsertEntryLen widgetName string

DESCRIPTION
  Returns the length of the text that would be contained in the Tk or tile entry, BWidget Entry, Tk or tile spinbox, or tile combobox widget `widgetName` after inserting `string`.
KEYWORDS
  insert, Tk entry, tile entry, BWidget Entry, Tk spinbox, tile spinbox, tile combobox, widget

Contents Start page

## The `wcb::postInsertEntryText` Command

NAME
  `wcb::postInsertEntryText` – Query the would-be text of a Tk or tile entry, BWidget Entry, Tk or tile spinbox, or tile combobox widget after text insertion
SYNOPSIS

      wcb::postInsertEntryText widgetName index string

DESCRIPTION
  Returns the text that would be contained in the Tk or tile entry, BWidget Entry, Tk or tile spinbox, or tile combobox widget `widgetName` after inserting `string` before the character indicated by `index`.
KEYWORDS
  insert, Tk entry, tile entry, BWidget Entry, Tk spinbox, tile spinbox, tile combobox, widget

Contents Start page

## The `wcb::postDeleteEntryText` Command

NAME
  `wcb::postDeleteEntryText` – Query the would-be text of a Tk or tile entry, BWidget Entry, Tk or tile spinbox, or tile combobox widget after text deletion
SYNOPSIS

      wcb::postDeleteEntryText widgetName from ?to?

DESCRIPTION
  Returns the text that would be contained in the Tk or tile entry, BWidget Entry, Tk or tile spinbox, or tile combobox widget `widgetName` after deleting the characters starting with the one indicated by the index `from` and stopping just before `to`. If `to` is not specified then the return value is the text that would be contained in the widget after deleting the single character given by `from`.
  REMARK: This command has a variable number (2 or 3) of arguments, because the `delete` subcommand of the Tcl command associated with `widgetName` expects either one or two indices as arguments. For this reason, the correct way to invoke this command from within a before-`delete` callback is as shown in the following example:

  >     proc myBeforeDeleteCallback {w args} {
  >         #
  >         # Get the text that would be contained in the widget after
  >         # deleting the characters specified by $args, which stands
  >         # for the one or two arguments passed to delete; pass these
  >         # arguments to wcb::postDeleteEntryText by expanding $args
  >         #
  >         set newText [eval [list wcb::postDeleteEntryText $w] $args]
  >         if {!some_condition_on_$newText} {
  >             wcb::cancel
  >         }
  >     }

  The following alternative, more elegant solution requires Tcl/Tk 8.5 or later:

  >     proc myBeforeDeleteCallback {w args} {
  >         # . . .
  >         set newText [wcb::postDeleteEntryText $w {*}$args]
  >         . . .
  >     }

KEYWORDS
  delete, Tk entry, tile entry, BWidget Entry, Tk spinbox, tile spinbox, tile combobox, widget

Contents Start page

## Before-`insert` Callbacks for entry, spinbox, and combobox Widgets

NAME
  `wcb::checkStrFor*`, `wcb::convStrTo*`, `wcb::checkEntryFor*`, `wcb::checkEntryLen` – Before-`insert` callbacks for Tk entry, tile entry, BWidget Entry, Tk spinbox, tile spinbox, and tile combobox widgets
SYNOPSIS

      wcb::checkStrForRegExp  exp w idx str

      wcb::checkStrForAlpha       w idx str
      wcb::checkStrForNum         w idx str
      wcb::checkStrForAlnum       w idx str

      wcb::convStrToUpper         w idx str
      wcb::convStrToLower         w idx str

      wcb::checkEntryForInt       w idx str
      wcb::checkEntryForUInt  max w idx str
      wcb::checkEntryForReal      w idx str
      wcb::checkEntryForFixed cnt w idx str

      wcb::checkEntryLen      len w idx str

DESCRIPTION
  The `wcb::checkStrForRegExp` callback checks whether the string `str` to be inserted into the Tk or tile entry, BWidget Entry, Tk or tile spinbox, or tile combobox widget `w` is matched by the regular expression `exp`; if not, it cancels the `insert` operation.
  The three other `wcb::checkStrFor*` callbacks check whether the string `str` to be inserted into the Tk or tile entry, BWidget Entry, Tk or tile spinbox, or tile combobox widget `w` is alphabetic, numeric, or alphanumeric, respectively; if not, they cancel the `insert` operation. These procedures just invoke the callback `wcb::checkStrForRegExp`, passing to it the Unicode-based patterns `{^[[:alpha:]]*$}`, `{^[[:digit:]]*$}`, and `{^[[:alnum:]]*$}` for Tk versions 8.1 or higher, and the ASCII patterns `{^[A-Za-z]*$}`, `{^[0-9]*$}`, and `{^[A-Za-z0-9]*$}` if Tk version 8.0 is being used.
  The `wcb::convStrTo*` callbacks replace the string `str` to be inserted into the Tk or tile entry, BWidget Entry, Tk or tile spinbox, or tile combobox widget `w` with its uppercase or lowercase equivalent, respectively.
  The `wcb::checkEntryFor*` callbacks check whether the text contained in the Tk or tile entry, BWidget Entry, Tk or tile spinbox, or tile combobox widget `w` after inserting the string `str` before the character indicated by the index `idx` would represent (the starting part of) an integer number, unsigned integer no greater than `max`, real number, or real number in fixed-point format with at most `cnt` digits after the decimal point, respectively; if not, they cancel the `insert` operation. `max` and `cnt` should be nonnegative numbers or `*`; `max = *` means: no upper bound for the Tk or tile entry, BWidget Entry, Tk or tile spinbox, or tile combobox value, while `cnt = *` stands for an unlimited number of digits after the decimal point.
  The `wcb::checkEntryLen` callback checks whether the length of the text contained in the Tk or tile entry, BWidget Entry, Tk or tile spinbox, or tile combobox widget `w` after inserting the string `str` would be greater than `len`; if yes, it cancels the `insert` operation.
  These callback procedures are implemented in the file `wcbEntry.tcl`, contained in the `scripts` directory. They return an empty string.
KEYWORDS
  callback, insert, Tk entry, tile entry, BWidget Entry, Tk spinbox, tile spinbox, tile combobox, widget

Contents Start page

## Before-`insert` Callbacks for text and ctext Widgets

NAME
  `wcb::checkStrsFor*`, `wcb::convStrsTo*` – Before-`insert` callbacks for text and ctext widgets
SYNOPSIS

      wcb::checkStrsForRegExp exp w idx args

      wcb::checkStrsForAlpha      w idx args
      wcb::checkStrsForNum        w idx args
      wcb::checkStrsForAlnum      w idx args

      wcb::convStrsToUpper        w idx args
      wcb::convStrsToLower        w idx args

DESCRIPTION
  The `wcb::checkStrsForRegExp` callback checks whether the strings to be inserted into the text or ctext widget `w`, contained in the list `args` of the form `string ?tagList string tagList ...?`, are matched by the regular expression `exp`; if not, it cancels the `insert` operation.
  The three other `wcb::checkStrsFor*` callbacks check whether the strings to be inserted into the text or ctext widget `w`, contained in the list `args` of the form `string ?tagList string tagList ...?`, are alphabetic, numeric, or alphanumeric, respectively; if not, they cancel the `insert` operation. These procedures just invoke the callback `wcb::checkStrsForRegExp`, passing to it the Unicode-based patterns `{^[[:alpha:]\n]*$}`, `{^[[:digit:]\n]*$}`, and `{^[[:alnum:]\n]*$}` for Tk versions 8.1 or higher, and the ASCII patterns `"^\[A-Za-z\n]*$"`, `"^\[0-9\n]*$"`, and `"^\[A-Za-z0-9\n]*$"` if Tk version 8.0 is being used (in this case, the presence of the `"\n"` makes the regular expressions a bit ugly).
  The `wcb::convStrsTo*` callbacks replace the strings to be inserted into the text or ctext widget `w`, contained in the list `args` of the form `string ?tagList string tagList ...?`, with their uppercase or lowercase equivalents, respectively.
  These callback procedures are implemented in the file `wcbText.tcl`, contained in the `scripts` directory. They return an empty string.
KEYWORDS
  callback, insert, text, ctext, widget

Contents Start page