Example 3 - Parsing the Database and Modifying Entities


Purpose of Example


Overview of Example The entities (or objects) created by Visual CADD and the Visual CADD API are held in a database, or list. When an application needs to access certain entities to edit or get information about them, the program must have a systematic way to look through the database to find the entity it needs. This systematic look through the database is called parsing.

The Visual CADD API provides a variety of ways to parse the database, including looking through all entities, those that are selected or on the screen, those that are part of a symbol or make up boundaries of a hatch or fill, or those meeting filter criteria. These parsing methods involve starting at the first entity meeting the criteria, then proceeding one at a time to the next entity, until reaching the last entity. As you go from entity to entity, your program can process each entity as needed.

This tutorial will illustrate the essential elements of parsing a database and making changes to entities.

The example will create a tool to add single unit fractions to text or leaders which have been selected by the user. Single unit fractions are the nicely formatted fractions, such as 8 ¾ instead of 8-3/4, which can add a professional look to your drawings. In dimensions, single unit fractions are an option available from the Numeric Tab (TBN). Whenever any of the fractional dimension units are chosen, the single unit fraction option will use the single unit fractions in dimensions.

It is undocumented that single unit fractions can be placed in text and leaders, also. Besides being undocumented, Visual CADD provides no convenient way of doing it within the existing interface.

Single unit fractions are represented internally in Visual CADD by some special codes which get embedded into the dimension text. The special code for ¾, for example, is *N3*/*D4**, using * to indicate the unprintable character represented by a hexadecimal byte equal to 1 (one). These same special codes work in text and leaders. Unfortunately, the special codes cannot be entered from the keyboard. (The usual trick of ALT+0nnn only works for numbers 32 and above.)

This example will provide a solution by appending these special codes to the end of any selected text or leaders. The user can then edit each text or leader entity directly to enter the necessary fractional values and to correctly place the fraction within the text or leader, using the Edit (ED) command and a little cut-and-paste. The tool will also support the undo feature of Visual CADD.

A discussion of the essential elements of the example follows.

The undo feature of Visual CADD allows the user to undo the results of using Visual CADD tools. The Visual CADD API provides two routines, VCBeginOperation and VCEndOperation, which tell Visual CADD that the application is beginning or ending an operation which can be undone. The VCBeginOperation is used early in the application, usually before the application makes any changes to the drawing entities, and the VCEndOperation is used near the end, usually after all changes have been made.

Applications usually need to change some settings as they work. The Visual CADD API provides two routines, VCSaveSettings and VCRestoreSettings, to save and restore the settings. The VCSaveSettings is used before the application changes any settings and the VCRestoreSettings is used when the application is done, in order to return to Visual CADD with all the original settings.

Parsing works by finding the first entity satisfying a criteria, such as those selected by the user, then sequentially finding each next entity satisfying the criteria, until there are none left. The Visual CADD API provides VCFirstSelected and VCNextSelected to find the first and next of the selected entities. Each of these routines returns a success/failure code which can be tested by the application in a loop, in order to step through all the entities.

There are several different ways in which entities may be identified so that tools can work on them. The method most obvious to Visual CADD users is to select an entity. For example, Change Properties (CG) will change the properties of the selected entities.

In addition, there are two ways which are internal to the Visual CADD API: the current entity and entity handles.

The current entity is the entity which the application, through the Visual CADD API, has set to be the entity which is currently being used (or accessed). You can think of the current entity as being the 'entity on which the application is currently working.' The Visual CADD API provides routines for setting which entity is current. Both VCFirstSelected and VCNextSelected set the current entity when they are called. There are others, as well.

When entities are stored in the database, they are assigned an entity handle. This is different from the handle point, which is used to place an entity. The entity handle is a unique number which represents the entity's position within the database, beginning with 0 (zero) for the first entity. The next higher sequential number is assigned by Visual CADD to a new entity when it is added to the drawing database. Although entity handles sound very much like the subscript of an array, they should not be used in that way. Entity handles can, and do, change as the database is modified, so that entity handles are dynamic. For this reason, entity handles should be retrieved immediately before they are needed and not stored for later use. The Visual CADD API provides VCGetCurrentEntityHandle for getting the entity handle of the current entity.

Visual CADD can create several kinds of entities, such as text, leaders, linear dimensions, etc. Each kind is identified by another number, called an entity type number, which the application can use to tell what kind of entity it is. The entity type numbers for each of these kinds are listed in the Visual CADD API Help file and are also in the VCTYPE32.H and VCTYPE32.BAS declaration files. For example, the constant TEXT2D (with a value of 8) refers to text entities, and the constant LEADER2D (with a value of 21) is for leader entities.

When creating entities, the entity settings must be set first. In Visual CADD, Match Entity (ME) will match all the settings of an entity. In the Visual CADD API, the VCMatchCurrentEntity routine does the same thing.

Text and leaders contain a text string. The Visual CADD API has routines for getting or setting these strings. They are VCGetTextString, VCSetTextString, VCGetLeaderString, and VCSetLeaderString. The VCSet… routines will not change the text string of an existing entity. Instead, VCSet… is used to set the text string of an entity about to be created.

Entities in the Visual CADD API are modified or edited by changing the entity properties, then creating a copy of the original entity using the modified settings. In this tool, the text string will be modified before creating the new entity. Then, the original is deleted. The Visual CADD API routine VCDuplicate will create a new entity just like an existing entity, but using the current settings for that kind of entity. VCSetCurrentErased will delete the current entity.

As an application works through (parses) a group of selected entities, it may want to deselect the entities after it has worked on them. For example, Change Properties (CG) deselects all entities after it is done. The Visual CADD API routine to deselect the current entity is VCSetCurrentDeSelected.

When the application is done making changes to a drawing, it can redraw it by using VCInvalidateRect. This routine works like the Redraw (RD).

These are the essential elements of a tool to put single unit fractions into text and leaders. Now, all that remains is the coding.

Visual Basic Example 3 Code
Visual C++ Example 3 Code