From: brad@bradley.bradley.edu (Bradley E. Smith)
Newsgroups: comp.os.linux
Subject: Re: SUIT
Date: 9 Jan 93 21:52:14 GMT
Organization: Bradley University


=============================================================================
	 SUIT -- The Simple User Interface Toolkit
=============================================================================


INTRODUCTION: WHAT IS SUIT?
===================================
Welcome to SUIT, Simple User Interface Toolkit.

SUIT is a library of interface tools developed at the University of
Virginia to help C programmers create sophisticated mouse based
interfaces without the lengthy learning period associated with
traditional user interface toolkits. Ease of learning and fast ramp up
time is central to SUIT's design. The SUIT tutorial is designed to
make the user productive in under two hours.

Also central to SUIT design is portability. SUIT programs currently
run without changes to the source code on the following platforms:
	o IBM PC
	o Macintosh
	o Sun3
	o Sun4 (SparcStation)
	o SGI (Silicon Graphics IRIS workstations)
	o DECstation
	o HP 

This document is an overview of SUIT's capabilities; full
documentation is included with the SUIT distribution in the form of a
10 page tutorial and a comprehensive Reference Manual. Parts of this
overview were taken from the SUIT tutorial.

In this introduction you will:
	o Run a sample SUIT program
	o See how SUIT allows you to modify the appearance of the
   	  interface while the program is running
	o See how to ftp SUIT from the University of Virginia to 
	  your local site

Along with this document, you will need the files called:
	o demo
	o demo.sui


THE DEMO PROGRAM
============================

	To begin the demonstration, start the SUIT demonstration
program called demo; a so-called "do-nothing application" because
none of the widgets are connected to any program functionality.

	Demo contains just a few of the screen objects (or
"widgets") available to programmers from the SUIT library.  If you
need a specialized widget of your own, you can create one with the
programming calls that SUIT provides. Such "home grown" widgets can be
introduced into any SUIT program as easily as one from the standard
SUIT library.

	Try clicking on the "bounded value" widget found in the lower
left hand corner. This is a widget that allows the user to specify a
number between a minimum and maximum value. 
	

	The Other Widgets in Demo:
	----------------------------------
	o Bouncing balls (just for fun)
	o A label widget for displaying text
	o A bounded value widget.
	o A polygon widget (used mostly for demonstration
	  purposes)
	o A menu widget 
	o A set of radio buttons for mutually exclusive choices
	o A Text editor 
	 (The simple editing commands are customizable, but default
	 to those used by the popular text editor, Emacs)
	o A scrollable list of text for selecting
	 words/lines of text from a list.
	o An on/off switch
	o A type-in box for letting users specify strings
	  (Also Emacs)
	o A set of color chips for selecting colors
	o a UVa Logo !
	o A set of buttons to exit the program.


	There are several other widgets, like dialog boxes and
	file selectors that are also part of the standard SUIT 
	distribution, but are not shown in Demo.	

	Try interacting with the various widgets in Demo.


MANIPULATING A SUIT INTERFACE
=====================================

	Moving Widgets
	--------------
	SUIT gives you the ability to move and resize widgets while
	the application is running.

	To move a SUIT widget:
	1.) Hold down both the SHIFT and CONTROL keys with one
	 hand.
	2.) With the other hand, move the cursor near the center
	 of the widget you'd like to move and press and hold down
	 the leftmost mouse button. A dashed outline of the widget
	 should appear and follow the cursor until you release the
	 mouse button, at which point the widget will be placed at 
	 the new location and you can release the SHIFT and CONTROL keys.

	Try moving the bounded value widget.


	SHIFT and CONTROL: The SUIT-keys
	--------------------------------
	The SHIFT and CONTROL keys are used as a signal to SUIT that you wish
	to interact with the interface as the interface designer (letting you
	move and resize things), not as a user of the application (letting you
	move the needle on the bounded value up and down). Whenever
	you are holding down the SHIFT and CONTROL keys, you're
	"talking to SUIT" and whenever you are not,
	you're "talking to the application". In the rest of this overview, we
	will precede any operation which requires you to use the SHIFT and
	CONTROL keys with the prefix "SUIT-". For example, "SUIT-a" means
	"hold down the SHIFT and CONTROL keys and press the letter `a`on the
	keyboard". Similarly, "SUIT-click" means "hold down the SHIFT and
	CONTROL keys, and click on the left mouse button".


	Selecting Widgets
	-----------------
	SUIT provides several other means by which you can change the
	appearance of widgets in your interface. All of these, however,
	require you to first select the object you wish to change. To do this,
	SUIT-click on it.
 
	Try selecting the bounded value. When the bounded value is selected, 
	"handles" appear around the edges.


	Deselecting Widgets
	-------------------
	An object may be deselected either by SUIT-clicking on it again, or by
	SUIT-clicking anywhere on the screen. 

	Try deselecting the bounded value. The handles should go away.


	Resizing Widgets
	----------------
	In addition to moving widgets, you can also resize them. To do this:
	1.) SUIT-click on the object you wish to resize
	2.) SUIT-drag one of the handles

	Practice resizing the bounded value. Try to make it taller and
	thinner. Now make it square.


	Cycling Widgets Among Display Styles
	------------------------------------

	The bounded value you have been manipulating allows the user to specify a
	number from 1 to 10. There are any number of ways that a bounded value
	like this could be displayed. SUIT provides four built-in display
	styles: a simple slider, a pie-chart display, a scroll bar,
	and a speedometer-like display: To change a given widget from 
	its current display style to another, you can cycle the
	widget. 
	To do this:

	1.) Move the cursor to the center of the widget
	2.) Type SUIT-c 

	Cycle to each of the five available display styles and click
	on them to see how they work.



