Overview of ObjectARX

1
In this chapter
I The ObjectARX Programming

ObjectARX , the AutoCAD Runtime Extension programming environment, includes C++ libraries that are the building blocks you can use to develop AutoCAD applications, extend AutoCAD classes and protocol, and create new commands that operate in the same manner as built-in AutoCAD commands. An ObjectARX application is a dynamic link library (DLL) that shares the address space of AutoCAD and makes direct function calls to AutoCAD. You can add new classes to the ObjectARX program environment and export them for use by other programs. You can also extend the ObjectARX protocol by adding functions at runtime to existing AutoCAD classes. This section provides an overview of the ObjectARX class libraries and gives information for getting started with ObjectARX. The ObjectARX Developers Guide assumes that you are familiar with C++, object-oriented programming, and AutoCAD.

Environment
I The ObjectARX

Documentation Set
I ObjectARX Logo Program I ObjectARX Class Libraries I Getting Started

The ObjectARX Programming Environment

The ObjectARX programming environment provides an object-oriented C++ application programming interface for developers to use, customize, and extend AutoCAD. The ObjectARX libraries comprise a versatile set of tools for application developers to take advantage of AutoCADs open architecture, providing direct access to AutoCAD database structures, the graphics system, and native command definition. In addition, these libraries are designed to work in conjunction with Visual LISP and other application programming interfaces so that developers can choose the programming tools best suited to their needs and experience. As a developer, you can use ObjectARX to accomplish the following tasks:
I I I I I I I

Access the AutoCAD database Interact with the AutoCAD editor Create user interfaces using the Microsoft Foundation Classes (MFC) Support the multiple document interface (MDI) Create custom classes Build complex applications Interact with other programming environments

The next sections take a brief look at these topics. They will be discussed in greater detail throughout the book.

Accessing the AutoCAD Database

An AutoCAD drawing is a collection of objects stored in a database. These objects represent not only graphical entities, but also internal constructs such as symbol tables and dictionaries. ObjectARX provides your application with access to these database structures. In addition, you can create new database objects for your specific application.

Interacting with the AutoCAD Editor

ObjectARX provides classes and member functions to interact with the AutoCAD editor. You can register commands with AutoCAD that will be treated as built-in commands. Your application can receive and respond to notification about a variety of events that occur within AutoCAD.

Chapter 1

Overview of ObjectARX

Creating User Interfaces with MFC

ObjectARX applications can be built with a dynamically linked MFC library that is shared with AutoCAD. You can use this library to create standard Microsoft Windows graphical user interfaces (GUIs).

Supporting MDI
With ObjectARX, you can create applications that will support the AutoCAD multiple document interface, and you can ensure that your applications will interact properly with other applications in the Microsoft Windows environment.

Creating Custom Classes

You can leverage the classes in the ObjectARX hierarchy to create your own custom classes. In addition, you can make use of the extensive graphics libraries of ObjectARX when creating custom classes.

Building Complex Applications

ObjectARX supports the development of complex applications, providing the following features:
I I I I I I

Notification Transaction management Deep cloning Reference editing Protocol extension Proxy object support

Interacting with Other Environments

ObjectARX applications can communicate with other programming interfaces, such as Visual LISP, ActiveX, and COM. In addition, ObjectARX applications can interact with the Internet, by associated URLs with entities, and by loading and saving drawing files from the World Wide Web (WWW).

The ObjectARX Programming Environment

The ObjectARX Documentation Set

You can access the ObjectARX online documentation from the \objectarx\docs directory. The following online documents are provided with ObjectARX:
I I I I

ObjectARX Reference. A programmers reference that provides detailed information on each class and function in the ObjectARX API. ObjectARX Developers Guide. The same content as the printed ObjectARX Developers Guide in online format. Whats New in ObjectARX. Lists the APIs that have been added to ObjectARX for AutoCAD 2002. ObjectARX Readme. Describes last-minute changes and additions to ObjectARX.

Using the ObjectARX Developers Guide

The ObjectARX Developers Guide is organized in seven parts: Part I: Using ObjectARX describes the fundamental concepts of ObjectARX. Part II: User Interfaces shows how to work with ObjectARX global functions and MFC to create and interact with user interfaces. Part III: Defining New Classes describes how to create custom classes in ObjectARX. Part IV: Specialized Topics examines topics of interest to more advanced users, such as proxy objects, notification, and protocol extension. Part V: Interacting with Other Environments discusses working with external programming environments such as COM and ActiveX Automation. Part VI: ObjectARX Libraries describes several of the ObjectARX libraries, including the ObjectDBX libraries and the graphics interface library.

