| vtoolkit.note - "V" Toolkit Overview
*****************************************************************************
* *
* COPYRIGHT (c) 1989, 1990 BY *
* DIGITAL EQUIPMENT CORPORATION, MAYNARD, MASSACHUSETTS. *
* ALL RIGHTS RESERVED. *
* *
* THIS SOFTWARE IS FURNISHED UNDER A LICENSE AND MAY BE USED AND COPIED *
* ONLY IN ACCORDANCE WITH THE TERMS OF SUCH LICENSE AND WITH THE *
* INCLUSION OF THE ABOVE COPYRIGHT NOTICE. THIS SOFTWARE OR ANY OTHER *
* COPIES THEREOF MAY NOT BE PROVIDED OR OTHERWISE MADE AVAILABLE TO ANY *
* OTHER PERSON. NO TITLE TO AND OWNERSHIP OF THE SOFTWARE IS HEREBY *
* TRANSFERRED. *
* *
* THE INFORMATION IN THIS SOFTWARE IS SUBJECT TO CHANGE WITHOUT NOTICE *
* AND SHOULD NOT BE CONSTRUED AS A COMMITMENT BY DIGITAL EQUIPMENT *
* CORPORATION. *
* *
* DIGITAL ASSUMES NO RESPONSIBILITY FOR THE USE OR RELIABILITY OF ITS *
* SOFTWARE ON EQUIPMENT WHICH IS NOT SUPPLIED BY DIGITAL. *
* *
*****************************************************************************
*****************************************************************************
* *
* DIGITAL INTERNAL USE ONLY *
* *
* Do not distribute outside Digital without first contacting the author. *
* THIS SOFTWARE IS NOT FORMALLY SUPPORTED AND IS PROVIDED AS IS. *
* *
* Steve Klein, DECWIN::KLEIN, Digital ZKO *
* *
*****************************************************************************
+----------------------+
| Modification History |
+----------------------+
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
VToolkit.h - XUI/MOTIF portability module
Sample Programs:
VDragRoot - draggable windows anywhere on screen
VDiskQuota - (VMS only) disk quota display program
BTrap - (VMS only) broadcast message display program
TestVDrag - test VDrag utility routines
TestVList - test VList widget
TestVHist - test VHist widget
TestTList - test TList widget
To build all the VToolkit components (on a VMS system), do "@buildall".
This compiles all modules and link the following executable programs:
btrap.exe
testtlist.exe
testvdrag.exe
testvhist.exe
testvlist.exe
vdiskquota.exe
vdragroot.exe
Please feel free to contact me, Steve Klein (DECWIN::KLEIN), with any
comments, questions or suggestions you might have about the VToolkit.
-steve-
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.
I encourage you to examine what's here and use whatever you find
useful. The code has proven to be robust and stable. It quite
possibly could save you substantial development time and effort
and might just give you a better user interface as well.
A note about portability
------------------------
It is my intention that all VToolkit components be as portable as possible
across base toolkits (XUI and MOTIF), operating systems (VMS and ULTRIX)
and hardware platforms (VAX and RISC). Whenever possible, industry-standard
C is used and operating-system-specific features are avoided.
At this time, however, not all components satisfy all these portability goals.
A checklist is included showing the present status of each component. Over
time, with feedback from non-VMS, non-VAX clients, VToolkit portability
will improve. The VList widget is a good example of a fully-portable
VToolkit component.
If you do port any of the VToolkit components, please send me a copy of
your work and it will be incorporated into the master sources with due
credit and appreciation.
[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 does
the test program TestVList.
Platforms:
Toolkits: [Y] XUI [Y] MOTIF
Operating Systems: [Y] VMS [Y] ULTRIX
Hardware: [Y] VAX [Y] RISC
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.makefile
testvlist.uil
testvlistm.com
testvlistm.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.
Platforms:
Toolkits: [Y] XUI [ ] MOTIF
Operating Systems: [Y] VMS [?] ULTRIX
Hardware: [Y] VAX [?] RISC
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.
Platforms:
Toolkits: [Y] XUI [ ] MOTIF
Operating Systems: [Y] VMS [Y] ULTRIX
Hardware: [Y] VAX [Y] RISC
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.
Platforms:
Toolkits: [Y] XUI [ ] MOTIF
Operating Systems: [Y] VMS [?] ULTRIX
Hardware: [Y] VAX [?] RISC
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.
Platforms:
Toolkits: [Y] XUI [ ] MOTIF
Operating Systems: [Y] VMS [?] ULTRIX
Hardware: [Y] VAX [?] RISC
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.
Platforms:
Toolkits: [Y] XUI [ ] MOTIF
Operating Systems: [Y] VMS [?] ULTRIX
Hardware: [Y] VAX [?] RISC
Documentation Module:
(not yet written)
Utility Module:
vautorepeat.c
vautorepeat.uil
Test Program Module:
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.
Platforms:
Toolkits: [Y] XUI [ ] MOTIF
Operating Systems: [Y] VMS [N] ULTRIX
Hardware: [Y] VAX [N] RISC
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.
Platforms:
Toolkits: [Y] XUI [ ] MOTIF
Operating Systems: [Y] VMS [N] ULTRIX
Hardware: [Y] VAX [N] RISC
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.
Platforms:
Toolkits: [Y] XUI [ ] MOTIF
Operating Systems: [Y] VMS [?] ULTRIX
Hardware: [Y] VAX [?] RISC
Program Module:
vdragroot.c
[END-OF-DOCUMENT]
|
| Subject: VToolkit Update (APR-10)
An updated VToolkit is available in the public directory.
Thanks to all who have asked for the VToolkit.
To date, over 100 of you have been added to the interest list and
new requests are arriving daily. I believe I am up-to-date in replies.
If you sent me mail and have not received a reply, please send it again.
The VToolkit is a collection of widgets, sample programs and utility
routines that extend the XUI and MOTIF X toolkits.
This baselevel completely replaces all previous ones.
There were no incompatible changes in this baselevel.
Changes since the last posted baselevel (APR-02) include:
(*) MOTIF support for:
VHist widget
VFake widget
VDrag utility module
TestVHist sample program
VDragRoot sample program
VDiskQuota sample program
(*) A new sample program, VCountdown, that displays a countdown histogram.
This can be used as the starting point for a work-in-progress type window.
This sample program works under both XUI and MOTIF.
(*) A new utility module, VtkUtil, that contains convenience routines
used in many of the VToolkit sample programs.
(*) A new orientation option, VHistOrientationBestFit, for the VHist widget
that allows the widget to select vertical or horizontal orientation based
on its actual size.
(*) Simplified build procedures.
As before, if you want a copy of the VToolkit and don't yet know the
location of the public directory, simply send me mail. I will add you
to the interest list and will reply with the name of the public directory.
(The only reason I am not posting the directory name publicly is because I
want to maintain a reasonably complete interest list.)
-steve-
(DECWIN::KLEIN)
|
| VToolkit Availability Update 12-Jun-1990
-------------------------------------------------------------------
A new VToolkit baselevel is now available in the public directory. If you do
not already have a pointer to this directory, send me mail and I will add you
to the interest list and reply with the pointer.
This update supercedes all previous VToolkit baselevels.
Over 250 people are now on the VToolkit interest list. There are plans to
include a recent VToolkit baselevel in the VMS/DECwindows V3.0 DECW$EXAMPLES
directory. However, I will continue to maintain the public directory with
the very latest versions of the code. Thanks to all for your encouragement
The only incompatible change in this baselevel was in the VHist
widget-to-application call interface, which now supports colored bars
and grid lines. The interface is now extensible and should not need
to be changed again even as more features are added. See vhist.note
for more details.
Attached is a list of changes between the MAY04 and JUN12 VToolkit baselevels.
My apologies to those whose suggestions have not yet been implemented.
I recently changed projects and have not had as much "spare" time as before.
But I will continue to work on the VToolkit as time allows.
As always, comments and suggestions are more than welcome.
Enjoy.
-steve-
Itemized changes (MAY04 to JUN12) are:
(*) Colored bar and grid line support was added to the VHist widget.
The documentation (vhist.note) was updated. THERE WERE INCOMPATIBLE
CHANGES MADE TO THE VHIST WIDGET APPLICATION INTERFACE. The sample programs,
testvhist.c and vcountdown.c, were changed to conform to the new call interface.
(*) The userData (aka DwtNuserData) resource was added to the VHist widget.
(*) A new sample program, vcolorizer.c, was added. This program allows the
user to color any window on the screen using direct manipulation with a
color palette. Many thanks to Malcolm Forbes and Mark Pratt whose code
and ideas were freely borrowed for this sample program.
(*) The VToolkit was updated to support MOTIF BL1.1 instead of BL1.0.
MOTIF BL1.0 is no longer supported.
(*) The build command files were renamed to "vbuildall*.com"
instead of simply "buildall*.com", and a common build environment is
now used for both XUI and MOTIF versions.
(*) Copyright notices were updated in all files to conform to the latest
version specified by Digital's legal department.
(*) A bugfix was made to btrap.c. Under certain circumstances, XtFree was
being called with a different address than had been returned by XtMalloc.
(*) Many new routines were added to the utility module, vtkutil.c. For
example, there is now a routine, VtkInitialize, that does common
application initialization for all the sample programs.
(*) Source language portability improvements were made to several modules.
These usually involved better type casting.
(*) A change was made to the VDiskQuota sample program to make
it possible to save application settings (Customize/SaveSettings) while
an update is in progress.
(*) The VDrag utility module was changed to conditionalize the button
bindings to support MOTIF style (MB2 for direct manipulation instead of MB3.)
It was also changed to use the X-standard drag cursor instead of a
DEC-proprietary cursor.
|