ITools

class ITools

Bases: ImpactCOMWrapperBase

Description:

Allows the execution of several interactive tools, such as hole-finder and path-finder.

Remarks:

Note that the ITools object is not available from nServer, because interactive tools will not work without a user interface. There are non-interactive methods available for some of the tools, for use with nServer. Please see the remarks section of each method for more information.

Wraps a COM object or another wrapper instance. Accepts: - A valid impact_object - An existing impact_com_wrapper_base-derived instance

property active_english_tool_name

Gets active_english_tool_name.

Description:

Gives the English name for the currently running tool.

Remarks:

Introduced in Impact 12.0.0.166

Returns:

The value of active_english_tool_name.

Return type:

active_english_tool_name (str)

property active_plot_context

Gets active_plot_context.

Description:

Gets information about the last plot operation.

Remarks:

This object is generally used by scripts that respond to the plotBefore and plotAfter auto-tasks.

Returns:

The value of active_plot_context.

Return type:

active_plot_context (IPlotContext)

Examples:

create_layer()
Description:

Creates a new layer in the same way a layer would be created interactively.

Remarks:

Introduced in Impact 7.0.0.10. See ILayers.add for the recomended way to create layers non-interactively.

Examples:

create_project()
Description:

Creates a new drawing in the same way a drawing would be created interactively.

Remarks:

It is usually better to use IDatabase.create_item than this method. Introduced in Impact 5.1.4.23.

Examples:

execute_file(path)
Description:

Executes another script file (or IML macro file).

Remarks:

Path can be a location relative to the script and macro repository (example “UtilitiesLayer Checker.txt”) or it can be a full pathname (“D:My ScriptsLayer Checker.txt”). To call a legacy macro, use the “@” method of specifying the name of the macro within the file (example “Utilitieslayer_checker.run@first_check”). The current script will resume after the executed script has completed. Introduced in Impact 8.0.0.46.

Parameters:

path (str) – The location of the script (as an absolute or relative path).

Examples:

fill_area(points, fill_area_m_t_s)
Description:

Allows you to fill an area with offset entities, defined by the chosen master tool setting

Remarks:

This method behaves in a similar way to the hole_finder and hole_finder2 methods, in that one or more points are required to indicate the area(s) to be filled. This tool is available only in Impact; area filling is not currently supported from nServer. Introduced in Impact 8.0.0.43

Parameters:

  • points (any) – An array of IVector objects, defining the points about which to detect the holes.

  • fill_area_mts (IMasterSetting) – Specifies an object defining the fill area master tool settings to use. This must be a setting of type mstFillArea.

Examples:

hole_finder(points, replicate, settings)
Description:

This method allows you to create new geometry offsetting inside and or outside from an area defined by existing geometry.

Remarks:

Deprecated, use hole_finder2 instead. This is an interactive tool, available only in Impact. For non-interactive hole-finding, see the IHoleFinder object.

Returns:

Returns True if a hole was found for every point specified, or False otherwise.

Parameters:

  • points (any) – An array of IVector objects, defining the points about which to detect the holes.

  • replicate (bool) – Specifies if common blocks should be operated on.

  • settings (str) – Specifies the name of the hole/path finding master tool settings to use.

hole_finder2(points, replicate, hole_finder_m_t_s)
Description:

This method allows you to create new geometry offsetting inside and or outside from an area defined by existing geometry.

Remarks:

This is an interactive tool, available only in Impact. For non-interactive hole-finding, see the IHoleFinder object.

Returns:

Returns True if a hole was found for every point specified, or False otherwise.

Parameters:

  • points (any) – An array of IVector objects, defining the points about which to detect the holes.

  • replicate (bool) – Specifies if common blocks should be operated on.

  • hole_finder_mts (IMasterSetting) – Specifies an object defining the hole/path finding master tool settings to use. This must be a setting of type mstHoleFinder.

Examples:

is_tool_available(english_tool_name)
Description:

Indicates whether the specified Impact tool can be run

Remarks:

In Impact, you can determine the tool name using Help > What’s This and clicking on the menu item for that tool. The English tool name is shown at the end, in square brackets - for example enquire_distance_parallel. A tool might be unavailable for a variety of reasons; for example the current user might not have the necessary privileges for that tool, or the current licence might not allow the tool, or the tool might require a drawing to be open. If this method returns false, you can call is_tool_available_reason for more information. If the tool is available, you may call start_tool to run it. Introduced in Impact 12.0.0.166

