Utility Controller

interface ICwAPI3DUtilityController

Public Functions

virtual ICwAPI3DString *getLastError(int32_t *aErrorCode) = 0

Gets the last error.

Parameters:: aErrorCode – [out] [int32_t*] The error code.
Returns:: [ICwAPI3DString*] The error string.

virtual uint32_t get3DVersion() = 0

Gets the 3D version.

Returns:: [uint32_t] The 3D version.

virtual uint32_t get3DBuild() = 0

Gets the 3D build.

Returns:: [uint32_t] The 3D build.

virtual HWND get3DHWND() = 0

Gets the 3D HWND.

Returns:: [HWND] The 3D HWND.

virtual ICwAPI3DString *get3DFileName() = 0

Gets the 3D file name.

Returns:: [ICwAPI3DString*] The 3D file name.

virtual ICwAPI3DString *get3DFilePath() = 0

Gets the 3D file path.

Returns:: [ICwAPI3DString*] The 3D file path.

virtual void setProjectData(const character *aProjectDataId, const character *aData) = 0

Sets the project data.

Parameters:

aProjectDataId – [in] [const character*] The project data id.
aData – [in] [const character*] The data to set.

virtual ICwAPI3DString *getProjectData(const character *aProjectDataId) = 0

Gets the project data.

Parameters:: aProjectDataId – [in] [const character*] The project data id.
Returns:: [ICwAPI3DString*] The project data.

virtual void printError(const character *aMessage) = 0

Prints an error.

Parameters:: aMessage – [in] [const character*] The error message.

virtual ICwAPI3DString *getLanguage() = 0

Gets the 3D language.

Returns:: [ICwAPI3DString*] The language.

virtual void printMessage(const character *aMessage, uint32_t aRow = 1, uint32_t aColumn = 1) = 0

Prints a message.

Parameters:

aMessage – [in] [const character*] The message to print.
aRow – [in] [uint32_t] The row to print the message in.
aColumn – [in] [uint32_t] The column to print the message in.

virtual int32_t getUserInt(const character *aMessage) = 0

Prompts the user for an integer.

Parameters:: aMessage – [in] [const character*] The message to display.
Returns:: [int32_t] The user input integer.

virtual double getUserDouble(const character *aMessage) = 0

Prompts the user for a double.

Parameters:: aMessage – [in] [const character*] The message to display.
Returns:: [double] The user input double.

virtual bool getUserBool(const character *aMessage, bool aDefaultYes = true) = 0

Prompts the user for a boolean.

Parameters:

aMessage – [in] [const character*] The message to display.
aDefaultYes – [in] [bool] The default value, True by default.

Returns:

[bool] The user input boolean.

virtual ICwAPI3DString *getUserString(const character *aMessage) = 0

Prompts the user for a string.

Parameters:: aMessage – [in] [const character*] The message to display.
Returns:: [ICwAPI3DString*] The user input string.

virtual ICwAPI3DString *getProjectName() = 0

Gets the project name.

Returns:: [ICwAPI3DString*] The project name.

virtual void setProjectName(const character *aProjectName) = 0

Sets the project name.

Parameters:: aProjectName – [in] [const character*] The project name.

virtual ICwAPI3DString *getProjectNumber() = 0

Gets the project number.

Returns:: [ICwAPI3DString*] The project number.

virtual void setProjectNumber(const character *aProjectNumber) = 0

Sets the project number.

Parameters:: aProjectNumber – [in] [const character*] The project number.

virtual ICwAPI3DString *getProjectPart() = 0

Sets the project part.

Returns:: [ICwAPI3DString*] The project part.

virtual void setProjectPart(const character *aProjectPart) = 0

Sets the project part.

Parameters:: aProjectPart – [in] [const character*] The project part.

virtual ICwAPI3DString *getProjectArchitect() = 0

Gets the project architect.

Returns:: [ICwAPI3DString*] The project architect.

virtual void setProjectArchitect(const character *aProjectArchitect) = 0

