AutoCAD .NET Developer's Guide

AutoCAD® Map 3D 2008

.NET Developer's Guide

Copyright© 2007 Autodesk, Inc.All Rights ReservedThis publication, or parts thereof, may not be reproduced in any form, by any method, for any purpose.AUTODESK, INC., MAKES NO WARRANTY, EITHER EXPRESS OR IMPLIED, INCLUDING BUT NOT LIMITED TO ANY IMPLIEDWARRANTIES OF MERCHANTABILITY OR FITNESS FOR A PARTICULAR PURPOSE REGARDING THESE MATERIALS, AND MAKES SUCHMATERIALS AVAILABLE SOLELY ON AN "AS-IS" BASIS.IN NO EVENT SHALL AUTODESK, INC., BE LIABLE TO ANYONE FOR SPECIAL, COLLATERAL, INCIDENTAL, OR CONSEQUENTIALDAMAGES IN CONNECTION WITH OR ARISING OUT OF ACQUISITION OR USE OF THESE MATERIALS. THE SOLE AND EXCLUSIVELIABILITY TO AUTODESK, INC., REGARDLESS OF THE FORM OF ACTION, SHALL NOT EXCEED THE PURCHASE PRICE, IF ANY, OFTHE MATERIALS DESCRIBED HEREIN.Autodesk, Inc., reserves the right to revise and improve its products as it sees fit. This publication describes the state of the product at the timeof publication, and may not reflect the product at all times in the future.

Autodesk TrademarksThe following are registered trademarks or trademarks of Autodesk, Inc., in the USA and other countries: 3DEC (design/logo), 3December,3December.com, 3ds Max, ActiveShapes, Actrix, ADI, Alias, Alias (swirl design/logo), AliasStudio, Alias|Wavefront (design/logo), ATC, AUGI,AutoCAD, AutoCAD Learning Assistance, AutoCAD LT, AutoCAD Simulator, AutoCAD SQL Extension, AutoCAD SQL Interface, Autodesk, AutodeskEnvision, Autodesk Insight, Autodesk Intent, Autodesk Inventor, Autodesk Map, Autodesk MapGuide, Autodesk Streamline, AutoLISP, AutoSnap,AutoSketch, AutoTrack, Backdraft, Built with ObjectARX (logo), Burn, Buzzsaw, CAiCE, Can You Imagine, Character Studio, Cinestream, Civil3D, Cleaner, Cleaner Central, ClearScale, Colour Warper, Combustion, Communication Specification, Constructware, Content Explorer,Create>what's>Next> (design/logo), Dancing Baby (image), DesignCenter, Design Doctor, Designer's Toolkit, DesignKids, DesignProf, DesignServer,DesignStudio, Design|Studio (design/logo), Design Your World, Design Your World (design/logo), DWF, DWG, DWG (logo), DWG TrueConvert,DWG TrueView, DXF, EditDV, Education by Design, Extending the Design Team, FBX, Filmbox, FMDesktop, GDX Driver, Gmax, Heads-upDesign, Heidi, HOOPS, HumanIK, i-drop, iMOUT, Incinerator, IntroDV, Kaydara, Kaydara (design/logo), LocationLogic, Lustre, Maya, MechanicalDesktop, MotionBuilder, ObjectARX, ObjectDBX, Open Reality, PolarSnap, PortfolioWall, Powered with Autodesk Technology, Productstream,ProjectPoint, Reactor, RealDWG, Real-time Roto, Render Queue, Revit, Showcase, SketchBook, StudioTools, Topobase, Toxik, Visual, VisualBridge, Visual Construction, Visual Drainage, Visual Hydro, Visual Landscape, Visual Roads, Visual Survey, Visual Syllabus, Visual Toolbox, VisualTugboat, Visual LISP, Voice Reality, Volo, and Wiretap.The following are registered trademarks or trademarks of Autodesk Canada Co. in the USA and/or Canada and other countries: Backburner,Discreet, Fire, Flame, Flint, Frost, Inferno, Multi-Master Editing, River, Smoke, Sparks, Stone, Wire.

Third Party TrademarksAll other brand names, product names or trademarks belong to their respective holders.

Third Party Software Program CreditsACIS Copyright © 1989-2001 Spatial Corp.Copyright © 1999-2000 The Apache Software Foundation. All rights reserved. This product includes software developed by the Apache SoftwareFoundation (http://www.apache.org) subject to its license terms and conditions (http://xml.apache.org/dist/LICENSE.txt).Typefaces from the Bitstream® typeface library Copyright © 1992.HLM © Copyright D-Cubed Ltd. 1996-2006. HLM is a trademark of D-Cubed Ltd.AutoCAD® 2008 and AutoCAD LT® 2008 are produced under a license of data derived from DIC Color Guide® from Dainippon Ink and Chemicals,Inc. Copyright © Dainippon Ink and Chemicals, Inc. All rights reserved. DIC and DIC Color Guide are registered trademarks of Dainippon Inkand Chemicals, Inc.Portions of this software are based on the work of the Independent JPEG Group.Active Delivery™ 2.0 © 1999-2004 Inner Media, Inc. All rights reserved.ISYS and the ISYS logo are registered trademarks or trademarks of ISYS® Search Software Inc.Copyright © 1988-1997 Sam Leffler. Copyright © 1991-1997 Silicon Graphics, Inc.Copyright © Lingea s.r.o. 2006.The New Features Workshop contains Macromedia Flash™ Player software by Macromedia, Inc. Copyright © 1995-2005 Macromedia, Inc. Allrights reserved. Macromedia® and Flash® are registered trademarks or trademarks of Adobe Systems Incorporated in the United States or othercountries.Copyright © 1996-2006 Macrovision Corporation. All rights reserved.Copyright © 1996-2006 Microsoft Corporation. All rights reserved.Copyright © 2002 Joseph M. O'Leary.PANTONE® Colors displayed in the software application or in the user documentation may not match -PANTONE-identified standards. Consultcurrent PANTONE Color Publications for accurate color.PANTONE® and other Pantone, Inc. trademarks are the property of Pantone, Inc. © Pantone, Inc., 2004.Pantone, Inc. is the copyright owner of color data and/or software which are licensed to Autodesk, Inc., to distribute for use only in combinationwith certain Autodesk software products. PANTONE Color Data and/or Software shall not be copied onto another disk or into memory unlessas part of the execution of this Autodesk software product.Typefaces from Payne Loving Trust © 1992, 1996. All rights reserved.RAL DESIGN © RAL, Sankt Augustin, 2004.RAL CLASSIC © RAL, Sankt Augustin, 2004.Representation of the RAL Colors is done with the approval of RAL Deutsches Institut für Gütesicherung und Kennzeichnung e.V. (RAL GermanInstitute for Quality Assurance and Certification, re. Assoc.), D-53757 Sankt Augustin.

This product includes code licensed from RSA Security, Inc. Some portions licensed from IBM are available at http://oss.software.ibm.com/icu4j/.The Sentry Spelling-Checker Engine Copyright © 1994-2003 Wintertree Software, Inc.Portions of this product include one or more Boost libraries. Use of the Boost libraries is subject to its license agreementhttp://www.boost.org/LICENSE_1_0.txt.

Stingray® is Copyright © 1995-2005, Quovadx, Inc. All Rights Reserved. Protected by copyright and licenses restricting use, copying, distributionand decompilation. The Rogue Wave name and logo and the Stingray name and logo are either registered trademarks or trademarks of Quovadx,Inc. in the United States and/or other countries.Xerces and Xalan are Copyright © 1999-2005, The Apache Software Foundation. Licensed under the Apache License, Version 2.0; you may notuse this file except in compliance with the license. You may obtain a copy of the license at the following web address:http://www.apache.org/licenses/LICENSE-2.0.Copyright © 1998-2006 The OpenSSL Project. All rights reserved.This product includes software written by Tim Hudson ([email protected]). This product includes cryptographic software written by Eric Young([email protected]). Copyright © 1995-1998 Eric Young ([email protected]). All rights reserved.ACE™ is copyrighted by Douglas C. Schmidt and his research group at Washington University, University of California, Irvine, and VanderbiltUniversity, Copyright ©1993-2006, all rights reserved.The Director General of the Geographic Survey Institute has issued the approval for the coordinates exchange numbered TKY2JGD for JapanGeodetic Datum 2000, also known as technical information No H1-N0.2 of the Geographic Survey Institute,to be installed and used within thissoftware product (Approval No.: 646 issued by GSI, April 8, 2002).MrSID image compression format is Copyright © 2005, LizardTech, a division of Celartem,Inc. All rights reserved.MrSID technology is protectedby U.S. Patent No 5,710,835 and patents pending.Portions of this computer program are Copyright © 2000 Earth Resource Mapping, Inc.The OSTN97 coordinate transformation is © Crown copyright 1997. All rights reserved.The OSTN02 coordinate transformation is © Crown copyright 2002. All rights reserved.The OSGM02 coordinate transformation is © Crown copyright 2002, © Ordnance Survey Ireland, 2002.FME Objects Engine Copyright © 2005 SAFE Software. All rights reserved.Libcurl is Copyright ©1996 - 2007, Daniel Stenberg, <[email protected]>. All rights reserved.The Redland RDF Application Framework is Copyright © 2000-2005 Institute for Learning and Research Technology, University of Bristol. Licensedunder the Apache License, Version 2.0; you may not use this file except in compliance with the license. You may obtain a copy of the licenseat the following web address: http://www.apache.org/licenses/LICENSE-2.0.GDAL is Copyright © 2000, Frank Warmerdam.Portions of sample data provided by NAVTEQ. Copyright © NAVTEQ 2001-2006, All rights reserved.

GOVERNMENT USEUse, duplication, or disclosure by the U.S. Government is subject to restrictions as set forth in FAR 12.212 (Commercial ComputerSoftware-Restricted Rights) and DFAR 227.7202 (Rights in Technical Data and Computer Software), as applicable.

Published By: Autodesk, Inc.111 Mclnnis ParkwaySan Rafael, CA 94903, USA

1 2 3 4 5 6 7 8 9 10

Contents

Chapter 1 Overview . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 1Introduction . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 2Using the API Reference . . . . . . . . . . . . . . . . . . . . . . . . . . 3Setting Up Visual Studio . . . . . . . . . . . . . . . . . . . . . . . . . . 3AutoCAD . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 6

Chapter 2 Session and Project . . . . . . . . . . . . . . . . . . . . . . . . . 9Overview . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 10Drawing Objects . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 12

Chapter 3 Object Data . . . . . . . . . . . . . . . . . . . . . . . . . . . . 15Introduction . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 16Creating a Table . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 17Attaching Object Data . . . . . . . . . . . . . . . . . . . . . . . . . . . 18Getting Object Data . . . . . . . . . . . . . . . . . . . . . . . . . . . . 19Updating and Deleting Records . . . . . . . . . . . . . . . . . . . . . . 21

Chapter 4 Annotation . . . . . . . . . . . . . . . . . . . . . . . . . . . . 23Overview . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 24Annotation Templates . . . . . . . . . . . . . . . . . . . . . . . . . . . 24Expressions in Annotations . . . . . . . . . . . . . . . . . . . . . . . . 27Inserting Annotations . . . . . . . . . . . . . . . . . . . . . . . . . . . 28

v

Updating and Refreshing Annotations . . . . . . . . . . . . . . . . . . 29Annotation Overrides . . . . . . . . . . . . . . . . . . . . . . . . . . . 29

Chapter 5 Events . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 31Overview . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 32Events in the API Reference . . . . . . . . . . . . . . . . . . . . . . . . 32List of Events . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 34

Chapter 6 Drawing Sets . . . . . . . . . . . . . . . . . . . . . . . . . . . 43Overview . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 44Drive Aliases . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 44Attaching and Detaching Drawings . . . . . . . . . . . . . . . . . . . . 44

Chapter 7 Queries and Save Sets . . . . . . . . . . . . . . . . . . . . . . . 47Overview . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 48Queries . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 48Query Libraries . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 51Save Sets . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 51

Chapter 8 Classification . . . . . . . . . . . . . . . . . . . . . . . . . . . 53Overview . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 54Managing Feature Definition Files . . . . . . . . . . . . . . . . . . . . 54Creating Feature Class Definitions . . . . . . . . . . . . . . . . . . . . 55Classifying Objects . . . . . . . . . . . . . . . . . . . . . . . . . . . . 57

Chapter 9 Filters . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 59Overview . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 60Basic Filters . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 60Custom Filters . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 60

Chapter 10 Import/Export . . . . . . . . . . . . . . . . . . . . . . . . . . . 61Overview . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 62Importing . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 62Exporting . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 63

Chapter 11 Topology . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 65Overview . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 66Drawing Cleanup . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 67Creating Topologies . . . . . . . . . . . . . . . . . . . . . . . . . . . . 70Node Topology . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 70Network Topology . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 70Polygon Topology . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 71

vi | Contents

Chapter 12 Display Manager . . . . . . . . . . . . . . . . . . . . . . . . . 73Overview . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 74Elements . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 74Data Source Descriptors . . . . . . . . . . . . . . . . . . . . . . . . . . 76Style . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 79

Chapter 13 MapBook . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 81Overview . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 82MapBook Templates . . . . . . . . . . . . . . . . . . . . . . . . . . . . 82Creating a Map Book . . . . . . . . . . . . . . . . . . . . . . . . . . . 83

Index . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 85

Contents | vii

viii

Overview

In this chapter

■ Introduction

■ Using the API Reference

■ Setting Up Visual Studio

■ AutoCAD

1

1

IntroductionThe AutoCAD® Map 3D 2008 .NET API provides access to AutoCAD Map 3Dfunctionality so you can modify and extend it for your own purposes. TheAPI can be used by any .NET language.

The snippets in this guide are mainly in VB.NET, but most samples are availablein VB.NET, C#, and C++.

Some of the short snippets in this guide write to the AutoCAD Map 3D console.Ensure that the console is visible. Press CTRL+9 to display the or hide console.

Namespaces

The Autodesk.Gis.Map namespace contains the .NET classes for AutoCADMap 3D. Some of the general-purpose classes are defined directly within thetop-level Autodesk.Gis.Map namespace, but most are grouped into lower-levelnamespaces below Autodesk.Gis.Map.

For the sake of cleaner code, all examples within this guide will assume thefollowing Imports:

Imports Autodesk.Gis.Map

Imports Autodesk.AutoCAD.DatabaseServices

Imports Autodesk.AutoCAD.ApplicationServices

In this guide, objects from namespaces within Autodesk.Gis.Map are partiallyqualified. For example, the Table class in the Autodesk.Gis.Map.ObjectDatanamespace is generally given as ObjectData.Table. This makes it simple tofind the class details in the API Reference.

Certain chapters may define additional imports. For example, the chapterabout Object Data defines

Imports Autodesk.Gis.Map.ObjectData

Related Documentation

AutoCAD Map 3D 2008 includes the new Geospatial Platform API for workingwith geospatial data. See the Geospatial Platform Developer’s Guide for details.

2 | Chapter 1 Overview

Using the API ReferenceThe API reference applies to multiple languages. Because of differences betweenlanguages, the terms and syntax used in the reference may not match a givenlanguage. Some differences are:

C#VB.NETAPI Ref

abstractMustInherit__abstract

sealedNotInheritable__sealed

__gc

..::

NullNothingNULL

This guide uses VB.NET for most examples. The sample applications areavailable in VB.NET, C#, and C++;

Setting Up Visual StudioThe AutoCAD Map 3D SDK requires Microsoft Visual Studio 2005. To set upa project for a custom application, open the project properties.

NOTE These instructions apply to VB.NET. Setting up a project for C# is slightlydifferent.

On the Application tab, set the application type to Class library.

Add the following references. The DLLs are in the AutoCAD Map 3Dinstallation folder:

■ acdbmgd.dll

■ acmgd.dll

■ ManagedMapApi.dll

Using the API Reference | 3

acdbmgd.dll contains the following AutoCAD namespaces:

■ Autodesk.AutoCAD.Colors

■ Autodesk.AutoCAD.ComponentModel

■ Autodesk.AutoCAD.DatabaseServices

■ Autodesk.AutoCAD.DatabaseServices.Filters

■ Autodesk.AutoCAD.Geometry

■ Autodesk.AutoCAD.GraphicsInterface

■ Autodesk.AutoCAD.GraphicsSystem

■ Autodesk.AutoCAD.LayerManager

■ Autodesk.AutoCAD.Runtime

acmgd.dll contains the following AutoCAD namespaces:

■ Autodesk.AutoCAD.ApplicationServices

■ Autodesk.AutoCAD.EditorInput

■ Autodesk.AutoCAD.GraphicsSystem

■ Autodesk.AutoCAD.PlottingServices

■ Autodesk.AutoCAD.Publishing

■ Autodesk.AutoCAD.Runtime

■ Autodesk.AutoCAD.Windows

■ Autodesk.AutoCAD.Windows.ToolPalette

ManagedMapApi.dll contains the following AutoCAD Map 3D namespaces:

■ Autodesk.Gis.Map

■ Autodesk.Gis.Map.Annotation

■ Autodesk.Gis.Map.Classification

■ Autodesk.Gis.Map.Constants

■ Autodesk.Gis.Map.DisplayManagement


■ Autodesk.Gis.Map.Filters

■ Autodesk.Gis.Map.ImportExport

■ Autodesk.Gis.Map.MapBook

■ Autodesk.Gis.Map.ObjectData

■ Autodesk.Gis.Map.Project

■ Autodesk.Gis.Map.Query

■ Autodesk.Gis.Map.Topology

■ Autodesk.Gis.Map.Utilities

For each of the references, set the Copy Local property to False. Double-clickthe reference to open the properties.

Set the reference path to the AutoCAD Map 3D installation directory.

On the Debug tab, set:

■ Start external program: InstallDir\acad.exe, where InstallDir is theinstallation directory for AutoCAD Map 3D.

■ Working directory: InstallDir\UserDataCache\

Running AutoCAD Map 3D Custom Applications

Every custom application requires at least one subroutine that can be calledfrom AutoCAD Map 3D. Identify this using the CommandMethod attribute. Forexample, using VB.NET the syntax is:

<CommandMethod("CustomCommand")> _

Public Sub CommandSub()

Using C# the syntax is:

[CommandMethod("CustomCommand")]

public void CommandSub();

To run a custom application, type the NETLOAD command at the AutoCADMap 3D command prompt. Browse to the DLL containing the customapplication assembly. Open the assembly. This makes any custom commandsdefined using the CommandMethod attribute available to the AutoCAD Map 3Dsession.

Setting Up Visual Studio | 5

To execute a command, type the command method at the command prompt.In the example above, this would be

CustomCommand

For more details, refer to the AutoCAD documentation.

AutoCADAutoCAD Map 3D relies on AutoCAD for much of its functionality. It isimportant to understand some basic AutoCAD concepts before writingAutoCAD Map 3D applications. For complete details, refer to the AutoCADdeveloper documentation.

In particular, managing objects in the AutoCAD database is important.

Transactions

The AutoCAD database uses a transaction model for access to all objects.

To use any object in the database, start a transaction and use the transactionto open the database object in either read-only or read-write mode.Transaction.Open() returns a generic reference. Cast that to the type of objectbeing returned. For example, given a database object id for a MapBook object,the following will return a reference to the object:

Dim bookObj As MapBook.Book

bookObj = CType(trans.GetObject(mapBookId, OpenMode.ForWrite),

MapBook.Book)

Short examples in this guide may not include all the transaction processing,so they can highlight the concepts being discussed. In all cases, though, if anychanges are being made to the drawing, it should be assumed that thefollowing general structure is in place:


Dim trans As Transaction = Nothing

Dim docs As DocumentCollection = Application.DocumentManager

Dim activeDoc As Document = docs.MdiActiveDocument

Try

trans = activeDoc.TransactionManager.StartTransaction()

'

' Open object(s)

'

Dim bookObj As MapBook.Book

bookObj = CType(trans.GetObject(mapBookId, OpenMode.ForWrite),

MapBook.Book)

'

' Insert code to process transaction

'

' Commit transaction

'

trans.Commit()

Catch

'

' Handle exception, and cancel transaction

'

Finally

trans.Dispose()

End Try

Although transactions can be nested, this is not recommended. Onecomplication is that adding an entity takes place immediately, but removingan entity does not take effect until the transaction has been committed.

NOTE Many examples in this guide assume that activeDoc refers to the activedocument.

AutoCAD | 7

8

Session and Project

In this chapter

■ Overview

■ Drawing Objects

2

9

OverviewAn AutoCAD Map 3D session represents the active state of the Map 3Dapplication.

Most of the classes for working with the session are defined in theAutodesk.Gis.Map namespace.

There is a single instance of the Map application, available through theApplication property of the abstract class

Autodesk.Gis.Map.HostMapApplicationServices

This returns a MapApplication object that represents the entire application.It has some read-only properties that provide access to objects in the session.One of the main properties is Projects.

Projects returns a collection of all open projects, a ProjectCollection objectin the Autodesk.Gis.Map.Project namespace. A project is represented by aProjectModel object. A project is the container for a Map 3D drawing and allits associated objects. Nearly all interaction with a drawing begins with aproject.

ActiveProject returns the ProjectModel for the currently active project.

NOTE For historical reasons, the API uses the term project where the user interfacewill normally use map or drawing.

For example, the following gets the current project:

Dim mapApp As MapApplication

mapApp = HostMapApplicationServices.Application

Dim activeProj As Project.ProjectModel

activeProj = mapApp.ActiveProject

The following processes all open projects:

Dim mapApp As MapApplication

mapApp = HostMapApplicationServices.Application

Dim projList As Project.ProjectCollection

projList = mapApp.Projects

For Each project As Project.ProjectModel In projList

' Process projects

Next

NOTE Many of the examples in this guide assume that mapApp and activeProjhave already been defined as in the example above.

10 | Chapter 2 Session and Project

A project is closely related to an AutoCAD drawing. In AutoCAD Map 3D,opening a drawing automatically creates a new project. You cannot instantiatea new project directly.

MapApplication.GetDocument() returns the AutoCAD document associatedwith a project. Conversely, Project.ProjectCollection.GetProject() returnsthe ProjectModel for an AutoCAD document.

For example, the following diagram shows a session that has three openprojects. The first project refers to external drawings in its drawing set. Anyone of the projects could be active at one time. Each project has acorresponding AutoCAD drawing.

Session(Autodesk.Gis.Map.ApplicationServices.Application)

Session.Projects(Autodesk.Gis.Map.Project.ProjectCollection object)

Projects(0) Projects(1) Projects(2)

DrawingSet

Additional Project Properties

ProjectModel objects have many properties that provide access to differentaspects of the drawing. For example, the DrawingSet property gets the drawingset for the project.

Some of the important project properties are:

■ Annotations

■ Database

Overview | 11

■ DrawingSet

■ ODTables

■ Topologies

For more details about the various properties, refer to the appropriate chaptersin this guide.

AutoCAD Database

The ProjectModel.Database property returns a reference to the AutoCADdatabase. This is necessary for many AutoCAD operations.

Project Options

The ProjectModel.Options property returns a reference to the project’s options.

Drawing ObjectsDrawing objects are the visible items in an AutoCAD drawing.

NOTE The AutoCAD developer documentation generally uses the term entity orAcDb entity when discussing drawing objects.

In the AutoCAD API, an Autodesk.AutoCAD.DatabaseServices.DBObjectobject represents any object in the drawing database, including drawingobjects. A DBObject can be referred to by either:

■ Autodesk.AutoCAD.DatabaseServices.Handle

■ Autodesk.AutoCAD.DatabaseServices.ObjectID

A Handle is a persistent identifier that is stored with the AutoCAD databasewhen it is saved. Each handle is unique within a single drawing, but differentdrawings are likely to have duplicate handles referring to separate objects.

An ObjectID is used for quick access to drawing objects within an AutoCADsession. They are not persistent, though. They expire when the drawing isclosed.

12 | Chapter 2 Session and Project

Map Objects

Because a single AutoCAD Map 3D project can include more than oneAutoCAD drawing, an AutoCAD handle is not sufficient to uniquely identifyan object.

A MapObjectId, defined in the namespace Autodesk.Gis.Map.Utilities,identifies an object by its AutoCAD handle and by its drawing identifier. TheMapObjectId.ObjectHandle property is the AutoCAD handle, andMapObjectId.DrawingId is the drawing identifier, an object of typeUtilities.MapId.

Drawing Objects | 13

14

Object Data

In this chapter

■ Introduction

■ Creating a Table

■ Attaching Object Data

■ Getting Object Data

■ Updating and DeletingRecords

3

15

IntroductionObject data provides a way of attaching additional information to drawingobjects. It is more powerful and flexible than AutoCAD block attributes becauseobject data can be attached to any object in a drawing.

NOTE Object data can only be attached to drawing objects. FDO feature sourceshave a different way to handle feature properties.

The classes for handling object data are mostly within the ObjectDatanamespace. Code in this chapter assumes the following:

Imports Autodesk.Gis.Map.ObjectData

Tables

Internally, object data is stored in tables. Each drawing has its own set oftables, available from the ProjectModel.ODTables property. This returns anobject of type ObjectData.Tables.

For example, if mapApp is the Map application, the following will get the objectdata tables for the active drawing:

Dim activeProject As Project.ProjectModel = mapApp.ActiveProject

Dim tableList As ObjectData.Tables = activeProject.ODTables

ObjectData.Tables.GetTableNames() returns a list of the table names thathave been defined for the drawing.

To get a single table from the set of tables, use the ObjectData.Tables.Itemproperty. Note that this requires a table name as a parameter, not a tablenumber. For example:

Dim table As ObjectData.Table = tableList.Item("table1")

or

Dim table As ObjectData.Table = tableList("table1")

Use Tables.IsTableDefined() to see if a table name exists. An attempt to geta table that does not exist throws an exception.

16 | Chapter 3 Object Data

Field Definitions

Columns in a table are defined by ObjectData.FieldDefinition objects, whichdescribe the data type and default value. The data types are defined in theConstants.DataType enum:

■ UnknownType

■ Integer

■ Real

■ Character

■ Point

Records

Each row in the table is of type ObjectData.Record. Every record in the tableis associated with a drawing object.

The Item property of an ObjectData.Record contains the values for the record,one for each field definition in the table. Each item is of typeUtilities.MapValue, which is a general-purpose class for storing data.

Creating a TableCreating a table requires:

■ Creating an ObjectData.FieldDefinitions object

■ Adding field definitions for every column in the table

■ Creating the table by adding the field definitions to the ODTables objectfor the drawing

Create an ObjectData.FieldDefinitions object using theProjectModel.MapUtility.NewODFieldDefinitions() method. Add fieldsusing the FieldDefinitions.Add() method. For example, if mapApp is the Mapapplication, the following creates field definitions for 2 columns:

Creating a Table | 17

Dim fieldDefs As ObjectData.FieldDefinitions

fieldDefs = _

mapApp.ActiveProject.MapUtility.NewODFieldDefinitions()

Dim def1 As ObjectData.FieldDefinition

def1 = fieldDefs.Add("FIRST_FIELD", "Owner name", _

Autodesk.Gis.Map.Constants.DataType.Character, 0)

def1.SetDefaultValue("A")

Dim def2 As ObjectData.FieldDefinition

def2 = fieldDefs.Add("SECOND_FIELD", "Assessment year", _

Autodesk.Gis.Map.Constants.DataType.Integer, 1)

def2.SetDefaultValue(0)

Get a reference to the ODTables property for the drawing, and add the fielddefintions to create a new table.

Dim tables As ObjectData.Tables

tables = mapApp.ActiveProject.ODTables

tables.Add("NewTable", fieldDefs, "Description", True)

Get a reference to the table using Tables.Item(). This expects a stringparameter.

Dim table As ObjectData.Table

table = tables("NewTable")

Removing a Table

To remove a table, get a reference to the ODTables property for the drawing,and call Tables.RemoveTable().

Dim tables As ObjectData.Tables

tables = mapApp.ActiveProject.ODTables

tables.RemoveTable("NewTable")

Attaching Object DataAdding object data to a drawing object requires:

■ Creating an empty record

■ Initializing the record with correct types for the table

■ Setting values for each column


■ Attaching the object data by adding the record to the table

Create an empty record using the static method ObjectData.Record.Create().This does not define any fields for the record. Initialize the record, whichcreates fields of the correct type, using Table.InitRecord().

Dim rec As ObjectData.Record

rec = ObjectData.Record.Create()

table.InitRecord(rec)

Each Item property in the record is of type Utilities.MapValue, which is ageneral-purpose class for storing data of variant types. To set any field, get areference to the field from the Record object using the Item property. Assignthe value with MapValue.Assign(). For example, if rec is a record in a tablewhere the second field is of type integer, the following will assign a value of10 to the field.

Dim val As Utilities.MapValue

val = rec(1)

val.Assign(10)

Add the record to the table with Table.AddRecord() and associate it with anobject. This requires a Record and either an AutoCAD DBObject or ObjectIdas parameters.

newTable.AddRecord(rec, objId)

A single drawing object may have more than one object data record in a giventable.

Getting Object DataTo get all object data records from a single table for a drawing object:

■ Get the ObjectData.Tables object for the drawing.

■ Get the individual table.

■ Get the ObjectData.Records collection for the object, using one of theGetObjectTableRecords() methods.

■ Iterate through the records in the collection.

■ Process the fields in each record.

Getting Object Data | 19

The following example writes the values from table for objId to the console.

Dim fieldDefs As ObjectData.FieldDefinitions = _

table.FieldDefinitions

Dim recs As ObjectData.Records

recs = table.GetObjectTableRecords(0, objId, _

Constants.OpenMode.OpenForRead, True)

If (recs.Count() > 0) Then

For Each rec As ObjectData.Record In recs

For i As Integer = 0 To rec.Count() - 1

Dim val As Autodesk.Gis.Map.Utilities.MapValue

val = rec(i)

Dim fieldDef As ObjectData.FieldDefinition

fieldDef = fieldDefs(i)

acEditor.WriteMessage(

vbNewLine + fieldDef.Name + ": ")

Select Case val.Type

Case Constants.DataType.Character

acEditor.WriteMessage(val.StrValue)

Case Constants.DataType.Integer

acEditor.WriteMessage(val.Int32Value.ToString)

Case Constants.DataType.Point

acEditor.WriteMessage("point")

Case Constants.DataType.Real

acEditor.WriteMessage(val.DoubleValue.ToString)

Case Else

acEditor.WriteMessage("undefined")

End Select

Next

Next

End If

recs.Dispose()

Processing all tables for an object is similar. Instead of callingTable.GetObjectTableRecords() for an individual table, callTables.GetObjectRecords() for all tables. When processing the fields, be sureto to get the field definitions from the correct table for the current record.

■ Get the ObjectData.Tables object for the drawing.

■ Get the ObjectData.Records collection for the object, using one of theGetObjectRecords() methods.

■ Iterate through the records in the collection.


■ Get the table name for the current record.

■ Get the fields definitions for the table.

■ Process the fields in each record.

NOTE When you have finished processing the records, release any of the disposableobjects with their Dispose() methods. This applies to any classes inheritingAutodesk.AutoCAD.Runtime.DisposableWrapper, like ObjectData.Table,ObjectData.Records, or Utilities.MapValue.

Updating and Deleting RecordsTo update or delete records, they must be opened for write access in the callto Table.GetObjectTableRecords() or Tables.GetObjectRecords().

Fields in a record are of type Utilities.MapValue. To update a field, get areference to the value from the Record object. Assign a new value usingMapValue.Assign() and update the record using Records.UpdateRecord().The following example sets the value of the first field in a record:

Dim val As Utilities.MapValue = rec(0)

val.Assign(19)

recs.UpdateRecord(rec)

To delete a record, get an IEnumerator using Records.GetEnumerator().Advance the enumerator to the record to be deleted and callRecords.RemoveRecord(). The following example deletes the first record foran object.

Dim recs As ObjectData.Records

recs = table.GetObjectTableRecords(0, objId, _

Constants.OpenMode.OpenForWrite, True)

Dim ie As IEnumerator

ie = recs.GetEnumerator()

ie.MoveNext()

recs.RemoveRecord()

recs.Dispose()

Updating and Deleting Records | 21

22

Annotation

In this chapter

■ Overview

■ Annotation Templates

■ Expressions in Annotations

■ Inserting Annotations

■ Updating and RefreshingAnnotations

■ Annotation Overrides

4

23

OverviewAnnotations provide a way to label drawing objects, based on data associatedwith the objects. The associated data can come from various places, such asobject data, linked databases, or object properties. For example, if a drawingcontains parcels, and the parcels have object data with the name of the parcelowner or the most recent sale price of the parcel, then these values could beadded to the map as part of an annotation.

Each annotation is based on an annotation template, which is a special blockin the drawing. The template describes the annotation, and usually containsannotation text defining the variable content.

A new annotation is created by inserting a reference to the annotationtemplate. This creates a reference to the annotation block, substituting theproper values in the expression fields.

The classes for handling annotations are mostly within the Annotationnamespace. Code in this chapter assumes the following:

Imports Autodesk.Gis.Map.Annotation

Annotation TemplatesAn annotation template is a special block in the drawing. It defines the fixedand variable parts of the annotation.

NOTE For more information about blocks, refer to the AutoCAD developerdocumentation.

Internally, annotation templates use a special naming convention. The namesof all blocks containing annotation templates begin withACMAP_ANN_TEMPLATE_. This prefix is defined in theAnnotations.TemplateNameBlockTableRecordPrefix property.

Annotation API calls, though, use the annotation name as it appears in theUI. For example, an annotation template named ParcelName would be storedin a block named ACMAP_ANN_TEMPLATE_ParcelName, but it would be createdwith a call to Annotations.CreateAnnotationTemplate("ParcelName").

The ProjectModel.Annotations property returns an Annotations object thatcan be used for managing the annotations and annotation templates.

24 | Chapter 4 Annotation

Attributes

An AutoCAD block can contain attribute definitions, which are text entitiesthat can define informational text for each block reference.

In an annotation template, attribute definitions are used to define the variableparts of the annotation. For example, if the annotations include object data,then attribute definitions in the block template define what object data shouldappear and how it will be displayed.

The AttributeDefinition class inherits the DBText class, which inherits theEntity class. These have properties such as Color and Height that define howthe annotation will appear in the drawing. For example, to set the text heightfor an annotation, set the Height property of the attribute definition used forthe annotation.

NOTE The properties used for the attribute definition can also be modified usingexpression strings. See Expressions in Annotations (page 27) for details.

Creating an Annotation Template

Although an annotation template is a form of AutoCAD block, it must becreated using the Map API or it will not be recognized properly.

■ Start a transaction.

■ Create the annotation template usingAnnotations.CreateAnnotationTemplate().

■ Get a reference to the annotation template using Annotations.Item().

■ If required, set block properties for the annotation template usingAnnotationTemplate.SetExpressionString(). For example, this can beused to rotate the block reference to match the rotation of the object beingannotated.

■ If required, add fixed drawing objects to the annotation template. Get theAutoCAD block id using the AnnotationTemplate.BlockDefinitionIdproperty and add drawing objects to the template using standard AutoCADAPI calls.

■ Add variable annotation text to the template usingAnnotationTemplate.CreateAnnotationText(). This creates an attributedefinition in the block.

Annotation Templates | 25

■ Set the display properties of the annotation text by setting properties forthe attribute definition.

■ Set the expression string for the annotation text usingAnnotations.SetExpressionString().

■ Commit the transaction.

Annotations.CreateAnnotationTemplate() creates an empty template. Itreturns an AutoCAD ObjectID that is the id of the block table record. Get areference to the annotation template object using Annotations.Item().

Dim annotations As Annotation.Annotations = _

activeProj.Annotations



Dim newTemplateId As ObjectId = _

annotations.CreateAnnotationTemplate("templateName")

Dim newTemplate As Annotation.AnnotationTemplate = _

annotations(newTemplateId)

If required, set block properties for the annotation template. See Expressionsin Annotations (page 27) for details.

newTemplate.SetExpressionString(_

Annotation.AnnotationExpressionFields.BlockRotation, ".ANGLE")

Add objects to the template. They can be normal drawing objects or annotationtext.

To add normal drawing objects, use standard AutoCAD methods.

Dim line As New Line

line.StartPoint = New Geometry.Point3d(0.0, -0.6, 0.0)

line.EndPoint = New Geometry.Point3d(2.0, -0.6, 0.0)

Dim blockTableRec As BlockTableRecord

blockTableRec = newTemplateId.GetObject(OpenMode.ForWrite)

blockTableRec.AppendEntity(line)

trans.AddNewlyCreatedDBObject(line, True)

To add annotation text, create an annotation text object. This is a special typeof AutoCAD attribute definition. AnnotationTemplate.CreateAnnotationText()returns the AutoCAD ObjectId of the attribute definition. Open this objectfor writing and cast to an AttributeDefinition object:


Dim expressionTextId As ObjectId

expressionTextId = newTemplate.CreateAnnotationText()

Dim attDef As AttributeDefinition

attDef = _

CType(trans.GetObject(expressionTextId, OpenMode.ForWrite), _

AttributeDefinition)

Most of the properties for the annotation template can be set using theAttributeDefinition properties. For example:

attDef.Position = _

New Autodesk.AutoCAD.Geometry.Point3d(0.0, 0.0, 0.0)

attDef.Tag = "testTag"

attDef.Height = 0.5

attDef.VerticalMode = TextVerticalMode.TextVerticalMid

attDef.HorizontalMode = TextHorizontalMode.TextCenter

attDef.AlignmentPoint =

New Autodesk.AutoCAD.Geometry.Point3d(0.0, 0.0, 0.0)

The annotation text must be set using Annotations.SetExpressionString().See Expressions in Annotations (page 27) for details.

Expressions in AnnotationsUse expressions to set the text or the display properties of the annotation.Some of the items that can use expressions are:

■ Annotation text

■ Text color

■ Text size

■ Rotation angle

■ Position relative to the drawing object being annotated

NOTE Properties in an attribute definition can be overridden by annotationexpressions. For example, if the attribute definition defines the location of the text,the annotation expression could override it.

AnnotationTemplate.SetExpressionString() sets properties for the entiretemplate. Annotations.SetExpressionString() sets properties for annotationtext within the block.

Expressions in Annotations | 27

Expressions are evaluated by the AutoLISP interpreter, and return a singlevalue. Depending on the property being set, the value can be numeric orstring. If the expression cannot be evaluated properly it displays the attributetag name instead.

NOTE For more details about expressions, including a list of functions and variables,see the Map 3D Help. In the Reference Guide section there is a chapter about theExpression Evaluator.

The enum Annotation.AnnotationExpressionFields contains the completelist of fields that can use expressions.

In most cases, expressions are used to define the text of the annotation, butthey can also be used to define things like color, size, or position.

Example

To set the annotation text based on object data, use the syntax:fieldname@tablename. For example:

Imports Autodesk.Gis.Map.Annotation

annotations.SetExpressionString(attDef, _

AnnotationExpressionFields.AttributeDefinitionAnnotationString, _

":PARCEL_OWNER@ParcelData")

Inserting AnnotationsTo insert an annotation, call one of theAnnotationTemplate.InsertReference() methods. They all require anObjectId or ObjectIdCollection as parameter, to identify the drawing objectsto be annotated.

This creates a block reference in the drawing. It evaluates the annotationexpressions and uses the results to set the text or other properties of thereference.

An inserted annotation reference can also have overrides that change thedisplay properties. See Annotation Overrides (page 29) for details.


Updating and Refreshing AnnotationsOnce inserted, annotation references do not change unless they are explicitlychanged. For example, if the object data for a drawing object changes, anyanotations that use the object data will still display the original value.

There are two operations for revising existing annotation references:

■ Updating

■ Refreshing

Updating removes and recreates all the annotations that use a template.Refreshing re-evaluates the annotation expressions, but does not removeout-of-date annotations.

To update annotations, call AnnotationTemplate.UpdateReferences().

newTemplate.UpdateReferences(True)

To refresh annotations, call AnnotationTemplate.RefreshReferences().

newTemplate.RefreshReferences(True)

Annotation OverridesAn annotation override can be applied when an annotation reference is created.It changes selected properties of the annotation template. For example, anannotation override can change the color or text size of the annotation.

Annotation overrides can apply to the static properties of the annotation,which are set using the AttributeDefinition properties, or the dynamicproperties, which are set using expressions.

Annotation overrides correspond to the Insert Options and Insert Propertiesof the Insert Annotation dialog in the UI.

For example, to override the static color, set the ColorOverride property ofthe annotation override. To override a color set using an expression, set theColorExpressionOverride property.

To apply an annotation override, insert the annotation usingAnnotationTemplate(ObjectId, AnnotationOverrides). For example:

Updating and Refreshing Annotations | 29

Dim annOverrides As New Annotation.AnnotationOverrides

annOverrides.Clear()

Dim greenClr As Autodesk.AutoCAD.Colors.Color = _

Autodesk.AutoCAD.Colors.Color.FromColorIndex( _

Autodesk.AutoCAD.Colors.ColorMethod.None, 3)

annOverrides.ColorOverride = greenClr

annTemplate.InsertReference(objId, annOverrides)


Events

In this chapter

■ Overview

■ Events in the APIReference

■ List of Events

5

31

OverviewEvents and event handlers provide a way for applications to respond to changesin the Map application. For example, opening a new project can fire an eventhandler to perform additional processing.

The API uses standard .NET mechanisms for handling events. Applicationswanting to handle events subscribe to the events. When the event is fired allhandlers subscribed to that event are called.

Event handlers accept two parameters:

■ A reference to the object raising the event

■ Event arguments

The class definition for the event arguments is usually specific to the eventbeing handled.

Events in the API ReferenceFor every event, the AutoCAD Map 3D API Reference contains the following:

■ Class definition for the event arguments. The names of these classes usuallybegin with the event name and end with “EventArgs”. In some cases theevent uses System.EventArgs instead of defining a new class.

■ Methods for adding and removing event handlers. The names of thesemethods begin with “add_” or “remove_”. Do not call these methodsdirectly. Instead use the correct syntax for the language.

■ Type definition for the event handler.

NOTE Some events, such as ProjectModel.BeginClose, useSystem.EventHandler and System.EventArgs instead of objects derived fromthem. For details refer to the API reference or the Visual Studio Object Browser.

For example, the ProjectOpened event in the Autodesk.Gis.Map namespaceconsists of the following:

■ ProjectOpenedEventArgs class

■ add_ProjectOpened method in the MapApplication class

32 | Chapter 5 Events

■ remove_ProjectOpened method in the MapApplication class

■ ProjectOpenedEventHandler type

NOTE The actual event name is not used in the API reference. It can always beinferred from the corresponding add_ or remove_ methods.

Example:VB.NET

To define an event handler for the ProjectOpened event, create a subroutine:

Sub handleProjectOpened(ByVal pSender As Object, _

ByVal pArgs As ProjectOpenedEventArgs)

' Insert code to handle event

End Sub

To subscribe to the event:

AddHandler mapApp.ProjectOpened, AddressOf handleProjectOpened

To unsubscribe from the event:

RemoveHandler mapApp.ProjectOpened, AddressOf handleProjectOpened

Example: C#

To define an event handler for the ProjectOpened event, create a subroutine:

void handleProjectOpened(Object sender,

ProjectOpenedEventArgs args)

{

// Insert code to handle event

}

To subscribe to the event:

mapApp.ProjectOpened += new ProjectOpenedEventHandler(

handleProjectOpened);

To unsubscribe from the event:

mapApp.ProjectOpened -= new ProjectOpenedEventHandler(

handleProjectOpened);

Events in the API Reference | 33

List of EventsNamespace Autodesk.Gis.Map

Aliases class

DescriptionEvent name

Fired when a new alias is added to the application.The event args pass the alias name.

AlliasAdded

Fired when an alias is deleted from the application.The event args pass the alias name and path of thedeleted alias.

AliasDeleted

MapApplication class


Fired when one of the application options is modi-fied. The event args pass the option name and thenew and old values of the option.

IntOptionModified

Fired when a project begins the close operation,but before the project has been closed. The eventargs pass the project model.

ProjectBeginClose

Fired after a new project has been created. Theevent args pass the project model.

ProjectCreated

Fired when an existing project has been opened.The event args pass the project model.

ProjectOpened

Fired when one of the application options is modi-fied. The event args pass the option name and thenew and old values of the option.

StringOptionModified

Not used for .NET applications.UnloadApp


Namespace Autodesk.Gis.Map.Classification

ClassificationManager class


Fired when a new feature class definition has beencreated. The event args pass the class name and

FeatureClassDefinitionCreated

the name of the XML file containing the classdefinition.

Fired when a feature class definition has been de-leted. The event args pass the class name and thename of the XML file containing the class definition.

FeatureClassDefinitionDeleted

Fired when a feature class definition has beenmodified. The event args pass the class name and

FeatureClassDefinitionModified

the name of the XML file containing the classdefinition.

Fired when a feature class definition has been re-named. The event args pass the new and old class

FeatureClassDefinitionRenamed

names and the name of the XML file containing theclass definition.

Fired when a new definition file is attached. Theevent args pass the filename.

FeatureDefinitionFileAttached

Fired when a definition file is modified. The eventargs pass the filename.

FeatureDefinitionFileModified

Namespace Autodesk.Gis.Map.DisplayManagement

DisplayManager class


CategoryAppended

CategoryModified

List of Events | 35


CategoryUnappended

MapAppended

MapGoodBye

Fired when changing the current display managermap, before the change is made. Returns

MapSetCurrentBegin

MapSetCurrentEnd

MapSetCurrentFails

MapUnappended

StyleAppendedToCategory

StyleModified

StyleUnappended

Map class


CurrentScaleModified

DismissStylizationBegin

DismissStylizationCancel

DismissStylizationEnd

ItemAppended



ItemErased

ItemModified

ScaleAdded

ScaleErased

ScaleModified

StyleAppended

StyleErased

StyleReferenceAppended

StyleReferenceErased

StyleReferenceModified

UpdateStylizationBegin

UpdateStylizationCancel

UpdateStylizationEnd

Namespace Autodesk.Gis.Map.ImportExport

Exporter class


ExportRecordError

RecordExported

List of Events | 37


RecordReadyForExport

Importer class


ImportRecordError

RecordImported

RecordReadyForImport

Namespace Autodesk.Gis.Map.MapBook

BookManager class


MapBookAppended

MapBookErased

MapBookModified

MapBookSetCurrent

MapBookTileModified

MapBookTileWillBeErased

MapBookTreeNodeModified

MapBookWillBeErased


Namespace Autodesk.Gis.Map.Project

DrawingSet class


DrawingActivated

DrawingActivationCancelled

DrawingAttachCancelled

DrawingAttached

DrawingDeactivated

DrawingDetached

DrawingSettingsModified

DrawingToBeActivated

DrawingToBeAttached

ProjectModel class


AbortCSChange

AbortSwapId

BeginClose

BeginCSChange

BeginDestroy

List of Events | 39


BeginOpen

BeginQuery

BeginSave

BeginSaveBack

BeginSwapId

BeginTransform

EndClose

EndCSChange

EndOpen

EndQuery

EndSave

EndSaveBack

EndSwapId

EndTransform

IntOptionModified

StringOptionModified


Namespace Autodesk.Gis.Map.Query

QueryLibrary class


QueryAdded

QueryCategoryAdded

QueryCategoryDeleted

QueryCategoryRenamed

QueryDeleted

QueryModified

QueryRenamed

List of Events | 41

42

Drawing Sets

In this chapter

■ Overview

■ Drive Aliases

■ Attaching and DetachingDrawings

6

43

OverviewDrawing sets provide a way for a single map to combine objects from multipledrawings. One drawing, the project drawing, can attach multiple sourcedrawings. The source drawings, in turn, can attach other source drawings toform a tree of attached drawings.

Running a query on the attached drawings copies selected objects into theproject drawing, where they can be displayed and edited. Unless an objectfrom an attached drawing has been “queried in” it does not appear in theproject drawing. See Queries and Save Sets (page 47) for more details.

Drive AliasesAttached drawings are often shared between different users on differentcomputers. Because of this, the paths to the attached drawings can be differentfor each user. Aliases help manage these files.

Each alias maps an alias name to a directory path. Each AutoCAD Map 3Duser can define different paths for the aliases. The locations of attacheddrawings are always identified using the aliases, so users can have differentpaths to the atttached drawings, as long as the aliases are the same.

The DriveAlias class in the Autodesk.Gis.Map namespace represents anindividual alias. It has two properties: Name and Path.

The Aliases property of the map application returns an Aliases object formanaging the aliases in the session. Aliases.Item() returns an individualdrive alias, either by alias name or index number.

Dim aliasList As Aliases

aliasList = mapApp.Aliases

Aliases objects have methods for adding and removing aliases, and eventhandlers for detecting when aliases have been added or removed.

Attaching and Detaching DrawingsAttaching a drawing adds it to the drawing set for a project. Detaching adrawing removes it from the drawing set.

44 | Chapter 6 Drawing Sets

To attach a drawing, use DrawingSet.AttachDrawing(). Pass a single stringargument that contains the alias and the path to the drawing to attach. Theform is:

alias:\filename

This returns a reference to the attached drawing, an AttachedDrawing object.

When an attached drawing is activated, the file is locked against editing byother applications. To remove the lock, but keep the drawing attached, callAttachedDrawing.Deactivate(). To reactivate the drawing, callAttachedDrawing.Activate().

Attaching and Detaching Drawings | 45

46

Queries and Save Sets

In this chapter

■ Overview

■ Queries

■ Query Libraries

■ Save Sets

7

47

OverviewQueries and save sets work on attached drawings. A query copies drawingobjects from attached drawings into the project drawing. Once in the projectdrawing, the objects can be edited like any other drawing object.

A save set is a list of objects in the project drawing that are to be updated inattached drawings. The save set can contain:

■ objects that have been modified in the project drawing that should alsobe modified in the attached drawings

■ objects that have been deleted from the project drawing and should bedeleted from the attached drawings

■ new objects that have been added to the project drawing that should alsobe added to an attached drawing

Objects that have been queried into the project drawing are not added to thesave set automatically.

QueriesA query is a tree structure containing branches (QueryBranch objects) andconditions (DataCondition, LocationCondition, PropertyCondition, andSqlCondition objects). All of these objects are subclassed from QueryUnit.

To create a query, call ProjectModel.CreateQuery().

query = activeProj.CreateQuery()

This returns an empty QueryModel object.

A simple query can have a root branch with a single condition. More complexqueries combine branches and conditions.

The criteria that the query uses to select objects are expressed in queryconditions. There are four types of query conditions.

Description

Based on the location of objects relative toa boundary. There are several boundarytypes. See Location Boundaries below.

Location Conditions

48 | Chapter 7 Queries and Save Sets

Description

Based on a particular AutoCAD property.Property Conditions

Based on object data. To query object dataset the query type to DataIrd. To query

Data Conditions

object classes set the query type toDataFeature.

Based on data about drawing objects thatis stored in external database tables and is

SQL Conditions

specified by the WHERE clause of a SQLquery.

Location Boundaries

There are several types of location boundaries. They are all represented bydescendents of the LocationBoundary class, as illustrated in the followingdiagram.

Queries | 49

LocationBoundary

FenceBoundary

AllBoundary

PolylineBoundary

BufferFenceBoundary

PolygonBoundary

WindowBoundary

PointBoundary

CircleBoundary

ClosedPolylineBoundary

BufferPolylineBoundary

Executing Queries

To build a query

1 Create the query using ProjectModel.CreateQuery().

2 Create one or more query conditions using the constructors forDataCondition, LocationCondition, PropertyCondition, andSqlCondition.

3 Create one or more query branches using the constructor for QueryBranch.

4 Build the query tree by appending query conditions and branches usingQueryBranch.AppendOperand().

5 Create the query definition by passing the root query branch toQueryModel.Define().


6 Optionally, save the query definition in an external file or query library.

To execute a query

1 You may want to set the mode, enable or disable property alteration, orcreate a report template for the query.

2 Call QueryModel.Run() to execute the query against all attached drawings.Call QueryModel.Execute() to execute the query for a particular drawingset.

The query mode determines if the objects from the attached drawings aredisplayed as a preview or cloned into the project drawing.QueryModel.Execute() returns a list of objects that have been queried in.

Query LibrariesQuery libraries provide a way to save and re-use queries. The queries can besaved internally in the project file or externally. Each project has its ownlibrary, available with ProjectModel.QueryCategories.

Libraries are divided into categories, where each category is a container forsaved queries. The saved queries are represented by QueryAttribute objects.

To add a query to the library, first add a category then add the query.

Dim queryLib As Query.QueryLibrary = activeProject.QueryCategories

Dim queryCat As Query.QueryCategory

queryCat = queryLib.AddCategory("catName")

queryCat.AddQuery("queryName", "query description", queryObj)

To save a query to an external file, call QueryModel.Save().

Save SetsEach project has a save set, which manages a list of object ids to be updatedin attached drawings.

Objects are not added to the save set automatically. It is up to the applicationto add objects using SaveSet.AddObjects().

Query Libraries | 51

To save objects back to an attached drawing, callAttachedDrawing.CloneBack(), AttachedDrawing.CloneBackArea(), orAttachedDrawing.CloneBackLayer().


Classification

In this chapter

■ Overview

■ Managing FeatureDefinition Files

■ Creating Feature ClassDefinitions

■ Classifying Objects

8

53

OverviewObject classification is a way of tagging drawing objects with an object classname. This can help organize the objects in the drawing, and enforce drawingstandards.

NOTE For historical reasons, the API uses the terms feature and feature class forobject classification. These are different from FDO features and feature classes. Itis important not to confuse the two.

Managing Feature Definition FilesFeature class definitions are stored in XML files, external to the drawing file.Before definitions from a file can be used, the file must be attached to adrawing. There can only be one attached feature definition file active at onetime for a given project.

NOTE In the UI, feature definition files are called object class definition files.

Creating Feature Definition Files

To create a feature definition file:

■ Get the classification manager object for the project usingProjectModel.ClassificationManager.

■ Create the new file usingClassificationManager.CreateFeatureDefinitionFile(). Note that thecurrent user must have administrative privileges in the Map session. Tocheck, test ClassificationManager.CanCurrentUserAlterSchema.

Dim classMgr As Classification.ClassificationManager

classMgr = activeProj.ClassificationManager

If (classMgr.CanCurrentUserAlterSchema) Then

classMgr.CreateFeatureDefinitionFile(filename)

Else

' Error

End If

54 | Chapter 8 Classification

Attaching and Detaching Feature Definition Files

To attach a feature definition file, callClassificationManager.AttachFeatureDefinitionFile().

To detach the current file, callClassificationManager.DetachCurrentFeatureDefinitionFile().

Creating Feature Class DefinitionsFeature class definitions are composed of properties that define how classifiedobjects will appear. Each feature class definition can only be used with certaintypes of drawing objects.

To create a feature class definition, start with a drawing object to use as atemplate. Get the properties of the drawing object usingClassificationManager.GetProperties(). The current values of the drawingobject become the default property values.

Determine the list of object types that the feature class definition can be usedwith. This list can be expressed as a string collection or a collection of AutoCADRXClass objects. Create the empty feature class definition usingClassificationManager.CreateFeatureClassDefinition(). Set a drawingobject type to use for creating new instances of the class usingFeatureClassDefinition.SetCreateMethod().

Creating Feature Class Definitions | 55

Dim classMgr As Classification.ClassificationManager

Dim newDef As Classification.FeatureClassDefinition

classMgr = activeProj.ClassificationManager


Dim obj As DBObject = Nothing

Dim cls As RXClass = Nothing

Try

trans = _

MdiActiveDocument.TransactionManager.StartTransaction()

obj = trans.GetObject(objId, OpenMode.ForRead)

cls = obj.GetRXClass()

trans.Commit()

Finally

trans.Dispose()

End Try

Dim entType As System.String = System.String.Copy(cls.Name)

Dim entTypesCol As StringCollection = New StringCollection()

entTypesCol.Add(entType)

newDef = classMgr.CreateFeatureClassDefinition( _

defName, Nothing, entTypesCol, Nothing, False)

newDef.SetCreateMethod(entType, "")

Use the FeatureClassPropertyCollection as an initial set of properties forthe feature class definition. Modify it as needed by setting range and defaultvalues for the properties in the collection. Create a newFeatureClassPropertyCollection with the updated properties. Save the featuredefinition file.

Dim classProp As Classification.FeatureClassProperty

Dim propCollection As _

Classification.FeatureClassPropertyCollection

propCollection = _

New Classification.FeatureClassPropertyCollection

classMgr.GetProperties(classPropCollection, Nothing, objId)

For Each classProp In classPropCollection

' Modify the property if necessary

newDef.AddProperty(classProp)

Next

classMgr.SaveCurrentFeatureDefinitionFile()

56 | Chapter 8 Classification

Classifying ObjectsTo classify a drawing object, call ClassificationManager.Classify(). Thistags the object with the name of the feature definition file and the featureclass name. If the feature definition file is detached, the classification tagremains.

A single object may be classified more than once, by using feature classes fromdifferent feature definition files. To get a list of all classifications for an object,call ClassificationManager.GetAllTags().

To unclassify an object, call ClassificationManager.Unclassify().

To get a list of all objects in a drawing that have not been classified, callClassificationManager.GetUnclassifiedEntities(). The result of this canbe used to find and classify missing objects.

Classifying Objects | 57

58

Filters

In this chapter

■ Overview

■ Basic Filters

■ Custom Filters

9

59

OverviewFilters provide a simple mechanism for selecting drawing objects that meetcertain criteria. In the AutoCAD Map 3D UI, a basic filter can be used to selectdrawing objects for an export operation.

A basic filter has options for filtering based on combinations of layer names,object classification, and block names. Custom filters can filter based on othercriteria. Both types are based on the Filters.ObjectFilter class.

An ObjectFilterGroup can combine multiple filters into a single filteroperation.

Objects for working with filters are in the Autodesk.Gis.Map.Filtersnamespace.

Basic FiltersThe FilterObjects() method for any filter takes a list of drawing objects tobe filtered and returns a list of drawing objects that meet the filtering criteria.

To create a basic filter, call the constructor with a list of layer names, featureclass names, and block names. Separate multiple values with commas. Anasterisk (“*”) wild card selects all objects matching the criterion.

Dim newFilter As Autodesk.Gis.Map.Filters.BasicFilter

newFilter = New Autodesk.Gis.Map.Filters.BasicFilter

("Parcels, Lots", "*", "*"))

