DESCRIPTION

	The FlatExclusives widget is a special class of OLIT widget, called a "Flat Widget".  
	A Flat widget is basically a single widget which manages a set of 'like' components
	(Rectangular items in this case).  The flat widget gives the appearance of many widgets, 
	however they consume only a fraction of memory as the same implementation using an
	equivalent normal widget hierarchy.

	The FlatExclusive widget implements an Exclusive Choice object using a single widget.  

	For more detailed and complete information on the FlatExclusives
	Widget, see the following sections in the OPEN LOOK Intrinsics Toolkit
	Widget Set Reference Guide:
		. FlatExclusives
		. Flat Widget Layout
		. Flat Widget Functions

EXAMPLE CODE

The following code was written to Create a FlatExclusives Widget close to
the one shown in the Table (All color specific code has been removed for simplification):

/**************************************************************************************/
#include <X11/Intrinsic.h>
#include <X11/StringDefs.h>
#include <Xol/OpenLook.h>
#include <Xol/FExclusive.h>
#include <Xol/Caption.h>

#include <Xol/ControlAre.h>

/* Declare resources which we'll need to set for each individual
 * subobject in the Flat exclusives.
 */
typedef struct {
	XtArgVal label;		/* label string of subobject */
	XtArgVal background;	/* color of subobject */
} FlatExclusives;

String attributes[] = { XtNlabel, XtNbackground };



char *colors[] = {"WhiteSmoke","LavenderBlush","PeachPuff","MintCream",
		"SlateGray","MistyRose","Turquoise","LightSeaGreen",
		"DarkSalmon","BlueViolet","SteelBlue","LemonChiffon"};

static FlatExclusives subobjects[XtNumber(colors)];
Widget controlarea;


/******************************************************************
 * ConvertColorToPixel:  routine which converts a colorname to 
 *			 pixel value.
 *****************************************************************/
Pixel
ConvertColorToPixel(w, colorname)
Widget w;
String colorname;
{
	XrmValue src, dst;
	Pixel color;

	/* Given a colorname, we need to Convert it to a Pixel
	 * and return that value.
	 */

	src.size = strlen(colorname) + 1;
	src.addr = colorname;
	dst.size = sizeof(Pixel);
	dst.addr = (caddr_t)&color;

	if (!XtConvertAndStore(w, XtRString, &src, XtRPixel, &dst))
		return(NULL);

	return(color);
}
/*****************************************************************
 * selectedCB:  Callback called when one of the sub-items on the
 * 		exclusive choice is selected.
 *****************************************************************/
void
selectedCB(w, clientData, callData)
Widget w;
XtPointer clientData, callData;
{
	OlFlatCallData *fcd = (OlFlatCallData*)callData;
	int subitem = fcd->item_index;  /* index of item selected */

	/* A Color has been selected OFF the Flat exclusive
	 */

	XtVaSetValues(controlarea,
			XtNbackground,(XtArgVal)subobjects[subitem].background,
			NULL);
}
/*****************************************************************/

main(argc, argv)
int argc;
char **argv;
{
	Widget toplevel, caption, flatexclusive;
	XtAppContext app;
	int i;

	OlToolkitInitialize(NULL);
	toplevel = XtAppInitialize(&app, "Test", 
				(XrmOptionDescRec *)NULL,
				(Cardinal)0, (int *)&argc, argv,
				(String *)NULL, (ArgList)NULL, 0);

	controlarea = XtVaCreateManagedWidget("controls", 
				controlAreaWidgetClass,
				toplevel, 
				XtNvPad,	(XtArgVal)10,
				XtNhPad,	(XtArgVal)10,
				NULL);

	caption = XtVaCreateManagedWidget("caption",
				captionWidgetClass,
				controlarea,
				XtNlabel,	"Colors:",
				XtNalignment,	(XtArgVal)OL_TOP,
				XtNposition,	(XtArgVal)OL_LEFT,
				NULL);

	/*
	 * Load up FlatExclusives data structure with the
 	 * resource values for each subobject.
	 */
	for (i = 0; i < XtNumber(subobjects); i++)
		{
		subobjects[i].background = 
				(XtArgVal)ConvertColorToPixel(toplevel,colors[i]);
		subobjects[i].label = 	
				(XtArgVal)XtNewString(colors[i]);
		}

	/*
	 * Create Exclusive Widget to hold color choices...
	 */
	flatexclusive = XtVaCreateManagedWidget("flatexclusive", 
			    	flatExclusivesWidgetClass, 
			    	caption,
				XtNlayoutType,	(XtArgVal)OL_FIXEDCOLS,
				XtNmeasure,	(XtArgVal)2,
				XtNitems,	(XtArgVal)subobjects,
				XtNnumItems,	(XtArgVal)XtNumber(subobjects),
				XtNitemFields,	(XtArgVal)attributes,
				XtNnumItemFields,(XtArgVal)XtNumber(attributes),

				/* Add routine to get called when subobject is selected
				 * Note: we cannot add this as a normal callback using
				 * XtAddCallback.
				 */
				XtNselectProc,	(XtArgVal)selectedCB,
			    	NULL);


	XtRealizeWidget(toplevel);
	XtAppMainLoop(app);

}
/******************************END EXAMPLE****************************/




