Process Windows

Functions related to the Process Control (Process Window). More...

Enumerations
enum	API_ProcessControlTypeID { API_MenuCommandEnabled , API_MenuCommandDisabled }
	Process control types. More...

Functions
GSErrCode	ACAPI_ProcessWindow_GetProcessControl (GS::ProcessControl **processControl)
	Returns the actual process control from Archicad.
GSErrCode	ACAPI_ProcessWindow_SetInnerProcessControl (GS::ProcessControl *processControl=nullptr)
	Sets the given process control to Archicad.
GSErrCode	ACAPI_ProcessWindow_InitProcessWindow (const GS::UniString *title=nullptr, Int32 *nPhase=nullptr, API_ProcessControlTypeID *processCntrolType=nullptr)
	Opens the process window.
GSErrCode	ACAPI_ProcessWindow_CloseProcessWindow ()
	Closes the process window.
GSErrCode	ACAPI_ProcessWindow_SetNextProcessPhase (const GS::UniString *subtitle, Int32 *maxval, bool *showPercent=nullptr)
	Starts the next process phase in the process window.
GSErrCode	ACAPI_ProcessWindow_SetProcessValue (Int32 *newval)
	Sets the value of the process bar in the process window.
GSErrCode	ACAPI_ProcessWindow_IncProcessValue (Int32 *incval=nullptr)
	Increments the value of the process bar in the process window.
GSErrCode	ACAPI_ProcessWindow_IsProcessCanceled ()
	Checks if the process was canceled by the user.
GSErrCode	ACAPI_ProcessWindow_SetProcessOnOffSwitch (bool *switchOff)
	Turns the process window on/off.
GSErrCode	ACAPI_ProcessWindow_GetProcessOnOffSwitch (bool *param)
	Returns whether the process window will appear.

Detailed Description

Functions related to the Process Control (Process Window).

Enumeration Type Documentation

API_ProcessControlTypeID

enum API_ProcessControlTypeID

Process control types.

Remarks

Used in ACAPI_ProcessWindow_InitProcessWindow.

Enumerator
API_MenuCommandEnabled	Enabled
API_MenuCommandDisabled	Disabled

Function Documentation

ACAPI_ProcessWindow_CloseProcessWindow()

GSErrCode ACAPI_ProcessWindow_CloseProcessWindow

(

)

Closes the process window.

Returns

• NoError - The function always returns NoError.

Remarks

This function closes the process window opened with ACAPI_ProcessWindow_InitProcessWindow.

Example

GSErrCode       err;
API_LibPart     libPart {};
GS::UniString   title ("Listing the library");
GS::UniString   subtitle ("working...");
Int32           nPhase;
Int32           i, nLib;
char            buffer [256];
 
err = ACAPI_LibraryPart_GetNum (&nLib);
if (nLib > 0) {
    nPhase = 1;
 
    ACAPI_ProcessWindow_InitProcessWindow (&title, &nPhase);
    ACAPI_ProcessWindow_SetNextProcessPhase (&subtitle, &nLib);
 
    for (i = 1; i <= nLib; i++) {
        libPart.index = i;
        err = ACAPI_LibraryPart_Get (&libPart);
        if (!err) {
            sprintf (buffer, "[%2d] \"%s\"", i, (const char *) GS::UniString (libPart.docu_UName).ToCStr ());
            ACAPI_WriteReport (buffer, false);
        }
 
        ACAPI_ProcessWindow_SetProcessValue (&i);
        if (ACAPI_ProcessWindow_IsProcessCanceled ())
            break;
    }
 
    ACAPI_ProcessWindow_CloseProcessWindow ();
}

ACAPI_ProcessWindow_GetProcessControl()

GSErrCode ACAPI_ProcessWindow_GetProcessControl

(

GS::ProcessControl **

processControl

)

Returns the actual process control from Archicad.

Parameters

processControl

[out]

Returns

• NoError - The function has completed with success.

ACAPI_ProcessWindow_GetProcessOnOffSwitch()

GSErrCode ACAPI_ProcessWindow_GetProcessOnOffSwitch

(

bool *

param

)

Returns whether the process window will appear.

Parameters

param

[out] returns the current state.

Returns

• NoError - The function has completed with success.

ACAPI_ProcessWindow_IncProcessValue()

GSErrCode ACAPI_ProcessWindow_IncProcessValue

(

Int32 *

incval = nullptr

)

Increments the value of the process bar in the process window.

Parameters

incval

[in] The value to increment the process bar by in the current process phase.

Returns

• NoError - The function completed successfully.
• APIERR_BADPARS - increment is nullptr.

