The Components element is used to specify the components that make up one version of the plug-in.
More than one Components element 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 with the RuntimeRequirements element.
If 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.
Along with the RuntimeRequirements element, the Components element can contain one or more of the following elements
The following outlines the basic relationship of the Components element and any elements it can contain.
<Components> <RuntimeRequirements ... /> <RegistryEntries> <RegistryEntry ... /> </RegistryEntries> <SystemVariables> <SystemVariable ... /> </SystemVariables> <EnvironmentVariables> <EnvironmentVariable ... /> </EnvironmentVariables> <ComponentEntry ... > <RuntimeRequirements ... /> </ComponentEntry> <ComponentEntry ... /> <Commands ...> <Command ... /> </Commands> </Components>
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:
Windows and Mac OS
Windows only
A ComponentEntry element may contain a Commands element if the LoadReasons attribute is set to LoadOnCommandInvocation.
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:
|
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:
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. Note: All 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:
The following parameters are available:
|
XamlType |
XAML type; currently the only supported value is "ContextualTabRule" and it is required when a XAML file is assigned to the ModuleName attribute. The application file that uses the XAML file should be listed after the ComponentEntry element that contains the XAML file. |
The RegistryEntries element is optional, and can contain one or more RegistryEntry elements. A RegistryEntry element contains the definition of a registry entry that the plug-in should create or modify. Registry entries are stored in the Windows Registry or in a property list (PLIST) file on Mac OS.
Attribute |
Description |
---|---|
Name |
Name of the registry entry to create or modify. |
Value |
Value to assign to the registry entry. The value can include one of the optional operator prefixes: +, -, &, and |. See the "Variable Value Operator Prefixes" section for more information. Note: The operator prefix is not retained when the value is applied to the registry entry.
|
Type |
Data type to assign to the registry entry. Optional when modifying an existing registry entry. Valid values are:
If an operator prefix is used as part of the registry entry's value, the appropriate data type must be specified. If the appropriate data type is not used, the operation will be treated as a string operation. |
Flags |
Optional, creation and modification flags. Multiple flags can be specified; use a pipe symbol to separate each flag. The following flags are supported:
Note: The Open or OpenOnce flag must be used to modify the value of a registry entry.
|
The following example creates the registry key MYREGKEY and adds the values STRING and NUMBER:
<RegistryEntries> <RegistryEntry Key="MYREGKEY" Name="STRING" Value="Example" Type="REG_SZ" /> <RegistryEntry Key="MYREGKEY" Name="NUMBER" Value="123" Type="REG_DWORD" /> </RegistryEntries>
The SystemVariables element is optional, and can contain one or more SystemVariables elements. A SystemVariable element contains the definition of a system variable that the plug-in should create or modify.
Attribute |
Description |
---|---|
Name |
Name of the system variable to create or modify. |
Value |
Value to assign to the variable. The value can include one of the optional operator prefixes: +, -, &, and |. See the "Variable Value Operator Prefixes" section for more information. Note: The operator prefix is not retained when the value is applied to the variable.
|
PrimaryType |
Data type to assign to the variable. Optional when modifying an existing system variable. Valid values are:
If an operator prefix is used as part of the variable's value, the appropriate data type must be specified. If the appropriate data type is not used, the operation will be treated as a string operation. |
StorageType |
Storage location for the variable's value; when persisted. Optional when modifying an existing system variable. Valid values are:
|
Owner |
Optional, AcRX service name. Used to make a system variable read-only and only modifiable by the application that registers the service name using acrxRegisterService(). |
Flags |
Optional, creation and modification flags. Multiple flags can be specified; use a pipe symbol to separate each flag. The following flags are supported:
Note: The Open or OpenOnce flag must be used to modify the value of a variable.
|
The following example creates a system variable named MYVARIABLE:
<SystemVariable Name="MYVARIABLE" PrimaryType="String" StorageType="User" Value="Example" Owner="" Flags="Create|DotIsEmpty|SpacesAllowed" />
The following example changes the value of the CURSORSIZE system variable to 100 when the plug-in is loaded the first time:
<SystemVariable Name="CURSORSIZE" Value="100" Flags="OpenOnce" />
The EnvironmentVariables element is optional, and can contain one or more EnvironmentVariable elements. A EnvironmentVariable element contains the definition of an environment variable that the plug-in should create or modify. Environment variables are stored in the Windows Registry or in a property list (PLIST) file on Mac OS.
Attribute |
Description |
---|---|
Name |
Name of the environment variable to create or modify. |
Value |
Value to assign to the variable. The value can include one of the optional operator prefixes: +, -, &, and |. See the "Variable Value Operator Prefixes" section for more information. Note: The operator prefix is not retained when the value is applied to the variable.
|
Type |
Optional, data type that Value represents. Valid values are:
If an operator prefix is used as part of the variable's value, the appropriate data type must be specified. If the appropriate data type is not used, the operation will be treated as a string operation. |
Flags |
Optional, creation and modification flags. Multiple flags can be specified; use a pipe symbol to separate each flag. The following flags are supported:
Note: The Open or OpenOnce flag must be used to modify the value of a variable.
|
The following is an example of creating two environment variables named MYNUMVAR and MYSTRVAR:
<EnvironmentVariables> <EnvironmentVariable Name="MYNUMVAR" Value="123" /> <EnvironmentVariable Name="MYSTRVAR" Value="Example" /> </EnvironmentVariables>
Operator prefixes are used to modify the current value of a variable when the plug-in is loaded. You can add one of the operator prefixes listed in the following table to the Value attribute of a RegistryEntry, SystemVariable, or EnvironmentVariable element.
Prefix |
Description |
---|---|
+ (plus sign) |
Adds or appends a value to an existing variable's value. Int16, Int32, Real: Adds Value to an existing variable's value. String: Appends Value to an existing variable's value. |
- (hyphen) |
Subtracts or removes a value to an existing variable's value. Int16, Int32, Real: Subtracts Value from an existing variable's value. String: Removes Value from an existing variable's value. |
& (ampersand) |
Bitwise-and operation with the existing value of the variable; only numeric values are supported. |
| (pipe symbol) |
Bitwise-or operation with the existing value of the variable; only numeric values are supported. |
The following always enables the END, MID, CEN, NOD, QUA, and INT running object snaps, and leaves all other object snap settings as-is:
<SystemVariable Name="OSMODE" Value="|63" Flags="Open" />
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. |
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. Note: To 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. |