This directory contains the following subdirectories:

	bitmaps			holds common bitmap files, no programs
	callback		using callbacks
        dragdrop                demonstrates different drag-drop concepts
        entry_field             introducing the sequential entry field
	filec			file completion program ala tcsh
	general			some small, real programs
	glyph			using glyph objects
        help                    demonstrates the OI help mechanism
	international		multiple language programs
	io_select_loop		grabbing tty input
        layout                  example of using layout methods
	menu			menu examples
        panedbox                using the paned box objects
	resource		programs using resources
        scrolling               using gang scrolling
	simple			hello_world (good place to start)
	speriodic		a periodic table of OI objects
	subclass		how to derive subclasses
	translation		using the translation mechanism

Subdirectories are named for concepts or objects.

The programs contained in this directory tree will guide the reader
through writing OI programs.  The reader is already assumed to
know the basics of C++, but is not assumed to be an expert.

To prepare these demos for "make"-ing in your local environment, edit
the file "config.mk" in the top level of the demos directory.  This
specifies the exact location of the OI include files and libraries on
your system.  Then, in each demo directory, move the file
"makefile.site" to "Makefile" or specify "make -f makefile.site" when
building each demo.

This directory tree contains the following demo programs:

1. Introductory 

	- hello_world (subdirectory simple)
		Make:	hello_world
		Files:	hello_world.C
	
		This program introduces the user to OI, and discusses
		how to approach the OI library and OI documentation at
		length.

	- speriodic (subdirectory speriodic)
		Make: speriodic
		Files: speriodic.C, *.bm, *.txt

		This program shows the basic OI objects in a single
		window.