To run a filter, call its FilterObjects() method with the output and inputObjectIdCollection objects.

Custom FiltersCustom filters can implement additional filtering capabilities. To create acustom filter, define a new class based on the ObjectFilter class. At aminimum, the custom filter must define a FilterObjects() method. It candefine any other methods needed for creating and modifying the filter.

60 | Chapter 9 Filters

Import/Export

In this chapter

■ Overview

■ Importing

■ Exporting

10

61

OverviewThe AutoCAD Map 3D application maintains lists of available import andexport formats. It is not possible to modify these lists using the API. Theapplication Importer and Exporter classes can import and export data usingthese formats.

Any import or export procedure requires the following:

■ Selecting the external file format and location

■ Mapping attribute data from the external file to object data

■ Setting any necessary driver options

■ Importing or exporting

The particular options will vary depending on the type of data being importedor exported, but the overall procedure is the same.

ImportingThe import procedure brings in objects from external files and creates newdrawing objects. Some external files have a single layer, while others havemore than one.

To start an import process, get the Importer object for the application andinitialize it with the import format name and the location of the file or filesto import. For example::

myImporter.Init("SHP", fileName)

This sets up the available layers for the import. Iterate through the layers. Foreach layer, determine if objects from the layer will be imported. SetInputLayer.ImportFromInputLayerOn.

