ObjectARX 2010 and

AutoCAD .NETAutodesk Developer Technical Services

© 2008 Autodesk

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 APIsAutoCAD: Hello.arxObjectDBX: StructureObjectDBX: Extend it!AutoCAD: Multi-Document EnvironmentNotification 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

1. Source code 2. Static library3. DLL 4. EXE

SomeApp.exeATL templates

API1

Static MFC LibraryAPI

2

Win 32 API DLLsAPI

3

Client EXE, DLL, script, etc.

API4

© 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

.EXE

.DLL .DLL

API

AutoCAD

.ARX

.ARX

ObjectARX APIs

© 2008 Autodesk

Forms of Client Code

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

SLOW

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

AutoCAD

ObjectDBX3D graphicscache

dwg

HEID

I

2D graphicscache (WHIP!)P

lotH

DI

Dis

pla

ydri

ver

Plo

tter

dri

ver

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)

Input acquisition

Input

dri

ver

© 2008 Autodesk

API Implementation II

AutoCAD

ObjectARX APIs

axdb.dll

vl.arx

Lispscript

COM

acvba.arx

VBAscript

COM Client(VB, Java, Delphi)

Acdbmgd.dllAcmgd.dll

.NET

© 2008 Autodesk

Old API Performance ComparisonS.0.58 production

AutoCAD API Performance

S.0.58 prod Create 1000 Circles Create 1000 lines Update 1000 Circles Add XData to 1000 Entities Create 1000 2dPolylines Total

COM (VB) 24.70 23.75 7.14 9.73 26.79 92.11

COM (VBA) 1.40 1.34 0.62 2.24 4.22 9.82

LISP 3.76 3.58 4.63 6.08 28.04 46.08

ObjectARX 0.29 0.26 0.13 1.12 2.81 4.62

CO

M (

VB

)

CO

M (

VB

A)

LIS

P

Ob

jectA

RX Create 1000 Circles

Create 1000 lines

Update 1000 Circles

Add XData to 1000 Entities

Create 1000 2dPolylines

Total

0.00

10.00

20.00

30.00

40.00

50.00

60.00

70.00

80.00

90.00

100.00

Se

co

nd

s

AutoCAD's APIs

Machine profile:CPU: Pentium 150 MHz

RAM: 64 MB

S.0.58 API Performance

Create 1000 Circles

Create 1000 lines

Update 1000 Circles

Add XData to 1000 Entities

Create 1000 2dPolylines

Total

© 2008 Autodesk

Different Programming Techniques

0

50

100

150

200

250

300

350

400

Xrecord Custom Object Xdata

ObjectARX

.NET

LISP

How to Store Your Data in AutoCAD

Data Container Performance Chart

Tim

e in

sec

onds

© 2008 Autodesk

How to Store Your Data in AutoCAD

Different Programming Techniques

0

20000

40000

60000

80000

100000

120000

140000

Xrecord Xdata

ObjectARX

.NET

LISP

VBA

VB

Data Container Performance Chart

Tim

e in

sec

onds

© 2008 Autodesk

Different Programming Techniques

0

1000

2000

3000

4000

5000

Xrecord CustomObject

ObjectARX

.NET

VBA

LISP

How to Store Your Data in AutoCAD

Data Container Performance Chart

Tim

e in

sec

onds

© 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

Overview of APIsAutoCAD: Hello.arxObjectDBX: StructureObjectDBX: Extend it!AutoCAD: Multi-Document EnvironmentNotification System

Agenda

© 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

.EXE

.DLL .DLL

API

acrxEntryPoint acrxGetApiVersion

AutoCAD

.ARX

.ARX

ObjectARX APIs

© 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

1. LoadLibrary2. _DllMainCRTStartup (see MSDN for info)3. CRT_INIT (constructs global class vars)4. DllMain (see MSDN for info)

5. acrxGetApiVersion6. acrxEntryPoint

.ARXAutoCAD

Operating System

1. 2.

3.

5.

6.

Rxapi.lib

CRT 4.

© 2008 Autodesk

Wrong ARX Memory Management

1. .ARX allocates memory from debug heap2. .ARX passes allocated memory to AutoCAD3. AutoCAD de-allocates it with release ‘delete’…

CRASH

AutoCAD/ObjectDBX MSVCRT.DLL

.ARX MSVCRTD.DLL

Piece of Memory

1.

2.

3.

CRASH!

© 2008 Autodesk

3.

.ARX

Correct ARX Memory Management I

AutoCAD/ObjectDBX

1. .ARX allocates memory from release heap2. .ARX passes allocated memory to AutoCAD3. AutoCAD de-allocates it with release ‘delete’… OK

MSVCRT.DLL

Piece of Memor

y

1.

2.

© 2008 Autodesk

Correct ARX Memory Management II

