ObjectARX 2010

and
AutoCAD .NET
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 SDK‟s

 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 autodesk.com
 Promotional opportunities
 1 to 3 free API training classes
 Based on user level

www.autodesk.com/joinadn

© 2008 Autodesk
 Developer Technical Services

Worldwide Workgroup
 Over 25 Specialists World Wide
 Virtually 24 hour support, 5 days a week
Americas Team
 CA, WA, São Paulo
European Team
 Switzerland, United Kingdom, France, Czech Republic, Russia
APac Team
 China, Japan, India

© 2008 Autodesk
 Getting Support
http://www.autodesk.com/adn-devhelp

 Provides access to
 On-line knowledgebase
 Request submission
 Newsgroups
 Requests are logged automatically
 1-3 day turnaround
 Callbacks as needed
 Answers to frequently asked questions are posted in our on-
line 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

 AutoCAD .NET

© 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 - this presentation
 AutoCAD.NET*.pptx - .NET API presentation
 objectarx_2010_win_64_and_32bit.exe - ObjectARX installation file

 objectarx_2010_training.zip - ObjectARX labs

 AutoCAD 2010.Net Training.zip - .NET labs
 Inspector.zip - 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

AutoCAD‟s 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.

4
API
ATL templates
API 2
1 SomeApp.exe API
Static MFC Library
3
API
Win 32 API DLLs

1. Source code 2. Static library

3. DLL 4. EXE

© 2008 Autodesk
 Client/Server Interaction

In process
 Client/server is in the same process

Local
 Client/server is on the same machine

Remote
 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

.DLL
.ARX .DLL
.ARX

API APIs
ObjectARX

.EXE
AutoCAD

© 2008 Autodesk
 Forms of Client Code

SLOW Interpreted code

 Source script
 AutoLISP in the past
Packaged code (p-code)
 Pre-processed, semi interpreted code
 Compiled Visual LISP
AutoCAD.NET
 Compiled into IL
Compiled code
 Processor instructions
 ObjectARX
FAST

© 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

driver
Input
Input acquisition

AutoCAD

PlotHDI
2D graphics

Plotter
driver
cache
(WHIP!)

Display