RESOURCES

________________________________________________________________________________________________
Resource Name		Type		Default		Brief Description
________________________________________________________________________________________________
XtNaccelerator		String		NULL		String which defines accelerator key
XtNacceleratorText	String		Dynamic		string to be displayed as accelerator
XtNancestorSensitive	Boolean		TRUE		Will immediate parent receive events?
XtNbackground		Pixel		White		background color of widget
XtNbackgroundPixmap	Pixmap		(none)		pixmap used for tiling the background
XtNborderWidth		Dimension	0		width in pixels of object border
XtNclientData		XtPointer	NULL		data supplied to callback procedures
XtNconsumeEvent		XtCallbackList	NULL		routines called on virtual events
XtNdefault		Boolean		FALSE		is subobject default item?
XtNdepth		Cardinal	(parent's)	depth (in pixels) of widget
XtNdim			Boolean		FALSE		is subobject dimmed?
XtNfont			XFontStruct*	OPEN LOOK font	font used in label
XtNfontColor		Pixel		Black		label font's color
XtNforeground		Pixel		Black		foreground color of widget
XtNgravity		int		CenterGravity	the gravity of subobjects as group
XtNhPad			Dimension	4		size in pixels of margin on sides 
XtNhSpace		Dimension	4		space in pixels between columns
XtNheight		Dimension	(calculated)	height of widget's window in pixels
XtNinputFocusColor	Pixel		Red		color of input focus indicator
XtNitemFields		String*		NULL		pointer to resources set for subobject
XtNitemMaxHeight	Dimension	OL_IGNORE	max allowable height for subobjects
XtNitemMaxWidth		Dimension	OL_IGNORE	max allowable width for subobjects
XtNitemMinHeight	Dimension	OL_IGNORE	min allowable height for subobjects
XtNitemMinWidth		Dimension	OL_IGNORE	min allowable width for subobjects
XtNitems		XtPointer	NULL		pointer to subobject structure
XtNitemsTouched		Boolean		False		see manpage
XtNlabel		String		(classname)	string used for label
XtNlabelImage		XImage *	(classname)	pointer to image used for label
XtNlabelJustify		OlDefine	OL_LEFT		position of label relative to checkbox 
XtNlabelTile		Boolean		FALSE		should background be tiled with pixmap?
XtNlayoutHeight		OlDefine	OL_MINIMIZE	resize policy for flat widget
XtNlayoutType		OlDefine	OL_FIXEDROWS	layout policy for subobjects
XtNlayoutWidth		OlDefine	OL_MINIMIZE	resize policy for flat widget
XtNmanaged		Boolean		TRUE		is subobject managed?
XtNmappedWhenManaged	Boolean		TRUE		will widget be mapped when managed?
XtNmeasure		int		1		* number of rows/cols or fixed hgt/wth
XtNmnemonic		Usigned char	NULL		key used to activate widget
XtNnoneSet		Boolean		FALSE		can NO subobjects be set at one time?
XtNnumItemFields	Cardinal	0		number of resources set for subobject
XtNnumItems		Cardinal	0		number of subobjects in Flat widget
XtNreferenceName	String		NULL		see manpage		
XtNreferenceWidget	Widget		NULL		see manpage
XtNsameHeight		OlDefine	OL_ALL		size policy for subobjects' height
XtNsameWidth		OlDefine	OL_COLUMNS	size policy for subobjects in column
XtNselectProc		XtCallbackProc	NULL		routine called when subobject selected
XtNsensitive		Boolean		TRUE		will widget receive input events?
XtNset			Boolean		TRUE		current state of subobject
XtNtraversalOn		Boolean		TRUE		is mouseless turned "on" for widget?	
XtNunselectProc		XtCallbackProc	NULL		routine called when subobject unselected
XtNuserData		XtPointer	NULL		storage for user defined data
XtNvPad			Dimension	4		size in pixels of top/bottom margins
XtNvSpace		Dimension	4		space in pixels between rows
XtNwidth		Dimension	(calculated)	width of widget's window in pixels
XtNx			Position	0		x coord of widget's upper left corner
XtNy			Position	0		y coord of widget's uuper left corner



	