Sets the project architect.

Parameters:: aProjectArchitect – [in] [const character*] The project architect.

virtual ICwAPI3DString *getProjectCustomer() = 0

Gets the project customer.

Returns:: [ICwAPI3DString*] The project customer.

virtual void setProjectCustomer(const character *aProjectCustomer) = 0

Sets the project customer.

Parameters:: aProjectCustomer – [in] [const character*] The project customer.

virtual ICwAPI3DString *getProjectDesigner() = 0

Gets the project designer.

Returns:: [ICwAPI3DString*] The project designer.

virtual void setProjectDesigner(const character *aProjectDesigner) = 0

Sets the project designer.

Parameters:: aProjectDesigner – [in] [const character*] The project designer.

virtual ICwAPI3DString *getProjectDeadline() = 0

Gets the project deadline.

Returns:: [ICwAPI3DString*] The project deadline.

virtual void setProjectDeadline(const character *aProjectDeadline) = 0

Sets the project deadline.

Parameters:: aProjectDeadline – [in] [const character*] The project deadline.

virtual ICwAPI3DString *getProjectUserAttribute(uint32_t aNumber) = 0

Gets the project user attribute.

Parameters:: aNumber – [in] [uint32_t] The project user attribute number.
Returns:: [ICwAPI3DString*] The project user attribute.

virtual void setProjectUserAttribute(uint32_t aNumber, const character *aUserAttribute) = 0

Sets the project user attribute.

Parameters:

aNumber – [in] [uint32_t] The project user attribute number.
aUserAttribute – [in] [const character*] The project user attribute.

virtual ICwAPI3DString *getProjectUserAttributeName(uint32_t aNumber) = 0

Gets the project user attribute name.

Parameters:: aNumber – [in] [uint32_t] The project user attribute number.
Returns:: [ICwAPI3DString*] The project user attribute name.

virtual void setProjectUserAttributeName(uint32_t aNumber, const character *aUserAttributeName) = 0

Sets the project user attribute name.

Parameters:

aNumber – [in] [uint32_t] The project user attribute number.
aUserAttributeName – [in] [const character*] The project user attribute name.

virtual double getProjectLatitude() = 0

Gets the project latitude.

Returns:: [double] The project latitude.

virtual double getProjectLongitude() = 0

Gets the project longitude.

Returns:: [double] The project longitude.

virtual void setProjectLatitude(double aLatitude) = 0

Sets the project latitude.

Parameters:: aLatitude – [in] [double] The project latitude.

virtual void setProjectLongitude(double aLongitude) = 0

Sets the project longitude.

Parameters:: aLongitude – [in] [double] The project longitude.

virtual ICwAPI3DString *getProjectAddress() = 0

Gets the project address.

Returns:: [ICwAPI3DString*] The project address.

virtual void setProjectAddress(const character *aAddress) = 0

Sets the project address.

Parameters:: aAddress – [in] [const character*] The project address.

virtual ICwAPI3DString *getProjectPostalCode() = 0

Gets the project postal code.

Returns:: [ICwAPI3DString*] The project postal code.

virtual void setProjectPostalCode(const character *aPostalCode) = 0

Sets the project postal code.

Parameters:: aPostalCode – [in] [const character*] The project postal code.

virtual ICwAPI3DString *getProjectCity() = 0

Gets the project city.

Returns:: [ICwAPI3DString*] The project city.

virtual void setProjectCity(const character *aCity) = 0

Sets the project city.

Parameters:: aCity – [in] [const character*] The project city.

virtual ICwAPI3DString *getProjectCountry() = 0

Gets the project country.

Returns:: [ICwAPI3DString*] The project country.

virtual void setProjectCountry(const character *aCountry) = 0

Sets the project country.

Parameters:: aCountry – [in] [const character*] The project country.

virtual ICwAPI3DString *get3DUserprofilPath() = 0

Gets the 3D userprofil path.

Returns:: [ICwAPI3DString*] The 3D userprofil path.

