Share

Components Element Reference

Product Documentation
Intermediate
View Original

The Components element is used to specify the components that make up one version of the plug-in.

More than one Components elements can be used to identify the components for a plug-in; each Components element can identify one or more components. Platform and product information for a Components element is defined by the RuntimeRequirements element.

Along with the RuntimeRequirements element, the Components element might contain one or more ComponentEntry elements. The ComponentEntry element is used to define the individual files that need to be loaded by AutoCAD when the plug-in is ran. Each ComponentEntry element can contain a RuntimeRequirements element to identify which platform and product the component is associated with.

NoteIf all the components defined within a Components element apply to the same platform, you do not need to add a RuntimeRequirements element to each individual ComponentEntry element.

The following outlines the basic relationship of the Components, ComponentEntry, and RuntimeRequirements elements.

<Components>
  <RuntimeRequirements ... />

  <ComponentEntry ... >
    <RuntimeRequirements ... />
  </ComponentEntry>
  <ComponentEntry ... >
    <RuntimeRequirements ... />
  </ComponentEntry>
</Components>

ComponentEntry Element

The ComponentEntry element is required and is used to specify details about each individual component in the Components element.

You can specify as many ComponentEntry elements as needed. Component types can be one of the following file formats:

  • AutoLISP (LSP)
  • AutoLISP Fastload (FAS)
  • Visual LISP (VLX)
  • Managed or Mixed Mode .NET Assembly (DLL)
  • ObjectARX (ARX)
  • ObjectDBX (DBX)
  • Partial Customization (CUIx)
  • Tool Palette (ATC)

A ComponentEntry element may contain a Commands element if the LoadReasons attribute is set to LoadOnCommandInvocation.

NoteComponentEntry elements are loaded in the order they are listed, but from the bottom up. Therefore, any files that other components are dependent on must be lower down the list. For example, if an ObjectARX module is dependent on an ObjectDBX module, then the ObjectARX module will need to appear above the ObjectDBX module in the list.

A ComponentEntry element can have any of the following attributes attached to it:

Attribute

Description

AppName

Optional for AutoLISP; Required for ObjectARX and .NET - Component name; same as AppName in the ObjectARX API AcadAppInfo class.

AppDescription

Component description; same as AppDescription in the ObjectARX API AcadAppInfo class.

AppType

Component type; overrides the type derived from the file extension provided in the ModuleName attribute.

The component type can be one of the following:

  • Arx – ObjectARX
  • Cui or CuiX– Partial customization
  • Mnu – Menu customization
  • Dbx – ObjectDBX
  • .Net – Managed or Mixed .NET assembly
  • Lisp or CompiledLisp – AutoLISP/Visual LISP
  • Atc – Tool palette
  • Bundle – Bundle package
  • Dependency – Resource DLL (not to be loaded into the AutoCAD-based product)

ModuleName

Relative path to the component within the bundle; same as ModuleName in the ObjectARX API AcadAppInfo class.

The component type is determined from the file extension:

  • .arx – ObjectARX
  • .dbx – ObjectDBX
  • .dll – Managed .NET assembly
  • .lsp, .fas, or .vlx – AutoLISP/Visual LISP
  • .cuix – Partial customization
  • .atc – Tool palette

If your application will handle multiple languages, different versions of a specific component can be specified by combining ModuleName with a locale code. See Supported Locale Codes Reference for a full list of supported locale codes.

NoteAll path specifiers are '/' and not '\', and paths are relative to the root .bundle folder.

PerDocument

AutoLISP only - When True, the AutoLISP file is loaded once per document. Default is True.

Loadreasons

Multiple values can be specified - Defines the load behavior parameters for the component with LoadReasons and the exception of the LoadOnCommandInvocation parameter.

By default, LoadOnAutoCADStartup, LoadOnAppearance, and LoadOnProxy are enabled (set to True) if LoadReasons is not specified. If parameters need to be disabled (set to False), the LoadReasons element must be specified along with the parameters set to False.

By default, LoadOnCommandInvocation is disabled, enabling it will disable LoadOnAutoCADStartup and LoadOnAppearance unless they are explicitly enabled.

See the ObjectARX Reference Guide for full details on AcadAppInfo LoadReasons.

Valid parameter values:

  • True – Parameter is enabled
  • False – Parameter is disabled

The following parameters are available:

  • LoadOnCommandInvocation. Load only when a custom commands is invoked. When using this parameter, a ‘Commands’ element must be included. If LoadOnCommandInvocation is enabled, LoadOnAutoCADStartup and LoadOnAppearance are assumed to be disabled unless explicitly enabled. Only applies to AutoLISP, ObjectARX, and .NET modules.
    NoteFor startup performance reasons, it is very important to use this option when your components define commands.
  • LoadOnAutoCADStartup. Load when the AutoCAD-based product starts up. When specified, this parameter has precedence over all other parameters. It is recommended only to use LoadOnAutoCADStartup when none of the other parameters are suitable, disable it (set it to False) whenever possible. If the LoadOnAutoCADStartup parameter is omitted, then it defaults to enabled (set to True) unless LoadOnCommandInvocation is enabled, in which case LoadOnAutoCADStartup defaults to False. Only applies to ObjectARX and .NET modules.
  • LoadOnProxy. Load when a proxy for a custom entity is detected. By default, this parameter is enabled unless explicitly disabled (set to False). When enabled (set to True), LoadOnAutoCADStartup should be disabled. Only applies to ObjectDBX files.
  • LoadOnAppearance. Load when the product detects the application bundle in one of the ApplicationPlugins folders, thereby supporting instant load on installation with no need to restart the AutoCAD-based product. The parameter behaves the same way as LoadOnAutoCADStartup except the load context is relevant to when an application is installed while the product is running, for instance if installed via the Autodesk Exchange Apps website.

Commands Element

The Commands element is optional unless the LoadOnCommandInvocation parameter is enabled for the LoadReasons attribute. Used to specify which commands to register for LoadOnCommandInvocation.

You can specify more than one Command element as needed.

A Commands element can have the following attribute attached to it:

Attribute

Description

GroupName

Name used to organize related commands.

Command Element

Specifies the global and local names for each command.

A Command element can have any of the following attributes attached to it:

Attribute

Description

Global

Global command name.

Local

Local command name.

Commands can be defined for multiple languages by combining Local with a locale code. See Supported Locale Codes Reference for a full list of supported locale codes.

HelpTopic

Help topic to open when the command is active and F1 is pressed.

NoteTo display the help topic, a help file must be assigned to the plug-in. The help file location for the plug-in is specified with the HelpFile attribute under the ApplicationPackage element.

StartupCommand

Executes the command at startup when True.

Related References

Related Concepts

Was this information helpful?