AutoCAD/ObjectDBX

1. .ARX allocates memory via rxheap.lib2. AutoCAD allocates memory on release heap3. .ARX passes memory to AutoCAD4. AutoCAD de-allocates it with release ‘delete’… OK

MSVCRT.DLL

.ARXRxheap.lib

1. 3.

4.

Piece of Memory

2.

Libcm

t.lib

© 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

1. Add command2. Create command object

3. Parameterize it

4. User types command name5. Lookup command object

6. Call callback function

AcEdCommandStack

AutoCAD

.ARX

Callbackfunction

AcEdCommand

2, 3. 6.

4.

5.

1.

© 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 Wizardetc.

Visual Studio Add-In ObjectARX Commands Autodesk Class Exploreretc.

© 2008 Autodesk

Lab - Step 2

Play around with user input functions

© 2008 Autodesk

Agenda

Overview of APIsAutoCAD: Hello.arxObjectDBX: StructureObjectDBX: Extend it!AutoCAD: Multi-Document EnvironmentNotification System

© 2008 Autodesk

Terminology

AutoCAD SessionDocument

Current Document ObjectARX works with this in background

Active Document User sees this in UI

DrawingDatabase

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

Design Object Data

DWG DXF

DWG Client Apps

ObjectDBX

axdb.lib

acdb18.dll

acismobj18.lib acge18.lib

achapi18.lib

acis.dll(s)

Acgiapi.lib others...

Object Enablers

ObjEnabler3.dbx

ObjEnabler2.dbx

ObjEnabler1.dbx

ObjEnablerN.dbx

AutoCAD

App 1

Partners:

App 2

Corp. Dev.

Other

Autodesk:

Inventor

Revit

Max

ObjectARXApplication

User Interface

© 2008 Autodesk

Enabling Custom Objects w/o ACAD

DWG Client Apps.

Autodesk:

Inventor

Revit

Max

Design Object Data

DWG DXF

App 1

Partners:

App 2

Corp. Dev.

Other

ObjectDBX

axdb.lib

acdb18.lib

acISMobj.lib acge18.lib

achapi18.lib

acis.dll(s)

acgiapi.lib others...

Object Enablers

ObjEnabler3.dbx

ObjEnabler2.dbx

ObjEnabler1.dbx

ObjEnablerN.dbx

© 2008 Autodesk

Plug-In Model & ObjectDBX

ObjectDBX DLLs

AutoCAD process

Acad.exe & other AutoCAD specific DLLs

.ARX .DBX

© 2008 Autodesk

ObjectARX & ObjectDBX

ObjectDBX ObjectARX SDK

acad.libacedapi.libacui18.libadui18.liboleaprot.libAcTc.libAcTcUI.lib…

Shared

acdb18.libacge18lib

acgiapi.lib

axdb.libachapi18.librxapi.libacismobj18.librxheap.lib…

rcexelib.obj

RealDWG

© 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

1. Object read from file Handle Object ID2. Object opened Object ID Pointer3. New object added to database New Object ID & Handle assigned4. Object closed Pointer becomes invalid 5. Object saved to file Handles are written to disk

ObjectDBX session

.dwgObjectClosed

OpenAcDbObject

1.2.

4.5.

NewAcDbObject

3.

© 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. Client starts Trans1 and gets Obj1 & Obj22. Client starts Trans2 and gets Obj2 & Obj33. 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

obj1 obj2Transaction 1

1

obj1 obj2

obj1 obj3

obj2

obj1

obj2

obj3

obj2AcDbDatabase

obj2 obj3Transaction 2

2 3 4

obj1 obj3

obj2

obj2 obj3

© 2008 Autodesk

Getting an AcDbDatabase Object

Construct one In memory

Get the one currently active in AutoCADacdbHostApplicationServices()->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 ClassesAcRxObject

AcDbObject

AcDbEntity

AcDbDictionary

AcDbSymbolTable

AcDbSymbolTableRecord

AcGiDrawable

Database resident objects

Drawable objects

AcDbCurve

AcDbLine

AcDbBlockTable

© 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

iterator1

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

Client1 Client2

Aggregate

Stores ‘where we are’

iterator1

© 2008 Autodesk

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

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?

© 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

Another AcDbLine

An AcRxClass for

AcDbCurve

An AcRxClass for

AcDbLine

An AcRxClass for

AcDbCircle

Runtime classhierarchy

An AcRxClass for

AsdkCircle

An AsdkCircle

A protocol extension

objectPseudo

constructor

.DBX/.ARX App

© 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

AcDbBlockTableRecord

AcDbLayerTable

AcDbLayerTableRecord

AcDbDictionaryNamed Object Dict.

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

OpenAcDbObject

NewAcDbObject

ObjectDBX Session

removed

