The Big Picture

The Big Picture

ActiveX Object Model

The ActiveX Object Model is an interface into the AutoCAD Land Desktop product. It is not a replacement for AutoCAD's ActiveX interface but is an extension of that interface.

Through the ActiveX Object Model you can create and edit your project data. Through AutoCAD ActiveX, you can create and modify drawing entities. There is very little overlap between the two. The ActiveX Object Model provides very little drawing interaction. The ActiveX Object Model has no user interface. AutoCAD ActiveX provides these (and others) features. Using AutoCAD ActiveX you can draw and edit AutoCAD entities, as well as prompt the user for entity selection or creation.

By using both the ActiveX Object Model and the AutoCAD ActiveX interface, you can easily customize AutoCAD Land Desktop for your business.

ActiveX Object Model Versions

When designing your applications, you can detect what version of the ActiveX Object Model is installed, and behave appropriately according to the available features. If you are using ActiveX Automation (using IDispatch methods such as Invoke and GetIdsOfNames), you can try to access a new feature with the appropriate error handling (on error handler, try-catch block, etc.). However, if you are creating compiled applications (vtable binding), you must check the program IDs that are registered for the application object:

Sub version()

  Dim app As AeccApplication

  Dim version2 As Boolean

  Dim version4 As Boolean

  version2 = False

  version4 = False

Check1:

  On Error GoTo Check2

  Set app = ThisDrawing.Application.GetInterfaceObject("Aecc.Application.2")

  version2 = True

Check2:

  On Error GoTo Done

  Set app = ThisDrawing.Application.GetInterfaceObject("Aecc.Application.4")

  version4 = True

Done:

  If version4 Then

    Debug.Print vbCrLf & "Land Desktop 2007 functionality is available."

  ElseIf version2 Then

    Debug.Print vbCrLf & "Land Desktop 2i functionality is available." & _

      "Do not try to invoke 2007 features on this desktop."

  Else

    Debug.Print vbCrLf & "No ActiveX functionality for Land Desktop is available."

  End If

End Sub

Loading Civil Engineering Features

To access civl engineering features, such as Alignment Profiles, CrossSections and Superelevations, you must have AutoCAD Civil 3D Land Desktop Companion 2009 running. The "AutoCAD Civil 3D Land Desktop Companion 2009" version of Land Desktop has the civil engineering and survey features included. The version of Land Desktop named "AutoCAD Land Desktop 2009", sometimes referred to as the stand-alone version of Land Desktop, does not have the civil engineering and survey features installed. You may get an error code AECC_E_CIVIL_NOT_LOADED (or message "Civil Desktop\civil engineering features has\have not been loaded.") when you try to access profile objects on the version of Land Desktop that does not contain civil engineering features ("AutoCAD Land Desktop 2009").

If you have AutoCAD Civil 3D Land Desktop Companion 2009 installed, the civil engineering features are automatically loaded.

Data Validation

The AutoCAD Land Desktop product gets input through menus, dialogs, command line input, and the pointer device. In most cases the program validates this input before sending the data to the functions. The ActiveX Object Model exposes the programs functions, bypassing the AutoCAD Land Desktop interface. When using The ActiveX Object Model, you are responsible for the interface. The method used for collecting and validating the data is critical to the design of any program written for use with the ActiveX Object Model. Providing incorrect data to the Methods or Properties provided in the ActiveX Object Model can result in invalid results and incorrect data in the projects databases.

Projects and Drawings

AutoCAD Land Desktop is project-based. The majority of data for a project is stored externally from an AutoCAD drawing. This includes COGO points, surfaces, and alignments. A Drawing is considered part of that project data. A drawing is associated with one project. However, a project can have multiple drawings associated with it. A drawing is a view into the project data. Because you can have multiple drawings associated with a project, you can have multiple views of the project. In one drawing, you might have all of the COGO points. In another drawing, the alignments might be displayed. The number of project-based drawings and their content is up to the end user. However, all data ends up as project data.

This idea of being project-based is central to AutoCAD Land Desktop, and the ActiveX Object Model is based on it.

Drawings and Documents

A Project can have multiple AutoCAD drawings associated with it. The Drawings collection is this list of AutoCAD drawings. This list is retrieved from the [Project]\dwgs directory.