ObjectARX Logo Program

Autodesk now offers a Built with ObjectARX logo program for AutoCAD applications that use ObjectARX. If you are creating AutoCAD products based on ObjectARX technology, you should look into this program. A guideline for making your application logo-compliant is available from VeriTest, the company that performs the certification process. To find out more about

Chapter 1

Overview of ObjectARX

this logo program or to get a copy of the guide, go online to http://www.veritest.com/autodesk/main(f).htm and follow the process listed there. Developers with products that meet with the Built with ObjectARX test criteria will be eligible to license and use ObjectARX branding on product packaging, collateral items, and Web sites, and to participate with Autodesk in related marketing initiatives.

NOTE The logo program guidelines contain information about how to register
your Registered Developer Symbol (RDS) with Autodesk, in addition to the other logo requirements.

ObjectARX Class Libraries

The ObjectARX environment consists of the following groups of classes and functions: AcRx AcEd AcDb AcGi AcGe Classes for binding an application and for runtime class registration and identification. Classes for registering native AutoCAD commands and for AutoCAD event notification. AutoCAD database classes. Graphics classes for rendering AutoCAD entities. Utility classes for common linear algebra and geometric objects.

The following table lists the libraries required to link ObjectARX applications. All ObjectARX applications must link with acad.lib and rxapi.lib. Other libraries may also be required, depending on the prefix of the ObjectARX classes and functions that you are using. Required ObjectARX libraries
Prefix AcRx AcEd AcDb Required Libraries acad.lib, rxapi.lib, acrx15.lib acad.lib, rxapi.lib, acedapi.lib, acrx15.lib acad.lib, rxapi.lib, acdb15.lib, acrx15.lib

ObjectARX Class Libraries

Required ObjectARX libraries (continued)

Prefix AcGi AcGe Required Libraries acad.lib, rxapi.lib, acgiapi.lib, acrx15.lib acad.lib, rxapi.lib, acge15.lib, acrx15.lib

The following sections take a closer look at each of the ObjectARX libraries. For more information about specific classes and member functions, see the ObjectARX Reference.

AcRx Library
The AcRx library provides system-level classes for DLL initialization and linking and for runtime class registration and identification. The base class of this library is AcRxObject, which provides the following facilities:
I I I I

Object runtime class identification and inheritance analysis Runtime addition of new protocol to an existing class (see chapter 19, Protocol Extension) Object equality and comparison testing Object copy

The AcRx library also provides a set of C++ macros to help you create new ObjectARX classes derived from AcRxObject (see chapter 11, Deriving a Custom ObjectARX Class).
AcRxDictionary is another important class in this library. A dictionary is a

mapping from a text string to another object. The AcRx library places its objects, classes, and service dictionaries in a global object dictionary, which is an instance of the AcRxDictionary class. Applications can add objects to this dictionary so that they are accessible to other applications.

Chapter 1

Overview of ObjectARX

The class hierarchy for the AcRx library is as follows:

AcRxClass AcRxDictionary AcRxDynamicLinker AcRxEvent AcEditor AcRxService AcRxKernal AcDbServices AcEdServices AcadAppInfo

Runtime Type Identification

Every subclass of AcRxObject has an associated class descriptor object (of type AcRxClass) that is used for runtime type identification. ObjectARX provides functions for testing whether an object is of a particular class or derived class, functions for determining whether two objects are of the same class, and functions for returning the class descriptor object for a given class. For more information on using AcRx classes, see chapter 3, ObjectARX Application Basics, chapter 11, Deriving a Custom ObjectARX Class, and chapter 19, Protocol Extension.

AcEd Library
The AcEd library provides classes for defining and registering new AutoCAD commands that operate in the same manner as built-in AutoCAD commands. The new commands you define are referred to as native commands because they reside in the same internal structure (the AcEdCommandStack) as built-in commands. The AcEd library also provides an editor reactor and a set of global functions for interacting with AutoCAD. An important class in this library is AcEditorReactor; it monitors the state of the AutoCAD editor and notifies the application when specified events occur, such as starting, ending, or canceling a command.

ObjectARX Class Libraries

The class hierarchy for the AcEd library is as follows:

For information on registering new AutoCAD commands using ObjectARX, see chapter 3, ObjectARX Application Basics. For an example of using an editor reactor, see chapter 15, Notification.