Returns:

Returns true if the tool may be started at this time.

Parameters:

english_tool_name (str) – The English name of the required tool.

Examples:

is_tool_available_reason(english_tool_name)
Description:

Gives the reason that the specified tool is not available.

Remarks:

Introduced in Impact 12.0.0.166

Returns:

Returns the reason (in the current language).

Parameters:

english_tool_name (str) – The English name of the required tool.

Examples:

layout(options, results)
Description:

Creates a layout from the active drawing.

Remarks:

This method is deprecated, please use ILayer.layout instead.

Parameters:

  • options (ILayoutOptions) – Specifies the options to use to create the layout.

  • results (ILayoutResults) – The results of creating the layout are returned in this method parameter.

path_finder(start_entity, end_entity, position, continue_past_dead_ends, replicate, left_on_junction, settings)
Description:

Allows you to create new geometry relative to existing geometry, offsetting to one or both sides of a specified path.

Remarks:

It is often preferable to use the path_finder2 method, as that allows you to specify a point on the start entity and a point on the end entity (similar to how the Impact tool operates). This is an interactive tool, available only in Impact. For non-interactive path-finding, see the IPathFinder object.

Parameters:

  • start_entity (IEntity) – Specifies the start entity.

  • end_entity (IEntity) – Specifies the end entity.

  • position (IVector) – Specifies the direction of travel from the start entity.

  • continue_past_dead_ends (bool) – Specifies if the tool will pause when a dead-end is detected along the path.

  • replicate (bool) – Specifies if the tool is to check for paths of the same configuration of entities and blocks as the path highlighted and automatically copy the geometry.

  • left_on_junction (bool) – Allows control of the direction of the path at intersections.

  • settings (IMasterSetting) – Specifies an object defining the hole/path finding master tool settings to use. This must be a setting of type mstHoleFinder.

Examples:

path_finder2(start_entity, start_point, end_entity, end_point, position, continue_past_dead_ends, replicate, left_on_junction, settings)
Description:

Allows you to create new geometry relative to existing geometry, offsetting to one or both sides of a specified path.

Remarks:

Introduced in Impact 8.0.0.20 This is an interactive tool, available only in Impact. For non-interactive path-finding, see the IPathFinder object.

Parameters:

  • start_entity (IEntity) – Specifies the start entity.

  • start_point (IVector) – Specifies the point on the start entity at which to begin the path.

  • end_entity (IEntity) – Specifies the end entity.

  • end_point (IVector) – Specifies the point on the end entity at which to stop the path.

  • position (IVector) – Specifies the direction of travel from the start entity.

  • continue_past_dead_ends (bool) – Specifies if the tool will pause when a dead end is detected along the path.

  • replicate (bool) – Specifies if the tool is to check for paths of the same configuration of entities and blocks as the path highlighted and automatically copy the geometry.

  • left_on_junction (bool) – Allows control of the direction of the path at intersections.

  • settings (IMasterSetting) – Specifies an object defining the hole/path finding master tool settings to use. This must be a setting of type mstHoleFinder.

plot(options)
Description:

Plots items from the active drawing.

Remarks:

This tool is available only in Impact; plotting is not currently supported from nServer.

Parameters:

options (IPlotOptions) – Specifies additional options for plotting.

start_tool(english_tool_name)
Description:

Starts the specified tool (if available) to be run intreactively.

Remarks:

You should call is_tool_available before attempting to start the tool. start_tool will not work if an automation task is already running. You can queue up multiple tools to run, but it is not guaranteed that they will all be run. This mechanism is best used from an external application or external script. It can be used from the script toolbox or a menu item, but you should ensure that the script finishes soon after calling start_tool, otherwise unpredictable behaviour can occur. In Impact, you can determine the tool name using Help > What’s This and clicking on the menu item for that tool. The English tool name is shown at the end, in square brackets - for example enquire_distance_parallel. Introduced in Impact 12.0.0.166

Returns:

Currently this tool always returns true.

Parameters:

english_tool_name (str) – The English name of the required tool.

Examples: