3

Overview of ObjectARX

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 Developer’s Guide

assumes that you are familiar with C++, object-oriented

programming, and AutoCAD.

In this chapter

� The ObjectARX Programming Environment

� The ObjectARX Documentation Set

� ObjectARX Logo Program

� ObjectARX Class Libraries

� Getting Started

1

4 | Chapter 1 Overview of ObjectARX

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 AutoCAD’s 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:

� 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.

The ObjectARX Programming Environment | 5

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:

� 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).

6 | Chapter 1 Overview of ObjectARX

The ObjectARX Documentation Set

You can access the ObjectARX online documentation from the \objectarx\docs directory.

The following online documents are provided with ObjectARX:

� ObjectARX Reference. A programmer’s reference that provides detailed information on each class and function in the ObjectARX API.

� ObjectARX Developer’s Guide. The same content as the printed ObjectARX Developer’s Guide in online format.

� What’s 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 Developer’s Guide

The ObjectARX Developer’s 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 guide-line for making your application logo-compliant is available from VeriTest, the company that performs the certification process. To find out more about

ObjectARX Class Libraries | 7

this logo program or to get a copy of the guide, go online to http://www.ver-itest.com/autodesk/main(f).htm and follow the process listed there. Devel-opers 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 Classes for binding an application and for runtime class registration and identification.

AcEd Classes for registering native AutoCAD commands and for AutoCAD event notification.

AcDb AutoCAD database classes.

AcGi Graphics classes for rendering AutoCAD entities.

AcGe Utility classes for common linear algebra and geometric objects.

The following table lists the libraries required to link ObjectARX applica-tions. 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 Required Libraries

AcRx acad.lib, rxapi.lib, acrx15.lib

AcEd acad.lib, rxapi.lib, acedapi.lib, acrx15.lib

AcDb acad.lib, rxapi.lib, acdb15.lib, acrx15.lib

8 | Chapter 1 Overview of ObjectARX

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:

� 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.

AcGi acad.lib, rxapi.lib, acgiapi.lib, acrx15.lib

AcGe acad.lib, rxapi.lib, acge15.lib, acrx15.lib

Required ObjectARX libraries (continued)

Prefix Required Libraries

ObjectARX Class Libraries | 9

The class hierarchy for the AcRx library is as follows:

Runtime Type IdentificationEvery 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 com-mands. 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.

AcRxClassAcRxDictionaryAcRxDynamicLinkerAcRxEvent

AcEditorAcRxService

AcRxKernalAcDbServicesAcEdServices

AcadAppInfo

10 | Chapter 1 Overview of ObjectARX

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:

� 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.

ObjectARX Class Libraries | 11

The class hierarchy for the AcDb library is as follows:

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.

AcDbDictionaryAcDbDictionaryWithDefault

AcDbFilterAcDbLayerFilterAcDbSpatialFilter

AcDbGroupAcDbIDBufferAcDbIndex

AcDbLayerIndexAcDbSpatialIndex

AcDbLongTransactionAcDbMlineStyleAcDbPlaceholderAcDbPlotSettings

AcDbLayout

AcDbProxyObjectAcDbXrecordAcDbEntity

AcDbSymbolTableAcDbAbstractViewTable

AcDbViewportTableAcDbViewTable

AcDbBlockTableAcDbDimStyleTableAcDbFontTableAcDbLayerTableAcDbLinetypeTableAcDbRegAppTableAcDbTextStyleTableAcDbUCSTable

AcDbRasterImageDefAcDbRasterImageDefReactorAcDbRasterVariables

AcDbSymbolTableRecordAcDbAbstractViewTableRecord

AcDbViewportTableRecordAcDbViewTableRecord

AcDbBlockTableRecordAcDbDimStyleTableRecordAcDbFontTableRecordAcDbLayerTableRecordAcDbLinetypeTableRecordAcDbRegAppTableRecordAcDbTextStyleTableRecordAcDbUCSTableRecord

12 | Chapter 1 Overview of ObjectARX

The class hierarchy for the AcGi library is as follows:

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 begin-ning 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.

AcGiCommonDrawAcGiWorldDrawAcGiWorldDraw

AcGiContextAcGiEdgeDataAcGiFaceDataAcGiGeometry

AcGiViewportGeometryAcGiWorldGeometry

AcGiLinetypeEngineAcGiSubEntityTraits

AcGiDrawableTraitsAcGiTextStyleAcGiVertexDataAcGiViewportAcGiDrawable

AcGiGlyph

ObjectARX Class Libraries | 13

The class hierarchy for the AcGe library is as follows:

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.

AcGeBoundBlock2dAcGeClipBoundary2dAcGeCurve2d

AcGeCircArc2dAcGeCompositeCurve2dAcGeEllipArc2dAcGeExternalCurve2dAcGeLinearEnt2d

AcGeLine2dAcGeLineSeg2dAcGeRay2d

AcGeOffsetCurve2dAcGeSplineEnt2d

AcGeCubicSplineCurve2dAcGeNurbCurve2dAcGePolyline2d

AcGeCurveCurveInt2dAcGePointEnt2d

AcGePointOnCurve2dAcGePosition2d

AcGeCurveBoundaryAcGeAcGeContextAcGeDwgIOAcGeDxfIOAcGeFileIOAcGeFilerAcGeIntervalAcGeKnotVectorAcGeLibVersionAcGeMatrix2dAcGeMatrix3dAcGePoint2d

AcAxPoint2dAcGePoint3d

AcAxPoint3dAcGeScale2dAcGeScale3dAcGeTolAcGeVector2dAcGeVector3d

AcGeBoundBlock3dAcGeCurve3d

AcGeCircArc3deAcGeCompositeCurve3dAcGeEllipArc3eAcGeExternalCurve3dAcGeLinearEnt3d

AcGeLine3dAcGeLineSeg3dAcGeRay3dAcGeMatrix3d

AcGeOffsetCurve3dAcGeSplineEnt3d

AcGeCubicSplineCurve3dAcGeNurbCurve3dAcGePolyline3d

AcGeAugPolyline3dAcGeCurveCurveInt3dAcGeCurveSurfIntAcGePointEnt3d

AcGePointOnCurve3dAcGePointOnSurfaceAcGePosition3d

AcGeSurfSurfIntAcGeSurface

AcGeConeAcGeCylinderAcGeExternalBoundedSurfaceAcGeExternalSurfaceAcGeNurbSurfaceAcGeOffsetSurfaceAcGePlanarEnt

AcGeBoundedPlanetAcGePlane

AcGeSphereAcGeTorus

14 | Chapter 1 Overview of ObjectARX

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:

� 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 ObjectARXWhen 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 TreeThe 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.

15

classmap The classmap directory contains an AutoCAD drawing illustrating the ObjectARX class hierarchy.

docs The docs directory contains online help files for ObjectARX developers, including the ObjectARX Developer’s Guide, the ObjectARX Reference, What’s New in ObjectARX, and the ObjectARX Readme file.

docsamps The docsamps directory contains subdirectories for each of the programs from which examples were extracted for the ObjectARX Developer’s Guide. Each subdirectory contains the full set of source code for the application and an explanatory Readme file.

inc The inc directory contains the ObjectARX header files.

lib The lib directory contains the ObjectARX library files.

redistrib 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.

samples 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.

utils 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.