/*********************************************************************************************
 *                                                                                           *
 *                                                                                           *
 *   Copyright 1989-2018 by AutoDesSys, Inc.                                                 *
 *                                                                                           *
 *   This software and its associated documentation contains proprietary,                    *
 *   confidential, and trade secret information of AutoDesSys Inc. and may not be            *
 *   disclosed, copied in any form, or used for any purpose except as specifically           *
 *   permitted in writing by AutoDesSys, Inc.                                                *
 *                                                                                           *
 *   AutoDesSys, Inc. grants permission to use the software to those who purchase            *
 *   a license.  Such a usage will be made according to the terms and conditions             *
 *   specified in the license agreement to which a licensee agrees before installing         *
 *   and commencing usage of the software.  The license agreement can be found               *
 *   on the envelop that contains the software CD.                                           *
 *                                                                                           *
 *   AutoDesSys, Inc. also grants permission to licensees to develop extensions to           *
 *   the software, which can be in the form of scripts or plugins.  The permission           *
 *   includes calling the API and call back functions provided by AutoDesSys, Inc.           *
 *   and accessing information relevant to these functions and the general workings          *
 *   of form.Z, but only up to the point to which AutoDesSys, Inc. has chosen to             *
 *   expose, through its form.Z SDK Manual.  All extensions developed by third               *
 *   parties will include a copy of this copyright note in an easily accessible place or     *
 *   a clear instruction to read this original note by AutoDesSys, Inc.                      *
 *                                                                                           *
 *   All the software distributed under a license, either for the purpose of using it or     *
 *   for the purpose of developing extensions, is distributed AS IS, WITHOUT                 *
 *   WARRANTY OF ANY KIND, EITHER EXPRESS OR IMPLIED, AND                                    *
 *   AutoDesSys, Inc. HEREBY DISCLAIMS ALL SUCH WARRANTIES,                                  *
 *   INCLUDING WITHOUT LIMITATION, ANY WARRANTIES OF                                         *
 *   MERCHANTABILITY OR FITNESS FOR A PARTICULAR PURPOSE.                                    *
 *                                                                                           *
 *   formZ, RenderZone, and RadioZity are registered trademarks of AutoDesSys, Inc.          *
 *                                                                                           *
 *   form.Z SDK, Version 8.6.3, Dec 03, 2018                                                 *
 *                                                                                           *
 *                                                                                           *
 *********************************************************************************************/


#ifndef _FZ_FUIM_PROG_API
#define _FZ_FUIM_PROG_API