Any attribute data attached to objects in the layers can be brought into thedrawing as object data. Each attribute in the source file corresponds to acolumn in the input layer. These columns can be mapped to fields in objectdata tables.

To map input columns, set the object data table name usingInputLayer.SetDataMapping(). Then iterate through each column, settingthe mapping for the column using Column.SetColumnDataMapping().

62 | Chapter 10 Import/Export

Different import drivers will have different options. The default options arestored in MapImport.ini. To modify the options, get the options usingImporter.DriverOptions(). This returns a name-value collection. Modify theoptions in the collection and call Importer.SetDriverOptions().

Some drivers also have an options dialog. For those drivers, callImporter.InvokeDriverOptionsDialog() to have the user set the options.

When all the mappings and driver options have been set up properly, callImporter.Import(). This returns an ImportResults object, which containsdetails of the import.

Import Events

The RecordReadyForImport event handler can be used to control which recordsare imported. The handler is fired for every record, before the import has beencompleted. To stop the import for a record, setRecordReadyForImportEventArgs.ContinueImport to false.

ExportingExporting is similar to importing, with some small differences.

To select which drawing objects should be exported, callExporter.SetSelectionSet(). To export all drawing objects, setExporter.ExportAll to true. To filter the list of objects, set theExporter.FeatureClassFilter or Exporter.LayerFilter properties.

