Utility Controller

Application environment and user interaction.

The bridge between scripts and the surrounding cadwork application: filesystem and version information, language and locale, user-facing dialogs and prompts, status messages and progress indicators, GUID generation, project metadata, and access to the host window itself. General-purpose helpers that don't belong to any specific modelling domain.

api_autostart(api_name: str, option: int) -> int

Sets an API autostart option.

Parameters:

Name	Type	Description	Default
api_name	str	The name of the API be managed.	required
option	int	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.	required

Note: This function reads and updates alias and module configuration files to manage the autostart state of the API.

Examples:

>>> api_autostart("my_api", 1)  # Enable autostart
>>> api_autostart("my_api", 0)  # Disable autostart
>>> api_autostart("my_api", -1)  # Check current autostart state

Returns:

Type	Description
int	The value of option if the operation is successful, or -1 in case of errors.

change_check_and_query_data_to_no_queries() -> None

Changes the current state of check and query data to no queries.

change_check_and_query_data_to_queries() -> None

Changes the current state of check and query data to allow queries.

check_autostart(api_name: str) -> bool

Checks if autostart is enabled for a given API.

Parameters:

Name	Type	Description	Default
api_name	str	The name of the API to check.	required

Returns:

Type	Description
bool	True if autostart is enabled, false otherwise.

clear_errors() -> None

Clears all errors.

close_cadwork_document_saved() -> None

close cadwork saved.

close_cadwork_document_unsaved() -> None

close cadwork unsaved.

create_new_guid() -> str

Creates a new GUID.

Returns:

Type	Description
str	The new GUID.

create_snapshot() -> str

Get snapshot from screen.

Returns:

Type	Description
str	The snapshot as a string.

delete_project_data(element_id: str) -> None

Deletes the project data.

Parameters:

Name	Type	Description	Default
element_id	str	The project data id.	required

disable_auto_display_refresh() -> None

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.

disable_autostart(api_name: str) -> None

Disables autostart for a given API.

Parameters:

Name	Type	Description	Default
api_name	str	The name of the API for which to disable autostart.	required

disable_direct_info() -> None

Disables Direct Info.

disable_update_variant() -> None

Disables the update variant.

enable_auto_display_refresh() -> None

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.

Examples:

