HyperPics: Beyond the UI

AutoCAD 2017 ObjectARX and Managed .NET Documentation

As a developer, the one thing that is almost as important to me as my development environment is the documentation for the libraries I plan on using.  Documentation is broken up into two different pieces of information: reference and concepts.

• Reference documentation is used to explain the namespaces, classes, and members that make up a library. Members might be methods, properties, or enumerators.
• Concepts, often referred to as developer topics, explain how to implement various parts of a library in your program.

These two things aren't earth shattering by any means, but that is the general way I approach the organization of the AutoCAD developer documentation.  What is most important to you as a developer is where this documentation exists so you can do your job, and that is to write the programs that your customers or company expect.

The ObjectARX SDK is a set of not only library and header files that describe the AutoCAD ObjectARX and Managed .NET APIs, but also contains sample projects and most importantly the documentation for these two APIs (or most of it, more on that in a bit). The ObjectARX SDK, is essential, whether you are developing applications with C++ or VB.NET/C#. You can download the ObjectARX SDK from http://www.objectarx.com/. Once downloaded, execute the EXE file to install the ObjectARX SDK which wants to be installed to an Autodesk folder under root drive of your workstation.

The ObjectARX SDK contains 11 folders:

• Classmap - Drawing file that outlines the hierarchy of the ObjectARX, Managed .NET, and ActiveX object models.
• Docs - CHM files that make up most of the ObjectARX and Managed .NET documentation set, with the exception of the Managed .NET Developer's Guide.
• Inc - Platform independent library and header files for developing ObjectARX and Managed .NET applications.
• Inc-Win32 - Windows 32-bit (x86) library and header specific files for developing ObjectARX and Managed .NET applications.
• Inc-x64 - Windows 64-bit (x64) library and header specific files for developing ObjectARX and Managed .NET applications.
• Lib-Win32 - Windows 32-bit (x86) library specific files for developing ObjectARX applications.
• Lib-x64 - Windows 64-bit (x64) library specific files for developing ObjectARX applications.
• Redistrib-Win32 - Precompiled DBX files for the AecModeler and Hidden Line Representation libraries that can be distributed with your 32-bit applications.
• Redistrib-x64 -Precompiled DBX files for the AecModeler and Hidden Line Representation libraries that can be distributed with your 64-bit applications.
• Samples - Sample projects that demonstrate various aspects of the ObjectARX and Managed .NET APIs.
• Utils - Additional libraries that are less frequently used; AModeler, Atil, BRep, and Hidden Line Representation.

My main focus is on the developer documentation, so that is what this article will be focusing on.  if you want additional information on the various other parts of the ObjectARX SDK, see the developer documentation. :)

Classmap

The Classmap provides a visual representation of how the objects in the ObjectARX, Managed .NET, and ActiveX libraries are related to each other. This can be helpful in understanding object inheritance or where an object is located within the object models.

ObjectARX and Managed .NET Documentation

A majority of the ObjectARX and Managed .NET documentation is only available from the CHM files that are in the Docs folder of the ObjectARX SDK installation folder. The following provides a summary of each CHM file that is available:

• arxdev.chm - ObjectARX Developer's Guide which contains concepts related to developing applications with the ObjectARX API.
• arxdoc.chm - Main file that allows you to search and browse all of the available CHM files located in the folder from a single documentation file.
• arxiop.chm - Interoperability Guide which outlines the best practices to use when developing and deploying your applications.
• arxmgd.chm - Managed .NET Reference Guide which provides information about the classes and members exposed in the library files of the AutoCAD Managed .NET API.
• arxmgr.chm - Migration Guide which contains information about updating applications to 64-bit, and handling the New Tab Page and changes to the graphics system.
• arxref.chm - ObjectARX Reference Guide which provides information about the classes and members exposed in the header and library files of the ObjectARX API.
• readarx.chm - ObjectARX Readme that contains last minute changes or important information on the changes in the latest release

The Managed .NET Developer's Guide until recently has only been available online (http://bit.ly/1RdYZ2L), but starting with the AutoCAD 2017 release it is now also available as a CHM file for offline viewing. The CHM file for the Managed .NET Developer's Guide is not part of the ObjectARX SDK and must be downloaded separately, a ZIP file containing the CHM file and a new version of the arxdoc.chm file can be downloaded directly from http://bit.ly/1pxfLz8. After downloading the file, copy the two CHM files into the Docs folder of the ObjectARX SDK installation folder.

