txmbox - Tcl Xtreme Message Box


package require Tcl 8.4
package require Tk 8.4
package require BWidget 1.7
package require twapi 0.9 [ windows platforms ]
package require txmbox ?1.0?

::txmbox::messageBox ?option value ...?
::txmbox::addToMsgBox pathName text ?fg color? ?bg color?
::txmbox::changeMsgBoxButtonLabel pathName originalLabel newLabel
::txmbox::destroyMsgBox pathName
::txmbox::cleanMsgBox ?pathName?
::txmbox::detab text ?tab size? ?offset?
::txmbox::alignText text width ?left margin? ?nonewline? ?noindents?
::txmbox::pushGrabStack pathName ?global?
::txmbox::waitForClose pathName ?focus? ?pid? ?force?
::txmbox::posGeom pathName
::txmbox::configButton pathName
::txmbox::placeWindow pathName geometry
::txmbox::centerWindow pathName ?width? ?height?



txmbox is an attempt to provide a general purpose informational dialog tool to replace tk_messageBox. txmbox adheres to all the tk_messageBox options, improving on many of them. Also, txmbox adds so many additional features that you may never need to build another informational dialog box. txmbox is a psuedo widget. The only exception to compatibility with tk_messageBox; the default for -icon is to not display an icon.

Here's a list of most of the features included in this package:

txmbox Variables:

The following txmbox variables are available:

txmbox::TxMessageBox(Button.pathName) The label of the button pressed. Empty string if no button was pressed. Useful when -wait false. Where pathName is the pathName returned by ::txmbox::messageBox.
txmbox::TxMessageBox(ButtonPressed.pathName) Flag indicating whether or not a button was pressed.
txmbox::TxMessageBox(Geometry.pathName) If the window was repositioned by the user this variable contains the xy geometry of the dialog when the window closed else contains an empty string. Useful if you wish to save the user's preferred window placement.
txmbox::TxMessageBox(FontSize) Allows the message font size to be set for all Message Boxes which have no -font option. Basically allows a default font size to be set.
txmbox::TxMessageBox(LastName) The widget path of the last dialog box created.



::txmbox::messageBox ?option value ...?

The command was design to be a drop-in replacement for tk_messageBox right down the name of the command. Notice you need only replace the tk_ portion of your exsting tk_messageBox instances with txmbox::.

If -wait option is set to true (default) then function waits for user reponse and returns the button label of the button pressed. If -wait option is set to false then messageBox does not wait for user response and returns the pathName of the messageBox window. When the user presses a button the button label is placed in the variable txmbox::TxMessageBox(Button.pathName) and the messageBox closes.

The dialog adds a vertical scroll bar if the text height exceeds 25 lines. By default the width of the window is computed based on the widest line in the message up to a maximum of 100 chars. Lines longer than 100 chars are wrapped. So your dialogs will always fit on your screen!

There are dozens of features that could be added to this but for the sake of getting it out there I have not addressed those yet (but I will)! Please submit your requests to the email address below. I won't guarentee that I will add every suggested feature but if it makes sense and seems to have some general utility I most likely will.

Option Default value What it does

Specifies a global variable to hold the state of the "show again"checkbutton. Presents of this option indicates you wish to present this option to the user.

Valid values are: 0, 1, true, false, yes, no

-beep no sound

Gives an audible alert when dialog pops up.

Valid values are: 0, 1, true, false, yes, no


Calls the specified proc before creating the dialog. Proc name and parameters are accepted. I suggest you pass this in as follows:

-before {<proc name> <param 1> ... <param N>}


Specifies the name of a global variable where messageBox will create a list of eval type expressions that will allow the messageBox buttons to be executed programmatically. The list should be accessed in the following fashion:

eval [lindex $<var name> <button number>]

where button number starts at 0

For instance, if we specify -type yesnocancel then to press the cancel button the button number would be 2. Trying to press a button on a closed instance of messageBox does NOT throw an error.

-callback   Calls the specified procedure with the label of the button that was pressed.
-confirm false

Presents a confirmation window when the user clicks any button on the messageBox.

Valid values are: 0, 1, true, false, yes, no

-default first button in type Set the focus to the button specified by name. Button has green highlight if on UNIX platforms and not using Tile.
-font depends on platform