2. Basic object manipulation 

	- Glyphs -- simple (subdirectory glyph)
		Make:	simple_glyph
		Files:	simple_glyph, bitmaps/*.xbm

		This program creates one of all the major types of
		glyphs from bitmap(1) files.  It creates a simple
		glyph, a highlighting glyph, a glyph that has
		different normal and active bitmaps, a 3d-glpyh, and
		a two-color glyph.

	- Glyphs -- intermediate (subdirectory glyph)
		Make:	simple_ls
		Files:	simple_ls.C bitmaps/*.xbm

		This program creates a filemgr-like display of all the
		files in a given directory.  It doesn't sort these
		files, you can't interact with the icons, and the
		directory is a static list.  This program concentrates
		on the basics of using glyphs in a real program.

	- Glyph -- Advanced (subdirectory glyph)
		Make:	complex_ls
		Files:	complex_ls.C bitmaps/*.xbm

		This program is an advanced version of simple_ls.C.
		It fleshes that program out by sorting the files by
		name, adding file viewing for ascii files, execution
		of executables, and changing directories.  C++
		subclassing is used heavily and should provide a good
		example.

	- Menus -- simple (subdirectory menu)
		Make:	simple_menus
		Files:	simple_menus.C

		This program uses a single cell spec to create all five
		types of menus, three types of abbreviated menus, and
		five types of scroll menus.  This program simply demonstrates
		the ease with which menus can be created.

	- Menus -- interactive (subdirectory menu)
		Make:	active_menu
		Files:	active_menu.C

		This program creates a simple menu from a cell spec, and
		sets up callbacks on those menu cells to dynamically modify
		the original menu.  This program demonstrates creating
		a simple menu, callbacks, associated objects, changing cell
		labels, and other concepts.

	- Menus -- complex (subdirectory menu)
		Make:	make hierarchy
		Files:	hierarchy.C

		This program demonstrates dynamically creating a menu, by
		recursively walking through the OI class hierarchy.  The
		program will print a copy of the class hierarchy to stdout
		if command line argument (-print) is used.


	- Callback mechanisms -- example using a C function for the
				 callback entry check. 
				(subdirectory callback)
		Make:	make callbackC
		Files:	callbackC.C

		This program demonstrates setting a character check
		callback on an entry field using a C function as the
		callback.  The program creates a hex entry field, and
		uses the character check callback to ensure that typed
		characters are hex [0-9, a-f, A-F]. 

	- Callback mechanisms -- example using a C++ member function
				 for the callback entry check.
				(subdirectory callback)
		Make:	make callbackM
		Files:	callbackM.C

		This program demonstrates setting a character check
		callback on an entry field using a C++ member function
		as the callback.  This program creates two entry
		fields, fruit and vegetable, which validate the
		entries that the user types.  The entry field uses
		member functions from the FRUIT and VEGETABLE objects
		to validate entries for the objects.

	- Callback vs Translations -- Comparative example of callbacks
					and translations (subdirectory filec)		

		Make:	make filec_callbk filec_trans
		Files:	filec_callbk.C, filec_common.C, filec_trans.C,
			config.filec

		These two programs demonstrate rudimentary file
		completion via 	two different mechanisms.
		filec_callbk demonstrates how to accomplish this via
		a character callbk for each character typed into the
		entry field.  It is simple, but is not configurable.
		filec_trans demonstrates how to use translations for
		the same task.  The translations are more flexible,
		require less code (but more careful placement of some
		operations), and will work with any key, not just any
		character.  config.filec gives the translations the
		author uses.  filec_common.C are common routines used
		by both versions of this demo. 

	- Sequential Entry Fields (subdirectory entryfield)
		Make:	make seq_entry_ck
		Files:	seq_entry_ck.C

		This program was created to introduce special sequential
		entry field increment, decrement, and entry check routines.
		This example shows how to set up a sequential entry field
		to display the names of days and months.


3. General Examples

	- smore	(subdirectory general)
		Make:	make smore
		Files:	smore.C
	
		This program demonstrates how to write a simple
		OI application.  It demonstrates the proper use
		of the following OI objects:
			OI_menu
			OI_entry_field
			OI_scroll_text
		as well as demonstrating size_tracking and callback
		concepts.

	- sfontmore	(subdirectory fonts)
		Make:	make sfontmore
		Files:	sfontmore.C
	
		This program is a version of smore which allows
		switching between various fonts.

	- Xlib_calls (subdirectory general)
		Make:	make Xlib_calls
		Files:	Xlib_calls.C

		This program demonstrates how to easily integrate Xlib
		calls (XClearArea, XCopyArea, XDrawLine, etc) into an
		OI application.  This application displays a damped
		sine wave in an OI_box.  The region displayed is controlled
		by an OI_scroll_bar.

	- Paned Box	(subdirectory panedbox)
		Make: 	make fileb
		Files: 	fileb.C

		This demo shows the use of the OI object paned_box.

4. Help

	- Help_files - resource (simple) approach (subdirectory help)
		Make	make keyhelp_res
		Files:	keyhelp_res.C
			keyhelp.hp

		This program demonstrates how to specify context
		sensitive help through the resource mechanism.

	- Help_files - programatic (complex) approach (subdirectory help)
		Make	make keyhelp
		Files:	keyhelp.C
			keyhelp.hp

		This program demonstrates how to specify context
		sensitive help through function calls.

5. Resources and command line arguments

	- Resources and Command Line Args (subdirectory resource)
		Make:	make resources
		Files:	resources.C

		This program demonstrates how a program can specify
		and fetch both additional resources and command line
		arguments.  The program presents a calendar spreadsheet
		which retrieves its start and end times from either
		the command line, ~/.Xdefaults, or a resource file
		specified through the -config command line argument.

6. Intermediate OI Concepts

	- Translations -- using c functions. (subdirectory translation)
		Make:	make transC
		Files:	transC.C
			trans.ad

		This program demonstrates the use of the translation mechanism
		to add callbacks to Mouse events.  The program demonstrates the
		use of c functions for the callbacks. This program should be
		executed as:
			./transC -config trans.ad
		Otherwise the appropriate mouse actions will not be set.
		
	- Translations -- using C++ member functions.  (subdirectory translation)
		Make:	make transM
		Files:	transM.C
			trans.ad

		This program demonstrates the use of the translation
		mechanism to add callbacks to Mouse events.  The
		program demonstrates the use of C++ member functions
		for the callbacks. This program should be executed as:
			./transM -config trans.ad
		Otherwise the appropriate mouse actions will not be set.

	- Translations -- using a C language function as callbacks. (subdirectory translation)
		make: 	make bargraph
		Files: 	bargraph.C
			trans.ad

		This program demonstrates the use of the translation 
		mechanism to add callbacks to Mouse events.  

	- Translations -- using C++ member functions as callbacks (subdirectory translation)
		make:	make nonOI
		File:  nonOI.C

		This program demonstrates the use of the translation 
		mechanism to add callbacks to Mouse events.  This 
		program shows how to get member function callbacks on 
		a non-OI object.

	- Translations -- using translations to call enter/leave notifier (subdirectory translation)
		make:	make notifier
		File:  notifier.C

		This program demonstrates the use of the translation 
		mechanism to add callbacks to enter/leave notify
		As the user moves the cursor over the display of 16
		glyphs, the program prints out enter/leave events.

	- Internationalization  (subdirectory international)
		Make:	make internat
		Files:	internat.C
			internat.french
			internat.german
			internat.spanish
			internat.kanji
	
		This program provides an example of how to do customization
		of applications for international usage.  With the usage of
		language-specific resource files, text items in the application
		can appear in the chosen language for the user.

	- Select		(subdirectory io_select_loop)
		Make:	make select
		Files:	select.C

		This program demonstrates adding io callbacks to the
		OI dispatch routine.  The program opens the parent
		xterm.  All text entered on the xterm is captured and
		displayed within the scrolled text object.

	- Scrolling	(subdirectory scrollng)
		Make: 	make gang_scroll
		Files: 	gang_scroll.C

		This demo program shows how to set up a pair of scroll menus
		such that they are both controlled by the scroll bar of the
		lower one.
		
	- Layout -- layout method tester (subdirectory layout)
		Make: 	make complex
		Files: 	complex.C

		This demo program allows the user to add objects 
		to a sample box and watch how different layout methods
		cause different interaction between the layed out objects

	- Layout -- tree layout demonstration (subdirectory layout)
		Make: 	make vtree
		Files: 	vtree.C

		This program shows a simple example of tree layout.


7. Intermediate Library Concepts

	- SubClassing -- simple (subdirectory subclass)
		Make:	make simpleSubcl
		Files:	simpleSubcl.C

		This program demonstrates simple subclass from leaf.
		The program creates a hex entry field object based on the
		OI entry field object.
	

	- SubClassing -- complete (subdirectory subclass)
		Make:	make complexSubcl
		Files:	complexSubcl.C

		This program demonstrates a complete subclass from leaf.
		The program creates a hex entry field object based on the
		OI entry field object.  This program also demonstrates
		three additions to the simple subclass:
			- register the class so that class hierarchy
			  queries will work. 
			- add resources.
			- add interface function in case of
			  constructor failure. 

8.  Drag and Drop  (all subdirectory dragdrop)

	- Drag and Drop - dragging a live object around the screen
		Make: 	make draglive
		Files: 	draglive.C

		This demo shows how to use the drag and drop code to
		drag a live object around the screen

	- Drag and Drop - a sample file manager
		Make: 	make filemgr
		Files: 	filemgr.C

		A sample implementation of a file manager which
		implements a rudimentary drag and drop.

	- Drag and Drop - translations
		Make: 	make objdrag
		Files: 	objdrag.C

		This demo shows how to use translations to drag
		objects from one window to another.
		

	- Drag and Drop - receiver client
		Make: 	make receiver
		Files: 	receiver.C

		This client demonstrates a "reciever" client that 
		can handle drops from some other client.  This 
		application sets up two drop sites: a "green" box
		and a non-rectangular drop site that is painted
		initially as a "red" cross.
		
		See the source code for more details.

	- Drag and Drop - sender client
		Make: 	make sender
		Files: 	sender.C

		This client demonstrates a "sender" program that
		allows the user to drag data from and drop it on
		other clients.