Making the Managed .NET Developer's Guide available offline has been an on going request for several years now, so let us know what you think and if there is anything we can improve.  As time goes along, additional index terms will be added to topics to improve the discoverability of topics.

Accessing Developer Documentation from Visual Studio

CHM files are the current backbone of the ObjectARX and Managed .NET developer documentation, but parts of the documentation can be accessed from within Microsoft Visual Studio.  Since AutoCAD 2012, a separate Help installer has allowed for the integration of the ObjectARX and Managed .NET Reference Guides into Microsoft Visual Studio.  This integration provides:

• Contextual F1 support from a code editor window; highlight a member's name and press F1 to open the Microsoft Help Viewer to the specific topic.
• Browse and search the reference topics from within Microsoft Visual Studio without needing to browse to and open the CHM files. The integrated help contains the same content as the CHM files.

To utilize the integrated help within Microsoft Visual Studio, download one of the following ZIP files and run the installer:

• AutoCAD 2017 (supports Microsoft Visual Studio 2015)
• AutoCAD 2016 (supports Microsoft Visual Studio 2012 and 2013)
• AutoCAD 2015 (supports Microsoft Visual Studio 2012)
• AutoCAD 2014 (supports Microsoft Visual Studio 2010 and 2012)
• AutoCAD 2013 (supports Microsoft Visual Studio 2010)
• AutoCAD 2012 (supports Microsoft Visual Studio 2010)

Starting with AutoCAD 2017, some of the reference content can be accessed via tooltips with the Intellisense feature and Object Browser in Microsoft Visual Studio.  This is done by providing segments of the content as XML documentation for each of the public AutoCAD Managed .NET libraries.  Not all classes and members have documentation at this moment, but 85+% have some form of documentation at this time.  This is very much a work in progress yet.

To utilize the XML documentation, download one of the following ZIP files and extract its contents to the location in which you reference the AutoCAD Managed .NET DLLs from for you projects:

• AutoCAD 2017
• AutoCAD 2016
• AutoCAD 2015

 

 

While the XML documentation has only been created back to AutoCAD 2015, it is possible to use the XML documentation for AutoCAD 2015 with an earlier version of the AutoCAD Managed .NET libraries.  For example, simply download the ZIP file created for AutoCAD 2015 and extract the XML files into the location of the AutoCAD 2014 libraries. The XML documentation should be recognized by Microsoft Visual Studio and displayed in the environment.

