SDK:The Plug-in and the User
.SDK|SDK ..SDK:Types|SDK Types ..SDK:Using the SDK|Using the SDK ..VCOM:VCOM (Vectorworks Component Object Model)|VCOM Basics ..VCOM:Class Reference|VCOM Class Reference
The Plug-in Environment
The VectorWorks open environment is composed of 4 pieces:
- the user
- the plug-in
- the drawing
- the VectorWorks application.
The user works with the plug-in to manipulate the drawing.
VectorWorks provides the means of communication between the other parts as well as the essential functionality of a CAD system (coordinate systems, objects, math routines, etc.).
The system works because each part has a well-defined role and each part, except one, has a well-defined protocol to carry out its role. The one exception is, of course, the user, who will not submit to any protocol.
The other parts must be tolerant of unexpected user input, and provide information to the user so that he or she will naturally make the right choices.
- The user’s role is to generate events, from mouse movement and button clicks to requests for a wall or to rotate the world. The user is the action to which everything else reacts.
- The drawing is the data that the user creates. Its job is to exist.
- VectorWorks’ role is the enabler. It provides the framework in which the other parts meet.
- The role of the plug-in is to respond to the user, servicing his or her requests to create and manipulate the drawing, thereby building on the VectorWorks framework useful software. In less grand terms, a tool or menu command solves a user problem with the help of VectorWorks.
The Plug-in and the User
As stated above, the user will relate to the plug-in in any way he or she pleases. A plug-in, however, in dealing with the user, must provide the following:
- Functionality - This is not that difficult to do. If you are reading this document then you probably have some ideas, ranging from the just plain silly to the revolutionary. The difficult thing about functionality is making it useful. The rest of the requirements exist to help do this (though they are by no means sufficient).
- Undo - Documentation may guide the user to your plug-in. Help messages may reassure them. But only experience teaches them. If your plug-in permanently modifies the drawing in any way, you must preserve the user’s guarantee to experiment freely by providing undo. VectorWorks
offers a simple, powerful and generic undo facility for use in a plug-in. For information on how to implement undo, see the subsection on undo in the services section.
- Help - All plug-ins have help tags (tool tips) that concisely state the purpose of the plug-in. It appears when the user positions the cursor over the tool or menu command. In addition, plug-in developers can provide context sensitive help. This help is contained in html files on the user’s hard drive or on the internet. For information on how to provide context sensitive help, see the
subsection on context sensitive help in the services section.
- Message bar help - When a tool is selected text can be displayed in the message bar. A plug-in should display the name of the current tool mode, and prompt the user towards the next expected action
- Smart Cursor - VectorWorks uses the cursor to provide information to the user about a tool. Which cursor a tool uses should indicate to the user what task the tool will perform next. An example is how the selection tool changes from a hollow arrow when the cursor is over an object
to the standard arrow cursor when the next click will allow specification of a selection marquee. Make use of existing VectorWorks cursors and conventions where possible and make logical extensions otherwise. Some tools may need a completely new cursor. If a tool’s behavior depends on the object it is being used with or on some state internal to the tool, then the appearance of the cursor should convey this.
- Alerts - If the user attempts to use the plug-in in a way that is inappropriate or impossible, the plug-in should provide information about what is wrong and how to correct the situation. A plug-in should never fail without an explanation or with only a beep.
- Constraints - Constraints allow the user to control a plug-in’s behavior and enhance its usefulness. See the constraints subsection in the services section for a discussion of how to make a tool work with the constraint palette.
- Menu Highlighting - Menu commands have the option to make themselves unavailable when the conditions for their use are not met. Disabling a menu does not provide information. It only limits choices. A menu should not disable itself unless it is clear to the user why the functionality is inappropriate at that time. If it is unclear then the menu command should remain enabled. If the user selects it, it can provide an alert telling the user it is unavailable. The alert explains what conditions need to change for the menu command to be activated.
The Plug-in and the User | The Definition of a Plug-in | Tool or Menu Command | Communication Between VectorWorks and Plug-ins | Global Data