ObjectARX 2016

Developer Technical Services

Developer Technical Services
Worldwide Workgroup
Over 25 Specialists World Wide
Virtually 24 hour support, 5 days a week

Americas Team
US (CA, AZ, WA), Canada, Brazil

European Team
Switzerland, United Kingdom, France, Russia

APac Team
China, Japan, India
Getting Support
http://www.autodesk.com/adn-devhelp
Provides access to
On-line knowledge base
Call submission
Newsgroups

Calls are logged automatically

1-3 day turnaround
Callbacks as needed

Answers to frequently asked questions are posted in our on-

line knowledge base
Course Objective

It is to understand:
The fundamentals of ObjectARX
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
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
Class Schedule
Time : 9:30 AM - 5:30 PM
Lunch 12:00 PM - 1:00 PM

Day 1
Overview of APIs
AutoCAD: Hello.arx
Lab : Step 1 + Step 2

Day 2
ObjectDBX: Structure
ObjectDBX: Extend it!
Lab : Step 3 + Step 4 + Step 5 + Step 6

Day 3
AutoCAD: MDE
Notification System
Lab : Step 7
 Training Material

ObjectARX.pptx - this presentation

objectarx_2016_win_64_and_32bit.exe - ObjectARX
installation file
ArxDbg - ObjectARX snoop tool
Agenda

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

A general look at APIs

Types of API
Client/Server interaction
Client code

AutoCADs APIs and IDEs

Implementation
Comparison
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
API Packaging

Client EXE, DLL, script, etc.

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

1. Source code 2. Static library

3. DLL 4. EXE
 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
 The Plug-In Architecture

API is implemented by an exe

Client is implemented as a dll

.DLL
. ..DLL
ARX ARX
API
ObjectARX
APIs
.EXE
AutoCAD
Forms of Client Code

Interpreted code
SLO Source script
W AutoLISP in the past

Packaged code (p-code)

Pre-processed, semi interpreted code
Compiled Visual LISP

AutoCAD.NET
Compiled into IL

FAST Compiled code

Processor instructions
ObjectARX
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)

API Implementation II

.NET Lisp VBA COM Client

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

axdb.dll

ObjectARX APIs COM

AutoCAD
Old API Performance Comparison
S.0.58 production

AutoCAD API Performance

S.0.58 prod Create 1000 Circles Create 1000 line s Update 1000 Circle s Add XData to 1000 Entitie s Crea te 1000 2dPolylines Tota l

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

S.0.58 API Performance

100.00

90.00

80.00

70.00
S econds

60.00
Machine prof ile:
50.00 CPU: Pentium 150 MHz
RAM: 64 MB
40.00
Total
30.00
Create 1000 2dPolylines
20.00
Add XData to 1000 Entities
10.00 Update 1000 Circles
0.00 Create 1000 lines
C O M (V B )

C O M (V B A )

Create 1000 Circles

O b j e c tA R X
L IS P

Create 1000 Circles

Create 1000 lines
Update 1000 Circles

AutoCAD's APIs Add XData to 1000 Entities

Create 1000 2dPolylines
Total
How to Store Your Data in
AutoCAD
Different Programming Techniques

Data Container Performance Chart

Time in seconds
How to Store Your Data in
AutoCAD
Different Programming Techniques

Data Container Performance Chart

Time in seconds
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
Agenda

Overview of APIs
AutoCAD: Hello.arx
ObjectDBX: Structure
ObjectDBX: Extend it!
AutoCAD: Multi-Document Environment
Notification System
 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
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
...
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
 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/
http://
adn.autodesk.com/adn/servlet/index?siteID=481486
2&id=16619795&linkID=4900509
Binary compatibility
ObjectARX 2016
AutoCAD 2016

ObjectARX 2015
AutoCAD 2015 and 2016
Binary incompatible with earlier releases

ObjectARX 2014
AutoCAD 2014

ObjectARX 2013
AutoCAD 2013 and 2014
Binary incompatible with earlier releases

ObjectARX 2012
AutoCAD 2012

ObjectARX 2011
AutoCAD 2011 and 2012
Development Environment

For ObjectARX development

Microsoft Visual Studio 2012 SP1 with Update 4

ObjectARX 2016 SDK

Microsoft Windows WIN7 or better

ObjectARX SDK Contents

What comes with the SDK

Libraries and Header Files
Documentation
Samples
Utilities
Main Libraries - I

AcRx Object and Class Management (rxapi.lib)

AcDb AutoCAD Database (acdb20.lib)
AcGi AutoCAD Graphics Interface (acgiapi.lib)
AcGe AutoCAD Geometry Library (acge20.lib)
AutoCAD Core Library (accore.lib and ac1st20.lib)

