README: 7/09/92
/*************************************************************************
COPYRIGHT NOTICE:
Control Panel Widget Set (Xc), v. 1.3
copyright (c) 1992 by Paul D. Johnston
All rights reserved. You may freely use and distribute the Control
Panel Widget Set (Xc), but you may not use it, or any widget in the set,
in your commercial or freely distributable applications without giving the
author due recognition.
Example:
"This software product makes use of the Control Panel Widget Set (Xc),
v. 1.3, copyright 1992 by Paul D. Johnston."
**************************************************************************/
TABLE OF CONTENTS:
1. General Info
1.1 Release Notes
1.2 Acknowledgements
1.3 Archive Contents
2. Installation
2.1 Installed System List
3. Xc Widgets
3.1 Getting Started
3.1.1 Tips for Using Xc Widgets
3.1.2 The 3D Effect and Xc Color Resources
3.2 Control Widget
3.3 Value Widget
3.4 SimpleButton Widget
3.5 ValueButton Widget
3.6 Slider Widget
3.7 LCD Widget
3.8 ToggleButton Widget
3.9 LedButton Widget
3.10 BarGraph Widget
4. Bug Reports/Suggestions
1. GENERAL INFO
The Control Panel Widget Set, identified as Xc, is an Xt Intrinsics-based
widget set that provides a library of widgets for "control panel" style
interfaces. Currently it consists of 9 widgets: a Control widget, a Value
widget, a SimpleButton widget, a ValueButton widget, a ToggleButton widget,
a Slider widget, an Lcd widget, an LedButton widget, and a BarGraph widget.
The Control widget is a subclass of the Intrinsics Core widget class and it
basically stores resources used by all Xc widget subclasses. The Value widget
is a subclass of Control and is also used for subclassing other widgets that
manipulate integer/floating point values. The SimpleButton, LedButton, and
ToggleButton widgets are subclasses of Control; and the ValueButton, Slider,
Lcd, and BarGraph widgets are subclasses of the Value widget. See section 3
of this document for a detailed description and programming info for each
widget.
One shortcoming with this release of the Xc widget set is that
there are no man(1) pages for the widgets yet. I will try to provide
these in a future release. Shared libraries are not supported in this
release. An additional shortcoming is that the code is not ANSI-C. I
will convert to ANSI-C probably by the next version (if we get the ANSI
compiler by then). I'll put the affected parts within #ifdef __STDC__
sandwiches in order to maintain compatibility with those who are still
working with K&R 'C'. Also, when we get X11R5 from the company that
produces the operating system we're working with, I'll add R5 support.
I plan on adding a number of 'control panel' style widgets to this
widget set in the future, including a Guage widget (similar to the aircraft
cockpit guage), a SelectorSwitch (similar in functionality to Motif's
RadioBox, but emulates a hardware multi-selection switch), a BarChart widget
(many BarGraph widgets connected together with the same value range), and
whatever other widgets I decide on. If you have any ideas, let me know.
1.1 RELEASE NOTES
Version Changes
--------- --------------------------------------------------
1.3 1. Changed the method for producing the 3D effect:
a white/black dashed line is used to produce 'dithered'
top & bottom shade colors, thereby using less server
resources and increasing the range of background colors
to choose from. The old method for the 3D effect is
still available for those who choose by specifying a
'-DNICE_SHADES' compiler option.
2. ValueButton widget:
a. You can now use the keypad '+' and '-' keys or the
up and down arrow keys to increment/decrement the
value. The Return/Enter keys active the Accept
Button also.
b. You can rapidly increment/decrement the value by
holding the pointer button down within the Up/Down
arrows.
3. Slider widget:
a. Added a Zoom feature to allow for fine tuning of
the Slider's value, implemented with Up/Down Zoom
Buttons.
b. Added an optional Accept Button. The application's
callback function won't be called until the user
presses the Accept button (allowing the user to
achieve the desired value first).
c. Fixed the Nob's movement range to be the center of
the Nob.
4. LCD widget:
a. Made the border around the LCD Display to be the
same proportional size all around.
b. Changed the individual LCD segments to have angled
ends like a real 7-segment display.
5. Added an "ledVisible" resource to the LedButton widget
to allow the application to use it to indicate a state/
status string without a corresponding LED indicator.
6. Changed the SimpleButton widget's minimum size to be the
smallest rectangle enclosing the widget's Label.
7. Added a "valueJustify" resource to the Value widget (and
subclasses) to allow for left, right, or center
justification of the value displayed within the Value Box.
1.2 1. Changed Xc widget class names so that they are preceded
by 'xc' in order to prevent possible name collisions
with other widget sets.
1.1 1. Fixed Xctest.c so that the argc parameter to XtInitialize
is passed by reference (address) instead of by value (oops!).
2. Fixed the xctest shell script so that the #!/bin/sh line
is the first line in the file.
3. Added range checking to the Lcd and BarGraph widgets so
that the application cannot set a value outside of the
XcNupperBound/XcNlowerBound range via the convenience
functions or callback functions.
4. Fixed Control.c so that it uses " " instead of "NO LABEL"
as the default label if one is not supplied.
1.0 1. Initial release.
1.2 ACKNOWLEDGEMENTS
Special thanX goes to the following people for their help in the propagation
of this widget set:
Jay Chiang chiang@spc5.jpl.nasa.gov
Robert Withrow witr@rwwa.COM
Markku Savela savela@tel.vtt.fi
Przemek Klosowski przemek@rrdstrad.nist.gov
Richard Hesketh rlh2@ukc.ac.uk
Kevin Sweet sweet@horizon.com
1.3 ARCHIVE CONTENTS
Enclosed in the Xc.tar file is the following source code/documentation:
FILE DESCRIPTION
---------- ---------------------------------------------
README Documentation for the Control Panel Widget Set (Xc)
from both the user and application stand-point.
Control.h The public header files included by the application
Value.h that uses a particular widget.
SimpleB.h
VButton.h
ToggleB.h
Slider.h
Led.h
BarGraf.h
Lcd.h
Xc.h
ControlP.h The private header files used by the each
ValueP.h widget's code and by its subclasses.
SimpleBP.h
VButtonP.h
ToggleBP.h
SliderP.h
LedP.h
BarGrafP.h
LcdP.h
Control.c The actual widget code that contains widget methods,
Value.c action functions, and definitions.
SimpleB.c
VButton.c
ToggleB.c
Slider.c
Led.c
BarGraf.c
Lcd.c
Imakefile An imake file for making an X makefile to build
the Xc widget set and test program (use xmkmf on
your system to make the Makefile).
Xc.mak A simple make file that builds the Xc widgets
into an archive library (libXc.a) to be linked
with your applications, and also makes the Xctest
program as an example Xc application. Use it if
you don't have xmkmf (everyone should have it).
You will probably have to edit it first.
Xctest.c A simple program that creates two of each widget
in the Xc widget set and demonstrates widget
applications.
Xctest.ad An application defaults resource file for the Xctest
application (demonstrates Xc widget resource settings).
xctest Simple shell script that enables you to try out the
Xctest demo program without moving the Xctest.ad
file to your app-defaults directory.
copyright.doc Copyright Notice for the Xc widget set and source,
to be included in any commercial/shareware
applications that you use any of these widgets in.
2. INSTALLATION
1) Uncompress and extract the contents of the tar file (Xc-1.3.tar.Z) in
the directory of your choice:
cat Xc-1.3.tar.Z | uncompress | tar -xfvo -
2) run 'xmkmf' in the directory you extracted into. This will
make a Makefile for your system from the Imakefile provided.
3) Then just enter 'make World' to build the Xc library (libXc.a)
and the test/demonstration program Xctest.
4) After you have successfully built the Xc library and the demo
program, run the 'xctest' script to try the Xctest program with the
application defaults file 'Xctest.ad' without having to copy the file
to your app-defaults or home directory.
5) Enter `make install' to copy the library and the header files to
the installation directories. You may need to be root to do this
depending on your setup.
6) To use the library, simply link with it when you build your
applications (use the -lXc link option). To include the
necessary header files, use (for example) this path specification:
#include <X11/Xc/Control.h>
2.1 INSTALLED SYSTEM LIST
The Xc widget set has been successfully built and run on the following
systems:
MACHINE OPERATING SYSTEM X11 VERSION
-------------- ------------------------ ------------------
Modcomp 9735 (68030) REAL/IX (SVR4 Unix) R3/R4
Intel 386 (clone) Interactive SVR4.0.3.0 R5 Patch 8
Sun 3/60 SunOS 4.1.1 R4
Sparc SunOS 4.1.1 R5 Patch 11
SunIPX SunOS 4.1.2 R5
HP 9000/750 HPUX 8.07 R5
DEC VAX VMS 5.4-3 R4/DECWINDOWS
3. XC WIDGETS
3.1 Getting Started
3.1.1 Tips for Using Xc Widgets
To create widgets in the Xc widget set, just use the XtCreateWidget
or XtCreateManagedWidget functions and specify the appropriate widget
class name (specified in the detailed widget description that follows).
Use XtSetArg and XtSetValues if you need to hard code resources in your
application. See the Xctest.ad file for an example of setting Xc resources
within resource files.
Be conscious of each widget's geometry (width & height) because the
sizes of each graphical element of a widget are scaled according to
the Core widget width & height resource settings. If you find that
a widget's label or value string gets clipped by other widget elements,
either resize the widget or choose a smaller font.
3.1.2 The 3D Effect and Xc Color Resources
As of version 1.3, the method used to produce the 3D effect is a
'dithered' approach using a white and black dashed line against the
background to produce the top and bottom shade colors. No colors are
allocated in the DefaultColormap, making the widgets more server-
resource-efficient. The resulting effect is similar to Motif's, and
allows for a much larger range of background colors possible. However,
the 3D effect is not as nice (in my opinion) as that produced with the
old method. Therefore, the old method of producing the 3D effect is still
available by specifying a '-DNICE_SHADES' switch to the compiler (add this
to the CCOPTIONS variable in the Makefile) for those who want the better
shading.
If the '-DNICE_SHADES' option is defined, the Control background color
resource setting is used to generate the colors used to make the 3D effect.
Basically, the Control widget takes the Control background color
setting and calculates a lighter shade of the color for the top & left
corners of Xc objects, and calculates a darker shade of the background
color for the bottom & right corners of the objects. I found that
on our X server (a 256 color Tektronix X Terminal), certain background
color settings work better in producing the 3D effect than others.
Generally, any "pure" RGB colors (i.e., red, yellow, blue, black, white,
green, etc.) do not produce as good a 3D effect. But, I do know that soft
colors, pastels, and otherwise bland background colors do work fine to
produce the 3D shading effect. Obviously, the lighter a background color
is, the less pronounced the lighter shade color will be; and the darker a
background is, the less pronounced the darker shade color will be. Also,
keep in mind that if you specify this method for producing the 3D effect,
the Control widget allocates the shade colors in the DefaultColormap.
So if you get the "unable to alloc shade 1/shade 2 color" warning, you
will have to kill whatever client is using up alot of colors in the
DefaultColormap (a prime culprit of this is if you use xloadimage to
load a GIF or other image with alot of colors on the root window).
I chose to use the DefaultColormap for allocating the shade colors
because of the possibility that false colors will be displayed whenever
the pointer is not within an Xc widget's window. If your display can
handle alot of colors (like 16 million or something), or you're not
using other clients that use up alot of colors, then you shouldn't have
to worry about it.
3.2 CONTROL WIDGET
xcControlWidgetClass
USER INFO -
The Control widget serves as the superclass for all of the Xc widgets.
It simply stores resources that are common to all of the Xc widget classes
(i.e., label, font, colors, etc.). It also calculates the shade colors
used in producing the 3D effect. Resources are as follows:
Resource Rep.
Name Type Default Value Description
--------- ---------- ------------- ----------------------
XcNbackground Pixel gray Background color,
(used in producing
the 3D effect if the
-DNICE_SHADES switch
is specified).
XcNlabel String "" The widget's label.
XcNlabelColor Pixel black The label's color.
XtNfont XtFontStruct DefaultFont Font used for widget's
strings.
XcNshadeDepth int 3 Depth of the 3D
shadow effect in
Pixels. (1 - 5)
These resources apply to each of the Xc widget classes.
PROGRAMMER'S INFO -
Be sure to properly set color or font resources if you hard-code these
by using XtSetValues in your application.
3.3 VALUE WIDGET
xcValueWidgetClass
USER INFO -
The Value widget is used only for subclassing widgets that manipulate
long integer/floating point values, and it does nothing other than store
resource settings common to this widget class. As contained in the Xc
widget set header file (Xc.h), the XcDType is defined as an enumerated
type containing XcLval, XcHval, and XcFval ("lval", "hval", and "fval" in
resource files), and it is used to specify the value's datatype (long, hex,
or float). The XcVType is defined as a union containing a long integer
(lval) member and a float member (fval), and is used in specifying a
Value widget's value, upper and lower bound, and increment resources.
The XcNvalueForeground and XcNvalueBackground resources are used to
specify the foreground/background color of the widget's displayed value.
The XcNvalueJustify resource is a string that identifies how the value
should be displayed in the subclass's Value Box (i.e. left, right, or center
justification).
Resource Rep.
Name Type Default Value Description
--------- ---------- ------------- ----------------------
XcNdataType XcDType lval The value's data type,
either long, hex, or
float ("lval", "hval",
or "fval").
XcNdecimals int 2 Number of decimal
places for float
type ("fval") values
(1 - 6 places).
XcNincrement XcVType 1 Value to increment/
decrement by.
XcNupperBound XcVType 100 Maximum value range.
XcNlowerBound XcVType 0 Minimum value range.
XcNvalue XcVType XcNlowerBound Initial or new value
for this widget.
XcNvalueForeground Pixel black Foreground Color of
the value string
in the Value Box.
XcNvalueBackground Pixel white Background Color of
the Value Box.
XcNvalueCallback Pointer NULL Callback function to
call when the value
has changed by the
user.
XcNvalueJustify XcValueJustify justifyCenter Specifies how to
place the value within
the Value Box
("justifyLeft",
"justifyRight", or
"justifyCenter")
Currently, the valid XcNdecimals settings are 1 - 6. Obviously, the
XcNincrement setting must be greater than 0, and the XcNupperBound and
XcNlowerBound settings must not conflict with each other. The XcNvalue
setting must be within the range specified by XcNupperBound/XcNlowerBound.
Look at the example application defaults resource file (Xctest.ad) for
setting Xc resources in a resource file.
PROGRAMMER'S INFO -
The accompanying application source file, Xctest.c, demonstrates
how to use Xc widgets in application code. The program creates ValueButtons,
Sliders, Lcds, and BarGraph widgets. This test program also demonstrates
the setting of resource values from application code using XtSetValues().
When specifying floating point values for resource settings (i.e.,
XcNincrement, XcNupperBound, XcNlowerBound, and XcNvalue) be sure to follow
the example in Xctest.c or the settings won't work. Create variables of
type XcVType (a union with a long member and a float member), assign your
floating point setting to the float member of this union, BUT reference the
long member when setting the resource with XtSetArg. Example:
{
Widget vbutton;
Arg args;
int i;
XcVtype up_bound, lo_bound, increment;
/* First, create the ValueButton widget obviously */
/* Set your float type values in the XcVType variables */
increment.fval = 0.01;
up_bound.fval = 1.00;
lo_bound.fval = 0.00;
/* BUT, reference the lval member when using the XtSetArg macro. */
i = 0;
XtSetArg(args[i], XcNincrement, increment.lval); i++;
XtSetArg(args[i], XcNupperBound, up_bound.lval); i++;
XtSetArg(args[i], XcNlowerBound, lo_bound.lval); i++;
XtSetValues(vbutton, args, i); /* NOTE: ^ the long member is referenced
* even though the value is a float.
*/
}
This seems kludgy, but it's the best way to get by the Xt limitation
of the XtArgVal type cast (happens to be a long). Asente & Swick get
the credit for this solution.
Look at the sample callback function in Xctest.c for using the
XcCallData structure in your callback functions. The application
should use the XcData pointer type for the call_data parameter in your
callbacks for the Value class widgets. For those subclasses that allow
the user to manipulate the value, the Value widget calls the XcNvalueCallback
whenever the value is changed. The call_data parameter points to a
structure containing the widget's datatype, number of decimals, and the
new value. See Xctest.c for examples.
3.4 SIMPLE BUTTON WIDGET
xcSimpleButtonWidgetClass
USER INFO -
The SimpleButton widget is similar to Motif's XmPushButton widget. It's
provided in the Xc widget set for those who aren't fortunate to have Motif
and still want to have cool looking buttons. It is a 3D rectangle button
that looks like it's depressed when the user clicks on it. If the user
moves the pointer out of the SimpleButton while it is depressed, the
SimpleButton will pop back up again (become 'raised'). The SimpleButton
is only activated when the user releases the pointer button while the
pointer is over the SimpleButton. This feature allows the user to 'change
their mind' after pressing the pointer button over the SimpleButton. Once
the SimpleButton is activated, the application's registered XcNactivateCallback
function is called. Specific resources include:
Resource Rep.
Name Type Default Value Description
--------- ---------- ------------- ----------------------
XcNactivateCallback Pointer NULL Application callback
function to be called
when the user activates
the SimpleButton.
PROGRAMMER'S INFO-
Include the SimpleB.h header in application code.
KNOWN PROBLEMS -
None, (yet).
FUTURE ENHANCEMENTS -
I may add the ability to specify a bitmap/Pixmap in place of the Label.
3.5 VALUE BUTTON WIDGET
xcValueButtonWidgetClass
USER INFO -
The ValueButton widget was created to provide a user-interface element
that would allow a user to increment/decrement an integer, long integer,
or floating point value by clicking on an Up or Down arrow, and allow an
application to access the incremented/decremented value when the user clicks
on an Accept button. One of the many possible uses of such a widget would
be to provide an interface element enabling the user to quickly change
application 'settings' by using the mouse pointer instead of typing values
from the keyboard, thus providing a more logical approach to a user-interface
(i.e., its more logical to press an up/down arrow to increment/decrement
a value instead of typing its new value in some kind of text widget).
The Valuebutton widget has five graphical elements: an Up Arrow, a Down
Arrow, an Accept Button, a Value Box, and the widget's Label string. The
user clicks (once) on the Up Arrow to increment the value in the Value Box
by whatever value is specified in the XcNincrement resource setting (default
is 1). Likewise, the user clicks on the Down Arrow to decrement the value.
The value isn't actually changed until the user releases the pointer button
while over the Up/Down Arrow, enabling the user to change his/her mind.
The user can click the Up/Down Arrows as many times as he/she likes until
the upper range or lower range value is reached (specified by the XcNupper-
Bound and XcNlowerBound resource settings); this way the user is prevented
from incrementing/decrementing the value beyond specified limits. The Value
Box indicates the ValueButton's current numeric value. When the user has
set the value to the desired value, he/she can then click on the Accept
Button to make the value 'current', which causes the application program's
XcNvalueCallback function to be called in order to do something with the
current value. The Accept Button does not have a label on it, it is simply
the raised 3D button between the Up and Down Arrows.
There are keyboard equivalents for the Up/Down Arrows and Accept Button:
hit the keypad '+' or '-', or the up/down arrow keys to increment/decrement
the value when the pointer is in the ValueButton widget. Similarly, the
Return/Enter keys activate the Accept Button. An additional feature of the
ValueButton widget is that the user can rapidly increment/decrement the
value by pressing the pointer button and holding it down over the Up/Down
Arrow. The value will start incrementing/decrementing automatically about
1 second later and will continue to do so until the user releases the
pointer button, moves the pointer out of the Up/Down Arrow, or the upper/
lower bound is reached. Additionally, if the user holds down the above
mentioned keyboard equivalents, the value will also rapidly increment/
decrement.
The following identifies the ValueButton's resources:
Resource Rep.
Name Type Default Value Description
--------- ---------- ------------- ----------------------
(None yet)
PROGRAMMER'S INFO -
Include the VButton.h header in application code. See PROGRAMMER'S INFO
on the Value widget for a description of using the ValueButton in application
code.
KNOWN PROBLEMS -
None, (yet).
FUTURE ENHANCEMENTS -
I will add a resource that allows for horizontal or vertical orientation of
the ValueButton. I plan on creating a Multi-Value Button widget that
operates like the ValueButton but it would allow you to manipulate many
values of the same datatype within the same widget (taking up less window
real-estate).
3.6 SLIDER WIDGET
xcSliderWidgetClass
USER INFO -
The Slider widget is a subclass of the Value widget and it is similar in
behavior/functionality to Motif's XmScale widget in that it allows you to
manipulate a numeric value over a given range. The Xc Slider widget differs
from the Motif XmScale in that it allows manipulation of real floating point
values (not just an integer that is displayed like a float). Additionally,
the Slider widget allows manipulation of values over a broader range (i.e.,
the range of 'C' long integer and float types).
The Slider widget has 6 graphical elements: the widget's Label, a Nob for
changing the widget's value, a Channel that the Nob slides in, a Value Box
that displays the widget's current value, an optional Accept Button, and an
optional Zoom control (with Zoom Buttons and displayed Zoom Factor) for fine
tuning of the Slider's value. If the XcNenableAccept resource is set to
True, the Accept Button will appear as the raised button to the left of the
Channel with a vertical Slider orientation, or will appear to the left of
the Value Box with a horizontal orientation. If the XcNmaxZoomFactor
resource is set to a value greater than 0, then the Zoom control will appear
to the right of the Channel with a vertical Slider, or will appear to the
right of the Value Box with a horizontal orientation.
The user can manipulate the widget's value in three ways: click on the Nob
and drag it up and down the Channel to increase/decrease the value; click in
any place in the Channel, the Nob will move to that place and the value will
be changed to the corresponding value; or press the up and down arrows on the
keyboard to increment/decrement the value according to its precision (i.e.,
if the value has 3 decimal places, the value will be incremented/decremented
by .001; if the value is integer/hexadecimal, the value will be incremented/
decremented by 1). The Slider also has an optional fine-tune feature that
lets the user manipulate values that have large ranges. If the
XcNmaxZoomFactor resource is set to an integer number greater than 0, the
Zoom controls will be available to allow the user to adjust the 'Zoom Window'
over which the Slider Nob can be moved. The Up/Down Zoom Arrows are used
to increment/decrement the Zoom Factor (displayed between the Arrows)
enabling you to 'zoom' in on the Slider's current value. Basically, the
value's range is divided by 2 to the power of the Zoom Factor to determine
the 'Zoom Window'. If the Zoom Factor is 0, then there is no zooming (2 to
the power of 0 equals 1). The larger the Zoom Factor, the greater the
precision for fine tuning the value. You'll have to experiment with the
XcNmaxZoomFactor resource to determine the best possible Zoom Factor for
fine tuning a value over a given range.
The Slider widget can have vertical or horizontal orientation based on
the XcNorient resource setting ("vertical" or "horizontal" in resource files,
XcVert or XcHoriz in application code). With the vertical orientation, the
value is increased as the Nob is moved from bottom to top; and with the
horizontal orientation, the value is increased as the Nob is moved from left
to right. Application callback functions for the Slider widget will be
called under 2 circumstances. If the XcNenableAccept resource is set to
False (default), the callback is called whenever the value is changed
(i.e., the user clicks on the Nob, drags it, and then releases the pointer
button; the user clicks in the Channel to set the Nob; or the user presses
the up or down arrow keys on the keyboard). If XcNenableAccept is set to
True, the callback is only called when the user presses the Accept Button,
thereby allowing the user to achieve the desired value (fine tune, etc.)
before any action is taken on that new value.
As with all subclasses of the Value widget, the Slider's value (and Nob
position) can be set initially or at any time after the widget is created
by setting the XcNvalue resource. Specific Slider widget resources are:
Resource Rep.
Name Type Default Value Description
--------- ---------- ------------- ----------------------
XcNorient XcROrient XcVert Slider's orientation:
("vertical" or
"horizontal" in
resource files, XcVert
or XcHoriz in
application code.
XcNnobColor Pixel black Color of the Slider's
Nob.
XcNenableAccept Boolean False Enable/disable the
Accept Button.
XcNmaxZoomFactor Int 0 Sets the max Zoom
Factor.
PROGRAMMER'S NOTES -
Include the Slider.h header in application code. See the Value widget's
PROGRAMMER'S NOTES for a description of using the Slider widget in
application code. Note that the XcNincrement resource of the Value widget
has no effect on the Slider widget.
KNOWN PROBLEMS -
The Nob seems to move a little slow when dragging it in the Channel (it
sometimes lags behind the mouse pointer movement). This is because the
widget receives and processes all PointerMotion events. I haven't figured
out yet how to make the server send only PointerMotionHints to a widget
(I tried using XSelectInput, but that didn't work). If anyone has a
solution to this problem, please let me know.
FUTURE ENHANCEMENTS -
I may add scale segments along the Channel.
3.7 LCD WIDGET
xcLcdWidgetClass
(ThanX to Robert Withrow for the idea and requirements specification)
USER INFO -
The LCD widget is also a subclass of the Value widget and it emulates
the traditional 7-segment LCD display. It simply takes an application-
specified long integer/floating point/hexadecimal value and displays
each character of the value in 7-segment LCD fashion.
The LCD widget has 2 graphical elements: the widget's Label, and the
LCD Display in the center of the widget. The widget basically takes
the application-specified value, does a sprintf on it based on the
XcNdataType setting, and displays each character in 7-segment fashion
(right-justified, starting with the most significant digit) in the LCD
Display. The XcNvalueLength resource setting is important. Choose the
max length that the value can obtain, otherwise, the displayed value may have
its least significant digits clipped. The XcNvalueLength setting is also
used in determining the geometry (size, line width, etc.) of each character
in the LCD Display; so if the characters get displayed weird, adjust
the XcNvalueLength or resize the widget (preferably the latter).
Since this widget is used as an indicator, there is currently no user
interaction with the Lcd widget. But, there is nothing stopping you
from adding your own action functions in your application (e.g., you could
popup a 'help' dialog whenever the user clicks the right pointer button in
the LCD, etc.).
There are two ways the application can update the value in the LCD
Display: by specifically setting the XcNvalue resource to the desired
value (i.e., using XtSetArg/XtSetValues, or the XcLcdUpdateValue convenience
function), or by enabling the widget to notify the application to update
the value at timed intervals (via the XcNinterval and XcNupdateCallback
resources). See the PROGRAMMER'S NOTES section for more detail. Specific
LCD widget resources are:
Resource Rep.
Name Type Default Value Description
--------- ---------- ------------- ----------------------
XcNvalueLength short 10 Length (in characters)
of the widget's value.
XcNinterval int 0 Time Interval (in
milliseconds) between
invoking the
XcNupdateCallback
procedure.
XcNupdateCallback Pointer NULL Callback function
invoked at XcNinterval
milliseconds used to
notify the application
to update the displayed
value.
The Value widget's XcNincrement and XcNvalueCallback are not used by this
widget. Use the XcNvalueForeground and XcNvalueBackground resources to specify
the LCD Display's colors. Realistic colors are red on black, gray on yellow,
etc.
PROGRAMMER'S NOTES -
Include the Lcd.h header in application code. To set the LCD's displayed
value, you can use XtSetArgs/XtSetValues as defined in the PROGRAMMER'S NOTES
section for the Value widget, or you can use the following convenience
function provided with this widget:
void XcLcdUpdateValue(LcdWidget w, XcVType *value);
/* Example usage */
Widget lcd;
XcVType new_value;
/* Create the widget first (obviously)... */
new_value.fval = 5.002;
/* Update the LCD with the latest value. */
XcLcdUpdateValue(lcd, &new_value);
Applications can also specify a callback function to be invoked at specified
time intervals in order to update the value displayed in the LCD. In order
to do this, set the XcNinterval to the desired time interval in milliseconds,
and add an XcNupdateCallback function for the specific LCD widget. The
following example defines a callback function to set the LCD widget's
displayed value:
/* Voltage update interval: 500 msecs. */
#define VOLTAGE_INTERVAL 500
/* Declaration of callback function. */
void Update_value(Widget w, caddr_t client_data, XcData call_data);
/* Globals */
Widget Lcd;
float Current_voltage;
{ /* probably function main()... */
int i;
Arg args[10];
/* Create all the necessary widgets... */
/* Set resources to enable update value notification at timed intervals. */
i = 0;
XtSetArg(args[i], XcNinterval, VOLTAGE_INTERVAL); i++;
XtSetValues(Lcd, args, i);
/* Specify the callback to be invoked by the LCD widget. */
XtAddCallback(Lcd, XcNupdateCallback, Update_value, NULL);
}
/* Callback function to update the LCD's displayed value with the voltage. */
void Update_value(w, client_data, call_data)
Widget w;
caddr_t client_data;
XcData call_data; /* Important: must be XcData type. */
{
/* Set the LCD's displayed value to be the current measured voltage. */
call_data->value.fval = Current_voltage;
}
The call_data parameter of the XcNupdateCallback will be a pointer to an
XcNCallData structure containing the widget's current value, its datatype,
and number of decimal places if applicable. The XcNupdateCallback function
must set the value member of the structure pointed to by call_data to the
new value before it returns. See Xctest.c for an example XcNupdateCallback
function. See Value widget's PROGRAMMER'S NOTES for a description of setting
Value widget resources in application code.
KNOWN PROBLEMS -
None (yet).
FUTURE ENHANCEMENTS -
None planned.
3.8 TOGGLE BUTTON WIDGET (ThanX to Robert Withrow for the idea!)
xcToggleButtonWidgetClass
USER INFO -
This widget behaves in much the same way as the SimpleButton widget,
except that it toggles between an 'on' and 'off' state. It is made up of
two graphical elements: the widget's Label, and an LED indicator.
To toggle between 'on' and 'off', the user simply presses and releases the
pointer button while the pointer is in the ToggleButton. When the ToggleButton
is toggled like this, the LED indicator will display the color specified by
the XcNonColor or XcNoffColor resource setting, depending upon which state has
been toggled to. In this way, the user receives a positive indication of
the ToggleButton's state, which is represented by the widget as an enumerated
type: either of XcOn or XcOff ("on" or "off" in resource files).
When the user presses the pointer button over the ToggleButton, it will
appear to be 'depressed', and when the user releases the pointer button over
the ToggleButton, it will become 'raised' again with the LED indicator changed
to the toggled state's color. As with the SimpleButton widget, the user has
the option of changing his/her mind when the pointer button has been pressed
over the ToggleButton by simply moving the pointer out of the ToggleButton's
window. The ToggleButton will raise again but there will be no state change.
Specific ToggleButton resources are:
Resource Rep.
Name Type Default Value Description
--------- ---------- ------------- ----------------------
XcNonColor Pixel "green" Color used for
indicating the 'on'
state.
XcNoffColor Pixel "black" Color used for
indicating the 'off'
state.
XcNstate XcToggleState XcOff ToggleButton's current
state: XcOn or XcOff
("on" or "off" in
resource files).
XcNactivateCallback Pointer NULL Callback function
called when the
ToggleButton has
changed states.
PROGRAMMER'S NOTES -
Include the ToggleB.h header in application code. The application's
XcNactivateCallback function will be called whenever the user 'toggles'
the ToggleButton's state from off to on and vice-versa. If you need to,
you can use the following two convenience functions for setting and
retrieving the ToggleButton's current state:
void XcToggleSet(ToggleButtonWidget w, XcToggleState state);
void XcToggleGet(ToggleButtonWidget w, XcToggleState *state);
where XcToggleState is an enumeration, one of XcOn or XcOff. Note that the
XcToggleGet function's state parameter is a pointer.
KNOWN PROBLEMS -
None (yet).
FUTURE ENHANCEMENTS -
None planned.
3.9 LED BUTTON WIDGET
xcLedButtonWidgetClass
USER INFO -
This widget is a subclass of the Control widget and it is used as an
indicator to display an application-specified status to the user. It
consists of three graphical elements: the Label, an LED indicator, and
an optional State Box that displays an application specified string
corresponding to the current LedButton state.
Since this widget is used as an indicator, there is currently no user
interaction with the LedButton widget. But, there is nothing stopping you
from adding your own action functions in your application (e.g., you could
popup a 'help' dialog whenever the user clicks the right pointer button in
the LedButton, etc.). Both the LED and the State Box are optional, but you
need one or the other because without either, the widget would be useless.
If XcNledVisible resource is set to True, then the LED indicator will be
shown. If the XcNstateVisible resource is True, then the State Box will be
shown. This allows for three possible configurations for this indicator
widget: an LED by itself, a State Box (state string) by itself, or both
an LED and a State Box. With a State Box by itself, the application can
indicate application states/status with just a string.
Specific LedButton resources are:
Resource Rep.
Name Type Default Value Description
--------- ---------- ------------- ----------------------
XcNledColor Pixel "white" Current color of the
LED indicator.
XcNstate String NULL String corresponding
to the current state.
XcNledVisible Boolean True Enable/disable display
of the LED indicator.
XcNstateVisible Boolean False Enable/disable display
of the State Box.
XcNstateForeground Pixel "black" Foreground color of
the string displayed
in the State Box.
XcNstateBackground Pixel "white" Background color of
the string displayed
in the State Box.
XcNinterval int 0 Time Interval (in
milliseconds) between
invoking the
XcNupdateCallback
procedure.
XcNupdateCallback Pointer NULL Callback function
invoked at XcNinterval
milliseconds used to
notify the application
to update the LedButton
color and state string.
PROGRAMMER'S NOTES -
To set the current LED color and optionally the state string, you can use
XtSetArg/XtSetValues (inconvenient), or you can use the XcLedSetState
convenience function:
void XcLedSetState(LedButtonWidget w, char *color, char *state_string);
where color is a valid color name on your server and the state_string
indicates what corresponding string to display in the State Box. If the
XcNledVisible resource is set to False, then pass NULL as the color parameter;
or if XcNstateVisible is False, then pass NULL as the state_string parameter.
You can also have the widget notify your application at XcNinterval time
intervals so that your application can update the LED's color and string.
See the PROGRAMMER'S NOTES section of the LCD Widget for a description on
using the XcNinterval and XcNupdateCallback resources. The LedButton passes
a pointer to an XcLedInfoRec structure as the call_data to your registered
XcNupdateCallback function. It expects you to copy the new LED color name
and state string to the appropriate members of the XcLedInfoRec before your
function returns. See the Xctest.c demo program source for an example of this.
The XcLedInfoRec is defined as follows in Led.h:
typedef struct _LedInfoRec
{
char color[MAX_COLOR_LEN]; /* New LED color name. */
char str[MAX_STR_LEN]; /* Corresponding state string. */
} XcLedInfoRec, *XcLedCallData;
Just assign NULL to the color or str member if the corresponding indicator
(XcNledVisible or XcNstateVisible) is disabled.
KNOWN PROBLEMS -
None (yet).
FUTURE ENHANCEMENTS -
None anticipated.
3.10 BARGRAPH WIDGET
xcBarGraphWidgetClass
USER INFO -
The BarGraph widget is used as a horizontal or vertical bar graph
indication of a specified value. It is a subclass of the Value widget so it
can display long integer/hexadecimal/floating point values. This BarGraph
widget is not to be confused with a bar chart widget (i.e., it only displays
one value, not many values side-by-side). It looks like a digital
'thermometer', or a traditional graphic equalizer band. It is used to
visually indicate a current value in relation to a specified range.
The BarGraph widget is composed of 4 graphical elements: the Label, a Bar
indicator, Scale Segments indicating the range of values and where the
current value fits in that range, and optionally a Value Box that displays
the current value numerically.
Since this widget is used as an indicator, there is currently no user
interaction with the BarGraph widget. But, there is nothing stopping you
from adding your own action functions in your application (e.g., you could
popup a 'help' dialog whenever the user clicks the right pointer button in
the BarGraph, etc.).
In addition to the Value widget resources, specific BarGraph resources
include:
Resource Rep.
Name Type Default Value Description
--------- ---------- ------------- ----------------------
XcNorient XcROrient XcVert BarGraph's orientation:
("vertical" or
"horizontal" in
resource files, XcVert
or XcHoriz in
application code.
XcNbarForeground Pixel "black" Foreground of the bar
in the Bar indicator.
XcNbarBackground Pixel "white" Background of the Bar
indicator.
XcNscaleColor Pixel "black" Color of the Scale
Segments.
XcNscaleSegments int 7 Number of segments
on the Scale.
XcNvalueVisible Boolean True Enable/disable the
displaying of the
Value Box.
XcNinterval int 0 Time Interval (in
milliseconds) between
invoking the
XcNupdateCallback
procedure.
XcNupdateCallback Pointer NULL Callback function
invoked at XcNinterval
milliseconds used to
notify the application
to update the BarGraph's
color and state string.
An odd number for the XcNscaleSegments appears to be best, with the max number
of segments allowed is 20 and the minimum is 0.
PROGRAMMER'S NOTES -
Include the BarGraf.h header file in application code. To change the
BarGraph's indicated value you can use XtSetArg/XtSetValues (inconvenient)
to set the value resource, or you can use the XcBGUpdateValue convenience
function:
void XcBGUpdateValue(BarGraphWidget w, XcVType *value);
where the value parameter is a pointer to an XcVType union (see Xc.h for the
definition of the XcVType union). See the Xctest.c demo code for an example.
You can also have the widget notify your application at XcNinterval time
intervals so that your application can update the BarGraph's indicated value.
See the PROGRAMMER'S NOTES section of the LCD Widget for a description on
using the XcNinterval and XcNupdateCallback resources. The BarGraph passes
a pointer to an XcCallData structure as the call_data to your registered
XcNupdateCallback function. It expects you to copy the new value into the
value member before your function returns.
KNOWN PROBLEMS -
None (yet).
FUTURE ENHANCEMENTS -
I'll probably create a BarChart widget out of this one in a future
version. It will display multiple application-specified values in BarGraph
fashion.
4. BUG REPORTS/SUGGESTIONS
If you note any problems (compiling, running, etc.) please send email to:
xcbugs@spc5.jpl.nasa.gov
I'd like to find out if this widget set is usable by the X community. If you
have any suggestions for new widgets that could be added to the Xc widget
set, or suggestions for improving existing widgets, please send email to:
xcuser@spc5.jpl.nasa.gov
I'll try to address each problem/suggestion as soon as is feasible.
Enjoy!
Paul D. Johnston
johnston@spc5.jpl.nasa.gov
|