Note: The XML documentation will also part of the official AutoCAD 2017 .NET NuGet packages (https://www.nuget.org/packages/AutoCAD.NET/) once they have been published.

I will expand on the in Microsoft Visual Studio integrated help and XML documentation in a future article.  These two features can be huge productivity gains as a developer. 

If you have any comments about the developer documentation please let me know.  I am always looking for ways to improve the content and access to the developer documentation.

Sincerely,
  Lee

AutoCAD Developer Documentation Survey - 2016

Do you want to affect the direction of the AutoCAD developer documentation?  Have comments you want to share with us about the AutoCAD developer documentation?  If so, we want to hear from you.

A new AutoCAD Developer Documentation survey has been posted, and is an updated version of the survey that I had posted several years ago.  You can access the new survey at the following URL:
https://www.surveymonkey.com/r/QXNH7VQ

The survey will be open from March 28, 2016 through May 31, 2016.  This should provide plenty of time to respond to the survey.  Feel free to share the link with other fellow developers, the more responses collected the better.

A few years ago, I was tasked with creating a road map for the AutoCAD developer documentation that would help to establish the future direction of the documentation.  As part of that work, I created a survey that was sent out to the AutoCAD developer community; the survey provided great input and generated many more responses than I ever expected, 405 to be exact.

Some of the more interesting results from that survey are as follows:

• C# and AutoLISP are the top two popular programming languages of choice.
• Many developer's were not aware of the Sheet Set Object, Transmittal Object, Connectivity Automation Object, and CAD Standards Plug-in libraries that were introduced between AutoCAD 2000 through AutoCAD 2006.
• CHM and PDF formats were the preferred delivery formats for ObjectARX and Managed .NET documentation.
• Majority of developers were unaware of the ObjectARX and Managed .NET integrated help for Microsoft Visual Studio.

The work done on the developer documentation over the past few years has been directly influenced by the survey responses.  Here are many of the high-level changes that were influenced by the survey:

• Developer documentation centric landing page - Page that lists the locations of the AutoCAD developer documentation in the AutoCAD product and on Autodesk.com.
• XML documentation for the Managed .NET libraries - Documentation enables the display of short descriptions for members and arguments in the libraries.  The descriptions are displayed in tooltips within the code editor window and as part of the text in Object Browser.
• ObjectARX and Managed .NET Integrated Help - ObjectARX and Managed .NET reference documentation made available from the Microsoft Help Viewer in Microsoft Visual Studio.  Improvements have been made to the content, content formatting, and search results.
• Managed .NET Developer's Guide - Content was expanded to cover more features (viewports, plotting, page setups, render presets, and more) and additional code samples were added.
• Managed .NET Developer's Guide offline - CHM file has been made available and is accessible as part of the ObjectARX SDK documentation.
• ActiveX and AutoLISP reference documentation - Reformatted and improvements made to the content.
• ActiveX Developer's Guide - Republished as a CHM file for offline access.
• ActiveX reference documentation - AutoLISP/Visual LISP code samples were added for most of the ActiveX code samples.
• Transmittal and CAD Standards Plug-in documentation - Now accessible from the AutoCAD product help, and has been updated with the inclusion of code samples.

I can't promise any changes will result from the responses collected, but as you can tell from the list of changes that your responses do have an impact on the AutoCAD developer documentation.

If you have any questions or comments, please to let me know and I will do my best to respond to them as soon as possible.

Sincerely,
  Lee

What's New In the AutoCAD 2017 APIs and Developer Documentation

Wow, where did the year go!  Looking back, the last article I wrote was for the changes in the AutoCAD 2016 APIs and Developer Documentation... I will try to be more active this year.  I have been trying to blog more, but often find myself spending time working on the developer documentation or preparing for AU sessions.

There have been many small and large changes to the AutoCAD application programming interfaces (APIs) in the latest release along with many improvements to the developer documentation.  While I cannot cover them all in depth here, I will highlight the changes that were introduced.

The developer related documentation can be found at:
http://help.autodesk.com/view/ACD/2017/ENU/?home=homepage_dev

The following outlines the changes that were made to the AutoCAD APIs:

General Updates

• The CAD Management and Developer Home Page has been reorganized to provide a better flow. General compatibility information for the AutoLISP, ActiveX, Managed .NET, and ObjectARX APIs are not accessible from this page.
• BMP images used in CUIx files no longer support the color 192,192,192 as a workaround for transparency. If custom images need to support transparency, they must be converted to PNG files and assigned the transparent color. (http://help.autodesk.com/view/ACD/2017/ENU/?guid=GUID-94A0EA14-5165-4D84-A2F1-F44D33F80BCC)

AutoLISP

• No new or changed functions this release.
• The ssget function topic has been updated to include the :L, _:V, and # selection modes. (http://help.autodesk.com/view/ACD/2017/ENU/?guid=GUID-0F37CC5E-1559-4011-B8CF-A3BA0973B2C3)
• Historical list of changes from AutoCAD 2009 through AutoCAD 2017 can be used to identify potential problems in existing programs. (http://help.autodesk.com/view/ACD/2017/ENU/?guid=GUID-037BF4D4-755E-4A5C-8136-80E85CCEDF3E)

DCL

• No new or changed functions/tiles this release.

ActiveX/COM

• No new classes were added, but the following here changed:
  • AcadAcCmColor
  • AcadApplication
  • AcadLayerStateManager
  • AcadSecurityParams
• The IAcadShadowDisplay class is now obsolete as a result of Mental Ray support being removed.
• Four new constants were added to the AcInsertUnits enum.
• The Transmittal Object Library documentation can be found in the product documentation and includes code samples. Change was made late in the AutoCAD 2016 release, so many people didn't know the change was made. (http://help.autodesk.com/cloudhelp/2017/ENU/AutoCAD-ActiveX/files/GUID-667D1179-3A76-437E-BBB7-12ADF3E614F7.htm)
• The CAD Standards Plug-in documentation is now part of the product documentation and includes code samples. Change was made late in the AutoCAD 2016 release, so many people didn't know the change was made. (http://help.autodesk.com/cloudhelp/2017/ENU/AutoCAD-ActiveX/files/GUID-F126AABA-FE9E-4E26-B51D-88D3E54512B5.htm)
• Documentation continues to be available online through the product help and offline as CHM files in the %ProgramFiles%\Common Files\Autodesk Shared\en-US\ directory. The files are named acad_aag.chm and acadauto.chm.

Managed .NET

• Updates were made to the Reference Guide to include the new classes, interfaces, and functions introduced for this release.
  • Palette themes were expanded.
  • DwgFiler and DxfFiler class now supports a minor version.
• Refer to the Managed Class Reference Guide (part of the ObjectARX SDK) and the What's New topic for a list of changes made to the API.
• API and documentation can be downloaded from the ADN or ObjectARX websites (http://www.objectarx.com/).
• Reference documentation is accessible via a CHM file in the ObjectARX SDK or as part of a Visual Studio integration installer (http://images.autodesk.com/adsk/files/objectarx_2017_documentation_vs2015.zip).
• Reference documentation can now be accessed using the Intellisense feature of the Visual Studio code editor window and the Object Browser. You must download either the NuGet packages for AutoCAD 2017, or the posted XML files and copy the files to the location of the DLL files that represent the Managed .NET API (http://images.autodesk.com/adsk/files/xml_intellisense_autocad_managed_dotnet_api_2017.zip). 
• Managed .NET Developer's Guide was previously only available via the product help system, but is now also available in a CHM file that can be integrated in the ObjectARX SDK. To download the CHM file, go to http://images.autodesk.com/adsk/files/managed_dotnet_dev_guide_2017.zip. Install the ObjectARX SDK, and then copy the two CHM files from the ZIP file into the Docs folder of the ObjectARX SDK installation location.
• Topic about the ResultBuffer has been added to the Developer's Guide. (http://help.autodesk.com/view/ACD/2017/ENU/?guid=GUID-A43BA3F1-513E-42E5-A21F-633FAF97B5C9)
• Topic was created that covers using keywords for prompts asking for a selection set. (http://help.autodesk.com/view/ACD/2017/ENU/?guid=GUID-94A4E3DE-0066-4D6A-8558-0252BE8CB85E)
• Topic added that covers Application Initialization and Load-Time Optimization. (http://help.autodesk.com/view/ACD/2017/ENU/?guid=GUID-FA3B4125-F7BD-4E89-969F-9DCC90AC6977)
• Documentation related to working with the CUI library was moved from the ObjectARX Developer's Guide to the Managed .NET Developer's Guide. (http://help.autodesk.com/view/ACD/2017/ENU/?guid=GUID-71554E76-8FD5-4853-82CD-3587764CBCAC)

ObjectARX

• Updates were made to include the new classes, interfaces, and functions introduced for this release.  The following provides an overview of the main changes to the API
  • Graphics system was modified and existing programs will need to be updated.
  • Class that provides information about the language and country name.
  • String class was expanded to include additional operators and functions.
• Refer to the ObjectARX Reference Guide and the What's New topic for a list of changes made to the API.
• API and documentation can be downloaded from the ADN or ObjectARX websites (http://www.objectarx.com/).
• Reference documentation is accessible via a CHM file in the ObjectARX SDK or as part of a Visual Studio integration installer (http://images.autodesk.com/adsk/files/objectarx_2017_documentation_vs2015.zip).

JavaScript

• No new or changed functions this release. V3 remains the latest version of the API. (https://df-prod.autocad360.com/jsapi/v3/docs/index.html)
• Getting Started Guide can be used to learn the basics of the JavaScript API. (https://df-prod.autocad360.com/jsapi/v3/GettingStart/index.html)

In future blog postings, I hope to cover some of the various developer documentation components that can be used to become more efficient with the AutoCAD APIs.

Sincerely,
  Lee