32- and 64-bit versions:

C:\ObjectARX 2016\lib-win32 and
C:\ObjectARX 2016\lib-x64
Main Libraries - II

AcUi/AdUi MFC Extension Library (adui20.lib

acui20.lib)
Automation (axdb.lib)
ads_ Function Set (acad.lib)
Utilities

AutoCAD Facet Modeler (aecmodeler.lib)

AutoCAD Boundary Representation (acbr20.lib,

acgex20.lib)

ObjectARX Wizard
ArxWizards.msi downloadable from Developer Center
http://usa.autodesk.com/adsk/servlet/index?siteID=123112&id=
1911627

ATIL - Raster graphics

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)
Migration Guide (arxmgr.chm)
Interoperability Guide (arxiop.chm)
ObjectARX Readme (readarx.chm)

ObjectARX Training Material and Labs

ObjectARXLabs.chm downloadable from Developer Center
http://usa.autodesk.com/adsk/servlet/index?siteID=123112&id=1
911627
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 and visit ADN

Devblog.
.ARX = .DLL + 2 exported functions

acrxEntryPoint
acrxGetApiVersion

.DLL
. ..DLL
ARX ARX
API
ObjectARX
APIs
.EXE
AutoCAD
Loading ObjectARX Applications I

Loaded by the user

ARX & APPLOAD commands
Drag & Drop

Demand loaded
Startup
Registry
(arxload) in acad2015doc.lsp
On command invocation
Registry
On request
From another application
On proxy detection
Registry
Loading ObjectARX Applications
II
3.

Rxapi.lib
AutoCAD 5. 4.

CRT
.ARX

1. 6.
2.
Operating System
1. LoadLibrary
2. _DllMainCRTStartup (see MSDN for info)
3. CRT_INIT (constructs global class vars)
4. DllMain (see MSDN for info)
5. acrxGetApiVersion
6. acrxEntryPoint
Wrong ARX Memory Management

AutoCAD/ObjectDBX 3.
MSVCRT.DLL

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

1. .ARX allocates memory from debug heap

2. .ARX passes allocated memory to AutoCAD

3. AutoCAD de-allocates it with release delete

CRASH
Correct ARX Memory Management
3.
AutoCAD/ObjectDBX MSVCRT.DLL
Piece of
Memor
2. y

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

Visual C++ 11.0

AutoCAD 2016
ObjectARX 2016

ArxDbg \ObjectARX 2016\samples\database\ARXDBG

Dependency Walker www.dependencywalker.com

Process Monitor www.sysinternals.com
Command Mechanism I

.ARX
1.
AcEdCommandStack
3.
4. Callback
2 5. function
AcEdCommand

AutoCAD

1. Add command

2. Create command object

3. User types command name

4. Lookup command object

5. Call callback function

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=10750
06
Lab - Step 1

Setup your first .ARX

Prompting for User Input

AcEd functions
String, number acquisition : acedGetString(), acedGetInt()
Point, angle acquisition : acedGetPoint(), acedGetAngle()
Entity selection : acedEntSel()

Full range of Win32 controls

ObjectARX 2016 Wizards
Installer downloadable from Developer Center
Visual Studio ObjectARX wizards
COM Wrapper Wizard
Custom Object Wizard
Reactors Class Wizard
Jig wizard
Dynamic Property Wizard
etc.
Lab - Step 2

Play around with user input functions

Agenda

Overview of APIs
AutoCAD: Hello.arx
ObjectDBX: Structure
ObjectDBX: Extend it!
AutoCAD: Multi-Document Environment
Notification System
 Terminology
AutoCAD Session
Document
Current Document
ObjectARX works with this in background
Active Document
User sees this in UI
Drawing
Database
Working Database
acdbHostApplicationServices()->workingDatabase()
ObjectDBX: Introduction

What is ObjectDBX and RealDWG?

AutoCAD drawing database

Object identity
Transactions
Inter-object references
Important classes
Important objects
Storing data
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
DWG Viewers

No viewing available in RealDWG!

AutoCAD OEM
DWF
www.dwfit.com
Autodesk Design Review
DWG TrueView conversion of dwgs from old formats
Database Framework
Enabling Custom Objects w/o
ACAD
Plug-In Model & ObjectDBX

AutoCAD process

.ARX .DBX

Acad.exe &
other AutoCAD ObjectDBX DLLs
specific DLLs
 ObjectARX & ObjectDBX

ObjectDBX ObjectARX
SDK

