`co(4,7);─────────────────────── /// Rectangle Functions ────────────────────────────`co();

┌──────────────────────────────────────────────────────────────────────────┐	
│          `keyword(set_rect,/// set_rect);                  `keyword(rect_equal,/// rect_equal);        `keyword(rect_overlap,/// rect_overlap);        │
│          `keyword(offset_rect,/// offset_rect);               `keyword(cr_inrect,/// cr_inrect);                             │
└──────────────────────────────────────────────────────────────────────────┘

		The UltraWin library uses the structure RECT to handle information
	dealing with rectangular sections of the screen, as in the WINDOW
	structure.	Included are functions to define the rectangle, check to
	see if one rectangle overlaps another, and several other routines
	that you may wish to utilize in your program.

`co(10,1);/// set_rect`co();   `keyword(source,[UW_WIN.C]~set_rect);
	Takes the variable of type RECT passed by pointer, and sets the upper
	left corner and lower right corner to the coordinates passed as
	integers.

Prototype:
	void set_rect(RECT *rectp, int x1, int y1, int x2, int y2);

Parameters:
`co(11,1);	RECT *rectp;`co();
		A pointer to the rectangle variable.
`co(11,1);	int x1, y1, x2, y2`co();
		The coordinate pair for the upper left corner (x1,y1) and the
		lower right corner (x2,y2) of the rectangle.

Usage:
	RECT r;
	...
	set_rect( &r, 10, 10, 20, 20 );

`co(10,1);/// rect_equal`co();   `keyword(source,[UW_WIN.C]~rect_equal);
	Checks to see if the two rectangles are the same.

Prototype:
	int rect_equal(RECT r1, RECT r2);

Parameters:
`co(11,1);	RECT r1, r2;`co();
		The two rectangles to compare.

Usage:
	RECT r1, r2;
	...
	if (rect_equal( r1, r2 )) {}

`co(10,1);/// rect_overlap`co();   `keyword(source,[UW_WIN.C]~rect_overlap);
	Reports on the relationship between two windows.  This function
	will return the status as one of the following (defined in uw.h):
		1) FIRST_ENCLOSED
				 The first rectangle is enclosed within the second.
		2) SECOND_ENCLOSED
				 The second rectangle is enclosed within the first.
		3) OVERLAP
				 The rectangles overlap
		4) NO_OVERLAP
				 The rectangles do not overlap.

Prototype:
	int rect_overlap(RECT *r1, RECT *r2);

Parameters:
`co(11,1);	RECT r1, r2;`co();
		The two rectangles whose relationship to find.

Usage:
	RECT r1, r2;
	int status;
	...
	status = rect_overlap( r1, r2 );

`co(10,1);/// offset_rect`co();   `keyword(source,[UW_WIN.C]~offset_rect);
	Moves the rectangles coordinates by a fixed amount in both the
	x (column) and y (row) direction.  The fixed amount can either
	be positive or negative.

Prototype:
	void offset_rect(RECT *rectp, int col, int row);

Parameters:
`co(11,1);	RECT *rectp;`co();
		A pointer to the rectangle variable.
`co(11,1);	int col, row`co();
		The offsets to add to the rectangle's coordinates.

Usage:
	RECT r;
	...
	offset_rect( &r, 5, -4 );

`co(10,1);/// cr_inrect`co();   `keyword(source,[UW_WIN.C]~cr_inrect);
	Check to see if a particular location is inside (or on the border 
	of) the rectangle passed.

Prototype:
	int cr_inrect(int col, int row, RECT rect);

Parameters:
`co(11,1);	int col, row`co();
		The coordinate to see if it lies in the rectangle.
`co(11,1);	RECT r;`co();
		The rectangle to check.

Usage:
	RECT r;
	...
	if (cr_inrect( 5, 5, r )) {}

`co(4,7);──────────────────────────── /// Data Entry ────────────────────────────────`co();

┌──────────────────────────────────────────────────────────────────────────┐	
│           `keyword(wn_gets,/// wn_gets);                            `keyword(Masks/Templates,/// Masks/Templates);             │
│           `keyword(Validation Chars,/// Validation Chars);                   `keyword(Strip Mask Option,/// Strip Mask Option);           │
└──────────────────────────────────────────────────────────────────────────┘

	One of the most flexible of all functions in the UltraWin library
	is wn_gets.  With this one function you can have the user enter
	dates, times, prices, strings, and any other type will full
	control over every character entered!  UltraWin V2.00 adds an even
	more powerful lower level function now called by wn_gets to enhance
	the capabilities even further.  Full compatibility is maintained.
  The new function called wn_gets_ll (which wn_gets calls) has added
  the capability to uppercase the first char of each word, strip the
  mask completely, only strip the end, or not strip at all.  More
  importantly, it can allow the user to input a string longer than the
  display width of the field and will scroll within this region
  automatically! It can also display arrows to show the user that the
  string has data to the left or right of the current display field.
  If this isn't enough for you, we've added the ability to call your own
  validation function for every key pressed in wn_gets_ll!  This allows
  you to validate the user's input "as it happens", and allows you to
  customize the validation routine for any data entry task.
  see `keyword(set_validation_func,/// set_validation_func);

`co(10,1);/// wn_gets`co();   `keyword(source,[UW_ENTRY.C]~wn_gets);
	Get input from the user according to the restrictions of the mask
	and template strings in the window passed by pointer.  This 
	function will pass back the input either with the mask characters
	included in the string, or stripped out.	A -1 is returned if the
	mouse is clicked off of the string, and one of the values KEY_UP,
	KEY_DN, KEY_PGUP, KEY_PGDN, KEY_ESC, KEY_ENTER or KEY_TAB (all
	defined in uw.h) are returned if pressed.  Read about the mask and
	template strings for more information.

Prototype:
	int wn_gets( char *str, char *mask, char *template, int m_att,
							int strip_mode, WINDOW *wnp );

Parameters:
`co(11,1);	char *str`co();
		The string to be returned by the function.
`co(11,1);	char *mask`co();
		The mask string.
`co(11,1);	char *template`co();
		The template string.
`co(11,1);	int m_att`co();
		The attribute (colors) to use when displaying the string.
`co(11,1);	int strip_mode`co();
		Set to 1 (STRIP_ON) to strip mask characters out of result,
		or set to 0 (STRIP_OFF) for full mask and result.
`co(11,1);	WINDOW *wnp;`co();
		A pointer to the window in which entry is to take place.

Usage:
	WINDOW *wnp;
	int result;
	char s[80];
	...
	result = wn_gets( s, "(___)-___-____", "###  ### ####",
										wnp->att, STRIP_ON, wnp);

`co(10,1);/// wn_gets_ll`co();   `keyword(source,[UW_ENTRY.C]~wn_gets_ll);
	This function has the same capabilities as wn_gets() and more. wn_gets_ll
	has the capability to uppercase the first char of each word, strip the
  mask completely, only strip the end, or not strip at all.  More
  importantly, it can allow the user to input a string longer than the
  display width of the field and will scroll within this region
  automatically! It can also display arrows to show the user that the
  string has data to the left or right of the current display field.
  If this isn't enough or you, we've added the ability to call your own
  validation function for every key pressed in wn_gets_ll!  This allows
  you to validate the user's input "as it happens", and allows you to
  customize the validation routine for any data entry task.
  see `keyword(set_validation_func,/// set_validation_func);

Prototype:
	int wn_gets_ll( char *str, char *mask, char *template, int m_att,
							int flags, int disp_width, WINDOW *wnp );

Parameters:
`co(11,1);	char *str`co();
		The string to be returned by the function.
`co(11,1);	char *mask`co();
		The mask string.
`co(11,1);	char *template`co();
		The template string.
`co(11,1);	int m_att`co();
		The attribute (colors) to use when displaying the string.
`co(11,1);	int flags`co();
   G_STRIP        strips the entire mask from the string.
                * 12/04/91 = 120491, (432)-555-3421 = 4325553421
   G_STRIP_END    strips the end of the string only.
                * John Doe____ = John Doe
   G_UP_FST_CHAR  convert the first letter of each word to uppercase
                * this is a test = This Is A Test
   G_ARROW        displays left and right arrows if display width is less
                  than field width. NOTE: This requires an additional
                  screen/window space before and after the field.
   G_VALIDATE     call the validation function set by `keyword(set_validation_func,/// set_validation_func); 
`co(11,1);	int disp_width`co();
		The number of characters to display.  If less than the length of
		the input field, the display field will scroll.

`co(11,1);	WINDOW *wnp;`co();
		A pointer to the window in which entry is to take place.

Usage:
	WINDOW *wnp;
	int result;
	char s[80];
	...
/*---- strip mask, convert first character of each word to uppercase, -----*/
/*------- and only display 6 characters, using arrows to show more --------*/
	result = wn_gets_ll( s, "______________", "AAAAAAAAAAAAA", wnp->att,
		G_STRIP | G_UP_FIRST_CHAR | G_ARROW, 6, wnp);

`co(10,1);/// Masks/Templates`co();

	The wn_gets function requires the programmer to specify two
	important strings to perform its magic.  These are the mask and
	template strings.

	The mask string gives the programmer the flexibility of displaying
	textual information inside the area to be typed by the user.	When
	the user types, the cursor simply skips over the mask characters.

	The template string is essentially a string containing validation
	characters.  Before a character is entered into the string, the
	wn_gets function compares the typed character with the template
	to see if the character is valid.  In addition, the template can
	be used to force an uppercase or lowercase character without having
	the user touch the CapsLock or Shift keys.

	When combined, the mask and template strings give the programmer
	great flexibility.	The following are just a few examples with
	explanations of what they accomplish:

	mask = "________"           Enter an 8 character string, where all
	tplt = "AAAAAAAA"           characters must be alphanumeric.
	
	mask = "________"           Enter an 8 character string, where
	tplt = "********"           anything typed is valid.
	
	mask = "________"           Enter an 8 character string, where the
	tplt = "Uaaaaaaa"           first character is converted to
															uppercase, and the rest must be alpha.
	
	mask = "________"           Enter an 8 character string, where all 8
	tplt = "uuuuuuuu"           characters must by typed in uppercase.

	mask = "(___) ___-____"     Enter a 14 character string, where only
	tplt = " ###  ### ####"     numbers can be typed at the _ positions.


`co(10,1);/// Validation Chars`co();

	Validation characters are simply characters that are valid to put
	in your templates.	The following is a list of the validation
	characters along with their effect.
	
	Validation Char 		 Effect
	--------------- 		 -----------------------------------------------
			 '#'             Allow only a digit to be entered.
			 'X'             Allow only a hexidecimal digit to be entered.
			 'u'             Allow only upper case letters to be entered.
			 'l'             Allow only lower case letters to be entered.
			 'U'             Convert to upper case, even if typed as lower.
			 'L'             Convert to lower case, even if typed as upper.
			 'A'             Allow only alphanumeric characters and <space>.
			 'a'             Allow only alpha characters and <space>.
			 '*'             Allow any characters.

`co(10,1);/// Strip Mask Option`co();

	This parameter to the wn_gets function gives the programmer the
	option to have wn_gets either format the string with the mask
	characters intact, or strip out the mask characters.	This can
	best be demonstrated as follows:

	mask = "(___) ___-____"
	tplt = " ###  ### ####"
	
	When wn_gets is called with these parameters, and a phone number is
	entered, the display looks like this:
	
														(123) 456-7890

	Very simply, if the strip mask option is not used, then this string
	is what is returned by the function (mask intact).	However, if the
	strip mask option is used, then the returned string would be:
	
															 1234567890

	with no mask characters left, only what the user typed!  By utilizing
	this parameter in appropriate places you can save yourself a considerable
	amount of work.

`co(10,1);/// set_validation_func`co();   `keyword(set_validation_func,[UW_ENTRY.C]~set_validation_func);
	This allows you to set your own data entry validation function that
	is called every time a character is typed in `keyword(wn_gets_ll,/// wn_gets_ll); 
  Note that this is not necessarily called for every keystroke.  If the
  user pressed the arrow keys, backspace, etc. the function will not be
  called.  It is called only when entering data.  When the function is 
  called it is passed a series of parameters that allow complete flexibility.
  The validation routine should return a 1 if all's well, else it should 
  return a 0.  If 0 is returned, the entry routine will overwrite the
  invalid character with the mask character for the current position.
  See the demo program `keyword(str_demo,[STR_DEMO.C]main); for more details.

Prototype:
void set_validation_func( int (*func_ptr)() )

Parameters:
  func_ptr - a function pointer which is called fo each character entry

Usage:
	set_validation_func( date_vld );
...
int date_vld(char *w, char *t, char *m, int pos, int max_pos, WINDOW *wnp )
{
	/* w       - pointer to current work string */
	/* m       - pointer to the mask            */
	/* m       - pointer to the template        */
	/* pos     - current position in string     */
	/* max_pos - maximum position in string     */
	/* WINDOW  - pointer to entry window (can be used to output err msg,etc) */
}

`co(4,7);───────────────────────────── /// Menuing ──────────────────────────────────`co();

┌──────────────────────────────────────────────────────────────────────────┐	
│          `keyword(menu_create,/// menu_create);             `keyword(menu_destroy,/// menu_destroy);          `keyword(menu_set,/// menu_set);          │ 
│          `keyword(menu_restore,/// menu_restore);            `keyword(item_add,/// item_add);              `keyword(do_menu,/// do_menu);           │
│          `keyword(menu_system,/// menu_system);                                                     │
└──────────────────────────────────────────────────────────────────────────┘

	Another feature of the UltraWin library is menuing.  UltraWin allows
	both vertical and horizontal menus to be easily created and displayed
	for interaction with the user.	The menu's entries can be selected with
	just one keystroke (or a simple click of the mouse).  The letter to
	check when selecting an entry can be any character of the entry, and
	can even be highlighted in a different color.  In addition, the menus
	can be defined as a popup menu, restoring the area under the menu when
	finished, or it can be used with the window manager, forcing redraw
	of the area(s) of the window(s) below the menu when finished.

`co(10,1);/// menu_create`co();   `keyword(source,[UW_MENU.C]~menu_create);
	Initializes the menu to the specified coordinates on the screen,
	the menu attributes (colors), the border style and menu type
	passed.  A call to this function must be made to define the menu
	before the menu is placed on the screen with menu_set.	For
	the type parameter, use WN_POPUP if you wish the menu to be a
	popup menu (restoring the screen below), or WN_NORMAL if you are
	using UltraWin's powerful window manager.

Prototype:
	void menu_create(int x_min, int y_min, int x_max, int y_max,
								 int direction, int back_att, int bdr_att, int csr_att,
								 int first_att, int bdr, int type, MENU *mnp);

Parameters:
`co(11,1);	int x_min, y_min`co();
		The upper left corner of the menu to create.
`co(11,1);	int x_max, y_max`co();
		The lower right corner of the menu to create.
`co(11,1);	int direction`co();
		The menu direction, use M_VERTICAL for a vertical menu and
		M_HORIZONTAL for a horizontal menu.
`co(11,1);	int back_att`co();
		The attribute to use for the menu.	This defines the color of
		the menu and the characters in the menu, and can be a value from
		0-255.	For example, use (RED << 4) | WHITE for white menu entry
		characters on a red background.
`co(11,1);	int bdr_att`co();
		The border attribute (not used if the bdr parameter is NO_BDR).
`co(11,1);	int csr_att`co();
		The attribute to use when displaying the cursor position.
`co(11,1);	int first_att`co();
		The attribute to use for the menu entry selection character.
		Typically you would use the same background color as back_att,
		but a different foreground color.
`co(11,1);	int bdr`co();
		The border style, can be either NO_BDR, SGL_BDR, DBL_BDR,
		SLD_BDR or DUAL_BDR (defined in uw.h).
`co(11,1);	int type`co();
		The menu type, can be either WN_POPUP or WN_NORMAL.  Use the
		former when not using the window manager.
`co(11,1);	MENU *mnp;`co();
		A pointer to the menu to create.

Usage:
	MENU mn;
	int back_att, bdr_att, csr_att, first_att;
	...
	menu_create(0, 0, 20, 10, M_VERTICAL, back_att, bdr_att,
							csr_att, first_att, SGL_BDR, WN_NORMAL, *mn);

`co(10,1);/// menu_destroy`co();   `keyword(source,[UW_MENU.C]~menu_destroy);
	This function destroys the menu created with menu_create.  The
	window allocated for the menu is freed.
		
Prototype:
	void menu_destroy( MENU *mnp );

Parameters:
`co(11,1);	MENU *mnp;`co();
		A pointer to the menu to destroy.

Usage:
	MENU *mnp;
	...
	menu_destroy(mnp);

`co(10,1);/// menu_set`co();   `keyword(source,[UW_MENU.C]~menu_set);
	This function takes a menu created with menu_create, and places
	it on the screen.  If the menu was defined with type WN_POPUP, the
	area below the window will be saved for later restoration.

Prototype:
	void menu_set( MENU *mnp );

Parameters:
`co(11,1);	MENU *mnp;`co();
		A pointer to the menu to place on the screen.

Usage:
	MENU *mnp;
	...
	menu_set(mnp);

`co(10,1);/// menu_restore`co();   `keyword(source,[UW_MENU.C]~menu_restore);
	This function takes a menu created with menu_create, placed on
	the screen with menu_set, and removes it from the screen.  If the
	menu was defined with type WN_POPUP, the area below the window is
	restored.  If the menu was defined with type WN_NORMAL and the
	window manager is in use, then the area under the menu will be
	redrawn.

Prototype:
	void menu_restore( MENU *mnp );

Parameters:
`co(11,1);	MENU *mnp;`co();
		A pointer to the menu to restore.

Usage:
	MENU *mnp;
	...
	menu_restore(mnp);

`co(10,1);/// item_add`co();   `keyword(source,[UW_MENU.C]~item_add);
	This function is used to add an entry into a menu.	An integer
	handle (or id) that you define is passed to identify the entry.
	The menu_do function returns this id when the entry is selected.
	In addition, the index into the string for the "active" character
	is passed.	This is the character in the string that is displayed
	in the first_att color upon display, and is used when a key on
	the keyboard is pressed that matches.

Prototype:
	void item_add( char *entry, int id, int first_pos, MENU *mnp );

Parameters:
`co(11,1);	char *entry;`co();
		The string to add to the menu.	This string does not have to
		be the same length as the width of the menu, as the display
		routines of menu_set and menu_do justify the entry for you.
`co(11,1);	int id`co();
		This is an id you define which will be returned to you when
		the menu item is selected in menu_do.
`co(11,1);	int first_pos`co();
		This is an index into the string for the "active" letter.  This
		letter will be used to check against keyboard letters pressed,
		and will be displayed in the first_att color specified in the
		menu_create function.  For example, for the entry "Dos Shell"
		to make the menu_do function return the id with one keypress,
		use a first_pos of 4, which corresponds to the "S" in "Shell".
`co(11,1);	MENU *mnp;`co();
		A pointer to the menu the item is to be added.

Usage:
	#define DOS_SHELL 37
	MENU *mnp;
	...
	item_add("Dos Shell", DOS_SHELL, 4, mnp);

`co(10,1);/// do_menu`co();   `keyword(source,[UW_MENU.C]~do_menu);
	Call this function after you have called menu_set, and the menu
	will be activated for input from the user.	To retain flexibility,
	you may specify whether the do_menu function should interact
	with the user through the wait_event function, or immediately
	process the global Event variable and return to you.	This gives
	you the ability to use your own event logic if you wish, and
	is useful for menus which are static on the screen, as opposed to
	menus that pop up and restore when finished.	If interaction
	through wait_event is specified, then this function returns
	either the id of the item selected, or 0 if no item is selected.
	If you have do_menu only process the information in the global
	variable Event, then a 0 is returned for each call to do_menu
	that does not have an <Enter> keypress in Event.

Prototype:
	int do_menu( MENU *mnp, int proc_mode );

Parameters:
`co(11,1);	MENU *mnp;`co();
		A pointer to the menu for interaction.
`co(11,1);	int proc_mode`co();
		The processing mode, which can be one of the defines M_GET_EVENT
		or M_PROC_EVENT.	If M_GET_EVENT is used, then the menu will
		get input via the keyboard (or mouse if it exists) until the
		user has either selected one of the items, or pressed the Esc
		key.

Usage:
	MENU *mnp;
	...
	do_menu( mnp, M_GET_EVENT );

`co(10,1);/// menu_system`co();   `keyword(source,[UW_MENU.C]~menu_system);
	This function was written specifically for the standard top menu
	bar with corresponding drop down menus.  This function gives you
	the option of displaying the top menu upon entry and removing the
	top menu upon exit (a popup menuing system), or simply use the top
	menu previously placed on the screen with menu_set.  When called,
	the function will interact with the user through the keyboard and
	mouse, and return the menu id of the entry selected.  If the Esc
	key was pressed or the mouse clicked off the menu, then a 0 is
	returned.  Upon completion, the global Event variable will contain
	information about the last key or mouse press.
		
	NOTE: To utilize this function, you must first define your menus
	with menu_create, then add each entry with item_add, being sure
	to define a unique id for each entry.

Prototype:
	int menu_system( MENU *top_mnp, MENU *dropmenu[], int draw_top );

Parameters:
`co(11,1);	MENU *top_mnp;`co();
		A pointer to the vertical main menu.
`co(11,1);	MENU *dropmenu[];`co();
		An array of pointers to a series of drop down menus.
`co(11,1);	int draw_top`co();
		This parameter can be either 1 or 0, and specifies whether the
		menu_system function should handle the initial display of the
		top menu or assume that the top menu is already displayed.
		Using a value of 1 is useful if you wish your menu system to be
		hidden during your program, and only called up with a key.	Use
		a 0 for when your program keeps the top menu on the screen.

Usage:
	MENU *top_mnp;
	MENU *drop_mnp[8];
	...
	menu_system( top_mnp, drop_mnp, 1);

`co(4,7);─ End ──────────────────────────────────────────────────────────────────────`co();`sound(1024,10);