THE SUIT PROPERTY EDITOR
================================

What if we wanted to change something about a widget other than its
location, such as its color? Each SUIT widget maintains information like this in 
the form of a collection of variables or properties that govern the widget's 
appearance and functionality. To view or change any of the properties that 
a widget has, you can invoke the SUIT property editor. You will notice that 
properties, like variables, come in different types; SUIT supports a wide 
variety of types including double, string, boolean, and more advanced 
types like color, font, and enumeration.

To become familiar with the property editor, try these steps:
	1.) Make sure you are still running demo.

	2.) Move the cursor to the center of the polygon widget. Type SUIT-e.

	3.) BOOLEANS: Click on the object property FILLED. It should change to 
		NO. Notice that the polygon is not filled anymore.

	4.) TEXT: Click on the object property called NUMBER_OF_SIDES. A text 
		box will appear. Type a CONTROL-k to delete the text currently in the 
		textbox. (This means hold down the control key and press "k") Type 
		in the number 3 and press RETURN. Notice that the
		polygon has 3 sides. 
		
		Here are some other useful editing keys:
		o Delete character	CONTROL-d
		o Forward a character	CONTROL-f
		o Backward a character	CONTROL-b
		o Kill Line		CONTROL-k
		o Beginning of Line	CONTROL-a
		o End of Line		CONTROL-e

	5.) COLOR: If you have a color monitor, Click on the
		object property FOREGROUND_COLOR. Select a bright color from
		the choices offered and press OK. Notice
		that the color of the polygon has changed to the 
		color selected on the color chips.

	6.) Exit the property editor by clicking on "OK."


	More About Properties 
	--------------------- 

	As you have seen, each screen object has various properties
	which store information about the object's appearance and
	functionality. If these properties were always stored with
	each object, it would be hard to enforce consistency. For
	example, if all the labels in an application were green, and
	you decided to make them all red, you would have to change
	them all one by one. SUIT addresses this problem by allowing
	properties to be stored at three different levels: the
	object level, the class level, and the global level.  These
	nested levels are shown below.

	To find a property, SUIT starts at the object level. If the
	property in question has not been defined at the object
	level, the search is performed again at that widget's class
	level. If the search fails here too, SUIT searches the
	global level, where if it is still not found, a default
	value for that type of property is returned.
	
	EXAMPLE: Suppose the code for a button widget called 
	"Bert" initiates a property lookup on a property called 
	FOREGROUND_COLOR. SUIT first looks to see if a
	FOREGROUND_COLOR property has been specified for Bert at the
	object level. If so, SUIT returns the value of the property. 
	If not, SUIT looks to see if there is a FOREGROUND_COLOR 
	property specified at the class level for all widgets that
	belong to the class called "buttons". If not, SUIT searches
	the global level for FOREGROUND_COLOR, at which point, if the
	property is still not found, the default value of black will
	be returned.
	

	Experimenting with Property Lookups
	-----------------------------------
	To get a better idea of how property lookup works, perform 
	the following steps. 

	1.) INVOKE THE PROPERTY EDITOR: Type SUIT-e over the label at the top 
	of the screen that says "SUIT".

	Note that the label has no HAS_BORDER property at the object level. This 
	means that the label is inheriting its HAS_BORDER from a higher level -- in 
	this case, the class level. Change the class level HAS_BORDER
	property to YES by clicking on it.

	2.) EXIT THE PROPERTY EDITOR: Click on the OK button. 

	All the labels now have borders because they are all getting their boolean 
	HAS_BORDER property from the Class level. Suppose you wanted all but 
	one of the labels to have a border? To do this, you have the single label 
	override his class level property by giving him a property at the object 
	level. We'll do this by copying the label's class property to
	the object level.

	3.) COPYING PROPERTIES: Invoke the property editor again on the same 
	label. We are now going to copy a property from the Class level to the 
	Object level. To do this: Press and hold the mouse button down (No 
	need to use SUIT keys here) over the HAS_BORDER property listed 
	under Class Properties and move your mouse until the cursor is over 
	the Object Properties box. When you release the mouse button, the 
	property will be copied from the Class level to the Object level. 

	4.) Change the Object level HAS_BORDER property of this label back to 
	NO. Exit the property editor again. Notice that this label is now differ
	ent from the others: it has no border because this label finds its 
	HAS_BORDER property at the object level (where HAS_BORDER is NO), 
	not the class level (where the value is YES). 

	What if we wanted this label to revert to inheriting its HAS_BORDER from 
	the Class? We need to delete the object level property to let
	this happen. 

	5.) DELETING PROPERTIES: Invoke the property editor one last time on 
	the label. Dispose of the object level HAS_BORDER property by drag
	ging the property from the object level listing to the trash can icon. 
	Notice that the label has gone back to inheriting its HAS_BORDER 
	property from its class. 

	6.) EXIT PROPERTY EDITOR: Click on OK.
	
	