A Document is a drawing file loaded into AutoCAD Land Desktop. Currently, the ActiveX Object Model only supports one Document being loaded at a time. This Document is derived from the AutoCAD ActiveX Document and all methods are supported.

Retrieving Project Information

The ActiveX Object Model can only retrieve data for the ActiveProject. The ActiveProject is the Project associated with the Document that is currently loaded. You can get a list of all Projects, the statistics for those Projects, and the drawings associated with those Projects. You can not get any other information from those Projects. For example, you can not get a list of alignments or surfaces for a non-active Project. In addition, you can not have an active project if AutoCAD Land Desktop is not running. If AutoCAD Land Desktop is not running, the ActiveX Object Model will not be running and you can not get any information about projects or drawings.

Keeping this in mind, usually the first thing you do is to get the ActiveProject. In VBA, to retrieve the ActiveProject, do:

Dim activeProj As AeccProject

Set activeProj = AeccApplication.ActiveProject

Project Navigation

From the Project, you can get most of the Land project information that has been exposed through the ActiveX Object Model. The Object Model diagram shows that from the Project you have direct access to CogoPoints, PointGroups, Description Keys, Surfaces, and Alignments. In addition, you have access to all of the Project specific settings and FileLocks.

CogoPoints, PointGroups, Description Keys, Surfaces, and Alignments are collections. A collection will contain zero or more objects. For example, the Surfaces collection will contain zero or more individual surfaces. To get access to an individual member of a collection, use either the Item or Enumeration methods on the collection.

Note: All collections support the Item and Enumeration methods, and the Count property. Note that all collections begin with an index of 0. This is a C++ standard, and is used consistently across AutoCAD-based ActiveX implementations.

You can query or modify the object after you retrieve it. Delete or add operations always exist at the collection level. If you think about this, it makes sense. When adding or deleting, you are changing the collection. All additions and deletions to a collection will return the new object.

What's Next

Ok, so now you have the ActiveProject, what is the next step? First, you have to figure out what you want to accomplish with your program. Let’s take a simple problem: print out the PointGroup names. The easiest way to use the ActiveX Object Model is to look at the Object Model and work your way backward. The problem is to print out some information on a PointGroup. If we click on the PointGroup in the Developers Guide, it will display all of the methods and properties for the PointGroup. In the Developers Guide, we see that PointGroup has a property called GroupName. This is what we want to print out.

After we have figured out what we want to print, then we work our way up the Object Model until we get to the Application. By doing this, we see that we have to use the PointGroups collection, the Project object, the Projects collection, and finally the AeccApplication. These are the objects needed to print out the PointGroup.GroupName. If we reverse the order and start at the AeccApplication, we can now work our way back down to the PointGroup. This is how to get PointGroup information.

You can traverse the Object Model in the same fashion for any of the objects or collections. First, find what information and object you need, then follow the Object Model down to that object.

Overview of Modules

Projects

From Projects, you can get to CogoPoints, PointGroups, DescriptionKeyFiles, Surfaces, Alignments, Parcels, CrossSections and Superelevations. In addition, the PreferencesProject, FileLocks, and Drawings are exposed.

The PreferencesProject contains the Cogo, Surface, Alignment, Parcel, Profile, and CrossSection properties. These properties return objects that expose settings for those areas. All settings are for the project.

FileLocks is a collection of all multi-user locks that exist for the project.

Drawing collection is the list of drawings for the project.

Cogo

CogoPoints, PointGroups, and DescriptionKeys are exposed through the ActiveX Object Model. The CogoPoint is a COGO point that exists in the Project database. It may or may not exist in the current drawing. When a COGO point is inserted into a drawing, it can be inserted as an AeccPoint or as a block. The AeccPoint is a COM wrapper around an ARX object.

PointGroups are used to work with a number of points at a time. A PointGroup does not actually hold the CogoPoint. The PointGroup has a range of point numbers. The point number in a point group may contain points that are not contained in the Project point database. A PointGroup can also be used to override the elevation, description, and name for the points in the PointGroup.

A DescriptionKey overrides the raw description for the COGO point. By using DescriptionKeys, you can substitute a short description with a longer description. By doing it with a DescriptionKey, you only have to change the value in one spot.

