ObjectARX_2010_-_Marat_2009-06-01_FINAL
Transcript of ObjectARX_2010_-_Marat_2009-06-01_FINAL
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!