AcDb Library
The AcDb library provides the classes that compose the AutoCAD database. This database stores all the information for the graphical objects, called entities, that compose an AutoCAD drawing, as well as the nongraphical objects (for example, layers, linetypes, and text styles) that are also part of a drawing. You can query and manipulate existing instances of AutoCAD entities and objects with the AcDb library, and you can create new instances of database objects. The AutoCAD database contains these major elements:
I

A set of nine symbol tables that own uniquely named symbol table entry objects. These objects represent various commonly used AcDbDatabase objects and data members. A named object dictionary (of class AcDbDictionary), which provides the table of contents for an AutoCAD drawing. Initially, this table of contents contains the IDs of the four other dictionaries used by AutoCAD. Applications you develop, however, are free to add other objects to the dictionary. A fixed set of about 200 header variables, whose values are set by AutoCAD.

10

Chapter 1

Overview of ObjectARX

The class hierarchy for the AcDb library is as follows:

AcDbDictionary AcDbDictionaryWithDefault AcDbFilter AcDbLayerFilter AcDbSpatialFilter AcDbGroup AcDbIDBuffer AcDbIndex AcDbLayerIndex AcDbSpatialIndex AcDbLongTransaction AcDbMlineStyle AcDbPlaceholder AcDbPlotSettings AcDbLayout AcDbProxyObject AcDbXrecord AcDbEntity

AcDbSymbolTable AcDbAbstractViewTable AcDbViewportTable AcDbViewTable AcDbBlockTable AcDbDimStyleTable AcDbFontTable AcDbLayerTable AcDbLinetypeTable AcDbRegAppTable AcDbTextStyleTable AcDbUCSTable

AcDbSymbolTableRecord AcDbAbstractViewTableRecord AcDbViewportTableRecord AcDbViewTableRecord AcDbBlockTableRecord AcDbDimStyleTableRecord AcDbFontTableRecord AcDbLayerTableRecord AcDbLinetypeTableRecord AcDbRegAppTableRecord AcDbTextStyleTableRecord AcDbUCSTableRecord

AcDbRasterImageDef AcDbRasterImageDefReactor AcDbRasterVariables

For more information on the AcDb library, see chapter 2, Database Primer, chapter 4, Database Operations, chapter 5, Database Objects, chapter 6, Entities, and chapter 7, Container Objects. For information on deriving new classes from AcDbObject and AcDbEntity, see chapter 12, Deriving from AcDbObject and chapter 13, Deriving from AcDbEntity.

AcGi Library
The AcGi library provides the graphics interface used for drawing AutoCAD entities. This library is used by the AcDbEntity member functions worldDraw(), viewportDraw(), and saveAs(), all part of the standard entity protocol. The worldDraw() function must be defined by all custom entity classes. The AcGiWorldDraw object provides an API through which AcDbEntity::worldDraw() can produce its graphical representation in all viewports simultaneously. Similarly, the AcGiViewportDraw object provides an API through which the AcDbEntity::viewportDraw() function can produce different graphical representations for each viewport.

ObjectARX Class Libraries

11

The class hierarchy for the AcGi library is as follows:

AcGiCommonDraw AcGiWorldDraw AcGiWorldDraw AcGiContext AcGiEdgeData AcGiFaceData AcGiGeometry AcGiViewportGeometry AcGiWorldGeometry AcGiLinetypeEngine AcGiSubEntityTraits AcGiDrawableTraits AcGiTextStyle AcGiVertexData AcGiViewport AcGiDrawable AcGiGlyph

For more information on using AcGi classes, see chapter 13, Deriving from AcDbEntity.

AcGe Library
The AcGe library is used by the AcDb library and provides utility classes such as vectors and matrices that are used to perform common 2D and 3D geometric operations. It also provides basic geometric objects such as points, curves, and surfaces. The AcGe library consists of two major subsets: classes for 2D geometry and classes for 3D geometry. The major abstract base classes are AcGeEntity2d and AcGeEntity3d. Several basic classes not derived from any other class include AcGePoint2d, AcGeVector2d, and AcGeMatrix2d (shown at the beginning of the class hierarchy). These basic classes can be used to perform many types of common operations, such as adding a vector to a point, computing the dot or cross product of two vectors, and computing the product of two matrices. The higher-level classes of this library are implemented using these basic classes.

12

Chapter 1

Overview of ObjectARX

The class hierarchy for the AcGe library is as follows:

