/*********************************************************************************************
 *                                                                                           *
 *                                                                                           *
 *   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_ALRT_API_
#define _FZ_FUIM_ALRT_API_

#ifdef __cplusplus
extern "C" {
#endif


#include "fzpl_plugin.h"
#include "fz_type_api.h"


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

	Alerts


	Description
		Alerts are simple dialogs that present information or questions to the user. They are 
		frequently used for error notification or for asking the user questions at critical times. 
		Alerts usually consist of a simple message and one or more buttons for the user to select 
		the desired response to the alert. Some common standard alerts are provided in the functions 
		fz_fuim_alrt_std_confirm, fz_fuim_alrt_std_name and fz_fuim_alrt_std_error.

		Custom alerts are created by calling fz_fuim_alrt_ptr_init followed by calls to fz_fuim_alrt_ptr_add_str, 
		fz_fuim_alrt_ptr_add_button to create the content of the alert. The alert is then shown on the screen 
		using fz_fuim_alrt_driver which returns the button that is clicked by the user. 
		The alert should be freed with a call to fz_fuim_alrt_ptr_finit.
 ****************************************************************/


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

	fz_fuim_alrt_ptr


	Description
		fuim alert manager main data structure

	Availability	5.0.0.0


	See Also
		fz_fuim_alrt_ptr_add_button, fz_fuim_alrt_ptr_add_str

 ****************************************************************/
typedef struct fuim_alrt_td *fz_fuim_alrt_ptr;


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

	fz_fuim_alrt_flag_enum


	Description
		Alert options. These bit flags are used to set options in Alerts.

	Members
		FZ_FUIM_ALRT_FLAG_NONE
			default alert options
		FZ_FUIM_ALRT_FLAG_BVRT
			if set buttons in alert are vertical, else horizontal (default)
		FZ_FUIM_ALRT_FLAG_LGINFO
			if set the info area of the laert is made larger to handle more text.

	Availability	5.0.0.0


	See Also
		fz_fuim_alrt_ptr_init

 ****************************************************************/
typedef enum fz_fuim_alrt_flag_enum
{	FUIM_ALRT_FLAG_BVRT_BIT=0,
	FUIM_ALRT_FLAG_LGINFO_BIT=1,
	FUIM_ALRT_FLAG_BIT_MAX,
	FZ_FUIM_ALRT_FLAG_NONE=0,
	FZ_FUIM_ALRT_FLAG_BVRT=(1<<FUIM_ALRT_FLAG_BVRT_BIT),
	FZ_FUIM_ALRT_FLAG_LGINFO=(1<<FUIM_ALRT_FLAG_LGINFO_BIT)
} fz_fuim_alrt_flag_enum;

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

	fz_fuim_alrt_icon_enum


	Description
		Alert Icons. Identifies what standard icon should be placed in the alert. The icon is a graphic indication 
		to the user as to the severity of the alert.

	Members
		FZ_FUIM_ALRT_ICON_NONE
			indicates no icon
		FZ_FUIM_ALRT_ICON_WARN
			indicates a warning icon
		FZ_FUIM_ALRT_ICON_INFO
			indicates a informational icon
		FZ_FUIM_ALRT_ICON_STOP
			indicates a stop sign icon

	Availability	5.0.0.0


	See Also
		fz_fuim_alrt_ptr_init

 ****************************************************************/
typedef enum fz_fuim_alrt_icon_enum
{	FZ_FUIM_ALRT_ICON_NONE=0,
	FZ_FUIM_ALRT_ICON_WARN,
	FZ_FUIM_ALRT_ICON_INFO,
	FZ_FUIM_ALRT_ICON_STOP
} fz_fuim_alrt_icon_enum;


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

	fz_fuim_alrt_butn_opts_enum


	Description
		Alert button options. These bit flags are used to set options in alert buttons. The default button 
		(FZ_FUIM_ALRT_BUT_DEF) is the button that is selected when the user presses the return/enter key. 
		This should be set for the desired default button. The default cancel button (FZ_FUIM_ALRT_BUT_DEF) 
		is selected when the user presses standard cancel keys (>esc< key).

	Members
		FZ_FUIM_ALRT_BUT_NONE
			button has no options
		FZ_FUIM_ALRT_BUT_DEF
			button is the default (OK) button for the alert
		FZ_FUIM_ALRT_BUT_DEF_CANCEL
			button is the default (CANCEL) button for the alert

	Availability	5.0.0.0


	See Also
		fz_fuim_alrt_ptr_add_button

 ****************************************************************/