INTERACTIVE CREATION OF WIDGETS
=======================================
	SUIT is capable of adding widgets to an application on the
fly. In this next section, we are going to add a clock widget.

	To create a clock widget on the fly:
	1.) Invoke the "New Widget" command by typing 
		"SUIT-n"
	3.) Select "clock" from the list of widget 
	    classes supplied
	4.) Press OK.

This same procedure can be used to add labels, buttons and other
widgets to an application without writing code. Adding functionality
to a widget can be done by writing code or by "exporting" a property...



EXPORTING PROPERTIES
==========================

	SUIT can attach program functionality interactively.

	Suppose you had a widget called "Ernie" and you wanted the
user to be able to control Ernie's foreground color through a set of
color chips some where in the application. Instead of adding a
SUIT_createColorChips() call to your code, writing the callback, and
recompiling the code, you could "export" Ernie's FOREGROUND COLOR to the
application's interface via the export button in the property editor.

	Exporting a property means having SUIT add another widget to
your application interface whose sole job is to control some property
of another widget. SUIT can do this because for every data type that
SUIT manipulates (integers, booleans, strings, etc.) there is a
corresponding widget that can represent that type (bounded values,
check boxes, type-in boxes, and respectively). 

	To export the polygon's FILLED property: 

	1.) If you're not still running demo, start up the demo program again.
	2.) Invoke the property editor (SUIT-e) on the polygon widget.
	3.) Drag the FILLED property from the object level listing to the export
	panel (looks like a moving van), in the same way you might drag a
	property to the trash can.  Select OK to exit the property editor.

Notice that there is now a new on/off switch in the application (this
is the kind of widget that controls boolean data types). Click on the
switch and the polygon will change from filled to unfilled and back
again.
	New functionality. No new code.



WHO CAN GET SUIT?
==============================
SUIT, including all its source code, is available without charge
to Universities and other non-profit institutions.  For-profit
organizations can send email to 

	suit@uvacs.cs.virginia.edu 

to find out how they can help support graduate education in America.

WHAT DO I NEED AT MY SITE IN ORDER TO USE SUIT? 
===================================================
	This all depends on the platform you will use:

	X WINDOWS: 
		You will need at least X11R4 and gcc 2.1 or later.
		Or any ANSI-compatible C compiler. 
		(If all you have is gcc 1.37.X, send us mail.)
				
	MAC:
		Think C 5.0 

	DOS:
		DOS version 5.0 and Borland C++ version 3.1
	
	WINDOWS:
		Microsoft Windows 3.1 and Borland C++ version 3.1
	

HOW TO GET THE SUIT DISTRIBUTION
========================================
SUIT is available through anonymous ftp from
uvacs.cs.virginia.edu (128.143.8.29). Each SUIT distribution 
package comes with full source code and documentation, though
as explained below, the source and docs are available separately 
as well for those attempting to port SUIT to an architecture we do not
yet support. To set a standard SUIT distribution package for your 
machine: 