#ifdef __cplusplus
extern "C" {
#endif



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

	Progress Bar


	Description
		Functions for constructing and managing progress bars.  Progress bars are used to display 
		a window to the user when an operation takes some duration of time to complete.
 ****************************************************************/

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

	fz_fuim_prog_kind_enum


	Description
		Fuim progress kind. There are two types of progress bars. The normal progress bar has a progress 
		indicator, a short information field and a short detail field. The expanded progress bar has a progress 
		indicator and a single line information field and a multi-line detail field.

	Members
		FZ_FUIM_PROG_KIND_NORMAL
			normal progress bar
		FZ_FUIM_PROG_KIND_EXPANDED
			detailed progress bar

	Availability	5.0.0.0


	See Also
		fz_fuim_prog_init

 ****************************************************************/
typedef enum fz_fuim_prog_kind_enum
{	FZ_FUIM_PROG_KIND_NORMAL=1,
	FZ_FUIM_PROG_KIND_EXPANDED,
	
	FZ_FUIM_PROG_KIND_MAX
} fz_fuim_prog_kind_enum;
/****************************************************************

	fz_fuim_prog_init



	Description
		Initialize progress bar. This function creates a progress bar used to indicate a time consuming task. The stages parameter 
		indicates how many tasks the progress bar will show. Each stage is started with a call to fz_fuim_prog_stage_init and 
		completed with a call to fz_fuim_prog_stage_finit. The progress bar contains a graphic progress indicator which 
		indicates the progress of the task. If the progress bar contains a multiple stages (stages greater than 1), then there are two 
		graphic progress indicators shown. The top indicator indicates the overall progress of all stages and is evenly 
		segmented to represent each stage. The lower indicator indicates the progress of the current stage. 

		By default the progress bar is shown on the screen after 2 seconds of processing. This can be adjusted with the 
		fz_fuim_prog_set_delay function. The progress bar is updated during fz_fuim_curs_wait calls when the use_clock parameter is TRUE. 
		If use_clock is FALSE then the progress bar is only updated when fz_fuim_prog_update is called. For the smoothest interface 
		and best performance, it is recommended that use_clock is set to TRUE and fz_fuim_curs_wait function is called during the execution 
		of the task. 

		The progress bar also contains a cancel button in the lower right corner. The function fz_fuim_key_cancel can be used to 
		determine if the user has clicked the cancel button or pressed a cancel key shortcut. The function fz_fuim_prog_stage_set_cancel 
		can be used to disable the cancel button or change the title of the button.

	Parameters
		stages  [Input]
			number of stages in progress bar
		kind  [Input]
			kind of progress bar to display
		use_clock  [Input]
			if TRUE, then progress bar is updated when  fz_fuim_curs_wait() is called 
			if FALSE, then progress bar is updated when fz_fuim_prog_update is called

	Returns
		Error codes


	Availability	5.0.0.0


	See Also
		fz_fuim_prog_finit,fz_fuim_prog_stage_init,fz_fuim_prog_stage_finit,fz_fuim_prog_set_delay,fz_fuim_curs_wait,fz_fuim_prog_stage_set_cancel,fz_fuim_key_cancel

 ****************************************************************/
typedef fzrt_error_td  (*fz_fuim_prog_init_func)(
	fzrt_int 					stages,
	fz_fuim_prog_kind_enum		kind,
	fzrt_boolean 			use_clock
	);

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

	fz_fuim_prog_finit



	Description
		Finalize progress bar. Completes the progress bar and removes it from the screen.

	Returns
		Error codes


	Availability	5.0.0.0


	See Also
		fz_fuim_prog_init

 ****************************************************************/
typedef fzrt_error_td  (*fz_fuim_prog_finit_func)(void);
		
/****************************************************************

	fz_fuim_prog_set_delay



	Description
		Set progress delay. This function sets the delay before the progress bar is shown on the screen. 
		The default delay is 2 seconds. A delay of 0 causes the progress bar to be show immediately. 
		This function should be called immediately after fz_fuim_prog_init()

	Parameters
		delay_time  [Input]
			time to delay (in 1/60 of second)

	Returns
		Error codes


	Availability	5.0.0.0


	See Also
		fz_fuim_prog_get_delay

 ****************************************************************/
typedef fzrt_error_td  (*fz_fuim_prog_set_delay_func)(
	fzrt_int 		delay_time
	);

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

	fz_fuim_prog_get_delay



	Description
		Get current Progress Delay. Retrieves the current progress delay setting for the progress bar.

	Parameters
		delay_time  [Result]
			current delay (in 1/60 of second)

	Returns
		Error codes


	Availability	5.0.0.0


	See Also
		fz_fuim_prog_set_delay

 ****************************************************************/
typedef fzrt_error_td  (*fz_fuim_prog_get_delay_func)(
	fzrt_int 		*delay_time
	);


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

	fz_fuim_prog_update



	Description
		Update Progress bar. This function redraws the progress bar on the screen. This function is 
		automatically called from fz_fuim_curs_wait() when the use_clock parameter is set to TRUE in fz_fuim_prog_init. 
		Note that if the initial delay time has not been reached, nothing is drawn. 

		To prevent the progress bar from consuming an large amount of CPU time by being updated too frequently, 
		the function has an internal timer such that it only actually performs an update no more than every 1/3 of a second.

	Returns
		Error codes


	Availability	5.0.0.0


	See Also
		fz_fuim_prog_init,fz_fuim_prog_set_delay

 ****************************************************************/
typedef fzrt_error_td  (*fz_fuim_prog_update_func)(void);


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

	fz_fuim_prog_enable



	Description
		Enable or disable progress bar. This function can be used to disable the progress bar so that 
		subsequent calls to fz_fuim_prog_stage_init will not create a progress bar. This is useful for suppressing a 
		progress bar in when calling a function that normally uses a progress bar. This function should be 
		used with caution and always must be called twice, once to disable the progress bar and once to re-enable it. 
		Unbalanced calls will perminantly disable the progress bar.

	Parameters
		enable  [Input]
			

	Returns
		Error codes


	Availability	5.0.0.0


	See Also
		fz_fuim_prog_stage_init

 ****************************************************************/
typedef fzrt_error_td  (*fz_fuim_prog_enable_func)(
	fzrt_boolean 		enable
	);

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

	fz_fuim_prog_hide_show



	Description
		Show or hide progress bar. This function shows or hides the current progress bar window. This function 
		does not need to be called to make a progress bar initially visible as fz_fuim_prog_update will do this as soon 
		as the delay time has expired. This function can be used to hide and re-display a progress bar in the event 
		that you task needs to perform some action where the progress bar interferes with the operation.

	Parameters
		show  [Input]
			If TRUE then the progress bar window is shown 
			if FALSE then the window is hidden

	Returns
		Error codes


	Availability	5.0.0.0

 ****************************************************************/
typedef fzrt_error_td  (*fz_fuim_prog_hide_show_func)(
	fzrt_boolean 		show
	);

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

	fz_fuim_prog_stage_init



	Description
		Initialize a progress stage. This function indicates the start of a stage of the progress bar. The progress 
		of the stage is communicated to the progress bar by specifying the range of the stage and then subsequent calls to 
		fz_fuim_prog_stage_set_current to move the indicator along the range (from min to max). To make a smooth progress bar, 
		find a good way of measuring the range of the task and the progress of the task. The range (max - min) should 
		be greater than 400. 

		If the current stage has not been finalized with fz_fuim_prog_stage_finit, it is automatically finalized starting 
		the new stage. 

	Parameters
		name  [Input]
			name of the stage (appears in the title bar of the progress bar)
		min  [Input]
			minimum value for stage range
		max  [Input]
			maximum value for stage range

	Returns
		Error codes


	Availability	5.0.0.0


	See Also
		fz_fuim_prog_stage_finit,fz_fuim_prog_stage_set_current

 ****************************************************************/
typedef fzrt_error_td  (*fz_fuim_prog_stage_init_func)(
	char 		*name,
	fzrt_int 		min,
	fzrt_int 		max
	);

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

	fz_fuim_prog_stage_finit



	Description
		Finalize a progress stage. This function completes the stage and the progress indicator is drawn at the maximum position. 
		This function does not need to be called between calls to fz_fuim_prog_stage_init as fz_fuim_prog_stage_init will automatically 
		finalize a stage before starting a new stage. Use the function to indicate the completion of the stage when there may 
		be a delay before the start of the next stage or the completion of the progress bar.

	Returns
		Error codes


	Availability	5.0.0.0


	See Also
		fz_fuim_prog_stage_init

 ****************************************************************/
typedef fzrt_error_td  (*fz_fuim_prog_stage_finit_func)(void);

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

	fz_fuim_prog_stage_set_current



	Description
		Set the current progress stage indicator value. This function calls fz_fuim_prog_update to update the progress bar.

	Parameters
		current  [Input]
			current value for progress

	Returns
		Error codes


	Availability	5.0.0.0


	See Also
		fz_fuim_prog_stage_init,fz_fuim_prog_stage_get_current

 ****************************************************************/
typedef fzrt_error_td  (*fz_fuim_prog_stage_set_current_func)(
	fzrt_int 		current
	);
	
/****************************************************************

	fz_fuim_prog_stage_get_current



	Description
		Get the value of the current progress stage indicator

	Parameters
		current  [Input]
			current value for progress

	Returns
		Error codes


	Availability	5.0.0.0


	See Also
		fz_fuim_prog_stage_set_current

 ****************************************************************/
typedef fzrt_error_td  (*fz_fuim_prog_stage_get_current_func)(
	fzrt_int 		*current
	);

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

	fz_fuim_prog_stage_set_range



	Description
		Set the range for the current progress stage. This overrides the range specified in fz_fuim_prog_stage_init.

	Parameters
		min  [Input]
			minimum value for stage range
		max  [Input]
			maximum value for stage range

	Returns
		Error codes


	Availability	5.0.0.0


	See Also
		fz_fuim_prog_stage_init,fz_fuim_prog_stage_get_range

 ****************************************************************/
typedef fzrt_error_td  (*fz_fuim_prog_stage_set_range_func)(
	fzrt_int 		min,
	fzrt_int 		max
	);
	
/****************************************************************

	fz_fuim_prog_stage_get_range



	Description
		Get the range for the current progress stage.

	Parameters
		min  [Result, Optional]
			current minimum value for stage range
		max  [Result, Optional]
			current maximum value for stage range

	Returns
		Error codes


	Availability	5.0.0.0


	See Also
		fz_fuim_prog_stage_set_range

 ****************************************************************/
typedef fzrt_error_td  (*fz_fuim_prog_stage_get_range_func)(
	fzrt_int 		*min,
	fzrt_int 		*max
	);

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

	fz_fuim_prog_stage_set_title



	Description
		Set the title of the current progress stage. This overrides the range specified in fz_fuim_prog_stage_init.

	Parameters
		title  [Input]
			title for progress bar (set initially in fz_fuim_prog_stage_init)

	Returns
		Error codes


	Availability	5.0.0.0


	See Also
		fz_fuim_prog_stage_init,fz_fuim_prog_stage_get_title

 ****************************************************************/
typedef fzrt_error_td  (*fz_fuim_prog_stage_set_title_func)(
	char 		*title
);
/****************************************************************

	fz_fuim_prog_stage_get_title



	Description
		Get the title of the current progress stage.

	Parameters
		title  [Result, Optional]
			title for progress bar (set initially in fz_fuim_prog_stage_init)
		title_len  [Input, Optional]
			length of the prog_title parameter

	Returns
		Error codes


	Availability	5.0.0.0


	See Also
		fz_fuim_prog_stage_set_title

 ****************************************************************/
typedef fzrt_error_td  (*fz_fuim_prog_stage_get_title_func)(
	char 		*title,
	fzrt_int		title_len
);
/****************************************************************

	fz_fuim_prog_stage_set_strings



	Description
		Set the current progress information and detail strings. The information string is usually a description of 
		the task progress and often is the subject for the detail string. For example, when reading a file the 
		information string could be "Lines Read:" and the detail string could be the actual number of lines currently read. 
		In this type of implementation the function is called once immediately after a fz_fuim_prog_stage_init 
		with the information string. It is then called immediately before each fz_fuim_prog_stage_set_current call 
		to set the detail string. 

		Note that for progress bars initialized with FZ_FUIM_PROG_KIND_NORMAL, the space for the strings is 
		small and the strings appear side by side with the information string on the left and the detail on the right. 
		For progress bars initialized with FZ_FUIM_PROG_KIND_EXPANDED, the information string is the width of the progress 
		bar and the detail string appears below it and can contain up to three lines.

	Parameters
		prog_info  [Input, Optional]
			string for the progress information field
		prog_detail  [Input, Optional]
			string for the progress detail field

	Returns
		Error codes


	Availability	5.0.0.0


	See Also
		fz_fuim_prog_stage_init,fz_fuim_prog_stage_set_current,fz_fuim_prog_stage_get_strings

 ****************************************************************/
typedef fzrt_error_td  (*fz_fuim_prog_stage_set_strings_func)(
	char 		*prog_info,
	char		*prog_detail
	);

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

	fz_fuim_prog_stage_get_strings



	Description
		Get the current progress information strings.

	Parameters
		prog_info  [Result, Optional]
			string for the progress information field
		prog_info_len  [Input, Optional]
			length of the prog_info parameter
		prog_detail  [Result, Optional]
			string for the progress detail field
		prog_detail_len  [Input, Optional]
			length of the prog_detail parameter

	Returns
		Error codes


	Availability	5.0.0.0


	See Also
		fz_fuim_prog_stage_set_strings

 ****************************************************************/
typedef fzrt_error_td  (*fz_fuim_prog_stage_get_strings_func)(
	char 		*prog_info,
	fzrt_int 		prog_info_len,
	char		*prog_detail,
	fzrt_int		prog_detail_len
	);

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

	fz_fuim_prog_cancel_enum


	Description
		Fuim progress cancel button state.

	Members
		FZ_FUIM_PROG_CANCEL_ENABLED
			progress cancel button is enabled
		FZ_FUIM_PROG_CANCEL_DISABLED
			progress cancel button is disabled (dimmed)
		FZ_FUIM_PROG_CANCEL_SELECTED
			progress cancel button is selected (highlighted)

	Availability	5.0.0.0

 ****************************************************************/
typedef enum fz_fuim_prog_cancel_enum
{	FZ_FUIM_PROG_CANCEL_ENABLED=0,
	FZ_FUIM_PROG_CANCEL_DISABLED=255,
	FZ_FUIM_PROG_CANCEL_SELECTED=1,
	
	FZ_FUIM_PROG_CANCEL_MAX
} fz_fuim_prog_cancel_enum;
/****************************************************************

	fz_fuim_prog_stage_set_cancel



	Description
		Set progress button state and title. The progress button is by default enabled with the "Cancel" 
		(localized) as the title. button. This function can  be used to change the enabled state of the button 
		or to change its title. 

		Setting the state to FZ_FUIM_PROG_CANCEL_DISABLED disables the button and ability to cancel the 
		task. Setting the state to FZ_FUIM_PROG_CANCEL_SELECTED indicates that to progress has been canceled by some 
		specific action in the task.  

		Changing the title should be used with caution because the button will still act like a cancel button 
		(responds to clicks and cancel key shortcuts). An acceptable reason to change the title is to use 
		the string "Pause" to indicate that a task can be suspended and then resumed. To implement this, the 
		task should enter a suspended state when fz_fuim_key_cancel indicates that the process has been canceled.

	Parameters
		state  [Input, Optional]
			new state for the cancel button
		title  [Input, Optional]
			title for progress button (Cancel by default)

	Returns
		Error codes


	Availability	5.0.0.0


	See Also
		fz_fuim_prog_init,fz_fuim_prog_stage_get_cancel

 ****************************************************************/
typedef fzrt_error_td  (*fz_fuim_prog_stage_set_cancel_func)(
	fz_fuim_prog_cancel_enum 	*state,
	char 						*title
	);

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

	fz_fuim_prog_stage_get_cancel



	Description
		Get progress cancel state and title.

	Parameters
		state  [Result, Optional]
			current state of the cancel button
		title  [Result, Optional]
			title for progress button (Cancel by default)
		title_len  [Input, Optional]
			length of the title parameter

	Returns
		Error codes


	Availability	5.0.0.0


	See Also
		fz_fuim_prog_stage_set_cancel

 ****************************************************************/
typedef fzrt_error_td  (*fz_fuim_prog_stage_get_cancel_func)(
	fz_fuim_prog_cancel_enum 	*state,
	char 						*title,
	fzrt_int						title_len
	);


#ifdef __cplusplus
}
#endif

#endif