added

© 2008 Autodesk

Changing an Object’s Identity II

ObjectDBX Session

AcDbObject::swapIdWith

Changes the object denoted by the object ID

AcDbObject AcDbObject

idid

© 2008 Autodesk

Lab - Step 4

Accessing object containers

Dictionaries

© 2008 Autodesk

Agenda

Overview of APIsAutoCAD: Hello.arxObjectDBX: StructureObjectDBX: Extend it!AutoCAD: Multi-Document EnvironmentNotification 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 AcDbObject

1. Object implementing filer protocol created2. Filer is passed to the database object3. Database object calls back into the filer

ObjectDBX

AnotherAcDbObject

An AcDbDwgFiler

1.

3.

3.2.

2.

© 2008 Autodesk

AnotherAcDbObject

An AcDbDwgFiler

Filing In

ObjectDBX

1. Class identifier is read from filer2. Class is instantiated by AcRxClass class factory3. Filer is passed to the newly created object4. Database object calls back into the filer

1.

4.

4.

3.

3.

An AcDbObject2.

2.

© 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

Graphics data Object data

C

lass

ID

Cla

ss ID

Used to draw proxy graphics

Only inter-object references are interpreted

© 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

AcGiContextAcGiCommonDraw

AcGiWorldDraw

AcGiViewportDraw

AcGiViewport

AcGiSubentityTraits

AcGiGeometry

AcGiWorldGeometry

AcGiViewportGeometry

Legend:InheritanceContainment

© 2008 Autodesk

Graphics Acquisition

1. Host creates object implementing AcGiWorldDraw2. Host creates object implementing AcGiViewportDraw3. Host passes world-draw object to your drawable4. Drawable draws viewport independent graphics5. Host passes viewport-draw object to your drawable6. Drawable draws viewport dependent graphics

An AcGiDrawableAn AcGiWorldDraw

1.

4.

2.An AcGiViewportDraw

3.6.

5.

Host Application

© 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

correct wrong

© 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 APIsAutoCAD: Hello.arxObjectDBX: StructureObjectDBX: Extend it!AutoCAD: Multi-Document EnvironmentNotification 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

Cmd started in Doc1

Doc1 prompts for user input

User switches to Doc2, starts

cmd

Cmd completesin Doc2

App Fiber Doc1 FiberDoc2 Fiber

Time

Msg loop

Msg loop

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

Cu

rren

t L

ock

New Lock Request(from another context)

XWrite Write Read AWrite

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 APIsAutoCAD: Hello.arxObjectDBX: StructureObjectDBX: Extend it!AutoCAD: Multi-Document EnvironmentNotification System

© 2008 Autodesk

Notification System

Observer Pattern Implementation

Subjects & Observers

ObjectDBX

AutoCAD

Acting as an Observer

Acting as a Subject

© 2008 Autodesk

Notification

SubjectObserver

ConcreteSubject

ConcreteObserver

observers

Update()

Update()

Attach(Observer)Detach(Observer

)SendNotification(

)

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

subjectState

Observer pattern class diagram

1. Knows its observers2. Provides interface to attach/detach observers

Defines updating interface

observerState

© 2008 Autodesk

Notification

A ConcreteSubject

1. Client creates observer2. Client attaches observer to subject3. Subject changes state and fires notification to observer4. Observer learns details of state change

Client

A ConcreteObserver

1.2.

3.

4.

Observer pattern interaction diagram

© 2008 Autodesk

Notification Example

An AcDbLine

1. Client creates your custom object2. Client calls addPersistentReactor on the AcDbLine3. Changing AcDbLine sends objectModified notification4. Your custom object looks at the line to find out what changed

Client

Your custom object

1.2.

3.

4.

Interaction diagram

© 2008 Autodesk

ObjectDBX

ObjectDBX

An AcDbDatabase

An AcDbDatabaseReactor

An AcDbObject An AcDbObjectReactor

The AcRxEvent An AcRxEventReactor

The AcRxDynamicLinker An AcRxDLinkerReactor

Another AcDbObject

The AcDbLayoutManager An AcDbLayoutManagerReactor

The AcDbTransactionManager An AcTransactionReactor

Su

bje

cts

Observers (reactors)

© 2008 Autodesk

AutoCAD

AutoCAD

The AcApLongTransactionManager An AcApLongTransactionReactor

The AcApDocumentManager An AcApDocManagerReactor

The AcEditor An AcEditorReactor

The AcEdInputPointManager

An AcEdInputContextReactor

An AcEdInputPointMonitor

An AcEdInputPointFilter

The AcApProfileManager An AcApProfileManagerReactor

An AcGsReactor The AcGsManager

The AcDbSummaryInfoManager An AcDbSummaryInfoReactor

Su

bje

cts

Observers (reactors)

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