A fully qualified font specification to use on all textual aspects of the dialog, ie:

{"courier new"16 normal italic}

The font is used for all textual aspects of the dialog.

-force true

If true then forces the focus to the default button or the window if type "none" is specified.

Valid values are: 0, 1, true, false, yes, no

-format false

If format is true then the message will use the rules for the ::txmbox::alignText routine and they are:

The width used for formatting will be the value passed by the -width option OR, if that's not provided, the length of the longest line present in the message OR 100 which ever is less.

Because resizing the window could cause the text to become ugly and difficult to read the minsize for the window will be fixed to the calculated maximum width and height for the text window. This allows the window to be grown but not shrunk.

Valid values are: 0, 1, true, false, yes, no

-geom window will be placed
at the screen center
This option may be used as an alternative to specifying the xy, height, width options. The geometry mode will be set to full. The geometry variable will then report the full geometry for the window instead of just the xy position.
-grab false

Grabs the focus so the parent is unable to process any keys or buttons.

Valid values are: 0, 1, true, false, yes, no

-height calculated Force the height to this number of lines. If height is not specified then the window height will be set to the smaller of 25 lines or computed number of lines to display based on all other options provided. In this case, if the number of resulting lines is greater than 25 then a vertical scrollbar will be added.
-icon no icon

Name of the icon to use. If none specified then none will be displayed. -image will override this option if it occurs later in the arg list.

Valid icons are:

info, error, warning, question

-image no image A gif to place on the left side of the window.
-message blank message Message to be displayed in dialog.
-name   Passes the name of a global variable where messageBox will save the name of the messageBox toplevel window.
-notitle false

If this option is true then no window dressing will be applied to the popup. This is useful for "Please Wait" screens.

Valid values are: 0, 1, true, false, yes, no

-parent . Specifies the transient leader for this new dialog.
-resize true

If resize is true then the window can be resized by the user otherwise not.

Valid values are: 0, 1, true, false, yes, no

-showtime false

For timed windows, adds time remaining to titlebar of timed dialogs.

Valid values are: 0, 1, true, false, yes, no

-timeout 0

How long to wait before automatically closing window. 0 waits forever.

NOTE: Combining this option with the -confirm option is allowed but not recommended.

-title ATTENTION The text in the titlebar.
-type ok

Valid values are:

ok, okcancel, cancel, yesno, yesnocancel, abort, abortretrycancel, retrycancel, none, custom

If type is custom then a list of button names must be passed in using the -typebuttons option. The button name will appear on the buttons just as you have specified them. Currently only 1 row of buttons will be made. If large number of buttons is created this could force the window off the screen. A mechanism will be created in the future to deal with this.

-typebuttons   A list of custom button names. The return value is the button label (the value that you see on the button).
-wait true

Wait for the user to respond to the dialog then return the button label of the pressed button.

Valid values are: 0, 1, true, false, yes, no

-watch   Watch a pid and wait for it to terminate then close the dialog and return an empty string. If user presses a button then returns button label.
-wicon no icon Provide the absolute path to the xbm file that should be used for iconifed window. This is mainly for systems where the icon will be seen in a taskbar or icon window.
-width calculated Force the width to this number of characters. If width is not specified then the window width will be set to the smaller of 100 columns or computed number of columns to display based on all other options provided.

Specify the XY coordinates for the window.

Valid forms are: +X+Y, +X-Y, -X+Y, -X-Y


::txmbox::addToMsgBox pathName text ?fg color? ?bg color?

Provides a mechanism for adding text to an instance of ::txmbox::messageBox. The foreground and background color for the new text may also be given.


::txmbox::changeMsgBoxButtonLabel pathName originalLabel newLabel

Use this to change the text of any button label. You must always provide the original label when making changes. For instance, if the original label was Start and then the text was changed to Stop and then later it was changed back to Too Late. Each time the label was changed the original label (Start) was provided as the originalLabel parameter value.


::txmbox::destroyMsgBox pathName

It is recommended to use this routine when destroying a ::txmbox::messageBox because it records the dialog's final geometry in case you wish to retain the user's location preference.


::txmbox::cleanMsgBox ?pathName?