The Exporter object does not have a property corresponding to InputLayer.The mappings for attribute data are set usingExporter.SetExportDataMappings(). This requires anExpressionTargetCollection parameter as input.

Items in an ExpressionTargetCollection object are name-value pairs, wherethe name corresponds to an object data expression and the value is theattribute name in the exported file. For details about object data expressionssee Expressions in Annotations (page 27) or the Map 3D Help.

Export Events

The RecordReadyForExport event handler is similar to RecordReadyForImport.To stop the export of a record, set RecordReadyForExport.ContinueExport tofalse.

Exporting | 63

64

Topology

In this chapter

■ Overview

■ Drawing Cleanup

■ Creating Topologies

■ Node Topology

■ Network Topology

■ Polygon Topology

11

65

OverviewA network topology contains a set of edges or links. Each link has a node ateach end. Multiple links can intersect at a single node.

A polygon topology represents an area coverage.

Topologies describe relationships between drawing objects. There are threetypes of topology:

■ Node, also called point

■ Network

■ Polygon

A node topology contains a set of points.

A network topology contains a set of edges or links. Each link has a node ateach end. Multiple links can intersect at a single node.

A polygon topology represents an area coverage. The borders of polygons arerepresented by edges. The polygons in a polygon topology cannot overlap,but adjacent polygons share edges.

