You are on page 1of 135

ObjectARX 2010


Autodesk Developer Technical Services

Getting Acquainted
Instructor: Marat Mirgaleev (
Developer Consultant ADN  Mechanics Engineering + Computer Science  20 years in software development (CAD, 3D, Databases)  C++, C#, Delphi, Assembler; Object-Oriented Analysis and Design )

Who Are You?


Your work, your software AutoCAD customization experience Your company What are you expecting from this training?

2008 Autodesk

Autodesk Developer Network (ADN)


Access to almost all Autodesk software and SDKs

Including early access to Beta software

Members-only website with 1000s of technical articles  Unlimited technical support  Product direction through conferences  Marketing benefits

Exposure on Promotional opportunities Based on user level

1 to 3 free API training classes
2008 Autodesk

Developer Technical Services

Worldwide Workgroup

Over 25 Specialists World Wide Virtually 24 hour support, 5 days a week

Americas Team

CA, WA, So Paulo

European Team

Switzerland, United Kingdom, France, Czech Republic, Russia

APac Team

China, Japan, India

2008 Autodesk

Getting Support

Provides access to

On-line knowledgebase Request submission Newsgroups 1-3 day turnaround Callbacks as needed

Requests are logged automatically


Answers to frequently asked questions are posted in our online knowledge base

2008 Autodesk

Course Objective
It is to understand:

The fundamentals of ObjectARX and AutoCAD .NET How to teach yourself AutoCAD APIs Where to get help with afterwards

What it is not:

Teach you C++, C#, VB, .NET Give you complete of coverage of all API functions

2008 Autodesk

Class Agenda
Lectures with Labs  Slides give an abstract overview  Labs and my comments give the practical experience Lectures:  Overview of APIs  AutoCAD: Hello.arx Step 1 + 2  ObjectDBX: Structure Step 3 + 4  ObjectDBX: Extend it! Step 5 + 6  AutoCAD: Multi-Document Environment  Notification System Step 7


2008 Autodesk

Class Schedule
Time 10:00 - 5:00  Lunch 12:00 - 1:00 Day 1  Overview of APIs  AutoCAD: Hello.arx Day 2  ObjectDBX: Structure  ObjectDBX: Extend it! Day 3  AutoCAD: MDE Environment  Notification System Day 3, Day 4  AutoCAD .NET
2008 Autodesk

Training Material
C:\AutoCAD API Training

ObjectARX*.pptx AutoCAD.NET*.pptx

- this presentation - .NET API presentation

objectarx_2010_win_64_and_32bit.exe - ObjectARX installation file AutoCAD 2010.Net

- ObjectARX labs - .NET labs - ObjectARX snoop tool

2008 Autodesk

Agenda Overview of APIs AutoCAD: Hello.arx ObjectDBX: Structure ObjectDBX: Extend it! AutoCAD: Multi-Document Environment Notification System

2008 Autodesk

API Overview
A general look at APIs

Types of API Client/Server interaction Client code

AutoCADs APIs and IDEs


Implementation Comparison

2008 Autodesk

What is an API?
A contract, it is about responsibilities  Both sides are (or may be) required to

Implement service entry points Call services properly

Code implementing API can be packaged as  Source code modules (.h/.cpp in C++)  Binary

Static library DLL EXE

2008 Autodesk

API Packaging
Client EXE, DLL, script, etc.

ATL templates





Static MFC Library

Win 32 API DLLs

1. Source code 3. DLL

2008 Autodesk

2. Static library 4. EXE

Client/Server Interaction
In process

Client/server is in the same process


Client/server is on the same machine


Client/server is on the same network

2008 Autodesk

The Plug-In Architecture

API is implemented by an exe Client is implemented as a dll




2008 Autodesk

Forms of Client Code

Interpreted code

Source script AutoLISP in the past Pre-processed, semi interpreted code Compiled Visual LISP Compiled into IL Processor instructions ObjectARX

Packaged code (p-code)



Compiled code


2008 Autodesk

AutoCAD APIs and IDEs

Application Programming Interfaces

ObjectARX .NET Managed API COM Automation (VB, Java, Delphi, etc.) AutoLISP

Integrated Development Environments in AutoCAD


Visual LISP Visual Basic, Applications Edition (VBA)

(Visual Studio outside AutoCAD)

2008 Autodesk

API Implementation I
Input driver Input acquisition AutoCAD PlotHDI 2D graphics cache (WHIP!) Plotter driver Display driver


3D graphics cache


 ObjectARX SDK (free,  RealDWG (licensed,  Plot DDK (licensed,  HEIDI DDK (licensed,  Wintab API (free)
2008 Autodesk


API Implementation II
.NET Lisp script VBA script COM Client
(VB, Java, Delphi)

Acdbmgd.dll Acmgd.dll





2008 Autodesk







S.0.58 API Performance Old API Performance Comparison

100.00 90.00 80.00 70.00


60.00 50.00 40.00 30.00 20.00 10.00 0.00


Total Create 1000 2dPolylines Add XData to 1000 Entities Update 1000 Circles Create 1000 lines COM (VB) COM (VBA) Create 1000 Circles LI SP ObjectARX

Create 1

Create 1

Update 1

AutoCAD's APIs
2008 Autodesk

Add XDa Total

Create 1

How to Store Your Data in AutoCAD

Different Programming Techniques
Data Container Performance Chart
400 350 300 250 200 150 100 50 0 Xrecord Custom Object Xdata

Time in seconds


2008 Autodesk

How to Store Your Data in AutoCAD

Different Programming Techniques
Data Container Performance Chart
Time in seconds

120000 100000 80000 60000 40000 20000 0 Xrecord Xdata ObjectARX .NET LISP VBA VB

2008 Autodesk

How to Store Your Data in AutoCAD

Different Programming Techniques
Data Container Performance Chart
Time in seconds

4000 3000 2000 1000 0 Xrecord Custom Object ObjectARX .NET VBA LISP

2008 Autodesk

API Comparison Summary

Speed  ObjectARX, .NET is close second, VBA also though obsolete Coverage  ObjectARX, .NET everything except custom objects Ease of use  .NET, VBA Learning curve  .NET, VBA

2008 Autodesk

Agenda Overview of APIs AutoCAD: Hello.arx ObjectDBX: Structure ObjectDBX: Extend it! AutoCAD: Multi-Document Environment Notification System

2008 Autodesk

AutoCAD: Hello.arx

What it is Where to get it Structure Loading Memory management Command mechanism Prompting for user input

ObjectARX applications

Creating commands

ObjectARX Wizards

2008 Autodesk

What is ObjectARX?
AutoCAD Runtime eXtension

A DLL plug-in model A set of Object Oriented C++ libraries A framework

A framework?

More than just a toolkit Specialized objects can be plugged back into the system

Custom entities Reactors ...

2008 Autodesk

What can I do with ObjectARX?

Modify and extend the drawing database

Create/modify/erase objects Create new types of objects

Modify AutoCADs user interface


Commands Toolbars/dialogs Properties Window Design Center Display system

Monitor/Modify AutoCADs standard behavior


Event notifications Input point acquisition

2008 Autodesk

Getting the ObjectARX SDK

Download - Free
On Autodesk public web site Developer Center - ObjectARX

Or Search for ObjectARX on

2008 Autodesk

Binary compatibility
ObjectARX 2010

AutoCAD 2010 Binary incompatible with earlier releases

ObjectARX 2009

AutoCAD 2009

ObjectARX 2008

AutoCAD 2008 and 2009

ObjectARX 2007

AutoCAD 2007, 2008 and 2009 Binary incompatible with earlier releases

ObjectARX 2006, 2005, 2004

Not supported, as well as AutoCAD versions older than 2007

2008 Autodesk

Development Environment
For ObjectARX development

Microsoft Visual Studio 2008 SP1 only for AutoCAD 2010 VS 2005 SP1 only for AutoCAD 2009 VS 2005 RTM for AutoCAD 2007, 2008, 2009 VS 2008 VS 2005 RTM or SP1

For .NET development:


ObjectARX 2007, 2008, 2009 or 2010 Microsoft Windows 2000 SP2 or better

2008 Autodesk

ObjectARX SDK Contents

What comes with the SDK

Libraries and Header Files Documentation Samples Utilities

2008 Autodesk

Main Libraries - I
AcRx Object and Class Management (rxapi.lib) AcEd AutoCAD Editor Facilities (acedapi.lib) AcDb AutoCAD Database (acdb18.lib) AcGi AutoCAD Graphics Interface (acgiapi.lib) AcGe AutoCAD Geometry Library (acge18.lib) 32- and 64-bit versions:
\ObjectARX 2010\lib-win32 and \ObjectARX 2010\lib-x64

2008 Autodesk

Main Libraries - II
AcUi/AdUi MFC Extension Library (adui18.lib acui18.lib) Automation (axdb.lib oleaprot.lib) ads_ Function Set (acad.lib) Static Linking Memory Management (rxheap.lib)

2008 Autodesk

AutoCAD Facet Modeler (aecmodeler60.lib) AutoCAD Boundary Representation (acbr18.lib, acgex19.lib) ObjectARX Wizard
(<your path>\ObjectARX 2010\utils\ObjARXWiz\ArxWizards.msi)

ATIL - Raster graphics Teefy - Converting existing applications to Unicode string handling

2008 Autodesk

On-line Documentation
Found in ObjectARX\docs

ObjectARX Documentation (arxdoc.chm) ObjectARX Developers Guide (arxdev.chm) Reference Manual (arxref.chm) Managed Class Reference Guide (arxmgd.chm) ObjectARX 2010 Migration Guide (arxxmg.chm) 64-bit Migration Guide (arxmgr.chm) Interoperability Guide (arxiop.chm) ObjectARX Readme (readarx.chm)

ObjectARX Training Material and Labs

(can be found on the Autodesk site)

2008 Autodesk

The ObjectARX SDK comes with a number of code samples organized into sub-categories:


COM Database DotNet Editor Entity Graphics Misc Reactors PolySamp and ArxDbg

Also see Knowledgebase on the ADN website.

2008 Autodesk

.ARX = .DLL + 2 exported functions

acrxEntryPoint acrxGetApiVersion




2008 Autodesk

Loading ObjectARX Applications I

Loaded by the user

ARX & APPLOAD commands Drag & Drop Startup


Demand loaded

acad.rx file Registry (arxload) in acad.lsp Registry From another application Registry


On command invocation

On request

On proxy detection

Live Enablers (see PolySamp)

2008 Autodesk

Loading ObjectARX Applications II

3. AutoCAD 1. 1. LoadLibrary
2. _DllMainCRTStartup (see MSDN for info) 3. CRT_INIT (constructs global class vars) 4. DllMain (see MSDN for info) 5. acrxGetApiVersion 6. acrxEntryPoint
2008 Autodesk

5. 6.


.ARX 2.


Operating System

Wrong ARX Memory Management





Piece of Memory


1. .ARX allocates memory from debug heap 2. .ARX passes allocated memory to AutoCAD 3. AutoCAD de-allocates it with release delete CRASH

2008 Autodesk

Correct ARX Memory Management I

2. 3.


Piece of Memory


1. .ARX allocates memory from release heap 2. .ARX passes allocated memory to AutoCAD 3. AutoCAD de-allocates it with release delete


2008 Autodesk

Correct ARX Memory Management II



Piece of Memory




1. .ARX allocates memory via rxheap.lib 2. AutoCAD allocates memory on release heap 3. .ARX passes memory to AutoCAD 4. AutoCAD de-allocates it with release delete


2008 Autodesk

Getting Started
Visual C++ 9.0 (.NET) AutoCAD 2010 ObjectARX 2010

ArxDbg Dependency Walker Process Monitor

\ObjectARX 2010\samples\database\ARXDBG or

C:\Program Files\Microsoft Visual Studio 9\Common7\Tools\bin\depends.exe

2008 Autodesk

Command Mechanism I
1. 4. AcEdCommandStack 2, 3. 5. AcEdCommand AutoCAD Callback function .ARX


1. Add command
2. Create command object 3. Parameterize it

4. User types command name

5. Lookup command object 6. Call callback function
2008 Autodesk

Command Mechanism II
Removing commands is as important as adding them Command names can clash

Commands belong to groups

Command groups must be unique


Registered Developer Symbol (RDS) Search for Registered Developer Symbol takes you to

2008 Autodesk

Lab - Step 1
Setup your first .ARX

2008 Autodesk

Prompting for User Input

AcEd functions

String, number acquisition Point, angle acquisition Entity selection

acedGetString(), acedGetInt() acedGetPoint(), acedGetAngle() acedEntSel()

Full range of Win32 controls

2008 Autodesk

ObjectARX Wizards
Application Wizard
ObjectARX\utils\ObjARXWiz\ArxWizards.msi  COM Wrapper Wizard  Custom Object Wizard  Reactors Class Wizard etc.

Visual Studio Add-In

ObjectARX Commands  Autodesk Class Explorer etc.

2008 Autodesk

Lab - Step 2
Play around with user input functions

2008 Autodesk

Agenda Overview of APIs AutoCAD: Hello.arx ObjectDBX: Structure ObjectDBX: Extend it! AutoCAD: Multi-Document Environment Notification System

2008 Autodesk

AutoCAD Session Document

Current Document

ObjectARX works with this in background User sees this in UI

Active Document

Drawing Database

Working Database

Current Drawing

2008 Autodesk

ObjectDBX: Introduction
What is ObjectDBX and RealDWG? AutoCAD drawing database

Object identity Transactions Inter-object references Important classes Important objects Storing data

2008 Autodesk

What is ObjectDBX and RealDWG?

ObjectDBX is an AutoCAD-independent subset of ObjectARX RealDWG is the license to use ObjectDBX in an own application outside of AutoCAD. RealDWG allows to read/write DWG files from your own application Set of DLLs Custom object data services Extensible application development framework

2008 Autodesk

DWG Viewers
No viewing available in RealDWG! AutoCAD OEM DWF

Autodesk Design Review DWG TrueView conversion of dwgs from old formats

2008 Autodesk

Database Framework
DWG Client Apps AutoCAD
App 1 App 2 Corp. Dev. Other

ObjectARX Application
User Interface

Inventor Revit Max

acdb18.dll acismobj18.lib axdb.lib Acgiapi.lib achapi18.lib acge18.lib

Object Enablers

acis.dll(s) others...
ObjEnabler2.dbx ObjEnabler3.dbx ObjEnablerN.dbx

Design Object Data


2008 Autodesk

Enabling Custom Objects w/o ACAD

DWG Client Apps.
App 1 App 2 Corp. Dev. Other

Inventor Revit
acISMobj.lib acge18.lib acis.dll(s) others...

Object Enablers
acdb18.lib achapi18.lib
ObjEnabler1.dbx ObjEnabler2.dbx ObjEnabler3.dbx


axdb.lib acgiapi.lib

Design Object Data


2008 Autodesk

Plug-In Model & ObjectDBX AutoCAD process


Acad.exe & other AutoCAD specific DLLs

ObjectDBX DLLs

2008 Autodesk

ObjectARX & ObjectDBX

ObjectDBX ObjectARX SDK
acdb18.lib acge18lib acgiapi.lib axdb.lib achapi18.lib rxapi.lib acismobj18.lib rxheap.lib acad.lib acedapi.lib acui18.lib adui18.lib oleaprot.lib AcTc.lib AcTcUI.lib


2008 Autodesk


What can I do with ObjectARX?

Create/Modify DWG/DXF files (.ARX) Create object enabler DLLs (.DBX) Cannot create standalone applications this requires RealDWG

2008 Autodesk

AutoCAD Drawing Database

An AutoCAD drawing file is the persistent state of an object database

Objects have identity (primary key) Objects are only accessed in a transaction Objects can have references to other objects Objects can encapsulate data

Relational model Tables Records Fields

Object model Objects Objects Data members (encapsulated)

2008 Autodesk

Object Identity
Handle (AcDbHandle)

Unique identifier of an object for the life of the drawing

Object ID (AcDbObjectId)

Unique identifier of an object for a session of ObjectDBX Multiple drawings allowed per session IDs unique across ALL files would require too much storage space (GUIDs)


Unique identifier of an object for the duration of a transaction

2008 Autodesk

Handles, Object IDs, Pointers

ObjectDBX session
1. 2.


Object Closed
4. 5.

Open AcDbObject

New AcDbObject

1. Object read from file

Handle Object ID Object ID Pointer

2. Object opened 3. New object added to database

New Object ID & Handle assigned

4. Object closed
Pointer becomes invalid

5. Object saved to file

Handles are written to disk
2008 Autodesk

Object ID and Entity Name

ads_name is a relic from days of ADS Virtually the same  An ads_name

Array of two longs First element of ads_name

An AcDbObjectId

Exchange one for another  acdbGetAdsName( adsName, objId );  acdbGetObjectId( objId, adsName );

2008 Autodesk

Open Modes

255 simultaneous readers Open/Close model



1 writer at a time read/write are mutually exclusive multiple writers are allowed read/write are NOT exclusive

Transaction model


2008 Autodesk

Used internally

Two models


acdbOpenObject AcDbObject::close, AcDbObject::cancel AcDbTransactionManager::startTransaction AcTransaction::getObject AcDbTransactionManager::end/abortTransaction


Do not mix transaction models

e.g. getObject, then close

2008 Autodesk

Nesting AcTransactions
Transaction 2 Transaction 1
obj1 obj2

obj2 obj3

obj1 AcDbDatabase obj2


1. Client starts Trans1 and gets Obj1 & Obj2 2. Client starts Trans2 and gets Obj2 & Obj3 3. Client commits Trans2

Trans2 changes are committed Trans1 changes are committed Trans1 (and Trans2) changes are rolled back

4a. Client commits Trans1

4b. Client aborts Trans1 instead

2008 Autodesk

Getting an AcDbDatabase Object

Construct one

In memory

Get the one currently active in AutoCAD


More on this in the AutoCAD: MDE section

Access some other open document Open a new dwg file

2008 Autodesk

AcDbDatabase Ownership Hierarchy

2008 Autodesk

Object Model Overview


in ObjectARX distribution

2008 Autodesk

Important Classes
AcRxObject AcGiDrawable AcDbObject AcDbEntity AcDbCurve AcDbDictionary AcDbSymbolTable AcDbBlockTable AcDbSymbolTableRecord Database resident objects Drawable objects AcDbLine

2008 Autodesk

Snoop Tools for the AutoCAD Database

Tool Language Where to find

ArxDbg MgdDbg Inspector

C++ C# C++

ObjectARX Samples ADN site ADN site

2008 Autodesk

Important Objects
Block Table  Three default records



Only entities added to one of these is visible in AutoCAD editor Block table records only own entities

Named Objects Dictionary  AutoCADs symbol tables  Dictionaries own any objects (but not entities)

2008 Autodesk

Iterating Through Containers

Objects that use iterators

Symbol Tables Block Table Records Dictionaries Polylines PolyFaceMesh & PolygonMesh ACIS Solids

Called traversers

BlockReferences (Inserts)

Only useful when attributes are present

2008 Autodesk

Iterator Pattern
Abstract form of i in the following construct: for( int i=0; i<numElems; i++ ) a = array[i]; Needs initialization, done condition and next operation




iterator1 Aggregate

See Design Patterns by Erich Gamma et al. (ISBN 0-201-63361-2)

2008 Autodesk

RTTI Runtime Type Identification

Object containers provide generic pointers to

AcDbObjects AcDbEntities RTTI allows us to do this cast isA isKindOf down-cast pointer safely get class descriptor is object derived from?

We might prefer a pointer to an AcDbPolyline

AcRxObject defines (in rxobject.h)


AcDbEntity * ent; if( ent->isKindOf( AcDbLine::desc() ) ) { AcDbLine * line = AcDbLine::cast( ent ); // do something with line->startPoint() ... }
2008 Autodesk

AcRxClass I (Overview)
Three roles:

Runtime type identification Class factory Protocol extension


samples\database\dataxtsn\peinvent samples\entity\tempapp_dg

AcRxClass is usually set up for a custom object via macros in rxboiler.h


2008 Autodesk

AcRxClass II (Cont.)
AcRxObject-derived objects hold a pointer to an AcRxClass object (class descriptor object)

static class variable

AcRxClass objects hold a pointer to the parent AcRxClass object

forms a run time class hierarchy

2008 Autodesk

AcRxClass III (Object Diagram)

An AcDbLine Runtime class hierarchy An AcRxClass for AcDbCurve

Another AcDbLine

An AcRxClass for AcDbLine An AcRxClass for AcDbCircle

An AsdkCircle

A protocol extension object .DBX/.ARX App Pseudo constructor

An AcRxClass for AsdkCircle

2008 Autodesk

AcRxClass IV (Roles)
Class Factory

During filing we look up the class identifier in the runtime class hierarchy AcRxClass provides a constructor function

Run time type identification

Each AcRxObject provides a virtual member to look up the static member pointing to its AcRxClass object

Protocol Extension

AcRxClasses hold a list of extension objects

2008 Autodesk

Storing Data in the Database

Create custom objects (more on this later) Without using custom objects

Extended entity data (Xdata) Xrecords


Extension dictionaries on individual objects Dictionaries e.g. under the Named Objects

Data stored with these methods can be also accessed by LISP and COM

2008 Autodesk

Lab - Step 3
Accessing object containers

Symbol tables

2008 Autodesk

AcDbDatabase Ownership Hierarchy

2008 Autodesk

Inter-Object References

Dictates objects written to disk (DWG/DXF) A database object has exactly one owner Database is the ultimate owner Bi-directional

Pointer reference

Arbitrary references between object Multiple objects can point to the same object Uni-directional

Use ArxDbg to discover them

2008 Autodesk

Inter-Object References



AcDbDictionary Named Object Dict.



AcDbDictionary Company Dictionary *



AcDbHardOwnershipId AcDbSoftOwnershipId

AcDbHardPointerId AcDbSoftPointerId

2008 Autodesk

Inter-Object References
Hard ownership examples

Database Object Block Table

Extension Dictionary

Model Space BTR Entries

Extension Dictionaries

Hard pointer examples


Entity Text

Linetype Style

2008 Autodesk

Inter-Object References
Soft owner examples


Entries Entities

(can be made hard owner)

Symbol Tables

(except model and paper space which are hard)

Soft pointer example


Entity Object

Xdata Entity Handle Persistent Reactor

2008 Autodesk

Soft/Hard References

Follows both types of ownership links


Follows hard references


COPY, MIRROR, EXPLODE commands Follows only ownership links


Soft references do not protect the object from purge

2008 Autodesk

Changing an Objects Identity I


Replaces an objects in the db with a new one Objects cannot be removed from the db

You can only flag them as erased


Open AcDbObject

New AcDbObject

ObjectDBX Session


2008 Autodesk

Changing an Objects Identity II


Changes the object denoted by the object ID



ObjectDBX Session
2008 Autodesk


Lab - Step 4
Accessing object containers


2008 Autodesk

Agenda Overview of APIs AutoCAD: Hello.arx ObjectDBX: Structure ObjectDBX: Extend it! AutoCAD: Multi-Document Environment Notification System

2008 Autodesk

ObjectDBX: Extend It!

First step: create a new class Then: participate in desired mechanisms  Filing ObjectDBX  Undo ObjectDBX  Graphics Display host application  Whatever else the host application may define

e.g. TRIM and BREAK in AutoCAD

2008 Autodesk

Create a New Class

Derive from  AcRxObject  AcGiDrawable  AcDbObject  AcDbEntity  AcDbCurve 

RTTI protocol + Graphics protocol + Filing protocol Persistent graphics Curve entities

ObjectDBX and host applications interact with your object through these interfaces

2008 Autodesk

Read/write object state to another object (filer)

Visitor Pattern

Filers implement AcDbDwgFiler or AcDbDxfFiler interface Used for DWG/DXF save/load, and also:

Copy Undo entmake/entget/entmod Copy/Wblock/Insert/Xref/Refedit Paging Wblock Purge

kCopyFiler kUndoFiler kBagFiler kIdXlateFiler kPageFiler kWBlockCloneFiler kPurgeFiler

2008 Autodesk

Filing Out
An AcDbDwgFiler

An AcDbObject

1. 2. 3.


Another AcDbObject

1. Object implementing filer protocol created 2. Filer is passed to the database object 3. Database object calls back into the filer

2008 Autodesk

Filing In
An AcDbDwgFiler

An AcDbObject

1. 2. 3.



Another AcDbObject


1. Class identifier is read from filer 2. Class is instantiated by AcRxClass class factory 3. Filer is passed to the newly created object 4. Database object calls back into the filer
2008 Autodesk

Filing Member Functions - I

AutoCAD calls the dwgIn which calls your dwgInFields function on:

Open Undo Insert, Copy, Xref Wblock Object paging

kFileFiler kUndoFiler kDeepCloneFiler + kIdXlateFiler kWblockCloneFiler + kIdXlateFiler kPageFiler

2008 Autodesk

Filing Member Functions - II

AutoCAD calls the dwgOut which in turn calls your dwgOutFields function on:

Save/SaveAs Wblock Insert, Xref

kFileFiler kWblockCloneFiler + kIdXlateFiler kDeepCloneFiler + kIdXlateFiler

Copy same as Insert (files out objects state and files it into another object) Purge Object paging Any Object modification for undo recording kPurgeFiler kPageFiler kUndoFiler

2008 Autodesk

Filing Member Functions - III

AutoCAD calls dxfOut which calls your dxfOutFields function on:


kFileFiler kFileFiler kFileFiler kBagFiler

AutoCAD calls dxfIn which calls your dxfInFields function on:


OPEN INSERT acdbEntMod, acdbEntMake, acdbEntMakeX

kFileFiler kFileFiler


2008 Autodesk

Data sent to a DXF filer is tagged with DXF group codes

Group code ranges for each data type AcDb enum has first in each range use +1, +2, etc to get others AcDb::DxfCode

Groups may come in any sequence

2008 Autodesk

Check You Have Access Rights

Member functions should first call one of these:

assertReadEnabled  Every member function that reads data assertWriteEnabled  Every member function that modifies data assertNotifyEnabled  Used internally

2008 Autodesk

A proxy object is created in memory when a defining application is not available

Surrogate data holder for custom object

Class ID

Graphics data Object data

Only inter-object references are interpreted Used to draw proxy graphics

2008 Autodesk

Class ID

Lab - Step 5
Creating a Custom Object

2008 Autodesk

Graphics Display
ObjectDBX does not display any graphics ObjectDBX defines a callback API that host applications may implement

AcGi: interface between database objects and a display system

Host applications must implement AcGi to display graphics

AcGi Library defines the interface between database objects and a display system

2008 Autodesk

AcGi Class Diagram

AcGiCommonDraw AcGiContext AcGiSubentityTraits AcGiGeometry AcGiWorldDraw AcGiViewportDraw AcGiViewport
Legend: Inheritance Containment

AcGiWorldGeometry AcGiViewportGeometry

2008 Autodesk

Graphics Acquisition

An AcGiWorldDraw

An AcGiDrawable


3. 5.

Host Application

An AcGiViewportDraw

1. Host creates object implementing AcGiWorldDraw 2. Host creates object implementing AcGiViewportDraw 3. Host passes world-draw object to your drawable 4. Drawable draws viewport independent graphics 5. Host passes viewport-draw object to your drawable 6. Drawable draws viewport dependent graphics
2008 Autodesk

Responsible for inserting geometry into the graphics cache for later display Primitive geometry used:

circle, circularArc, polyline, mesh, pline, polygon, shell, text, xline and ray

Viewport-dependent and viewport-independent graphics

2008 Autodesk

Traits control current attributes for primitives:

color, layer, linetype, filltype graphics system (GS) marker

Allows identification of sub-entities

Once set, a trait stays active until changed or out of scope

Default attribute values:


color, layer, linetype - Current for editor filltype - kAcGiFillNever if standard mode kAcGiFillAlways if hide, shade, render gsmarker - invalid, must be set by app

2008 Autodesk

Special Uses of AcGi

Can derive from AcGiWorldGeometry, implementing own versions of geometry functions

2008 Autodesk

Host-Defined Mechanisms
ObjectDBX defines protocols for

Grips Osnaps Intersection Transformations etc.

Host applications use as appropriate

e.g. Volo View does not use grips

2008 Autodesk

AcDbEntity Protocol
subGetOsnapPoints subGetGripPoints subMoveGripPointsAt subGetStretchPoints - define osnap points - define grip points - default is to call AcDbEntity::subTransformBy - provide stretch points other than the grippoints, default is to call subGetGripPoints

subMoveStretchPointsAt - used by stretch, default is subTransformBy subTransformBy - needed for moving entity

2008 Autodesk

AcDbEntity Protocol
subIntersectWith - no default

subGetGeomExtents - no default subList subExplode


- print specified data, DXF name, layer, space, and handle by default - no default, must be implemented for hatch to work

If exploding to non-native objects, return eExplodeAgain Hatch calls explode recursively until down to native entities (until eOk returned)

2008 Autodesk

Lab - Step 6
Creating a Custom Entity

2008 Autodesk

Agenda Overview of APIs AutoCAD: Hello.arx ObjectDBX: Structure ObjectDBX: Extend it! AutoCAD: Multi-Document Environment Notification System

2008 Autodesk

AutoCAD: Multi-Document Environment (MDE)

Documents, per-document data Execution context Document locking

2008 Autodesk

State of the edit session AcApDocument class encapsulates

AcDbDatabase viewed XRefed databases Selection sets Most system variables

AcApDocManager holds the list of documents

2008 Autodesk

Per-Document Data
Applications may have per-doc data

this is their concept of a document

Data must be kept in sync with the active document (fiber)

this is their concept of a document manager

2008 Autodesk

Execution Contexts
AutoCAD has a fiber-based architecture

see MSDN for more info on fibers fibers are scheduled by AutoCAD they have their own call stack

Application fiber (context):


runs windows message loop kicks off a fiber for each document created

Document fibers (context):

run commands for the given document

2008 Autodesk

Fiber scheduling in AutoCAD

App Fiber Doc1 Fiber Doc2 Fiber

Msg loop Cmd started in Doc1 Time Msg loop User switches to Doc2, starts cmd Cmd completes in Doc2 Msg loop Doc1 prompts for user input

2008 Autodesk

Document Locking
Document-level transaction

Non-database resident data cannot rely on the ObjectDBX transaction model e.g. system variables

Provides synchronization, avoids data corruption Provides rollback (undo)

2008 Autodesk

Lock Types
New Lock Request
(from another context)

XWrite Write Read AWrite Current Lock None Read Write XWrite AutoWrite

v v v

v v

v v v v

2008 Autodesk

Document vs. Application

Document context

Automatic locking (simpler) e.g. for exclusive write


Application context

Manual locking (more control)


acDocManager->lockDocument( pDoc, kXWrite ); Required for multiple docs

2008 Autodesk

Current vs. Active Documents


for the user = Active for the API = Current

Activating a document sets the current doc

current document = active document

Current doc can change (programmatically)

current document may not be active

2008 Autodesk

Agenda Overview of APIs AutoCAD: Hello.arx ObjectDBX: Structure ObjectDBX: Extend it! AutoCAD: Multi-Document Environment Notification System

2008 Autodesk

Notification System
Observer Pattern Implementation Subjects & Observers

ObjectDBX AutoCAD

Acting as an Observer Acting as a Subject

2008 Autodesk

Observer pattern class diagram
1. Knows its observers 2. Provides interface to attach/detach observers observers Defines updating interface

Observer Update()

Subject Attach(Observer) Detach(Observer) SendNotification()

For all o in observers { o->Update() }

ConcreteSubject subjectState

ConcreteObserver Update() observerState

2008 Autodesk

Observer pattern interaction diagram

A ConcreteSubject


A ConcreteObserver

2. Client


1. Client creates observer 2. Client attaches observer to subject 3. Subject changes state and fires notification to observer 4. Observer learns details of state change
2008 Autodesk

Notification Example
Interaction diagram

An AcDbLine


Your custom object

2. Client


1. Client creates your custom object 2. Client calls addPersistentReactor on the AcDbLine 3. Changing AcDbLine sends objectModified notification 4. Your custom object looks at the line to find out what changed
2008 Autodesk

Another AcDbObject An AcDbDatabase

Observers (reactors)
An AcDbDatabaseReactor


An AcDbObject

An AcDbObjectReactor

The AcDbLayoutManager The AcDbTransactionManager The AcRxEvent The AcRxDynamicLinker ObjectDBX

An AcDbLayoutManagerReactor An AcTransactionReactor An AcRxEventReactor An AcRxDLinkerReactor

2008 Autodesk

The AcDbSummaryInfoManager The AcGsManager The AcApProfileManager

Observers (reactors)
An AcDbSummaryInfoReactor An AcGsReactor An AcApProfileManagerReactor An AcEdInputPointFilter


The AcEdInputPointManager

An AcEdInputPointMonitor An AcEdInputContextReactor

The AcApLongTransactionManager The AcApDocumentManager The AcEditor AutoCAD

An AcApLongTransactionReactor An AcApDocManagerReactor An AcEditorReactor

2008 Autodesk

Acting as an Observer
Derive a concrete observer class

Override notification functions

Instantiate it Attach it to subject Remove it when done

At least when application is unloaded

2008 Autodesk

Acting as a Subject
Define your own observer (notification) interface Provide methods to attach/detach observers Send notifications when state changes

If your observer (reactor) is database resident then open it for kForNotify

2008 Autodesk

Lab - Step 7
Observing various subjects

2008 Autodesk

Thank you!

2008 Autodesk