virtual ICwAPI3DString *getUserFileFromDialog(const character *aFilter) = 0

Gets a file with a dialog.

Parameters:: aFilter – [in] [const character*] The dialog file filter.
Returns:: [ICwAPI3DString*] The file path.

virtual ICwAPI3DString *getClientNumber() = 0

Gets the client number.

Returns:: [ICwAPI3DString*] The client number.

virtual vector3D getUserPoint() = 0

Gets a point from the user.

Returns:: [vector3D] The user point.

virtual void disableAutoDisplayRefresh() = 0: Disables automatic display refresh. This function prevents the display from updating automatically, which can significantly improve performance during operations that involve multiple changes or computations. The display will remain static until explicitly refreshed by the user.

virtual void enableAutoDisplayRefresh() = 0

Enables automatic display refresh. This function restores the default behavior where the display updates automatically after each operation. Use this function to resume normal display updates after previously disabling them with disable_auto_display_refresh(). It’s recommended to call this function after completing operations that required disabled display refreshing.

Example:

aFactory->getUtilityController()->disableAutoDisplayRefresh();  // Disable automatic display refresh

// Perform operations that require the display refresh to be off

ICwAPI3DElementIDList* yourListOfElements = aFactory->createElementIDList();  // Empty element list

aFactory->getUtilityController()->enableAutoDisplayRefresh();   // Re-enable automatic display refresh
aFactory->getElementController()->recreateElements(yourListOfElements);  // Recreate the elements

Note

If elements were created while display refresh was disabled, it’s important to recreate these elements after enabling the display refresh to ensure they are properly visualized in cadwork.

virtual ICwAPI3DString *createNewGUID() = 0

Creates a new GUID.

Returns:: [ICwAPI3DString*] The new GUID.

virtual void printToConsole(const character *aMessage) = 0

Prints a message to the console.

Parameters:: aMessage – [in] [const character*] The message.

virtual void exportScreenToImage(const character *aFilePath, uint32_t aFactor = 1) = 0

Exports the screen to an image.

Parameters:

aFilePath – [in] [const character*] The file path.
aFactor – [in] [uint32_t] The image factor.

virtual ICwAPI3DString *getNewUserFileFromDialog(const character *aFilter) = 0

Gets a new file with a dialog.

Parameters:: aFilter – [in] [const character*] The dialog file filter.
Returns:: [ICwAPI3DString*] The file path.

virtual uint32_t apiAutostart(const character *aAPIName, uint32_t aOption) = 0

Sets an API autostart option.

Example:

aFactory->getUtilityController()->apiAutostart(L"my_api", 1);   // Activer l'autostart
aFactory->getUtilityController()->apiAutostart(L"my_api", 0);  // Désactiver l'autostart
uint32_t isEnabled = aFactory->getUtilityController()->apiAutostart(L"my_api", static_cast<uint32_t>(-1));  // Lire l'état actuel

Parameters:

aAPIName – [in] [const character*] The name of the API to start.
aOption – [in] [uint32_t] The autostart option to use.
- -1: Checks if API is configured for autostart without making changes. Returns 1 if API is found, 0 if not, or -1 in case of errors.
- 1: Enables autostart for the specified API.
- 0: Disables autostart for the specified API. // TODO check for the uint value

Returns:

[uint32_t] The status of the operation.

virtual void enableAutostart(const character *aAPIName) = 0

Enables autostart for a given API.

Parameters:: aAPIName – [in] [const character*] The name of the API for which to enable autostart.

virtual void disableAutostart(const character *aAPIName) = 0

Disables autostart for a given API.

Parameters:: aAPIName – [in] [const character*] The name of the API for which to disable autostart.

virtual bool checkAutostart(const character *aAPIName) = 0

Checks if autostart is enabled for a given API.

Parameters:: aAPIName – [in] [const character*] The name of the API to check.
Returns:: [bool] True if autostart is enabled, false otherwise.

virtual void deleteProjectData(const character *aProjectDataId) = 0