Each object in the topology (node, link, or polygon centroid) has an ID numberthat is unique within the topology.

NOTE The topology is related to drawing objects, but it is stored independently.It is possible to have a topology where the nodes do not correspond to drawingobjects.

Internally, the relationship between drawing objects and topologies isimplemented using object data tables. For a topology named topol_name, thefollowing tables are used:

■ TMPCNTR_topol_name

■ TPMDESC_topol_name

■ TPMID_topol_name

■ TPMLINK_topol_name

■ TPMNODE_topol_name

66 | Chapter 11 Topology

TPMDESC and TPMID are not attached to any drawing objects. They are used tostore information about the topology itself. TPMDESC contains the parametersused to create the topology, such as topology type, colors, and layer names.TPMID contains a single value for the last id assigned for the topology.

TPMNODE data is attached to nodes in the topology. Each node has an ID anda resistance value.

TPMLINK data is attached to links between nodes. For network topologies thelink has values for the ID, start and end node, direction of the link, andresistance values for traversing the link in each direction. For polygontopologies the link also has values for the polygons on either side of the link.

TPMCNTR data is attached to the centroids of polygons in a polygon topology.Each centroid has values for the ID, area, perimeter, and number of links thatform the edges of the polygon.

In most cases, applications do not need to manage the object data directly.The topology API calls perform all the necessary updates. An applicationneeding to know which topologies have been defined in the drawing, however,should check the object data tables for names beginning with “TMPDESC_”.

Drawing CleanupDrawing cleanup is essential for polygon and network topologies. It ensuresthat the objects in the topology can be connected properly. For more detailsabout the various types of cleanup actions, refer to the UI documentation.

A drawing cleanup operation involves combining one or more cleanup actions.Each action is identified by an action number. Many of the actions haveadditional settings.

SettingsDescriptionAction

CLEAN_TOLErase Short Objects1

Break Crossing Objects2

CLEAN_TOL?? break target

Extend Undershoots4

CLEAN_TOLINCLUDE_LINEAROBJS

Delete Duplicates8

Drawing Cleanup | 67

SettingsDescriptionAction

INCLUDE_POINTSINCLUDE_BLOCKSINCLUDE_TEXTINCLUDE_MTEXTINCLUDE_ROTATIONINCLUDE_ZVALUES

