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 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 autodesk.com Promotional opportunities Based on user level

1 to 3 free API training classes

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, So 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 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

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 AutoCAD.NET*.pptx

- this presentation - .NET API presentation

objectarx_2010_win_64_and_32bit.exe - ObjectARX installation file

objectarx_2010_training.zip

- ObjectARX labs

AutoCAD 2010.Net Training.zip

Inspector.zip

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

ATL templates

API

API

SomeApp.exe
3

API

Static MFC Library

Win 32 API DLLs

API

1. Source code 3. DLL

2008 Autodesk

2. Static library 4. EXE

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
API ObjectARX APIs

.DLL .ARX

.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

Compiled into IL Processor instructions ObjectARX

AutoCAD.NET

Compiled code

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
Input driver Input acquisition AutoCAD PlotHDI

2D graphics cache (WHIP!)

Display driver

Plotter driver

HEIDI

3D graphics cache

ObjectDBX

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

dwg

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

COM Client

Acdbmgd.dll Acmgd.dll

vl.arx

acvba.arx

axdb.dll
ObjectARX APIs COM

AutoCAD

2008 Autodesk

S.0.58 API Performance Old API Performance Comparison

100.00 90.00 80.00 70.00

Seconds

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)

LISP

Create 1000 Circles

ObjectARX

Cre

Cre

Upd

AutoCAD's APIs
2008 Autodesk

Add

Cre

Tota

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

ObjectARX .NET LISP

2008 Autodesk

How to Store Your Data in AutoCAD

Different Programming Techniques
Data Container Performance Chart
140000
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
5000
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
ObjectARX

What it is

Where to get it
Structure Loading Memory management Command mechanism

ObjectARX applications

Creating commands

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

(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 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

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
API ObjectARX APIs

.ARX .DLL

.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 From another application Registry

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.

Rxapi.lib

.ARX

4.

2.

Operating System

Wrong ARX Memory Management

AutoCAD/ObjectDBX
2.

3.

MSVCRT.DLL

CRASH!

Piece of Memory
1.

.ARX

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

AutoCAD/ObjectDBX
2. 3.

MSVCRT.DLL

Piece of Memory

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
1.
Rxheap.lib

4.
Piece of Memory

MSVCRT.DLL

3.
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
Process Monitor

www.dependencywalker.com or

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

www.sysinternals.com

2008 Autodesk

Command Mechanism I
AcEdCommandStack 2, 3.

1.
Callback function

.ARX

4.

5.
AcEdCommand

6.

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

Terminology
AutoCAD Session Document

Current Document

ObjectARX works with this in background User sees this in UI

Active Document

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 AutoCAD
Partners:
App 1 App 2 Corp. Dev. Other

ObjectARX Application
User Interface

Autodesk:
Inventor Revit Max

ObjectDBX
acdb18.dll acismobj18.lib axdb.lib Acgiapi.lib achapi18.lib acge18.lib
ObjEnabler1.dbx

Object Enablers

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

Design Object Data

DWG DXF

2008 Autodesk

Enabling Custom Objects w/o ACAD

DWG Client Apps.
Partners:
App 1 App 2 Corp. Dev. Other
ObjEnablerN.dbx

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

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

Max

axdb.lib acgiapi.lib

Design Object Data

DWG DXF

2008 Autodesk

Plug-In Model & ObjectDBX AutoCAD process

.ARX .DBX

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

rcexelib.obj

RealDWG
2008 Autodesk

Shared

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)

Pointer

Unique identifier of an object for the duration of a transaction

2008 Autodesk

Handles, Object IDs, Pointers

ObjectDBX session
1. 2.

.dwg

Object Closed
5.

4.

Open AcDbObject
3.

New AcDbObject

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 First element of ads_name

An AcDbObjectId

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 multiple writers are allowed read/write are NOT exclusive

Transaction model

Notify

2008 Autodesk

Used internally

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
Transaction 2 Transaction 1
obj1 obj2

2
obj2 obj3

obj1 AcDbDatabase

obj3

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

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
AcDbSymbolTable

AcDbLine

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
Inspector

C#
C++

ADN site
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 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
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
RTTI allows us to do this down-cast pointer safely get class descriptor is object derived from?

We might prefer a pointer to an AcDbPolyline

AcRxObject defines (in rxobject.h)

cast isA isKindOf

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)

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

AcDbBlockTable

AcDbLayerTable

AcDbDictionary Named Object Dict.

AcDbBlockTableRecord

AcDbLayerTableRecord

AcDbDictionary Company Dictionary *

AcDbLine

AcDbObject'

AcDbHardOwnershipId AcDbSoftOwnershipId

AcDbHardPointerId 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 Objects 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 AcDbObject

New AcDbObject

ObjectDBX Session

added

2008 Autodesk

Changing an Objects Identity II

AcDbObject::swapIdWith

Changes the object denoted by the object ID

id

id

AcDbObject
ObjectDBX Session
2008 Autodesk

AcDbObject

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

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

An AcDbObject

1. 2.

3.

ObjectDBX

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

ObjectDBX

Another AcDbObject

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
Undo Insert, Copy, Xref

kFileFiler
kUndoFiler kDeepCloneFiler + kIdXlateFiler

Wblock
Object paging

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:

WBLOCK

kFileFiler

SAVE
SAVEAS acdbEntGet

kFileFiler
kFileFiler kBagFiler

AutoCAD calls dxfIn which calls your dxfInFields function on:

OPEN INSERT acdbEntMod, acdbEntMake, acdbEntMakeX

kFileFiler kFileFiler

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

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

AcGiWorldGeometry
AcGiViewportGeometry

AcGiViewport
Legend: Inheritance Containment

2008 Autodesk

Graphics Acquisition
An AcGiWorldDraw
1.

4.

An AcGiDrawable
6.

3.

5. 2.

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

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

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
Msg loop

Doc1 prompts for user input 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

Current Lock

None 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 attach/detach observers Defines updating interface

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

observers

Observer Update()

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

ConcreteSubject subjectState

ConcreteObserver Update() observerState

2008 Autodesk

Notification
Observer pattern interaction diagram
3.

A ConcreteSubject

4.

A ConcreteObserver

2. Client

1.

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

1.

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
Another AcDbObject An AcDbDatabase

Observers (reactors)
An AcDbDatabaseReactor

Subjects

An AcDbObject

An AcDbObjectReactor

The AcDbLayoutManager The AcDbTransactionManager

An AcDbLayoutManagerReactor An AcTransactionReactor

The AcRxEvent
The AcRxDynamicLinker ObjectDBX
2008 Autodesk

An AcRxEventReactor
An AcRxDLinkerReactor

AutoCAD
The AcDbSummaryInfoManager

Observers (reactors)
An AcDbSummaryInfoReactor

The AcGsManager
The AcApProfileManager

An AcGsReactor
An AcApProfileManagerReactor An AcEdInputPointFilter

Subjects

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