Updated 2016-02-13 16:15:04 by escargo

I hate badly documented features I want to use. I like a good challenge, but 'badly documented' is obviously not good...

Any comments in "..." are straight from the dialog widget's source, dialog.tcl

widget::dialog

widget::dialog $path ?options?

-command "Gets appended: $win $reason" $reason is the value returned by the button which was clicked default value {}

-focus "Subwindow to set focus on display" default value: {}

-modal Blocking access to other windows while dialog is displayed default value: none

none: all windows accessible. Triggering the dialog again may lead to an error message local: window(s?) of the program that triggered the dialog are not accessible global: no window on screen is accessible unless the dialog is closed

-padding This option is delegated to a ttk::frame and should therefore show the same behaviour as the underlying widget. default value: 0

-parent Specifies the name of the parent widget default value: ""

-place default value: center Specifies the place in which the dialog window appears.

none: Ends up centered near the top of the windows. Title of the dialog window is within the title of the initial window, just a bit lower. (On my system. This behaviour might be intended by the author, but it might as well just be how my system handles it) left: On the left of the window. Title of the dialog window begins where title of the initial window ends. right: On the right of the window. Vertical alignment same as 'left' center: Dialog window appears in the middle of the screen over: Appears over the widget that triggered the dialog window. above: Dialog window appears centered and towards the top of the window. Bottom of the dialog goes in about at the top of the initial window and is never fully outside the initial window. below: Dialog window appears centered and below the initial window. If there is no space left under the initial window, the dialog window moves into the initial window. pointer: Top center of the dialog window appears right at the current position of the pointer.

-separator Horizontal ruler that separates the buttonfield from the rest of the dialog window default value: 1 (bool)

-synchronous Except for the hints in the source I have no clue and even that leaves me completely puzzled. There's something about custom buttons in the dialog and "A synchronous dialog will always withdraw" seems to be the most understandable statement from the comments. Absolutely no idea here. default value: 1 (bool, I guess)

-title Title of the dialog window default value: " "

-transient Specifies whether or not the dialog window can be minimized or maximized or rather whether the icons are displayed in the title bar. default value: 1 (bool, I guess)

-type Specify the buttons displayed. Create your own buttons with 'custom' or choose from 'ok', 'okcancel' and 'okcancelapply'. Functionality of these three buttons should be pretty self-explanatory default value: custom other values: ok okcancel okcancelapply

-timeout Only active with -synchronous. Behaviour unknow. It would probably help to have an idea about the type of the value. Is it supposed to be a boolean value or does it mean 'timeout in milliseconds' or something else? default value: 0

Methods:

add $path add $what $args... => $id

getframe $path getframe => $frame returns name of the frame

setwidget $path setwidget $widget => ""

display $path display

cancel $path cancel

withdraw $path withdraw

# getframe and setwidget are somewhat mutually exclusive. # Use one or the other.

Bindings:

Escape (ESC-Key) WM_DELETE_WINDOW

both invoke [$dlg close cancel]

Usage example:

1) Write a proc that defines the dialog similar to the example take from dialog.tcl below
package require widget::dialog ;# or widget::all
proc showDialog {} {
set dlg [widget::dialog .pkgerr -modal local -separator 1 -place right\
-parent . -type okcancel -title "DialogTitle"]
[...]
puts [$dlg display]
destroy $dlg
}

2) Invoke proc when you want the dialog to appear 3) Any further information you want to provide with the dialog goes basically where I put ...
set frame [frame $dlg.f]
label $frame.lbl -text "Type Something In:"
grid $frame.lbl $frame.ent -sticky ew
$dlg setwidget $frame

Again taken from dialog.tcl and condensed to the basics. You can put any further information into the frame widget as demonstrated with the label widget.