[ Main Table Of Contents | Table Of Contents | Keyword Index | Categories | Modules | Applications ]
NAME
widgetPlus - Enhanced Entry, Spinbox, and Combobox Widgets with Undo/Redo and other useful features
Table Of Contents
SYNOPSIS
package require Tcl 8.5
package require Tk 8.5
package require snit
package require widgetPlus ?1.0?
widgetPlus::entryPlus ?create? pathName
widgetPlus::spinboxPlus ?create? pathName
widgetPlus::ttkEntryPlus ?create? pathName
widgetPlus::ttkSpinboxPlus ?create? pathName
widgetPlus::ttkComboboxPlus ?create? pathName
widgetPlus::EnableBWidget
pathName edit ?arg arg ...?
pathName edit canredo
pathName edit canundo
pathName edit modified ?boolean?
pathName edit redo
pathName edit reset
pathName edit separator
pathName edit undo
DESCRIPTION
The widgetPlus package adds new features to the widgets _entry_, _spinbox_, _ttk::entry_, _ttk::spinbox_, and _ttk::combobox_.
The new features are Undo and Redo operations, a <
The revised _entry_, _spinbox_, _ttk::entry_, _ttk::spinbox_, and _ttk::combobox_ widgets are created by the commands widgetPlus::entryPlus, widgetPlus::spinboxPlus, widgetPlus::ttkEntryPlus, widgetPlus::ttkSpinboxPlus, and widgetPlus::ttkComboboxPlus respectively.
For example, the widgetPlus::entryPlus widget is implemented as a Snit snit::widgetadaptor that wraps a Tk _entry_ widget. Its winfo class is Entry, and it uses a binding tag EntryPlus that replaces the Entry binding tag. The other widgets are implemented in a similar way.
The package uses the namespace ::widgetPlus, which exports (only) the five commands defined below that begin with a lower-case letter (EnableBWidget is not exported). These commands can be imported into the global namespace, and for simplicity, descriptive text in this manual will henceforth omit the namespace qualifier.
namespace import ::widgetPlus::*
WIDGET OPTIONS
In addition to the usual options of the _entry_, _spinbox_, _ttk::entry_, _ttk::spinbox_, and _ttk::combobox_ widgets, the wrappers _entryPlus_, _spinboxPlus_, _ttkEntryPlus_, _ttkSpinboxPlus_, and _ttkComboboxPlus_ provide the options below.
Command-Line Switch: _-inactiveselectbackground_
Database Name: inactiveSelectBackground
Database Class: ForegroundSpecifies the color to use for the selection when the window does not have the input focus. If empty, {}, then no selection is shown when the window does not have the focus. The -inactiveselectbackground option has no effect on the Ttk (themed) widgets _ttkEntryPlus_, _ttkSpinboxPlus_, and _ttkComboboxPlus_.
Command-Line Switch: _-maxundo_
Database Name: maxUndo
Database Class: MaxUndoSpecifies the maximum number of compound undo actions on the undo stack. A zero or a negative value imply an unlimited undo stack.
Command-Line Switch: _-undo_
Database Name: undo
Database Class: UndoSpecifies a boolean that says whether the undo mechanism is active or not.
COMMANDS
widgetPlus::entryPlus ?create? pathName
Create an _entryPlus_ widget; or convert an existing entry widget into an _entryPlus_.
widgetPlus::spinboxPlus ?create? pathName
Create a _spinboxPlus_ widget; or convert an existing spinbox widget into a _spinboxPlus_.
widgetPlus::ttkEntryPlus ?create? pathName
Create a _ttkEntryPlus_ widget; or convert an existing ttk::entry widget into a _ttkEntryPlus_.
widgetPlus::ttkSpinboxPlus ?create? pathName
Create a _ttkSpinboxPlus_ widget; or convert an existing ttk::spinbox widget into a _ttkSpinboxPlus_.
widgetPlus::ttkComboboxPlus ?create? pathName
Create a _ttkComboboxPlus_ widget; or convert an existing ttk::combobox widget into a _ttkComboboxPlus_.
-
Enable widgetPlus to modify BWidget _Entry_ widgets and their compounds (such as the BWidget _ComboBox_). The command creates a bindtag BwEntryPlus to replace the default bindtag BwEntry. This operation is not performed when the package is loaded because it requires BWidget to be loaded first. This command is not exported from namespace ::widgetPlus.
WIDGET COMMANDS
In addition to the usual commands of the _entry_, _spinbox_, _ttk::entry_, _ttk::spinbox_, and _ttk::combobox_ widgets, the wrappers _entryPlus_, _ttkEntryPlus_, _spinboxPlus_, _ttkSpinboxPlus_, and _ttkComboboxPlus_ provide:
-
This command controls the undo mechanism and the modified flag. The exact behavior of the command depends on the option argument that follows the edit argument. The following forms of the command are currently supported:
-
Returns a boolean true if redo is possible, i.e. when the redo stack is not empty. Otherwise returns false.
-
Returns a boolean true if undo is possible, i.e. when the undo stack is not empty. Otherwise returns false.
pathName edit modified ?boolean?
If boolean is not specified, returns the modified flag of the widget. The insert, delete, edit undo and edit redo commands, or (by using this command) the user, can set or clear the modified flag. If boolean is specified, sets the modified flag of the widget to boolean.
-
When the -undo option is true, reapplies the last undone edits provided no other edits were done since then. Generates an error when the redo stack is empty. Does nothing when the -undo option is false.
-
Clears the undo stack and redo stack.
-
Included for completeness, but has no effect.
(N.B. An implicit separator is added to the undo stack for each call to a widget command (e.g. insert or delete) that changes the widget contents. These therefore separate the addition or removal of individual characters by typing, except that cut or paste operations are discrete.)
-
Undoes the last edit action when the -undo option is true. An edit action is defined as a single insert or delete command that is recorded on the undo stack. Generates an error when the undo stack is empty. Does nothing when the -undo option is false.
BINDINGS
Class Bindings
The class binding tag for different widgets has these default values:
_entry_ uses Entry
_spinbox_ uses Spinbox
_ttk::entry_ uses TEntry
_ttk::spinbox_ uses TSpinbox
_ttk::combobox_ uses TCombobox
_entryPlus_ uses EntryPlus
_spinboxPlus_ uses SpinboxPlus
_ttkEntryPlus_ uses TEntryPlus
_ttkSpinboxPlus_ uses TSpinboxPlus
_ttkComboboxPlus_ uses TComboboxPlus
Undo and Redo
The <
On X11 systems (Linux®, BSD®, Solaris®, etc):
- <
> is mapped to
- <
> is mapped to
- <
On Windows® systems:
- <
> is mapped to
- <
> is mapped to
- <
On Aqua® systems (i.e. Apple® macOS® or OS X®):
- <
> is mapped to
- <
> is mapped to
- <
EntryPlus
The EntryPlus bindings are based on those of the Entry bindtag, with these changes:
New bindings to <
> and <> .An adjustment to the <
> binding, so that it behaves the same way on X11 as on other windowing systems (i.e. it deletes the existing selection, if any exists).The removal of the antiquated
binding. New bindings to
and , to facilitate the implementation of the -inactiveselectbackground option.
SpinboxPlus
The SpinboxPlus bindings are based on those of the Spinbox bindtag, with the same changes as are made when converting Entry to EntryPlus.
TEntryPlus
The TEntryPlus bindings are based on those of the TEntry bindtag, with these changes:
- New bindings to <
> and <> .
TSpinboxPlus
The TSpinboxPlus bindings are based on those of the TSpinbox bindtag, with these changes:
- New bindings to <
> and <> .
TComboboxPlus
The TComboboxPlus bindings are based on those of the TCombobox bindtag, with these changes:
- New bindings to <
> and <> .
VIRTUAL EVENT <>
Each widgetPlus widget generates a virtual event <
USE WITH MEGAWIDGETS
When an _entry_, _spinbox_, _ttk::entry_, _ttk::spinbox_, or _ttk::combobox_ is a component of a megawidget, it is often possible to apply widgetPlus to that component without modifying the megawidget code.
combobox (by Bryan Oakley)
A _combobox_ with path $w includes an _entry_ widget $w.entry, which uses the Entry binding tag. Thus widgetPlus can be applied to the _combobox_ after creation, using the command (see EXAMPLES)
entryPlus $w.entry -undo 1 -maxundo 0
ComboBox (BWidget)
A BWidget ComboBox with path $w includes an _entry_ widget $w.e, which uses the BwEntry binding tag in place of the default tag Entry.
Package widgetPlus provides a replacement bindtag BwEntryPlus, but this is not computed when the package is loaded because it requires BWidget to be loaded first. The command ::widgetPlus::EnableBWidget must be called to provide BwEntryPlus, and then the BWidget ComboBox can be modified (see EXAMPLES)
::widgetPlus::EnableBWidget
entryPlus $w.e -undo 1 -maxundo 0
TO DO
Undo and Redo do not sync the value of the modified flag - they always set the value to boolean true.
Undo and Redo do not sync the position of the insertion cursor.
The <
> event is not generated.Undo/Redo separators, and the -autoseparators option, as found in the _text_ widget, are not implemented. An implicit separator is added for each call to a widget command (e.g. insert or delete) that changes the widget contents. The edit separator command has no effect. Separator functionality would be less useful for widgets such as _entryPlus_ than it is for a _text_ widget.
Add an overwrite mode, toggled by
on non-macOS® systems.
BUGS
This version of widgetPlus is intended to be compatible with all releases of Tk 8.5 and 8.6, and with the branches core-8-5-branch, core-8-6-branch, and trunk in the source code repository for Tk. Any incompatibility with any of these versions, for any Tk windowing system, should be reported as a bug. Please report such in the category widgetPlus of the Tklib Trackers.
EXAMPLES
To create and map an _entryPlus_ widget .ep with an unlimited Undo/Redo stack:
package require widgetPlus
widgetPlus::entryPlus .ep -undo 1 -maxundo 0
pack .ep
The same but using namespace import:
package require widgetPlus
namespace import widgetPlus::*
entryPlus .ep -undo 1 -maxundo 0
pack .ep
To convert an existing _entry_ widget .ee into an _entryPlus_ with an unlimited Undo/Redo stack:
entry .ee
.
.
.
package require widgetPlus
widgetPlus::entryPlus .ee -undo 1 -maxundo 0
The same but using namespace import:
entry .ee
.
.
.
package require widgetPlus
namespace import widgetPlus::*
entryPlus .ee -undo 1 -maxundo 0
Apply widgetPlus to a Bryan Oakley _combobox_:
package require combobox
combobox::combobox .cb
.
.
.
package require widgetPlus
namespace import widgetPlus::*
entryPlus .cb.entry -undo 1 -maxundo 0
Apply widgetPlus to a BWidget _ComboBox_. The command ::widgetPlus::EnableBWidget must be called first.
package require BWidget
ComboBox .cb
.
.
.
package require widgetPlus
::widgetPlus::EnableBWidget
namespace import widgetPlus::*
entryPlus .cb.e -undo 1 -maxundo 0
Bugs, Ideas, Feedback
This document, and the package it describes, will undoubtedly contain bugs and other problems. Please report such in the category widgetPlus of the Tklib Trackers. Please also report any ideas for enhancements you may have for either package and/or documentation.
SEE ALSO
BWidget, ComboBox, Entry, entry, persistentSelection, spinbox, text, ttk::combobox, ttk::entry, ttk::spinbox