Deletes the project data.

Parameters:: aProjectDataId – [in] [const character*] The project data id.

virtual bool runExternalProgram(const character *aName) = 0

Runs a 3D external program.

Parameters:: aName – [in] [const character*] The external program name.
Returns:: [bool] False if the program could not be run, true otherwise.

virtual void save3DFileSilently() = 0: Saves the 3D file silently.

virtual ICwAPI3DString *getProjectGUID() = 0

Gets the project GUID.

Returns:: [ICwAPI3DString*] The project GUID.

virtual ICwAPI3DString *getLicenceFirstPart() = 0

Gets the first part of the licence.

Returns:: [ICwAPI3DString*] The first part of the licence.

virtual ICwAPI3DString *getLicenceSecondPart() = 0

Gets the second part of the licence.

Returns:: [ICwAPI3DString*] The second part of the licence.

virtual void showProgressBar() = 0: Shows a ProgressBar in the CommandBar.

virtual void updateProgressBar(int32_t aValue) = 0

Updates the ProgressBar with a value.

Parameters:: aValue – [in] [int32_t] A value between 0 and 100.

virtual void hideProgressBar() = 0: Hides the ProgressBar.

virtual uint32_t getUserColor(uint32_t aInitialColor) = 0

Gets a color choosen by the user.

Parameters:: aInitialColor – [in] [uint32_t] The initial color.
Returns:: [uint32_t] The color number.

virtual ICwAPI3DString *get3DLinearUnits() = 0

Gets the current linear units.

Returns:: [ICwAPI3DString*] The current linear units.

virtual ICwAPI3DString *get3DLinearDisplayUnits() = 0

Gets the current display units.

Returns:: [ICwAPI3DString*] The current display units.

virtual ICwAPI3DString *get3DAngularUnits() = 0

Gets the current angular units.

Returns:: [ICwAPI3DString*] The current angular units.

virtual ICwAPI3DString *get3DAngularDisplayUnits() = 0

Gets the current angular display units.

Returns:: [ICwAPI3DString*] The current angular display units.

virtual ICwAPI3DString *get3DBuildDate() = 0

Gets the current build date.

Returns:: [ICwAPI3DString*] The current build date.

virtual double getProjectElevation() = 0

Gets the project elevation.

Returns:: [double] The project elevation.

virtual void setProjectElevation(double aElevation) = 0

Sets the project elevation.

Parameters:: aElevation – [in] [double] The project elevation.

virtual void clearErrors() = 0: Clears all errors.

virtual void pushCheckAndQueryData() = 0: Pushes the current state of check and query data onto a stack.

virtual void popCheckAndQueryData() = 0: Pops the most recent state of check and query data from the stack.

virtual void changeCheckAndQueryDataToNoQueries() = 0: Changes the current state of check and query data to no queries.

virtual void changeCheckAndQueryDataToQueries() = 0: Changes the current state of check and query data to allow queries.

virtual bool isDirectInfoEnabled() = 0

Checks if Direct Info is enabled.

Returns:: [bool] True if Direct Info is enabled, false otherwise.

virtual void enableDirectInfo() = 0: Enables Direct Info.

virtual void disableDirectInfo() = 0: Disables Direct Info.

virtual void loadAttributeDisplaySettings(const character *aFilePath) = 0

Loads attribute display settings from a file.

Parameters:: aFilePath – [in] [const character*] The path to the file containing the settings.

virtual ICwAPI3DString *getProjectDescription() = 0

Gets the project description.

Returns:: [ICwAPI3DString*] A string containing the project description.

virtual void setProjectDescription(const character *aDescription) = 0

Sets the project description.

Parameters:: aDescription – [in] [const character*] The new description for the project.

virtual void startProjectDataDialog() = 0: Starts the project data dialog.

virtual void initLxSDK() = 0: Initializes the LxSDK.

virtual void loadElementAttributeDisplaySettings(const character *aFilePath, ICwAPI3DElementIDList *aElementIdList) = 0