Remarks

This function increments the value of the process bar in the process window by the specified increment. The value is added to the current value of the process bar.

Example

GSErrCode       err;
API_LibPart     libPart {};
GS::UniString   title ("Listing the library");
GS::UniString   subtitle ("working...");
Int32           nPhase;
Int32           i, nLib;
char            buffer [256];
 
err = ACAPI_LibraryPart_GetNum (&nLib);
if (nLib > 0) {
    nPhase = 1;
 
    ACAPI_ProcessWindow_InitProcessWindow (&title, &nPhase);
    ACAPI_ProcessWindow_SetNextProcessPhase (&subtitle, &nLib);
 
    for (i = 1; i <= nLib; i++) {
        libPart.index = i;
        err = ACAPI_LibraryPart_Get (&libPart);
        if (!err) {
            sprintf (buffer, "[%2d] \"%s\"", i, (const char *) GS::UniString (libPart.docu_UName).ToCStr ());
            ACAPI_WriteReport (buffer, false);
        }
 
        ACAPI_ProcessWindow_SetProcessValue (&i);
        if (ACAPI_ProcessWindow_IsProcessCanceled ())
            break;
    }
 
    ACAPI_ProcessWindow_CloseProcessWindow ();
}

ACAPI_ProcessWindow_InitProcessWindow()

GSErrCode ACAPI_ProcessWindow_InitProcessWindow	(	const GS::UniString *	title = nullptr,
		Int32 *	nPhase = nullptr,
		API_ProcessControlTypeID *	processCntrolType = nullptr )

Opens the process window.

Parameters

title	[in] Title of the process.
nPhase	[in] Number of phases.
processCntrolType	[in] Type of process control.

Returns

• NoError - The function completed successfully.
• APIERR_BADPARS - nPhase is nullptr.

Remarks

This function prepares the process window for a long operation. You can specify the name of the entire operation and the number of phases in the process. Other related process window functions are:

• ACAPI_ProcessWindow_SetNextProcessPhase
• ACAPI_ProcessWindow_SetProcessValue
• ACAPI_ProcessWindow_IncProcessValue
• ACAPI_ProcessWindow_IsProcessCanceled
• ACAPI_ProcessWindow_CloseProcessWindow

Example

GSErrCode       err;
API_LibPart     libPart {};
GS::UniString   title ("Listing the library");
GS::UniString   subtitle ("working...");
Int32           nPhase;
Int32           i, nLib;
char            buffer [256];
 
err = ACAPI_LibraryPart_GetNum (&nLib);
if (nLib > 0) {
    nPhase = 1;
 
    ACAPI_ProcessWindow_InitProcessWindow (&title, &nPhase);
    ACAPI_ProcessWindow_SetNextProcessPhase (&subtitle, &nLib);
 
    for (i = 1; i <= nLib; i++) {
        libPart.index = i;
        err = ACAPI_LibraryPart_Get (&libPart);
        if (!err) {
            sprintf (buffer, "[%2d] \"%s\"", i, (const char *) GS::UniString (libPart.docu_UName).ToCStr ());
            ACAPI_WriteReport (buffer, false);
        }
 
        ACAPI_ProcessWindow_SetProcessValue (&i);
        if (ACAPI_ProcessWindow_IsProcessCanceled ())
            break;
    }
 
    ACAPI_ProcessWindow_CloseProcessWindow ();
}

ACAPI_ProcessWindow_IsProcessCanceled()

GSErrCode ACAPI_ProcessWindow_IsProcessCanceled

(

)

Checks if the process was canceled by the user.

Returns

• NoError - The function has completed with success.
• APIERR_CANCEL - The current process was canceled.

Remarks

This function is used to check whether the user has canceled a long process (by clicking on the Cancel button of the process window, or by pressing the appropriate keys on the keyboard). It also gives visual feedback by changing the cursor shape.

Example

GSErrCode       err;
API_LibPart     libPart {};
GS::UniString   title ("Listing the library");
GS::UniString   subtitle ("working...");
Int32           nPhase;
Int32           i, nLib;
char            buffer [256];
 
err = ACAPI_LibraryPart_GetNum (&nLib);
if (nLib > 0) {
    nPhase = 1;
 
    ACAPI_ProcessWindow_InitProcessWindow (&title, &nPhase);
    ACAPI_ProcessWindow_SetNextProcessPhase (&subtitle, &nLib);
 
    for (i = 1; i <= nLib; i++) {
        libPart.index = i;
        err = ACAPI_LibraryPart_Get (&libPart);
        if (!err) {
            sprintf (buffer, "[%2d] \"%s\"", i, (const char *) GS::UniString (libPart.docu_UName).ToCStr ());
            ACAPI_WriteReport (buffer, false);
        }
 
        ACAPI_ProcessWindow_SetProcessValue (&i);
        if (ACAPI_ProcessWindow_IsProcessCanceled ())
            break;
    }
 
    ACAPI_ProcessWindow_CloseProcessWindow ();
}