AcGeBoundBlock2d AcGeClipBoundary2d AcGeCurve2d AcGeCircArc2d AcGeCompositeCurve2d AcGeEllipArc2d AcGeExternalCurve2d AcGeLinearEnt2d AcGeLine2d AcGeLineSeg2d AcGeRay2d AcGeOffsetCurve2d AcGeSplineEnt2d AcGeCubicSplineCurve2d AcGeNurbCurve2d AcGePolyline2d AcGeCurveCurveInt2d AcGePointEnt2d AcGePointOnCurve2d AcGePosition2d AcGeCurveBoundary AcGe AcGeContext AcGeDwgIO AcGeDxfIO AcGeFileIO AcGeFiler AcGeInterval AcGeKnotVector AcGeLibVersion AcGeMatrix2d AcGeMatrix3d AcGePoint2d AcAxPoint2d AcGePoint3d AcAxPoint3d AcGeScale2d AcGeScale3d AcGeTol AcGeVector2d AcGeVector3d

AcGeBoundBlock3d AcGeCurve3d AcGeCircArc3de AcGeCompositeCurve3d AcGeEllipArc3e AcGeExternalCurve3d AcGeLinearEnt3d AcGeLine3d AcGeLineSeg3d AcGeRay3d AcGeMatrix3d AcGeOffsetCurve3d AcGeSplineEnt3d AcGeCubicSplineCurve3d AcGeNurbCurve3d AcGePolyline3d AcGeAugPolyline3d AcGeCurveCurveInt3d AcGeCurveSurfInt AcGePointEnt3d AcGePointOnCurve3d AcGePointOnSurface AcGePosition3d AcGeSurfSurfInt AcGeSurface AcGeCone AcGeCylinder AcGeExternalBoundedSurface AcGeExternalSurface AcGeNurbSurface AcGeOffsetSurface AcGePlanarEnt AcGeBoundedPlanet AcGePlane AcGeSphere AcGeTorus

The AcGe library provides several different coordinate systems. For more information, see chapter 30, Using the Geometry Library. The sample programs in this documentation illustrate numerous common uses of AcGe classes.

ObjectARX Class Libraries

13

Getting Started
The following topics discuss the system requirements for ObjectARX and provide installation instructions.

System Requirements
Developing applications with ObjectARX requires the following software and hardware:
I I I I

Windows NT 4.0 Microsoft Visual C++ 32bit Edition Release 6.0 Pentium PC running at 90MHz or better, with 32MB RAM or more 800 x 600 SVGA display or better

Installing ObjectARX
When you install ObjectARX, a setup program guides you through the process. To install ObjectARX 1 Insert the CD into the CD-ROM drive. 2 If you are running Windows NT 4.0 with AutoPlay, follow the on-screen instructions. 3 If you have turned off AutoPlay in Windows NT 4.0, from the Start menu on the taskbar, choose Run, designate the CD-ROM drive, enter the path name, and then enter setup.

ObjectARX Directory Tree

The default installation for ObjectARX software creates the base directory c:\objectarx. The nine main subdirectories under the objectarx directory are described here. arxlabs The arxlabs directory consists of a set of subdirectories, each containing a lab (tutorial) that demonstrates implementation of one aspect of the ObjectARX API. Each subdirectory includes instructions for the lab, a source code file with key pieces missing that are to be filled in by the user according to the instructional comments in the code, and a solved subdirectory containing the completed source code file for the lab.

14

Chapter 1

Overview of ObjectARX

classmap docs

The classmap directory contains an AutoCAD drawing illustrating the ObjectARX class hierarchy. The docs directory contains online help files for ObjectARX developers, including the ObjectARX Developers Guide, the ObjectARX Reference, Whats New in ObjectARX, and the ObjectARX Readme file. The docsamps directory contains subdirectories for each of the programs from which examples were extracted for the ObjectARX Developers Guide. Each subdirectory contains the full set of source code for the application and an explanatory Readme file. The inc directory contains the ObjectARX header files. The lib directory contains the ObjectARX library files. The redistrib directory contains a set of DLLs, some of which may be required for an ObjectARX application to run. Developers should copy the DLLs that they need for application development to a directory in the AutoCAD search path, and package the necessary DLLs with their ObjectARX applications for distribution. The samples directory includes subdirectories containing examples of ObjectARX applications. These subdirectories include source code and Readme files. The most significant set of sample ObjectARX applications is in the polysamp subdirectory. The utils directory contains subdirectories for applications that are extensions to ObjectARX, including brep for boundary representation. Each application directory includes inc, lib, and sample subdirectories.

docsamps

inc lib redistrib

samples

utils

15