typedef enum fz_fuim_alrt_butn_opts_enum
{	FZ_FUIM_ALRT_BUT_NONE=0,
	FZ_FUIM_ALRT_BUT_DEF,
	FZ_FUIM_ALRT_BUT_DEF_CANCEL
} fz_fuim_alrt_butn_opts_enum;

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

	fz_fuim_alrt_button_enum


	Description
		Alert button title.  Identifies what string (text) should appear in a button string. There are 
		five standard strings. These will appear using the current language. A custom button title can be 
		specified using FZ_FUIM_ALRT_BUTTON_CUSTOM.

	Members
		FZ_FUIM_ALRT_BUTTON_OK
			button is standard OK button (localized)
		FZ_FUIM_ALRT_BUTTON_CANCEL
			button is standard Calcel button (localized)
		FZ_FUIM_ALRT_BUTTON_YES
			button is standard Yes button (localized)
		FZ_FUIM_ALRT_BUTTON_NO
			button is standard No button (localized)
		FZ_FUIM_ALRT_BUTTON_QUIT
			button is standard Quit button (localized)
		FZ_FUIM_ALRT_BUTTON_CUSTOM
			button has custom title specified

	Availability	5.0.0.0


	See Also
		fz_fuim_alrt_ptr_add_button

 ****************************************************************/
typedef enum fz_fuim_alrt_button_enum
{	FZ_FUIM_ALRT_BUTTON_OK=0,
	FZ_FUIM_ALRT_BUTTON_CANCEL,
	FZ_FUIM_ALRT_BUTTON_YES,
	FZ_FUIM_ALRT_BUTTON_NO,
	FZ_FUIM_ALRT_BUTTON_QUIT,
	FZ_FUIM_ALRT_BUTTON_CUSTOM
} fz_fuim_alrt_button_enum;

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

	fz_fuim_alrt_str_opts_enum


	Description
		Alert string options.  Option flags for alert strings. Currently there are no flags. Exists for future compatibility.

	Members
		FZ_FUIM_ALRT_STR_NONE
			string has no options

	Availability	5.0.0.0

 ****************************************************************/
typedef enum fz_fuim_alrt_str_opts_enum
{	FZ_FUIM_ALRT_STR_NONE=0
} fz_fuim_alrt_str_opts_enum;

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

	fz_fuim_std_conf_enum


	Description
		Standard confirm alert options. Identifies which buttons should be present in a standard confirm alert.

	Members
		FZ_FUIM_ALRT_CONFIRM_OK
			alert has a OK (localized) button
		FZ_FUIM_ALRT_CONFIRM_OK_CANCEL
			alert has a OK (localized) and Cancel (localized) button
		FZ_FUIM_ALRT_CONFIRM_OK_CANCEL_DEF
			Same as FZ_FUIM_ALRT_CONFIRM_OK_CANCEL, but the CANCEL button 
			is the default button (i.e. hitting return or enter will cancel, not ok the dialog)

	Availability	5.0.0.0

 ****************************************************************/
typedef enum fz_fuim_std_conf_enum
{	FZ_FUIM_ALRT_CONFIRM_OK=0,
	FZ_FUIM_ALRT_CONFIRM_OK_CANCEL,
	FZ_FUIM_ALRT_CONFIRM_OK_CANCEL_DEF
} fz_fuim_std_conf_enum;

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

	fz_fuim_alrt_ptr_init



	Description
		Creates a custom alert. This function allocates memory for a new custom alert. The functions fz_fuim_alrt_ptr_add_str, 
		fz_fuim_alrt_ptr_add_button should be used to create the content of the alert. The alert is then shown on the screen 
		using fz_fuim_alrt_driver which returns the button that is clicked by the user. 
		The alert should be freed with a call to fz_fuim_alrt_ptr_finit.

	Parameters
		fuim_alrt  [Result]
			pointer to alert
		flags  [Input]
			option flags
		alrt_icon  [Input]
			icon to show in alert
		alrt_title  [Input, Optional]
			Alert name to appear in title bar

	Returns
		Error codes


	Availability	5.0.0.0


	See Also
		fz_fuim_alrt_flag_enum,fz_fuim_alrt_icon_enum,fz_fuim_alrt_driver,fz_fuim_alrt_ptr_finit

 ****************************************************************/
typedef fzrt_error_td  (*fz_fuim_alrt_ptr_init_func) (
	fz_fuim_alrt_ptr 		*fuim_alrt,
	fz_fuim_alrt_flag_enum	flags,
	fz_fuim_alrt_icon_enum 	alrt_icon,
	char 					*alrt_title
	);

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

	fz_fuim_alrt_ptr_finit



	Description
		Frees a custom alert.

	Parameters
		fuim_alrt  [Input, Result]
			pointer to alert to free

	Returns
		error codes


	Availability	5.0.0.0


	See Also
		fz_fuim_alrt_ptr_init

 ****************************************************************/