Loads element attribute display settings from a file.

Parameters:

aFilePath – [in] [const character*] The path to the file containing the settings.
aElementIdList – [in] [ICwAPI3DElementIDList*] The element list for which to load the settings.

virtual double getGlobalXOffset() = 0

Gets the global X offset.

Returns:: [double] The global X offset.

virtual void setGlobalXOffset(double aOffset) = 0

Sets the global X offset.

Parameters:: aOffset – [in] [double] The new global X offset.

virtual double getGlobalYOffset() = 0

Gets the global Y offset.

Returns:: [double] The global Y offset.

virtual void setGlobalYOffset(double aOffset) = 0

Sets the global Y offset.

Parameters:: aOffset – [in] [double] The new global Y offset.

virtual double getGlobalZOffset() = 0

Gets the global Z offset.

Returns:: [double] The global Z offset.

virtual void setGlobalZOffset(double aOffset) = 0

Sets the global Z offset.

Parameters:: aOffset – [in] [double] The new global Z offset.

virtual void showNorthArrow() = 0: Shows the north arrow on the 3D view.

virtual void hideNorthArrow() = 0: Hides the north arrow on the 3D view.

virtual bool isNorthArrowVisible() = 0

Checks if the north arrow is visible on the 3D view.

Returns:: [bool] True if the north arrow is visible, false otherwise.

virtual double getNorthAngle() = 0

Gets the angle of the north direction.

Returns:: [double] The angle of the north direction in degrees.

virtual void setNorthAngle(double aNorthAngle) = 0

Sets the angle of the north direction.

Parameters:: aNorthAngle – [in] [double] The angle of the north direction in degrees.

virtual ICwAPI3DString *getUserFileFromDialogInPath(const character *aFilter, const character *aPath) = 0

Gets a user file from a dialog in a specified path.

Parameters:

aFilter – [in] [const character*] The filter for the dialog.
aPath – [in] [const character*] The path in which to get the user file.

Returns:

[ICwAPI3DString*] A string containing the user file.

virtual ICwAPI3DString *getNewUserFileFromDialogInPath(const character *aFilter, const character *aPath) = 0

Gets a new user file from a dialog in a specified path.

Parameters:

aFilter – [in] [const character*] The filter for the dialog.
aPath – [in] [const character*] The path in which to get the new user file.

Returns:

[ICwAPI3DString*] A string containing the new user file.

virtual double getMillimetreFromImperialString(const character *aValue) = 0

Converts an imperial string to millimetres.

Parameters:: aValue – [in] [const character*] The imperial string to convert.
Returns:: [double] The value in millimetres.

virtual ICwAPI3DString *getImperialStringFromMillimetre(double aValue) = 0

Converts a value in millimetres to an imperial string.

Parameters:: aValue – [in] [double] The value in millimetres to convert.
Returns:: [ICwAPI3DString*] The value as an imperial string.

virtual void enableUpdateVariant() = 0: Enables the update variant.

virtual void disableUpdateVariant() = 0: Disables the update variant.

virtual ICwAPI3DString *getPluginPath() = 0

Gets the plugin path.

Returns:: [ICwAPI3DString*] A string containing the plugin path.

virtual ICwAPI3DVertexList *getUserPoints() = 0

Gets user points.

Returns:: [ICwAPI3DVertexList*] A list of user points.

virtual ICwAPI3DVertexList *getUserPointsWithCount(uint64_t aCount) = 0

Gets user points with a specified count.

Parameters:: aCount – [in] [uint64_t] The number of user points to get.
Returns:: [ICwAPI3DVertexList*] A list of user points.

virtual ICwAPI3DString *getUserCatalogPath() = 0

Gets the user catalog path.

Returns:: [ICwAPI3DString*] A string containing the user catalog path.

virtual ICwAPI3DString *getUserPathFromDialog() = 0

Gets the user path from a dialog.

Returns:: [ICwAPI3DString*] A string containing the user path.