This routine reclaims memory space used by an instance of ::txmbox::messageBox. WIthout the optional pathName argument all memory space used by previously created ::txmbox::messageBox instances is cleared. If the optional pathName is given then only the space used by that instance is cleared. If an instance is still in existance then it's parameters will NOT be cleared.


::txmbox::detab text ?tab size? ?offset?

This is a general detab routine and can be called to detab any text. tab size is the width of a tab and offset is the amount of text to the left that has already been detabbed.


::txmbox::alignText text width ?left margin? ?nonewline? ?noindents?

This is a general purpose routine that aligns text to a specific width so it can later be displayed as a nicely formatted block of text. The following rules apply:

	text      - The text to be formatted
	width     - The width of the page
	lmargin   - The left edge of the text
	nonewline - Remove the last newline at the end of the formatted text
	noindents - Treat indents as regular text

1. Text that extends beyond the page width will wrap at the last space that occurs just before the page edge.

2. Any line that is not butting up against the left edge will be considered indented. The indent amount will be detected and any wrapping text will include this additional indent. The routine will attempt to handle things like indented bullets by detecting the number of chars from the start of the bullet to the start of the actual text for that bullet. All but the first line shall have an additional indent equal to the number of chars detected. If no bullet is detected the wrapped lines will align with the first line. The following initial chars (when followed by some white space) will constitute a bullet:

*, -, +, N., N)

where N is any number. Examples:

   * This is a bullet
   - So is this
   1. And this
   2) this one too

The user is expected to handle the left edge of the text. What is meant here is, if the user wants numbered bullets that are aligned around the "." then the user will need to adjust the indent accordingly, ie;

   1. First line is here. You can see that the
      wrapped part is in-line with the first
      char of the text.
  14. This might be the fourteenth line. Notice
      how both it's bullet and the text aligns
      with the previous line.

The first line above has an additional space before it in order for the periods in the numbers to sit in the same column.


::txmbox::pushGrabStack pathName ?global?

Creates a general purpose Grab Stack. Use to stack windows on top of each other and ensure they stay stacked.



Pops grabs off previously stacked windows.


::txmbox::waitForClose pathName ?focus? ?pid? ?force?

Grab the focus for pathName (or widget specified by option focus) and wait for the window to close. Make the window a transient of the one placed on the grab stack before it. Forces focus to pathName if force option is 1. Waits for pid to terminate is pid specified. Use this routine after creating a popup window to wait for the use to respond. It keeps the event loop running and allow the user's reponse t be recorded by your routine. See the code at the end of the ::txmbox::messageBox routine for an example of use.


::txmbox::posGeom pathName

Returns the XY coordinates of pathName in standard geometry format less the WxH, ie; +230+410


::txmbox::configButton pathName

Configures a BWidget Button with the look defined by the following variables:

The following variables are honored and are used to dress up none Tile buttons. You can also take advantage of these values for other buttons in your program but you must use BWidgets Button widget when creating your buttons. Once your buttons have been created make a call to to this routine and it will set all these parameters into the button. You must define these values before you call this routine.

txmbox::TxMessageBox(Button.fg) foreground color if not otherwise specified
txmbox::TxMessageBox( background color if not otherwise specified
txmbox::TxMessageBox(Button.relief) relief; default is normal button default
txmbox::TxMessageBox(Button.hlwidth) highlight width default is 0
txmbox::TxMessageBox(Button.activefg) foreground color when mouse if over button
txmbox::TxMessageBox(Button.activebg) background color when mouse if over button


::txmbox::placeWindow pathName geometry

A general purpose routine for placing a window in a specific location with a specific size.


::txmbox::centerWindow pathName ?width? ?height?

A general purpose routine for centering a window on the screen.


To create a message box that executes a proc before displaying the dialog, terminates the dialog in the event that the user does not within 30 seconds, shows the timeout time counting down in the titlebar, and waits for the user to respond do the following:

set response [ txmbox::messageBox -title     $titleString \
                                  -message   $messageString \
                                  -before    {beforeProc arg1 arg2} \
                                  -callback  {callbackProc} \
                                  -timeout   30 \
                                  -showtime  true \
                                  -type      yesnocancel \
                                  -wait      true ]

Click here to see the Change Log.






Copyright © Robert Joy <> Licensed under the BSD License.