acdb20.lib acad.lib
Acge20.lib acedapi.li
rcexelib.obj acgiapi.lib b
axdb.lib acui20.lib
achapi20.lib adui20.lib
rxapi.lib oleaprot.li
b
acismobj20.li AcTc.lib
b
rxheap.lib AcTcUI.lib

RealDWG
Share
d
What can I do with ObjectARX?

Create/Modify DWG/DXF files (.ARX)

Create object enabler DLLs (.DBX)

Cannot create standalone applications

this requires RealDWG
 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 canmodel
Relational encapsulate data
Object model
Tables Objects
Records Objects
Fields Data members (encapsulated)
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
Handles, Object IDs, Pointers
ObjectDBX session
1.
2.
Object Open New
.dwg Closed AcDbObject AcDbObject
4. 3.
5.

1. Object read from file

Handle Object ID
2. Object opened
Object ID Pointer
3. New object added to database
New Object ID & Handle assigned
4. Object closed
Pointer becomes invalid
5. Object saved to file
Handles are written to disk
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 );
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
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
Nesting AcTransactions

1 2 3 4
Transaction 2 obj2 obj3

Transaction 1 obj1 obj2

obj1 obj3
obj2
AcDbDatabas
e
1. Client starts Trans1 and gets Obj1 & Obj2
2. Client starts Trans2 and gets Obj2 & Obj3
3. Client commits Trans2
Trans2 changes are committed
4a. Client commits Trans1
Trans1 changes are committed
4b. Client aborts Trans1 instead
Trans1 (and Trans2) changes are rolled back
Getting an AcDbDatabase Object

Construct one
In memory

Get the one active in AutoCAD

acdbHostApplicationServices()->workingDatabase()
More on this in the AutoCAD: MDE section

Access some other open document

Open a new dwg file

AcDbDatabase Ownership
Hierarchy
Object Model Overview

classmap.dwg
in ObjectARX distribution
Important Classes
AcRxObject

AcGiDrawable

AcDbObject

AcDbEntity

AcDbCurve

AcDbDictionary AcDbLine

AcDbSymbolTable

AcDbBlockTable

AcDbSymbolTableRecord

Database resident objects

Drawable objects
Snoop Tools for the AutoCAD
Database
Tool Languag Where to find
e
ArxDbg C++ ObjectARX Samples
MgdDbg C# ADN site
Inspector C++ ADN site
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
AutoCADs symbol tables
Named Objects Dictionary
Dictionaries own any objects (but not entities)
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
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

Stores where
Client1 Client2 we a re

iterator1 iterator1

Aggregate

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

 RTTI Runtime Type
Identification
Object containers provide generic pointers to
AcDbObjects
AcDbEntities
We might prefer a pointer to an AcDbPolyline
RTTI allows us to do this
AcRxObject defines (in rxobject.h)
cast down-cast pointer safely
isA get class descriptor
isKindOf is object derived from?

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

Three roles:
Runtime type identification
Class factory
Protocol extension
Look for Protocol extension in developers guide.

AcRxClass is usually set up for a custom object via

macros in rxboiler.h
ACRX_DECLARE_MEMBERS(CLASS_NAME)
ACRX_DXF_DEFINE_MEMBERS

 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

AcRxClass III (Object Diagram)

Runtime class
An AcDbLine hierarchy An AcRxClass
for
AcDbCurve

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

A protocol
extension An AcRxClass
object for
Pseudo
.DBX/.ARX construct AsdkCircle
App or
 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
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
Lab - Step 3

Accessing object containers

Symbol tables
AcDbDatabase Ownership
Hierarchy
 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

Inter-Object References

AcDbDatabase

AcDbDictionary
AcDbBlockTable AcDbLayerTable
Named Object Dict.

AcDbDictionary
AcDbBlockTableRecord AcDbLayerTableRecord
Company Dictionary *

AcDbLine AcDbObject'

AcDbHardOwnershipId AcDbHardPointerId

AcDbSoftOwnershipId AcDbSoftPointerId
 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
 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
 Soft/Hard References

Save
Follows both types of ownership links
Wblock
Follows hard owner and hard pointer
references.
DeepClone
COPY, MIRROR, EXPLODE commands
Follows only ownership links
Purge
Soft references do not protect the object
from purge
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 New
AcDbObject AcDbObject

ObjectDBX Session added

Changing an Objects Identity II

AcDbObject::swapIdWith
Changes the object denoted by the object ID

id id

AcDbObject AcDbObject

ObjectDBX
Session
 Lab - Step 4

Accessing object containers

Dictionaries
Agenda

Overview of APIs
AutoCAD: Hello.arx
ObjectDBX: Structure
ObjectDBX: Extend it!
AutoCAD: Multi-Document Environment
Notification System
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
 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
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
Filing Out

