/*************************************************************************

	formZ by autodessys, Inc.
	Copyright c 1994 autodessys, Inc.  All rights reserved.
	
	
	File :	fz_script_only_api.h
	
	By :	MJB
	
	Created on :  		April 20, 2004
	Last Updated on :  	April 20, 2004
	
	Description :	
					
***************************************************************************/

#ifndef __FORMZ_SCRIPT_ONLY_API_H
#define __FORMZ_SCRIPT_ONLY_API_H 1

#ifdef __cplusplus
extern "C" {
#endif

/* @doc EXTERNAL SCRIPT_ONLY */

/************************************************************************

	@module Script Only

	@desc	Many ANSI standard functions are provided to the formZ Script
			Language through these functions.

	@toc	script_only_util

*************************************************************************/
/************************************************************************

	@module Script Only Templates

	@desc	Since scripts deal with templates in a simpler way than plugins,
			scripts have their own set of FUIM template functions.

	@toc	script_only_fuim

*************************************************************************/


/************************************************************************
	UTILITY FUNCTIONS. ANSI EQUIVALENTS AND A FEW MORE.
*************************************************************************/
/************************************************************************

	@scrfunc	
	
	@desc		Computes the sine of x
	
	@return		sine of x
		
	@avail		5.0.0.0

	@see		

	@toc		script_only_util

*************************************************************************/
double  fz_std_sin(	
	double	x	/* @parm <in> | the value for which to compute the sine (in radians) */
	);

/************************************************************************

	@scrfunc	
	
	@desc		Computes the cosine of x
	
	@return		cosine of x
		
	@avail		5.0.0.0

	@see		

	@toc		script_only_util

*************************************************************************/
double  fz_std_cos(	
	double	x	/* @parm <in> | the value for which to compute the cosine (in radians) */
	);

/************************************************************************

	@scrfunc	
	
	@desc		Computes the tangent of x
	
	@return		tangent of x
		
	@avail		5.0.0.0

	@see		

	@toc		script_only_util

*************************************************************************/
double  fz_std_tan(	
	double	x	/* @parm <in> | the value for which to compute the tangent (in radians) */
	);

/************************************************************************

	@scrfunc	
	
	@desc		Computes the arc sine of x
	
	@return		arc sine of x in the range -PI/2 to PI/2
		
	@avail		5.0.0.0

	@see		

	@toc		script_only_util

*************************************************************************/
double  fz_std_asin(	
	double	x	/* @parm <in> | the value for which to compute the arc sine.
				   @rimin_imax -1.0 | 1.0 */
	);

/************************************************************************

	@scrfunc	
	
	@desc		Computes the arc cosine of x
	
	@return		arc cosine of x in the range 0 to PI
		
	@avail		5.0.0.0

	@see		

	@toc		script_only_util

*************************************************************************/
double  fz_std_acos(	
	double	x	/* @parm <in> | the value for which to compute the arc cosine.
				   @rimin_imax -1.0 | 1.0 */
	);

/************************************************************************

	@scrfunc	
	
	@desc		Computes the arc tangent of x
	
	@return		arc tangent of x in the range -PI/2 to PI/2
		
	@avail		5.0.0.0

	@see		

	@toc		script_only_util

*************************************************************************/
double  fz_std_atan(	
	double	x	/* @parm <in> | the value for which to compute the arc tangent. */
	);

/************************************************************************

	@scrfunc	
	
	@desc		Computes the arc tangent of y / x
	
	@return		arc tangent of y / x in the range -PI to PI
		
	@avail		5.0.0.0

	@see		

	@toc		script_only_util

*************************************************************************/
double  fz_std_atan2(	
	double	y,	/* @parm <in> | the y value for which to compute the arc tangent. */
	double	x	/* @parm <in> | the x value for which to compute the arc tangent. x cannot be zero. */
	);

/************************************************************************

	@scrfunc	
	
	@desc		Computes the hyperbolic sine of x
	
	@return		hyperbolic sine of x
		
	@avail		5.0.0.0

	@see		

	@toc		script_only_util

*************************************************************************/
double  fz_std_sinh(	
	double	x	/* @parm <in> | the value for which to compute the hyperbolic sine (in radians) */
	);

/************************************************************************

	@scrfunc	
	
	@desc		Computes the hyperbolic cosine of x
	
	@return		hyperbolic cosine of x
		
	@avail		5.0.0.0

	@see		

	@toc		script_only_util

*************************************************************************/
double  fz_std_cosh(	
	double	x	/* @parm <in> | the value for which to compute the hyperbolic cosine (in radians) */
	);

/************************************************************************

	@scrfunc	
	
	@desc		Computes the hyperbolic tangent of x
	
	@return		hyperbolic tangent of x
		
	@avail		5.0.0.0

	@see		

	@toc		script_only_util

*************************************************************************/
double  fz_std_tanh(	
	double	x	/* @parm <in> | the value for which to compute the hyperbolic tangent (in radians) */
	);

/************************************************************************

	@scrfunc	
	
	@desc		Computes the exponential function : e to the power of x
	
	@return		e to the power of x
		
	@avail		5.0.0.0

	@see		

	@toc		script_only_util

*************************************************************************/
double  fz_std_exp(	
	double	x	/* @parm <in> | the exponent for e to the power of x */
	);


/************************************************************************

	@scrfunc	
	
	@desc		Computes the natural logarithm ln(x)
	
	@return		ln(x)
		
	@avail		5.0.0.0

	@see		

	@toc		script_only_util

*************************************************************************/
double  fz_std_log(	
	double	x	/* @parm <in> | the value for which to compute the natural logarithm.
				   $rmin 0.0 */
	);
	
/************************************************************************

	@scrfunc	
	
	@desc		Computes the base 10 logarithm log10(x)
	
	@return		log10(x)
		
	@avail		5.0.0.0

	@see		

	@toc		script_only_util

*************************************************************************/
double  fz_std_log10(	
	double	x	/* @parm <in> | the value for which to compute the base 10 logarithm.
				   $rmin 0.0 */
	);
	
/************************************************************************

	@scrfunc	
	
	@desc		Computes x to the power of y. An error occurs if x is equal
				to zero and y is less than or equal to zero. An also error occurs 
				if x is less than zero and y is not a whole number. In both cases
				the returned value is undefined.
	
	@return		x to the power of y
		
	@avail		5.0.0.0

	@see		

	@toc		script_only_util

*************************************************************************/
double  fz_std_pow(	
	double	x,	/* @parm <in> | base */
	double	y	/* @parm <in> | exponent */
	);
	
/************************************************************************

	@scrfunc	
	
	@desc		Computes the square root of x
	
	@return		square root of x
		
	@avail		5.0.0.0

	@see		

	@toc		script_only_util

*************************************************************************/
double  fz_std_sqrt(	
	double	x	/* @parm <in> | value for which to compute the square root.
				   @rimin 0.0 */
	);
/************************************************************************

	@scrfunc	
	
	@desc		Computes the smallest integer, not less than x, as a double (ceiling)
	
	@return		ceiling of x
		
	@avail		5.0.0.0

	@see		

	@toc		script_only_util

*************************************************************************/
double  fz_std_ceil(	
	double	x	/* @parm <in> | value for which to compute the ceiling */
	);
/************************************************************************

	@scrfunc	
	
	@desc		Computes the largest integer, not greater than x, as a double (floor)
	
	@return		floor of x
		
	@avail		5.0.0.0

	@see		

	@toc		script_only_util

*************************************************************************/
double  fz_std_floor(	
	double	x	/* @parm <in> | value for which to compute the floor */
	);

/************************************************************************

	@scrfunc	
	
	@desc		Computes the absolute value of x
	
	@return		absolute value of x
		
	@avail		5.0.0.0

	@see		

	@toc		script_only_util

*************************************************************************/
double  fz_std_fabs(	
	double	x	/* @parm <in> | value for which to compute the absolute value */
	);
	
/************************************************************************

	@scrfunc	
	
	@desc		Computes the x times 2 to the power of n
	
	@return		x * pow(2,n)
		
	@avail		5.0.0.0

	@see		

	@toc		script_only_util

*************************************************************************/
double  fz_std_ldexp(	
	double	x,	/* @parm <in> | x value */
	fzrt_int	n	/* @parm <in> | exponent */
	);
	
/************************************************************************

	@scrfunc	
	
	@desc		Splits x into a normalized fraction in the interval 0.5 to 1.0,
				which is returned, and a power of 2, which is stored in exp.
				If x is zero, both parts of the result are zero
	
	@return		normalized fraction
		
	@avail		5.0.0.0

	@see		

	@toc		script_only_util

*************************************************************************/
double  fz_std_frexp(	
	double	x,	/* @parm <in> | x value */
	fzrt_int	*n	/* @parm <out> | exponent */
	);
	
/************************************************************************

	@scrfunc	
	
	@desc		Splits x into integral and fractional parts, each with the
				same sign as x. If stores the integral part in ip and
				returns the fractional part.
	
	@return		fractional part
		
	@avail		5.0.0.0

	@see		

	@toc		script_only_util

*************************************************************************/
double  fz_std_modf(	
	double	x,	/* @parm <in> | x value */
	double	*ip	/* @parm <out> | integral part */
	);
	
/************************************************************************

	@scrfunc	
	
	@desc		Computes the floating point remainder of x / y, with the same sign as
				x. If y is zero, the result is undefined.
	
	@return		remainder of x / y
		
	@avail		5.0.0.0

	@see		

	@toc		script_only_util

*************************************************************************/
double  fz_std_fmod(	
	double	x,	/* @parm <in> | x value */
	double	y	/* @parm <out> | y value (cannot be zero). */
	);
	
/************************************************************************

	@scrfunc	
	
	@desc		Determines whether an integer is odd.
	
	@return		TRUE is odd. FALSE otherwise
		
	@avail		5.0.0.0

	@see		

	@toc		script_only_util

*************************************************************************/
fzrt_boolean  fz_std_odd(	
	fzrt_int	val	/* @parm <in> | value */
	);
	
/************************************************************************

	@scrfunc	
	
	@desc		Determines whether an integer is even.
	
	@return		TRUE is even. FALSE otherwise
		
	@avail		5.0.0.0

	@see		

	@toc		script_only_util

*************************************************************************/
fzrt_boolean fz_std_even(	
	fzrt_int	val	/* @parm <in> | value */
	);
	
/************************************************************************

	@scrfunc	
	
	@desc		Computes a pseudo random integer number in the range from min to max.
	
	@return		the random number
		
	@avail		5.0.0.0

	@see		

	@toc		script_only_util

*************************************************************************/
fzrt_int  fz_std_irand(	
	fzrt_int	min,	/* @parm <in> | the minimum number in the range (inclusive) */
	fzrt_int	max		/* @parm <in> | the maximum number in the range (inclusive) */
	);

/************************************************************************

	@scrfunc	
	
	@desc		Computes a pseudo random floating point number in the range from min to max.
	
	@return		the random number
		
	@avail		5.0.0.0

	@see		

	@toc		script_only_util

*************************************************************************/
double  fz_std_frand(	
	double	min,	/* @parm <in> | the minimum number in the range (inclusive) */
	double	max		/* @parm <in> | the minimum number in the range (inclusive) */
	);

/************************************************************************

	@scrfunc	
	
	@desc		srand uses the seed argument as the seed for a new sequence of
				pseudo random numbers. The initial seed is 1.
	
	@return		
		
	@avail		5.0.0.0

	@see		

	@toc		script_only_util

*************************************************************************/
void fz_std_srand(	
	fzrt_int	seed	/* @parm <in> | the random number seed */
	);

/************************************************************************

	@scrfunc	
	
	@desc		Opens the named file and returns a pointer to the file or NULL
				if the attempt fails. Legal values for the mode are : <nl>
				"r"	open text file for reading<nl>
				"w" open text file for writing. Discard previous content, if the file existed.<nl>
				"a" append to the file. Opens or creates the file for writing at the end.<nl>
				"r+" open text file for update (reading and writing).<nl>
				"w+" create text file for update (reading and writing). Discard previous content, if file existed.<nl>
				"a+" append to the file. Open or create text file for update (reading and writing), writing at end.<nl>
				Update mode permits reading and writing the same file. fflush must be called between a
				read and a write or vice versa. If the mode includes b after the initial letter, as
				in "rb" or "w+b", it indicates a binary file. Filenames are limited to FILENAME_MAX
				characters. At most FOPEN_MAX files may be open at once.
				
	@return		pointer to the open file or NULL, if the function fails.
		
	@avail		5.0.0.0

	@see		

	@toc		script_only_util

*************************************************************************/
FILE*  fz_std_fopen(	
	fz_string_td	filename,	/* @parm <in> | the name of the file to be opened */
	fz_string_td	mode		/* @parm <in> | the mode in which to open the file */
	);

/************************************************************************

	@scrfunc	
	
	@desc		Flushes any unwritten data for the file, discards any unread
				buffered input, frees any automatically allocated buffer and 
				closes the file. It returns EOF, if any errors occurred and 
				zero otherwise.
				
	@return		EOF, if an error occurred, zero otherwise
		
	@avail		5.0.0.0

	@see		

	@toc		script_only_util

*************************************************************************/
fzrt_int  fz_std_fclose(	
	FILE	*file	/* @parm <in> | file to be closed */
	);

/************************************************************************

	@scrfunc	
	
	@desc		On an output file, fflush causes any buffered, but unwritten data to
				be written. On an input file, the effect is undefined. It returns EOF for a
				write error and zero otherwise.
				
	@return		EOF, if an error occurred, zero otherwise
		
	@avail		5.0.0.0

	@see		

	@toc		script_only_util

*************************************************************************/
fzrt_int  fz_std_fflush(	
	FILE	*file	/* @parm <in> | file to be flushed */
	);

/************************************************************************

	@scrfunc	
	
	@desc		Writes an integer value to a file. The field_width argument
				determines the minimum width of the output in # of digits.
				More are written, if the integer has more digits. If the
				integer has less digits, extra blanks are written in front of 
				the number. If the field_width is passed as 0 or less,
				the exact number of digits for the integer are written.
				The file must have been opened for write (see fz_std_fopen).
				
	@return		# of digits written, or negative if an error occurred.
		
	@avail		5.0.0.0

	@see		fz_std_fscan_int

	@toc		script_only_util

*************************************************************************/
fzrt_int  fz_std_fprint_int(	
	FILE	*file,			/* @parm <in> | file to be written to. */
	fzrt_int	lval,			/* @parm <in> | the integer to be written. */
	fzrt_int	field_width		/* @parm <in> | the minimum field width */
	);
	
/************************************************************************

	@scrfunc	
	
	@desc		Writes "TRUE" or "FALSE" to a file.
				The file must have been opened for write (see fz_std_fopen).
				
	@return		# of characters written, or negative if an error occurred.
		
	@avail		5.0.0.0

	@see		fz_std_fscan_bool

	@toc		script_only_util

*************************************************************************/
fzrt_int  fz_std_fprint_bool(	
	FILE	*file,					/* @parm <in> | file to be written to. */
	fzrt_boolean	bval			/* @parm <in> | the boolean to be written. */
	);
	
/************************************************************************

	@scrfunc	
	
	@desc		Writes a floating point value to a file. The pre_width
				argument determines the minimum number of digits written
				for the integral part of the number. If the integral part
				has more digits, more are written. If it has less, blanks
				are written before. If zero or less is passed for the
				pre_width argument, the exact number of digits for the
				integral part are written. The post_width argument determines the minimum 
				number of digits written for the fractional part of the number. 
				If the fractional part has more digits, they are not written (i.e. the 
				less significant digits are truncated). If it has less, zeroes are appended. 
				If zero or less is passed for the post_width argument, the exact number of 
				digits for the fractional part are written.
				The file must have been opened for write (see fz_std_fopen).
				
	@return		# of digits written, or negative if an error occurred.
		
	@avail		5.0.0.0

	@see		fz_std_fscan_float

	@toc		script_only_util

*************************************************************************/
fzrt_int  fz_std_fprint_float(	
	FILE	*file,					/* @parm <in> | file to be written to. */
	double	dval,					/* @parm <in> | the number to be written. */
	fzrt_int	pre_width,				/* @parm <in> | the minimum number of digits to be written for the integral part. */
	fzrt_int	post_width				/* @parm <in> | the minimum number of digits to be written for the fractional part. */
	);
	
/************************************************************************

	@scrfunc	
	
	@desc		Writes a string to a file
				The file must have been opened for write (see fz_std_fopen).
				
	@return		# of characters written, or negative if an error occurred.
		
	@avail		5.0.0.0

	@see		fz_std_fscan_str

	@toc		script_only_util

*************************************************************************/
fzrt_int  fz_std_fprint_str(	
	FILE	*file,					/* @parm <in> | file to be written to. */
	fz_string_td	str				/* @parm <in> | the string to be written. */
	);
	
/************************************************************************

	@scrfunc	
	
	@desc		Writes a pointer value to a file. It is written in
				hexadecimal format. For example: <nl>
				0x0FA1CD02<nl>
				The file must have been opened for write (see fz_std_fopen).
				
	@return		# of characters written, or negative if an error occurred.
		
	@avail		5.0.0.0

	@see		

	@toc		script_only_util

*************************************************************************/
fzrt_int  fz_std_fprint_ptr(	
	FILE		*file,					/* @parm <in> | file to be written to. */
	fzrt_ptr	ptr_val					/* @parm <in> | the pointer value to be written. */
	);

/************************************************************************

	@scrfunc	
	
	@desc		Writes a tag value to a file. 
				The file must have been opened for write (see fz_std_fopen).
				
	@return		# of characters written, or negative if an error occurred.
		
	@avail		5.0.1.0

	@see		fz_std_fscan_tag

	@toc		script_only_util

*************************************************************************/
fzrt_int  fz_std_fprint_tag(	
	FILE		*file,					/* @parm <in> | file to be written to. */
	fz_tag_td	*tag					/* @parm <in> | the tag value to be written. */
	);

/************************************************************************

	@scrfunc	
	
	@desc		Writes a uuid value to a file. 
				The file must have been opened for write (see fz_std_fopen).
				
	@return		# of characters written, or negative if an error occurred.
		
	@avail		5.0.1.0

	@see		fz_std_fscan_uuid

	@toc		script_only_util

*************************************************************************/
fzrt_int  fz_std_fprint_uuid(	
	FILE			*file,					/* @parm <in> | file to be written to. */
	fzrt_UUID_td	uuid					/* @parm <in> | the uuid value to be written. */
	);

/************************************************************************

	@scrfunc	
	
	@desc		Writes an integer value into a string. The field_width argument
				determines the minimum width of the output in # of digits.
				More are written, if the integer has more digits. If the
				integer has less digits, extra blanks are written in front of 
				the number. If the field_width is passed as 0 or less,
				the exact number of digits for the integer are written. This is
				in essence the same as fprint_int, except, that the output
				goes into a string, instead of a file.
				
	@return		# of digits written, or negative if an error occurred.
		
	@avail		5.0.0.0

	@see		fz_std_sscan_int

	@toc		script_only_util

*************************************************************************/
fzrt_int  fz_std_sprint_int(	
	fz_string_td	str,			/* @parm <in> | string to be written to. */
	fzrt_int			lval,			/* @parm <in> | the integer to be written. */
	fzrt_int			field_width		/* @parm <in> | the minimum field width */
	);
	
	
/************************************************************************

	@scrfunc	
	
	@desc		Writes "TRUE" or "FALSE" to a string.
				
	@return		# of characters written, or negative if an error occurred.
		
	@avail		5.0.0.0

	@see		fz_std_sscan_bool

	@toc		script_only_util

*************************************************************************/
fzrt_int  fz_std_sprint_bool(	
	fz_string_td	str,			/* @parm <in> | string to be written to. */
	fzrt_boolean	bval			/* @parm <in> | the boolean to be written. */
	);

/************************************************************************

	@scrfunc	
	
	@desc		Writes a floating point value to a string. The pre_width
				argument determines the minimum number of digits written
				for the integral part of the number. If the integral part
				has more digits, more are written. If it has less, blanks
				are written before. If zero or less is passed for the
				pre_width argument, the exact number of digits for the
				integral part are written. The post_width argument determines the minimum 
				number of digits written for the fractional part of the number. 
				If the fractional part has more digits, they are not written (i.e. the 
				less significant digits are truncated). If it has less, zeroes are appended. 
				If zero or less is passed for the post_width argument, the exact number of 
				digits for the fractional part are written.
				
	@return		# of digits written, or negative if an error occurred.
		
	@avail		5.0.0.0

	@see		fz_std_sscan_float

	@toc		script_only_util

*************************************************************************/
fzrt_int  fz_std_sprint_float(	
	fz_string_td	str,			/* @parm <in> | string to be written to. */
	double	dval,					/* @parm <in> | the number to be written. */
	fzrt_int	pre_width,				/* @parm <in> | the minimum number of digits to be written for the integral part. */
	fzrt_int	post_width				/* @parm <in> | the minimum number of digits to be written for the fractional part. */
	);

/************************************************************************

	@scrfunc	
	
	@desc		Writes a pointer value to a string. It is written in
				hexadecimal format. For example: <nl>
				0x0FA1CD02
				
	@return		# of characters written, or negative if an error occurred.
		
	@avail		5.0.0.0

	@see		

	@toc		script_only_util

*************************************************************************/
fzrt_int  fz_std_sprint_str(	
	fz_string_td	str,					/* @parm <in> | string to be written to. */
	fzrt_ptr	ptr_val					/* @parm <in> | the pointer value to be written. */
	);


/************************************************************************

	@scrfunc	
	
	@desc		Writes a tag value to a string. 
				
	@return		# of characters written, or negative if an error occurred.
		
	@avail		5.0.1.0

	@see		fz_std_sscan_tag

	@toc		script_only_util

*************************************************************************/
fzrt_int  fz_std_sprint_tag(	
	fz_string_td	str,					/* @parm <in> | string to be written to. */
	fz_tag_td	*tag					/* @parm <in> | the tag value to be written. */
	);

/************************************************************************

	@scrfunc	
	
	@desc		Writes a uuid value to a string. 
				
	@return		# of characters written, or negative if an error occurred.
		
	@avail		5.0.1.0

	@see		fz_std_sscan_uuid

	@toc		script_only_util

*************************************************************************/
fzrt_int  fz_std_sprint_uuid(	
	fz_string_td	str,					/* @parm <in> | string to be written to. */
	fzrt_UUID_td	uuid					/* @parm <in> | the uuid value to be written. */
	);

/************************************************************************

	@scrfunc	
	
	@desc		Copies the string src_str into the string dst_str. Any previous
				content of dst_str is discarded.
				
	@return		the destination string
		
	@avail		5.0.0.0

	@see		

	@toc		script_only_util

*************************************************************************/
fz_string_td	fz_std_strcpy(	
	fz_string_td	dst_str,				/* @parm <in> | destination string. */
	fz_string_td	src_str					/* @parm <in> | source string. */
	);
	
/************************************************************************

	@scrfunc	
	
	@desc		Copies at most n characters from string src_str to string dst_str. Any previous
				content of dst_str is discarded.
				
	@return		the destination string
		
	@avail		5.0.0.0

	@see		

	@toc		script_only_util

*************************************************************************/
fz_string_td	  fz_std_strncpy(	
	fz_string_td	dst_str,				/* @parm <in> | destination string. */
	fz_string_td	src_str,				/* @parm <in> | source string. */
	fzrt_int			n						/* @parm <in> | the number of characters to be copied.
											   @rimin_imax 1 | 255 */
	);

/************************************************************************

	@scrfunc	
	
	@desc		Concatenates (appends) the string src_str to the string
				dst_str.
				
	@return		the destination string
		
	@avail		5.0.0.0

	@see		

	@toc		script_only_util

*************************************************************************/
fz_string_td	fz_std_strcat(	
	fz_string_td	dst_str,				/* @parm <in> | destination string. */
	fz_string_td	src_str					/* @parm <in> | source string. */
	);
	
/************************************************************************

	@scrfunc	
	
	@desc		Concatenates (appends) at most n characters from string src_str to string dst_str.
				The total length of dst_str cannot exceed 255 characters.
				
	@return		the destination string
		
	@avail		5.0.0.0

	@see		

	@toc		script_only_util

*************************************************************************/
fz_string_td	fz_std_strncat(	
	fz_string_td	dst_str,				/* @parm <in> | destination string. */
	fz_string_td	src_str,				/* @parm <in> | source string. */
	fzrt_int			n						/* @parm <in> | the number of characters of src_str to be appended.
											   @rimin_imax 1 | 255 */
	);

/************************************************************************

	@scrfunc	
	
	@desc		Compares str1 to str2.
				
	@return		0 if they are equal, less than 0 if str1 is less than str2 and greater 
				than 0 if str1 is greater than str2.
		
	@avail		5.0.0.0

	@see		

	@toc		script_only_util

*************************************************************************/
fzrt_int  fz_std_strcmp(	
	fz_string_td	str1,					/* @parm <in> | string1 */
	fz_string_td	str2					/* @parm <in> | string2 */
	);

/************************************************************************

	@scrfunc	
	
	@desc		Compares at most n characters of str1 to str2.
				
	@return		0 if they are equal, less than 0 if str1 is less than str2 and greater 
				than 0 if str1 is greater than str2.
		
	@avail		5.0.0.0

	@see		

	@toc		script_only_util

*************************************************************************/
fzrt_int  fz_std_strncmp(	
	fz_string_td	str1,					/* @parm <in> | string1 */
	fz_string_td	str2,					/* @parm <in> | string2 */
	fzrt_int			n						/* @parm <in> | the number of characters to compare.
										   	   @rimin_imax 1 | 255 */
	);

/************************************************************************

	@scrfunc	
	
	@desc		Returns the number of characters in a string
				
	@return		the number of characters
		
	@avail		5.0.0.0

	@see		

	@toc		script_only_util

*************************************************************************/
fzrt_int  fz_std_strlen(	
	fz_string_td	str					/* @parm <in> | the string. */
	);
	
	
/************************************************************************

	@scrfunc	
	
	@desc		Compares the ranges of two strings to be equal. The range is defined
				by a starting character position for each string and the number of subsequent
				characters to compare. 
				
	@return		The function returns 0 if the string ranges
				are equal, less than 0 if str1 is less than str2 and greater 
				than 0 if str1 is greater than str2. If the starting character position of
				either string is invalid, -1 is returned.
		
	@avail		5.5.0.0

	@see		

	@toc		script_only_util

*************************************************************************/
fzrt_int  fz_std_strcmp_range(	
	fz_string_td	str1, 			/* @parm <in> | the first string. */
	fzrt_int 			start1, 		/* @parm <in> | the starting character in the first string (0 based). 
									   @rimin_imax 0 | 255 */
	fz_string_td	str2, 			/* @parm <in> | the second string. */
	fzrt_int 			start2, 		/* @parm <in> | the starting character in the second string (0 based). 
									   @rimin_imax 0 | 255 */
	fzrt_int 			num_chars		/* @parm <in> | the number of characters to compare. 
									   @rimin_imax 1 | 255 */
	);

/************************************************************************

	@scrfunc	
	
	@desc		Copies a range of characters from one string to the range of characters of another. 
				The range is defined by a starting character for each string and the number of subsequent
				characters to copy from and to. The function returns an error, if the
				starting character position for either string is not valid. If the number of
				characters to be copied is less than the number of characters in either
				range, only the number of characters in the range are copied.
				If the terminate argument is TRUE, the destination string will end after
				the copied characters. If FALSE, the original characters in the destination string
				following the copied range, will remain.
				
				Note, that it is important for this function, that the destination string contains
				valid characters (i.e. it must be initialized).
				
	@return		Error codes
		
	@avail		5.5.0.0

	@see		

	@toc		script_only_util

*************************************************************************/
fzrt_int  fz_std_strcpy_range(	
	fz_string_td	dst_str, 			/* @parm <in_out> | the destination string. */
	fzrt_int 			dst_start, 			/* @parm <in> | the starting character in the destination string (0 based). 
									   	   @rimin_imax 0 | 255 */
	fz_string_td	src_str, 			/* @parm <in> | the source string. */
	fzrt_int 			src_start, 			/* @parm <in> | the starting character in the source string (0 based). 
									       @rimin_imax 0 | 255 */
	fzrt_int 			num_chars,			/* @parm <in> | the number of characters to copy. 
									   	   @rimin_imax 1 | 255 */
	fzrt_boolean 	terminate			/* @parm <in> | set to TRUE to terminate the destination string after the copied characters. */
	);
	
/************************************************************************

	@scrfunc	
	
	@desc		Gets the nth character of a string. The character is returned in
				a separate string, which is one character fzrt_int. The function returns
				an error, if the character position is invalid
				
	@return		Error codes
		
	@avail		5.5.0.0

	@see		

	@toc		script_only_util

*************************************************************************/
fzrt_int  fz_std_str_get_char(	
	fz_string_td	src_str, 			/* @parm <in> | the source string. */
	fzrt_int 			n, 					/* @parm <in> | the character in the source string to get (0 based). 
									       @rimin_imax 0 | 255 */
	fz_string_td	dst_str 			/* @parm <out> | the string holding the character. */
	);
	
/************************************************************************

	@scrfunc	
	
	@desc		Gets the position of the character, where a given string (search string) 
				occurs in another string (source string), starting at a given character position
				in the source string. If the search string does not exist, -1 is returned.
				
	@return		The starting position of the search string in the source string
		
	@avail		5.5.0.0

	@see		

	@toc		script_only_util

*************************************************************************/
fzrt_int  fz_std_str_find_str(	
	fz_string_td	src_str, 			/* @parm <in> | the source string. */
	fzrt_int 			src_start, 			/* @parm <in> | the starting character in the source string (0 based). 
									       @rimin_imax 0 | 255 */
	fz_string_td	dst_str 			/* @parm <in> | the search string. */
	);

/************************************************************************

	@scrfunc	
	
	@desc		Converts all the letters in a string to lower case.
				
	@return		Error code
		
	@avail		5.5.0.0

	@see		

	@toc		script_only_util

*************************************************************************/
fzrt_int  fz_std_str_to_lower(	
	fz_string_td	src_str 			/* @parm <in_out> | the string to convert. */
	);
	
/************************************************************************

	@scrfunc	
	
	@desc		Converts all the letters in a string to upper case.
				
	@return		Error code
		
	@avail		5.5.0.0

	@see		

	@toc		script_only_util

*************************************************************************/
fzrt_int  fz_std_str_to_upper(	
	fz_string_td	src_str 			/* @parm <in_out> | the string to convert. */
	);

/************************************************************************

	@scrfunc	
	
	@desc		Determines if the nth character in a string is a letter (TRUE) or not (FALSE).
				
	@return		TRUE if it is, FALSE otherwise
		
	@avail		5.5.0.0

	@see		

	@toc		script_only_util

*************************************************************************/
fzrt_boolean  fz_std_str_isalpha(	
	fz_string_td	src_str, 			/* @parm <in> | the string in which to check. */
	fzrt_int			n					/* @parm <in> | the character position in the string (0 based). 
									       @rimin_imax 0 | 255 */
	);

/************************************************************************

	@scrfunc	
	
	@desc		Determines if the nth character in a string is a letter or
				decimal digit (TRUE) or not (FALSE).
				
	@return		TRUE if it is, FALSE otherwise
		
	@avail		5.5.0.0

	@see		

	@toc		script_only_util

*************************************************************************/
fzrt_boolean  fz_std_str_isalnum(	
	fz_string_td	src_str, 			/* @parm <in> | the string in which to check. */
	fzrt_int			n					/* @parm <in> | the character position in the string (0 based). 
									       @rimin_imax 0 | 255 */
	);

/************************************************************************

	@scrfunc	
	
	@desc		Determines if the nth character in a string is a control character (TRUE) or not (FALSE).
				
	@return		TRUE if it is, FALSE otherwise
		
	@avail		5.5.0.0

	@see		

	@toc		script_only_util

*************************************************************************/
fzrt_boolean  fz_std_str_iscntrl(	
	fz_string_td	src_str, 			/* @parm <in> | the string in which to check. */
	fzrt_int			n					/* @parm <in> | the character position in the string (0 based). 
									       @rimin_imax 0 | 255 */
	);

/************************************************************************

	@scrfunc	
	
	@desc		Determines if the nth character in a string is a decimal digit (TRUE) or not (FALSE).
				
	@return		TRUE if it is, FALSE otherwise
		
	@avail		5.5.0.0

	@see		

	@toc		script_only_util

*************************************************************************/
fzrt_boolean  fz_std_str_isdigit(	
	fz_string_td	src_str, 			/* @parm <in> | the string in which to check. */
	fzrt_int			n					/* @parm <in> | the character position in the string (0 based). 
									       @rimin_imax 0 | 255 */
	);
	
/************************************************************************

	@scrfunc	
	
	@desc		Determines if the nth character in a string is a printing character except space (TRUE) or not (FALSE).
				
	@return		TRUE if it is, FALSE otherwise
		
	@avail		5.5.0.0

	@see		

	@toc		script_only_util

*************************************************************************/
fzrt_boolean  fz_std_str_isgraph(	
	fz_string_td	src_str, 			/* @parm <in> | the string in which to check. */
	fzrt_int			n					/* @parm <in> | the character position in the string (0 based). 
									       @rimin_imax 0 | 255 */
	);
	
/************************************************************************

	@scrfunc	
	
	@desc		Determines if the nth character in a string is a printing character including space (TRUE) or not (FALSE).
				
	@return		TRUE if it is, FALSE otherwise
		
	@avail		5.5.0.0

	@see		

	@toc		script_only_util

*************************************************************************/
fzrt_boolean  fz_std_str_isprint(	
	fz_string_td	src_str, 			/* @parm <in> | the string in which to check. */
	fzrt_int			n					/* @parm <in> | the character position in the string (0 based). 
									       @rimin_imax 0 | 255 */
	);

/************************************************************************

	@scrfunc	
	
	@desc		Determines if the nth character in a string is a printing character except space or letter or digit (TRUE) or not (FALSE).
				
	@return		TRUE if it is, FALSE otherwise
		
	@avail		5.5.0.0

	@see		

	@toc		script_only_util

*************************************************************************/
fzrt_boolean  fz_std_str_ispunct(	
	fz_string_td	src_str, 			/* @parm <in> | the string in which to check. */
	fzrt_int			n					/* @parm <in> | the character position in the string (0 based). 
									       @rimin_imax 0 | 255 */
	);

/************************************************************************

	@scrfunc	
	
	@desc		Determines if the nth character in a string is a lower case letter (TRUE) or not (FALSE).
				
	@return		TRUE if it is, FALSE otherwise
		
	@avail		5.5.0.0

	@see		

	@toc		script_only_util

*************************************************************************/
fzrt_boolean  fz_std_str_islower(	
	fz_string_td	src_str, 			/* @parm <in> | the string in which to check. */
	fzrt_int			n					/* @parm <in> | the character position in the string (0 based). 
									       @rimin_imax 0 | 255 */
	);

/************************************************************************

	@scrfunc	
	
	@desc		Determines if the nth character in a string is an upper case letter (TRUE) or not (FALSE).
				
	@return		TRUE if it is, FALSE otherwise
		
	@avail		5.5.0.0

	@see		

	@toc		script_only_util

*************************************************************************/
fzrt_boolean  fz_std_str_isupper(	
	fz_string_td	src_str, 			/* @parm <in> | the string in which to check. */
	fzrt_int			n					/* @parm <in> | the character position in the string (0 based). 
									       @rimin_imax 0 | 255 */
	);

/************************************************************************

	@scrfunc	
	
	@desc		Determines if the nth character in a string is a space, formfeed, newline, carriage return, tab, vertical tab (TRUE) or not (FALSE).
				
	@return		TRUE if it is, FALSE otherwise
		
	@avail		5.5.0.0

	@see		

	@toc		script_only_util

*************************************************************************/
fzrt_boolean  fz_std_str_isspace(	
	fz_string_td	src_str, 			/* @parm <in> | the string in which to check. */
	fzrt_int			n					/* @parm <in> | the character position in the string (0 based). 
									       @rimin_imax 0 | 255 */
	);

/************************************************************************

	@scrfunc	
	
	@desc		Determines if the nth character in a string is a hexadecimal digit (TRUE) or not (FALSE).
				
	@return		TRUE if it is, FALSE otherwise
		
	@avail		5.5.0.0

	@see		

	@toc		script_only_util

*************************************************************************/
fzrt_boolean  fz_std_str_isxdigit(	
	fz_string_td	src_str, 			/* @parm <in> | the string in which to check. */
	fzrt_int			n					/* @parm <in> | the character position in the string (0 based). 
									       @rimin_imax 0 | 255 */
	);

/************************************************************************

	@scrfunc	
	
	@desc		Converts a string to an integer number. It is assumed, that the string
				contains valid numeric characters, such as "12" or "-100".
				
	@return		the integer derived from the string
		
	@avail		5.5.0.0

	@see		

	@toc		script_only_util

*************************************************************************/
fzrt_int  fz_std_str_to_int(
	fz_string_td	src_str 			/* @parm <in> | the string to convert. */
	);

/************************************************************************

	@scrfunc	
	
	@desc		Converts a string to a floating point number. It is assumed, that the string
				contains valid numeric characters, such as "5.01", ".001" or "-1.0e10".
				
	@return		the floating point number derived from the string
		
	@avail		5.5.0.0

	@see		

	@toc		script_only_util

*************************************************************************/
double  fz_std_str_to_double(	
	fz_string_td	src_str 			/* @parm <in> | the string to convert. */
	);

/************************************************************************
	FUIM FUNCTIONS.
*************************************************************************/
/************************************************************************

	@scrfunc	
	
	@desc		Initialize interface template. This function must be the first function called in an 
				interface setup function. The titl_str parameter is shown in the name of the dialog or 
				palette window title bar. <nl>
				
				The UUID and version are provided so that formZ can maintain some persistent information 
				about the template so that is kept in same state when it is invoked the next time. 
				This includes settings like the active tab in tab controls, the collapse state for 
				groups in palettes etc.. This information is also used to automate the predefined settings 
				menu which is present next to the reset button (when a UUID is provided). The version number 
				should start at 0 and if the content of the template is changed, the version number should be 
				increased so that formZ can properly handle persistent information from previous versions.
				
	@return		the number of characters
		
	@avail		5.0.0.0

	@see		

	@toc		script_only_fuim

*************************************************************************/
fzrt_int 	 fz_fuim_script_tmpl_init(
	fz_fuim_tmpl_ptr 	fuim_tmpl,		/* @parm	<in> | pointer to fuim template */
	fz_string_td		titl_str,		/* @parm	<in> | name of template. */
	fzrt_int				tmpl_flags,		/* @parm	<in> | flags used for how template is constructed. */
	fzrt_UUID_td		uuid, 			/* @parm	<in_opt> | UUID for template */
	fzrt_int 				version			/* @parm	<in> | version for template */
	);

/********************************************************************************************************

	@scrfunc	

	@desc		Creates a new group. 
				All items created using this group's id as a parent will appear in this group.<nl>
				An id will be created and assigned to the group and returned.<nl>
				Pass FZ_FUIM_ROOT for parent if there is no parent group.

	@return		Group id

	@avail		5.0.0.0

	@see		

	@exfile		

	@toc		script_only_fuim

*********************************************************************************************************/
fzrt_int 	 fz_fuim_script_new_group(
	fz_fuim_tmpl_ptr fuim_tmpl,			/* @parm	<in> | fuim manager							*/
	fzrt_int			parent,				/* @parm	<in> | parent group							*/
	fzrt_int			flags				/* @parm	<in> | construction flags
										   @rflag	fz_fuim_flag_enum							*/
	);

/********************************************************************************************************

	@scrfunc	

	@desc		Creates a new tab group. 
				All items created using this group's id as a parent will appear in this tab.<nl>
				An id will be created and assigned to the group and returned.<nl>
				Pass FZ_FUIM_ROOT for parent if there is no parent group.

	@return		Tab group id

	@avail		5.0.0.0

	@see		

	@exfile		

	@toc		script_only_fuim

*********************************************************************************************************/
fzrt_int 	 fz_fuim_script_new_tab_group(
	fz_fuim_tmpl_ptr 	fuim_tmpl,			/* @parm	<in> | fuim manager								*/
	fzrt_int				parent,				/* @parm	<in> | parent group								*/
	fzrt_int				flags				/* @parm	<in> | construction flags
											   @rflag	fz_fuim_flag_enum								*/
	);

/********************************************************************************************************

	@scrfunc	

	@desc		Creates a new frame group. 
				All items created using this group's id as a parent will appear in this group, bounded by a border.<nl>
				An id will be created and assigned to the group and returned.<nl>
				Pass FZ_FUIM_ROOT for parent if there is no parent group.

	@return		Frame group id

	@avail		5.0.0.0

	@see		

	@exfile		

	@toc		script_only_fuim

*********************************************************************************************************/
fzrt_int 	 fz_fuim_script_new_frame_group(
	fz_fuim_tmpl_ptr fuim_tmpl,				/* @parm	<in> | fuim manager								*/
	fzrt_int				parent,				/* @parm	<in> | parent group								*/
	fzrt_int				flags				/* @parm	<in> | construction flags
											   @rflag	fz_fuim_flag_enum								*/
	);

/********************************************************************************************************

	@scrfunc	

	@desc		Creates a new button item.<nl>
				An id will be created and assigned to the item and returned.<nl>
				Pass FZ_FUIM_ROOT for parent if there is no parent group.<nl>
				The item_func is the name of the script function, which will be called by
				formZ, when the button is pressed. This function can have any name, but must
				fit the required return type and arguments. The callback function definition is : <nl>
				<nl>
				fzrt_int	my_button_func(				<nl>
					fz_fuim_tmpl_ptr 	fuim_tmpl, 	<nl>
					fzrt_int				item_id 	<nl>
					); 	<nl>
				The button callback function should return TRUE, if it did anything when it was called.
				It should return FALSE, when noting was processed. The item_id passed in to the button
				callback function is the id generated and returned by fz_fuim_script_new_button. It is
				possible to use the same button callback function for multiple buttons. The
				item_id passed in can be used to distinguish which button is pressed. The palt_my_view.fsl
				sample script contains a use of a button and its callback function.

	@return		Button id

	@avail		5.0.0.0

	@see		

	@exfile		

	@toc		script_only_fuim

*********************************************************************************************************/
fzrt_int 	 fz_fuim_script_new_button(
	fz_fuim_tmpl_ptr fuim_tmpl,		/* @parm	<in> | fuim manager									*/
	fzrt_int				parent,				/* @parm	<in> | parent group									*/
	fzrt_int				flags,				/* @parm	<in> | construction flags
											   @rflag	fz_fuim_flag_enum									*/
	fz_string_td		titl_str,			/* @parm	<in_opt> | button title
											   @default	button item is created without a title				*/
	fz_string_td		item_func			/* @parm	<in_opt> | name of button callback function			*/
	);

/********************************************************************************************************

	@scrfunc	

	@desc		Creates a divider item that is used to separate items or groups.<nl>
				An id will be created and assigned to the item and returned.<nl>
				Pass FZ_FUIM_ROOT for parent if there is no parent group.<nl>

	@return		Divider id

	@avail		5.0.0.0

	@see		

	@exfile		

	@toc		script_only_fuim

*********************************************************************************************************/
fzrt_int 	 fz_fuim_script_new_divider(
	fz_fuim_tmpl_ptr fuim_tmpl,		/* @parm	<in> | fuim manager									*/
	fzrt_int				parent,				/* @parm	<in> | parent group									*/
	fzrt_int				flags				/* @parm	<in> | construction flags
											   @rflag	fz_fuim_flag_enum									*/
	);

/********************************************************************************************************

	@scrfunc	

	@desc		Creates a new radio button item.<nl>
				Pass FZ_FUIM_NONE for id to not assign a specific item id. 
				An id will be created and assigned to the item and returned.<nl>
				Pass FZ_FUIM_ROOT for parent if there is no parent group.<nl>

	@return		Radio button id

	@avail		5.0.0.0

	@see		

	@exfile		

	@toc		script_only_fuim

*********************************************************************************************************/
fzrt_int 	 fz_fuim_script_new_radio(
	fz_fuim_tmpl_ptr fuim_tmpl,				/* @parm	<in> | fuim manager										*/
	fzrt_int				parent,				/* @parm	<in> | parent group										*/
	fzrt_int				flags,				/* @parm	<in> | construction flags
											   @rflag	fz_fuim_flag_enum										*/
	fz_string_td		titl_str			/* @parm	<in_opt> | radio button title
											   @default	a radio button item without a title is created			*/
	);

/********************************************************************************************************

	@scrfunc	

	@desc		Creates an edit field attached to a radio button item.<nl>
				An id will be created and assigned to the item.<nl>
				Pass FZ_FUIM_ROOT for parent if there is no parent group.

	@return		Radio button item id

	@avail		5.0.0.0

	@see		

	@exfile		

	@toc		script_only_fuim

*********************************************************************************************************/
fzrt_int    fz_fuim_script_new_radio_text_edit(
	fz_fuim_tmpl_ptr fuim_tmpl,				/* @parm	<in> | fuim manager									*/
	fzrt_int				parent,				/* @parm	<in> | parent group									*/
	fz_string_td	radio_str,			/* @parm	<in> | <in_opt> | static radio button name
											   @default	a radio button item without a name is created		*/
	fzrt_int				*text_indx			/* @parm	<out_opt> | text edit item id						*/
	);

/********************************************************************************************************

	@scrfunc	

	@desc		Creates a new checkbox item.<nl>
				An id will be created and assigned to each item.<nl>
				Pass FZ_FUIM_ROOT for parent if there is no parent group.

	@return		Checkbox id

	@avail		5.0.0.0

	@see		

	@exfile		

	@toc		script_only_fuim

*********************************************************************************************************/
fzrt_int 	 fz_fuim_script_new_check(
	fz_fuim_tmpl_ptr fuim_tmpl,				/* @parm	<in> | fuim manager									*/
	fzrt_int				parent,				/* @parm	<in> | parent group									*/
	fzrt_int				flags,				/* @parm	<in> | construction flags
											   @rflag	fz_fuim_flag_enum									*/
	fz_string_td	titl_str			/* @parm	<in_opt> | checkbox title
											   @default	a checkbox item without a title is created			*/
	);

/********************************************************************************************************

	@scrfunc	

	@desc		Creates a new checkbox item.<nl>
				An id will be created and assigned to each item.<nl>
				The checkbox item id is returned by the function and the text edit item 
				id is returned in text_indx.<nl>
				Pass FZ_FUIM_ROOT for parent if there is no parent group.

	@return		Checkbox item id

	@avail		5.0.0.0

	@see		

	@exfile		

	@toc		script_only_fuim

*********************************************************************************************************/
fzrt_int	 fz_fuim_script_new_check_text_edit(
	fz_fuim_tmpl_ptr 	fuim_tmpl,			/* @parm	<in> | fuim manager									*/
	fzrt_int				parent,				/* @parm	<in> | parent group									*/
	fz_string_td	check_str,			/* @parm	<in_opt> | checkbox title
											   @default	a checkbox item without a title is created			*/
	fzrt_int				*text_indx			/* @parm	<out_opt> | text edit item id						*/
	);

/********************************************************************************************************

	@scrfunc	

	@desc		Creates a new slider item.<nl>
				An id will be created and assigned to the item.<nl>
				Pass FZ_FUIM_ROOT for parent if there is no parent group.

	@return		Slider id

	@avail		5.0.0.0

	@see		

	@exfile		

	@toc		script_only_fuim

*********************************************************************************************************/
fzrt_int 	 fz_fuim_script_new_slider(
	fz_fuim_tmpl_ptr 	fuim_tmpl,			/* @parm	<in> | fuim manager									*/
	fzrt_int				parent,				/* @parm	<in> | parent group									*/
	fzrt_int				flags,				/* @parm	<in> | construction flags
											   @rflag	fz_fuim_flag_enum									*/
	fz_string_td	titl_str			/* @parm	<in_opt> | slider title
											   @default	a slider item without a name is created				*/
	);

/********************************************************************************************************

	@scrfunc	

	@desc		Creates a new static (uneditable) text item.<nl>
				An id will be created and assigned to the item.<nl>
				Pass FZ_FUIM_ROOT for parent if there is no parent group.<nl>

	@return		Static text id

	@avail		5.0.0.0

	@see		

	@exfile		

	@toc		script_only_fuim

*********************************************************************************************************/
fzrt_int 	 fz_fuim_script_new_text_static(
	fz_fuim_tmpl_ptr 	fuim_tmpl,			/* @parm	<in> | fuim manager									*/
	fzrt_int				parent,				/* @parm	<in> | parent group									*/
	fzrt_int				flags,				/* @parm	<in> | construction flags
											   @rflag	fz_fuim_flag_enum									*/
	fz_string_td	titl_str			/* @parm	<in_opt> | item text
											   @default	an empty static text item is created				*/
	);

/********************************************************************************************************

	@scrfunc	

	@desc		Creates a new edit (editable) text item.<nl>
				An id will be created and assigned to the item.<nl>
				Pass FZ_FUIM_ROOT for parent if there is no parent group.

	@return		Edit text id

	@avail		5.0.0.0

	@see		

	@exfile		

	@toc		script_only_fuim

*********************************************************************************************************/
fzrt_int 	 fz_fuim_script_new_text_edit(
	fz_fuim_tmpl_ptr 	fuim_tmpl,			/* @parm	<in> | fuim manager									*/
	fzrt_int				parent,				/* @parm	<in> | parent group									*/
	fzrt_int				flags,				/* @parm	<in> | construction flags
											   @rflag	fz_fuim_flag_enum									*/
	fz_string_td	titl_str			/* @parm	<in_opt> | item text
											   @default	an empty static text item is created				*/
	);

/********************************************************************************************************

	@scrfunc	

	@desc		Creates a new note text item.<nl>
				An id will be created and assigned to the item.<nl>
				Pass FZ_FUIM_ROOT for parent if there is no parent group.

	@return		Note text id

	@avail		5.0.0.0

	@see		

	@exfile		

	@toc		script_only_fuim

*********************************************************************************************************/
fzrt_int 	 fz_fuim_script_new_note(
	fz_fuim_tmpl_ptr 	fuim_tmpl,			/* @parm	<in> | fuim manager									*/
	fzrt_int				parent,				/* @parm	<in> | parent group									*/
	fzrt_int				flags,				/* @parm	<in> | construction flags
											   @rflag	fz_fuim_flag_enum									*/
	fz_string_td	titl_str			/* @parm	<in_opt> | note title
											   @default	a note item without a name is created				*/
	);

/********************************************************************************************************

	@scrfunc	

	@desc		Creates a new menu item.<nl>
				Pass FZ_FUIM_NONE for id to not assign a specific item id. 
				An id will be created and assigned to the item.<nl>
				Pass FZ_FUIM_ROOT for parent if there is no parent group.<nl>
				item_func is an optional function that is called to handle actions occurring to this item.

	@return		Menu id

	@avail		5.0.0.0

	@see		

	@exfile		

	@toc		script_only_fuim

*********************************************************************************************************/
fzrt_int 	 fz_fuim_script_new_menu(
	fz_fuim_tmpl_ptr 	fuim_tmpl,			/* @parm	<in> | fuim manager									*/
	fzrt_int				parent,				/* @parm	<in> | parent group									*/
	fzrt_int				flags,				/* @parm	<in> | construction flags
											   @rflag	fz_fuim_flag_enum									*/
	fzrt_boolean		is_pop,				/* @parm	<in> | if TRUE, the menu is a popup, 
														otherwise it is a standard menu						*/
	fz_string_td	titl_str,			/* @parm	<in_opt> | menu title
											   @default	a menu item without a name is created				*/
	fz_string_td		*menu_items,		/* @parm	<in> | an array of strings, which defines the items in the menu. */
	fzrt_int				nitems				/* @parm	<in> | the number of menu items	*/
	);

/********************************************************************************************************

	@scrfunc	

	@desc		Attaches a string to a fuim item for editing. The item_id passed in should be
				the id of a fuim item, which was previously created and which supports editing
				of a string, such as a text edit item. The max_value argument determines how
				many characters the user can enter for the string.

	@return		Error codes

	@avail		5.0.0.0

	@see		fz_fuim_script_item_range_int,fz_fuim_script_item_range_double

	@exfile		

	@toc		script_only_fuim

*********************************************************************************************************/
fzrt_int 	 fz_fuim_script_item_range_string(
	fz_fuim_tmpl_ptr	fuim_tmpl,			/* @parm	<in> | fuim manager								*/
	fzrt_int				item_id,			/* @parm	<in> | item id of the fuim item to edit the string in */
	fz_string_td	data_ptr,			/* @parm	<in> | the string									*/
	fzrt_int				max_value			/* @parm	<in> | maximum number of characters allowed			*/
	);							


/********************************************************************************************************

	@scrfunc	

	@desc		Sets the valid range of fzrt_int values for a fuim item.

	@return		Error codes

	@avail		5.0.0.0

	@see		fz_fuim_script_item_range_string,fz_fuim_script_item_range_double

	@exfile		

	@toc		script_only_fuim

*********************************************************************************************************/
fzrt_int 	fz_fuim_script_item_range_int(	fz_fuim_tmpl_ptr 		fuim_tmpl, 	/* @parm	<in> | fuim manager									*/
										fzrt_int 					item_id,    /* @parm	<in> | item id of fuim item to encode				*/
										fzrt_int					*data_ptr,  /* @parm	<in> | pointer to the data							*/
										fzrt_int 					min_value,  /* @parm	<in> | minimum allowed value						*/
										fzrt_int 					max_value,  /* @parm	<in> | maximum allowed value						*/
										fz_fuim_format_int_enum format,     /* @parm	<in> | formatting option							*/
										fzrt_int 					range_flags /* @parm	<in> | range flags
																			   @rflag	fz_fuim_range_enum									*/
										);
										
/********************************************************************************************************

	@scrfunc	

	@desc		Sets the valid range of double values for a fuim item.

	@return		Error codes

	@avail		5.0.0.0

	@see		fz_fuim_script_item_range_string,fz_fuim_script_item_range_int

	@exfile		

	@toc		script_only_fuim

*********************************************************************************************************/
fzrt_int 	fz_fuim_script_item_range_double(fz_fuim_tmpl_ptr 		fuim_tmpl, 	/* @parm	<in> | fuim manager									*/
										fzrt_int 					item_id,    /* @parm	<in> | item id of fuim item to encode				*/
										double					*data_ptr,  /* @parm	<in> | pointer to the data							*/
										double 					min_value,  /* @parm	<in> | minimum allowed value						*/
										double 					max_value,  /* @parm	<in> | maximum allowed value						*/
										fz_fuim_format_float_enum format,     /* @parm	<in> | formatting option							*/
										fzrt_int 					range_flags /* @parm	<in> | range flags
																			   @rflag	fz_fuim_range_enum									*/
	);							

/********************************************************************************************************

	@scrfunc	

	@desc		Converts a bit value into a mask. 
				Useful for converting a known bit into a bit mask for use with the bit_value parameter of the 
				fuim item encode functions.
	
	@return		The mask equivalent to the bit value

	@avail		5.0.0.0

	@see		fz_fuim_script_item_range_string,fz_fuim_script_item_range_int		

	@exfile		

	@toc		script_only_fuim

*********************************************************************************************************/
fzrt_int 	 fz_fuim_script_bit_2_mask(
	fzrt_int 	lval			/* @parm	<in> | the bit value */
	);							

/********************************************************************************************************

	@scrfunc	

	@desc		Encodes a fuim item to a fzrt_int.<nl>
				The fuim item (such as a checkbox) will be 'on' if (data_ptr & bit_mask == true_value), 
				otherwise the fuim item will be 'off'.

	@return		None

	@avail		5.0.0.0

	@see		

	@exfile		

	@toc		script_only_fuim

*********************************************************************************************************/
void 	 fz_fuim_script_item_encod_int(
	fz_fuim_tmpl_ptr fuim_tmpl,			/* @parm	<in> | fuim manager								*/
	fzrt_int			item_id,			/* @parm	<in> | item id of fuim item to encode				*/
	fzrt_int			*data_ptr,			/* @parm	<in> | pointer to the data to encode				*/
	fzrt_boolean	true_value,			/* @parm	<in> | if TRUE, the true value of 
													the encoding agrees with the bit mask, 
													otherwise the true value is when the 
													bit mask doesn't find the value						*/
	fzrt_int			bit_mask			/* @parm	<in> | bit mask of value to encode					*/
	);

/********************************************************************************************************

	@scrfunc	

	@desc		Creates a new color box item.<nl>
				An id will be created and assigned to the item.<nl>
				Pass FZ_FUIM_ROOT for parent if there is no parent group.

	@return		Color picker item id

	@avail		5.0.0.0

	@see		

	@exfile		

	@toc		script_only_fuim

*********************************************************************************************************/
fzrt_int 	 fz_fuim_script_new_color_box(
	fz_fuim_tmpl_ptr fuim_tmpl,	/* @parm	<in> | fuim manager										*/
	fzrt_int	parent,				/* @parm	<in> | parent group										*/
	fzrt_int	flags,				/* @parm	<in> | construction flags
								   @rflag	fz_fuim_flag_enum										*/
	fz_string_td	color_title,		/* @parm	<in_opt> | title of the color box
								   @default	a color box item without a name is created				*/
	fz_string_td	picker_title,		/* @parm	<in_opt> | color picker title
								   @default	The color picker dialog is shown without a title		*/
	fz_rgb_float_td	*col		/* @parm	<in> | color											*/
	);

/********************************************************************************************************

	@scrfunc	

	@desc		Runs a dialog. Program execution Control stays within the dialog until the dialog is closed by the
				user, pressing OK or Cancel. The name of the callback function, which sets up the dialog template
				and dialog items is passed in. This callback function can have any name, but must
				fit the required return type and arguments. The function definition for the
				callback function is :<nl>
				<nl>
				fzrt_int	my_dialog_func(fz_fuim_tmpl_ptr fuim_tmpl);<nl>
				<nl>
				This function should first initialize the template calling fz_fuim_script_tmpl_init. One or
				more dialog items can be created with the respective fz_fuim_script_new... function and
				variables can be attached to an item with the fz_fuim_script_item_range... functions. The
				dialog callback function should return FZRT_NOERR, if it succeeds and an error if it 
				does not.

	@return		FZRT_STD_OK or FZRT_STD_CANCEL

	@avail		5.0.0.0

	@see		

	@exfile		

	@toc		script_only_fuim

*********************************************************************************************************/
fzrt_std_enum 	 fz_fuim_script_run_dialog(
	fz_string_td	dialog_func		/* @parm	<in> | name of dialog template callback function */	
	);

/********************************************************************************************************

	@scrfunc	

	@desc		Runs a dialog with the window index of a project being passed in. 
				Program execution Control stays within the dialog until the dialog is closed by the
				user, pressing OK or Cancel. The name of the callback function is passed in, which sets up the dialog template
				and dialog items. This callback function can have any name, but must
				fit the required return type and arguments. The function definition for the
				callback function is :<nl>
				<nl>
				fzrt_int	my_dialog_func(fzrt_int windex, fz_fuim_tmpl_ptr fuim_tmpl);<nl>
				<nl>
				This function should first initialize the template calling fz_fuim_script_tmpl_init. One or
				more dialog items can be created with the respective fz_fuim_script_new... function and
				variables can be attached to an item with the fz_fuim_script_item_range... functions. The
				dialog callback function should return FZRT_NOERR, if it succeeds and an error if it 
				does not.
				This function is the same as fz_fuim_script_run_dialog, except that windex is passed in
				and passed through to the callback function.

	@return		FZRT_STD_OK or FZRT_STD_CANCEL

	@avail		5.0.0.0

	@see		

	@exfile		

	@toc		script_only_fuim

*********************************************************************************************************/
fzrt_std_enum 	 fz_fuim_script_run_dialog_windex(
	fzrt_int		windex,				/* @parm	<in> | project window index */
	fz_string_td	dialog_func		/* @parm	<in> | name of dialog template callback function */	
	);

/********************************************************************************************************

	@scrfunc	

	@desc		Creates a slider item with a text edit item using a fzrt_int for the range 
				where the range value and the display range value are the same.<nl>
				An id will be created and assigned to the item.<nl>
				Pass FZ_FUIM_ROOT for parent if there is no parent group.

	@return		Static text item id

	@avail		5.0.0.0

	@see		

	@exfile		

	@toc		script_only_fuim

*********************************************************************************************************/
fzrt_int 	 fz_fuim_script_new_slider_edit_int(
	fz_fuim_tmpl_ptr fuim_tmpl,	/* @parm	<in> | fuim manager								*/
	fzrt_int	parent,				/* @parm	<in> | parent group								*/
	fz_string_td	titl_str,			/* @parm	<in_opt> | slider title
								   @default	a slider item without a name is created			*/
	fzrt_int	*data,				/* @parm	<in> | pointer to the data						*/
	fzrt_int	min,				/* @parm	<in> | minimum value of slider					*/
	fzrt_int	max,				/* @parm	<in> | maximum value of slider					*/
	fzrt_int	range_flags,		/* @parm	<in> | range flags
								   @rflag	fz_fuim_range_enum								*/
	fzrt_int	*text_item			/* @parm	<out_opt> | text edit item id					*/
	);


/********************************************************************************************************

	@scrfunc	

	@desc		Creates a slider item with a text edit item using a double for the range 
				where the range value and the display range value are the same.<nl>
				An id will be created and assigned to the item.<nl>
				Pass FZ_FUIM_ROOT for parent if there is no parent group.

	@return		Static text item id

	@avail		5.0.0.0

	@see		

	@exfile		

	@toc		script_only_fuim

*********************************************************************************************************/
fzrt_int 	 fz_fuim_script_new_slider_edit_double(
	fz_fuim_tmpl_ptr fuim_tmpl,		/* @parm	<in> | fuim manager								*/
	fzrt_int	parent,				/* @parm	<in> | parent group								*/
	fz_string_td	titl_str,			/* @parm	<in_opt> | slider title
								   @default	a slider item without a name is created			*/
	double	*data,				/* @parm	<in> | pointer to the data						*/
	double	min,				/* @parm	<in> | minimum value of slider					*/
	double	max,				/* @parm	<in> | maximum value of slider					*/
	fzrt_int	range_flags,		/* @parm	<in> | range flags
								   @rflag	fz_fuim_range_enum								*/
	fzrt_int	*text_item			/* @parm	<out_opt> | text edit item id					*/
	);

/********************************************************************************************************

	@scrfunc	

	@desc		Creates a slider item with a text edit item using a double for the range 
				where the range value is different from the display range value. 
				The range values [min, max] are mapped to the display values [pmin, pmax].<nl>
				An id will be created and assigned to the item.<nl>
				Pass FZ_FUIM_ROOT for parent if there is no parent group.

	@return		Static text item id

	@avail		5.0.0.0

	@see		

	@exfile		

	@toc		script_only_fuim

*********************************************************************************************************/
fzrt_int 	 fz_fuim_script_new_slider_edit_pcent_double(
	fz_fuim_tmpl_ptr fuim_tmpl,	/* @parm	<in> | fuim manager										*/
	fzrt_int	parent,				/* @parm	<in> | parent group										*/
	fz_string_td	titl_str,	/* @parm	<in_opt> | slider title
								   @default	a slider item without a name is created					*/
	double	*data_ptr, 			/* @parm	<in> | pointer to the data								*/
	double	min,				/* @parm	<in> | minimum value of slider (range value)			*/
	double	max,				/* @parm	<in> | maximum value of slider (range value)			*/
	double	pmin,				/* @parm	<in> | minimum value of slider (display value)			*/
	double	pmax,				/* @parm	<in> | maximum value of slider (display value)			*/
	fzrt_int	range_flags,		/* @parm	<in> | range flags
								   @rflag	fz_fuim_range_enum										*/
	fzrt_int	*text_item			/* @parm	<out_opt> | text edit item id							*/
	);

/********************************************************************************************************

	@scrfunc	

	@desc		Aligns the selected fuim items.

	@return		Error codes

	@avail		5.0.0.0

	@see		

	@exfile		

	@toc		script_only_fuim

*********************************************************************************************************/
fzrt_int 	 fz_fuim_script_item_align(
	fz_fuim_tmpl_ptr fuim_tmpl,	/* @parm	<in> | fuim manager								*/
	fzrt_int	flags,				/* @parm	<in> | alignment flags
								   @rflag	fz_fuim_align_enum								*/
	fzrt_int	knt,				/* @parm	<in> | number of items in array to align		*/
	fzrt_int	*item_ids			/* @parm	<in> | array of fuim item ids to align			*/
	);



/********************************************************************************************************

	@scrfunc	

	@desc		Changes the labels on the ok, cancel and reset buttons. 
				If a string is NULL, the associated default label is used. 
				If a string is the empty string (""), the associated button isn't drawn.

	@return		None

	@avail		5.0.0.0

	@see		

	@exfile		

	@toc		script_only_fuim

*********************************************************************************************************/
void 	 fz_fuim_script_tmpl_set_std_titles(
	fz_fuim_tmpl_ptr fuim_tmpl,	/* @parm	<in> | fuim manager						*/
	fz_string_td	str_ok,			/* @parm	<in_opt> | new ok button string			*/
	fz_string_td	str_cancel,		/* @parm	<in_opt> | new cancel button string		*/
	fz_string_td	str_reset			/* @parm	<in_opt> | new reset button string		*/
	);

/********************************************************************************************************

	@scrfunc	

	@desc		Sets a fuim item to be true when the associated boolean data (data_ptr) 
				is true (true_value). 
				The item is true when the value in data_ptr equals true_value.

	@return		None

	@avail		5.0.0.0

	@see		

	@exfile		

	@toc		script_only_fuim

*********************************************************************************************************/
void 	 fz_fuim_script_item_unary_bool(
	fz_fuim_tmpl_ptr fuim_tmpl,			/* @parm	<in> | fuim manager									*/
	fzrt_int			item_id,			/* @parm	<in> | item id										*/
	fzrt_boolean	*data_ptr,			/* @parm	<in> | pointer to data to check for true value		*/
	fzrt_boolean	true_value			/* @parm	<in> | value that indicates true					*/
	);

/********************************************************************************************************

	@scrfunc	

	@desc		Sets a fuim item to be true when the associated fzrt_int data (data_ptr) 
				is true (true_value). 
				The item is true when the value in data_ptr equals true_value.

	@return		None

	@avail		5.0.0.0

	@see		

	@exfile		

	@toc		script_only_fuim

*********************************************************************************************************/
void 	 fz_fuim_script_item_unary_int(
	fz_fuim_tmpl_ptr fuim_tmpl,	/* @parm	<in> | fuim manager									*/
	fzrt_int	item_id,			/* @parm	<in> | item id										*/
	fzrt_int	*data_ptr,			/* @parm	<in> | pointer to data to check for true value		*/
	fzrt_int	true_value			/* @parm	<in> | value that indicates true					*/
	);


/************************************************************************

	@scrfunc	
	
	@desc		Reads an integer value from a file. The integer number
				must be separated by white space (blanks, tabs, returns ...).
				The file must have been opened for read (see fz_std_fopen).
				
	@return		# of digits read, or negative if an error occurred.
		
	@avail		5.0.1.0

	@see		fz_std_fprint_int

	@toc		script_only_util

*************************************************************************/
fzrt_int  fz_std_fscan_int(	
	FILE	*file,			/* @parm <in> | file to be read from. */
	fzrt_int	*lval			/* @parm <out> | the integer to be read. */
	);
	
/************************************************************************

	@scrfunc	
	
	@desc		Reads TRUE or FALSE from a file. If the item to be
				read is not TRUE or FALSE, the boolean value is
				assigned FALSE. The boolean values in the file must
				be separated by white space (blanks, tabs, returns ...).
				The file must have been opened for read (see fz_std_fopen).
				
	@return		# of characters read, or negative if an error occurred.
		
	@avail		5.0.1.0

	@see		fz_std_fprint_bool

	@toc		script_only_util

*************************************************************************/
fzrt_int  fz_std_fscan_bool(	
	FILE			*file,			/* @parm <in> | file to be read from. */
	fzrt_boolean	*bval			/* @parm <out> | the boolean to be read. */
	);
	
/************************************************************************

	@scrfunc	
	
	@desc		Reads a floating point value from a file. 
				The floating point value in the file must
				be separated by white space (blanks, tabs, returns ...).
				The file must have been opened for read (see fz_std_fopen).
				
	@return		# of digits read, or negative if an error occurred.
		
	@avail		5.0.1.0

	@see		fz_std_fprint_float

	@toc		script_only_util

*************************************************************************/
fzrt_int  fz_std_fscan_float(	
	FILE			*file,			/* @parm <in> | file to be read from. */
	double			*dval			/* @parm <out> | the number to be read. */
	);
	
/************************************************************************

	@scrfunc	
	
	@desc		Reads a string from a file.
				The string in the file must
				be separated by white space (blanks, tabs, returns ...).
				The file must have been opened for read (see fz_std_fopen).
				
	@return		# of characters read, or negative if an error occurred.
		
	@avail		5.0.1.0

	@see		fz_std_fprint_str

	@toc		script_only_util

*************************************************************************/
fzrt_int  fz_std_fscan_str(	
	FILE			*file,			/* @parm <in> | file to be read from. */
	fz_string_td	str			/* @parm <out> | the string to be read. */
	);
	
/************************************************************************

	@scrfunc	
	
	@desc		Reads a tag value from a file. 
				The tag in the file must
				be separated by white space (blanks, tabs, returns ...).
				The file must have been opened for read (see fz_std_fopen).
				
	@return		# of characters read, or negative if an error occurred.
		
	@avail		5.0.1.0

	@see		fz_std_fprint_tag

	@toc		script_only_util

*************************************************************************/
fzrt_int  fz_std_fscan_tag(	
	FILE			*file,			/* @parm <in> | file to be read from. */
	fz_tag_td		*tag			/* @parm <out> | the tag value to be read. */
	);

/************************************************************************

	@scrfunc	
	
	@desc		Reads a uuid value from a file. 
				The uuid in the file must
				be separated by white space (blanks, tabs, returns ...).
				The file must have been opened for read (see fz_std_fopen).
				
	@return		# of characters read, or negative if an error occurred.
		
	@avail		5.0.1.0

	@see		fz_std_fprint_uuid

	@toc		script_only_util

*************************************************************************/
fzrt_int  fz_std_fscan_uuid(	
	FILE			*file,					/* @parm <in> | file to be read from. */
	fzrt_UUID_td	uuid					/* @parm <out> | the uuid value to be read. */
	);

/************************************************************************

	@scrfunc	
	
	@desc		Reads an integer value from a string. The integer number
				must be separated by white space (blanks, tabs, returns ...).
				
	@return		# of digits read, or negative if an error occurred.
		
	@avail		5.0.1.0

	@see		fz_std_sprint_int

	@toc		script_only_util

*************************************************************************/
fzrt_int  fz_std_sscan_int(	
	fz_string_td	str,			/* @parm <in> | string to be read from. */
	fzrt_int	*lval			/* @parm <out> | the integer to be read. */
	);
	
/************************************************************************

	@scrfunc	
	
	@desc		Reads TRUE or FALSE from a string. If the item to be
				read is not TRUE or FALSE, the boolean value is
				assigned FALSE. The boolean values in the string must
				be separated by white space (blanks, tabs, returns ...).
				
	@return		# of characters read, or negative if an error occurred.
		
	@avail		5.0.1.0

	@see		fz_std_sprint_bool

	@toc		script_only_util

*************************************************************************/
fzrt_int  fz_std_sscan_bool(	
	fz_string_td	str,			/* @parm <in> | string to be read from. */
	fzrt_boolean	*bval			/* @parm <out> | the boolean to be read. */
	);
	
/************************************************************************

	@scrfunc	
	
	@desc		Reads a floating point value from a string. 
				The floating point value in the string must
				be separated by white space (blanks, tabs, returns ...).
				
	@return		# of digits read, or negative if an error occurred.
		
	@avail		5.0.1.0

	@see		fz_std_sprint_float

	@toc		script_only_util

*************************************************************************/
fzrt_int  fz_std_sscan_float(	
	fz_string_td	str,			/* @parm <in> | string to be read from. */
	double			*dval			/* @parm <out> | the number to be read. */
	);
		
/************************************************************************

	@scrfunc	
	
	@desc		Reads a tag value from a string. 
				The tag in the string must
				be separated by white space (blanks, tabs, returns ...).
				
	@return		# of characters read, or negative if an error occurred.
		
	@avail		5.0.1.0

	@see		fz_std_sprint_tag

	@toc		script_only_util

*************************************************************************/
fzrt_int  fz_std_sscan_tag(	
	fz_string_td	str,			/* @parm <in> | string to be read from. */
	fz_tag_td		*tag			/* @parm <out> | the tag value to be read. */
	);

/************************************************************************

	@scrfunc	
	
	@desc		Reads a uuid value from a string. 
				The uuid in the string must
				be separated by white space (blanks, tabs, returns ...).
				
	@return		# of characters read, or negative if an error occurred.
		
	@avail		5.0.1.0

	@see		fz_std_sprint_uuid

	@toc		script_only_util

*************************************************************************/
fzrt_int  fz_std_sscan_uuid(	
	fz_string_td	str,					/* @parm <in> | string to be read from. */
	fzrt_UUID_td	uuid					/* @parm <out> | the uuid value to be read. */
	);

#ifdef __cplusplus
}
#endif

#endif /*__FORMZ_SCRIPT_ONLY_API_H */

