CP4164-L: ObjectARX® for Beginners: An Introduction
ObjectARX® for Beginners: An Introduction
Lee Ambrosius – Autodesk, Inc.
CP4164-L ObjectARX is the premier application programming interface (API) that AutoCAD®, AutoCAD for Mac®, and the AutoCAD-based verticals support. If you need access to APIs that are not exposed with programming languages such as AutoLISP® or if you have a need for building applications on Windows® and Mac OS X, ObjectARX may be the best API for you. This hands-on lab provides a basic understanding of ObjectARX and teaches you how to create and load an ARX application into AutoCAD. You should have an understanding of C++ if you want to get the most out of ObjectARX, but this class is designed to give you an idea of what ObjectARX is and how to get started. Attendees should have some prior AutoCAD programming experience with languages such as AutoLISP or VB.NET.
Learning Objectives
At the end of this class, you will be able to:
· Get started using ObjectARX
· Create a project in Visual Studio®
· Create a command and work with objects in a drawing
· Display messages to the user and request user input
· Load an ObjectARX application into AutoCAD
About the Speaker
Lee is one of the technical writers on the AutoCAD team at Autodesk and has been an AutoCAD® user for over 15 years in the fields of architecture and facilities management. He has been teaching AutoCAD users for over a decade at both the corporate and college level. He is best known for his expertise in programming and customizing AutoCAD-based products, and has 10+ years of experience programming with AutoLISP®, VBA, Microsoft® .NET, and ObjectARX®. Lee has written articles for AUGI® publications and white papers for Autodesk on customization. He is the author of several books on AutoCAD and has been an active technical editor for AutoCAD books in the Bible and For Dummies series.
Twitter: http://twitter.com/leeambrosius
Email:
Blog: http://hyperpics.blogs.com
Table of Contents
Contents
1 Introduction 3
2 What You Need to Get Started 4
3 Access ObjectARX Libraries 5
4 Create a New Project 7
5 Compile and Load a Project 8
6 Define a New Command 9
7 Access AutoCAD, Objects, System Variables, and Commands 10
8 Request User Input 14
9 Debugging a Project 17
10 Build a Project for Release 18
11 Where to Get More Information 19
12 Exercises 20
Appendixes 44
1 Introduction
ObjectARX is a software development library that allows you to communicate directly with AutoCAD, and is not a programming language like AutoLISP. ObjectARX requires you to have an understanding of the C++ programming language and Microsoft Visual C++ or Objective C. Based on your target release of AutoCAD, you will need a specific release of Microsoft Visual C++ or Objective C installed.
For AutoCAD 2010 through 2012, you will need to have access to Microsoft Visual C++ 2008 which is part of Microsoft Visual Studio 2008. Earlier releases of AutoCAD will require access to Microsoft Visual Studio 2005 or earlier.
Microsoft Visual Studio comes in two main editions: full and express. The full editions must be purchased after a trial period, while the Express editions are free and just need to be registered. Autodesk does not officially support Microsoft Visual C++ Express with ObjectARX, but it does work with what is demonstrated in this lab. Microsoft Visual C++ Express is also limited to compiling to 32-bit applications, unless you install the proper Windows SDK.
For information on Microsoft Visual Studio, see:
· www.microsoft.com/vs
· www.microsoft.com/express
Unlike AutoLISP, ObjectARX applications must be compiled prior to them being loaded into AutoCAD which allows them to be more efficient than AutoLISP which is an interpreted programming language. ObjectARX does contain a vast collection of classes that define functions and data types which represent most of the features of AutoCAD. These applications can be used to retrieve information about an open drawing, create/modify drawing objects, read/write information to or from a file, and much more.
This handout only scratches the surface of what ObjectARX has to offer, and is not setup to teach you how to be proficient with C++. The following table lists some of the syntax you will encounter in this lab.
Syntax / Description and Usage of Syntax// / Demotes a single line of code that should not be executed.
// Creates new line
/* … */ / Denotes a series of lines that should not be executed.
/* Defines a new command.
The new command creates a circle and a line. */
; / Denotes the end of a statement.
int iCnt = 0;
#include / Imports classes and functions for use in the current code module.
#include "arxHeaders.h"
retType funcName (vars …)
{
…
} / Defines a function. retType specifies the type of data that the function returns. When a function returns a value, the return statement must be used.
static void Greetings()
{
acutPrintf(_T("\nHello AU2011!"));
}
int addValues (int val1, int val2)
{
return val1 + val2;
}
After an ObjectARX project has been compiled, it can be loaded into AutoCAD with the Load/Unload Applications dialog box (APPLOAD command) or the AutoLISP arxload function. ObjectARX applications can be unloaded using the APPLOAD command or the AutoLISP arxunload function.
2 What You Need to Get Started
Before you start working with C++ and ObjectARX, you should obtain the following:
· ObjectARX Software Development Kit (SDK) – The ObjectARX SDK contains code samples, ObjectARX library files, and the ObjectARX documentation. - http://www.autodesk.com/objectarx, click License & Download and follow the onscreen instructions.
· ObjectARX 2012 Wizard – The ObjectARX 2012 Wizard helps to setup a default project that you can use to get started with. - http://www.autodesk.com/developautocad, click ObjectARX 2012 Wizard and save the file to your local drive. Extract the files and run ArxWizards.msi.
· Development Environment – Microsoft Visual Studio 2008 is what you will need to develop applications for AutoCAD 2010 through AutoCAD 2012. If you are working with AutoCAD 2007 through AutoCAD 2009, you will need Microsoft Visual Studio .NET 2005. You can use Microsoft Visual Studio 2010 as your development environment, but will need Microsoft Visual Studio 2008 to compile your projects.
If you do not have Microsoft Visual Studio 2008 available, you can download Microsoft Visual C++ 2008 Express. While it is possible to use Microsoft Visual C++ 2008 Express, there are limitations with MFC and no 64-bit support. Installing Microsoft Visual C++ 2010 Express does provide for a better development environment and the ability to compile 64-bit applications, but you need to install the Windows SDK for use with Microsoft Visual C++ 2008 in addition to Microsoft Visual C++ 2008 Express.
A1 Download and Install the ObjectARX SDK
See A1 at the end of the handouts for instructions on how to download and install the ObjectARX SDK.
A2 Download and Install the ObjectARX Wizard
See A2 at the end of the handouts for instructions on how to download and install the ObjectARX Wizard.
A3 Download Links for Visual C++ Express and Windows SDKs
See A3 at the end of the handouts for the locations that Visual C++ Express and the Windows SDKs can be downloaded from.
3 Access ObjectARX Libraries
ObjectARX is made up of a number of libraries that help to group related classes to make it easier to locate which features you want to work with. Each of the classes located in a library starts with the same four letters. For example, AcDb denotes classes that are related to the drawing database.
The common libraries that are part of ObjectARX are listed in the following table.
Library Prefix / DescriptionAcAp / Application level libraries used to access open documents and work with transactions.
AcCm / Color method library used to work with True colors and color books.
AcDb / Graphical and non-graphical object definitions stored in a drawing, such as a block insert and block definition.
AcEd / Editor services used to register commands and work with the drawing window.
AcGe / Geometry helper library that allows you to represent points, vectors, boundaries, and in memory objects.
AcPl / Plot engine library used to output a drawing to a hardcopy or an electronic file.
The ObjectARX libraries are available after you install the ObjectARX SDK. By default, the ObjectARX SDK is installed to the root of your local drive. For example, the ObjectARX 2012 SDK is installed to c:\ObjectARX 2012.
The files that you will need to reference are present in a few different folders based on the target operating system. You will be working with the files in the inc, inc-win32, inc-x64, lib-win32, and lib-x64 folders. The inc folder is the most important as it contains the header files that reflect which classes are exposed and available for you to use in your ObjectARX programs.
The following is a snipet from the dbents.h header file that shows the AcDbLine class which is used to represent a Line object in a drawing.
class AcDbLine: public AcDbCurve
{
public:
AcDbLine();
AcDbLine(const AcGePoint3d& start, const AcGePoint3d& end);
~AcDbLine();
ACDB_DECLARE_MEMBERS(AcDbLine);
DBCURVE_METHODS
Acad::ErrorStatus getOffsetCurvesGivenPlaneNormal(
const AcGeVector3d& normal, double offsetDist,
AcDbVoidPtrArray& offsetCurves) const;
AcGePoint3d startPoint() const;
Acad::ErrorStatus setStartPoint(const AcGePoint3d&);
AcGePoint3d endPoint() const;
Acad::ErrorStatus setEndPoint(const AcGePoint3d&);
double thickness() const;
Acad::ErrorStatus setThickness(double);
AcGeVector3d normal() const;
Acad::ErrorStatus setNormal(const AcGeVector3d&);
protected:
virtual Acad::ErrorStatus subGetClassID(CLSID* pClsid) const;
};
Tip: The arxheaders.h header file includes imports for many of the common classes that you will be using as part of your ObjectARX programs.
Once the libraries are installed, you must specify the location of the ObjectARX libraries in your Microsoft Visual C++ project and also import the classes you want to use with the #include statement.
4 Create a New Project
After Microsoft Visual C++, the ObjectARX SDK, and the Windows SDK (if needed) have been installed, you are ready to create a new ObjectARX project. There are two ways to create a new project: from scratch or using the ObjectARX Wizard.
When creating a project from scratch, you use the Win32 project under the Visual C++ templates. Once the project is created, you then modify the project’s properties so Visual C++ understands where the ObjectARX libraries are located and the output that the project should generate when compiled.
The ObjectARX Wizard is a separate download from the ObjectARX SDK, and cannot be used with Visual C++ Express.
Using the ObjectARX Wizard does make it easier to create a new project, but it does add some extra framework that you might not use for your ObjectARX project. The exercises in this handout do not utilize the ObjectARX Wizard to keep the project as simple as possible. No matter if you create a project from scratch or use the ObjectARX Wizard, you still need to set many of the project’s properties so it can be compiled and loaded into AutoCAD.
Each ObjectARX project must include an acrxEntryPoint function which allows you to perform tasks when the program is loaded or unloaded. The acrxEntryPoint function is commonly used to add new commands and remove command groups that are defined in the ObjectARX program. The following is an example of an acrxEntryPoint:
AcRx::AppRetCode acrxEntryPoint(AcRx::AppMsgCode msg, void* appId)
{
switch (msg) {
case AcRx::kInitAppMsg:
acrxDynamicLinker->unlockApplication(appId);
acrxDynamicLinker->registerAppMDIAware(appId);
// Add tasks here that should happen when loading the ARX file
break;
case AcRx::kUnloadAppMsg:
// Add tasks here that should happen when unloading the ARX file
break;
}
return AcRx::kRetOK;
}
E1 Create a New Project from Scratch
See Exercises at the end of the handouts.
5 Compile and Load a Project
ObjectARX programs must be compiled before they can be loaded into AutoCAD. The Build menu in Microsoft Visual C++ (or Debug menu in Microsoft Visual C++ Express) allows you to compile the project into a DLL (Dynamic Linked Library) file that can be loaded into AutoCAD. If you configured the project correctly, the compiled file should have the extension of .arx. ObjectARX programs can be compiled for debugging or release.
ObjectARX programs that are compiled for debugging can only be ran on a computer that has the Microsoft Visual C++ development environment installed. This is because Windows does not ship with the debug DLLs that are required to run a debugging project. Once a project has been debugged, you compile a release of the project which can be used on other workstations.
When you compile a project, the Output window displays the location that the compiled output is stored. The Output window also displays any errors or warnings that are generated while the program is being compiled. The following is an example of a failed compiling of a project:
1>------Build started: Project: ArxProject2, Configuration: Debug Win32 ------
1>Build started 11/14/2011 10:11:29 PM.
1>InitializeBuildStatus:
1> Touching "Win32\AU2011App.unsuccessfulbuild".
1>ClCompile:
1> StdAfx.cpp
1>c:\dataset\CP4164L\AU2011 – x86\AU2011\AU2011.cpp(5): fatal error C1083: Cannot open include file: 'arxHeaders.h': No such file or directory
1>
1>Build FAILED.
1>
1>Time Elapsed 00:00:02.28
======Build: 0 succeeded, 1 failed, 0 up-to-date, 0 skipped ======
An ObjectARX file can be loaded into AutoCAD using a number of methods. You can use the following methods to load an ObjectARX file:
· APPLOAD command
· arxload AutoLISP function
· Drag and drop an ARX file into the drawing window (Windows only)
· /ld command line switch used for shortcut icons (Windows only)
E2 Compile and Load an ObjectARX Project
See Exercises at the end of the handouts.
6 Define a New Command
Commands are the primary way users access the functionality that is exposed by a loaded ObjectARX program. You expose commands using the acedRegCmds or ACED_ARXCOMMAND_ENTRY_AUTO macro. If you create a project using the ObjectARX Wizard, you can use the ObjectARX Commands option on the ObjectARX Addin toolbar to create a new command which adds a new ACED_ARXCOMMAND_ENTRY_AUTO macro entry to the project.
No matter which macro you use, you must supply the following: