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 progress bar.
GSErrCode	ACAPI_ProcessWindow_IncProcessValue (Int32 *incval=nullptr)
	Increases the value of the progress bar.
GSErrCode	ACAPI_ProcessWindow_IsProcessCanceled ()
	Checks for user breaks during long processes.
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.

Function Documentation

ACAPI_ProcessWindow_CloseProcessWindow()

GSErrCode ACAPI_ProcessWindow_CloseProcessWindow

(

)

Closes the process window.

Returns

• NoError - The function always returns NoError.

Remarks

This function is used to close 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

)

Increases the value of the progress bar.

Parameters

incval

[in] The value to add to the progress bar in the current process phase.

Returns

• NoError - The function has completed with success.
• APIERR_BADPARS - incval is nullptr

Remarks

This function is used to increase the progress bar value of the current phase in the process window. The increment should be passed in the incval parameter. Use the ACAPI_ProcessWindow_SetProcessValue function to set the process value to a given value, instead of increasing the current one.

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] Process string.
nPhase	[in] Number of phases.
processCntrolType	[in]

Returns

• NoError - The function has completed with success.
• APIERR_BADPARS - nPhase is nullptr

Remarks

This function is used to prepare the process window for a long operation. You can specify the name of the whole operation and the number of the phases of the process. Other process window related 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 for user breaks during long processes.

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 give visual feedback on processing 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] Show phase percentage. (optional)

Returns

• NoError - The function has completed with success.
• APIERR_BADPARS - maxval is nullptr

Remarks

This function is used to reinitialize the process window for the next process phase during a long operation. Set some description about the process phase in the subtitle parameter. The progress bar will be divided up 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 progress bar.

Parameters

newval

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

Returns

• NoError - The function has completed with success.
• APIERR_BADPARS - newval is nullptr

Remarks

This function is used to set the progress bar value of the current phase in the process window. Use the ACAPI_ProcessWindow_IncProcessValue function to increment the process value, instead of setting it to a given value.

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 ();
}