2 Visual Components Manuals

The program is very short and constrained on purpose to encourage experimentation. It would be best to
compile the program now and load it to Automation Runtime. But first change the 'vga' string variable in the
VA_Setup function in the cyclic part and replace it with the name of the visualization project to which output
should take place.
Expand the program to include more output or change the parameters either in the program or using the Watch
command in Automation Studio. If necessary, use the Visapi Documentation in the reference manual to refer to
details.
The following is a brief overview of the example code:
• Some variables are defined in the Initialization part of the task which mostly serve as place holders for
the position and color of the elements to be drawn. An exception is the ready variable. This variable
makes a note of whether the Visapi library was completely and successfully initialized.
• Using VA_Setup, the first part of the program establishes a connection to the Visual Components
interpreter or to its management routine (aplib.br), the runtime. This is necessary, since both the
interpreter and the Visapi functions access the same resources, and accessing these resources must be
managed.
• If the function is successful, a unique VCHandle is returned. This is necessary since several Visual
Components projects can run at the same time. Therefore an exact differentiation must be made
regarding the destination of the Visapi functions (to which project and also to which display).
Subsequently, the handle must be transferred with every other Visapi function.
• If VA_Setup fails (returns 0) , then the function in the example is called cyclically until a valid handle is
returned. As soon as VA_Setup was successfully executed and a handle is available, the ready
variable is set to 1 and the actual working part of the task is 'released'.
• Once a handle is available, then the panel resources are requested using VA_Saccess. It is possible for
drawing operations to be carried out only after a successful call (return value is 0).
• If the panel resources can be successfully requested with VA_Saccess, then the drawing function can
be called. The function names display the respective tasks, and parameters are listed in the
documentation for the respective function in the reference manual.
(Click the corresponding function in the Library Manager and press F1 to receive help).
• Finally, the resources are released by the program with VA_Srelease.
Warning:
Only call VA_Srelease if VA_Saccess has returned 0.
Warning:
Always call VA_Srelease if VA_Saccess was successfully executed! Otherwise the Visual Components
editor can no longer output to the display and the visualization freezes.
4.2.3.4 Visapi − Tutorial − Preparing the C Example
Introduction to Visual Components 2.3
If you decided to use an ANSI C implementation, then a dialog box opens with the title 'Add C Files'. First you
create a new C file which contains the program. To do this, input 'visu.c' under File Name (without the single
quotes) and confirm with Add.
268 4.2.3.4 Visapi − Tutorial − Preparing the C Example