1.) On your system, make a directory that will hold the 
distribution. For example, in your home directory type:

		mkdir suit

The process of installing the SUIT distribution causes SUIT to 
create a new directory underneath the one you've created here.

2.) Change your current directory to this new location:

		cd suit

3.) Type the following command:

		ftp uvacs.cs.Virginia.EDU
		
	(if this doesn't work, try ftp 128.143.8.100 or
				   ftp 128.143.60.100)

 You should see something that looks like:

		Connected to 128.143.8.100
		220 uvacs FTP server (SunOS 4.1) ready.
		Name (128.143.8.100:CookieMonster):

	where "CookieMonster" is your login ID.


4.) At this prompt, type: 

		anonymous
	
	You should see something like this:
	
		331 Guest login ok, send ident as password.
		Password:

5.) Please type in your local login ID as a courtesy. This will not be
echoed back to you, so don't panic.
	You will see:

		230 Guest login ok, access restrictions apply.
		ftp>

6.) cd into the SUIT directory by typing:

		cd /pub/suit/distribution

7.) cd into the directory named after the hardware platform
	you intend to use:

	cd <machine_type>
	where <machine_type> is one of:

		sparc 		
		sun3
		sgi
		rs6000
	for example:
		cd sparc
			OR 
		cd sun3 
			ETC.

8.) VERY IMPORTANT: set the ftp transfer to use binary mode
	Type:
		binary

9.) transfer the archive
	Type:
		get <machine_type>.tar.Z

		for example:	
			get sparc.tar.Z
				OR
			get sun3.tar.Z
				ETC.

	This file is VERY large. Expect it to take
	several minutes to come over.
	
10.) leave ftp
	Type:
		quit

11.) uncompress the archive
	Type:
	uncompress < <machine_type>.tar.Z | tar xfh -
	
	for example:
		uncompress < sparc.tar.Z | tar xfh -

12.) CONGRATULATIONS! You've got yourself the SUIT library and header
files! You can now safely remove the <machine_name>.tar file if you so
desire.

13.) Follow the directions in the top level README file to prepare
the SUIT distrbution for your site.


GETTING SUIT SOURCE
===========================
	Full source code comes with each distribution package of SUIT
	(same source for all architectures). 

	IF YOU ONLY WANT THE SOURCE, you can ftp it from uvacs, as
	described above

		ftp uvacs.cs.virginia.edu
		(Be sure to use binary transfer)
		
	in the file called	

		/pub/suit/distribution/JustSource/src.tar.Z



GETTING THE SUIT REFERENCE MANUAL
=========================================
	Each standard distribution package of SUIT comes with a
	complete reference manual which describes the SUIT library 
	calls. In the standard distribution, the manual comes in
	the form of a VERY long	postscript file that prints out 
	from last page to first.
	
	If it is more convenient for you to print the manual out from
	first page to last, or if you need just individual reference 
	manual chapters, those are distributed as well in the file 

		/pub/suit/distribution/JustDocs/doc.tar.Z

	which can ftp from uvacs as explained above. These files are
	called chap_01.ps, chap_02.ps, etc. The complete reference
	manual is in the file chap_all.ps.

	Again, be sure to use binary mode when getting this file.
	(type "binary" at the ftp prompt before typing "get")


ACKNOWLEDGEMENTS
========================

	Thanks for SUIT are due to its original author, Nathaniel Young, and
	to Roderic Collins, Matt Conway, Jim Defay, Pramod Dwivedi, Robert
	DeLine, Brandon Furlich, Rich Gossweiler, Chris Long, William
	McClennan, Kim Passarella, and Randy Pausch. This work was supported
	in part by the National Science Foundation, the United Cerebral Palsy
	Foundation, the Virginia Engineering Foundation, the Virginia Center
	for Innovative Technology, and SAIC.
	
	TELL US WHAT YOU THINK: 
	We would like to hear from you: if you have 
	any comments about SUIT, please send electronic mail to 
	
		suit@uvacs.cs.Virginia.EDU 
	
	We are very interested in your comments as well as your reports of
	errors, unclear sections, or omissions you find in any part of SUIT.
	
	SUIT (c) 1990, 1991 , 1992
	Copyright Rector and Visitors of the University of Virginia

-- 
Bradley Smith			 brad@bradley.edu ---  309-677-2337
Network & Technical Services @ Bradley University, Peoria, IL

"It's amazing how much scrap metal you get from 4 cans of beer"