Surfaces

The Terrain Model is exposed through the Surfaces collection. Using the Surface object, you can define the inputs from PointFiles, PointGroupNames, BreakLines, ContourItems and DEM Files. You can also add Boundaries to your Surface.

You can also get all output information for the Surface. TinPoints, Edges, Faces, ElevationContours, and Watersheds can be retrieved for a Surface. You can query the Surface by point to get the elevation using the Surface.FindPoint method. You can query between two points and retrieve the coordinates where that line crosses a Surface Face by using the Surface.SampleElevations method. For a given elevation, you can retrieve all of the contours on that Surface by using the ElevationContours.Elevation method. This gives you full control over creation and querying of a Surface.

Volumes are also supported as Surface objects that result from DifferenceGrid and Composite calculation methods.

Alignments

The Alignments collection has all of the Alignments for the project. For each Alignment, you can retrieve, add, and delete the entities and station equations. Queries can also be made on the Alignment: Alignment.StationOffset, Alignment.PointLocation.

Parcels

The Parcels collection provides access to all of the parcels in the project. Each Parcel can be queried to obtain property information such as area, perimeter, centroid and name. New parcels can be created or exisiting parcel modified by editing thier individual curve and line objects.

Profiles, Cross Sections, and Superelevations

If you are using AutoCAD Civil 3D Land Desktop Companion, which includes civil engineering and survey features, extensive read access is available for existing ground profiles, finished ground profiles, cross sections, and superelevations properties. If you are using the stand-alone version of Land Desktop (titled "AutoCAD Land Desktop"), the civil engineering and survey features are not available.

You can import profiles and cross sections to the current drawing, and then access the resulting ProfileBlocks and CrossSectionBlocks for custom annotation.

Overview of Events

Events are a mechanism that allows your application to receive notification when a change occurs to the state of some object. To receive notification, you must “enable” events by providing a “handler” or “event sink”. Refer to the sample applications for examples of how to implement event handlers in VB and C++.

When coding in VBA, you must provide an event handler for all objects enabled for the Modified event. If you do not provide a handler, VBA may terminate unexpectedly.

Note that no events will be fired while a modal dialog is being displayed.

AcadObject

All of the objects outside of the Projects and Prototypes hierarchy are derived from AcadObject. This means that objects such as AeccApplication and AeccDocument derive all of the properties and methods from the parent ActiveX objects. However, since no additional events were implemented, you will use the base objects (AcadApplication and AcadDocument, for example) to get notifications in your application.

AcadEntity

The COM wrappers for the AeccDbPoint, AeccDbContour and AecDbCurveText objects support the Modified event. This event will be triggered whenever the object is modified. Modification includes whenever the value of a property is set, even if the new value is equal to the current value.

AeccObject

The AeccObject supports the Modified event, and all objects in the Projects and Prototypes hierarchy are dervied from AeccObject. While every object can support event notification, refer to the following table to determine when an event is fired.

Event notification is dispatched by a queueing mechanism that responds when AutoCAD enters a quiescent state. No events will be fired while a modal dialog is being displayed or while a command is in progress. In addition, the event queue will not accept more that one event for a given instance of a COM object at a time. If two or more event conditions occur on an object while a pending event is in the queue, there will be only one event sent when AutoCAD becomes quiescent.

Running Multiple Instances of AutoCAD

All AecBase objects that are derived from Acad objects support the Init method. This includes AecApplication, AecDocuments, AecDocuments, AecDatabasePreferences, AecPreferences, AecPreferencesFiles, AecPreferencesUser, etc.

The help string describes the Init method as an "Initialization method which must be called before accessing the AEC application object" The ActiveX Object Model for AutoCAD Land Desktop performs the call to Init automatically for Aecc objects.

It is not restricted (hidden) because it comes in handy when you are running multiple instances of AutoCAD, Architectural Desktop (AutoCAD Architecture) or AutoCAD Land Desktop. This allows you to pass in an instance of the AutoCAD application object that you are interested in, instead of relying on the active instance handed back from the Running Object Table. If you pass this into an instance of the application object, it will automatically be passed on to any new instance of child objects.