CLEAN_TOLINCLUDE_POINTS

Snap Clustered Nodes16

INCLUDE_BLOCKSSNAP_TO_NODE

Dissolve Pseudo Nodes32

CLEAN_TOLErase Dangling Objects64

CLEAN_TOL???create arcs

Simplify Objects128

Zero Length Objects256

CLEAN_TOLApparent Intersection512

WEED_DISTANCEWEED_ANGLE

Weed Polylines1024

WEED_SUPPLEMENT_DISTANCEWEED_SUPPLEMENT_BULGE

The same class, Topology.Variable, is used for both actions and settings. Tocreate a drawing cleanup action, create a settings variable and set its values:


Dim toleranceVal As New DatabaseServices.TypedValue _

(Autodesk.AutoCAD.DatabaseServices.DxfCode.Real, 25.5)

Dim toleranceSetting As New DatabaseServices.ResultBuffer

toleranceSetting.Add(toleranceVal)

Dim blocksVal As New DatabaseServices.TypedValue _

(Autodesk.AutoCAD.DatabaseServices.DxfCode.Int16, 1)

Dim blocksSetting As New DatabaseServices.ResultBuffer

blocksSetting.Add(blocksVal)

Dim settings As New Topology.Variable

settings.Set("CLEAN_TOL", toleranceSetting)

settings.Set("INCLUDE_BLOCKS", blocksSetting)

Create an action variable and add the action and its settings:

Dim action As New Topology.Variable

action.InsertActionToList(-1, 8, settings)

If the operation will include more than one action, repeat the process andinsert more actions and their corresponding settings into the same actionvariable.

To perform the cleanup, create a TopologyClean object and initialize it withthe action variable and a set of drawing objects to clean.

Dim cleanObj As New Topology.TopologyClean

cleanObj.Init(action, Nothing)

Each individual action in the action variable is a cleanup group. Start thecleanup and go through the groups until all actions have been completed.Commit the changes using TopologyClean.End().

cleanObj.Start()

cleanObj.GroupNext()

Do While Not cleanObj.Completed

cleanObj.GroupFix()

cleanObj.GroupNext()

Loop

cleanObj.End()

For finer control over the objects being cleaned, step through the errors in agroup using TopologyClean.ErrorCur(). Fix or ignore each one individually.Set TopologyClean.ErrorPoint to change the location for the fix.

To save a profile for later use, call Variable.SaveProfile() using an actionvariable object. To reload the profile, call Variable.LoadProfile().

Drawing Cleanup | 69

Creating TopologiesTo create a new topology, get the Topologies object for the project. Select thedrawing objects to include in the topology. Call Topologies.Create(). Get areference to the newly created topology using Topologies.Item(), which takesa string parameter.

Once a topology has been created, it must be opened usingTopologyModel.Open(). When the topology is no longer needed, close it withTopologyModel.Close().

Node TopologyA node topology represents a group of related points. Node topologies areoften used as part of network or polygon topologies, to represent the endpointsof the links in the topology.

TopologyModel.GetNodes() returns the collection of nodes. For each node,Node.Entity returns the associated drawing object. If the node does not havea drawing object associated with it, Node.Entity throws a MapException.

NOTE Do not update items in a NodeCollection object using methods like Add(),Insert(), and Remove(). Instead, call the appropriate methods for theTopologyModel object, like AddPointObject().

Call NodeCollection.Dispose() when the object is no longer needed.

Network TopologyA network topology represents a group of related nodes and the connectionsbetween the nodes. The connections between nodes are links or edges in thetopology.

Each full edge is composed of two half edges, representing travel in oppositedirections between the nodes. Each half edge can have its own resistancevalue, which is used in certain types of network analysis.

TopologyModel.GetFullEdges() returns the collection of full edges. For eachedge, FullEdge.Entity returns the associated drawing object. If the edge doesnot have a drawing object associated with it, FullEdge.Entity throws aMapException.


FullEdge.GetHalfEdge returns a half edge, in either the forward or backwarddirection.

Polygon TopologyA polygon topology represents an area coverage, with polygons inside thearea bounded by edges. Any polygon in the topology must be entirely enclosedwithin its edges.

Each polygon must have a centroid.

TopologyModel.GetPolygons() returns the collection of polygons. For eachedge, FullEdge.Entity returns the associated drawing object. If the edge doesnot have a drawing object associated with it, FullEdge.Entity throws aMapException.

Polygon Topology | 71

72

Display Manager

In this chapter

■ Overview

■ Elements

■ Data Source Descriptors

■ Style

12

73

OverviewDisplay Manager provides a way to organize and style layers in AutoCAD Map3D.

NOTE The Display Manager API only manages layers that contain drawing objects.To manage layers containing FDO data use the Geospatial Platform API. See theGeospatial Platform Developer’s Guide and the Geospatial Platform API Referencefor details.

Each project has its own map manager, which is represented by aDisplayManagement.MapManager object. To get the map manager for a project,perform the following steps:


Dim managerId As ObjectId

Dim manager As MapManager = Nothing

managerId = DisplayManager.Create(activeProject).MapManagerId( _

activeProject, True)

manager = trans.GetObject(managerId, OpenMode.ForRead)

A single project can contain multiple maps. MapManager.GetEnumerator()returns an enumerator that steps through the maps in the project. Theproperties MapManager.CurrentMapId and MapManager.Current get or set thecurrent map.

A map (DisplayManagement.Map object) is sub-classed fromDisplayManagement.Group, which represents any group of elements in DisplayManager. Maps can contain layers and more groups.

ElementsDisplay Manager elements represent the different layers in the map. Elementscan be of the following types, all subclassed from DisplayManagement.Element:

■ DisplayManagement.BaseElement

■ DisplayManagement.LayerElement

■ DisplayManagement.AttachedDwgsQueryElement

■ DisplayManagement.TopologyElement

74 | Chapter 12 Display Manager

■ DisplayManagement.TopologyQueryElement

■ DisplayManagement.FeatureElement

■ DisplayManagement.RasterElement

The following iterates through the elements in a map:

Dim iterator As IEnumerator = currentMap.NewIterator(True, True)

Dim elementType As Type = GetType(DisplayManagement.Element)

Dim groupType As Type = GetType(DisplayManagement.Group)

Do While (iterator.MoveNext())

Dim itemId As ObjectId = iterator.Current

Dim thisItem As Object = _

trans.GetObject(itemId, OpenMode.ForRead)

If (thisItem.GetType().Equals(elementType) Or _

thisItem.GetType().IsSubclassOf(elementType)) Then

Dim mapElement As Item = thisItem

' Process element (layer)

ElseIf (thisItem.GetType().Equals(groupType)) Then

Dim thisGroup As DisplayManagement.Group = thisItem

' Process group

Else

' Not a Display Manager object, probably contains FDO data

End If

Loop

The BaseElement layer represents the Map Base.

LayerElement objects display drawing objects from an AutoCAD layer.

AttachedDwgsQueryElement objects represent layers containing data queriedin from attached drawings.

TopologyElement objects represent Display Manager layers that containtopology from the current drawing. TopologyQueryElement objects representlayers that contain topology queried from attached drawings.

FeatureElement objects represent layers that contain classified drawing objects.

RasterElement objects are not generally used. Instead, use FDO data with theGeospatial Platform API.

Elements | 75

Data Source DescriptorsDisplayManagement.Element has two properties to describe the data sourcefor the element:

■ AcquisitionCriteriaString

■ AcquisitionCriteria

AcquisitionCriteriaString contains a string representation of the datasource, as described in the following table:

AcquisitionCriteriaString valueElement type

AutoCAD layer nameLayerElement

Object classification class nameFeatureElement

Topology nameTopologyElement

AttachedDwgsQueryElement

TopologyQueryElement

AcquisitionCriteria is of type DisplayManagement.DataSourceDescriptor.It contains additional data about the source. Each element type has acorresponding data source descriptor type, subclassed fromDataSourceDescriptor. For example, the AcquisitionCriteria property fora LayerElement is of type LayerDataSourceDescriptor.

For LayerElement, FeatureElement, and TopologyElement,AcquisitionCriteria.AcquisitionStatement is the same asAcquisitionCriteriaString. AttachedDwgsQueryDataSourceDescriptor andTopologyQueryDataSourceDescriptor define additional methods andproperties, as described in the following table.

DescriptionMethod or property

Gets the list of attached drawings used in the queryGetDrawingList()

Sets the list of attached drawings used in the querySetDrawingList()


DescriptionMethod or property

A result buffer containing the query definition, from theQueryModel.FileOut property

Query

For TopologyQueryDataSourceDescriptor only, thetopology name used in the query

TopologyName

To add a new element, create the element and its associated data sourcedescriptor, then add it to the map. The following example adds a LayerElementthat references an AutoCAD layer named “Layer1”. For other element types,create the appropriate data source descriptor.

Data Source Descriptors | 77

Dim activeProject As Project.ProjectModel = _

HostMapApplicationServices.Application.ActiveProject

Dim docs As DocumentCollection = Application.DocumentManager

Dim activeDoc As Document = docs.MdiActiveDocument


Try


' Get the Object Id for the current Map

Dim managerId As ObjectId

managerId = _

DisplayManager.Create(activeProject).MapManagerId( _

activeProject, True)

Dim manager As MapManager = trans.GetObject(managerId, _

OpenMode.ForRead)

Dim currentMapId = manager.CurrentMapId

Dim currentMap As Map = trans.GetObject(currentMapId, _

OpenMode.ForWrite)

' Create the Layer element and set its name

Dim element As LayerElement = LayerElement.Create()

element.Name = "NewLayer"

' Create the Layer Descriptor

Dim descriptor As LayerDataSourceDescriptor = Nothing

descriptor = LayerDataSourceDescriptor.Create()

descriptor.AcquisitionStatement = "Layer1"

' Now Add the new element to the current Map

Dim iterator As IEnumerator = _

currentMap.NewIterator(True, True)

Dim elementId As ObjectId = _

currentMap.AddItem(element, iterator)

trans.AddNewlyCreatedDBObject(element, True)

element = trans.GetObject(elementId, OpenMode.ForWrite)

element.AcquisitionCriteria = descriptor

trans.Commit()

trans = Nothing

Catch e As Autodesk.AutoCAD.Runtime.Exception

' Handle exception


Finally

If Not trans Is Nothing Then

trans.Abort()

trans = Nothing

End If

End Try

StyleDisplay Manager elements can have style associated with them.

DisplayManagement.Style is the base class for all the style classes. It is basedon AutoCAD.DatabaseServices.DBObject, so it must be managed usingAutoCAD transactions. The available style classes are:

■ DefaultStyle

■ EntityStyle

■ StylizationEntityAnnotationStyle

■ StylizationEntityHatchStyle

■ StylizationEntityTextStyle

■ RasterStyle

■ ThematicStyle

Element.AddStyle() creates a reference from the element to the style objectin the database. Multiple elements can refer to the same style object.

