txmbox - Tcl Xtreme Message Box

• SYNOPSIS
• DESCRIPTION
• COMMANDS
• EXAMPLES
• CHANGE HISTORY
• SEE ALSO
• KEYWORDS
• COPYRIGHT

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 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:

• Uses Tile widgets if the Tile package is already loaded so your dialogs will look like the rest of your interfaces.
• Keeps the event loop running. Doesn't hang your program.
• Dialogs can timeout after a predefined period AND you can optionally choose to show the remaining time in the dialog's title bar.
• Dialog buttons can be pressed programmatically.
• Dialog button labels can be changed after the dialog has been displayed.
• txmbox is written in Tcl so you can easily extend it's capability.
• Dialogs can be made to wait for the user to respond or not. If the dialog is instructed to wait then, after the user clicks a button, the button label of the pressed button is returned. If the dialog is instructed not to wait then the call to the dialog returns the dialog windows path, ie; .txmboxXYZ.
• The message widget is a text widget so it's text can easily be copied and pasted into other applications or emails. In fact, I'm looking at adding printing capability via a button 3 popup dialog. There's already a b3 popup that allows you to select all text and copy it to the cut buffer. Also, the text widget is disabled so the user can't mess with the message text.
• You can have multiple instances of  txmbox on the screen at one time.
• New text can be added dynamically to existing dialogs AND you can set the foreground and background colors as you add new text.
• Each dialog can be associated with a callback routine.
• You may specify the complete geometry of the dialog or just it's size or position.
• The dialog's position can be queried and saved so it can be repositioned according to the user's desire the next time it's presented.
• Includes a built-in "Don't show this dialog again" function.
• Includes an optional text formatting function.
• Can wait for a known process ID to terminate.
• Can be displayed without a titlebar.
• Dialogs can be resized.
• Can have a confirm sub-dialog. You know the old "Are you sure you want to do this?" Bill Gates really likes these.
• Add an image or icon to the left side of the message. Uses the standard bitmap icons available in Tcl or you can supply your own images.
• Can make a sound when dialog pops up.
• Can be centered or otherwise positioned.
• Can have custom button names OR use predefined button sets.
• Dialog's information is retained after dialog is closed so it can be processed post dialog. Used memory can be recovered via the cleanMsgBox command.
• Cross platform compliant. Works on Windows, Linux, and UNIX. It hasn't been tested on a Mac platform so I have no idea whether it will work there but I sure would like to get some feedback.
• Extensive error checking.
• The package also includes some useful routines that can be accessed separately from the messageBox.

txmbox Variables:

The following txmbox variables are available:

::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.

::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.

 

::txmbox::popGrabStack

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(Button.bg)	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.

tk_messageBox

Dialog

Copyright © Robert Joy <robert@doveware.com> Licensed under the BSD License.