ACAPI_ProcessWindow_SetInnerProcessControl()

GSErrCode ACAPI_ProcessWindow_SetInnerProcessControl

(

GS::ProcessControl *

processControl = nullptr

)

Sets the given process control to Archicad.

Parameters

processControl

[in] Can be nullptr.

Returns

• NoError - The function has completed with success.

ACAPI_ProcessWindow_SetNextProcessPhase()

GSErrCode ACAPI_ProcessWindow_SetNextProcessPhase	(	const GS::UniString *	subtitle,
		Int32 *	maxval,
		bool *	showPercent = nullptr )

Starts the next process phase in the process window.

Parameters

subtitle	[in] Description of the process phase.
maxval	[in] Maximum value of the progress bar.
showPercent	[in] Whether to show the phase percentage (optional).

Returns

• NoError - The function completed successfully.
• APIERR_BADPARS - maxval is nullptr.

Remarks

This function reinitializes the process window for the next process phase during a long operation. Set a description for the process phase in the subtitle parameter. The progress bar will be divided according to the value of the maxval parameter.

Example

GSErrCode       err;
API_LibPart     libPart {};
GS::UniString   title ("Listing the library");
GS::UniString   subtitle ("working...");
Int32           nPhase;
Int32           i, nLib;
char            buffer [256];
 
err = ACAPI_LibraryPart_GetNum (&nLib);
if (nLib > 0) {
    nPhase = 1;
 
    ACAPI_ProcessWindow_InitProcessWindow (&title, &nPhase);
    ACAPI_ProcessWindow_SetNextProcessPhase (&subtitle, &nLib);
 
    for (i = 1; i <= nLib; i++) {
        libPart.index = i;
        err = ACAPI_LibraryPart_Get (&libPart);
        if (!err) {
            sprintf (buffer, "[%2d] \"%s\"", i, (const char *) GS::UniString (libPart.docu_UName).ToCStr ());
            ACAPI_WriteReport (buffer, false);
        }
 
        ACAPI_ProcessWindow_SetProcessValue (&i);
        if (ACAPI_ProcessWindow_IsProcessCanceled ())
            break;
    }
 
    ACAPI_ProcessWindow_CloseProcessWindow ();
}

ACAPI_ProcessWindow_SetProcessOnOffSwitch()

GSErrCode ACAPI_ProcessWindow_SetProcessOnOffSwitch

(

bool *

switchOff

)

Turns the process window on/off.

Parameters

switchOff

[in] sets the current state.

Returns

• NoError - The function has completed with success.

ACAPI_ProcessWindow_SetProcessValue()

GSErrCode ACAPI_ProcessWindow_SetProcessValue

(

Int32 *

newval

)

Sets the value of the process bar in the process window.

Parameters

newval

[in] The new value of the process bar in the current process phase.

Returns

• NoError - The function completed successfully.
• APIERR_BADPARS - value is nullptr.

Remarks

This function sets the value of the process bar in the process window. The value parameter should be between 0 and the maximum value set by ACAPI_ProcessWindow_SetNextProcessPhase.

Example

GSErrCode       err;
API_LibPart     libPart {};
GS::UniString   title ("Listing the library");
GS::UniString   subtitle ("working...");
Int32           nPhase;
Int32           i, nLib;
char            buffer [256];
 
err = ACAPI_LibraryPart_GetNum (&nLib);
if (nLib > 0) {
    nPhase = 1;
 
    ACAPI_ProcessWindow_InitProcessWindow (&title, &nPhase);
    ACAPI_ProcessWindow_SetNextProcessPhase (&subtitle, &nLib);
 
    for (i = 1; i <= nLib; i++) {
        libPart.index = i;
        err = ACAPI_LibraryPart_Get (&libPart);
        if (!err) {
            sprintf (buffer, "[%2d] \"%s\"", i, (const char *) GS::UniString (libPart.docu_UName).ToCStr ());
            ACAPI_WriteReport (buffer, false);
        }
 
        ACAPI_ProcessWindow_SetProcessValue (&i);
        if (ACAPI_ProcessWindow_IsProcessCanceled ())
            break;
    }
 
    ACAPI_ProcessWindow_CloseProcessWindow ();
}