typedef void  (*fz_fuim_alrt_ptr_finit_func) (
	fz_fuim_alrt_ptr 			*fuim_alrt
	);

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

	fz_fuim_alrt_ptr_add_str



	Description
		Adds a string to a custom alert. The alert must first be created with fz_fuim_alrt_ptr_init.

	Parameters
		fuim_alrt  [Input]
			alert pointer
		flags  [Input]
			option flags of fz_fuim_alrt_str_opts_enum
		str  [Input]
			Text of string to appear in alert

	Returns
		error codes


	Availability	5.0.0.0


	See Also
		fz_fuim_alrt_ptr_init,fz_fuim_alrt_ptr_finit,fz_fuim_alrt_driver,fz_fuim_alrt_str_opts_enum

 ****************************************************************/
typedef fzrt_error_td  (*fz_fuim_alrt_ptr_add_str_func) (
	fz_fuim_alrt_ptr 		fuim_alrt,
	fzrt_int 					flags,
	char 					*str
	);

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

	fz_fuim_alrt_ptr_add_button



	Description
		Adds a button to a custom alert. The alert must first be created with fz_fuim_alrt_ptr_init.

	Parameters
		fuim_alrt  [Input]
			alert pointer
		button_id  [Input]
			identifier for button. Used to Identify which button is selected 
			by the user and returned by fz_fuim_alrt_driver
		button_opts  [Input]
			button options
		button_kind  [Input]
			kind of button
		str  [Input, Optional]
			Title of string to appear in button if button_kind == FZ_FUIM_ALRT_BUTTON_CUSTOM

	Returns
		error codes


	Availability	5.0.0.0


	See Also
		fz_fuim_alrt_ptr_init,fz_fuim_alrt_ptr_finit,fz_fuim_alrt_driver

 ****************************************************************/
typedef fzrt_int  (*fz_fuim_alrt_ptr_add_button_func) (
	fz_fuim_alrt_ptr 			fuim_alrt,
	fzrt_int 						button_id,
	fz_fuim_alrt_butn_opts_enum	button_opts,
	fz_fuim_alrt_button_enum 	button_kind,
	char 						*str
	);

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

	fz_fuim_alrt_driver



	Description
		Displays alert on screen. The alert is displayed on the screen in a movable modal window. 
		The alert stays on the screen until a button in the alert is selected. The return value is 
		the button_id of the selected button as specified in the fz_fuim_alrt_ptr_add_button function.

	Parameters
		fuim_alrt  [Input]
			alert pointer

	Returns
		identifier of button that was selected


	Availability	5.0.0.0


	See Also
		fz_fuim_alrt_ptr_init,fz_fuim_alrt_ptr_finit,fz_fuim_alrt_ptr_add_button,fz_fuim_alrt_ptr_add_str

 ****************************************************************/
typedef fzrt_int  (*fz_fuim_alrt_driver_func) (
	fz_fuim_alrt_ptr 			fuim_alrt
	);

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

	fz_fuim_alrt_std_confirm



	Description
		Standard confirm alert. Invokes the standard alert for posting a simple confirmation. This is useful for posting a 
		simple notification to the user or asking a simple OK/Cancel question from the user without 
		the need to setup your own alert pointer

	Parameters
		prmt_str  [Input]
			The prompt string that is to be posted to the user
		confirm_flags  [Input]
			fz_fuim_std_conf_enum

	Returns
		FZRT_STD_OK if OK button selected.  
		FZRT_STD_CANCEL if Cancel button selected


	Availability	5.0.0.0

 ****************************************************************/
typedef fzrt_int  (*fz_fuim_alrt_std_confirm_func) (
	char 					*prmt_str,
	fz_fuim_std_conf_enum 	confirm_flags
	);

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

	fz_fuim_alrt_std_name



	Description
		Standard name alert. Invokes the standard alert asking the user for a simple single text input. 
		This is useful for posting a simple notification to the user where the answer is a string.

	Parameters
		prmt_str  [Input]
			alert pointer
		name  [Result]
			alert pointer
		max_len  [Input]
			maximum of characters (bytes) that name can hold (including trailing '\0')

	Returns
		FZRT_STD_OK if OK button selected.  
		FZRT_STD_CANCEL if Cancel button selected


	Availability	5.0.0.0

 ****************************************************************/
typedef fzrt_int  (*fz_fuim_alrt_std_name_func) (
	char *prmt_str,
	char *name,
	fzrt_int max_len
	);

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

	fz_fuim_alrt_std_error



	Description
		Standard error alert. Invokes the standard alert for posting an error that was registered with the fzrt error manager

	Parameters
		err_id  [Input]
			the error
		where_id  [Input]
			ordinal identifier for where the error occurred
		where_str  [Input, Optional]
			string identifier for where the error occurred

	Returns
		TRUE if posted error, FALSE if not


	Availability	5.0.0.0


	See Also
		fzrt_error_set,fzrt_error_set_with_detail,fzrt_error_td,fzrt_error_severity_enum

 ****************************************************************/
typedef fzrt_boolean  (*fz_fuim_alrt_std_error_func) (
	fzrt_error_td 	err_id,
	fzrt_int 			where_id,
	char 			*where_str
	);


#ifdef __cplusplus
}
#endif

#endif