virtual ICwAPI3DString *getUserPathFromDialogInPath(const character *aPath) = 0

Gets the user path from a dialog in a specified path.

Parameters:: aPath – [in] [const character*] The path in which to get the user path.
Returns:: [ICwAPI3DString*] A string containing the user path.

virtual void executeShortcut(shortcutKeyModifier aShortcutKeyModifier, shortcutKey aShortcutKey) = 0

Executes a shortcut.

Parameters:

aShortcutKeyModifier – [in] [shortcutKeyModifier] The modifier key for the shortcut.
aShortcutKey – [in] [shortcutKey] The key for the shortcut.

virtual void closeCadworkDocumentSaved() = 0: close cadwork saved.

virtual void closeCadworkDocumentUnsaved() = 0: close cadwork unsaved.

virtual bool getUseOfGlobalCoordinates() = 0

Gets the use of global coordinates.

Returns:: [bool] True if global coordinates are used, false otherwise.

virtual void setUseOfGlobalCoordinates(bool aUseOfGlobalCoordinates) = 0

Sets the use of global coordinates.

Parameters:: aUseOfGlobalCoordinates – [in] [bool] True to use global coordinates, false otherwise.

virtual vector3D getGlobalOrigin() = 0

Gets the global origin.

Returns:: [vector3D] The global origin.

virtual void setGlobalOrigin(CwAPI3D::vector3D aGlobalOrigin) = 0

Sets the global origin.

Parameters:: aGlobalOrigin – [in] [vector3D] The global origin.

virtual ICwAPI3DString * createSnapshot (const character *aFormat=L"PNG", int aQuality=-1, bool aWhiteBackground=true)=0

Get snapshot from screen.

Parameters:

aFormat – [in] [const character*] File format PNG, JPEG.
aQuality – [in] [int] The quality factor must be in the range 0 to 100 or -1.
- 0 to obtain small compressed files.
- 100 for large uncompressed files.
- -1 (the default) to use the default settings.
aWhiteBackground – [in] [bool] True to use a white background, false for a transparent background.

Returns:

[ICwAPI3DString*] The snapshot as a string.

virtual bool runExternalProgramFromCustomDirectory(const character *aFilePath) = 0

Runs a 3D external program from a custom directory.

Parameters:: aFilePath – [in] [const character*] The external program file path.
Returns:: [bool] False if error, true otherwise.

virtual windowGeometry get3dMainWindowGeometry() = 0

Get the geometry of 3d main window.

Returns:: [windowGeometry] The geometry of the 3D main window.

virtual ICwAPI3DStringList *getProjectDataKeys() = 0

Gets all keys for project data.

Returns:: [ICwAPI3DStringList*] The list of project data keys.

virtual int32_t getUserIntWithDefaultValue(const character *aMessage, int32_t aDefaultValue) = 0

Prompts the user for an integer with a default value.

Parameters:

aMessage – [in] [const character*] The message to display.
aDefaultValue – [in] [int32_t] The default value.

Returns:

[int32_t] The user integer.

virtual double getUserDoubleWithDefaultValue(const character *aMessage, double aDefaultValue) = 0

Prompts the user for a double with a default value.

Parameters:

aMessage – [in] [const character*] The message to display.
aDefaultValue – [in] [double] The default value.

Returns:

[double] The user double.

virtual ICwAPI3DString *getUserStringWithDefaultValue(const character *aMessage, const character *aDefaultValue) = 0

Prompts the user for a string with a default value.

Parameters:

aMessage – [in] [const character*] The message to display.
aDefaultValue – [in] [const character*] The default value.

Returns:

[ICwAPI3DString*] The user string.

virtual ICwAPI3DString *get3DVersionName() = 0

Gets the 3D version name.

Returns:: [ICwAPI3DString*] The 3D version name.

virtual void redirectPythonOutputToLogger() = 0: Redirects output from Python’s print function to the cadwork logger. This function is used to redirect the output of the Python interpreter to the logger. This is useful for debugging and logging purposes.