External Utility Installation

Loading commands and applications into the Autodesk Revit UI is done solely through an .addin manifest file previously introduced in the 2011 version of the Revit API. That's right—the Revit.ini method has officially been retired!

An .addin manifest file is an XML-formatted file that Revit reads on startup and uses to register API applications into the current session. Manifest files are only read and processed by Revit from the following two locations on your system:

Windows XP

  • C:Documents and SettingsAll UsersApplication DataAutodeskRevitAddins2012
  • %USERPROFILE%Application DataAutodeskRevitAddins2012

Windows 7

  • C:ProgramDataAutodeskRevitAddins2012
  • %USERPROFILE%AppDataRoamingAutodeskRevitAddins2012

Loading multiple commands or applications within a single manifest file is possible by nesting multiple AddIn elements into one .addin file between the RevitAddins tag of the XML file. Example .addin files are shown here for adding our example ExternalCommand (Listing 25.5) and ExternalApplication (Listing 25.6).

LISTING 25.5 .addin manifest example—ExternalCommand
<?xml version="1.0" encoding="utf-8" standalone="no" ?>
<RevitAddIns>
 <AddIn Type="Command">
 <Assembly>MARA2012.Application.dll</Assembly>
 <AddInId>93749a2c-aa68-4331-a3a9-0e334d2a2653</AddInId>
 <FullClassName>MARA2012.Application.Command</FullClassName>
 <Text>MARA2012 - Workset Views Sample</Text>
 <VisibilityMode>NotVisibleInFamily</VisibilityMode>
 <VendorId>DONR</VendorId>
 <VendorDescription>Don Rudder, www.revitnet.blogspot.com
 </VendorDescription>
</AddIn>
</RevitAddIns>
LISTING 25.6 .addin manifest example—ExternalApplication
<?xml version="1.0" encoding="utf-8" standalone="no" ?>
<RevitAddIns>
 <AddIn Type="Application">
 <Name>MARA2012 Sample</Name>
 <Assembly>MARA2012.Application.dll</Assembly>
 <AddInId>356CDA5A-E6A5-412f-A9EF-B3233116B8C3</AddInId>
 <FullClassName>MARA2012.Application.Application</FullClassName>
 <VendorId>DONR</VendorId>
 <VendorDescription>Don Rudder, www.revitnet.blogspot.com
 </VendorDescription>
 </AddIn>
</RevitAddIns>

The .addin XML schema utilizes the XML tags described in Table 25.1. Note that VendorId and VendorDescription are new tags introduced in 2012's API that are required for all .addin manifest files.

TABLE 25.1: .addin Manifest File Tags and Descriptions

TAG DESCRIPTION
Assembly Required for all ExternalCommand and ExternalApplication objects. This is used to enter only the filename of the assembly if placed in the same directory as the .addin manifest file or the full path to the assembly if placed in a different directory.
FullClassName This is also a required tag for all ExternalCommand and ExternalApplication objects. Specifies the full name of the class (namespace.classname) that implements IExternalCommand or IExternalApplication.
AddInId This is another required tag for all ExternalCommand and ExternalApplication objects. Specifies a GUID that represents the ID of the particular application. AddInId must be unique for a given session of Revit. The property UIApplication.ActiveAddInId provides programmatic access to this value at runtime, if required.
Name This tag applies only for ExternalApplications and is the name of the command.
VendorId This is the first of two new required tags for all ExternalCommand and ExternalApplication objects. Note that the title of this tag is case sensitive. Contains the Autodesk registered ID for the developer from which the add-in originated.
VendorDescription This is the second of two new required tags for all ExternalCommand and ExternalApplication objects and is a brief description of the vendor.
Text An optional but suggested tag used to display a textual name for an ExternalCommand object only. The default is External Tool.
Description This is an entirely optional tag used with ExternalCommand objects only and provides a short description of the command, similar to a tooltip. The default is a tooltip with just the command text.
VisibilityMode This optional ExternalCommand objects–only tag provides the ability to specify if a command is to be visible in project documents, family documents, or no document at all. It is also possible to specify the discipline(s) where the command should be visible. Multiple values may be set for this option. The default is to display the command in all modes and disciplines, including when there is no active document. Previously written external commands that need to run against the active document should either (1) be modified to ensure that the code deals with invocation of the command when there is no active document, or (2) apply the NotVisibleWhenNoActiveDocument mode.
AvailabilityClassName This optional ExternalCommand object tag is used to selectively gray out a command button based on logic that you provide. This tag must list the full name of the class in the assembly file that implements IExternalCommandAvailability. The default is a command that is available whenever it is visible.
LargeImage This optional tag is used to display an icon next to your command name. Specifies the path to the icon to use for the button in the External Tools drop-down menu. The icon should be 32×32 pixels for best results. This tag can only be used for ExternalCommand objects.
LongDescription This optional tag is used to extend a button's tooltip. This tooltip is shown when the mouse hovers over the command. You can split the text of this option into multiple paragraphs by placing <p> tags around each paragraph. This tag can be used for ExternalCommand objects only. If neither this property nor TooltipImage is supplied, the button will not have an extended tooltip.
TooltipImage This is another optional tag for use with ExternalCommand objects only; should list the path to an image file (animated GIF files work well here) to show as a part of the button extended tooltip and is displayed when the mouse hovers over the command. If neither this property nor TooltipImage is supplied, the button will not have an extended tooltip.
LanguageType Localization setting for Text, Description, LargeImage, LongDescription, and TooltipImage of buttons for external tools. Revit will load the resource values from the specified language resource DLL. The value can be one of the 11 languages supported by Revit. If no LanguageType is specified, the language resource that the current session of Revit is using will be automatically loaded.
..................Content has been hidden....................

You can't read the all page of ebook, please click here login for view all page.
Reset