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

- ObjectARX labs - .NET labs - ObjectARX snoop tool

2008 Autodesk

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

2008 Autodesk

API Overview
A general look at APIs
  

Types of API Client/Server interaction Client code

AutoCADs APIs and IDEs

 

Implementation Comparison

2008 Autodesk

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

Implement service entry points Call services properly

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

Static library DLL EXE

2008 Autodesk

API Packaging
Client EXE, DLL, script, etc.
4

ATL templates

API

API

SomeApp.exe
3

API

Static MFC Library

API
Win 32 API DLLs

1. Source code 3. DLL

2008 Autodesk

2. Static library 4. EXE

Client/Server Interaction
In process


Client/server is in the same process

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 Pre-processed, semi interpreted code Compiled Visual LISP Compiled into IL Processor instructions ObjectARX

Packaged code (p-code)

 

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!) Plotter driver Display 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 COM Client
(VB, Java, Delphi)

Acdbmgd.dll Acmgd.dll

vl.arx

acvba.arx

axdb.dll
ObjectARX APIs COM

AutoCAD

2008 Autodesk

ObjectARX

0.29

0.26

0.13

1.12

2.81

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

M CPU

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

Create 1

Create 1

Update 1

AutoCAD's APIs
2008 Autodesk

Add XDa Total

Create 1

How to Store Your Data in AutoCAD

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

Time in seconds

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 Prompting for user input

ObjectARX applications
  

Creating commands
 

ObjectARX Wizards

2008 Autodesk

What is ObjectARX?
AutoCAD Runtime eXtension
  

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

A framework?
 

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

Custom entities Reactors ...

2008 Autodesk

What can I do with ObjectARX?

Modify and extend the drawing database
 

Create/modify/erase objects Create new types of objects

Modify AutoCADs user interface

    

Commands Toolbars/dialogs Properties Window Design Center Display system

Monitor/Modify AutoCADs standard behavior

 

Event notifications Input point acquisition

2008 Autodesk

Getting the ObjectARX SDK

Download - Free
On Autodesk public web site Developer Center - ObjectARX
(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 Startup

  

Demand loaded


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

  

On command invocation


On request


On proxy detection


Live Enablers (see PolySamp)

2008 Autodesk

Loading ObjectARX Applications II

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

5. 6.

Rxapi.lib

.ARX 2.

4.

Operating System

Wrong ARX Memory Management

AutoCAD/ObjectDBX
2.

3.

MSVCRT.DLL

CRASH! .ARX

Piece of Memory
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

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 Dependency Walker Process Monitor

\ObjectARX 2010\samples\database\ARXDBG www.dependencywalker.com or

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

www.sysinternals.com

2008 Autodesk

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

6.

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

Open AcDbObject
3.

New AcDbObject

1. Object read from file

Handle Object ID Object ID Pointer

2. Object opened 3. New object added to database

New Object ID & Handle assigned

4. Object closed
Pointer becomes invalid

5. Object saved to file

Handles are written to disk
2008 Autodesk

Object ID and Entity Name

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


Array of two longs First element of ads_name

An AcDbObjectId


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

2008 Autodesk

Open Modes
Read


255 simultaneous readers Open/Close model

 

Write


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 AcDbTransactionManager::startTransaction AcTransaction::getObject AcDbTransactionManager::end/abortTransaction

Transaction
  

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 obj2

obj3

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 AcDbBlockTable AcDbSymbolTableRecord Database resident objects Drawable objects AcDbLine

2008 Autodesk

Snoop Tools for the AutoCAD Database

Tool Language Where to find

ArxDbg MgdDbg Inspector

C++ C# C++

ObjectARX Samples ADN site ADN site

2008 Autodesk

Important Objects
Block Table  Three default records
 

*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 cast isA isKindOf down-cast pointer safely get class descriptor is object derived from?

We might prefer a pointer to an AcDbPolyline



AcRxObject defines (in rxobject.h)

  

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

AcRxClass I (Overview)
Three roles:
  

Runtime type identification Class factory Protocol extension

 

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

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

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

Extension Dictionary

Model Space BTR Entries

Extension Dictionaries

Hard pointer examples

 

Entity Text

Linetype Style

2008 Autodesk

Inter-Object References
Soft owner examples


Dictionary

Entries Entities

(can be made hard owner)



Symbol Tables

(except model and paper space which are hard)

Soft pointer example

 

Entity Object

Xdata Entity Handle Persistent Reactor

2008 Autodesk

Soft/Hard References
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 Wblock Object paging

kFileFiler kUndoFiler kDeepCloneFiler + kIdXlateFiler kWblockCloneFiler + kIdXlateFiler kPageFiler

2008 Autodesk

Filing Member Functions - II

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

Save/SaveAs Wblock Insert, Xref

kFileFiler kWblockCloneFiler + kIdXlateFiler kDeepCloneFiler + kIdXlateFiler

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

2008 Autodesk

Filing Member Functions - III

AutoCAD calls dxfOut which calls your dxfOutFields function on:
   

WBLOCK SAVE SAVEAS acdbEntGet

kFileFiler 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 AcGiViewport
Legend: Inheritance Containment

AcGiWorldGeometry AcGiViewportGeometry

2008 Autodesk

Graphics Acquisition
4.

An AcGiWorldDraw

An AcGiDrawable
6.

1.

3. 5.

Host Application
2.

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

2008 Autodesk

Document Locking
Document-level transaction
 

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

Provides synchronization, avoids data corruption Provides rollback (undo)

2008 Autodesk

Lock Types
New Lock Request
(from another context)

XWrite Write Read AWrite Current Lock None Read Write XWrite AutoWrite

v v v

v v

v v v v

2008 Autodesk

Document vs. Application

Document context
 

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



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 observers Defines updating interface

Observer Update()

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

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

ConcreteSubject subjectState

ConcreteObserver Update() observerState

2008 Autodesk

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 The AcRxEvent The AcRxDynamicLinker ObjectDBX

An AcDbLayoutManagerReactor An AcTransactionReactor An AcRxEventReactor An AcRxDLinkerReactor

2008 Autodesk

AutoCAD
The AcDbSummaryInfoManager The AcGsManager The AcApProfileManager

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