HEIDI
driver
3D graphics
ObjectDBX
cache

 ObjectARX SDK (free, http://www.autodesk.com/objectarx)

 RealDWG (licensed, http://usa.autodesk.com/adsk/servlet/index?siteID=123112&id=770257) dwg
 Plot DDK (licensed, http://www.autodesk.com/adn-devhelp)
 HEIDI DDK (licensed, http://www.autodesk.com/heidi)
 Wintab API (free)

© 2008 Autodesk
 API Implementation II

.NET Lisp VBA COM Client

script script (VB, Java, Delphi)
Acdbmgd.dll
Acmgd.dll vl.arx acvba.arx

axdb.dll

ObjectARX APIs COM

AutoCAD

© 2008 Autodesk
 Old API Performance Comparison
S.0.58 API Performance

100.00

90.00

80.00

70.00

60.00
Seconds

50.00

40.00
Total
30.00
Create 1000 2dPolylines
20.00
Add XData to 1000 Entities
10.00 Update 1000 Circles
0.00 Create 1000 lines
COM (VB)

COM (VBA)

Create 1000 Circles

LISP

ObjectARX

Cre
Cre
Upd

AutoCAD's APIs Add

Cre
Tota
© 2008 Autodesk
 How to Store Your Data in AutoCAD
Different Programming Techniques

Data Container Performance Chart

400
350
Time in seconds

300
250
ObjectARX
200
.NET
150
LISP
100
50
0
Xrecord Custom Object Xdata

© 2008 Autodesk
 How to Store Your Data in AutoCAD
Different Programming Techniques

Data Container Performance Chart

140000
120000
Time in seconds

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

© 2008 Autodesk
 How to Store Your Data in AutoCAD
Different Programming Techniques

Data Container Performance Chart

5000
Time in seconds

4000

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

© 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

ObjectARX
 What it is
 Where to get it
ObjectARX applications
 Structure
 Loading
 Memory management
Creating commands
 Command mechanism
 Prompting for user input
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 AutoCAD‟s user interface

 Commands
 Toolbars/dialogs
 Properties Window
 Design Center
 Display system

Monitor/Modify AutoCAD‟s standard behavior

 Event notifications
 Input point acquisition

© 2008 Autodesk
 Getting the ObjectARX SDK

Download - Free
On Autodesk public web site
Developer Center - ObjectARX
(http://usa.autodesk.com/adsk/servlet/index?id=773204&siteID=123112)

Or Search for ObjectARX on

http://www.autodesk.com/

© 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
For .NET development:
 VS 2008
 VS 2005 RTM or SP1

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
 Utilities

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
 Samples

The ObjectARX SDK comes with a number of code samples

organized into sub-categories:
 ObjectARX\Samples
 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

.DLL
.ARX .ARX
.DLL

API APIs
ObjectARX

.EXE
AutoCAD

© 2008 Autodesk
 Loading ObjectARX Applications I

Loaded by the user

 ARX & APPLOAD commands
 Drag & Drop

Demand loaded
 Startup
 acad.rx file
 Registry
 (arxload) in acad.lsp
 On command invocation
 Registry
 On request
 From another application
 On proxy detection
 Registry

Live Enablers (see PolySamp)

© 2008 Autodesk
 Loading ObjectARX Applications II
3.

Rxapi.lib
AutoCAD 5. 4.
.ARX

1. 6.
2.
Operating System
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
 Wrong ARX Memory Management

AutoCAD/ObjectDBX 3.
MSVCRT.DLL

2. Piece of
CRASH! Memory
.ARX 1. MSVCRTD.DLL

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

3.
AutoCAD/ObjectDBX MSVCRT.DLL
Piece of
Memory
2.

1.
.ARX

1. .ARX allocates memory from release heap

2. .ARX passes allocated memory to AutoCAD
3. AutoCAD de-allocates it with release „delete‟…  OK

© 2008 Autodesk
 Correct ARX Memory Management II
2.
AutoCAD/ObjectDBX 4. MSVCRT.DLL
Piece of
1. 3. Memory

Rxheap.lib

Libcmt.lib
.ARX

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‟…  OK

© 2008 Autodesk
 Getting Started

Visual C++ 9.0 (.NET)

AutoCAD 2010
ObjectARX 2010

ArxDbg \ObjectARX 2010\samples\database\ARXDBG

Dependency Walker www.dependencywalker.com or

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

Process Monitor www.sysinternals.com

© 2008 Autodesk
 Command Mechanism I
.ARX
1.
AcEdCommandStack
4.
5. Callback
2, 3. 6. function
AcEdCommand

AutoCAD

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
http://usa.autodesk.com/adsk/servlet/index?siteID=123112&id=1075006

© 2008 Autodesk
 Lab - Step 1

Setup your first .ARX

© 2008 Autodesk
 Prompting for User Input

AcEd functions
 String, number acquisition acedGetString(), acedGetInt()
 Point, angle acquisition acedGetPoint(), acedGetAngle()
 Entity selection 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
 Terminology

AutoCAD Session
Document
 Current Document
 ObjectARX works with this in background
 Active Document
 User sees this in UI
Drawing
Database
 Working Database
 Current Drawing
acdbHostApplicationServices()->workingDatabase()

© 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
 www.dwfit.com
Autodesk Design Review
DWG TrueView – conversion of dwgs from old formats

© 2008 Autodesk
 Database Framework
DWG Client Apps
ObjectARX
AutoCAD
Application
User Interface
Partners: Autodesk: ObjectDBX
App 1 Inventor acdb18.dll achapi18.lib
Object Enablers
acismobj18.lib acge18.lib
App 2 Revit ObjEnabler1.dbx
axdb.lib acis.dll(s)
ObjEnabler2.dbx
Corp. Dev. Acgiapi.lib others...
Max
ObjEnabler3.dbx

Other ObjEnablerN.dbx

Design Object Data

DWG DXF

© 2008 Autodesk
 Enabling Custom Objects w/o ACAD

DWG Client Apps.

Partners: Autodesk:

App 1 Inventor ObjectDBX

Object Enablers
acdb18.lib achapi18.lib
App 2 Revit ObjEnabler1.dbx
acISMobj.lib acge18.lib
ObjEnabler2.dbx
Corp. Dev. Max axdb.lib acis.dll(s)

acgiapi.lib others... ObjEnabler3.dbx

Other
ObjEnablerN.dbx

Design Object Data

DWG DXF

© 2008 Autodesk
 Plug-In Model & ObjectDBX

AutoCAD process

.ARX .DBX

Acad.exe &
other AutoCAD ObjectDBX DLLs
specific DLLs

© 2008 Autodesk
 ObjectARX & ObjectDBX

ObjectDBX ObjectARX SDK

acdb18.lib acad.lib
acge18lib acedapi.lib
rcexelib.obj acgiapi.lib acui18.lib
axdb.lib adui18.lib
achapi18.lib oleaprot.lib
rxapi.lib AcTc.lib
acismobj18.lib AcTcUI.lib
rxheap.lib …
…

RealDWG
Shared
© 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 Object model

Tables Objects
Records Objects
Fields 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)
Pointer
 Unique identifier of an object for the duration of a transaction

© 2008 Autodesk
 Handles, Object IDs, Pointers
ObjectDBX session
1.
2.
Object Open New
.dwg Closed AcDbObject AcDbObject
4. 3.
5.

1. Object read from file

Handle  Object ID
2. Object opened
Object ID  Pointer
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
 An AcDbObjectId
 First element of ads_name

Exchange one for another

 acdbGetAdsName( adsName, objId );
 acdbGetObjectId( objId, adsName );

© 2008 Autodesk
 Open Modes

Read
 255 simultaneous readers
Write
 Open/Close model
 1 writer at a time
 read/write are mutually exclusive
 Transaction model
 multiple writers are allowed
 read/write are NOT exclusive
Notify
 Used internally

© 2008 Autodesk
 Transactions

Two models
 Open/Close
 acdbOpenObject
 AcDbObject::close, AcDbObject::cancel
 Transaction
 AcDbTransactionManager::startTransaction
 AcTransaction::getObject
 AcDbTransactionManager::end/abortTransaction

Do not mix transaction models

 e.g. getObject, then close

© 2008 Autodesk
 Nesting AcTransactions
1 2 3 4
Transaction 2 obj2 obj3

Transaction 1 obj1 obj2

obj1 obj3
obj2
AcDbDatabase

1. Client starts Trans1 and gets Obj1 & Obj2

2. Client starts Trans2 and gets Obj2 & Obj3
3. Client commits Trans2
 Trans2 changes are committed
4a. Client commits Trans1
 Trans1 changes are committed
4b. Client aborts Trans1 instead
 Trans1 (and Trans2) changes are rolled back

© 2008 Autodesk
 Getting an AcDbDatabase Object

Construct one
 In memory

Get the one currently active in AutoCAD

acdbHostApplicationServices()->workingDatabase();
 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

classmap.dwg
 in ObjectARX distribution

© 2008 Autodesk
 Important Classes
AcRxObject

AcGiDrawable

AcDbObject

AcDbEntity

AcDbCurve

AcDbDictionary AcDbLine

AcDbSymbolTable

AcDbBlockTable

AcDbSymbolTableRecord

Database resident objects

Drawable objects

© 2008 Autodesk
 Snoop Tools for the AutoCAD Database

Tool Language Where to find

ArxDbg C++ ObjectARX Samples

MgdDbg C# ADN site
Inspector C++ ADN site

© 2008 Autodesk
 Important Objects

Block Table
 Three default records
 *MODEL_SPACE
 *PAPER_SPACE, *PAPER_SPACE0
 Only entities added to one of these is visible in AutoCAD editor
 Block table records only own entities

Named Objects Dictionary

 AutoCAD‟s “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

Client1 Client2

iterator1 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
We might prefer a pointer to an AcDbPolyline
 RTTI allows us to do this
AcRxObject defines (in rxobject.h)
 cast down-cast pointer safely
 isA get class descriptor
 isKindOf is object derived from?

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
ACRX_DECLARE_MEMBERS(CLASS_NAME)
ACRX_DXF_DEFINE_MEMBERS
…

© 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)

Runtime class
An AcDbLine hierarchy An AcRxClass
for
AcDbCurve

Another AcDbLine
An AcRxClass
for
AcDbLine
An AsdkCircle An AcRxClass
for
AcDbCircle

A protocol
extension An AcRxClass
object for
Pseudo AsdkCircle
.DBX/.ARX App constructor

© 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

Ownership
 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

AcDbDatabase

AcDbDictionary
AcDbBlockTable AcDbLayerTable
Named Object Dict.

AcDbDictionary
AcDbBlockTableRecord AcDbLayerTableRecord
Company Dictionary *

AcDbLine AcDbObject'

AcDbHardOwnershipId AcDbHardPointerId

AcDbSoftOwnershipId AcDbSoftPointerId

© 2008 Autodesk
 Inter-Object References

Hard ownership examples

 Database Object  Extension Dictionary
 Block Table  Model Space BTR
 Extension Dictionaries  Entries

Hard pointer examples

 Entity  Linetype
 Text  Style

© 2008 Autodesk
 Inter-Object References

Soft owner examples

 Dictionary  Entries
(can be made hard owner)
 Symbol Tables  Entities
(except model and paper space which are hard)

Soft pointer example

 Entity  Xdata Entity Handle
 Object  Persistent Reactor

© 2008 Autodesk
 Soft/Hard References

Save
 Follows both types of ownership links
Wblock
 Follows hard references
DeepClone
 COPY, MIRROR, EXPLODE commands
 Follows only ownership links
Purge
 Soft references do not protect the object from purge

© 2008 Autodesk
 Changing an Object’s Identity I

AcDbObject::handOverTo
 Replaces an objects in the db with a new one
 Objects cannot be removed from the db
 You can only flag them as erased

removed

Open New
AcDbObject AcDbObject

ObjectDBX Session added

© 2008 Autodesk
 Changing an Object’s Identity II

AcDbObject::swapIdWith

 Changes the object denoted by the object ID

id id

AcDbObject AcDbObject

ObjectDBX Session

© 2008 Autodesk
 Lab - Step 4

Accessing object containers

 Dictionaries

© 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 RTTI protocol
 AcGiDrawable + Graphics protocol
 AcDbObject + Filing protocol
 AcDbEntity Persistent graphics
 AcDbCurve Curve entities
…

ObjectDBX and host applications interact with your object

through these interfaces

© 2008 Autodesk
 Filing
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 kCopyFiler
 Undo kUndoFiler
 entmake/entget/entmod kBagFiler
 Copy/Wblock/Insert/Xref/Refedit kIdXlateFiler
 Paging kPageFiler
 Wblock kWBlockCloneFiler
 Purge kPurgeFiler

© 2008 Autodesk
 Filing Out

An AcDbDwgFiler 3.
An AcDbObject

1.
2.
3.
Another
AcDbObject
ObjectDBX
2.

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 4.
An AcDbObject
2.

1.
4.
2.
Another
3.
AcDbObject
ObjectDBX
3.

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 kFileFiler
 Undo kUndoFiler
 Insert, Copy, Xref kDeepCloneFiler
+ kIdXlateFiler
 Wblock kWblockCloneFiler
+ kIdXlateFiler
 Object paging kPageFiler

© 2008 Autodesk
 Filing Member Functions - II

AutoCAD calls the dwgOut which in turn calls your

dwgOutFields function on:
 Save/SaveAs kFileFiler
 Wblock kWblockCloneFiler + kIdXlateFiler
 Insert, Xref kDeepCloneFiler + kIdXlateFiler
 Copy same as Insert
(files out object‟s state and files it into another object)
 Purge kPurgeFiler
 Object paging kPageFiler
 Any Object modification kUndoFiler
for undo recording

© 2008 Autodesk
 Filing Member Functions - III

AutoCAD calls dxfOut which calls your dxfOutFields function on:

 WBLOCK kFileFiler
 SAVE kFileFiler
 SAVEAS kFileFiler
 acdbEntGet kBagFiler

AutoCAD calls dxfIn which calls your dxfInFields function on:

 OPEN kFileFiler
 INSERT kFileFiler
 acdbEntMod,
acdbEntMake,
acdbEntMakeX kBagFiler

© 2008 Autodesk
 AcDbDxfFiler

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
 Proxy

A proxy object is created in memory when a defining application

is not available
 Surrogate data holder for custom object

Class ID
Class ID

Graphics data Object data

Only inter-object references are interpreted

Used to draw proxy graphics

© 2008 Autodesk
 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
AcGiContext
AcGiCommonDraw
AcGiSubentityTraits

AcGiGeometry

AcGiWorldDraw AcGiWorldGeometry

AcGiViewportDraw AcGiViewportGeometry

AcGiViewport

Legend:
Inheritance
Containment

© 2008 Autodesk
 Graphics Acquisition
4.
An AcGiWorldDraw An AcGiDrawable

6.
1.
3.
5.
Host Application An AcGiViewportDraw
2.

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
 AcGiGeometry

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
 AcGiSubEntityTraits

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 - define osnap points

subGetGripPoints - define grip points
subMoveGripPointsAt - default is to call
AcDbEntity::subTransformBy
subGetStretchPoints - 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 - print specified data, DXF name, layer,
space, and handle by default
subExplode - 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
 Documents

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
Doc1 prompts for
user input
Msg loop
User switches to
Doc2, starts cmd

Cmd completes
in Doc2
Msg loop

© 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

None    
Current Lock

Read    
Write    
XWrite    
AutoWrite    

© 2008 Autodesk
 Document vs. Application

Document context
 Automatic locking (simpler)
 e.g. for exclusive write
 addCommand( …, ACRX_CMD_DOCEXCLUSIVELOCK, … );

Application context
 Manual locking (more control)
 acDocManager->lockDocument( pDoc, kXWrite );
 Required for multiple docs

© 2008 Autodesk
 Current vs. Active Documents

Current…
 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
 Notification
Observer pattern class diagram

1. Knows its observers

2. Provides interface to Defines updating interface
attach/detach observers

Observer
Subject observers

Attach(Observer) Update()
Detach(Observer)
For all o in observers { SendNotification()
o->Update()
}

ConcreteSubject ConcreteObserver
Update()
subjectState observerState

© 2008 Autodesk
 Notification

Observer pattern interaction diagram

3.
A ConcreteSubject 4. A ConcreteObserver

2. 1.

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

3.
An AcDbLine 4.
Your custom object

2. 1.

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
 ObjectDBX
Observers (reactors)

Another AcDbObject An AcDbDatabaseReactor

An AcDbDatabase

An AcDbObject An AcDbObjectReactor
Subjects

The AcDbLayoutManager An AcDbLayoutManagerReactor

The AcDbTransactionManager An AcTransactionReactor

The AcRxEvent An AcRxEventReactor

The AcRxDynamicLinker An AcRxDLinkerReactor

ObjectDBX

© 2008 Autodesk
 AutoCAD
Observers (reactors)

The AcDbSummaryInfoManager An AcDbSummaryInfoReactor

The AcGsManager An AcGsReactor

The AcApProfileManager An AcApProfileManagerReactor

Subjects

An AcEdInputPointFilter
The AcEdInputPointManager An AcEdInputPointMonitor
An AcEdInputContextReactor

The AcApLongTransactionManager An AcApLongTransactionReactor

The AcApDocumentManager An AcApDocManagerReactor

The AcEditor An AcEditorReactor

AutoCAD

© 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