>>> import cadwork
>>> import utility_controller as uc
>>> import element_controller as ec
>>> uc.disable_auto_display_refresh()
>>> # Perform operations that require disabled display refresh
>>> your_list_of_elements: list[int] = []
>>> uc.enable_auto_display_refresh()
>>> ec.recreate_elements(your_list_of_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.

enable_autostart(api_name: str) -> None

Enables autostart for a given API.

Parameters:

Name	Type	Description	Default
api_name	str	The name of the API for which to enable autostart.	required

enable_direct_info() -> None

Enables Direct Info.

enable_update_variant() -> None

Enables the update variant.

execute_shortcut(shortcut_key_modifier: shortcut_key_modifier, shortcut_key: shortcut_key) -> None

Executes a shortcut.

Parameters:

Name	Type	Description	Default
shortcut_key_modifier	shortcut_key_modifier	The modifier key for the shortcut.	required
shortcut_key	shortcut_key	The key for the shortcut.	required

export_screen_to_image(file_path: str, factor: int) -> None

Exports the screen to an image.

Parameters:

Name	Type	Description	Default
file_path	str	The file path.	required
factor	int	The image factor.	required

get_3d_angular_display_units() -> str

Gets the current angular display units.

Returns:

Type	Description
str	The current angular display units.

get_3d_angular_units() -> str

Gets the current angular units.

Returns:

Type	Description
str	The current angular units.

get_3d_build() -> int

Gets the 3D build.

Returns:

Type	Description
int	The 3D build.

get_3d_build_date() -> str

Gets the current build date.

Returns:

Type	Description
str	The current build date.

get_3d_file_name() -> str

Gets the 3D file name.

Returns:

Type	Description
str	The 3D file name.

get_3d_file_path() -> str

Gets the 3D file path.

Returns:

Type	Description
str	The 3D file path.

get_3d_gui_upper_left_screen_coordinates() -> tuple[int, int]

Get the coordinates of the upper left corner of the 3D GUI.

Returns:

Type	Description
tuple[int, int]	The coordinates of the upper left corner of the 3D GUI.

get_3d_hwnd() -> int

Gets the 3D HWND.

Returns:

Type	Description
int	The 3D HWND.

get_3d_linear_display_units() -> str

Gets the current display units.

Returns:

Type	Description
str	The current display units.

get_3d_linear_units() -> str

Gets the current linear units.

Returns:

Type	Description
str	The current linear units.

get_3d_main_window_geometry() -> window_geometry

Get the geometry of 3d main window.

Returns:

Type	Description
window_geometry	The geometry of the 3D main window.

get_3d_userprofil_path() -> str

Gets the 3D userprofil path.

Returns:

Type	Description
str	The 3D userprofil path.

get_3d_version() -> int

Gets the 3D version.

Returns:

Type	Description
int	The 3D version.

get_3d_version_name() -> str

Gets the 3D version name.

Returns:

Type	Description
str	The 3D version name.

get_client_number() -> str

Gets the client number.

Returns:

Type	Description
str	The client number.

get_global_origin() -> point_3d

Gets the global origin.

Returns:

Type	Description
point_3d	The global origin.

get_global_x_offset() -> float

Gets the global X offset.

Returns:

Type	Description
float	The global X offset.

get_global_y_offset() -> float

Gets the global Y offset.

Returns:

Type	Description
float	The global Y offset.

get_global_z_offset() -> float

Gets the global Z offset.

Returns:

Type	Description
float	The global Z offset.

get_imperial_string_from_millimetre(value: float) -> str

Converts a value in millimetres to an imperial string.

Parameters:

Name	Type	Description	Default
value	float	The value in millimetres to convert.	required

Returns:

Type	Description
str	The value as an imperial string.

get_language() -> str

Gets the 3D language.

Returns:

Type	Description
str	The language.

get_licence_first_part() -> str

Gets the first part of the licence.

Returns:

Type	Description
str	The first part of the licence.

get_licence_second_part() -> str

Gets the second part of the licence.

Returns:

Type	Description
str	The second part of the licence.

get_millimetre_from_imperial_string(value: str) -> float

Converts an imperial string to millimetres.

Parameters:

Name	Type	Description	Default
value	str	The imperial string to convert.	required

Returns:

Type	Description
float	The value in millimetres.

get_new_user_file_from_dialog(name_filter: str) -> str

Gets a new file with a dialog.

Parameters:

Name	Type	Description	Default
name_filter	str	The dialog file filter.	required

Returns:

Type	Description
str	The file path.

get_new_user_file_from_dialog_in_path(name_filter: str, path: str) -> str

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

Parameters:

Name	Type	Description	Default
name_filter	str	The filter for the dialog.	required
path	str	The path in which to get the new user file.	required

Returns:

Type	Description
str	A string containing the new user file.

get_north_angle() -> float

Gets the angle of the north direction.

Returns:

Type	Description
float	The angle of the north direction in degrees.

get_plugin_path() -> str

Gets the plugin path.

Returns:

Type	Description
str	A string containing the plugin path.

get_project_address() -> str

Gets the project address.

Returns:

Type	Description
str	The project address.

get_project_architect() -> str

Gets the project architect.

Returns:

Type	Description
str	The project architect.

get_project_city() -> str

Gets the project city.

Returns:

Type	Description
str	The project city.

get_project_country() -> str

Gets the project country.

Returns:

Type	Description
str	The project country.

get_project_customer() -> str

Gets the project customer.

Returns:

Type	Description
str	The project customer.

get_project_data(element_id: str) -> str

Gets the project data.

Parameters:

Name	Type	Description	Default
element_id	str	The project data id.	required

Returns:

Type	Description
str	The project data.

get_project_data_keys() -> list[str]

Gets all keys for project data.

Returns:

Type	Description
list[str]	The list of project data keys.

get_project_deadline() -> str

Gets the project deadline.

Returns:

Type	Description
str	The project deadline.

get_project_description() -> str

Gets the project description.

Returns:

Type	Description
str	A string containing the project description.

get_project_designer() -> str

Gets the project designer.

Returns:

Type	Description
str	The project designer.

get_project_elevation() -> float

Gets the project elevation.

Returns:

Type	Description
float	The project elevation.

get_project_guid() -> str

Gets the project GUID.

Returns:

Type	Description
str	The project GUID.

get_project_latitude() -> float

Gets the project latitude.

Returns:

Type	Description
float	The project latitude.

get_project_longitude() -> float

Gets the project longitude.

Returns:

Type	Description
float	The project longitude.

get_project_name() -> str

Gets the project name.

Returns:

Type	Description
str	The project name.

get_project_number() -> str

Gets the project number.

Returns:

Type	Description
str	The project number.

get_project_part() -> str

Gets the project part.

Returns:

Type	Description
str	The project part.

get_project_postal_code() -> str

Gets the project postal code.

Returns:

Type	Description
str	The project postal code.

get_project_user_attribute(number: int) -> str

Gets the project user attribute.

Parameters:

Name	Type	Description	Default
number	int	The project user attribute number.	required

Returns:

Type	Description
str	The project user attribute.

get_project_user_attribute_name(number: int) -> str

Gets the project user attribute name.

Parameters:

Name	Type	Description	Default
number	int	The project user attribute number.	required

Returns:

Type	Description
str	The project user attribute name.

get_use_of_global_coordinates() -> bool

Gets the use of global coordinates.

Returns:

Type	Description
bool	True if global coordinates are used, false otherwise.

get_user_bool(message: str, default_yes: bool) -> bool

Prompts the user for a boolean.

Parameters:

Name	Type	Description	Default
message	str	The message to display.	required
default_yes	bool	The default value, True by default.	required

Returns:

Type	Description
bool	The user input boolean.

get_user_catalog_path() -> str

Gets the user catalog path.

Returns:

Type	Description
str	A string containing the user catalog path.

get_user_color(initial_color: int) -> int

Gets a color choosen by the user.

Parameters:

Name	Type	Description	Default
initial_color	int	The initial color.	required

Returns:

Type	Description
int	The color number.

get_user_double(message: str) -> float

Prompts the user for a double.

Parameters:

Name	Type	Description	Default
message	str	The message to display.	required

Returns:

Type	Description
float	The user input double.

get_user_double_with_default_value(message: str, default_value: float) -> float

Prompts the user for a double with a default value.

Parameters:

Name	Type	Description	Default
message	str	The message to display.	required
default_value	float	The default value.	required

Returns:

Type	Description
float	The user double.

get_user_file_from_dialog(name_filter: str) -> str

Gets a file with a dialog.

Parameters:

Name	Type	Description	Default
name_filter	str	The dialog file filter.	required

Returns:

Type	Description
str	The file path.

get_user_file_from_dialog_in_path(name_filter: str, path: str) -> str

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

Parameters:

Name	Type	Description	Default
name_filter	str	The filter for the dialog.	required
path	str	The path in which to get the user file.	required

Returns:

Type	Description
str	A string containing the user file.

get_user_int(message: str) -> int

Prompts the user for an integer.

Parameters:

Name	Type	Description	Default
message	str	The message to display.	required

Returns:

Type	Description
int	The user input integer.

get_user_int_with_default_value(message: str, default_value: int) -> int

Prompts the user for an integer with a default value.

Parameters:

Name	Type	Description	Default
message	str	The message to display.	required
default_value	int	The default value.	required

Returns:

Type	Description
int	The user integer.

get_user_path_from_dialog() -> str

Gets the user path from a dialog.

Returns:

Type	Description
str	A string containing the user path.

get_user_path_from_dialog_in_path(path: str) -> str

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

Parameters:

Name	Type	Description	Default
path	str	The path in which to get the user path.	required

Returns:

Type	Description
str	A string containing the user path.

get_user_point() -> point_3d

Gets a point from the user.

Returns:

Type	Description
point_3d	The user point.

get_user_points() -> list[point_3d]

Gets user points.

Returns:

Type	Description
list[point_3d]	A list of user points.

get_user_points_with_count(count: int) -> list[point_3d]

Gets user points with a specified count.

Parameters:

Name	Type	Description	Default
count	int	The number of user points to get.	required

Returns:

Type	Description
list[point_3d]	A list of user points.

get_user_string(message: str) -> str

Prompts the user for a string.

Parameters:

Name	Type	Description	Default
message	str	The message to display.	required

Returns:

Type	Description
str	The user input string.

get_user_string_with_default_value(message: str, default_value: str) -> str

Prompts the user for a string with a default value.

Parameters:

Name	Type	Description	Default
message	str	The message to display.	required
default_value	str	The default value.	required

Returns:

Type	Description
str	The user string.

hide_north_arrow() -> None

Hides the north arrow on the 3D view.

hide_progress_bar() -> None

Hides the ProgressBar.

init_LxSDK() -> None

Initializes the LxSDK.

is_direct_info_enabled() -> bool

Checks if Direct Info is enabled.

Returns:

Type	Description
bool	True if Direct Info is enabled, false otherwise.

is_north_arrow_visible() -> bool

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

Returns:

Type	Description
bool	True if the north arrow is visible, false otherwise.

load_attribute_display_settings(file_path: str) -> None

Loads attribute display settings from a file.

Parameters:

Name	Type	Description	Default
file_path	str	The path to the file containing the settings.	required

load_element_attribute_display_settings(file_path: str, elements: list[ElementId]) -> None

Loads element attribute display settings from a file.

Parameters:

Name	Type	Description	Default
file_path	str	The path to the file containing the settings.	required
elements	list[ElementId]	The element list for which to load the settings.	required

pop_check_and_query_data() -> None

Pops the most recent state of check and query data from the stack.

print_error(message: str) -> None

Prints an error to the bottom toolbar of Cadwork 3d.

Notes

Attention, this function is blocking. User will need to click to continue the process.

Parameters:

Name	Type	Description	Default
message	str	The error message.	required

print_message(message: str, row: int, column: int) -> None

Prints a message that will be visualized in the bottom toolbar of the 3D view. You can arrange the message in the desired position by specifying the row and column.

Examples:

>>> import utility_controller as uc
>>> uc.print_message("Hello World!", 1, 1)

Parameters:

Name	Type	Description	Default
message	str	The message to print.	required
row	int	The row to print the message in.	required
column	int	The column to print the message in.	required

print_to_console(message: str) -> None

Prints a message to the Cadwork debug console.

Parameters:

Name	Type	Description	Default
message	str	The message.	required

push_check_and_query_data() -> None

Pushes the current state of check and query data onto a stack.

redirect_python_output_to_logger() -> None

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.

run_external_program(name: str) -> bool

Runs a 3D external program.

Parameters:

Name	Type	Description	Default
name	str	The external program name.	required

Returns:

Type	Description
bool	False if the program could not be run, true otherwise.

run_external_program_from_custom_directory(file_path: str) -> bool

Runs a 3D external program from a custom directory.

Parameters:

Name	Type	Description	Default
file_path	str	The external program file path.	required

Returns:

Type	Description
bool	False if error, true otherwise.

save_3d_file_silently() -> None

Saves the 3D file silently.

set_global_origin(global_origin: point_3d) -> None

Sets the global origin.

Parameters:

Name	Type	Description	Default
global_origin	point_3d	The global origin.	required

set_global_x_offset(offset: float) -> None

Sets the global X offset.

Parameters:

Name	Type	Description	Default
offset	float	The new global X offset.	required

set_global_y_offset(offset: float) -> None

Sets the global Y offset.

Parameters:

Name	Type	Description	Default
offset	float	The new global Y offset.	required

set_global_z_offset(offset: float) -> None

Sets the global Z offset.

Parameters:

Name	Type	Description	Default
offset	float	The new global Z offset.	required

set_north_angle(north_angle: float) -> None

Sets the angle of the north direction.

Parameters:

Name	Type	Description	Default
north_angle	float	The angle of the north direction in degrees.	required

set_project_address(address: str) -> None

Sets the project address.

Parameters:

Name	Type	Description	Default
address	str	The project address.	required

set_project_architect(project_architect: str) -> None

Sets the project architect.

Parameters:

Name	Type	Description	Default
project_architect	str	The project architect.	required

set_project_city(city: str) -> None

Sets the project city.

Parameters:

Name	Type	Description	Default
city	str	The project city.	required

set_project_country(country: str) -> None

Sets the project country.

Parameters:

Name	Type	Description	Default
country	str	The project country.	required

set_project_customer(project_customer: str) -> None

Sets the project customer.

Parameters:

Name	Type	Description	Default
project_customer	str	The project customer.	required

set_project_data(project_data_id: str, data: str) -> None

Sets the project data.

Parameters:

Name	Type	Description	Default
project_data_id	str	The project data id.	required
data	str	The data to set.	required

set_project_deadline(project_deadline: str) -> None

Sets the project deadline.

Parameters:

Name	Type	Description	Default
project_deadline	str	The project deadline.	required

set_project_description(description: str) -> None

Sets the project description.

Parameters:

Name	Type	Description	Default
description	str	The new description for the project.	required

set_project_designer(project_designer: str) -> None

Sets the project designer.

Parameters:

Name	Type	Description	Default
project_designer	str	The project designer.	required

set_project_elevation(elevation: float) -> None

Sets the project elevation.

Parameters:

Name	Type	Description	Default
elevation	float	The project elevation.	required

set_project_latitude(latitude: float) -> None

Sets the project latitude.

Parameters:

Name	Type	Description	Default
latitude	float	The project latitude.	required

set_project_longitude(longitude: float) -> None

Sets the project longitude.

Parameters:

Name	Type	Description	Default
longitude	float	The project longitude.	required

set_project_name(project_name: str) -> None

Sets the project name.

Parameters:

Name	Type	Description	Default
project_name	str	The project name.	required

set_project_number(project_number: str) -> None

Sets the project number.

Parameters:

Name	Type	Description	Default
project_number	str	The project number.	required

set_project_part(project_part: str) -> None

Sets the project part.

Parameters:

Name	Type	Description	Default
project_part	str	The project part.	required

set_project_postal_code(postal_code: str) -> None

Sets the project postal code.

Parameters:

Name	Type	Description	Default
postal_code	str	The project postal code.	required

set_project_user_attribute(number: int, user_attribute: str) -> None

Sets the project user attribute.

Parameters:

Name	Type	Description	Default
number	int	The project user attribute number.	required
user_attribute	str	The project user attribute.	required

set_project_user_attribute_name(number: int, user_attribute_name: str) -> None

Sets the project user attribute name.

Parameters:

Name	Type	Description	Default
number	int	The project user attribute number.	required
user_attribute_name	str	The project user attribute name.	required

set_use_of_global_coordinates(use_of_global_coordinates: bool) -> None

Sets the use of global coordinates.

Parameters:

Name	Type	Description	Default
use_of_global_coordinates	bool	True to use global coordinates, false otherwise.	required

show_north_arrow() -> None

Shows the north arrow on the 3D view.

show_progress_bar() -> None

Shows a ProgressBar in the CommandBar.

start_project_data_dialog() -> None

Starts the project data dialog.

update_progress_bar(value: int) -> None

Updates the ProgressBar with a value.

Parameters:

Name	Type	Description	Default
value	int	A value between 0 and 100.	required