Vdraft Developers Support Polishing Vdraft Add-ons

How to Add Polish to a Vdraft Add-on
Vdraft provides tools you can use to make your add-on behave like built-in Vdraft commands. For example, you can bundle all your commands together so they behave as one when the user undoes & redoes actions. Or you can use Vdraft's string conversion routines to display and parse strings so users can work in the same units they use in other areas of Vdraft.

Bundling Commands Together
Using the String to Units Conversions
Feedback While Picking

Bundling Commands Together

When you give Vdraft a series of commands, each command will be a separate item on the undo list. This makes it inconvenient for the user to undo what is perceived as a single action. By using the document's ICommands interface, you can have a series of commands combined together in one command. This allows the user to undo all the actions at once. Furthermore, you can give the commands a useful description so when users examine the commands they have performed, they can identify your command more easily.

In Visual Basic:

	Dim Commands As Object
	Set Commands = doc.Commands
	Commands.Group "Acme.DrawRoom Living Room"
	...	' insert blocks, draw lines, etc.
	Commands.EndGroup

In C++:

	ICommands commands(doc.GetCommands());
	commands.Group(CString("Acme.DrawRoom Living Room"));
	...	// insert blocks, draw lines, etc.
	commands.EndGroup();

This code would cause all the commands executed between Group and EndGroup to be lumped together. The first piece of text, Acme.DrawRoom, is the command name. When you click the right button in Vdraft or display the Edit pulldown menu, Undo Acme.DrawRoom will be displayed. In this example, we've added the company name to the name of the command to differentiate it from somebody else's DrawRoom command. (Alternately, you could use the program's name or have no prefix at all.) The rest of the string is the description. It can be whatever information may be useful to the user when they examine the undo/redo list.

Using the String to Units Conversions

Often you need to display distances, areas, volumes, points, or angles for the user and/or allow them to type these values in. The document's IUnits interface will convert strings such as 10' 2 1/2", 14' 2.1", 3.14r, or N 71 13' E into the appropriate distance, point, or angle. Additionally, IUnits will convert a distance, point, or angle into whatever units are in effect for the drawing - architectural, engineering, metric, scaled etc.

The following code snippets will convert the point string 10' 2 1/2", 12' 1.2, 5" and place 122.5, 145.2, 5 into MyVector.

In Visual Basic:

	Dim Units As Object, MyVector As Object
	Set Units = doc.Units
	' 10' 2 1/2", 12' 1.2, 5"
	pointstring$ = "10' 2 1/2" + Chr$(34) + ", 12' 1.2, 5" + Chr$(34)
	Set MyVector = Units.StringToPoint(pointstring$)

In C++:

	IUnits units(doc.GetUnits());
	IVector MyVector( units.StringToPoint(CString( "10' 2 1/2\", 12' 1.2, 5\"" )) );

Users have the option of displaying distances and angles in several different formats. If they have chosen metric with a scaling factor, or architectural with feet and fractional inches, then they would probably prefer to see all output in that format. The following code will create strings using the drawing's current settings.

In Visual Basic:

	point$ = Units.PointToString (MyVector)
	length$ = Units.CoordinateToString (1.234)	' note: specified in drawing units
	angle$ = Units.AngleToString (3.1415)		' note: specified in radians

In C++:

	CString point( Units.PointToString(MyVector) );
	CString length( Units.CoordinateToString(1.234) );	// note: specified in drawing units
	CString angle( Units.AngleToString(3.1415) );		// note: specified in radians

Feedback While Picking

Vdraft gives the user feedback and extra information through the status bar, text on the context sensitive popup menus, and cursor tips (the explanatory text which travels near the cursor). When your add-on uses IPickEvents or ISelectionEvents to ask the user for pick or selection information, generic defaults are used for the status bar, popup, and cursor tips. You can supplement these with text relevant to the action.

The following example prompts the user to pick a point. The popup menu will contain the text Cancel Center. On the status bar will be Pick the center of the object. The Visual Basic example uses the VdraftEvents Control. The C++ example derives cMyPickEvent from cPickEvent (defined in Vutil.hpp).

In Visual Basic:

	Dim pick As Object
	Set pick = doc.PickEvents
	pick.Name = "Center"
	pick.StatusBar = "Pick the center of the object"
	VdraftEvents1.RequestPick pick, 0

In C++:

	IPickEvents pick(doc.GetPickEvents());
	pick.SetName(CString("Center"));
	pick.SetStatusBar(CString("Pick the center of the object"));
	pick.RequestPick(id,cVariant(new cMyPickEvent(vdraft,id)));

The next example asks the user to select objects. The cursor tip will say select objects for manipulation. The popup will contain Cancel Manipulation. Once the user has selected as least one object, the popup will also say Start Manipulation. The status bar will display Select objects for manipulation. In the C++ example, cMySelectEvent is derived from cSelectEvent.

In Visual Basic:

	Dim selection As Object
	Set selection = doc.SelectionEvents
	selection.Name = "Manipulation"
	selection.StatusBar = "Select objects for manipulation"
	VdraftEvents1.RequestSelect selection, 0

In C++:

	ISelectionEvents selection(doc.GetSelectionEvents());
	selection.SetName(CString("Manipulation"));
	selection.SetStatusBar(CString("Select objects for manipulation"));
	selection.RequestSelect(id,cVariant(new cMySelectEvent(vdraft,id)));

SoftSource LLC 112 Ohio Street Suite 202 Bellingham, Washington 98225 Phone: (360) 676-0999 Sales Only: (800) 877-1875	Sales: sales@softsource.com Tech Support: tech@softsource.com

Return to Vdraft's Home Page