vtoolkit.note - VToolkit overview document ******************************************************************************* * VToolkit (1995) "If it doesn't use VToolkit, it isn't cool!" * * (c) Steve Klein * * Unpublished rights reserved under the copyright laws of the United States. * ******************************************************************************* This document contains an overview of the VToolkit. +----------------------+ | Modification History | +----------------------+ 9-Sep-1993 (sjk) VToolkit V2. 31-Aug-1990 (sjk) Add SimpleTestVList sample program. 15-May-1990 (sjk) Add VColorizer sample program. 10-Apr-1990 (sjk) Add MOTIF support for the VHist widget. Add the VCountdown sample program in both XUI and MOTIF flavors. Add MOTIF support for the VDiskQuota sample program Add the vtkutil.c module containing common convenience routines. 09-Apr-1990 (sjk) Add support for the new VHistOrientationBestFit in the VHist widget. This option allows the widget to select the best orientation (vertical or horizontal) based on the widgets actual run-time size. 05-Apr-1990 (sjk) Add MOTIF support for the VFake widget, VDrag and VDragRoot. 03-Apr-1990 (sjk) Initial entry. The "V" Toolkit is a collection of widgets, sample programs and utility routines that extend the XUI and MOTIF X toolkits. The VToolkit includes the following components: Widgets: VList - list widget VHist - histogram widget VFake - pseudo widget TList - scrolling message widget VFrame - (for VList) container widget VHeader - (for VList) column header label widget Utility Routines: VDrag - enable draggable windows VAutoRepeat - enable auto-repeating pushbutton widgets VtkUtil - common convenience routines Sample Programs: VDragRoot - draggable windows anywhere on screen VDiskQuota - (VMS only) disk quota display program BTrap - (VMS only) broadcast message display program VCountdown - countdown-style work in progress window VColorizer - colorize any window on the screen TestVDrag - test VDrag utility routines TestVList - test VList widget TestVHist - test VHist widget TestTList - test TList widget SimpleTestVList - simplified VList test program To build all the VToolkit components on a VMS system, do "@vbuildall". This compiles all modules and link the following executable programs. btrap.exe simpletestvlist.exe testtlist.exe testvdrag.exe testvhist.exe testvlist.exe vcolorizer.exe vcountdown.exe vdiskquota.exe vdragroot.exe A note about availability and restrictions ------------------------------------------ The VToolkit is not formally supported by DIGITAL or by the author. It is truly a "midnight project" born out of need and opportunity. Using quick iteration and a pragmatic development strategy, these components were written and refined to meet specific needs of real applications. The code is available in source form to anyone who might find it useful. Since this work is not formally funded and may be terminated at any time, you must accept ultimate responsibility for the support and enhancement of any code you use. Warnings aside, I do hope to continue working on the VToolkit. Continuous updates have been made available, and the number of distributed copies is growing. [VList widget] The VList widget can be used to display dynamic, interactive lists to the user. The user can select, drag, and otherwise manipulate the entries. The application can change the list dynamically and efficiently. At one extreme, the VList serves as a flexible, interactive widget that can display real-time numeric and graphic data. At the other extreme, it can present a simple set of options to the user in a typical list-box format. The sample program VDiskQuota uses the VList widget, as do the test programs TestVList and SimpleTestVList. Documentation Module: vlist.note Widget Modules: vlist.c vheader.c vframe.c vlist.h vheader.h vframe.h vlist.uil vheader.uil vframe.uil Test Program Modules: testvlist.c testvlist.uil simpletestvlist.c simpletestvlist.uil [VHist Widget] The VHist widget can be used to display numeric data in a real-time, bar chart (histogram) format. A number of resources allow you to customize the VHist widget display to your needs, including vertical or horizontal orientation, grid lines and labels. The VHist widget only repaints the minimally necessary portions of the window as bar values and labels change. It is designed to be updated by the application as often as 10 times a second to give the impression of smoothly animated changes. The test program TestVHist uses the VHist widget. Documentation Module: vhist.note Widget Modules: vhist.c vhist.h vhist.uil Test Program Modules: testvhist testvhist.uil [VFake Widget] The VFake widget is a special class of widget that allows one application to cleanly access windows that were created by another application. By using the VFake widget, you can continue to use XtMainLoop (and similar routines) to dispatch all events, even if your application did not create all the windows it deals with. Other solutions to the problem of accessing windows external to the application usually rely on writing a private version of XtMainLoop that has special filtering and dispatching logic for windows on a "hit" list. The VFake widget is a convenient way to register an external window with the toolkit intrinsics so that event handlers and actions can be registered on that window by using the normal intrinsics calls, such as XtAddEventHandler, etc. The sample program VDragRoot uses the VFake widget to access the workstation's root window, enabling draggable windows in all running applications. Documentation Module: vfake.note Widget Modules: vfake.c vfake.h vfake.uil [TList Widget] The TList widget is a specialized, easy-to-use widget designed to handle a dynamic, scrolling message list with a fixed length history. The TList widget supports messages in different colors and fonts. If a message is too wide for the widget's window, it will word-wrap. The user can scroll the contents of the list either by using the scroll-bar or by grabbing the list (with the mouse button) and dragging the pointer outside (above or below) the window. While the list is grabbed, the widget automatically saves any updates to be posted when the mouse button is finally released. The sample program BTrap uses the TList widget, as does the test program TestTList. Documentation Module: tlist.note Widget Modules: tlist.c tlist.h tlist.uil Test Program Modules: testtlist.c testtlist.uil [VDrag Utility Routine] The VDrag utility routine can be used to augment a widget's behavior, making it "draggable". Simply by calling the VDragEnable routine for a shell, dialog box (or any other) widget, movable widgets can be implemented in any application. Applications can use this as a starting point to implement a construction-set model, where objects (pushbuttons, labels, etc) can be picked up, dragged, and dropped by the user. The sample program VDragRoot uses the VDrag utility routine, as does the test program TestVDrag. Documentation Module: vdrag.note Utility Module: vdrag.c Test Program Module: testvdrag.c [VAutoRepeat Utility Routine] The VAutoRepeat utility routine can be used to augment a push-button widget or gadget, giving it auto-repeat behavior. This feature is transparent to the application. An auto-repeating push-button behaves exactly as though the user was quickly clicking it, with the push-button's activate callback being called for each click. To the user holding down an auto-repeating push-button, there is an initial delay, after which the push-button continues to trigger at an increasing rate until some maximum speed has been reached. Auto-repeat can be enabled in UIL or by application code. The test program TestVList uses the VAutoRepeat utility routine. Utility Modules: vautorepeat.c vautorepeat.uil Test Program Modules: testvlist.c testvlist.uil [VDiskQuota Sample Program] The VDiskQuota sample program uses the VList widget to display a colored, sorted list of disk usage based on the VMS disk quota information. This program needs (VMS) privileges to access the quota information. Enable BYPASS or SYSPRV before running this program. Other privileges may also work. If there are not enough privileges enabled, no information will be displayed in the output window. This program also shows how to save customization settings in an application-specific resource file and can serve as a starting point for similar applications. Program Modules: vdiskquota.c vdiskquota.uil [BTrap Sample Program] The BTrap sample program uses the TList widget to display VMS broadcast messages in a scrolling window. This program also shows how to use VMS ASTs with the X toolkit. Since the toolkit is not callable from AST level, XtAddInput must be used to merge completion AST events into the X toolkit's event stream. Program Modules: btrap.c btrap.uil [VDragRoot Sample Program] The VDragRoot sample program uses the VFake widget and the VDrag utility routine to make all windows on the workstation screen "movable". While this program is running, the user can press shift-control-MB3 over any window on the screen to grab and drag it around. The VFake widget is used to gain access to the screen's root window, and the VDrag utility routine is used enable and trap events on that root window. Program Module: vdragroot.c [VCountdown Sample Program] The VCountdown sample program shows how to use the VHist widget to make a countdown-style work in progress window. To run this program on VMS, set default to the directory containing the executable image and the UID file, and do: $VCountdown :== $SYS$DISK:[]VCOUNTDOWN $VCountdown 123 "Seconds until Lunch" There is a MB3 popup menu over the VCountdown window. Use this to reset, save current settings, and quit. Program Modules: vcountdown.c vcountdown.uil [VColorizer Sample Program] This program allows the user to colorize any window on the screen. Many thanks to Malcolm Forbes and Mark Pratt whose code and ideas were used in this example. I claim full credit for any bugs and shortcoming you might find. To use VColorizer, first run the vcolorizer executable. A color palette will appear on the screen. Press MB1 over any color cell to pick up a color, then drag the pointer to the window you want to colorize. Releasing MB1 will colorize that window. You can use MB2 to colorize more than one window without going back to the color palette for each window. Using MB1, pick up a color from the palette. Then, while still holding down MB1, click MB2 over each window you want to colorize. Finally, release MB1. You can use "chorded-cancel" with MB3 to cancel a colorization action. Click MB3 before releasing MB1 to avoid coloring any window. Colorization effects made by this tool are not saved. A future version of the VColorizer may be able to save color settings in a resource file. The VColorizer also includes VDragRoot functionality. Press Shift/Control/MB3 over any window on the screen and drag to move the window around within its parent. Program Modules: vcolorizer.c vcolorizer.uil [end-of-document]