An AcDbDwgFiler 3.
An AcDbObject

1.
3.
2.
Another
AcDbObject
ObjectDBX
2.

1. Object implementing filer protocol created

2. Filer is passed to the database object
3. Database object calls back into the filer
Filing In

An AcDbDwgFiler 4.
An AcDbObject
2.

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

1. Class identifier is read from filer

2. Class is instantiated by AcRxClass class factory
3. Filer is passed to the newly created object
4. Database object calls back into the filer
 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
 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 objects state and files it into another
object)
Purge kPurgeFiler
Object paging kPageFiler
Any Object modification kUndoFiler
for undo recording
 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
 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

 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
Proxy

A proxy object is created in memory when a

defining application is not available
Surrogate data holder for custom object

Class ID
Class ID

Graphics dataObject data

Only inter-object references are interpreted

Used to draw proxy graphics

Lab - Step 5

Creating a Custom Object

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
AcGi Class Diagram
AcGiContext
AcGiContext
AcGiCommonDraw
AcGiCommonDraw
AcGiSubentityTraits
AcGiSubentityTraits

AcGiGeometry
AcGiGeometry

AcGiWorldDraw AcGiWorldGeometry
AcGiWorldGeometry

AcGiViewportDraw
AcGiViewportDraw AcGiViewportGeometry
AcGiViewportGeometry

AcGiViewport

Legend:
Inheritance
Containment
Graphics Acquisition

4.
An AcGiWorldDraw An AcGiDrawable

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

1. Host creates object implementing AcGiWorldDraw

2. Host creates object implementing AcGiViewportDraw
3. Host passes world-draw object to your drawable
4. Drawable draws viewport independent graphics
5. Host passes viewport-draw object to your drawable
6. Drawable draws viewport dependent graphics
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
co g
rre n
ct ro
w
 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
 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
 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

 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)

Lab - Step 6

Creating a Custom Entity

Agenda

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

Documents

Per-document data

Current vs. Active Documents

Documents

State of the edit session

AcApDocument class encapsulates

AcDbDatabase viewed
XRefed databases
Selection sets
Most system variables

AcApDocManager holds the list of documents

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

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

Observer Pattern Implementation

Subjects & Observers
ObjectDBX
AutoCAD

Acting as an Observer
Acting as a Subject
 Notification
Observer pattern class diagram

1. Knows its observers

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

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

ConcreteSubje ConcreteObserver
ct Update
()
subjectState observerState
Notification
Observer pattern interaction diagram

3.
A ConcreteSubject 4. A ConcreteObserver

2. 1.

Client

1. Client creates observer

2. Client attaches observer to subject
3. Subject changes state and fires notification to
observer
4. Observer learns details of state change
Notification Example
Interaction diagram

3.
An AcDbLine 4.
Your custom object

2. 1.

Client

1. Client creates your custom object

2. Client calls addPersistentReactor on the AcDbLine
3. Changing AcDbLine sends objectModified notification
4. Your custom object looks at the line to find out what
changed
ObjectDBX
Observers (reactors)

Another AcDbObject An AcDbDatabaseReactor

An AcDbDatabase

An AcDbObject An AcDbObjectReactor
Subjects

The AcDbLayoutManager An AcDbLayoutManagerReactor

The AcDbTransactionManager An AcTransactionReactor

The AcRxEvent An AcRxEventReactor

The AcRxDynamicLinker An AcRxDLinkerReactor

ObjectDBX
 AutoCAD
Observers (reactors)

The AcDbSummaryInfoManager An AcDbSummaryInfoReactor

The AcGsManager An AcGsReactor

The AcApProfileManager An AcApProfileManagerReactor

Subjects

An AcEdInputPointFilter
The AcEdInputPointManager An AcEdInputPointMonitor
An AcEdInputContextReactor

The AcApLongTransactionManager An AcApLongTransactionReactor

The AcApDocumentManager An AcApDocManagerReactor

The AcEditor An AcEditorReactor

AutoCAD
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
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
Lab - Step 7

Observing various subjects

More API Resources
AutoCAD Developer Center - download training labs
http://www.autodesk.com/developautocad
Blogs
Through the Interface (AutoCAD.NET)
http://through-the-interface.typepad.com/through_the_interface/

AutoCAD DevBlog
http://adndevblog.typepad.com/autocad/

Whitepapers and Training Videos ADN members

http://adn.autodesk.com/adn/servlet/index?siteID=4814862&id=
5475217&linkID=4900509
Discussion Groups : http://discussion.autodesk.com

AutoCAD .NET Training (classroom)

http://www.autodesk.com/apitraining
Thank You !