Itcl Dialog Box Widget

The dialog widget class encapsulates a top-level widget and the widget's interaction with the window manager, Tk's grab mechanism and the keyboard traversal system. Options normally set through Tk's wm command can be specified using widget-configuration options. Dialog widgets can be centered relative to the screen or another top-level widget.

Synopsis

dialog pathName ?options?
create a new dialog box widget named pathName.
pathName option ?args...?
manipulate the dialog box widget named pathName.

Options

Name: background
Class: Background
Command-Line Switch: -background
Default: #ccc
Specifies the background colour of the widget.

Name: relief
Class: Relief
Command-Line Switch: -relief
Default: flat
Specifies the appearance of the widget's three-dimensional border. This option can take any of the values accepted by Tk_GetRelief(3).

Name: borderWidth
Class: BorderWidth
Command-Line Switch: -borderwidth
Default: 0
Specifies the width of the widget's three-dimensional border in screen units.

Name: transientFor
Class: TransientFor
Command-Line Switch: -transient
Default: ""
The window for which the dialog box is a transient-window. If set to the empty string (the default), the dialog box is not transient. Most window managers treat transient windows differently to normal top-level windows; for instance, they may always float above the window they are transient for, and the user may not be able to iconify them.

Name: grabMode
Class: GrabMode
Command-Line Switch: -grab
Default: none
The way in which the dialog box grabs the mouse events and keyboard focus. If set to local, the dialog box performs a local grab, affecting only the other windows of the same application. If set to global, the dialog box performs a global grab, stopping mouse and keyboard events from being sent to any other windows in the display. If set to none (the default), the dialog box does not perform any grab.

Name: title
Class: Title
Command-Line Switch: -title
Default: Dialog
The text to be displayed in the title-bar of the dialog box. Note, however, that configuration options such as transientFor may cause some window managers not to display a title for the dialog box's main window.

Name: x
Class: X
Command-Line Switch: -x
Default: ""
The x coordinate of the top-left hand corner of the dialog box, in root-window coordinates. If this is set to the empty string (the default), the positioning of the dialog box is left to the window manager.

Name: y
Class: Y
Command-Line Switch: -y
Default: ""
The y coordinate of the top-left hand corner of the dialog box, in root-window coordinates. If this is set to the empty string (the default), the positioning of the dialog box is left to the window manager.

Name: state
Class: State
Command-Line Switch: -state
Default: normal
If set to withdrawn, the dialog box is removed from the display. If set to iconic, the dialog box is iconified. If set to normal, the dialog box is displayed normally (ie: it is mapped if it was previously withdrawn and deiconified if it was previously iconified).

Widget Command

pathName configure ?options...?
Configure the widget.

pathName center ?window?
Center the dialog relative to the given window. If no window is given, the dialog is centered relative to the root window.

Subclassing from the Dialog class

By subclassing from the Dialog class, one can build top-level widgets which are automatically tied in to the keyboard traversal mechanism provided by tabgroup widgets.

By default, dialog widgets are created with the default widget class-name "Dialog". As with Tk's toplevel widgets, this class name can be overridden by the -class command-line option. However, when subclassing from the dialog class, one normally wants the default class-name to be specific to the new subclass. One could achieve this by calling the dialog constructor with the -class option, but this would stop classes further derived from the subclass from specifying their own class-names. Therefore, the dialog class provides the method:

dialog::override_class class
which will set the class name to a new value unless it has already been changed by a constructor lower down in the inheritance hierarchy. This method should be called at the top of the constructor before calling the constructor of the superclass. For instance:

itcl_class newdialog {
   inherit dialog
   
   ...
   
   constructor {config} {
      set class NewDialog
      dialog::constructor
      ...
   }
   
   ...
}


Nat Pryce (np2@doc.ic.ac.uk)