To create a new style, call its Create() method. Set the appropriate propertiesfor the style type. Save the style in the database and add it to an element. Forexample, the following creates a new entity style and assigns it to a layerelement:

Style | 79

Try


' Open the element for write, so the style can be added

Dim layer As Element = trans.GetObject(layerId, _

OpenMode.ForWrite)

' Pass 0.0 for the current scale

Dim styleRefIterator As StyleReferenceIterator = _

layer.GetStyleReferenceIterator(0.0, True, True)

' Add the style

Dim styleEntity As EntityStyle = EntityStyle.Create()

' Set style properties

Dim color As Autodesk.AutoCAD.Colors.Color = _

color.FromColorIndex( _

Autodesk.AutoCAD.Colors.ColorMethod.None, 5)

styleEntity.Color = color

styleEntity.Name = styleName

Dim id As ObjectId

id = layer.AddStyle(styleEntity, styleRefIterator)

trans.AddNewlyCreatedDBObject(styleEntity, True)

trans.Commit()

trans = Nothing

Catch e As System.Exception

' Process exception

Finally

If Not trans Is Nothing Then

trans.Abort()

trans = Nothing

End If

End Try


MapBook

In this chapter

■ Overview

■ MapBook Templates

■ Creating a Map Book

13

81

OverviewA Map Book is a way to divide a large map into smaller tiles, by creating aseparate layout for each tile.

Each project has its own MapBook manager. CallMapApplication.GetBookManager() to get the book manager for a database.

A Map Book requires a template file that defines the layout for each sheet inthe book.

MapBook TemplatesA Map Book template is an AutoCAD template (.dwt) file with some specialcharacteristics.

The template file must define at least one layout. The layout can containviewports for the following purposes:

■ Map view, which displays the map for the area covered by a particularsheet

■ Key view, which displays a small image of the entire map, outlining thearea covered by the map sheet

■ Map legend, which displays the map legend

The layout can also contain special blocks that show links to adjacent mapsheets. Within AutoCAD Map 3D or a DWF file, the links can be used to jumpdirectly to an adjacent sheet.

The layout can also contain a title block.

To identify objects in the template as any of the special views or blocks, callthe static function MapBook.SheetTemplate.MarkElement() with the objectid and element type. For example, to mark an object as the map view, call

MapBook.SheetTemplate.MarkElement(objId, _

MapBook.TemplateElementType.MapView)

Adjacent Map Sheets

The arrows pointing to adjacent map sheets are AutoCAD block references.Each block can have an attribute that defines the direction of the arrow andcreates a link to the adjacent sheet.

82 | Chapter 13 MapBook

To create an arrow to an adjacent map sheet, place a block reference of thedesired shape and orientation into the map. The block reference should havean attribute named TAG. Set the text string of the attribute to an expressionthat defines the adjacent sheet. This expression is of the form:

%<\AcSm Sheet.direction >%

where direction is one of the following:

■ Top

■ Bottom

■ Right

■ Left

■ TopRight

■ TopLeft

■ BottomRight

■ BottomLeft

Creating a Map BookTo create a Map Book, define the book settings using TileGenerator andTileNameGenerator objects. Call BookManager.GenerateMapBook() to createthe new book.

Creating a Map Book | 83

84

Index

A

AbortCSChange event 39AbortSwapId event 39acdbmgd assembly 3ACMAP_ANN_TEMPLATE_ 24acmgd assembly 3activeDoc 7activeProj 10AliasAdded event 34AliasDeleted event 34annotation expressions 27annotation overrides 29annotation references, inserting 28annotation templates 24–25

creating 25internal names 24

annotation text 27annotations 24, 29

updating and refreshing 29Annotations, ProjectModel class 24Annotations.CreateAnnotationTemplate()26Annotations.Item() 26Annotations.TemplateNameBlockTableRecordPrefix24AnnotationTemplate.CreateAnnotationText()26AnnotationTemplate.InsertReference() 28AnnotationTemplate.SetExpressionString()26AnnotationTemplate.UpdateReferences()29application 10assemblies, required 3AttachFeatureDefinitionFile(), in

ClassificationManager 55attaching object data 18attribute definitions 27

overriding properties 27attributes, in annotation templates 25AutoCAD database object 6AutoCAD document, and Map

project 11AutoCAD RXClass objects 55AutoCAD transactions 6

Autodesk.AutoCAD.ApplicationServicesnamespace 4

Autodesk.AutoCAD.Colors namespace 4Autodesk.AutoCAD.ComponentModel

namespace 4Autodesk.AutoCAD.DatabaseServices

namespace 4Autodesk.AutoCAD.DatabaseServices.Filters

namespace 4Autodesk.AutoCAD.EditorInput

namespace 4Autodesk.AutoCAD.Geometry

namespace 4Autodesk.AutoCAD.GraphicsInterface

namespace 4Autodesk.AutoCAD.GraphicsSystem

namespace 4Autodesk.AutoCAD.LayerManager

namespace 4Autodesk.AutoCAD.PlottingServices

namespace 4Autodesk.AutoCAD.Publishing

namespace 4Autodesk.AutoCAD.Runtime

namespace 4Autodesk.AutoCAD.Windows

namespace 4Autodesk.AutoCAD.Windows.ToolPalette

namespace 4Autodesk.Gis.Map namespace 2

B

BeginClose event 39BeginCSChange event 39BeginDestroy event 39BeginOpen event 40BeginQuery event 40BeginSave event 40BeginSaveBack event 40BeginSwapId event 40

85 | Index

BeginTransform event 40

C

CanCurrentUserAlterSchema property, inClassificationManager 54

CategoryAppended event 35CategoryModified event 35CategoryUnappended event 36ClassificationManager property, in

ProjectModel class 54ClassificationManager.AttachFeatureDefinitionFile()55ClassificationManager.CanCurrentUserAlterSchema

property 54ClassificationManager.CreateFeatureClassDefinition()55ClassificationManager.CreateFeatureDefinitionFile()54ClassificationManager.DetachCurrentFeatureDefinitionFile55ClassificationManager.GetAllTags() 57ClassificationManager.GetProperties() 55ClassificationManager.GetUnclassifiedEntities()57ClassificationManager.SaveCurrentFeatureDefinitionFile()56ClassificationManager.Unclassify() 57classifying objects 57CreateAnnotationTemplate(), Annotations

class 26CreateAnnotationText(),

AnnotationTemplate class 26CreateFeatureClassDefinition(), in

ClassificationManager 55CreateFeatureDefinitionFile(), in

ClassificationManager 54creating object data tables 17CurrentScaleModified event 36

D

database object id 6debugger 5deleting object data records 21DetachCurrentFeatureDefinitionFile(), in

ClassificationManager 55DismissStylizationBegin event 36DismissStylizationCancel event 36DismissStylizationEnd event 36document, and Map project 11drawing 10

drawing objects 12DrawingActivated event 39DrawingActivationCancelled event 39DrawingAttachCancelled event 39DrawingAttached event 39DrawingDeactivated event 39DrawingDetached event 39DrawingSettingsModified event 39DrawingToBeActivated event 39DrawingToBeAttached event 39

E

EndClose event 40EndCSChange event 40EndOpen event 40EndQuery event 40EndSave event 40EndSaveBack event 40EndSwapId event 40EndTransform event 40entity, and drawing object 12events, list of 34ExportRecordError event 37expressions, in annotations 27

F

feature class definitions 55creating 55

feature definition files 54–55attaching and detaching 55creating 54

FeatureClassDefinition.SetCreateMethod()55FeatureClassDefinitionCreated event 35FeatureClassDefinitionDeleted event 35FeatureClassDefinitionModified event 35FeatureClassDefinitionRenamed

event 35FeatureClassPropertyCollection 56FeatureDefinitionFileAttached event 35FeatureDefinitionFileModified event 35field definitions, for object data tables 17

86 | Index

G

GetAllTags(), inClassificationManager 57

GetProperties(), inClassificationManager 55

getting object data 19GetUnclassifiedEntities(), in

ClassificationManager 57

H

Handle 12HostMapApplicationServices.Application10

I

ImportRecordError event 38InsertReference(), in AnnotationTemplate

class 28IntOptionModified event 34, 40Item(), Annotations class 26ItemAppended event 36ItemErased event 37ItemModified event 37

M

ManagedMapApi assembly 3map 10Map 3D session 10map application 10mapApp 10MapAppended event 36MapApplication.Projects 10MapBookAppended event 38MapBookErased event 38MapBookModified event 38MapBookSetCurrent event 38MapBookTileModified event 38MapBookTileWillBeErased event 38MapBookTreeNodeModified event 38MapBookWillBeErased event 38MapGoodBye event 36MapObjectId 13

MapSetCurrentBegin event 36MapSetCurrentEnd event 36MapSetCurrentFails event 36MapUnappended event 36

N

namespaces 2

O

object class definition files 54object classification 54, 57object data 16, 18–19, 21

attaching to objects 18getting 19updating and deleting records 21

object data tables 16object data tables, creating 17object data tables, removing 18ObjectData.FieldDefinition 17ObjectData.Record 17ObjectId 6, 12ODTables property, in ProjectModel 16

P

project, and AutoCAD document 11ProjectBeginClose event 34ProjectCreated event 34ProjectModel 10ProjectModel properties 11ProjectModel.Annotations 24ProjectModel.ClassificationManager

property 54ProjectModel.ODTables property 16ProjectOpened event 34projects 10Projects 10properties 11

of ProjectModel 11

Q

queries 48

87 | Index

QueryAdded event 41QueryCategoryAdded event 41QueryCategoryDeleted event 41QueryCategoryRenamed event 41QueryDeleted event 41QueryModified event 41QueryRenamed event 41

R

RecordExported event 37RecordImported event 38RecordReadyForExport event 38RecordReadyForImport event 38records, in object data tables 17references, required 3refreshing annotations 29removing object data tables 18RXClass objects 55

S

SaveCurrentFeatureDefinitionFile(), inClassificationManager 56

ScaleAdded event 37ScaleErased event 37ScaleModified event 37session 10SetCreateMethod(), in

FeatureClassDefinition 55SetExpressionString(), AnnotationTemplate

class 26

StringOptionModified event 34, 40StyleAppended event 37StyleAppendedToCategory event 36StyleErased event 37StyleModified event 36StyleReferenceAppended event 37StyleReferenceErased event 37StyleReferenceModified event 37StyleUnappended event 36

T

tables, for object data 16Transaction.Open() 6transactions 6

U

Unclassify(), in ClassificationManager 57UnloadApp event 34UpdateReferences, in AnnotationTemplate

class 29UpdateStylizationBegin event 37UpdateStylizationCancel event 37UpdateStylizationEnd event 37updating annotations 29updating object data records 21

V

Visual Studio debugger 5Visual Studio, setting up 3

88 | Index

AutoCAD .NET Developer's Guide

Documents

geographic

geospatial

event args

data source

documentmanager

feature class

adjacent map

feature definition