API and Scripting Language

User’s Guide
Famic Technologies Inc.

All rights reserved. ©

API, Script and .NET Framework-based Extensibility for Automation Studio™.

Document reference: DASAPENFTP61U_01

REPRODUCTION

Reproduction or re-transmission of this manual or software, in whole or in part, by any

means is strictly prohibited without the express written consent of Famic
Technologies Inc.

Windows is a registered trademark of Microsoft Corporation.

AUTOMATION STUDIO is a registered trademark of Famic Technologies Inc.

™

350-9999 Cavendish, Montréal QC, H4M 2X5, Canada

T: +1 514 748-8050 F: +1 514 748-7169
www.automationstudio.com
 Table of Contents

1 Introduction ................................................................................................................... 1-1

2 Overview of Automation Studio™ Extensibility......................................................... 2-1
2.1 Purpose .................................................................................................................. 2-1
2.2 The Automation Studio™ Scripting Language ..................................................... 2-2
2.2.1 Advantages .............................................................................................. 2-2
2.2.2 Disadvantages .......................................................................................... 2-2
2.3 .NET Interface ....................................................................................................... 2-3
2.4 The API ................................................................................................................. 2-4
3 Getting Started Writing Scripts ................................................................................... 3-1
3.1 Installing IronRuby ................................................................................................ 3-2
3.1.1 Review the Install .................................................................................... 3-3
3.1.2 Uninstall IronRuby .................................................................................. 3-6
3.2 International Support ............................................................................................. 3-6
3.3 First Script ............................................................................................................. 3-7
3.3.1 IronRuby Example Script ........................................................................ 3-8
3.3.2 First C# Example Script........................................................................... 3-9
3.3.3 Visual Basic .NET Example Script (VB.NET) ...................................... 3-12
3.4 Launching a Script or Method ............................................................................. 3-15
3.4.1 User Variable HYPERLINK ................................................................. 3-15
3.4.2 Hyperlink Reference Field ..................................................................... 3-18
3.5 The Registration of a Script ................................................................................. 3-20
3.5.1 Registration Script Ruby........................................................................ 3-20
3.5.2 Registration Script C#............................................................................ 3-23
3.5.3 Registration Script Visual Basic ............................................................ 3-24
3.6 Run a Script at Startup ......................................................................................... 3-25
3.7 Finding Internal Names ....................................................................................... 3-26
3.8 Finding and Using Third Party Assemblies ......................................................... 3-27
3.8.1 What you need to know ......................................................................... 3-28
3.8.2 Using External Assemblies C# .............................................................. 3-29
3.8.3 What you need to know ......................................................................... 3-30
3.8.4 Using External Assemblies Visual Basic ............................................... 3-30

Famic Technologies Inc. i

Automation Studio™ – API and Scripting Language
3.8.5 What you need to know .........................................................................3-31
3.9 First Script with Functions ...................................................................................3-31
3.9.1 What you need to know .........................................................................3-34
3.10 C# Methods calling additional methods ...............................................................3-36
3.10.1 What you need to know .........................................................................3-39
4 Static and Runtime Model Overview ...........................................................................4-1
4.1 General Process Flow.............................................................................................4-1
4.2 Object Model .........................................................................................................4-2
4.2.1 Base Object ..............................................................................................4-2
4.2.2 Node .........................................................................................................4-3
4.2.3 Application...............................................................................................4-3
4.2.4 Project ......................................................................................................4-4
4.2.5 Document .................................................................................................4-4
4.2.6 View .........................................................................................................4-5
4.2.7 Component ...............................................................................................4-6
4.2.8 Ribbons ....................................................................................................4-6
4.3 Navigation ..............................................................................................................4-7
4.4 Client Entry Points .................................................................................................4-7
5 AS Scripting Environment ............................................................................................5-1
5.1 Initialization ...........................................................................................................5-1
5.1.1 Include Resources ....................................................................................5-1
5.1.2 Global Object Access ...............................................................................5-1
5.2 General Setup .........................................................................................................5-2
5.2.1 Writing Scripts .........................................................................................5-2
5.2.2 Search Path for Scripts .............................................................................5-2
5.3 How Scripts Are Run .............................................................................................5-3
5.3.1 Launch a Script from the Command Line ................................................5-3
5.3.2 User Variable HYPERLINK ....................................................................5-4
5.3.3 Hyperlink to Launch a User’s Script ........................................................5-4
5.3.4 Hooks .......................................................................................................5-4
5.3.5 Events ......................................................................................................5-6
5.4 User’s Runtime Environment .................................................................................5-6
5.4.1 Methodology ............................................................................................5-6
5.4.2 Object Type Identification .......................................................................5-7
5.5 Accessing Automation Studio™ Interfaces ...........................................................5-7
5.5.1 Application Object ...................................................................................5-7
5.5.2 Accessing Other Objects ..........................................................................5-8

ii
 Table of Contents
5.5.3 Primary Object ......................................................................................... 5-9
5.5.4 Register Scripts to be launched ................................................................ 5-9
5.5.5 Example ................................................................................................. 5-11
5.5.6 Remove Event Registration ................................................................... 5-12
5.5.7 Function Calls from a Script .................................................................. 5-12
6 .NET Environment ........................................................................................................ 6-1
6.1 Introduction ........................................................................................................... 6-1
6.2 General Setup ........................................................................................................ 6-1
6.3 Launch a .NET Method ......................................................................................... 6-1
6.3.1 Method Syntax ......................................................................................... 6-1
6.3.2 Loading Client Functionality ................................................................... 6-3
6.3.3 Command Line to Call a User’s Method ................................................. 6-4
6.3.4 Startup call to User Extendibility............................................................. 6-4
6.3.5 User Variable HYPERLINK ................................................................... 6-4
6.3.6 Hyperlink User Method Launch .............................................................. 6-4
6.3.7 Hooks ....................................................................................................... 6-5
6.3.8 Events ...................................................................................................... 6-5
6.4 User’s Runtime Environment ................................................................................ 6-5
6.4.1 Object Identification ................................................................................ 6-5
6.4.2 Accessing Automation Studio™ Interface Objects ................................. 6-6
6.4.3 Register Scripts or Methods to be Launched ......................................... 6-10
6.4.4 Sequence of Events ................................................................................ 6-12
6.4.5 Remove Event Registration ................................................................... 6-13
6.4.6 Automation Studio™  User ............................................................... 6-13
6.4.7 User  Automation Studio™ ............................................................... 6-14
6.5 User’s Runtime Environment .............................................................................. 6-15
6.5.1 Dynamically Load User’s .NET DLL .................................................... 6-15
6.5.2 ApplicationClientApi ............................................................................. 6-15
6.5.3 Additional Event Responding Objects ................................................... 6-15
6.5.4 Accessing Automation Studio™ Interface Objects ............................... 6-16
6.5.5 Application Object ................................................................................. 6-16
7 API Reference Manual .................................................................................................. 7-1
7.1 Available Interfaces ............................................................................................... 7-1
7.1.1 Objects Affected ...................................................................................... 7-1
7.1.2 Unique Identifiers .................................................................................... 7-2
7.1.3 Definitions ............................................................................................... 7-3
7.1.4 General Methods (Base) .......................................................................... 7-6
7.2 Node .................................................................................................................... 7-36
7.2.1 The Node Object.................................................................................... 7-36

Famic Technologies Inc. iii

Automation Studio™ – API and Scripting Language
7.2.2 Supported Events/Hooks ........................................................................7-36
7.2.3 Methods .................................................................................................7-37
7.3 Variable ................................................................................................................7-64
7.3.1 The Variable Object ...............................................................................7-64
7.3.2 Supported Events/Hooks ........................................................................7-64
7.3.3 Methods .................................................................................................7-65
7.4 Application ...........................................................................................................7-78
7.4.1 Access to the Application Object ...........................................................7-78
7.4.2 Supported Events/Hooks ........................................................................7-78
7.4.3 Methods .................................................................................................7-81
7.5 Project ................................................................................................................7-117
7.5.2 Supported Events/Hooks ......................................................................7-118
7.5.3 Methods ...............................................................................................7-120
7.6 Document ...........................................................................................................7-136
7.6.1 Access to the Document Object ...........................................................7-136
7.6.2 Methods ...............................................................................................7-137
7.7 Component .........................................................................................................7-191
7.7.1 Access to the Component identifier .....................................................7-191
7.7.2 Methods ...............................................................................................7-192
7.8 View ...................................................................................................................7-233
7.8.1 Access to the View identifier ...............................................................7-233
7.8.2 Methods ...............................................................................................7-234
A Glossary ............................................................................................................................. 1
B IronRuby Syntax ............................................................................................................... 1
C Internal Names .................................................................................................................. 1
D Command Line Launch of a Ruby Script ....................................................................... 1

iv
1 Introduction

Automation Studio™ provides a methodology that allows a third party developer to hook
scripts into Automation Studio™’s normal process flow with access to Automation
Studio™’s object model. This allows users to implement their own functionality from
within Automation Studio™ that can automate different tasks routinely applied by
overriding or creating new functionality, hence changing the way Automation Studio™
normally functions. To do this, Automation Studio™ comes with the following:

API: Application Programming Interface that provides an interface to AS’s runtime and
data module.

AS Scripting: Provides normal scripting methods like looping, assignments and

conditional expressions; and an access to Automation Studio™’s current object model
using the provided API. This document will supply the information required to implement
Automation Studio™ extensibility using scripts. Through this document we will show how
the language IronRuby can be used as the scripting language.

AS Scripting using Microsoft.NET Framework: Provides access to the Automation

Studio™ API from within .NET modules. In this way, Automation Studio™ brings to a third
party developer the power to manipulate and extend the internal workings of
Automation Studio™’s application environment.

This document describes how Automation Studio™ Extensibility can be used to add
functionality to Automation Studio™. The technologies used in both implementations
(Scripting and .NET) are not controlled by Famic Technologies therefore Famic
Technologies cannot assume responsibility for them.

1. .NET Framework: Terms of use are defined by the Microsoft Corporation

2. IronRuby is licensed by Microsoft under the Apache License, v2.0.

This document consists of eight chapters on the following topics:

Chapter 2 Overview of Automation Studio™ Extensibility: Supplies an overview of what

Automation Studio™ Extensibility does and a simple description of the difference

Famic Technologies Inc. 1-1

Automation Studio™ – API and Scripting Language

between scripts and the .NET development environment.

Chapter 3 Getting Started Writing Scripts: Provides a number of examples that allows a
developer to quickly start using scripts without having to concern themselves with
Automation Studio™’s data model.

Chapter 4 Static and Runtime Model Overview: Overview of Automation Studio™ data and
runtime model.

Chapter 5 AS Scripting Environment: Detailed description of how to use the scripting

environment.

Chapter 6 .NET Environment: Detailed description of how to use the C# extensibility

environment.

Chapter 7 API Reference Manual: Reference manual of all the available functionality
provided.

Appendix A: Glossary: Description of the terms used within the document.

Appendix B: IronRuby Syntax: A simple version of the available syntax provided by the
programming scripting language IronRuby.

1-2
2 Overview of Automation Studio™ Extensibility

General overview of the document.

2.1 Purpose

Automation Studio™ allows users to run their own programmatic control that affects the
runtime behavior and data of Automation Studio™. This is called Automation Studio™
extensibility. This is an extremely powerful way of supporting user’s every expanding
need to interface with additional systems or change the behavior of Automation Studio™.

The Automation Studio™ extensibility system opens up its environment and allows every
expanding functionality.

If an important need is identified that fits the API provided, it can be addressed directly
by the user and implemented using the extensibility system. Functionality that a user
wants to keep protected would never have to leave his environment. When new releases
of Automation Studio™ are provided these processes would work as before, like any data
kept by a user but this data would have functionality.

This interface is a great way for a third party to add functionality that would only be
applied by him, even things like manipulating current contents of projects as a data
preparation process. It generally opens up the general model on how things can behave.

The extensibility system allows a third party to manipulate Automation Studio™ runtime
data model and process flow using the following two methods:

 A scripting language

 .NET Interface

Either method requires some basic knowledge of running scripts.

A basic knowledge of .NET is required to use this environment. This document will not be
covering this, for this is well documented by Microsoft.

Famic Technologies Inc. 2-1

Automation Studio™ – API and Scripting Language

For the scripting environment, Automation Studio™ loads an IronRuby interpreter that is
used to translate and run the scripts written. IronRuby is one of the easiest languages to
use. The examples supplied within this document should be sufficient to get one started
writing IronRuby scripts. IronRuby is also well documented by third party content
providers. These third party content providers should be referenced in order to access
support or solve IronRuby problems.

2.2 The Automation Studio™ Scripting Language

The Automation Studio™ Scripting environment is the simple version of applying third
party functionality to Automation Studio™. This scripting language only requires a text
editor to create and deploy scripts that access Automation Studio™’s runtime data and
processing model. This environment provides most of expected methodologies required
to do this type of work.

The current implementation relies on IronRuby, a non-typed based interface language.

IronRuby is provided and licensed through Microsoft under the Apache License, v2.0.

With such a language, a client can access Automation Studio™’s runtime and data model
and implement normal scripting methods like looping, assignments and conditional
expressions. An example would allow him to write a script that could redirect the file
open operation to access files from a specific version control system.

2.2.1 Advantages

The script writer will only be required to know the scripting language that interfaces with
Automation Studio™ and the API command language described within this document. The
language provided is a very intuitive language that does not require any difficult
programming concepts.

A text editor is the only tool required in order to write scripts.

The language provided supports access to the .NET environment from within the scripts.

2.2.2 Disadvantages

The script is interpreted every time the event occurs, affecting performance. For most

2-2
 Overview of Automation Studio™ Extensibility

object events, this will not be an issue since they do not occur often, but if this type of
extensibility is used on objects like primitives that occur hundreds of times within a
display, it may affect the performance of the display.

The scripting language supported by Automation Studio™ will have to be learned.

Debugging and error checking tools are non-existent.

2.3 .NET Interface

This interface will offer .NET programmers a rich complex development environment that
can access Automation Studio™ ’s runtime and processing model.

The programmer would have to have a Microsoft’s .NET development environment in

order to generate the required DLL to be linked to Automation Studio™. With the .NET
environment, the programmer could also debug any problems that exist in the newly
developed third-party code with access to the user’s view of Automation Studio™’s
model.

Here the code does get compiled so significant performance improvements can be
expected over the Automation Studio™ scripting language method of client extensibility.

With a .NET based language, a client could build an entire interface on top of Automation
Studio™.

Advantages

 This will be significantly faster than the pure Automation Studio™ scripting
method;

 Good debugging tools exist;

 The users will be able to extend the Automation Studio™’s existing interface;

 Many developers already know the .NET environment.

Disadvantages

 Requires a .NET environment to write the users code;

 Requires that the third-party developer knows .NET.

Famic Technologies Inc. 2-3

Automation Studio™ – API and Scripting Language

2.4 The API

The API is the interface that is available to a user from within his .NET methods or the AS
scripting environment. This API provides the user access to the runtime and data model
of Automation Studio™.

This API consists of methods that can be applied to many objects within Automation
Studio™. These objects can be of type, general application, to individual projects,
documents, views, components, and catalogues to name a few. Methods are also
supplied within this API that allow a user to navigate between different objects within
Automation Studio™’s object model.

2-4
3 Getting Started Writing Scripts

This chapter will demonstrate a number of simple scripts using the Automation Studio™’s
scripting environment that can be easy installed and used. These scripts should provide a
simple overview of writing scripts without having to know very much about the
Automation Studio™’s Model.

Through this section, the scripts will be expected in the directory Scripts found in the
user’s application data folder. This will be referenced as the scripts quick start directory:

Windows Vista and 7:

C:\Users\<User>\AppData\Roaming\Famic
Technologies\Automation Studio\Scripts

Windows XP:
C:\Documents and Settings\<User>\Application Data\Famic
Technologies\Automation Studio\Scripts

<User> is the user that logged into the system.

Automation Studio™ is hardcoded to search this folder for scripts (see section 5.2.2 Search
Path for Scripts). If you were to place your scripts in a different folder, you have to define
the folder to be a scripts directory by setting the Automation Studio™ application variable
in the “Application Options dialog”.

Famic Technologies Inc. 3-1

Automation Studio™ – API and Scripting Language

Figure 3-1: Script Location Option

You can access this dialog by selecting the AS menu, and the “Automation Studio™
Options” button.

Figure 3-2: Launching AS Options

3. You can add more than one search paths, if you separate them with semicolons.

3.1 Installing IronRuby

IronRuby does not come with Automation Studio™ therefore, it has to be installed to be
used. If IronRuby does not exist on the targeted system, it can be installed from the

3-2
 Getting Started Writing Scripts

following web site:

IronRuby for .NET 4.0

http://ironruby.codeplex.com/downloads/get/217152

You must have system administrator rights, read and accept the appropriate agreements,
and following the IronRuby install instructions in order to install IronRuby. The above
install version is the one that is commonly used within Famic Technologies.

When the IronRuby installer prompts you for the features to be installed, make sure you
select at least the IronRuby main directory. Tools for Visual Studio are also useful if you
are using VS to edit your Ruby files.

Figure 3-3: IronRuby Installation

Automation Studio™ must be restarted for the new version of IronRuby to be found and
used. If Automation Studio™ was started through a shell, that shell also has to be closed.

3.1.1 Review the Install

When Automation Studio™ runs its first script, it will locate IronRuby in the path defined

Famic Technologies Inc. 3-3

Automation Studio™ – API and Scripting Language

by the system environment variables IRON_RUBY_<Version>, if not found it will

search the system path environment variable for an installed version and take the first
one found.

These install paths can be verified by opening the “Environment Variables” dialog in
Windows. This is done in the following way: Open up the “Control Panel”  “System and
Security”  “System” and then launch the “Advanced system settings”. This procedure is
a little different under different versions of windows.

Figure 3-4: Loading Advanced System Properties

The “System Properties” dialog will be launched. Select the advanced settings and then
press the “Environment Variables” button.

Figure 3-5: Accessing System Environment Variables

The “Environment Variables” dialog will be launched. In the “System Variable” section,
scroll down until you see the IRONRUBY_<version> variable. This value will contain

3-4
 Getting Started Writing Scripts

the current directory of IronRuby.

Figure 3-6: Changing IRONRUBY Variable

After that, the path statement will also contain a path to the IronRuby’s installation.

Figure 3-7: Editing System Variable

This path will be used if an unknown version of IronRuby has been installed. This allows

Famic Technologies Inc. 3-5

Automation Studio™ – API and Scripting Language

Automation Studio™, if more than one version of IronRuby exists, to select a preference.

We recommend to install only one version of IronRuby in order to support AS scripting

properly. If erroneous IronRuby defines exist like IRONRUBY_<version> that don’t
point to a valid version of IronRuby, they should be deleted. Also any paths found in the
path system environment variable that does not point to a valid version of IronRuby
either , should also be deleted.

3.1.2 Uninstall IronRuby

To uninstall IronRuby, select the Windows “Start” button  “Programs” 

“IronRuby <Version>”  “Uninstall IronRuby”.

Figure 3-8: Uninstall IronRuby

The uninstallation generally does a good job but for a number of reasons, it is possible
that the environment has not been properly reset. If this happens, the system
environment variable path must have IronRuby removed from it and the
IRONRUBY_<version> variable be deleted.

3.2 International Support

The scripts can be written using any text editor if international support is not required.

If the scripts are required to support non-ASCII based languages, they must be saved in
UTF8 format. This format is supported by most code editors, but you generally will have
to set the encoding properly.

3-6
 Getting Started Writing Scripts

NotePad++ is a good example of a code editor that supports many languages and
provides the syntax coloring rules to simplify the writing of Ruby scripts. IronRuby is a
.NET version of Ruby so any code editor that provides coloring rules for Ruby will work
very nicely. The NotePad++ application is provided by Don HO and can be accessed from
the following link:

http://notepad-plus-plus.org/download Copyright © 2010 Don HO

The following image is an example of (1) how to set (2) or convert the encoding of a file
currently being edited by NotePad++ to use the UTF8 file format, with or without the byte
order mark (BOM), either will do.

Figure 3-9: Changing UTF Encoding

 Scripts written using IronRuby will require the extension .rb.

3.3 First Script

This first example will demonstrate the basic concepts that a script requires to work. This
example will load the project C:\ASExamples\A.prx and start the image simulating.
You can change the name of the file and/or the directory, but you will have to be

Famic Technologies Inc. 3-7

Automation Studio™ – API and Scripting Language

consistent with your changes in the following examples.

Create a text file with the name IRScriptA.rb and place it into the scripts quick start
directory:

3.3.1 IronRuby Example Script

#------------------------------------------------------------
# Name of File::IRScriptA.rb
#
# Purpose::
# Loads a project and starts it simulating.
#------------------------------------------------------------
require "AS.API.Share"

applicationApi.LoadProject( "C:\\ASExamples\\A.prx" );
applicationApi.StartSimulation();

return AS::API::Share::ASAPI_RETURNS.NORMAL_PROCESSING

#------------------------------------------------------------

3.3.1.1 What you need to know

Any line that starts with “#” is ignored. This is how to comment IronRuby scripts.

require "AS.API.Share";

This command loads the DLL or script indicated. In this case, it will find the
AS.API.Share.dll assembly in the Automation Studio™ repository.
This is the general public interface to Automation Studio™ that is available to the current
user.

 You must not include any other DLL’s from the Automation Studio™ repository.

Application Api;

This is a global constant that points to the interface supplied by Automation Studio™. This

3-8
 Getting Started Writing Scripts

is provided by the assembly AS.API.Share.dll.

applicationApi.LoadProject ( "C:\\ASExamples\\A.prx" );

This is the first example of calling a method from the Automation Studio™’s application
interface. Access to the application is done through the object applicationApi. This
loads the project indicated by the parameter, into Automation Studio™.

 Note in the example the two backslashes “\\” indicating directory delimiters, this
is due to the fact that this current example was saved in pure ASCII format and a
single backslash is considered a special character.

Application Api.StartSimulation();

The method StartSimulation places the currently loaded project into simulation
mode.

return AS::API::Share::ASAPI_RETURNS.NORMAL_PROCESSING.

This indicates to Automation Studio™ to continue normal processing of the event that
triggered the call to the script after the script is complete. If this script returned
ASAPI_RETURNS.RETURN_FROM_PROCESSING, this would ignore regular processing
of the event. This way, a script builder could create a script that would bypass how
Automation Studio™ handles the open project event replacing it with his own
functionality.

3.3.2 First C# Example Script

This example will show the general structure of a C# interface that is used to access
Automation Studio™. This shows how to call a method that will open a project and start it
simulating. For any additional examples, just add the new methods to this structure. In
general, only IronRuby examples will be provided through the rest of the document.

//************************************************************
//
// Nom fichier : ClientCSharp.cs
//

Famic Technologies Inc. 3-9

Automation Studio™ – API and Scripting Language
// Classe : ClientCSharp
//
// Sujet : Example of a CSharp interface that
// will be used to access
// Automation Studio's data model.
//
// Copyright : (c) 2010 Famic Technologies inc.
// All Rights Reserved.
//***************************************************************

using System;
using System.Collections.Generic;
using System.Linq;
using System.Text;
using AS.API.Share;

namespace AS.API.Client
{
class ClientCSharp : IBaseClientApi
{
//-------------------------------------------------------
// This will keep track of the entry point to AS
//-------------------------------------------------------

IApplicationApi appApi;

//-------------------------------------------------------
// This is the first test method
//-------------------------------------------------------
public int IRScriptA() {
appApi.LoadProject("A.prx");
appApi.StartSimulation();
return(AS.API.Share.ASAPI_RETURNS.NORMAL_PROCESSING);
}

//-------------------------------------------------------
// Later in this document additional examples will be
// inserted here.
//-------------------------------------------------------
// ..
// ..
//-------------------------------------------------------

//-------------------------------------------------------

3-10
 Getting Started Writing Scripts
// Required method, reproduce as is.
//-------------------------------------------------------
public new void GetBinding(out long testValue) {
testValue = 0;
return;
}

//------------------------------------------------------
// Required method, reproduce as is, the script writer
// may want to keep the other entry points if provided
// by the event.
// ------------------------------------------------------
public bool SetParent(IApplicationApi app,
IProjectApi prj,
IDocumentApi doc,
IBaseApi bb)
{
appApi = app;
return (true);
}
}
}

3.3.2.1 What you need to know

Any line that starts with “//” is ignored. This is how to comment C# scripts.

using AS.API.Share;

This command provides access to the namespace indicated. The required DLL has
to have been included as a reference to the project.

AS.API.Share.dll is the general public interface to Automation Studio™ that

is available to the current user.

 You must not include any other DLL’s from the Automation Studio™ repository.

Famic Technologies Inc. 3-11

Automation Studio™ – API and Scripting Language
Share.IApplicationApi

This variable points to the interface supplied by Automation Studio™. This is

provided by the assembly AS.API.Share.dll just after an instance of the
object is created.

appApi.LoadProject("A.prx");

This is the first example of calling a method from the Automation Studio™’s
application interface. Access to the application is done through the object
provided when SetParent() is called. This loads the project indicated by the
parameter, into Automation Studio™.

appApp.StartSimulation();

The method StartSimulation places the currently loaded project into

simulation mode.

return(AS.API.Share.ASAPI_RETURNS.NORMAL_PROCESSING);

This indicates to Automation Studio™ to continue normal processing of the event

that triggered the call to the script, after the script is complete. If this script
returned RETURN_FROM_PROCESSING, this would ignore regular processing
of the event. This way a script builder could create a script that would bypass
how Automation Studio™ handles the open project event replacing it with his
own functionality.

3.3.3 Visual Basic .NET Example Script (VB.NET)

This example will show the general structure of a VB.NET interface that is used to access
Automation Studio™. This also shows how to call a method that will open a project and
start it simulating. For any additional examples, just add the new methods to this
structure. In general, only IronRuby examples will be provided through the rest of the
document.
'------------------------------------------------------------
' IRScriptA.vb
'
' Purpose::

3-12
 Getting Started Writing Scripts
' Loads a project and starts it simulating.
'------------------------------------------------------------

Imports System.Windows.Forms
Imports [AS].API.Share

Public Class ClientVB

Implements [AS].API.Share.IbaseClientApi

'---------------------------------------------------------
' This will keep track of the entry point to AS
'---------------------------------------------------------
Private apiApp As Share.IapplicationApi

'---------------------------------------------------------
' This is the first test method
'---------------------------------------------------------
Public Function IRScriptA() As Integer
apiApp.LoadProject("A.prx")
apiApp.StartSimulation()
Return
([AS].API.Share.ASAPI_RETURNS.NORMAL_PROCESSING)
End Function

'---------------------------------------------------------
' Required method, reproduce as is.
'---------------------------------------------------------
Public Sub GetBinding(ByRef testValue As Long)
Implements Share.IBaseClientApi.GetBinding
testValue = 0
End Sub

'---------------------------------------------------------
' Required method, reproduce as is, the script writter may
' want to keep the other entry points.
'---------------------------------------------------------
Public Function SetParent(ByVal app As
Share.IApplicationApi, _
ByVal prj As Share.IProjectApi,
_
ByVal doc As Share.IDocumentApi,
_
ByVal baseApi As Share.IBaseApi)
_

Famic Technologies Inc. 3-13

Automation Studio™ – API and Scripting Language
As Boolean Implements _
Share.IBaseClientApi.SetParent
apiApp = app
Return (True)
End Function
End Class

What you need to know:

Any line that starts with “'” is ignored. This is how to comment VB.NET scripts.

Imports [AS].API.Share

This command provides access to the namespace indicated. The required DLL has
to have been included as a reference to the project.

AS.API.Share.dll is the general public interface to Automation Studio™ that

is available to the current user.

Share.IApplicationApi

This variable points to the interface supplied by Automation Studio™. This is

provided by the assembly AS.API.Share.dll just after an instance of the
object is created.

apiApp.LoadProject("A.prx")

This is the first example of calling a method from the Automation Studio™’s
application interface. Access to the application is done through the object
provided when SetParent() is called. This loads the project indicated by the
parameter, into Automation Studio™.

apiApp.StartSimulation();

The method StartSimulation() places the currently loaded project into

simulation mode.

3-14
 Getting Started Writing Scripts
Return ([AS].API.Share.ASAPI_RETURNS.NORMAL_PROCESSING)

This indicates to Automation Studio™ to continue normal processing of the event

that triggered the call to the script after the script is complete. If this script
returned RETURN_FROM_PROCESSING, this would ignore regular processing
of the event. This way, a script builder could create a script that would bypass
how Automation Studio™ handles the open project event replacing it with his
own functionality.

3.4 Launching a Script or Method

Launching a script or method from Automation Studio TM.

3.4.1 User Variable HYPERLINK

The most universal way to launch a script from Automation Studio™ is to attach it to any
component within a document. The following process will demonstrate this approach.

1. Start Automation Studio™, when the environment has loaded, objects can be
added;

2. Add a component object into the current document like a rectangle or library
component;

3. Double click on the primitive to open its “Component Properties” dialog;

4. In the “Data” branch, click to add a new variable;

Famic Technologies Inc. 3-15

Automation Studio™ – API and Scripting Language

Figure 3-10: Inserting Hyperlink Variable

5. In the “Add Variable” dialog, select HYPERLINK for the “Select variable type”;

6. Add to the “Edit variable name” field the name you want to use. It must be
unique on the object;

Figure 3-11: Add Variable

7. To fill in the script to run information, make sure the “Details” section of the
dialog is displayed (click on “Show Details” at the bottom). Select the user
defined variable you just added and add to the “Value” field a script or method
call string. Then, add a appropriate name in the “Alias” field and finally select
the “Is displayed in tooltip” option;

3-16
 Getting Started Writing Scripts

Figure 3-12: Hyperlink Variable Attributes (Script)

Figure 3-13: Hyperlink Variable Attributes (Method)

8. Close the properties dialog;

9. In the “View” tab of the ribbon, enable the option “Component Tooltip”;

Famic Technologies Inc. 3-17

Automation Studio™ – API and Scripting Language

Figure 3-14: Tooltip Visibility

10. The script can now be launched by a left mouse click on the tooltip. For the
related script IRScriptA.rb to work, a project with the name
C:\\ASExamples\\A.prx must exist.

Figure 3-15: Tooltip look

3.4.2 Hyperlink Reference Field

The easiest way to launch a script from Automation Studio™ is to attach it to a graphical
object within a document. This is what this example will show:

1. Start Automation Studio™. When the environment has loaded, objects can be
added;

2. Add a primitive object like a rectangle to the current blank document;

3. Double-click on the primitive to open its “Component Properties” dialog;

4. Go to the “Hyperlink” branch;

3-18
 Getting Started Writing Scripts

Figure 3-16: Primitive Hyperlink Field

Figure 3-17: Calling a .NET Method from the Hyperlink Dialog.

5. Depending whether you work with a script or a method, fill the “destination”
field with:

Famic Technologies Inc. 3-19

Automation Studio™ – API and Scripting Language
SCRIPT:IRScriptA.rb

OR

METHOD:AS.API.Client::ApplicationClientApi::IRScriptA

The path to the file will be relative to the different script search paths that exist.
This relative path name cannot include “..”. This is done to limit where a user can
load scripts from.

6. Press the apply button and close the dialog;

7. Pressing CTRL + Left-click over the primitive with the script hyperlink will start the
script;

8. Validate that the project A.prx is loaded in simulation mode;

9. Now you can stop the image from simulating and proceed with the next step.

Figure 3-18: Stop Simulation

3.5 The Registration of a Script

Setting a script or method to be called when an event occurs.

3.5.1 Registration Script Ruby

Create the following script in your quick start directory:

3-20
 Getting Started Writing Scripts

#------------------------------------------------------------
# File::IRScriptB.rb
#
# Purpose::
# This example will show how to register a script to
# the open project event and add a tab, group and
# buttons to the ribbon system.
#------------------------------------------------------------

require "AS.API.Share"

#Simplify the structures provided from AS.API.Share

asEvent = AS::API::Share::ASAPI_EVENTS
asProcessType = AS::API::Share::ASAPI_PROCESS_TYPE
asMode = AS::API::Share::ASAPI_PROCESS_MODE
api = applicationApi

iconFile = api.FindFileFromScriptSearchPaths(
"ico\\mycustom2.ico");

api.RegisterEvent(asEvent.OPEN_FILE,
asProcessType.SCRIPT,
asMode.SYNC,
"OpenFile.rb");

api.AddRibbonCommandUsingDisplayName("Extended","Ruby",
"User Dialog",
"IRScriptC.rb",
iconFile);

api.AddRibbonCommandUsingDisplayName("Extended","Ruby",
"Export",
"IRScriptD.rb",
iconFile);

#Make visible our custom ribbon tab and panel

api.SetRibbonPanelVisibilityUsingDisplayName("Extended",
"Ruby", true);
return AS::API::Share::ASAPI_RETURNS.NORMAL_PROCESSING
#------------------------------------------------------------

Famic Technologies Inc. 3-21

Automation Studio™ – API and Scripting Language

3.5.1.1 What you need to know

asEvent = AS::API::Share::ASAPI_EVENTS

To access a public class supplied by an external assembly, the developer needs

to supply the entire namespace path to the class. In the above example, an
ASAPI_EVENTS object is accessed using the namespace AS::API::Share.
Notice each namespace and the class name is separated using “::”.

iconFile = api.FindFileFromScriptSearchPaths(
"ico\\mycustom2.ico");

This uses the AS options script search paths to find files that are required by the
script writer.

api.RegisterEvent(asEvent.OPEN_FILE,
asProcessType.SCRIPT,
asMode.SYNC,
"OpenFile.rb");

This registers the script OpenFile.rb to the open file event within Automation
StudioTM, therefore this script will be called just before the open file dialog is
supplied to the user, when the user selects the open file command.

If the script is an ASCII file control, characters have to be properly supported. If

the file has been saved in UTF8, this is not a problem.
api.AddRibbonCommandUsingDisplayName("Extended","Ruby",
"User Dialog",
"IRScriptC.rb",
iconFile);

api.AddRibbonCommandUsingDisplayName("Extended","Ruby",
"Export",
"IRScriptD.rb",
iconFile);

These two commands add the “Extended” tab to Automation Studio™’s ribbon
bar. This tab will contain the “Ruby” group with buttons “User Dialog” and
“Export”. When one of these buttons is selected, the script IRScriptC.rb or

3-22
 Getting Started Writing Scripts

IRScriptD.rb, respectively, will be called.

3.5.2 Registration Script C#

Only the actual methods required will be shown here. See section 3.3.2 First C# Example
Script for the structure of the module AS.API.Client and the class ClientCSharp.
Add the following method to the ClientCSharp class provided above.
//------------------------------------------------------------
//------------------------------------------------------------
// Name of File:: C# version of IRScriptB
//
// This is the second C# test. This example will show how
// to register a C# method to the open project event and add
// a tab, group and buttons to the ribbon system.
// -----------------------------------------------------------
-
public int IRScriptB()
{
appApi.RegisterEvent(ASAPI_EVENTS.OPEN_FILE,
ASAPI_PROCESS_TYPE.CSHARP,
ASAPI_PROCESS_MODE.SYNC,
"AS.API.Client.OpenFile");

System.String iconFile
=
appApi.FindFileFromScriptSearchPaths("ico\\mycustom2.ico");

appApi.AddRibbonCommandUsingDisplayName("Extended","C
Sharp",
"User Dialog",
"AS.API.Client::ClientCSharp::IRScriptC",
iconFile);

appApi.AddRibbonCommandUsingDisplayName("Extended","C
Sharp",
"Export",
"AS.API.Client::ClientCSharp::IRScriptD",
iconFile);

// Make visible our custom ribbon tab and panel

appApi.SetRibbonPanelVisibilityUsingDisplayName("Extended",

Famic Technologies Inc. 3-23

Automation Studio™ – API and Scripting Language
"C
Sharp",true);

return (ASAPI_RETURNS.NORMAL_PROCESSING);
}

What you need to know

The variable appApi is the script writer’s access point to Automation Studio™’s object
model.

3.5.3 Registration Script Visual Basic

Only the actual methods required will be shown here. See 3.3.3 Visual Basic .NET
Example Script (VB.NET) for the structure of the module AS.API.Client and the class
ClientVB. Add the following method ClientVB class provided above.
'------------------------------------------------------------
'-------------------------------------------------------------
'- Name of File:: VB version of IRScriptB
'-
'- This is the second VB test. This example will show how
'- to register a VB method to the open project event and add
'- a tab, group and buttons to the ribbon system.
'- -----------------------------------------------------------
-
Public Function IRScriptB() As Integer

apiApp.RegisterEvent(ASAPI_EVENTS.OPEN_FILE, _
ASAPI_PROCESS_TYPE.CSHARP, _
ASAPI_PROCESS_MODE.SYNC, _
"AS.API.Client.OpenFile")

apiApp.AddRibbonCommandUsingDisplayName("Extended", "Visual
Basic", _
"User Dialog", _

"AS.API.ClientVb::ClientVB::IRScriptC", _
"mycustom2.ico")

apiApp.AddRibbonCommandUsingDisplayName("Extended", "Visual
Basic", _

3-24
 Getting Started Writing Scripts
"Export", _

"AS.API.ClientVb::ClientVB::IRScriptD", _
"mycustom2.ico")

'- Make visible our custom ribbon tab and panel

apiApp.SetRibbonPanelVisibilityUsingDisplayName("Extended", _
"Visual
Basic", True)

Return ([AS].API.Share.ASAPI_RETURNS.NORMAL_PROCESSING)

End Function

What you need to know

The variable apiApp is the script writer’s access point to Automation Studio™’s object
model.

3.6 Run a Script at Startup

The Automation Studio™ options “Startup Script” sets what Ruby script or .NET method is
called as Automation Studio™ is launched. This script or method should be used to setup
(register) the scripting environment that will augment the runtime version of Automation
Studio™. To run a script or method every time Automation Studio™ starts, just go to the
“Automation Studio Options” dialog, and fill the “Startup Script” field.

Famic Technologies Inc. 3-25

Automation Studio™ – API and Scripting Language

Figure 3-19: Running a Ruby script or .NET method at Startup

When AS is launched the file IRScript.rb will be loaded and run from the directory
defined in one of the “Scripts Location” fields. The script will add to Automation Studio™’s
ribbon bar an additional tab called “Extended” with a group “Ruby” and two commands
“User Dialog” and “Export”. These buttons will be used to test the following examples.

3.7 Finding Internal Names

The Application Options dialog contains the option “Display Internal Variable Names in a
Tooltip”:

3-26
 Getting Started Writing Scripts

Figure 3-20: Displaying Internal Variables in a Tooltip

This option, when enabled, sets Automation Studio™ into a mode where internal names
of many variables will be provided in a tooltip.

Figure 3-21: Example of how an internal variable is displayed

The above figure shows a tooltip for the variable “Maximum Differential Pressure” of a
“Fixed Displacement Pump – Hydraulic” component. Here the last line indicates the
internal name of that variable that should be used in scripts.

3.8 Finding and Using Third Party Assemblies

Third party assemblies can be used directly by a script builder. Once the assemblies are
loaded, the public information (namespaces, classes, methods etc...) can be used. In the
following example we use System::Windows::Forms object to create a message
box.

Famic Technologies Inc. 3-27

Automation Studio™ – API and Scripting Language

The script uses the Windows registry to find assemblies so it is good practice to include
the public key related to the assembly that has to be loaded.

Create the following script in your quickstart directory:

#------------------------------------------------------------
# Name of File::IRScriptC.rb
#
# Purpose::
# Generate an users dialog box. Notice that if a Ruby
# file does not access elements from Automation Studio’s
# model the script does not require AS.API.Share or the
# return value.
#------------------------------------------------------------
require 'System, Version=2.0.0.0,
Culture=neutral,
PublicKeyToken=b77a5c561934e089'
require 'System.Windows.Forms,
Version=2.0.0.0, Culture=neutral,
PublicKeyToken=b77a5c561934e089'

System::Windows::Forms::MessageBox.show "User Dialog Box"

return
#------------------------------------------------------------

3.8.1 What you need to know

require 'System, Version=2.0.0.0,

Culture=neutral,
PublicKeyToken=b77a5c561934e089'

The above line supplies the required information in order to use the
System.dll provided by Windows. If you do not know the version or public
key of a particular DLL, it can be found by using the Assembly Cache viewer
within Windows Explorer. To find the information required to load your
assemblies, simply browsing %windir%\assembly\ (for example,
C:\WINDOWS\assembly) displays assemblies culture and key information
registered with the system.

The second method is to include any missing paths to the DLLs in the
environment variable LOAD_PATH. DLL’s that are loaded in this fashion do not

3-28
 Getting Started Writing Scripts

have to be signed.

"
Figure 3-22: Configure where DLL’s can be found.

To access a public class supplied by an assembly, the developer needs to supply

the entire namespace path to the class. In the above example a “MessageBox”
object is accessed using the namespace:

System::Windows::Forms::MessageBox.

Notice each namespace is separated by “::”.

3.8.2 Using External Assemblies C#

//------------------------------------------------------------
// Name of File:: C# version of IRScriptC.rb
//
// Purpose::
// Generate an users dialog box. Notice that if a Ruby
// does not access elements from Automation Studio’s model
the
// script does not require AS.API.Share or the return value.
//------------------------------------------------------------
public int IRScriptC()
{

MessageBox.Show("Mail sent");

return (ASAPI_RETURNS.NORMAL_PROCESSING);
}

Famic Technologies Inc. 3-29

Automation Studio™ – API and Scripting Language

3.8.3 What you need to know

using System;

using System.Collections.Generic;

using System.Linq;

using System.Text;

using AS.API.Share;

using System.Windows.Forms;

Any assembles used need to be accessed using the using command and added as a
reference to the module.

To access a public class supplied by an assembly, the developer needs only to supply the
class name if the namespace is provided using the using command.

3.8.4 Using External Assemblies Visual Basic

'---------------------------------------------------------
---
' Name of File::IRScriptC.rb
'
' Purpose::
' Generate an users dialog box. Notice that if a Ruby
' file does not access elements from Automation Studio’s
' model the script does not require AS.API.Share or the
' return value.
'---------------------------------------------------------
---
Public Function IRScriptC() As Integer

System.Windows.Forms.MessageBox.Show("User Dialog
Box")

Return
([AS].API.Share.ASAPI_RETURNS.NORMAL_PROCESSING)

3-30
 Getting Started Writing Scripts
End Function

3.8.5 What you need to know

Imports System

Imports System.Windows.Forms

Any assemblies used need to be accessed using the Imports command.

To access a public class supplied by an assembly, the developer needs to supply the
entire namespace path to the class. In the above example, a MessageBox object is
accessed using the namespace System.Windows.Forms.MessageBox. Notice each
namespace is separated by periods“.”.

3.9 First Script with Functions

In IronRuby a function must be defined before it is used. Here is the required syntax:

Famic Technologies Inc. 3-31

Automation Studio™ – API and Scripting Language

def <Function Name>([Parameters])

[Body]
end

The following example will show how to create and call functions from IronRuby:
#------------------------------------------------------------
# Name of File::IRScriptD.rb
#
# Purpose::
# This search for all projects currently loaded and export
# them to the following file formats.
# pdf, dxf, svg, and tiff
#------------------------------------------------------------
require "AS.API.Share"

require 'System, Version=2.0.0.0,

Culture=neutral,
PublicKeyToken=b77a5c561934e089'
require 'System.Windows.Forms,
Version=2.0.0.0, Culture=neutral,
PublicKeyToken=b77a5c561934e089'

ObjDoc = AS::API::Share::ASAPI_OBJ.DOCUMENT_API;
ObjPrj = AS::API::Share::ASAPI_OBJ.PROJECT_API;

#------------------------------------------------------------
# FlagDocumentsToBeExported( IProjectApi prj)
# Loop through all documents found in the current
# Set each document’s export flag
# Parameters::
# IProjectApi prj Project to be searched
#------------------------------------------------------------
def FlagDocumentsToBeExported(prj)

iCnt2 = prj.GetChildCount(ObjDoc);
j = 0

until j == iCnt2
doc = prj.GetNthChild(j,ObjDoc);
doc.SetToBeExported(true);
j += 1
end
end

3-32
 Getting Started Writing Scripts

#------------------------------------------------------------
# ExportAllExistingProjects(appApi)
# This will be called if the user presses OK from the
# message dialog.
# Parameters::
# * applicationApi is supplied as a parameter.
# Returns::
# * NIL
#------------------------------------------------------------
def ExportAllExistingProjects(appApi)

appApi.SetExportPath( "C:\\temp" );

iCnt = appApi.GetChildCount(ObjPrj);
i = 0
until i == iCnt
prj = appApi.GetNthChild(i, ObjPrj);

strPrjName = prj.GetName();

FlagDocumentsToBeExported(prj)
prj.Export(strPrjName, "pdf" );
prj.Export(strPrjName, "dxf" );
prj.Export(strPrjName, "svg" );
prj.Export(strPrjName, "tiff" );
i += 1
end

end
#------------------------------------------------------------

#------------------------------------------------------------
# Main Ruby Script::
# This process will export all projects and documents
# to many different file formats.
#
# Supplied Interface::
# applicatonApi Interface to Automation Studio's
# application object
#------------------------------------------------------------

MsgBox = System::Windows::Forms::MessageBox
MsgResultOK = System::Windows::Forms::DialogResult.OK

Famic Technologies Inc. 3-33

Automation Studio™ – API and Scripting Language
MsgBtns = System::Windows::Forms::MessageBoxButtons

msgboxRtn = MsgBox.Show( nil,

"Export all documents, do you want to continue.",
"Export All Projects", MsgBtns.OKCancel )
if (msgboxRtn == MsgResultOK)
ExportAllExistingProjects(applicationApi)
end

return AS::API::Share::ASAPI_RETURNS.NORMAL_PROCESSING

3.9.1 What you need to know

MsgBox = System::Windows::Forms::MessageBox

IronRuby assigns variables when they are accessed or changed. In the above
example, the MsgBox variable provides access to the message box object from
the namespace System::Windows::Forms. Now all message box methods
are available through MsgBox.

msgboxRtn = MsgBox.Show( nil,

"Export all documents, do you want to continue.",
"Export All Projects", MsgBtns.OKCancel )
if (msgboxRtn == MsgResultOK)
ExportAllExistingProjects(applicationApi)
end

This segment of code fetches information from the user of the application in
order to get permission to export all projects currently loaded. If the user agrees
the function ExportAllExistingProjects() is called.

def ExportAllExistingProjects(appApi)
# ...
end

This lines show the process of how to create a function that can be called
anywhere within the script.

3-34
 Getting Started Writing Scripts

def ExportAllExistingProjects(appApi)

appApi.SetExportPath( "C:\\temp" );

iCnt = appApi.GetChildCount(ObjPrj);
i = 0
until i == iCnt
prj = appApi.GetNthChild(i, ObjPrj);
# Do something with the project object supplied
end

end

This is a classic example of navigating through all the children of the application
object. The application object contains projects. From each project object their
respective documents can be accessed. The parameter above ObjPrj indicates
to the search to return projects. You will see the same form within the function
FlagDocumentsToBeExported().

appApi.SetExportPath( "C:\\temp" );

Here the applicationApi is passed to the variable appApi when the

ExportAllExistingProjects() function is called. From the
applicationApi object, the user can set the current directory to be used to
export files to.

doc.SetToBeExported(true);

This sets the “To be exported” attribute on a document defined by the variable
doc. When the next export process is run, this attribute will determine if the
document should be exported.

prj.Export(strPrjName, "pdf" );

This process exports the project to the specified file format. All files labeled to be
exported will be exported.

Famic Technologies Inc. 3-35

Automation Studio™ – API and Scripting Language

3.10 C# Methods calling additional methods

Only the actual methods required will be shown here. See section 3.3.2 First C# Example
Script for the structure of the module AS.API.Client and the class ClientCSharp.

The IRScriptD methods are launched from the “Extended” menu bar created by
example 3.5.2 Registration Script C#.
//------------------------------------------------------------
// Name of File:: IRSCRIPTD
//
// Purpose::
// The following set of methods are the C# version of the
// IRSCRIPTD demo.
//
// This search for all projects currently loaded and export
// them to the following file formats. pdf, dxf, svg, and
// tiff
// -----------------------------------------------------------
-

// -----------------------------------------------------------
-

// -----------------------------------------------------------
-
// Main C# IRSCRIPTD ::
//
// Purpose::
// This process will export all projects and documents
// to many different file formats.
//
// Supplied Interface::
// applicatonApi Interface to Automation Studio's
// application object
// -----------------------------------------------------------
-

public int IRScriptD()

{
// This segment of code fetches information from the user
// of the application in order to get permission to export
// all projects currently loaded.

3-36
 Getting Started Writing Scripts

DialogResult msgboxRtn = MessageBox.Show(null,

"Export all documents, do you want to
continue.",
"Export All Projects",
MessageBoxButtons.OKCancel);
if (msgboxRtn == DialogResult.OK)
{
ExportAllExistingProjects();
}
return (ASAPI_RETURNS.NORMAL_PROCESSING);
}

// -----------------------------------------------------------
-
// FlagDocumentsToBeExported( IProjectApi prj)
//
// Purpose::
// Set all documents export flag to true for all documents
// found in the provided project.
//
// Parameters::
// IProjectApi prj Project to be searched
// -----------------------------------------------------------
-
void FlagDocumentsToBeExported(IProjectApi prj)
{

// This is a classic example of navigating through all the

// children of the application object. The application
// object contains projects. From each project object
// their respective documents can be accessed and so on.

IDocumentApi doc;
int iCnt2 = prj.GetChildCount(ASAPI_OBJ.DOCUMENT_API);

for(int j = 0; j < iCnt2; j++){

doc = (IDocumentApi)prj.GetNthChild(j,
ASAPI_OBJ.DOCUMENT_API);
doc.SetToBeExported(true);
}
}

Famic Technologies Inc. 3-37

Automation Studio™ – API and Scripting Language
// -----------------------------------------------------------
-
// ExportAllExistingProjects()
//
// Purpose::
// This method exports all projects to a set of different
// file formats.
//
// This will be called if the user presses OK from the
// message dialog.
//
// Parameters::
// * Nil
// Returns::
// * Nil
// -----------------------------------------------------------
-
void ExportAllExistingProjects()
{
System.String strPrjName;
IProjectApi prj;

// From the application object the user can set the

// current directory to be used to export files to.
appApi.SetExportPath( "C:\\temp" );

int iCnt = appApi.GetChildCount(ASAPI_OBJ.PROJECT_API);

for( int i = 0; i < iCnt; i++)

{
prj = (IProjectApi)appApi.GetNthChild(i,
ASAPI_OBJ.PROJECT_API);

strPrjName = prj.GetName();

// This sets the “To be exported” attribute on a

// document defined by the variable “doc”. When the
// next export process is run this attribute will
// determine if the document should be exported.
FlagDocumentsToBeExported(prj);

// Here the project found is exported to many

// different file formats.
prj.Export(strPrjName, "pdf", true );

3-38
 Getting Started Writing Scripts
prj.Export(strPrjName, "dxf", true );
prj.Export(strPrjName, "svg", true );
prj.Export(strPrjName, "tiff", true );
}
return;
}

3.10.1 What you need to know

The comments in the code should cover most topics. Note that different structure for the
methods within C# as compared to Ruby.

Famic Technologies Inc. 3-39

4 Static and Runtime Model Overview

This is an overview of the API and Scripting static and runtime model. This provides some
basic information on how the scripts run within Automation Studio™.

4.1 General Process Flow

The following should provide the reader with a general idea of how the two basic types
of external process are inserted into Automation Studio™’s process flow.

Figure 4-1: General Process Flow

A minimum of a couple of processes would have to be written, the first process would
tell Automation Studio™ which hooks/events the user would like to add functionality to
and an additional process for each event that would respond to the respective
hooks/events.

Famic Technologies Inc. 4-1

Automation Studio™ – API and Scripting Language

The above diagram shows how a startup script registers functionality to different events
that could occur in Automation Studio™ and then, when the events occurs, run the
associate script/method.

4.2 Object Model

Concerning the way the extensibility system has been developed, the user will need a
little understanding of an object model but not much. The basic requirement here is that
the developer understands that the methods supplied through the API will be dependent
on an object. He will have to use the proper object with the correct method to get the
desired effect.

The interface supplied will relate to a simplified version of Automation Studio™’s object
model. Through this view, a client will be able to manipulate the data and process flow
that currently exist.
Automation
Ribbon Studio
Projects
Projects
Projects

Projects
Documents
Projects
(Diagrams) Projects
Projects Projects
Variables
Projects
Components
Projects
Projects
Layers Projects
Views
View
Projects
Projects
Variables

Figure 4-2: Users View to AS’s Object Model

4.2.1 Base Object

The use of the term base through the document indicates common functionality used by
all objects. For example, this common functionality gives information about:

 The number of the object’s children;

 The parent;

4-2
 Static and Runtime Model Overview

 The children;

 How to register and unregister events.

4.2.2 Node

The use of the term node through this document indicates common functionality used by
projects, documents and components. Examples of this common functionality are

 Get Variables;

 Set Variables.

4.2.3 Application

The application object (Automation Studio™) is the base of the system available to the
user of Automation Studio™. This object can be used as starting point to access all other
available objects. This is the first object created and only one is ever created.

Through the application object, the user can access all other objects that exist in the
system. From the application object, projects can be accessed, then from the projects
documents can be accessed. Finally from documents, views and components may be
accessed.

 The application object is the base of the system and every event that will supplies
extended functionality will be processed through this object.

The following are a few examples of what can be directly done using the application
object. For a complete list see the IApplicationApi object in chapter 7 API Reference
Manual.

 Load Projects;

 Select View using the current project;

 Set the Language;

 Turn on or off the process of logging actions;

 Create Ribbon tabs, groups, and buttons (commands);

Famic Technologies Inc. 4-3

Automation Studio™ – API and Scripting Language

 Hide Ribbon tabs, groups, and buttons (commands);

 Show Ribbon tabs, groups, and buttons (commands);

 Start Simulation;

 Stop Simulation.

Some of the above requirements will be handled by generic function/method calls that
will use the form “apply function to all children of type”.

4.2.4 Project

A project is a container of related data and is stored on the file system as a single file.
Mainly projects contain documents and an application may contain many projects.

The following are a few examples of what can be directly done using the project object.
For a complete list see the IProjectApi object in chapter 7 API Reference Manual.

 Show/Hide all diagrams;

 Access a diagrams interface;

 Show Diagrams;

 Modify the current simulation model.

4.2.5 Document

Many documents can be contained by a project and these documents can be many
different things. Therefore what the interface does when called will be dependent on
what the document is. A document could be any of the following objects:

 Schematic Diagram;

 Folio Diagram;

 Sequential Function Chart / Grafcet;

 Report.

4-4
 Static and Runtime Model Overview

The following are a few examples of what can be directly done using the document
object. For a complete list, see the IdocumentApi object in chapter 7 API Reference
Manual.

 Maximize;

 Minimize;

 Initial Zoom;

 All Zoom;

 Hide All Views;

 Show;

 Hide;

 Hide All Layers;

 Show Layers.

4.2.6 View

A document can contain many views. Views are used during navigation to find a
predetermined image within a document.

 Set Vertical Stretch True/False

 Set Horizontal Stretch True/False

 Set Symmetric Stretch True/False

 Set Always on top True/False

 Set Pan True/False

 Set AllZoom True/False

 Set Content to Follow Window Size True/False

Famic Technologies Inc. 4-5

Automation Studio™ – API and Scripting Language

4.2.7 Component

Component is a defined object within an image. Documents may contain many

components. Components are the basic building block of a graphical image. The
developer will be able to affect the following attributes on a component.

 Set colors;

 Set line styles;

 Set line widths;

 Set text used;

 Move, Rotate, Resize;

 Push, pop;

 Get Properties;

 Set Properties.

4.2.8 Ribbons

From the application object, the third-party developer will be able to access the system
ribbon.

This will supply the user with the ability to manipulate the availability of tabs, groups and
buttons (commands), or to add personal tabs, groups, and buttons to the system ribbon.
These new interfaces could be used to significantly alter the behavior of Automation
Studio™.

Scripts will be able to access the following information/methods of the ribbon bar:

 Hide All;

 Hide or show a tab, group and/or button;

 Add a tab, group, and/or button;

 Show.

4-6
 Static and Runtime Model Overview

4.3 Navigation

The interface supplied will be dependent on the objects that generated the event.

From these objects, it will be possible to obtain access to other objects within the model.
To save some fetching of information, if the object is contained within a project and/or
document, these projects and/or documents are supplied directly to client’s environment.

Any additional information will have to be extracted by navigation through the object
model until the correct object is found. Then the correct object calls the appropriate
methods.

 From the application object, the developer can fetch all the projects, the ribbon,
and the picture window.

 From a project, accessed through the application object, the developer can access
the contained documents and plotters.

 From a document, accessed through a project, the developer can access the
contained layers, views, and components.

4.4 Client Entry Points

A client entry point is a term that is used for either hooks or events. A User Entry Point is
any point in processing (event/hook) where a user can add additional functionality.

When the system starts up, an initialization script or .NET process can be called allowing a
client to set all the different entry points to be processed. Registering or un-registering
points can take place within any third-party method or script.

After registering the different Scripts or .NET processing entry points these events are
handled in the following way.

Famic Technologies Inc. 4-7

Automation Studio™ – API and Scripting Language

Figure 4-3: Entry Point Management

The entry points/events available to the scripts or .NET extensibility developer are listed
with each object described within the API section of this document and within the
interface files available (IApplicationApi.cs, IProjectApi.cs, etc). These entry
points will be set points at which the redirection can occur, bypassing, or not, normal
processing. These entry points can be system wide or dependent on a single object.

Also during registration, the user will be able to define how the entry points will be
handled, either by a user .NET method or a simple AS script.

4-8
5 AS Scripting Environment

This section may be skipped if the user intends only to use .NET extensibility.

5.1 Initialization

5.1.1 Include Resources

In IronRuby the require command makes an assembly available to the script. In order
to have access to the Automation Studio™ API the script builder must include access to
AS.API.Share for AS’s general interface:

require "AS.API.Share"

The following are a number of definitions that are required by different method calls.
Access to these definitions can be simplified by assigning them to variables at the top of
a script.

asTid = AS::API::Share::ASAPI_OBJ
asVarType = AS::API::Share::ASAPI_VARTYPES
asEvent = AS::API::Share::ASAPI_EVENTS
asProcessType = AS::API::Share::ASAPI_PROCESS_TYPE
asMode = AS::API::Share::ASAPI_PROCESS_MODE
asReturns = AS::API::Share::ASAPI_RETURNS

5.1.2 Global Object Access

The following global identifiers are available to any Automation Studio™ script called by
Automation Studio™. These supply access to important objects.

applicationApi Supplies access to the application object. This is always

available.

Famic Technologies Inc. 5-1

Automation Studio™ – API and Scripting Language

projectApi Supplies access to the project that is related to the object that
initiated the script call. This is only available if the event was
generated by a specific project.

documentApi Supplies access to the document that is related to the object

that initiated the script call. This is only available if the event
was generated by a specific document.

baseApi Supplies access to the object that initiated the script call. This
is only available if the event was generated by a specific
project.

There is only one applicationApi and this variable will always point to the
application object. All the other variables will be dependent on how the script was
launched. Example, if the script was initiated as a parameter to Automation Studio™ as it
was starting only the applicationApi object will exist. All the other variables will be
assigned to “nil” and an exception will be thrown if used. The script developer needs to
know which and when these objects come into existence if s/he intends to use them.

5.2 General Setup

This section provides the steps required to run scripts within Automation Studio™.

5.2.1 Writing Scripts

The only tool required to write Automation Studio™ user scripts is a text editor of some
kind. These scripts will have to follow the syntax of the supported language. As noted
before (section 3.2 International Support), a good text editor for simple AS scripts is
Notepad++.

5.2.2 Search Path for Scripts

The following is the general process that is used to find script files used within AS.:

 If the search path provided uses the following format

<Drive>:<Path>\<Script file name>
only that file will be loaded and executed.

5-2
 AS Scripting Environment

 If the search path provided starts with “.\” the script will be loaded relative to
the current directory.

 If the search path provided starts with “\”, the script will be loaded relative to
the current drive.

 If script string does not use any of the hardcoded paths described above the
following paths will be searched:
 AS’s system scripts directory.
 AS’s execution path plus the sub directory Scripts.
 The user’s application data path plus the sub-directory Scripts.
 Common application data path plus the sub-directory Scripts.

The system scripts directory can be set in any of the following ways in order of
precedence:

 A previous script using the application object method:

SetScriptsDirectory(string scriptsDir)

 AS’s Startup command line parameter:

/SCRIPTS:<script directory>

 AS’s scripts location defined by the application option “Scripts Location”

5.3 How Scripts Are Run

The section shows the different ways a script can be launched from within Automation
Studio.

5.3.1 Launch a Script from the Command Line

The parameter /SCRIPT:<Script Syntax> can be used to launch a user’s

initialization process as Automation Studio™ starts up.

Syntax

AsProjet.exe /SCRIPT:<Script Name>[<><ParN>]

Famic Technologies Inc. 5-3

Automation Studio™ – API and Scripting Language

AsProjet.exe Executable of Automation Studio™.

Script Name Name of the required script file to be run at startup.

Automation Studio™ expects to find this script in one of the
directories indicated in the general setup section.

ParN Parameter 1 to N all separated by spaces.

5.3.2 User Variable HYPERLINK

Please refer to section 3.4.1 User Variable HYPERLINK.

5.3.3 Hyperlink to Launch a User’s Script

Please refer to section 3.4.2 Hyperlink Reference Field.

5.3.4 Hooks

Throughout Automation Studio™, points in processing have been identified, callout hooks
have been supplied. During the running of an initialization script the developer can
register any of these points in processing and to a script to be called when the event
occurs.

In the following sections some examples are supplied.

5.3.4.1 New Project Example

As Automation Studio™ receives the “on new project” event a user may need to execute
his own processing. To do this the script developer assigns the “New project” hook to a
script of his choosing. This is done by calling the RegisterEvent() method within an
initialization script. The following is an example of how to assign a script with the name
OnProjectCreate.rb to the NEW_FILE hook.

5-4
 AS Scripting Environment
pEvent = AS::API::Share::ASAPI_EVENTS
pType = AS::API::Share::ASAPI_PROCESS_TYPE
pMode = AS::API::Share::ASAPI_PROCESS_MODE

applicationApi.RegisterEvent (pEvent.NEW_FILE,
pType.SCRIPT,
pMode.SYNC,
"OnProjectCreate.rb");

The above lines could be added to a functioning script file like ASScriptSetup.rb
located in the script directory, and this information set to AS through the Automation
Studio™ Options (see section 3.6 Run a Script at Startup).

The return value from the script will indicate to Automation Studio™ whether or not
normal processing should proceed.

pReturn.NORMAL_PROCESSING This indicates to Automation Studio™ that once the

script is complete, continue as if nothing had happened.

pReturn.RETURN_FROM_PROCESSING This indicates to Automation Studio™ that

once the script is complete, continue skip the normal processing expected from
the event.

The same script callout will exist wherever the user opens a project.

5.3.4.2 Open Project Example

Same goes for the open project event, as Automation Studio™ receives this event a user
needs to be able to execute his own processing. In this case the user will be hooking a
C# method, after the user method has completed its work the script indicates to
Automation Studio™ whether or not normal processing should precede.

To setup this hook the script developer would have had to include the following call in
his initialization script.

Famic Technologies Inc. 5-5

Automation Studio™ – API and Scripting Language
pEvent = AS::API::Share::ASAPI_EVENTS
pType = AS::API::Share::ASAPI_PROCESS_TYPE
pMode = AS::API::Share::ASAPI_PROCESS_MODE

applicationApi.RegisterEvent (pEvent.OPEN_FILE,
pType.CSHARP,
pMode.SYNC,
"OnCheckOut");

After this hook has been registered whenever the “Open Project” is selected the user’s
script OnCheckOut.rb is called first.

5.3.4.3 Extension of this process

Above are just a few examples of points in the system where a user may be interested in
applying functionality with the use of scripts or C# methods.

All the interfaces that will be developed will be described in detail in chapter 7 API
Reference Manual.

5.3.5 Events

Events are handled in a similar way.

5.4 User’s Runtime Environment

What is required in the windows environment to be able to run scripts from within
Automation Studio™.

5.4.1 Methodology

The scripting language supplies an object/method based interface to AS’s object model.
This scripting interface simplifies Automation Studio™’s object model so that the script
developer does not have to understand all the complexities of object oriented
programming in order to produce effective scripts.

The user will have to access the desired interface before calling methods related to
specific objects.

5-6
 AS Scripting Environment

As far as the user is concerned objects are just pieces of data maintained by Automation
Studio™. As an example objects can be the application itself, projects, documents,
graphical components etc.

5.4.2 Object Type Identification

The script writer will often call a function that extracts information of a particular type
from objects within Automation Studio™; therefore the user has to supply, as a
parameter, the type. The following list describes the identifiers of the different types of
objects that the user may need access to.

The following is a list of the object types and their identifiers that a developer can expect
to work with (Note: asTid = AS::API::Share::ASAPI_OBJ):

Automation Studio™ Object Type Identifier

Application asTid.APPLICATION_API
Component asTid.COMPONENT_API
Document asTid.DOCUMENT_API
Layer asTid.LAYOR_API
Project asTid.PROJECT_API
Variable asTid.VARIABLE_API
View asTid.VIEW_API

An example of how these identifiers can be used; a script can query a document for
component type children instead of a view of type children that could also be extracted.

5.5 Accessing Automation Studio™ Interfaces

Indicates how a script writer can access key objects within Automation Studio™.

5.5.1 Application Object

The variable applicationApi points to the application. This is the starting point for
any AS script that requires access to AS’s object model. The methods that are available
through this object are available through the interface IApplicationApi. This

Famic Technologies Inc. 5-7

Automation Studio™ – API and Scripting Language

interface is described in section 7.4 Application.

5.5.2 Accessing Other Objects

From the application object the script writer can then access objects available through
AS.API.Share module. This is done by using supplied search methods or by
navigating through the object structure from the application object. Here are a few
examples of search methods that can be used from any object dependent on the class
IBaseApi like the application object.

IProjectApi GetProjectApi();
IProjectApi GetProjectApi(string prj);
IDocumentApi GetDocumentApi();
IDocumentApi GetDocumentApi(string doc);
IDocumentApi GetDocumentApi(string doc, string prj)
IViewApi GetViewApi(string view);
IViewApi GetViewApi(string view, string doc);
IViewApi GetViewApi(string view, string doc, string prj);

These are methods that supply access to projects, documents and views. Of course what
is returned is dependent on the object the method was called from.

Here is an example of accessing a project and querying how many documents it contains.

asTid = AS::API::Share::ASAPI_OBJ;
prj = applicationApi.GetProjectApi("Prj1");
nNumDoc = prj.GetChildCount(asTid.DOCUMENT_API);

All interfaces supplied, include the following methods that allows the script builder to
access additional interfaces.

// Fetches the parent of the object

IBaseApi GetParent();
// Returns the number of iObjType children from the
object
int GetChildCount(int iObjType);
// Returns the identifier of the iNth child from the
// object

5-8
 AS Scripting Environment
// This Nth child will be extracted from the list defined
// by iObjType
// The identifier is global to all objects
IBaseApi GetNthChildId(int id, int iNth,
int iObjType);

With the above set of interfaces it is possible to navigate between the available objects
within Automation Studio™. This is accomplished by the fact that all client available
objects are accessible through the offspring of the application object that all scripts have
access to. The applications contain projects, projects contain documents, and documents
contain views, variables and components; and components contain variables.

5.5.3 Primary Object

The primary object is the object that generated the event that launched the script. In
most cases this is the application object.

IBaseApi GetPrimaryBaseApi();

This returns an object that is dependent on the interface IBaseApi. The primary object
can then be used to access related objects like parents and children as described in the
previous section.

5.5.4 Register Scripts to be launched

The registration function described in this section is used to assign user functionality to
possible events that can occur. This registration process can be called at anytime, during
initialization (most common) or after any event that has already been hooked to user
functionality.

This method must be called for every event a user wants to hook functionality to.

int RegisterEvent(int iEType, int iPType, int iMode,string

szP)

Famic Technologies Inc. 5-9

Automation Studio™ – API and Scripting Language

where:

iEType Identifier of the required event/hook (user callout entry

point) from table related to the object that the
RegisterEvent function was applied to. This table can be
found in the beginning section of each object in the reference
section of this document.

iPType asProcessType.CSHARP: User C# interface will be

used.

asProcessType.SCRIPT: Script processing will occur

iMode Currently for internal use.

szP Name of the method or script to call during the event.

5.5.4.1 Event Type (iEType)

There are two specific types of events, static and dynamic.

In the case of a static event, when the event is registered to a specific type of object, all
objects of that type will respond to the event.

In the case of dynamic events, they are dependent on the object that receives the
registration. When the above method is called on a specific object that hooks a specific
dynamic event, this is applied to the object and does not affect any other objects of the
same type.

Most events are applied to the application object. Since there is only one application
object these events are always triggered when they occur.

5.5.4.2 Process Type (iPType)

This allows the registration of how events will be handled. Either the event will use the
user’s C# interface or scripts. This allows the user to use a mix of different techniques to
respond to different events.

5-10
 AS Scripting Environment

5.5.4.3 Unique identifier (szP)

The unique identifier supplies the script or the method name that has to be called when
the event occurs.

5.5.5 Example

The following text describes how to create a hook to the OnCheckIn.rb script file
using the RegisterEvent() method in an initialization script.

First step is to create a script in a valid script directory using the following name. Call it
InitAS.rb.

Add the following lines to the file InitAS.rb in the scripting directory.

require "AS.API.Share"

pEvent = AS::API::Share::ASAPI_EVENTS
pType = AS::API::Share::ASAPI_PROCESS_TYPE
pMode = AS::API::Share::ASAPI_PROCESS_MODE

applicationApi.RegisterEvent (pEvent.CLOSE_FILE,
pType.SCRIPT,
pMode.SYNC,
"OnCheckIn.rb");

Launch Automation Studio™ using the initialization script InitAS.rb. This is done by
including the following syntax as Automation Studio™ is launched.

AsProjet.exe /SCRIPT:InitAS.rb

When processed, this will register the script OnCheckIn.rb to the close file event.

Now whenever a “close file” event occurs, the OnCheckIn.rb script will be processed
and if this script returns pReturn.NORMAL_PROCESS, the regular handling of the close
file event will be processed. If the script returns
pReturn.RETURN_FROM_PROCESSING the regular handling of the close file event
will be skipped.

Famic Technologies Inc. 5-11

Automation Studio™ – API and Scripting Language

5.5.6 Remove Event Registration

The following command will remove any event registration on the related object.

applicationApi.UnRegisterEvent(int iEventType);

Where iEventType is the event type on the object.

5.5.7 Function Calls from a Script

With respect to the interface to the Automation Studio™ model the scripts act very much
like equivalent calls found in the C# module. The major differents is performance.
Otherwise you are accessing the same interface that third party .NET developers are
using.

5-12
6 .NET Environment

This section shows what is required to link and call .NET methods from objects unrelated
to Automation Studio.

6.1 Introduction

This section may be skipped if the user intends only to use AS scripting environment.

The AS .NET extensibility environment is an object-based programming environment

designed to provide rich development capabilities. This runs in the same process space as
Automation Studio™ so it is the better solution if there are concerns about performance.

6.2 General Setup

Running .NET methods from Automation Studio™. We provide in this manual C# and
VB.NET examples. Only these two languages have been tested, other .NET languages
logically should work.

6.3 Launch a .NET Method

Different methods and the required syntax to call .NET methods from Automation
Studio™.

6.3.1 Method Syntax

The interface used to call .NET methods from Automation Studio™.

6.3.1.1 Method String

Throughout this document <Method String> defines the method syntax used in the
interface to indicate to Automation Studio™ what specific assembly object and method to
call. This is a string that uses the following syntax:

Famic Technologies Inc. 6-1

Automation Studio™ – API and Scripting Language

[[<dll name>::]<class name>::]<method>[< >[<ParN>]]

dll name: Name of require assembly. (optional). If supplied the class

and method must also be supplied. The first instance of a
call to a particular assembly will load the assembly.

class name: Name of class containing the method. (optional). A single

instance of this class will be created to be used as an
interface to all additional method calls using this class.

method: Functionality to be called. This method must be public.

ParN: The required parameter, separated by spaces.

6.3.1.2 Where a Method String is Used

Methods can be called from Automation Studio™ through the followining interfaces. To do
this, the user has to supply information about the assembly, class used and the desired
method to be called in the <Method String>.

In the application startup options:

Figure 6-1: Startup Script

Example of a <Method String>

AS.API.Client::ClientCSharp::IRScriptA

Command-line parameter (This will be restricted): /METHOD:<Method String>

6-2
 .NET Environment

Properties dialog, hyperlink field: METHOD:<Method String>

Method that can be called by any object within an AS or .NET client script:

IBaseApi.RunMethod(<Method String>);

If the <Method String> does not supply the assembly or class name, the system will
automatically create the following strings, dependent on the object that generated the
call:

Object based on the IApplicatonApi:

AS.API.Client::ApplicationApiClient::<Method Name>

Object based on the IProjectApi:

AS.API.Client::ProjectApiClient::<MethodName>

Object based on the IDocumentApi:

AS.API.Client::DocumentApiClient::<MethodName>

6.3.2 Loading Client Functionality

Client can create any modules to be used with Automation Studio™ as long as they do
not conflict with DLLs and classes that exist elsewhere. These modules can be used to
interact with AS through the use of the interface AS.API.Share.

Here is the process of linking such a module to AS:

1. Create a module that contains a class that is dependent on the interface

IApiClientBase found in the AS.API.Client.dll.

2. Link the external functionality to an object or the application by using one of the
plug-in interfaces described in the section 6.3.1 Method Syntax. The DLL created
by the method builder must be inserted into the system cash or in a directory
that is included in the path environment variable so the assembly can be safely
found by Automation Studio ™;

Famic Technologies Inc. 6-3

Automation Studio™ – API and Scripting Language

3. When the interface is called the DLL provided will be loaded and an instance of
the object will be created, and finally using the newly created object the method
indicated will be called. If anything does not exist an exception will be thrown,
caught by AS and the script builders process will be discontinued.

6.3.3 Command Line to Call a User’s Method

The parameter /METHOD:<Method Name> can be used to launch a user’s initialization

process as Automation Studio™ starts up. This method of creating a call out to user
functionality will not be enabled by default.

Syntax

AsProjet.exe /METHOD:<Method to Launch>

AsProjet.exe Executable of Automation Studio™.

<Method to Launch> Method that will be run at start up. See Section 6.5.2
ApplicationClientApi on how to write the class that contains
this method.

6.3.4 Startup call to User Extendibility

If the application option #Vo(App)StartupMethod is set to a <Method to

Launch> string, the method will be called on startup.

6.3.5 User Variable HYPERLINK

Please refer to section 3.4.1 User Variable HYPERLINK.

6.3.6 Hyperlink User Method Launch

Please refer to section 3.4.2 Hyperlink Reference Field.

6-4
 .NET Environment

6.3.7 Hooks

Throughout Automation Studio™ points in processing have been identified callout hooks
have been supplied. During the running of the initialization scripts the developer can
register any of these points in processing and hook it so that his .NET method is called.

6.3.8 Events

Events are handled in a similar way.

6.4 User’s Runtime Environment

6.4.1 Object Identification

The script writer or .NET developer will be working with objects. These objects map back
to equivalent objects found in Automation Studio™’s model. While working with these
objects you may have to supply an object type identifier. The following is a list of the
object interfaces and their identifiers that a developer can expect to work with.

Object Identifiers for .NET Extensibility

Automation Studio™ Interface Identifier

IApplicationApi TID.APPLICATION_API

IComponentApi TID.COMPONENT_API

IDocumentApi TID.DOCUMENT_API

IPictureWindowApi TID.PICTURE_API

IProjectApi TID.PROJECT_API

IViewApi TID.VIEW_API

An example of how these identifiers can be used, a script or .NET method can query for

Famic Technologies Inc. 6-5

Automation Studio™ – API and Scripting Language

the child of type TID.COMPONENT_API from the document interface receiving an

interface of type IComponentApi to the specific child instead of a different child of
type TID.VIEW_API.

6.4.2 Accessing Automation Studio™ Interface Objects

Any class that will be used to communicate with the Automation Studio™ object model
will have to be derived from IBaseClientApi found in the assemble
AS.API.Share.dll. The following methods are required in the class created for this
purpose.
void GetBinding(out long testValue);
bool SetParent(IApplicationApi app,
IProjectApi prj,
IDocumentApi doc,
IBaseApi baseApi);
void SystemInitialization();

Here is an example of creating a class that can be called from Automation Studio.
Automation Studio™ will use the <Method String> supplied by the different
interfaces within a project, script or startup value to load and run a method from an
external source during the appropriate event

As described earlier the method string is made up of the following:

[[<dll name>::]<class name>::]<method to launch>

The client module will have to reference the module AS.API.Base.dll that includes
the base class interface required to communicate with Automation Studio™.

C# Example:

At the top of the module this referenced module will have to be included:

using AS.API.Share;

The class created must use the reference IBaseClientApi. The following contains the
manditory methods required by the object.

6-6
 .NET Environment

class BaseClientApi : IBaseClientApi

{
static IApplicationApi m_app;

public void GetBinding(out long testValue)

{
testValue = 0;
return;
}

public bool SetParent(IApplicationApi app,

IProjectApi prj,
IDocumentApi doc,
IBaseApi baseApi)
{
m_app = app;
return(true);
}
}

VB.NET Example:

Famic Technologies Inc. 6-7

Automation Studio™ – API and Scripting Language
Imports System.Windows.Forms
Imports [AS].API.Share

Public Class ClientVB

Implements [AS].API.Share.IBaseClientApi

Private apiApp As Share.IapplicationApi

Public Sub GetBinding(ByRef testValue As Long) _

Implements Share.IBaseClientApi.GetBinding
testValue = 0
End Sub

Public Function SetParent(ByVal app As

Share.IApplicationApi, _
ByVal prj As Share.IProjectApi,
_
ByVal doc As Share.IDocumentApi,
_
ByVal baseApi As Share.IBaseApi)
_
As Boolean Implements _
Share.IBaseClientApi.SetParent
apiApp = app
Return (True)
End Function
End Class

Automation Studio™ finds the clients DLL, loads it, and creates an instance of the class
defined in the <Method String> by <class name>, then calls following expected
methods.

SetParent() This provides the required entry points to

the clients interface.

GetBinding() This method is used to identify externally

linked modules. This method should set
the provided parameter to zero.

6-8
 .NET Environment

The different objects provided by SetParent() will only have a value if they are
available at the time of the event that created the external interface. If the object that
generated the event was a project, then the current project and application are supplied.
No single document can be supplied since no specific document is contained by the
event. The application object is always available.

The IApplicationApi instance provide to the SetParent() method provides

access to the application object. This will probably be the main interface to the
Automation Studio™ object model.

The IBaseApi instance provided to the SetParent() method provides access to the
object that generated the event. If the object that generated the event was a
component, example button up on a line, then this will return access to
IComponentApi interface object. It is up to the user to cast the result to the correct
object.

Now the objects available to the developer through the above methods are all based on
the base class IBaseApi. This is the base interface into AS’s object model.

class IBaseApi
{
...
bool IsA(int iObjType); // Returns true if
// the type matches

This method is used to validate that an object fetched, using the general methods, is the
correct object type.

The base class IBaseApi also supplies the following access to the object’s children and
parents.

// Fetches the parent of the object

IBaseApi GetParent();
// Returns the number of iObjType children from object
int GetChildCount(int iObjType);
// Returns the identifier of the iNth child from object

Famic Technologies Inc. 6-9

Automation Studio™ – API and Scripting Language
// This Nth child will be extracted from the list
// defined by iObjType
// The identifier is global to all objects
IBaseApi GetNthChild(int iNth, int iObjType);

Most objects contain other objects: applications contain projects, projects contain
documents etc. These general methods allow a developer to navigate between such
objects; of course the developer would have to know the existing relationships.

The unique ID of an object can be accessed using the following method.

int GetId();

Once in possession of the object’s identifier the actual object can be accessed using the
following method. The object identifier is unique within the system so any object based
on the interface IBaseApi can access any other object if the correct identifier is
supplied.

IBaseApi GetInstanceWithId(int id); // Returns the

object using the identier.

The definition of the available interfaces can be found in the assembly

AS.API.Share.dll.

6.4.3 Register Scripts or Methods to be Launched

The registration method described in this section is used to assign user functionality to
possible events that can occur. This registration process can be called at anytime, during
initialization (most common) or after any event that has already been hooked to user
functionality.

This method must be called for every event a user wants to hook functionality to.

int RegisterEvent(int iEType, int iPType, int iMode,

string method)

6-10
 .NET Environment

iEType Identifier of the required event (user callout entry point) from
table AsApiEvents related to the object that the
RegisterEvent method was called from.

iPType
ASAPI_PROCESS_TYPE.CSHARP : User .NET interface
will be used.

ASAPI_PROCESS_TYPE.SCRIPT : AS script processing

environment will be used.

iMode ASAPI_PROCESS_MODE.SYNC or .ASYNC: Currently

everything is set to SYNC.

szParam Name of the method or script to call during the event.

6.4.3.1 Event Type

There are two specific types of events, static and dynamic.

In the case of a static event, when the event is registered to a specific type of object, all
objects of that type will respond to the event.

In the case of dynamic events, they are dependent on the object that receives the
registration. When the above method is called on a specific object that hooks a specific
dynamic event, this is applied to the object and does not affect any other objects of the
same type.

Most events are applied to the application object. Since there is only one application
object these events are always triggered when they occur.

6.4.3.2 Process Type

During registration this indicates what process type will handle the events when they are
called. Either the event will use the user’s .NET interface or Automation Studio™ scripts.
This allows the user to use a mix of different techniques to respond to different events.

Famic Technologies Inc. 6-11

Automation Studio™ – API and Scripting Language

6.4.3.3 Method String ( <method >)

The <method string> that has to be called when the event occurs.

[[<dll name>::]<class name>::]<method to launch>

6.4.4 Sequence of Events

When the point in processing that gets diverted is related to an object other than the
Application Object the sequence of events is as follows:

Figure 6-2: Sequence of Events (Non Application Objects)

When the component receives this event it posts the launch user method with the
application and finishes its processing of the event. After completion of the event, the
application object launches the user’s method or script. This way whatever the user does
in his script it will not destabilize Automation Studio ™. This does limit the user from being
able to bypass Automation Studio™ functionality.

When the object is an Application the sequence of events is as follows.

6-12
 .NET Environment

Figure 6-3: Sequence of Events (The Application Object)

When the application generates the event it calls the launch user event and waits for a
user’s response. When user processing is complete the launch user method will return a
code that indicates whether or not Automation Studio ™ will continue processing the
event.

6.4.5 Remove Event Registration

The following command will remove any event registration on the related object:

int UnRegisterEvent(int iEventType);

Where iEventType is the event previously registered.

6.4.6 Automation Studio™  User

Automation Studio™ generates calls to the user’s interface when different events occur,
if they have been registered. A few examples of events on the application object are
OPEN_FILE, PROJECT_CREATED, CLOSE_FILE, NEW_FILE, RUN_SCRIPT,
SNAPSHOT_DOC_CREATED, SIMULATE_PAUSED, SIMULATE_STOPPED,
SIMULATE_STOP, SIMULATE_START and CALL_METHOD.

All objects will have a set of possible events that can be registered; these events will be
documented with each object in each section.

Famic Technologies Inc. 6-13

Automation Studio™ – API and Scripting Language

These events, when generated, are sent to their respective objects, ApplicationApi,
ProjectApi etc. When these objects process the events, if hooked by client
functionality will create an instance of a mirror object based on the class
IBaseClientApi.cs.

This allows the .NET developer to have an instance of each object to work as an interface
to Automation Studio™.

Third-party developers through this process can add their own process flow to the current
Automation Studio™ environment.

Only one interface object will be created to communicate with their respective objects in
Automation Studio™.

6.4.7 User  Automation Studio™

How to access Automation Studio™’s object module from a user’s Automation Studio™
script or.NET modules can be found in the following interfaces:

 IApplicationApi.cs

 IBaseApi.cs

 IComponentApi.cs

 IDocumentApi.cs

 IProjectApi.cs

 IViewApi.cs

 IVariableApi.cs

This supplies a complete set of the methods available to the user modules. Of course this
set of interfaces will grow over time.

All .NET objects created by a developer have to be derived from the interface defined in
the module IBaseClientApi.cs.

This interface supplies these objects with a set of standard calls to manipulate their

6-14
 .NET Environment

environment.

6.5 User’s Runtime Environment

6.5.1 Dynamically Load User’s .NET DLL

User functionality will only be loaded when an event takes place that requires it. When
required, any dependent modules will be dynamically loaded. Errors will not be
generated if AS scripting environment DLL’s or the external modules do not exist, unless
they are explicitly called from a display or a loading script.

To demonstrate developing a module to be linked into Automation Studio™ the module

AS.API.Client.dll is supplied. Therefore external functionality should be provided
through a different assemble.

6.5.2 ApplicationClientApi

Automation Studio™ expects there to be a class derived from the BaseClientApi class
supplied. If the user does not supply the assembly and the class name it will expect a
.NET assembly with the name AS.API.Client that includes the following class:

class ApplicationClientApi : IBaseClientApi

{

The rest is up to the third party developer. The developer can create any methods that
will be registered to events or be called by the initialization or hyperlinks processes.

This object ApplicationClientApi will receive most of the user entry point events
as long as this object was the one created by the user’s class factory using the identifier
ASAPI_OBJ.APPLICATION_API. Only one of these objects can be created.

6.5.3 Additional Event Responding Objects

All objects a third party developer would like to register events to need to be created in
the same way that the ApplicationClientApi. Register events that call methods
based on IBaseClientApi.

Famic Technologies Inc. 6-15

Automation Studio™ – API and Scripting Language

Only one object will be registered to an equivalent object in Automation Studio ™.

6.5.4 Accessing Automation Studio™ Interface Objects

The system initialization entry point object is expected to be an instance of the class
BaseClientApi so it will receive a call SetParent() that will supply all the required
interfaces for future work. It is good practice to save these interfaces in the external
object and provide them when required. Here is a suggested interface.

class BaseClientApi : IBaseClientApi

{
public IApplicationApi GetApplication();
public IProjectApi GetProject();
public IDocumentApi GetDocument();
public IBaseApi GetBaseApi();

After fetching each object the methods described in the following section apply.

6.5.5 Application Object

The variable applicationApi points to the application. This is the starting point for
any AS script that requires access to AS’s object model. The methods that are available
through this object are available through the interface IApplicationApi. This
interface is described in section 7.4 Application.

Example: The following fetches the application object and tests to see that it is an
application object.

IApplicationApi pApp;
pApp = GetApplication();
if(pApp.IsA(TID.APPLICATION_API))

6-16
 .NET Environment
Register Methods to be Launched. Example

This interface can be called in the initialization method in order to hook scripts or
methods onto possible future events.

int RegisterEvent(int iEType, int iPType, int iMode,

string szParam)

First step, create the class ApplicationClientApi and compile it into the assembly
AS.API.Client.dll with the following two methods:

void InitializeClientInterface1()
void OnCheckIn(string pStr)

In the body of the method InitializeClientInterface1() hook the

OnCheckIn() method to the event ASAPI_EVENTS.CLOSE_FILE by adding the following
lines.

IApplicationApi app = getApplication();

app.RegisterEvent(ASAPI_EVENTS.CLOSE_FILE,
ASAPI_PROCESS_TYPE.CSHARP,
ASAPI_PROCESS_MODE.SYNC,
"OnCheckIn");

In order to get Automation Studio™ to run the initialization method

InitializeClientInterface1(), use the following syntax on the command
line.

AsProjet.exe /METHOD:InitializeClientInterface1

When Automation Studio™ starts the method InitializeClientInterface1 will

be called which will register the event OnCheckIn to the close file event using C#.

When the close file event occurs the method OnCheckIn(<filename>) will be called
on the application object. Different events will require different parameters so the third-
party developer has to know the available events and the parameters that will be

Famic Technologies Inc. 6-17

Automation Studio™ – API and Scripting Language

supplied with the event. This will all be documented in the interface file IBaseApi
found in Assembly AS.API.Share.

6-18
7 API Reference Manual

This section describes the available access to Automation Studio™’s object model that can
be used by a third-party developer. This interface can be used to manipulate the current
data contained within the current AS environment.

The reference manual will be organized by object that a user is required to manipulate.
Methods may be repeated due to they may behave slightly differently dependent on the
object involved in the call.

7.1 Available Interfaces

Overview of the available objects contained within AS’s model that can be accessed.

7.1.1 Objects Affected

With the scripting interface all calls are methods and these methods are generally
applied to objects within the Automation Studio™ environment.

From the client’s script, Automation Studio™ object model can be accessed through the
following interfaces. Each interface will be described in detail in the following sections.

 Application: Always available general interface to the base of Automation

Studio™’s object model.

 Component: Access to display objects.

 Document: Access to a document

 Project: Access to a project

 View: Access to a view

 Variable: Access to the variable existing on an object.

Famic Technologies Inc. 7-1

Automation Studio™ – API and Scripting Language

7.1.2 Unique Identifiers

All objects available to a builder can be accessed using a unique identifier. This identifier
is returned by a number of supported methods:

 int GetId();

 int GetParentId();

 int GetNthChildId(int idx, int iChildType).

The following command can then be used to retrieve the required object using an object
identifier.

object GetInstanceWithId(int id)

Also supplied the ability to access the object directly:

IBaseApi GetParent();

IBaseApi GetNthChild(int idx, int iChildType);

It is safe practice to validate that you have the correct object before using it. To do this
the method IsA() is supplied. Example (both parent and obj are IBaseApi based
objects):

parent = obj.GetParent();
if(parent.IsA()){
:
}

Methods Applicable To All Types of Objects

This section describes the functions and identifiers that can be used by all object types
available to the script builder. These objects can be identified using a common identifier
supplied by the navigation functions or the launch script interface. Most functions will
require this identifier in order to know what object to apply the function to.

7-2
 API Reference Manual

7.1.3 Definitions

This section supplies a common set of identifiers that exist within Automation Studio™.

7.1.3.1 ASAPI_PROCESS_TYPE
pType = AS::API::Share::ASAPI_PROCESS_TYPE Ruby
pType = AS.API.Share.ASAPI_PROCESS_TYPE; CSHARP

The system has been defined to allow a user to make calls to a script, or to methods
written in C#, so these attributes allow the user to set what process method will be used.

pType.CSHARP

This attribute is used as a parameter to the RegisterEvent() method. This

indicates that the user has supplied a C# method to handle the event when it
occurs.

pType.SCRIPT

This attribute is used as a parameter to the RegisterEvent() method. This

indicates that the user has supplied a script to handle the event when it occurs.

7.1.3.2 ASAPI_EVENTS

pEvent = AS::API::Share::ASAPI_EVENTS Ruby

pEvent = AS.API.Share.ASAPI_EVENTS; C#

This structure can be set to different objects. When registering events,

pEvent.OPEN_FILE
Just before AS’s open file dialog is initiated. Here a user can bypass this
functionality with his own.
pEvent.CLOSE_FILE
Just before AS’s close file processing occurs. Here a user can bypass this

Famic Technologies Inc. 7-3

Automation Studio™ – API and Scripting Language

functionality with his own.

There are many more, but they will be documents at the beginning of each object
section.

Ruby Example (AS Scripting environment) this is a code segment.

pEvent = AS::API::Share::ASAPI_EVENTS
pType = AS::API::Share::ASAPI_PROCESS_TYPE
pMode = AS::API::Share::ASAPI_PROCESS_MODE

applicationApi.RegisterEvent(pEvent.CLOSE_FILE,
pType.SCRIPT,
pMode.SYNC,
"OnCheckIn.rb");

After this method has been called, when the close file event occurs, Automation
Studio™ will first call the script OnCheckIn.rb. Knowing what events can be
mapped and how to map them comes from the definition of each event found in
this reference manual.

The mode AS::API::Share::ASAPI_PROCESS_MODE.SYNC is currently

the only mode supported, this option is here for future compatibility.

7.1.3.3 ASAPI_RETURNS

asReturns = AS::API::Share::ASAPI_RETURNS Ruby

asReturns = AS.API.Share.ASAPI_RETURNS CSHARP

A third party script can supply the following flags when the script ends. The hook that
launched a user’s script will be waiting on one of the following two returns.

asReturn.NORMAL_PROCESSING

When the user’s script returns this normal processing will proceed.

7-4
 API Reference Manual

asReturn.RETURN_FROM_PROCESSING

If this is returned, any normal processing that can be scripted will be skipped.
Only some hooks that are based on the application object can have normal
processing that can be skipped.

Example:

If the following function was called at the end of OnCheckIn.rb in the

example above

return(pReturns.RETURN_FROM_PROCESSING);

Automation Studio™ would cancel what it would normally do during a closed file
event since the pReturns.RETURN_FROM_PROCESSING flag was supplied.

Famic Technologies Inc. 7-5

Automation Studio™ – API and Scripting Language

7.1.4 General Methods (Base)

The following functions are available to all objects in the system. This supplies common
functionality like navigation between objects, management of objects and control of
events.

int GetChildCount(int nChildType)

int GetNthChildId(int nNth, int nChildType)
int GetParentId()
int RegisterEvent(int nEventType,
int nProcessType,
int nMode,
string str)
int UnRegisterEvent(int nEventType)

The following sections will describe in detail how to use these methods.

7-6
 API Reference Manual

7.1.4.1 IDocumentApi CreateDocument ( string dN, string pN)

bool CreateDocument(int dType, string dN, string pN)

bool CreateDocument(int dType, string dN, string pN, string dTmpl, string pTmpl)

This method creates a document in the project using the names provided if the document
does not already exists in memory with the same name. If the document already exists,
it will be selected. If the project provided does not already exist in memory, it will be
created.

If the object is a project or has a parent as a project, it will be used if a project name is
not supplied.

Parameters:

dType Type of document to be created. The values available for dType

are defined in the structure AS::APIP::Share::DOCTYPE.

This structure can be accessed using the following metod.

DOCTYPE DTy =
applicationApi.GetDocTypes();
DTy.Standard
DTy.SFC
DTy.Report
DTy.Electrotechnical
DTy.ElectrotechTerminals
DTy.ElectrotechCables
DTy.ElectrotechReport
DTy.OneLine

dN The name of the document to be created or selected.

pN The name of the project to be created or selected. This parameter

is optional if the object that generated a call to this method is
related to, or is a, project.

dTmpl Document template to used.

Famic Technologies Inc. 7-7

Automation Studio™ – API and Scripting Language

pTmpl Project template to be used.

Returns:

IDocumentApi An interface to the new document object.

Ruby Example:
#------------------------------------------------------------
# Name of File::BaseCreateDocument.rb
#
# Purpose::
# This shows how to create a new document.
#------------------------------------------------------------
require "AS.API.Share"
pDocType = applicationApi.GetDocTypes();
doc = applicationApi.CreateDocument("D1","NewFile");
prj = applicationApi.GetCurrentProject();
doc.CreateDocument(pDocType.Report,"Rp1",prj.GetName(),"BOM");
return AS::API::Share::ASAPI_RETURNS.NORMAL_PROCESSING

7-8
 API Reference Manual

7.1.4.2 IProjectApi CreateProject ( string projectName)

This method creates a project using the name provided if a project does not already
exists in memory with the same name. If the project already exists the project will be
selected.

Parameters:

projectName The name of the project to be created or selected.

Returns:

IProjectApi An interface to the new project object.

Example:
#------------------------------------------------------------
# Name of File::BaseCreateProject.rb
#
# Purpose::
# This shows how to create a new project.
#------------------------------------------------------------
require "AS.API.Share"
prj = applicationApi.CreateProject("NewFile");
return AS::API::Share::ASAPI_RETURNS.NORMAL_PROCESSING

Famic Technologies Inc. 7-9

Automation Studio™ – API and Scripting Language

7.1.4.3 int GetChildCount(int iObjectType)

This fetches the number of children an object has of type defined by iObjectType. An
object may have a number of lists, so object type points the query to the correct list. i.e.
a document may have children of type AS.API.Share.ASAPI_OBJ.VIEW_API or
AS.API.Share.ASAPI_OBJ.COMPONENT_API. This field is ignored if the object only
has one object type.

Parameters:

iObjectType (Optional) Objects may contain more than one type of children,
so this parameter indicates what object list count to return.
This uses defines from the structure
AS.API.Share.ASAPI_OBJ and can be one of the
following.
APPLICATION_API
PROJECT_API
DOCUMENT_API
COMPONENT_API
VIEW_API
If a type is provided that the object does not support no
elements will be found. If this parameter is not supplied the
default object type will be used.

Returns:

int Number of objects of type requested.

Example:
#------------------------------------------------------------
# Name of File::GetChildCount.rb
#
# Purpose::
# This ruby script demonstrates fetching the number of
# children of an object.
#------------------------------------------------------------
require "AS.API.Share"

7-10
 API Reference Manual
iObjectType = AS::API::Share::ASAPI_OBJ.PROJECT_API
ProjectList = "There are currently [";
iCnt = applicationApi.GetChildCount(iObjectType);

ProjectList << iCnt.ToString();

ProjectList << "] projects loaded";
# Generally this will write a log to the temp directory
# if no logfile has been set by another process.
logType = AS::API::Share::LOGTYPE.FILELOG
applicationApi.LogInformation(logType, ProjectList, false,
false, 0);

return AS::API::Share::ASAPI_RETURNS.NORMAL_PROCESSING

Famic Technologies Inc. 7-11

Automation Studio™ – API and Scripting Language

7.1.4.4 object GetNthChild(int iNth, int iObjectType)

This fetches the iNth child object of type defined by iObjectType. An object may
have a number of children lists, so the object type points the query to the correct list. i.e.
a document may have children of type AS.API.Share.ASAPI_OBJ.VIEW_API or
AS.API.Share.ASAPI_OBJ.COMPONENT_API. This field is ignored if the object only has one
object type.

This allows a script writer to index through all children of a particular type of object
associated to the current object.

Parameters:

iNth The iNth child in the object list.

iObjectType Objects may contain more than one type of children, so this
parameter indicates what object list count to return. This uses
defines from the structure AS.API.Share.ASAPI_OBJ and
can be one of the following
APPLICATION_API
PROJECT_API
DOCUMENT_API
COMPONENT_API
VIEW_API

Returns:
IBaseApi The objects iNth iChildType child of type IBaseApi.

Warning:

The act of fetching a child from an object builds its API managers. In general the
first time a script or .NET module requires access to a specific object is when the
managers are created. This adds overhead which could lead to performance
problems if many primitive objects like components are accessed.

Example:

7-12
 API Reference Manual
#------------------------------------------------------------
# Name of File::BaseGetNthChild.rb
#
# Purpose::
# This ruby script demonstrates the GetNthChild() method.
#------------------------------------------------------------
require "AS.API.Share"

iObjectType = AS::API::Share::ASAPI_OBJ.PROJECT_API
iCnt = applicationApi.GetChildCount(iObjectType);
i = 0
ProjectList = "";

until i == iCnt
prj = applicationApi.GetNthChild(i, iObjectType);
strPrjName = prj.GetName();
ProjectList << "[";
ProjectList << strPrjName;
ProjectList << "] ";
i += 1
end

applicationApi.SetLogFile("");
# Generally this will write a log to the temp directory
# if no logfile has been set by another process.
logType = AS::API::Share::LOGTYPE.FILELOG
applicationApi.LogInformation(logType,ProjectList, false,
false , 0);

return AS::API::Share::ASAPI_RETURNS.NORMAL_PROCESSING

Famic Technologies Inc. 7-13

Automation Studio™ – API and Scripting Language

7.1.4.5 IDocumentApi GetDocumentApi(string docStr, string prjStr)

This method returns the related object’s document. A null document will be returned if
not enough information is supplied relative to the object. i.e. the application object must
include the project and the document names.

Parameters:
docStr The name of the document to get. Optional but must be
supplied if the project is supplied. If not supplied the objects
document will be returned.
prjStr The name of the required document’s project. Optional, If not
supplied the objects project will be used.

Returns:

IDocumentApi A related document object.

Example:
#------------------------------------------------------------
# Name of File::BaseGetDocumentApi.rb
#
# Purpose::
# This ruby script demonstrates different ways to access
# a document related to an object. It expects specific
# project, document, and views to have been loaded.
#------------------------------------------------------------
require "AS.API.Share"
logType = AS::API::Share::LOGTYPE.FILELOG

prj = applicationApi.GetProjectApi("P2");

if(prj)
doc = prj.GetDocumentApi("D1");
if(doc)
doc.Show();
else
# Generally this will write a log to the temp directory
# if no logfile has been set by another process.

7-14
 API Reference Manual
applicationApi.LogInformation(logType, "Document not
found (\"D1\")", false, false, 0);
end
end

doc = applicationApi.GetDocumentApi( "D2" , "P1" );

if(doc)
doc.Show();
else
# Generally this will write a log to the temp directory
# if no logfile has been set by another process.
applicationApi.LogInformation(logType, "Document not found
(\"D2\",\"P1\")", false, false , 0);
end

view = applicationApi.GetViewApi("View2","D2","P1");
if(view)
doc = view.GetDocumentApi();
if(doc)
doc.Show();
else
# Generally this will write a log to the temp directory
# if no logfile has been set by another process.
applicationApi.LogInformation(logType, "Parent of View
not found.", false, false , 0);
end
else
# Generally this will write a log to the temp directory
# if no logfile has been set by another process.
applicationApi.LogInformation(logType, "View not found
(\"View2\",\"D2\",\"P1\")", false, false, 0);
end

return AS::API::Share::ASAPI_RETURNS.NORMAL_PROCESSING

Famic Technologies Inc. 7-15

Automation Studio™ – API and Scripting Language

7.1.4.6 IBaseApi GetParent(int iType)

This method returns the object’s parent. The parent is returned in a generic structure that
is common to all objects within the API.

Parameters:

int Optional: When this parameter is not supplied the method will
return the first parent, i.e. a document will return a project, a
view will return a document etc.. Otherwise this parameter
will search through the parents until the parent of type iType
is found.
TID.APPLICATION_API
TID.PROJECT_API
TID.DOCUMENT_API
Null will be returned if no parent is found that meets the
requirements.

Returns:

IBaseApi The objects parent returned in a common structure.

Example:
#------------------------------------------------------------
# Name of File::BaseGetParentApi.rb
#
# Purpose::
# This ruby script demonstrates fetching a parent of the
# object.
#------------------------------------------------------------
require "AS.API.Share"

msg = "The parent [";

doc = applicationApi.GetDocumentApi("D1","P1");
if(doc)
prj = doc.GetParent();
if(prj)
msg << prj.GetName();

7-16
 API Reference Manual
end
end

msg << "] Is the project of the current document";

# Generally this will write a log to the temp directory

# if no logfile has been set by another process.
logType = AS::API::Share::LOGTYPE.FILELOG
applicationApi.LogInformation(logType, msg, false, false , 0);
return AS::API::Share::ASAPI_RETURNS.NORMAL_PROCESSING

Famic Technologies Inc. 7-17

Automation Studio™ – API and Scripting Language

7.1.4.7 IProjectApi GetProjectApi(string prjName)

This method returns the requested project. A null project will be returned if not enough
information is supplied relative to the object. i.e. The application object must include the
project name.

Parameters:

prjName The name of the project required.

Optional, If not supplied the project of the object will be
returned.

Returns:

IProjectApi The related project of the object.

Example:
#------------------------------------------------------------
# Name of File::BaseGetProjectApi.rb
#
# Purpose::
# This ruby script demonstrates different ways to access
# a view related to an object. It expects that a project
# with the names "P1" with a document D1 and view View2
# exist.
#------------------------------------------------------------
require "AS.API.Share"

prj = applicationApi.GetProjectApi("P1");
logType = AS::API::Share::LOGTYPE.FILELOG

msg = "The project ["

if(prj)
msg << prj.GetName();
msg << "] was found";

# Generally this will write a log to the temp directory

# if no logfile has been set by another process.
applicationApi.LogInformation(logType, msg, false, false,

7-18
 API Reference Manual
0);
end

view = applicationApi.GetViewApi("View2","D2","P1");
if(view)
prj = view.GetProjectApi();
msg = "The project ["
msg << prj.GetName();
msg << "] was found using the view";
# Generally this will write a log to the temp directory
# if no logfile has been set by another process.
applicationApi.LogInformation(logType, msg, false,false,
0);
end

return AS::API::Share::ASAPI_RETURNS.NORMAL_PROCESSING

Famic Technologies Inc. 7-19

Automation Studio™ – API and Scripting Language

7.1.4.8 IViewApi GetViewApi(string vN, string dN, string pN)

This method returns the requested view. A null view will be returned if not enough
information is supplied relative to the object. i.e. The project object must include the
view and the document name.

Parameters:

vN The name of the view required.

Optional, If not supplied the primary view will be returned.

dN The name of the document that contains the view.

Optional, If not supplied the objects document will be used.

pN The name of the required document’s project.

Optional, If not supplied the objects project will be used.

Returns:

IViewApi A related view of the object.

Example:
#------------------------------------------------------------
# Name of File::BaseGetViewApi.rb
#
# Purpose::
# This ruby script demonstrates different ways to access
# a view related to an object. It expects that projects
# with the names "P1" and "P2"; and the documents "D1" and
# D2; and the views "View2", exist in memory
#------------------------------------------------------------
require "AS.API.Share"

prj = applicationApi.GetProjectApi("P2");

if(prj)
view = prj.GetViewApi("View2","D2");
if(view)

7-20
 API Reference Manual
view.Show();
end
end

doc = applicationApi.GetDocumentApi("D1","P1");

if(doc)
view = doc.GetViewApi();
if(view)
view.Show();
end
end

view = applicationApi.GetViewApi("View3","D2","P2");
if(view)
view.Show();
end

return AS::API::Share::ASAPI_RETURNS.NORMAL_PROCESSING

Famic Technologies Inc. 7-21

Automation Studio™ – API and Scripting Language

7.1.4.9 bool LoadScript(string scriptName)

This method can be used to call a ruby script using Automation Studio™’s script search
paths from within a script. If the script has already run, nothing will happen. The method
RunScript() should be used when it is required to have the script run more than
once.

Point about the Ruby implementation of this method. This is not like the Ruby “load”
command. The ruby load command is run every time it is encountered. Also Ruby load
command will reload classes and models. The LoadScript() just re-interpretes and runs,
line by line, the script defined by scriptName. To get identical behavior to the load
command you will need to also review the Ruby keywords “module” and “include”.

Parameters:

scriptName The name of the script to load.

Returns:

bool True indicates the process was successful.

Example:
#------------------------------------------------------------
# Name of File::BaseLoadScript.rb
#
# Purpose:
# This ruby script demonstrates loading a script from a
# script.
# Warning:
# It is easy for a user to crash Automation Studio if a
# script loads itself.
#------------------------------------------------------------
require "AS.API.Share"
applicationApi.LoadScript("Base\\BaseGetParentApi.rb");
return AS::API::Share::ASAPI_RETURNS.NORMAL_PROCESSING

7-22
 API Reference Manual

7.1.4.10 void LogScriptInformation(string msg, bool blHdr)

If logging is enabled, this will write the information supplied to the either a file or the
Automation Studio™ message utility. A line will be written to the message utility using
the following format if they include header flag blHdr is set to false.

[SCRIPTING : ] <Script | C# Init call> <msg>

or, if the include header flag is set to true

[SCRIPTING : ] <Script | C# Init call> : <The Object> : The

Method <msg>

Where

[SCRIPTING : ] Only supplied if the output is the Automation Studio ™

message utility.

Script Scriptfile that called the method.

C# init call C# object and method that linked the client’s C#

module to Automation Studio™.

The Object The namespace and object that called the method.

The Method The method called that generated the line in the log.

msg The string supplied by the script/C# developer.

Famic Technologies Inc. 7-23

Automation Studio™ – API and Scripting Language

Parameters:

msg The string the script writer wishes to be logged.

blHdr Include header flag. This adds a number of fields to the line that is
written to the file or message utility.

Returns:

void Nothing is returned.

Example:
#------------------------------------------------------------
# Name of File::BaseLogScriptInformation.rb
#
# Purpose::
# This shows how to write messages to the log system.
#------------------------------------------------------------
require "AS.API.Share"
doc = applicationApi.GetDocumentApi( "D1" , "P1" );
if(doc)
doc.StartLogging(AS::API::Share::LOGTYPE.AS_MESSAGE_SYSTEM)
doc.LogScriptInformation("Message with header",true);
doc.LogScriptInformation("Message no header",false);
doc.StopLogging();
end

return AS::API::Share::ASAPI_RETURNS.NORMAL_PROCESSING

7-24
 API Reference Manual

7.1.4.11 int RegisterEvent(int iEvent, int iType, int iMode,string action)

This is used to assign user functionality to possible events that can occur. This registration
process can be called within any script, during initialization script (most common) or in
any script that handles events that have been hooked previously. Often the latter type of
registration is called on specific objects just after they have been created. In this case the
user would assign an initialization script to the creation of a particular type of object and
then when this script is called, assign a script to some event processed by the object.

Parameters:

iEvent The type of event that is to be hooked. The possible list of events
is dependent on the object that the event is tied to. This list can
be found with the object type later in this document.

iType This is the type of process (AS Scripting or .NET method) that will
service the event:

AS::API::Share::ASAPI_PROCESS_TYPE.CSHARP  Use a C#
interface.
AS::API::Share::ASAPI_PROCESS_TYPE.SCRIPT  Use Script
processing

iMode Future use, currently supports only syncrinous mode.

AS::API::Share::ASAPI_PROCESS_MODE.SYNC  Scripts are

launched within the process stream.

action Name of the method or script that will be launched.

Famic Technologies Inc. 7-25

Automation Studio™ – API and Scripting Language

Returns:

bool ‘true’ if the registration process worked.

Example: Create the following two scripts

#------------------------------------------------------------
# File::BaseRegisterEvent.rb
#
# Purpose::
# This shows how to register a script to an event.
#------------------------------------------------------------
require "AS.API.Share"

asEvent = AS::API::Share::ASAPI_EVENTS
asProcessType = AS::API::Share::ASAPI_PROCESS_TYPE
asMode = AS::API::Share::ASAPI_PROCESS_MODE

applicationApi.RegisterEvent(asEvent.OPEN_FILE,
asProcessType.SCRIPT,
asMode.SYNC,
"Base\\BaseRegisterEventTest.rb");

applicationApi.RegisterEvent(asEvent.CLOSE_FILE,
asProcessType.SCRIPT,
asMode.SYNC,
"Base\\BaseRegisterEventTest.rb");

applicationApi.RegisterEvent(asEvent.NEW_FILE,
asProcessType.SCRIPT,
asMode.SYNC,
"Base\\BaseRegisterEventTest.rb");

return AS::API::Share::ASAPI_RETURNS.NORMAL_PROCESSING

#------------------------------------------------------------

7-26
 API Reference Manual
# Name of File::BaseRegisterEventTest.rb
#
# Purpose::
# This just tests that an event has been registed.
#------------------------------------------------------------
require "AS.API.Share"
require 'System.Windows.Forms,
Version=2.0.0.0, Culture=neutral,
PublicKeyToken=b77a5c561934e089'

pRtnNormal = AS::API::Share::ASAPI_RETURNS.NORMAL_PROCESSING
pRtnAbnNrml =
AS::API::Share::ASAPI_RETURNS.RETURN_FROM_PROCESSING

MsgBox = System::Windows::Forms::MessageBox
MsgResultOK = System::Windows::Forms::DialogResult.OK
MsgBtns = System::Windows::Forms::MessageBoxButtons

msgboxRtn = MsgBox.Show( nil, "Should the process be

bypassed?", "Register Event Test", MsgBtns.OKCancel )

if (msgboxRtn == MsgResultOK)
pRtn = pRtnAbnNrml
else
pRtn = pRtnNormal
end

return pRtn

Famic Technologies Inc. 7-27

Automation Studio™ – API and Scripting Language

7.1.4.12 bool RunMethod(string methodString)

This method can be used to call a client method. This provides the developer a simple
interface to C# dynamic loading mechanism. A developer has to be careful of how
variables are handled for recursive calls to this method. Any functionality loaded should
have been register in the system cash.

Parameters:

methodString The name of the Iron Ruby method to run, see section 6.3.1
Method Syntax.

Returns:

bool True indicates the process was successful.

Example:
#------------------------------------------------------------
# Name of File::BaseRunMethod.rb
#
# Purpose:
# This ruby script demonstrates running a client
# method from a script.
# Warning:
# It is easy for a user to crash Automation Studio if a
# method loads itself.
#------------------------------------------------------------
require "AS.API.Share"
applicationApi.RunMethod("OnCheckIn");
return AS::API::Share::ASAPI_RETURNS.NORMAL_PROCESSING

7-28
 API Reference Manual

7.1.4.13 bool RunScript(string scriptName)

This method can be used to call a script using Automation Studio™’s script search paths
from within another script. This method works like any method call; every time it is
called the script will be run. The developer has to be careful of how variables are handled
for recursive calls to this method.

Parameters:

scriptName The name of the Iron Ruby script to run.

Returns:

bool True indicates the process was successful.

Example:
#------------------------------------------------------------
# Name of File::BaseRunScript.rb
#
# Purpose:
# This script demonstrates running a script from an
# script.
# Warning:
# It is easy for a user to crash Automation Studio if a
# script loads itself.
#------------------------------------------------------------
require "AS.API.Share"
applicationApi.RunScript("Base\\BaseGetParentApi.rb");
return AS::API::Share::ASAPI_RETURNS.NORMAL_PROCESSING

Famic Technologies Inc. 7-29

Automation Studio™ – API and Scripting Language

7.1.4.14 int StartLogging(LOGTYPE ifo, LOGTYPE wrn, LOGTYPE err)

After this call, every API called by a client generates a message in either a previously
specified file or the Automation Studio™ message utility.

Parameters:

LOGTYPE The.type of output to generate:

AS::API::Share::LOGTYPE.AS_MESSAGE_SYSTEM
This flag will redirect the scripting messages to the Automation
Studio™ messaging utility.

AS::API::Share::LOGTYPE.FILELOG
This will redirect the scripting messages to a previously
specified file.

AS::API::Share::LOGTYPE.NOLOG
This will turn off logging on the related type of message.

AS::API::Share::LOGTYPE.VERBOSE
A dialog providing the user with a choose to continue or end
processing the script.

ifo Type LOGTYPE, sets the type of logging that will be applied to
general system information.

wrn Type LOGTYPE, sets the type of logging that will be applied to
system warnings. Default is LOGTYPE.NOLOG

err Type LOGTYPE, sets the type of logging that will be applied to
scripting errors. Default is LOGTYPE.VERBOSE

7-30
 API Reference Manual

Returns:

void No return supplied.

Example:
#------------------------------------------------------------
# Name of File::BaseStartLogging.rb
#
# Purpose::
# This shows how turn on different logging systems.
#------------------------------------------------------------
require "AS.API.Share"
doc = applicationApi.GetDocumentApi( "D1" , "P1" );
if(doc)
doc.StartLogging(AS::API::Share::LOGTYPE.AS_MESSAGE_SYSTEM)
doc.ShowViews("view1");
doc.SetLogFile("scriptlog.log");
doc.StartLogging(AS::API::Share:: LOGTYPE.FILELOG)
doc.ShowViews("view1");
else
doc.LogScriptInformation("Document[P1:D1] Not found",true);
end
return AS::API::Share::ASAPI_RETURNS.NORMAL_PROCESSING

Famic Technologies Inc. 7-31

Automation Studio™ – API and Scripting Language

7.1.4.15 void SetLogDirectory( string directory)

This method determines where the log file will be saved if the script writer selects the
AS::API::Share::LOGTYPE.FILELOG mode. By default, if this method has not
been called script files will be placed in the directory defined by windows environment
variable %TEMP%. Typically this directory is located
C:\Users\<user>\AppData\Local\Temp

Parameters:

directory This designates the directory to be used to for the script

output.

Returns:

void Nothing is returned to the calling script or C# process.

Example:
#------------------------------------------------------------
# Name of File::BaseSetLogDirectory.rb
#
# Purpose::
# This shows how change the directory of the current
# scripting log file..
#------------------------------------------------------------
require "AS.API.Share"
applicationApi.SetLogFile("scriptlog.log");
applicationApi.SetLogDirectory("C:\\Demo")
applicationApi.StartLogging(AS::API::Share:: LOGTYPE.FILELOG);

doc = applicationApi.GetDocumentApi( "D1" , "P1" );

if(doc)
applicationApi.ShowViews("view3");
end
return AS::API::Share::ASAPI_RETURNS.NORMAL_PROCESSING

7-32
 API Reference Manual

7.1.4.16 int SetLogFile(String logfile)

This allows the user to set the name of the file to be used for all script messages.

Parameters:

logfile The name of the file to be used for the script message output.

Returns:

void No output is supplied to the calling process.

Example:
#------------------------------------------------------------
# Name of File::BaseSetLogFile.rb
#
# Purpose::
# This shows how to redirect the scripting messages to a
# log file found in the %TEMP% directory.
#------------------------------------------------------------
require "AS.API.Share"

doc = applicationApi.GetDocumentApi( "D1" , "P1" );

if(doc)
doc.SetLogFile("scriptlog.log");
doc.StartLogging(AS::API::Share::LOGTYPE.FILELOG)
doc.ShowViews("view3");
end

return AS::API::Share::ASAPI_RETURNS.NORMAL_PROCESSING

Famic Technologies Inc. 7-33

Automation Studio™ – API and Scripting Language

7.1.4.17 int StopLogging()

This turns off the script logging process.

Parameters:

NIL No parameters will be set.

Returns:

void Not return is provided to the calling process.

Example:

Notice that only the first show view is added to the message utility.
#------------------------------------------------------------
# Name of File::BaseStopLogging.rb
#
# Purpose::
# This shows how turn off the redirection of scripting
# messages.
#------------------------------------------------------------
require "AS.API.Share"
doc = applicationApi.GetDocumentApi( "D1" , "P1" );
if(doc)
doc.StartLogging(AS::API::Share::LOGTYPE.AS_MESSAGE_SYSTEM)
doc.ShowViews("view1");
doc.StopLogging()
doc.ShowViews("view1");
end
return AS::API::Share::ASAPI_RETURNS.NORMAL_PROCESSING

7-34
 API Reference Manual

7.1.4.18 int UnRegisterEvent(int iEventType)

This is used to remove an event that previously had been registered. After which the
user’s methods or scripts will not be called.

Parameters:

iEventType The type of event that had been registered. The possible list of
events is dependent on the object that the event is tied to. This
list can be with the object type later in this document.

Returns:

bool ‘true’ if successful.

Example: First implement the RegisterEvent example.

#-------------------------------------------------------------
# File::BaseUnRegisterEvent.rb
#
# Purpose::
# This shows how to remove a registered event.
#------------------------------------------------------------
require "AS.API.Share"
asEvent = AS::API::Share::ASAPI_EVENTS

applicationApi.UnRegisterEvent(asEvent.OPEN_FILE);
applicationApi.UnRegisterEvent(asEvent.NEW_FILE);
applicationApi.UnRegisterEvent(asEvent.CLOSE_FILE);

return AS::API::Share::ASAPI_RETURNS.NORMAL_PROCESSING

Famic Technologies Inc. 7-35

Automation Studio™ – API and Scripting Language

7.2 Node

Projects, Documents, and Components are nodes. These all share the same behavior.
This section provides how these objects can be accessed.

7.2.1 The Node Object

This object inherited by all node objects. This class is inherited by the following:

 IProjectApi;

 IDocumentApi;

 IComponentApi.

7.2.2 Supported Events/Hooks

asEvent = AS::API::Share::ASAPI_EVENTS

This table represents the list of points in AS’s process that a third-party developer can
hook into. This process entry points table relate to the application. The event column
indicates the attribute that will be supplied to the RegisterEvent() and
UnRegisterEvent() methods. The bypass processing column indicates whether or
not any code can be bypassed if the user indicates this should happen with the correct
return from his script.

Node dependent Events and Hooks

Event Bypass Available Description

Processing Parameters

To be filled in Yes/No String Are there any events for nodes.

FileName

7-36
 API Reference Manual

7.2.3 Methods

7.2.3.1 bool CreateVariable (string strName, int type, bool bDisplay,

string defName);

This method creates a variable on the node using the supplied name. A variable can be
created of any type that exists in the ASAPI_VARTYPES structure.

Parameters:

strName The name of the required variable.

type Type of object being provided. Can be one of the following:

AS Variable Type Data created.

ASAPI_VARTYPES
BOOL bool
BYTE sbyte
COLOR uint
CURRENCY decimal
DATE DateTime
DATE_AND_TIME DateTime
DECIMAL decimal
DINT int
DWORD uint
FILLING_PATTERN uint
HYPERLINK string
INT short
LINE_END uint
LINE_STYLE uint
LINE_THICKNESS uint
LINT long
LREAL double
LWORD ulong
REAL float
SINT sbyte
STRING string
TIME TimeSpan
TIME_OF_DAY DateTime
UDINT uint
UINT uint

Famic Technologies Inc. 7-37

Automation Studio™ – API and Scripting Language
ULINT ulong
USINT byte
WORD ushort
WSTRING string

bDisplay To or not to display the variable in the parameter dialog.

defName In the case of complex variables link ARRAY’s, ENUM’s, and

STRUCT’s this is the name of the definition to use. Not
required for the other types.

Returns:

bool This method will return true if the variable was successfully
created or already exists. In the second case a warning
message will be supplied to the message handler.

Example:
#------------------------------------------------------------
# Name of File::NodeCreateVariable.rb
#
# Purpose::
# Provides to the script writer a method to create
# variables. Check the properties of the component “H1”
# for the results.
#------------------------------------------------------------
require "AS.API.Share"
asVarType = AS::API::Share::ASAPI_VARTYPES;
asMsgType = AS::API::Share::LOGTYPE.AS_MESSAGE_SYSTEM

applicationApi.ChangeAllLogOutputs(asMsgType);
applicationApi.LogScriptInformation("Create variables.",false);
prj = applicationApi.GetCurrentProject();

cmp = prj.GetComponent("H1");
bCreated = cmp.CreateVariable( "MyVar" , asVarType.DOUBLE, true);
bCreated = cmp.CreateVariable( "MyVarA1" , asVarType.SINT, true);
bCreated = cmp.CreateVariable( "MyVarA2" , asVarType.INT, true);
bCreated = cmp.CreateVariable( "MyVarA3" , asVarType.DINT, true);
bCreated = cmp.CreateVariable( "MyVarA4" , asVarType.LINT, true);
bCreated = cmp.CreateVariable( "MyVarA5" , asVarType.USINT, true);
bCreated = cmp.CreateVariable( "MyVarA6" , asVarType.UINT, true);

7-38
 API Reference Manual
bCreated = cmp.CreateVariable( "MyVarA7" , asVarType.UDINT, true);
bCreated = cmp.CreateVariable( "MyVarA8" , asVarType.ULINT, true);
bCreated = cmp.CreateVariable( "MyVarA9" , asVarType.REAL, true);
bCreated = cmp.CreateVariable( "MyVarB10" , asVarType.LREAL, true);
bCreated = cmp.CreateVariable( "MyVarB11" , asVarType.TIME, true);
bCreated = cmp.CreateVariable( "MyVarB12" , asVarType.DATE, true);
bCreated = cmp.CreateVariable( "MyVarB13" , asVarType.TIME_OF_DAY,
true);
bCreated = cmp.CreateVariable( "MyVarB14" , asVarType.DATE_AND_TIME,
true);
bCreated = cmp.CreateVariable( "MyVarB15" , asVarType.STRING, true);
bCreated = cmp.CreateVariable( "MyVarB16" , asVarType.BYTE, true);
bCreated = cmp.CreateVariable( "MyVarB17" , asVarType.WORD, true);
bCreated = cmp.CreateVariable( "MyVarB18" , asVarType.DWORD, true);
bCreated = cmp.CreateVariable( "MyVarB19" , asVarType.LWORD, true);
bCreated = cmp.CreateVariable( "MyVarC20" , asVarType.WSTRING, true);
bCreated = cmp.CreateVariable( "MyVarC21" , asVarType.CURRENCY, true);
bCreated = cmp.CreateVariable( "MyVarC22" , asVarType.DECIMAL, true);
bCreated = cmp.CreateVariable( "MyVarC23" , asVarType.COLOR, true);
bCreated = cmp.CreateVariable( "MyVarC24" , asVarType.FILLING_PATTERN,
true);
bCreated = cmp.CreateVariable( "MyVarC25" , asVarType.LINE_THICKNESS,
true);
bCreated = cmp.CreateVariable( "MyVarC26" , asVarType.LINE_STYLE,
true);
bCreated = cmp.CreateVariable( "MyVarC27" , asVarType.LINE_END, true);
bCreated = cmp.CreateVariable( "MyVarC28" , asVarType.HYPERLINK, true);

applicationApi.LogScriptInformation(" ---------------------------
Complete .",false);

applicationApi.LogScriptInformation(strOut,false);
return AS::API::Share::ASAPI_RETURNS.NORMAL_PROCESSING

Famic Technologies Inc. 7-39

Automation Studio™ – API and Scripting Language

7.2.3.2 string CreateVariableDefinition (string strXML, bool bOkExists)

This method creates a definition in AS so that complex variable types can then be
created. Complex variables are of type ENUM, STRUCT, and ARRAY.

This will not create the definition if one with the same name already exists.

This does not support combinations of the above like arrays of structures or structures
that contain arrays.

Parameters:

bOkExists True indicates that if the definition name already exists to return that
name and log a message. False indicates to return null indicating that
method failed.

strXML An XML structure defineing the require variable. This XML structure
takes on one of the following forms.

General form of XML structure

"<?xml version=\"1.0\" encoding=\"utf-16\" ?>"
"<[TYPE] N=\"[myDef]\" TID=\"00000000-0000-0000-0000-
000000000000\ [datatype of array]"
xmlns=\"http://tempuri.org/XMLSchemaDefinition.xsd\" >"
[Line Definition]
"</[TYPE]>"

Where [TYPE] can be one of the following.

ST for structure
EN for enum
AR for array

Where [myDef] Is the name of the definition to be created. If the name already exists
it will not be created and a message will be logged.

Where [datatype of array] is the datatype used.

Only required for XML strings describing an array. This uses the syntax

7-40
 API Reference Manual

T=\"[datatype_id]\" where [datatye_id] equals the id of the datatype. This value

can be found in the structure ASAPI_VARTYPES. Example T=\"15\" indicates that the
data will be of type string.

Where [Line Definition] can be one or multiple lines in the code.

This is dependent on whether the XML describes an array, structure or enum element.

If it is an array (only one line)

"<d sz=\"[size]\" /d>";

Where [size] indicates the number of rows in the array.

If it is a structure (a line for each element in the structure)

"<f N=\"[element name]\" T=\"[datatype_id]\" />"
Where [element name] is the name of the variable within the structure and
[datatype_id] equals the id of the datatype. This value can be found in the
structure ASAPI_VARTYPES.

If it is an enum definition (a line for each value in the enum variable)

"<e N=\"[Enum value discription]\" v=\"[int value]\" />"

Where [Enum value discription] indicates the name given to the enum
element and [int value] indicates the value related to the name.

Returns:

string This method will return the name of the newly defined variable type.
The string supplied above in the [myDef] value is extracted and returned. If the
definition already exists null will be returned if the parameter bOkExists is set to false.

Example:
#------------------------------------------------------------
# Name of File::NodeCreateVariableDefinition.rb
#
# Purpose:: Create a complex variable types that then can be
# used within AS. The array type "TypeARRAY0"
# must exist in AS for this script to work fully.
#------------------------------------------------------------

Famic Technologies Inc. 7-41

Automation Studio™ – API and Scripting Language
require "System"
require "AS.API.Share"

#Simplify various global variables.

logType = AS::API::Share::LOGTYPE.AS_MESSAGE_SYSTEM;
varitypeSt = AS::API::Share::ASAPI_VARTYPES.STRUCT;
varitypeAr = AS::API::Share::ASAPI_VARTYPES.ARRAY;
varitypeEn = AS::API::Share::ASAPI_VARTYPES.ENUM;

#Get the component H1 within the current project to be changed.

applicationApi.ChangeAllLogOutputs(logType);
prj = applicationApi.GetCurrentProject();
cmp = prj.GetComponent( "H1" );

# ===== Define the structure to be used to create variables.======

strXML = "<?xml version=\"1.0\" encoding=\"utf-16\"?>"
strXML << "<ST xmlns=\"http://tempuri.org/XMLSchemaDefinition.xsd\"
N=\"structMyDef\" TID=\"00000000-0000-0000-0000-000000000000\">"
strXML << " <f N=\"Contact Name\" T=\"15\" />"
strXML << " <f N=\"Address 1\" T=\"15\" />"
strXML << " <f N=\"Address 2\" T=\"15\" />"
strXML << " <f N=\"Phone\" T=\"15\" />"
strXML << "</ST>";

defName = cmp.CreateVariableDefinition(strXML, true);

cmp.CreateVariable("MyStructVariable3", varitypeSt, true, defName);

iVarStruct = cmp.GetVariableObject("MyStructVariable3")
iVar2 = cmp.GetVariableObject(iVarStruct, "Contact Name");
cmp.SetVariableObjValue(iVar2, "Paul");
iVar2 = cmp.GetVariableObject(iVarStruct, "Address 1");
cmp.SetVariableObjValue(iVar2, "A Street");
iVar2 = cmp.GetVariableObject(iVarStruct, "Address 2");
cmp.SetVariableObjValue(iVar2, "Dorval");

strOs = System::Environment.OSVersion.ToString();
cmp.SetVariableObjValue(iVar2, strOs);
iVar2 = cmp.GetVariableObject(iVarStruct, "Phone");
cmp.SetVariableObjValue(iVar2, "555 420 0779");

valuePhone = cmp.GetVariableObjValue(iVar2);

# ===== Define the array to be used to create variables. ======

strXML = "<?xml version=\"1.0\" encoding=\"utf-16\"?>";
strXML << "<AR N=\"arrayMyDef\" TID=\"00000000-0000-0000-0000-

7-42
 API Reference Manual
000000000000\" T=\"15\" >";
strXML << "<d sz=\"5\" >";
strXML << "</d >";
strXML << "</AR>";

strDefName = cmp.CreateVariableDefinition(strXML, true);

cmp.CreateVariable("MyArrayVariable3", varitypeAr, true, strDefName);
iVar = cmp.GetVariableObject("MyArrayVariable3");
iVar2 = cmp.GetVariableObject(iVar, 3);
cmp.SetVariableObjValue(iVar2, "Test string");
strTestString = cmp.GetVariableObjValue(iVar2);

# === Create an array of structures....

# == The definition TypeARRAY0 has to have been created in AS
cmp.CreateVariable("MyArStrVar1", varitypeAr, true, "TypeARRAY0");
iVar = cmp.GetVariableObject("MyArStrVar1");

i = 0
while (i < 4)
iVar2 = cmp.GetVariableObject(iVar, i);
iVar3 = cmp.GetVariableObject(iVar2, "Var1");
cmp.SetVariableObjValue(iVar3, 1);
iVar3 = cmp.GetVariableObject(iVar2, "Var2");
cmp.SetVariableObjValue(iVar3, 2);
iVar3 = cmp.GetVariableObject(iVar2, "Var3");
cmp.SetVariableObjValue(iVar3, "Paul");
i += 1
end

applicationApi.LogInformation(logType, "-------", true,false,0);

# ================= Create an enum structure ...

strXML = "<?xml version=\"1.0\" encoding=\"utf-16\" ?>";
strXML << "<EN N=\"enumMyDef\" TID=\"00000000-0000-0000-0000-
000000000000\" xmlns=\"http://tempuri.org/XMLSchemaDefinition.xsd\" >"
strXML << "<e N=\"200h\" v=\"0\" />";
strXML << "<e N=\"240h\" v=\"1\" />";
strXML << "<e N=\"280h\" v=\"2\" />";
strXML << "<e N=\"2C0h\" v=\"3\" />";
strXML << "</EN>";

strDefName = cmp.CreateVariableDefinition(strXML, true);

cmp.CreateVariable("MyEnumVariable3", varitypeEn, true, strDefName);
cmp.SetVariableValue("MyEnumVariable3", 1);
iValue = cmp.GetVariableValue("MyEnumVariable3");

Famic Technologies Inc. 7-43

Automation Studio™ – API and Scripting Language

return AS::API::Share::ASAPI_RETURNS.NORMAL_PROCESSING

7-44
 API Reference Manual

7.2.3.3 bool DeleteVariable (string strName);

This method deletes a variable specified.

Parameters:

strName The name of the required variable.

Returns:

bool This method will return true if the variable was successfully
deleted.

Example:
#------------------------------------------------------------
# Name of File::NodeDeleteVariable.rb
#
# Purpose::
# Provides to the script writer a method to delete a
# variables.
#------------------------------------------------------------
require "AS.API.Share"
applicationApi.StartLogging(AS::API::Share::LOGTYPE.AS_MESSAGE_SYSTEM,
AS::API::Share::LOGTYPE.AS_MESSAGE_SYSTEM,
AS::API::Share::LOGTYPE.AS_MESSAGE_SYSTEM,
AS::API::Share::LOGTYPE.AS_MESSAGE_SYSTEM);
prj = applicationApi.GetCurrentProject();
if(prj)
cmp = prj.GetComponent("H1");
if(cmp)
cmp.DeleteVariable( "MyVar");
end
end
return AS::API::Share::ASAPI_RETURNS.NORMAL_PROCESSING

Famic Technologies Inc. 7-45

Automation Studio™ – API and Scripting Language

7.2.3.4 string GetName();

This method fetches the name of the current node. Projects return project name,
documents use document name, components return instance name, and views return
view names.

Parameters:

NIL No parameters will be set.

Returns:

string String containing the nodes name.

Example:

#------------------------------------------------------------
# Name of File::NodeGetName.rb
#
# Purpose::
# This shows how to use the Node GetName() method.
#------------------------------------------------------------
require "AS.API.Share"
strPrjName = "Name of Project : ";
prj = applicationApi.GetProjectApi( "P1" );
if(prj)
strPrjName += prj.GetName();
end
applicationApi..LogScriptInformation(strPrjName,false);
return AS::API::Share::ASAPI_RETURNS.NORMAL_PROCESSING

7-46
 API Reference Manual

7.2.3.5 object GetVariableObject(object varObj, int iCol);

object GetVariableObject(object varObj, string strCellName);

When you have a structure, or array variable these two methods provide access to their
members.

This returns a derefrenced access to the variable object within AS. No interface is directly
provided by these methods. The return value must be used in one of the following
methods to access or change the actual variable objects.

Used to access the actual value contained by the variable object returned above.

object GetVariableObjValue(object var);

These two set the value to the variable object returned above.

void SetVariableObject(object var, string field, object

value);

void SetVariableObject(object var, int index, object value);

Parameters:

varObj The complex variable that contains the required element.

strCellName If the complex variable is a structure this provides access to the

internal element.

iCol If the complex variable is an array this provides access to the

element in the array.

Famic Technologies Inc. 7-47

Automation Studio™ – API and Scripting Language

Returns:

object This method will return “nil” if an error fetching the object
occurred.

Related Methods:

bool CreateVariable(string vName, int type, bool bLst, string def);

string CreateVariableDefinition(string xmlDef, bool exists
object GetVariableObjValue(object var);
bool SetVariableObjValue(object var, object value);
bool SetVariableObjValue(object var, int id, object value);
bool SetVariableObjValue(object var, string field, object value);
bool VariableDefinitionExists(string defName);

Example:
#------------------------------------------------------------
# Name of File::NodeGetVariableObject.rb
#
# Purpose:: Get and set the elements to a complex array of
# structures. This expects that the variable
# "MyArStrVar1" had been created using the script
# NodeCreateVariableDefinition.rb.
#------------------------------------------------------------
require "System"
require "AS.API.Share"

#Simplify various global variables.

logType = AS::API::Share::LOGTYPE.AS_MESSAGE_SYSTEM;

#Get the component H1 within the current project to be changed.

applicationApi.ChangeAllLogOutputs(logType);
prj = applicationApi.GetCurrentProject();
cmp = prj.GetComponent( "H1" );

# ===== Define the array to be used to create variables. ======

# == Get the array of structures variable called "MyArStrVar1"

iVar = cmp.GetVariableObject("MyArStrVar1");

i = 0
while (i < 4)
iVar2 = cmp.GetVariableObject(iVar, i);

7-48
 API Reference Manual
iVar3 = cmp.GetVariableObject(iVar2, "Var1");
cmp.SetVariableObjValue(iVar3, 5);
iVar3 = cmp.GetVariableObject(iVar2, "Var2");
cmp.SetVariableObjValue(iVar3, 6);
iVar3 = cmp.GetVariableObject(iVar2, "Var3");
cmp.SetVariableObjValue(iVar3, "Change the string");
i += 1
end

applicationApi.LogInformation(logType, "-------", true, false, 0);

return AS::API::Share::ASAPI_RETURNS.NORMAL_PROCESSING

Famic Technologies Inc. 7-49

Automation Studio™ – API and Scripting Language

7.2.3.6 object GetVariableObjValue(object varObj);

When you have access to the variable object this gets its value.

The following methods are used to access the variable object required for parameter one.

object GetVariableObject(string var);

object GetVariableObject(object var, string field);

object GetVariableObject(object var, int index);

Parameters:

varObj The variable to extract the value from.

Returns:

object This method will return “nil” if an error fetching the object
occurred, otherwise it will return the value that exists within
the variable. This can be anyone of the following data
elements.

AS Variable Type Data created.

ASAPI_VARTYPES
BOOL bool
BYTE sbyte
COLOR uint
CURRENCY decimal
DATE DateTime
DATE_AND_TIME DateTime
DECIMAL decimal
DINT int
DWORD uint
FILLING_PATTERN uint
HYPERLINK string
INT short
LINE_END uint

7-50
 API Reference Manual
LINE_STYLE uint
LINE_THICKNESS uint
LINT long
LREAL double
LWORD ulong
REAL float
SINT sbyte
STRING string
TIME TimeSpan
TIME_OF_DAY DateTime
UDINT uint
UINT uint
ULINT ulong
USINT byte
WORD ushort
WSTRING string

Related Methods:

bool CreateVariable(string vName, int type, bool bLst, string def);

string CreateVariableDefinition(string xmlDef, bool exists);
object GetVariableObject(string name);
bool SetVariableObjValue(object var, object value);
bool SetVariableObjValue(object var, int id, object value);
bool SetVariableObjValue(object var, string field, object value);
bool VariableDefinitionExists(string defName);

Example:
#------------------------------------------------------------
# Name of File::NodeGetVariableObjValue.rb
#
# Purpose:: Extract the value from a variable object that
# exists within a complex variable. The variable
# "MyArStrVar1". Thos would have been created
# running the example
# NodeCreateVariableDefinition.rb
#------------------------------------------------------------
require "System"
require "AS.API.Share"

#Simplify various global variables.

logType = AS::API::Share::LOGTYPE.AS_MESSAGE_SYSTEM;

#Get the component H1 within the current project to be changed.

Famic Technologies Inc. 7-51

Automation Studio™ – API and Scripting Language
applicationApi.ChangeAllLogOutputs(logType);
prj = applicationApi.GetCurrentProject();

# Get the component ...

cmp = prj.GetComponent( "H1" );
# Get the variable array "MyArStrVar1" from the component.
iVar = cmp.GetVariableObject("MyArStrVar1");
# Get the second element (a structure) in the array found
iVar2 = cmp.GetVariableObject(iVar, 1);
# Get the variable of the field "Var2" from the structure found.
iVar3 = cmp.GetVariableObject(iVar2, "Var2");
# Get the actual value from the field.
vValue = cmp.GetVariableObjValue(iVar3);

return AS::API::Share::ASAPI_RETURNS.NORMAL_PROCESSING

7-52
 API Reference Manual

7.2.3.7 object GetVariableValue(string strName);

Original Syntax: object GetVariableValue(string strName, int type);

This method fetches the variable object with using the variable’s name. This will return
the a copy of the data controlled by the variable. If the type is not provided, the return
type will be of the same type stored in the system.

The original syntax required the script writer to provide the type of data that should be
returned by the method.

Parameters:

strName The name of the required variable.

type If not provided the variable will be returned as their native
type.
Type of object to return. The variable type will be conveted to
the type indicated by this parameter. Can be one of the
following if the type can support it:
ASAPI_VARTYPES
STRING
DOUBLE
FLOAT
INT
BOOL
Not supported complex variable types link FONT, ENUM,
ARRAY, and STRUCT.
TimeSpan and DateTime variables are converted to ticks (long).

Returns:

object This method will return “nil” if the object does not exist or the
script writer used the wrong type, otherwise it will return the
object of the variable asked for. It may be one of the
following objects.

AS Variable Type Data return type

Famic Technologies Inc. 7-53

Automation Studio™ – API and Scripting Language
BOOL bool
BYTE sbyte
COLOR uint
CURRENCY decimal
DATE DateTime
DATE_AND_TIME DateTime
DECIMAL decimal
DINT int
DWORD uint
FILLING_PATTERN uint
HYPERLINK string
INT short
LINE_END uint
LINE_STYLE uint
LINE_THICKNESS uint
LINT long
LREAL double
LWORD ulong
REAL float
SINT sbyte
STRING string
TIME TimeSpan
TIME_OF_DAY DateTime
UDINT uint
UINT uint
ULINT ulong
USINT byte
WORD ushort
WSTRING string

Example:
#------------------------------------------------------------
# Name of File::NodeGetVariableValue.rb
#
# Purpose::
# This provides an example of the get variable method.
# This expects that all variables have been created by
# NodeCreateVariable.rb and set by NodeSetVariableValue.rb
# The output has been redirected to the message system
# for validation.
#------------------------------------------------------------
require "AS.API.Share"
asVarType = AS::API::Share::ASAPI_VARTYPES
asMsgType = AS::API::Share::LOGTYPE.AS_MESSAGE_SYSTEM;

7-54
 API Reference Manual
strOut = "Validate the output string includes the current values of
variables\n"
strOut << "MyVarA1 ... MyVarC28 \n"

applicationApi.ChangeAllLogOutputs(asMsgType);

cmp = prj.GetComponent("H1");
applicationApi.LogScriptInformation("=== Original Syntax ===",false);
dValue = cmp.GetVariableValue( "MyVarA0" , asVarType.BOOL);
dValue = cmp.GetVariableValue( "MyVarA1" , asVarType.SINT);
dValue = cmp.GetVariableValue( "MyVarA2" , asVarType.INT);
dValue = cmp.GetVariableValue( "MyVarA3" , asVarType.DINT);
dValue = cmp.GetVariableValue( "MyVarA4" , asVarType.LINT);
dValue = cmp.GetVariableValue( "MyVarA5" , asVarType.USINT);
dValue = cmp.GetVariableValue( "MyVarA6" , asVarType.UINT);
dValue = cmp.GetVariableValue( "MyVarA7" , asVarType.UDINT);
dValue = cmp.GetVariableValue( "MyVarA8" , asVarType.ULINT);
dValue = cmp.GetVariableValue( "MyVarA9" , asVarType.REAL);
dValue = cmp.GetVariableValue( "MyVarB10" , asVarType.DOUBLE);
dValue = cmp.GetVariableValue( "MyVarB11" , asVarType.INT);
dValue = cmp.GetVariableValue( "MyVarB12" , asVarType.INT);
dValue = cmp.GetVariableValue( "MyVarB13" , asVarType.INT);
dValue = cmp.GetVariableValue( "MyVarB14" , asVarType.INT);
dValue = cmp.GetVariableValue( "MyVarB15" , asVarType.STRING);
dValue = cmp.GetVariableValue( "MyVarB16" , asVarType.INT);
dValue = cmp.GetVariableValue( "MyVarB17" , asVarType.INT);
dValue = cmp.GetVariableValue( "MyVarB18" , asVarType.INT);
dValue = cmp.GetVariableValue( "MyVarB19" , asVarType.INT);
dValue = cmp.GetVariableValue( "MyVarC20" , asVarType.STRING);
dValue = cmp.GetVariableValue( "MyVarC21" , asVarType.FLOAT);
dValue = cmp.GetVariableValue( "MyVarC22" , asVarType.FLOAT);
dValue = cmp.GetVariableValue( "MyVarC23" , asVarType.INT);
dValue = cmp.GetVariableValue( "MyVarC24" , asVarType.INT);
dValue = cmp.GetVariableValue( "MyVarC25" , asVarType.INT);
dValue = cmp.GetVariableValue( "MyVarC26" , asVarType.INT);
dValue = cmp.GetVariableValue( "MyVarC27" , asVarType.INT);
dValue = cmp.GetVariableValue( "MyVarC28" , asVarType.STRING);

applicationApi.LogScriptInformation("==== New Syntax =======",false);

dValue = cmp.GetVariableValue( "MyVarA0" );
dValue = cmp.GetVariableValue( "MyVarA1" );
dValue = cmp.GetVariableValue( "MyVarA2" );
dValue = cmp.GetVariableValue( "MyVarA3" );
dValue = cmp.GetVariableValue( "MyVarA4" );
dValue = cmp.GetVariableValue( "MyVarA5");

Famic Technologies Inc. 7-55

Automation Studio™ – API and Scripting Language
dValue = cmp.GetVariableValue( "MyVarA6" );
dValue = cmp.GetVariableValue( "MyVarA7" );
dValue = cmp.GetVariableValue( "MyVarA8");
dValue = cmp.GetVariableValue( "MyVarA9" );
dValue = cmp.GetVariableValue( "MyVarB10" );
dValue = cmp.GetVariableValue( "MyVarB11" );
dValue = cmp.GetVariableValue( "MyVarB12" );
dValue = cmp.GetVariableValue( "MyVarB13" );
dValue = cmp.GetVariableValue( "MyVarB14" );
dValue = cmp.GetVariableValue( "MyVarB15");
dValue = cmp.GetVariableValue( "MyVarB16" );
dValue = cmp.GetVariableValue( "MyVarB17" );
dValue = cmp.GetVariableValue( "MyVarB18" );
dValue = cmp.GetVariableValue( "MyVarB19" );
dValue = cmp.GetVariableValue( "MyVarC20" );
dValue = cmp.GetVariableValue( "MyVarC21");
dValue = cmp.GetVariableValue( "MyVarC22" );
dValue = cmp.GetVariableValue( "MyVarC23" );
dValue = cmp.GetVariableValue( "MyVarC24" );
dValue = cmp.GetVariableValue( "MyVarC25" );
dValue = cmp.GetVariableValue( "MyVarC26" );
dValue = cmp.GetVariableValue( "MyVarC27" );
dValue = cmp.GetVariableValue( "MyVarC28" );

applicationApi.LogScriptInformation(" ----- Complete .",false);

return AS::API::Share::ASAPI_RETURNS.NORMAL_PROCESSING

7-56
 API Reference Manual

7.2.3.8 bool SetVariableObjValue(object varObj, object varValue);

bool SetVariableObjValue(object varParent, int idx, object varValue)

bool SetVariableObjValue(object varParent, string attName, object varValue)

When you have access to the variable object or its parent these provide methods to
change their values.

The following methods are used to access the variable object required for parameter one.

object GetVariableObject(string var);

object GetVariableObject(object var, string field);

object GetVariableObject(object var, int index);

Parameters:

varObj The variable to extract the value from.

varParent The parent of the variable to extract the value from.

varValue The value to set. This value must be of a type that can be
converted to the actual variable on the object. An example
which would fail would be if you provided a long value to be
set on a boolean variable.

Returns:

object This method will return “nil” if an error fetching the object
occurred, otherwise it will return the value that exists within
the variable. This can be anyone of the following data
elements.

AS Variable Type Data created.

Famic Technologies Inc. 7-57

Automation Studio™ – API and Scripting Language
ASAPI_VARTYPES
BOOL bool
BYTE sbyte
COLOR uint
CURRENCY decimal
DATE DateTime
DATE_AND_TIME DateTime
DECIMAL decimal
DINT int
DWORD uint
FILLING_PATTERN uint
HYPERLINK string
INT short
LINE_END uint
LINE_STYLE uint
LINE_THICKNESS uint
LINT long
LREAL double
LWORD ulong
REAL float
SINT sbyte
STRING string
TIME TimeSpan
TIME_OF_DAY DateTime
UDINT uint
UINT uint
ULINT ulong
USINT byte
WORD ushort

WSTRING string

Related Methods:

bool CreateVariable(string vName, int type, bool bLst,

string def);

string CreateVariableDefinition(string xmlDef, bool exists);

object GetVariableObject(string name);

Example:
#------------------------------------------------------------

7-58
 API Reference Manual
# Name of File::NodeSetVariableObjValue.rb
#
# Purpose:: Set the value to a variable within an array and
# structure. The variables "MyStructVariable3 and
# "MyArrayVariable3" are expected to exist. They
# can be created while running the example
# NodeCreateVariableDefinition.rb
#------------------------------------------------------------
require "System"
require "AS.API.Share"

#Simplify various global variables.

logType = AS::API::Share::LOGTYPE.AS_MESSAGE_SYSTEM;

#Get the component H1 within the current project to be changed.

applicationApi.ChangeAllLogOutputs(logType);
prj = applicationApi.GetCurrentProject();
cmp = prj.GetComponent( "H1" );

# ---------------- "MyStructVariable3" ---------------------

# Get the existing structure variable from component H1

iVarStruct = cmp.GetVariableObject("MyStructVariable3")

# Set the field "Address 1" using the variable from within
# structure.
iVar2 = cmp.GetVariableObject(iVarStruct, "Address 1");
cmp.SetVariableObjValue(iVar2, "Ted");

# Set the "Contact Name" directly

cmp.SetVariableObjValue(iVarStruct, "Contact Name", "Tom");

# --------------- "MyArrayVariable3" ---------------------

# Get the existing array variable from component H1

iVar = cmp.GetVariableObject("MyArrayVariable3");
# Set the third element directly in the array.
cmp.SetVariableObjValue(iVar, 3, "Next string 3");

return AS::API::Share::ASAPI_RETURNS.NORMAL_PROCESSING

Famic Technologies Inc. 7-59

Automation Studio™ – API and Scripting Language

7.2.3.9 bool SetVariableValue(string strName, object value);

This method set the object with the name equal to the name provided in the strName
variable with the supplied value. See CreateVariableValue() and GetVariableValue() for
more information on manipulating variable values.

Parameters:

strName The name of the required variable to set

value The value to be used to set the variable. This value has to be
of a type that can be convertibled to the of target variable. As
an example a “long” based value cannot be set to an “short”
based object.

Returns:

bool Will return false if the variable does not exist or could not be
set.

Example:
#------------------------------------------------------------
# Name of File::NodeSetVariableValue.rb
#
# Purpose::
# Provides to the script writer a method to set variables.
# This expects that all the variables have been created
# using NodeCreateVariable.rb
#------------------------------------------------------------
require "AS.API.Share"
asVarType = AS::API::Share::ASAPI_VARTYPES
asMsgType = AS::API::Share::LOGTYPE.AS_MESSAGE_SYSTEM
strOut = "Not found"

applicationApi.ChangeAllLogOutputs(asMsgType);

prj = applicationApi.GetCurrentProject();
if(prj)
cmp = prj.GetComponent("H1");

7-60
 API Reference Manual
if(cmp)
cmp.SetVariableValue( "MyVar" , 32.0);
cmp.SetVariableValue( "MyVarA1" , -33);
cmp.SetVariableValue( "MyVarA2" , -34);
cmp.SetVariableValue( "MyVarA3" , -35);
cmp.SetVariableValue( "MyVarA4" , -36);
cmp.SetVariableValue( "MyVarA5" , 37);
cmp.SetVariableValue( "MyVarA6" , 38);
cmp.SetVariableValue( "MyVarA7" , 39);
cmp.SetVariableValue( "MyVarA8" , 40);
cmp.SetVariableValue( "MyVarA9" , 41.1);
cmp.SetVariableValue( "MyVarB10" , 42.2);
cmp.SetVariableValue( "MyVarB11" , 55);
cmp.SetVariableValue( "MyVarB12" , 55);
cmp.SetVariableValue( "MyVarB13" , 55);
cmp.SetVariableValue( "MyVarB14" , 55);
cmp.SetVariableValue( "MyVarB15" , "Test String");
cmp.SetVariableValue( "MyVarB16" , 0x1A);
cmp.SetVariableValue( "MyVarB17" , 0x1B1B);
cmp.SetVariableValue( "MyVarB18" , 0x1C1C1C1C);
cmp.SetVariableValue( "MyVarB19" , 0x1D1D1D1D);
cmp.SetVariableValue( "MyVarC20" , "Test String 2");
cmp.SetVariableValue( "MyVarC21" , 44.6);
cmp.SetVariableValue( "MyVarC22" , 44.7);
cmp.SetVariableValue( "MyVarC23" , 255);
cmp.SetVariableValue( "MyVarC24" , 5);
cmp.SetVariableValue( "MyVarC25" , 5);
cmp.SetVariableValue( "MyVarC26" , 5);
cmp.SetVariableValue( "MyVarC27" , 5);
cmp.SetVariableValue( "MyVarC28" , "www.simply4.ca");
end
end
return AS::API::Share::ASAPI_RETURNS.NORMAL_PROCESSING

Famic Technologies Inc. 7-61

Automation Studio™ – API and Scripting Language

7.2.3.10 bool Show(SHOW_TYPE showType = SHOW_TYPE.SHOW);

This method sets the visibility of the object. Dependent on the object this method will
force the visibility of the object when closed.

Parameters:
showType Type of show that will be applied.
Default value is SHOW_TYPE.SHOW.

True  Shows the object

false Hides the object
SHOW_TYPE.HIDE  Hides the object
SHOW_TYPE.SHOW Shows the object
SHOW_TYPE.HIDE_ALL Hides all objects contained
SHOW_TYPE.SHOW_ALL Calls a show on all views
SHOW_TYPE.MAXIMIZE Maximizes the primary view
SHOW_TYPE.MINIMIZE Minimizes all views
SHOW_TYPE.NORMAL Resets the views to their original
size

Returns:

bool Returns false if the method failed to set the visibility.

Example:
#------------------------------------------------------------
# Name of File::NodeShow.rb
#
# Purpose::
# Shows how a script writer can force visibility on an
# object.
#------------------------------------------------------------
require "AS.API.Share"

prj = applicationApi.GetProjectApi( "P1" );

if(prj)

7-62
 API Reference Manual
cmp = prj.GetComponent( "REC1" );
if(cmp)
cmp.Show(false);
end
end

return AS::API::Share::ASAPI_RETURNS.NORMAL_PROCESSING

Famic Technologies Inc. 7-63

Automation Studio™ – API and Scripting Language

7.3 Variable

This section defines how to add, delete or modify variables on Components, Documents
or Projects.

7.3.1 The Variable Object

Any node may have a number of attributes that affect behavior. These attributes can be
accessed through a variable object. The variable object supplies a standard set of
methods that can be used to modify these attributes.

7.3.2 Supported Events/Hooks

asEvent = AS::API::Share::ASAPI_EVENTS

This table represents the list of points in AS’s process that a third-party developer can
hook into. This process entry points table relate to the application. The event column
indicates the attribute that will be supplied to the RegisterEvent() and
UnRegisterEvent() methods. The bypass processing column indicates whether or
not any code can be bypassed if the user indicates this should happen with the correct
return from his script.

Node dependent Events and Hooks

Event Bypass Available Description

Processing Parameters

To be filled in Yes/No String Are there any events for nodes.

FileName

7-64
 API Reference Manual

7.3.3 Methods

Methods available on the IVariable object.

7.3.3.1 bool ActivateComponentLink(bool toShow);

This method sets the component link attribute on the variable to on or off.

Parameters:

toShow True indicates to show the alias of the variable if the variable is
visible.

Returns:

bool “True” indicates success.

Example:
#------------------------------------------------------------
# Name of File::VarActivateComponentLink.rb
#
# Purpose::
# Turns on/off component linking for the component
#------------------------------------------------------------
require "AS.API.Share"

prj = applicationApi.GetProjectApi( "P1" );

if(prj)
cmp = prj.GetComponent( "REC1" );

if(cmp)
var = cmp.GetVariable("#VcLayer");

if(var)
var.ActivateComponentLink(true);
end
end
end
applicationApi.Refresh();

Famic Technologies Inc. 7-65

Automation Studio™ – API and Scripting Language
return AS::API::Share::ASAPI_RETURNS.NORMAL_PROCESSING

7-66
 API Reference Manual

7.3.3.2 bool ActivateTooltip(bool setActive);

This activates a tooltip related to the component. When a pointer device is placed over
the component the tooltip object will become visible if this attribute of the variable has
been set.

Parameters:

setActive True turns on tool tips for this component. For this to work the
Tooltip attribute on the view ribbon bar also has to be
activated.

Returns:

bool “True” indicates success.

Example:
#------------------------------------------------------------
# Name of File::VarActivateTooltip.rb
#
# Purpose::
# Turns on/off tooltip support for the component.
#------------------------------------------------------------
require "AS.API.Share"
prj = applicationApi.GetProjectApi( "P1" );
if(prj)
cmp = prj.GetComponent( "REC1" );

if(cmp)
var = cmp.GetVariable("#VcLayer");

if(var)
var.ActivateTooltip(true);
end
end
end
applicationApi.Refresh();
return AS::API::Share::ASAPI_RETURNS.NORMAL_PROCESSING

Famic Technologies Inc. 7-67

Automation Studio™ – API and Scripting Language

7.3.3.3 string GetAlias();

This method returns the alias of the variable.

Parameters:

NIL No parameters will be set.

Returns:

string The alias of the required variable.

Example:
#------------------------------------------------------------
# Name of File::VarGetAlias.rb
#
# Purpose::
# Returns the alias of the variable.
#------------------------------------------------------------
require "AS.API.Share"
prj = applicationApi.GetProjectApi( "P1" );
n = "";
if (prj)
cmp = prj.GetComponent( "REC1" );

if(cmp)
var = cmp.GetVariable("#VcLayer");

if(var)
n = var.GetAlias();
end
end
end
applicationApi.LogScriptInformation("[" + n + "]",false);
applicationApi.Refresh();
return AS::API::Share::ASAPI_RETURNS.NORMAL_PROCESSING

7-68
 API Reference Manual

7.3.3.4 string GetDescription();

This method returns the description set to the variable.

Parameters:

NIL No parameters will be set.

Returns:

string The description currently set to the component variable.

Example:
#------------------------------------------------------------
# Name of File::VarGetDescription.rb
#
# Purpose::
# Returns the description of the variable.
#------------------------------------------------------------
require "AS.API.Share"
prj = applicationApi.GetProjectApi( "P1" );
n = "";
if (prj)
cmp = prj.GetComponent( "REC1" );

if(cmp)
var = cmp.GetVariable( "#VcLayer" );

if(var)
n = var.GetDescription();
end
end
end
applicationApi.LogScriptInformation("[" + n + "]",false);
applicationApi.Refresh();
return AS::API::Share::ASAPI_RETURNS.NORMAL_PROCESSING

Famic Technologies Inc. 7-69

Automation Studio™ – API and Scripting Language

7.3.3.5 string GetInternalName();

This method returns the internal name of the variable.

Parameters:

NIL No parameters will be set.

Returns:

string The internal name of the required variable.

Example:
#------------------------------------------------------------
# Name of File::VarGetInternalName.rb
#
# Purpose::
# Returns the internal name of the variable.
#------------------------------------------------------------
require "AS.API.Share"
prj = applicationApi.GetProjectApi( "P1" );
n = "";
if (prj)
cmp = prj.GetComponent( "REC1" );

if(cmp)
var = cmp.GetVariable( "#VcLayer" );

if(var)
n = var.GetInternalName();
end
end
end
applicationApi.LogScriptInformation("[" + n + "]",false);
applicationApi.Refresh();
return AS::API::Share::ASAPI_RETURNS.NORMAL_PROCESSING

7-70
 API Reference Manual

7.3.3.6 string GetName();

This method returns the name of the variable.

Parameters:

NIL No parameters will be set.

Returns:

string The internal name of the required variable.

Example:
#------------------------------------------------------------
# Name of File::VarGetName.rb
#
# Purpose::
# Returns the name of the variable.
#------------------------------------------------------------
require "AS.API.Share"

prj = applicationApi.GetProjectApi( "P1" );

n = "";
if (prj)
cmp = prj.GetComponent( "REC1" );

if(cmp)
var = cmp.GetVariable( "#VcLayer" );

if(var)
n = var.GetName();
end
end
end
applicationApi.LogScriptInformation("[" + n + "]",false);
applicationApi.Refresh();
return AS::API::Share::ASAPI_RETURNS.NORMAL_PROCESSING

Famic Technologies Inc. 7-71

Automation Studio™ – API and Scripting Language

7.3.3.7 bool SetName(string aliasStr);

Interface that will change the name of the variable. This is treated as an internal name,
so after this is set anywhere this is displayed will show this name translated to the
current environment.

Parameters:

aliasStr New string to be used as an alias.

Returns:

bool “True” indicates success.

Example:
#------------------------------------------------------------
# Name of File::VarSetName.rb
#
# Purpose::
# Method that will change the name of the variable.
#------------------------------------------------------------
require "AS.API.Share"

prj = applicationApi.GetProjectApi( "P1" );

if (prj)
cmp = prj.GetComponent( "REC1" );

if(cmp)
var = cmp.GetVariable( "#VcLayer" );

if(var)
var.SetName( "Layer2" );
end
end
end
applicationApi.Refresh();
return AS::API::Share::ASAPI_RETURNS.NORMAL_PROCESSING

7-72
 API Reference Manual

7.3.3.8 bool SetAlias(string aliasStr);

Interface that will change the alias of the variable.

Parameters:

aliasStr New string to be used as an alias.

Returns:

bool “True” indicates success.

Example:
#------------------------------------------------------------
# Name of File::VarSetAlias.rb
#
# Purpose::
# Method that will change the variables alias.
#------------------------------------------------------------
require "AS.API.Share"

prj = applicationApi.GetProjectApi( "P1" );

if (prj)
cmp = prj.GetComponent( "REC1" );

if(cmp)
var = cmp.GetVariable( "#VcLayer" );

if(var)
var.SetAlias( "Alias Test" );
end
end
end
applicationApi.Refresh();
return AS::API::Share::ASAPI_RETURNS.NORMAL_PROCESSING

Famic Technologies Inc. 7-73

Automation Studio™ – API and Scripting Language

7.3.3.9 bool SetDescription(stirng newText);

This is the method to use to change the text that currently exists for the description of
the component attribute.

Parameters:

newText New text to be used as the description for the component

attribute.

Returns:

bool “True” indicates success.

Example:
#------------------------------------------------------------
# Name of File::VarSetDescripton.rb
#
# Purpose::
# Example of changing the description on a component.
#------------------------------------------------------------
require "AS.API.Share"
prj = applicationApi.GetProjectApi( "P1" );
if (prj)
cmp = prj.GetComponent( "REC1" );

if(cmp)
var = cmp.GetVariable( "#VcLayer" );
if(var)
var.SetDescription( "New text" );
end
end
end

applicationApi.Refresh();
return AS::API::Share::ASAPI_RETURNS.NORMAL_PROCESSING

7-74
 API Reference Manual

7.3.3.10 bool SetValue(object value);

Interface to the value of the component attribute that needs to be changed.

Parameters:

value The value to replace the current value on the component

attribute.

Returns:

bool “True” indicates the value was changed.

Example:
#------------------------------------------------------------
# Name of File::VarSetValue.rb
#
# Purpose::
# Script that will modify the value of component ‘H1’
#------------------------------------------------------------
require "AS.API.Share"
prj = applicationApi.GetProjectApi( "P1" );
if (prj)
cmp = prj.GetComponent( "REC1" );

if(cmp)
var = cmp.GetVariable( "#VcLayer" );

if(var)
var.SetValue( "P3" );
end
end
end
applicationApi.Refresh();

return AS::API::Share::ASAPI_RETURNS.NORMAL_PROCESSING

Famic Technologies Inc. 7-75

Automation Studio™ – API and Scripting Language

7.3.3.11 bool Show(bool toShow);

If a variable has a visible representation related to its component, this method can be
used to turn on or off the visibility of this attribute.

Parameters:

toShow “True” indicates to make the variable visible.

Returns:

bool “True” indicates success.

Example:
#------------------------------------------------------------
# Name of File::VarShow.rb
#
# Purpose::
# Makes a variable visible. Expects a component “REC1”
#------------------------------------------------------------
require "AS.API.Share"
prj = applicationApi.GetProjectApi( "P1" );
if (prj)
cmp = prj.GetComponent( "REC1" );

if(cmp)
var = cmp.GetVariable( "#VcLayer" );
if(var)
var.Show(true);
end
end
end

applicationApi.Refresh();
return AS::API::Share::ASAPI_RETURNS.NORMAL_PROCESSING

7-76
 API Reference Manual

7.3.3.12 bool ShowAlias(bool toShow);

If a variable is visible and has a visible representation related to its component, this
method can be used to turn on or off the visibility the alias.

Parameters:

toShow True indicates to show the alias of the variable if the variable is
visible.

Returns:

bool “True” indicates success.

Example:
#------------------------------------------------------------
# Name of File::VarShowAlias.rb
#
# Purpose::
# Makes an alias attribute of a variable, visible or not.
#------------------------------------------------------------
require "AS.API.Share"

prj = applicationApi.GetProjectApi( "P1" );

if (prj)
cmp = prj.GetComponent( "REC1" );

if(cmp)
var = cmp.GetVariable( "#VcLayer" );
if(var)
var.Show(true);
var.ShowAlias(true);
end
end
end

applicationApi.Refresh();
return AS::API::Share::ASAPI_RETURNS.NORMAL_PROCESSING

Famic Technologies Inc. 7-77

Automation Studio™ – API and Scripting Language

7.4 Application

The application object is the main interface available to Automation Studio™ ’s object
model. This section describes how to access it and how it can be used.

7.4.1 Access to the Application Object

applicationApi Global variable to be used to access the application object.

This is used to access the system wide attributes found in Automation Studio™. The
application is the first object to be created and contains all other objects. There will only
be one application object ever created. It can be used as an interface that supplies access
that a user can use to manipulate his environment using scripts.

Whenever an object id of zero is used the user is accessing the application object.

All method calls available to a script are actually being managed by the application
object.

7.4.2 Supported Events/Hooks

asEvent = AS::API::Share::ASAPI_EVENTS

This table represents the list of points in AS’s process that a third-party developer can
hook into. This process entry points table relate to the application. The event column
indicates the attribute that will be supplied to the RegisterEvent() and
UnRegisterEvent() methods. The bypass processing column indicates whether or
not any code can be bypassed if the user indicates this should happen with the correct
return from his script.

Application dependent Events and Hooks

Event Bypass Available Description

Processing Parameters

PROJECT_CREATED No No This is called when a

7-78
 API Reference Manual

Event Bypass Available Description

Processing Parameters
project object is just about
to be created. .

OPEN_FILE Yes No This is called when the

open project menu option
is selected.

NEW_FILE Yes No This is called when the

new project menu option
is selected.

CLOSE_FILE Yes No This is called when the

close project menu option
is selected.

SIM_DISPLAY_CYCLE Yes No Called during each cycle

during simulation.

SNAPSHOT_DOC_CREATED No No Called before a snapshot is

created.

SIMULATE_STOP No No Called just before a

simulation is stopped.

SIMULATE_STOPPED No No Called just after a

simulation has been
stopped.

SIMULATE_START No No Called just before a

simulation has been
launched.

SIMULATE_PAUSED No No Called just after a

simulation has been

Famic Technologies Inc. 7-79

Automation Studio™ – API and Scripting Language

Event Bypass Available Description

Processing Parameters
paused.

7-80
 API Reference Manual

7.4.3 Methods

Methods that can be called from the Application Object.

7.4.3.1 bool AddRibbonCommandUsingDisplayName(string rTab, string

rGr, string rCmd, string cbMthd, string iconPath)

This interface will add ribbon components to Automation Studio ™’s main ribbon panel.
Any elements that do not already exist will be created. The strings used will be expecting
the string displayed in Automation Studio™.

If developing a script that must work when the language environment changes the script
writer should use the internal name of any elements that already exists in Automation
Studio™ and use the translation method TranslateASElementString(string
internalName) to get the name that will be displayed at runtime.

Parameters:

rTab Ribbon tab name (will be created if it doesn’t exist).

rGr Ribbon group name (will be created if it doesn’t exist).

rCmd Ribbon command name.

cbMthd Method to be called.

iconPath Icon to be used on ribbon.

Famic Technologies Inc. 7-81

Automation Studio™ – API and Scripting Language

Returns:

bool true success

Example: Requires two scripts

7-82
 API Reference Manual

#------------------------------------------------------------
# File::AppAddRibbonCommandUsingDisplayName.rb
#
# Purpose::
# This will show how to add ribbon tabs, groups, and
# commands to Automation Studio.
#------------------------------------------------------------
require "AS.API.Share"
app = applicationApi; # Simplify the expression.
#Creates a ribbon element that when selected will call
#the script “AppResponceTest.rb”

app.AddRibbonCommandUsingDisplayName(
"Tb" , "Gp" , "Run" ,
"Application\\AppResponseTest.rb",
"mycustom2.ico");
str1 = app.TranslateASElementString("#TrHome");
str2 = app.TranslateASElementString("#TrDrawing");
app.AddRibbonCommandUsingDisplayName(
str1, str2, "Run" ,
"Application\\AppResponseTest.rb",
"mycustom2.ico");

return AS::API::Share::ASAPI_RETURNS.NORMAL_PROCESSING

#------------------------------------------------------------
# Name of File::AppResponseTest.rb
#
# Purpose::
# Used by other scripts to show a script responding to a
# an event.
#------------------------------------------------------------
require "AS.API.Share"
require 'System.Windows.Forms,
Version=2.0.0.0, Culture=neutral,
PublicKeyToken=b77a5c561934e089'
strMsg = "Response From Action"
System::Windows::Forms::MessageBox.show strMsg
return AS::API::Share::ASAPI_RETURNS.NORMAL_PROCESSING

Famic Technologies Inc. 7-83

Automation Studio™ – API and Scripting Language

7.4.3.2 int CloseApplication(bool saveProjects)

Allow Automation Studio™ to close down, with the option to save the files currently in
memory. This must be called from a registered event and not from within an object.

Parameters:

saveProjects “True” indicates to save any currently modified projects;

“False” indicates to exit with out saving.

Returns:

int “Non-Zero” indicates a problem.

Example:

#-------------------------------------------------------------
# File::AppCloseApplication.rb
#
# Purpose::
# When called this script will shut down a currently
# running Automation Studio with saving modifications.
#------------------------------------------------------------
require "AS.API.Share"
applicationApi.CloseApplication(true)
return AS::API::Share::ASAPI_RETURNS.NORMAL_PROCESSING

7-84
 API Reference Manual

7.4.3.3 bool CloseProject(string prjName, bool bSave)

Close the project represented by the name.

Parameters:

prjName Name of the project to be closed.

bSave Should the project be saved before closed.

Returns:

bool “True” indicates success.

Warning:

This method must be called from a registered event from the application frame.
It can’t be called from an event from an object within the project that is being
closed.

Example:
#-------------------------------------------------------
# Name of File::AppCloseProject.rb
#
# Purpose::
# Demonstrates how to use the application objects
# CloseProject(). This will close project P2 if
# open.
#
#-------------------------------------------------------
require "AS.API.Share"
applicationApi.CloseProject("P2",true);
return AS::API::Share::ASAPI_RETURNS.NORMAL_PROCESSING

Famic Technologies Inc. 7-85

Automation Studio™ – API and Scripting Language

7.4.3.4 IDocumentApi GetDocument(string strName)

Get the document using its name from within a project that is in memory.

Parameters:

strName Name of the required document within the project.

Returns:

IDocumentApi The interface to the required document. “null” will be

returned if the document could not be found.

Example:
#-------------------------------------------------------
# Name of File::AppGetDocument.rb
#
# Purpose::
# Demonstrates how to use the base object’s
# GetDocument() method.
# This expects a project “P1” and a document “D1” to
# have been previously loaded.
#-------------------------------------------------------
require "AS.API.Share"

doc = applicationApi.GetDocument("P1","D1");
if(doc)
doc.Maximize();
end

return AS::API::Share::ASAPI_RETURNS.NORMAL_PROCESSING

7-86
 API Reference Manual

7.4.3.5 string GetEnvString(string variableName)

This method can be used to access Automation Studio™ global variables.

Parameters:

variableName Name of the required environment variable.

Returns:

string The value of the required environment variable.

Example:
#------------------------------------------------------------
# Name of File::AppGetEnvString.rb
#
# Purpose:
# This ruby script demonstrates the application objects
# GetEnvString method.
#------------------------------------------------------------
require "AS.API.Share"

msg = "The open file dialog used the following directory ["
msg << applicationApi.GetEnvString("DefaultProjectDirectory")
msg << "]"

applicationApi.LogScriptInformation(msg,false);
return AS::API::Share::ASAPI_RETURNS.NORMAL_PROCESSING

Famic Technologies Inc. 7-87

Automation Studio™ – API and Scripting Language

7.4.3.6 string GetProjectHomeDirectory ()

This method returns the currently set directory to place project files

Parameters:

NIL No parameters will be set.

Returns:

string Current location where projects will be saved or searched for.

Example:

#------------------------------------------------------------
# Name of File::AppGetProjectHomeDirectory.rb
#
# Purpose::
# Demonstrates how to use the application method
# AppGetProjectHomeDirectory()
#------------------------------------------------------------
require "AS.API.Share"

msg = "The current project home directory is "

msg << applicationApi.GetProjectHomeDirectory();

applicationApi.LogScriptInformation(msg,false);
return AS::API::Share::ASAPI_RETURNS.NORMAL_PROCESSING

7-88
 API Reference Manual

7.4.3.7 IProjectApi GetCurrentProject()

This provides access to the current project.

Parameters:

NIL No parameters will be set.

Returns:

IProjectApi Project object, which will be set to “nil” if it does not exist.

Example:

#------------------------------------------------------------
# Name of File::AppGetCurrentProject.rb
#
# Purpose::
# Demonstrates how to use AppGetCurrentProject.rb
#------------------------------------------------------------
require "AS.API.Share"
prj = applicationApi.GetCurrentProject();
if(prj)
strPrjName = prj.GetName();
applicationApi.LogScriptInformation(strPrjName,false);
end
return AS::API::Share::ASAPI_RETURNS.NORMAL_PROCESSING

Famic Technologies Inc. 7-89

Automation Studio™ – API and Scripting Language

7.4.3.8 IProjectApi GetProject(string strProjectName)

This provides access to a project which is currently in memory using the project’s name.

Parameters:

strProjectName The name of the project.

Returns:

IProjectApi The project object, which will be set to “nil” if it does not exist.

Example:

#------------------------------------------------------------
# Name of File::AppGetProject.rb
#
# Purpose::
# Demonstrates how to use the method GetProject on the
# application object.
# Warning::
# Expects that a project with the name Test.prx is in
# memory.
#------------------------------------------------------------
require "AS.API.Share"

prj = applicationApi.GetProject("P1");
if(prj)
strPrjName = prj.GetName();
applicationApi.LogScriptInformation(strPrjName,false);
end

return AS::API::Share::ASAPI_RETURNS.NORMAL_PROCESSING

7-90
 API Reference Manual

7.4.3.9 String GetScriptsDirectory()

This method allows the script builder to access the names of the directories that are
searched first. The following lists provides the default set of searches that are used to
find scripts. This method returns a string where each directory is separated by “;”. All
the following strings may be made up of multiple directories.

 The scripts directory string, if set.

 The script directories set be the application option “Custom Scripts Location”

 The script directories set by the application option “Enterprise Scripts Location”

 AS’s execution path plus the sub directory “Scripts”.

 AS’s users application data path plus “Scripts”.

 AS’s common application data path plus the sub directory “Scripts”.

The script directory is automatically set if Automation Studio™ is started using the
parameter /SCRIPTS:<script directory>.

Parameters:

NIL No parameters will be set.

Returns:

String A string of directories separated by “;”. The directories will be

searched in the order provided by this list.t.

Example:
#------------------------------------------------------------
# Name of File::AppGetScriptDirectory.rb
#
# Purpose::
# This ruby script demonstrates fetching the script
# directory.
#------------------------------------------------------------

Famic Technologies Inc. 7-91

Automation Studio™ – API and Scripting Language
require "AS.API.Share"
dir = applicationApi.GetScriptsDirectory();
msg = "Scripts will be loaded from the following directory. ["
if(dir)
msg << dir
end
msg << "]"
applicationApi.LogScriptInformation(msg,false);
return AS::API::Share::ASAPI_RETURNS.NORMAL_PROCESSING

7-92
 API Reference Manual

7.4.3.10 int HideDialog(ASAPI_METHOD idDialog)

This will force the dialog identifier defined by the id provided to be hidden. The runtime
version of AS can’t change the visibility of the message output, the graphical library, or
the variables dialog.

Parameters:

idDialog One of the following.

AS::API::Share::ASAPI_METHODS.MTHD_SHOWDLG_LAYERS
AS::API::Share::ASAPI_METHODS.MTHD_SHOWDLG_OUTPUT
AS::API::Share::ASAPI_METHODS.MTHD_SHOWDLG_PROJECT_EXPLORER
AS::API::Share::ASAPI_METHODS.MTHD_SHOWDLG_LIBRARY
AS::API::Share::ASAPI_METHODS.MTHD_SHOWDLG_PLOTTER

AS::API::Share::ASAPI_METHODS.MTHD_SHOWDLG_PLOTTER_ELECTROTECHNIQUE
AS::API::Share::ASAPI_METHODS.MTHD_SHOWDLG_STATUS_BAR
AS::API::Share::ASAPI_METHODS.MTHD_SHOWDLG_VARIABLES

Returns:

bool “True” indicates success.

Example:
#------------------------------------------------------------
# Name of File::AppHideDialog.rb
# Purpose::
# Make a dialogs invisible.
#------------------------------------------------------------
require "AS.API.Share"

mthd = AS::API::Share::ASAPI_METHODS
nlogType = AS::API::Share::LOGTYPE.AS_MESSAGE_SYSTEM
applicationApi.ChangeAllLogOutputs(nlogType);
applicationApi.HideDialog(mthd.MTHD_SHOWDLG_LAYERS);
applicationApi.HideDialog(mthd.MTHD_SHOWDLG_PROJECT_EXPLORER);
applicationApi.HideDialog(mthd.MTHD_SHOWDLG_LIBRARY);
applicationApi.HideDialog(mthd.MTHD_SHOWDLG_VARIABLES);
applicationApi.HideDialog(mthd.MTHD_SHOWDLG_OUTPUT);

Famic Technologies Inc. 7-93

Automation Studio™ – API and Scripting Language

return AS::API::Share::ASAPI_RETURNS.NORMAL_PROCESSING

7-94
 API Reference Manual

7.4.3.11 int HideRibbon()

This method hides the application ribbon bar.

Parameters:

NIL No parameters will be set.

Returns:

bool “True” indicates success.

Example:
#------------------------------------------------------------
# Name of File::AppHideRibbon.rb
#
# Purpose::
# Demonstrates how to use the method HideRibbon on the
# application object.
#------------------------------------------------------------
require "AS.API.Share"
applicationApi.HideRibbon();
return AS::API::Share::ASAPI_RETURNS.NORMAL_PROCESSING

Famic Technologies Inc. 7-95

Automation Studio™ – API and Scripting Language

7.4.3.12 int LoadProject(string szProjectName)

This loads the project defined by szProjectName. If the project already exists it will be
made active. This expects either the full path or that the project exist in the current
project directory.

Parameters:

szProjectName Name of the project to be loaded. The path string will be

interpreted using the first of the following rules to find the file:

 If the path begins with a drive letter or “\\” it will be interpreted as the full
path name. No other rule will be applied.

Otherwise the first of the following rules to find the file will be used.

 The current project home directory. This is set by a script using

SetProjectHomeDirectory(string dir) method.

 The directory of the currently active project file.

 The default project directory. This is the current directory set by the last call to
open file dialog.

 The user’s application data directory for Automation Studio ™.

 The common user’s application data directory for Automation Studio ™.

Returns:

int Non-Zero indicates a problem

Example:
#------------------------------------------------------------
# Name of File::AppLoadProject.rb
#
# Purpose::
# This example will load a project with the name
# “ApiTest.prx”

7-96
 API Reference Manual
#------------------------------------------------------------
require "AS.API.Share"
applicationApi.LoadProject("ApiTest.prx");
return AS::API::Share::ASAPI_RETURNS.NORMAL_PROCESSING

Famic Technologies Inc. 7-97

Automation Studio™ – API and Scripting Language

7.4.3.13 bool Refresh(ptOrg,ptMin,ptMax, rStart, rEnd)

Refresh all projects, dialogs, and documents within an application. Points used by the
interface are of type System::Drawing::Point.

Parameters:

ptOrt The origin of the arc.

ptMin Minimum reference to the bounding box

of the arc.

ptMax Maximum reference to the bounding box

of the arc.

rStart Starting Radius in degrees.

iEnd Ending Radius in degrees of arc.

Returns:

bool The application was refreshed if true.

Example:
#------------------------------------------------------------
# Name of File::AppRefresh.rb
#
# Purpose::
# Shows how a script writer can refresh all elements in an.
# application.
#------------------------------------------------------------
require "AS.API.Share"

doc = applicationApi.GetDocumentApi( "D1" , "P1" );

if(doc)
st = doc.SetStandard("#VdPageSetupStandard","ISO A3");
applicationApi.Refresh();
end

7-98
 API Reference Manual
return AS::API::Share::ASAPI_RETURNS.NORMAL_PROCESSING

Famic Technologies Inc. 7-99

Automation Studio™ – API and Scripting Language

7.4.3.14 bool SelectView(string szView)

This method activates a particular or many views denoted by the string szView. This
expects the view to already be loaded in memory.

Parameters:

szView This is the name of the view to be

selected. This string uses the following
syntax:

<<project>,<document >,<view>>[:<<project>,<document>,<view>>]

The view name may use the view number instead of the string.

Returns:

bool Indicates that the view was successfully selected if

“true”.

Example:
#------------------------------------------------------------
# Name of File::AppSelectView.rb
#
# Purpose:
# This ruby script demonstrates the application objects
# SelectView method.
#------------------------------------------------------------
require "AS.API.Share"
applicationApi.SelectView("P3,D3,View2");
applicationApi.SelectView("P3,D1,3:P2,D1,View3:P3,D1,1");

return AS::API::Share::ASAPI_RETURNS.NORMAL_PROCESSING

7-100
 API Reference Manual

7.4.3.15 bool SetExportPath(string dir)

This method allows the script where exported files will be saved.

Parameters:

dir The export output directory

Returns:

bool “True” if successful.

Example:
#------------------------------------------------------------
# Name of File::AppSetExportPath.rb
#
# Purpose::
# Demonstrates how to use the application method
# SetExportPath()
#------------------------------------------------------------
require "AS.API.Share"
applicationApi.SetExportPath( "C:\\Temp" );
prj = applicationApi.GetProjectApi( "P1" );
if(prj)
prj.Export( "SVG" );
end
return AS::API::Share::ASAPI_RETURNS.NORMAL_PROCESSING

Famic Technologies Inc. 7-101

Automation Studio™ – API and Scripting Language

7.4.3.16 bool SendUserInterfaceMessage(int eventId)

This method allows the script builder to send a number of UI events to Automation
Studio™. These are specifically good if you are replacing ribbon buttons with your own
ribbon.

Parameters:

The event to be sent. It can be any of the following. They will only produce valid results if
the display can respond to the event when it is sent.

ID_SIMULATION_PROJECT_START
ID_SIMULATION_DIAGRAM_START
ID_SIMULATION_NORMAL
ID_SIMULATION_STEP
ID_SIMULATION_SLOW_MOTION
ID_SIMULATION_PAUSE
ID_SIMULATION_STOP
ID_ZOOM_DYNAMIC
ID_ZOOM_PREVIOUS
ID_ZOOM_PAGE
ID_ZOOM_WINDOW
ID_ZOOM_PLUS
ID_ZOOM_MINUS
ID_ZOOM_COMPONENTS
ID_CLEAR_MESSAGE_WINDOW
ID_TROUBLESHOOT_ HYDRAULIC
ID_TROUBLESHOOT_GAUGE
ID_TROUBLESHOOT_THERMOMETER
ID_TROUBLESHOOT_MULTIMETER
ID_TROUBLESHOOT_DISCONNECT_WIRE
ID_TROUBLESHOOT_RECONNECT_WIRE
ID_TROUBLESHOOT_DISCONNECT_LINE
ID_TROUBLESHOOT_RECONNECT_LINE
ID_TROUBLESHOOT_REPAIR
ID_TROUBLESHOOT_OPEN_HYDRAULIC_DETECTION_TOOL
ID_TROUBLESHOOT_EDIT_FAILURE
ID_WINDOW_TILE_HORZ
ID_WINDOW_TILE_VERT
ID_WINDOW_CASCADE
ID_PRJ_BACK

7-102
 API Reference Manual
ID_PRJ_FORWARD

Returns:

bool “True” indicates that the event was sent.

“False” indicates an unsupported alias was supplied.

Example:
#------------------------------------------------------------
# Name of File::AppSendUserInterfaceMessage.rb
#
# Purpose::
# This tests how the script builder can launch events
# that the user interface can respond to.
#------------------------------------------------------------
require "AS.API.Share"

idMessage = AS::API::Share::IdMessage

applicationApi.SendUserInterfaceMessage(idMessage.ID_TROUBLESHOOT_DIS

return AS::API::Share::ASAPI_RETURNS.NORMAL_PROCESSING

Famic Technologies Inc. 7-103

Automation Studio™ – API and Scripting Language

7.4.3.17 bool SetProjectHomeDirectory (string home)

This method allows the script builder to specify where project files will be located if no
path has been specified. If this variable is not set, the following search will take place:

 Current Directory;

 Users Application Data Directory for Automation Studio ™;

 Common Application Data Directory for Automation Studio™.

Parameters:

NIL No parameters will be set.

Returns:

string Current location where projects will be saved or searched

for.

Example:

#------------------------------------------------------------
# Name of File::AppSetProjectHomeDirectory.rb
#
# Purpose::
# Demonstrates how to use the application method
# AppSetProjectHomeDirectory(). This expects that
# C:\Temp\A1.prx exists
#------------------------------------------------------------
require "AS.API.Share"
applicationApi.SetProjectHomeDirectory("C:\\Temp");
applicationApi.LoadProject("P1.prx");
return AS::API::Share::ASAPI_RETURNS.NORMAL_PROCESSING

7-104
 API Reference Manual

7.4.3.18 bool SetRibbonPanelVisibilityUsingDisplayName(string tb,

string gr,bool visible)

This method removes or restores a specific application ribbon panel using display names
of the ribbon objects to be affected. Ribbons elements created by the script writer are
only known by the displayed name provided.

When the panel is restored it is restored to the end of the ribbon bar.

If developing a script that must work when the language environment changes, the script
writer should use the internal name of any elements that already exists in Automation
Studio™ and use the translation method TranslateASElementString(string
internalName) on the name that will be displayed at runtime.

Parameters:

tb Display name of the tab the panel is in.

gr Display name of the group to be made visible.

“true”: Make the tab visible
visible “false”: Make the tab invisible

Returns:

bool True indicates success

Example:

#------------------------------------------------------------
# File:: AppSetRibbonPanelVisibilityUsingDisplayName.rb
# Purpose::
# This will show how to add ribbon tabs and groups to
# Automation Studio.
#------------------------------------------------------------
require "AS.API.Share"
app = applicationApi;
str1 = app.TranslateASElementString("#TrEdit");
str2 = app.TranslateASElementString("#TrArrange");

Famic Technologies Inc. 7-105

Automation Studio™ – API and Scripting Language
app.SetRibbonPanelVisibilityUsingDisplayName(str1,str2,false);
#Make invisible our custom ribbon tab and panel
app.SetRibbonPanelVisibilityUsingDisplayName("Tb","Gp",false)
return AS::API::Share::ASAPI_RETURNS.NORMAL_PROCESSING

7-106
 API Reference Manual

7.4.3.19 bool SetRibbonTabVisibilityUsingDisplayName (string tName,

bool visible)

This method hides or restores a specific application ribbon tab using the displayed name
of the ribbon object to be affected. Client ribbons are only known by their displayed
name.

If developing a script that must work when the language environment changes the script,
the writer should use the internal name of the required tab and use the translation
method TranslateASElementString(string internalName) to get the name
that will be displayed at runtime.

Parameters:

tName Internal name of the required tab

visible “true” makes the tab visible.

“false” makes the tab invisible.

Returns:

bool “True” indicates success.

Example:

#------------------------------------------------------------
# File:: AppSetRibbonTabVisibilityUsingDisplayName.rb
#
# Purpose::
# This will make a particular ribbon tab invisible
#------------------------------------------------------------
require "AS.API.Share"
app = applicationApi;
str1 = app.TranslateASElementString("#TrTools");
#Make visible our custom ribbon tab and panel
app.SetRibbonTabVisibilityUsingDisplayName(str1, false);
app.SetRibbonTabVisibilityUsingDisplayName("Tb", false);
return AS::API::Share::ASAPI_RETURNS.NORMAL_PROCESSING

Famic Technologies Inc. 7-107

Automation Studio™ – API and Scripting Language

7-108
 API Reference Manual

7.4.3.20 int ShowDialog(ASAPI_METHOD idDialog)

This will force the dialog defined by the ID provided to be shown. The runtime version of
Automation Studio™ can’t change the visibility of the message output, the graphical
library, or the variables dialog.

Parameters:

idDialog One of the following.

AS::API::Share::ASAPI_METHODS.MTHD_SHOWDLG_LAYERS
AS::API::Share::ASAPI_METHODS.MTHD_SHOWDLG_OUTPUT
AS::API::Share::ASAPI_METHODS.MTHD_SHOWDLG_PROJECT_EXPLORER
AS::API::Share::ASAPI_METHODS.MTHD_SHOWDLG_LIBRARY
AS::API::Share::ASAPI_METHODS.MTHD_SHOWDLG_PLOTTER

AS::API::Share::ASAPI_METHODS.MTHD_SHOWDLG_PLOTTER_ELECTROTECHNIQUE
AS::API::Share::ASAPI_METHODS.MTHD_SHOWDLG_STATUS_BAR
AS::API::Share::ASAPI_METHODS.MTHD_SHOWDLG_VARIABLES

Returns:

bool “True” indicates success.

Example:
#------------------------------------------------------------
# Name of File::AppShowDialog.rb
# Purpose::
# Make a dialogs visible.
#------------------------------------------------------------
require "AS.API.Share"

mthd = AS::API::Share::ASAPI_METHODS
nlogType = AS::API::Share::LOGTYPE.AS_MESSAGE_SYSTEM
applicationApi.ChangeAllLogOutputs(nlogType);
applicationApi.ShowDialog(mthd.MTHD_SHOWDLG_LAYERS);
applicationApi.ShowDialog(mthd.MTHD_SHOWDLG_PROJECT_EXPLORER);
applicationApi.ShowDialog(mthd.MTHD_SHOWDLG_LIBRARY);
applicationApi.ShowDialog(mthd.MTHD_SHOWDLG_VARIABLES);
applicationApi.ShowDialog(mthd.MTHD_SHOWDLG_OUTPUT);

Famic Technologies Inc. 7-109

Automation Studio™ – API and Scripting Language
return AS::API::Share::ASAPI_RETURNS.NORMAL_PROCESSING

7-110
 API Reference Manual

7.4.3.21 bool SimulateInSlowMotion(int iFactor)

This method runs a simulation in slow motion and uses a factor between 2 and 25. The
larger the number is, the slower is the simulation.

Parameters:

iFactor Factor used to slow the simulation down by. A value between 1
and 25 with 25 being the slowest simulation.

Returns:

bool Return “true” if the simulation could be run in slow motion.

Example:
#------------------------------------------------------------
# Name of File::Application\AppSimulateInSlowMotion.rb
#
# Purpose::
# This starts a simulation using a different update rate.
#------------------------------------------------------------
require "AS.API.Share"
asVarType = AS::API::Share::ASAPI_VARTYPES

applicationApi.ChangeAllLogOutputs(
AS::API::Share::LOGTYPE.AS_MESSAGE_SYSTEM);

applicationApi.SimulateInSlowMotion(8);

return AS::API::Share::ASAPI_RETURNS.NORMAL_PROCESSING

Famic Technologies Inc. 7-111

Automation Studio™ – API and Scripting Language

7.4.3.22 int StartSimulation()

This method starts the currently selected set of documents and layers to be simulated.

Parameters:

NIL No parameters will be set.

Returns:

int Non-Zero value indicates a problem.

Example:

#------------------------------------------------------------
# Name of File::StartSimulationExample.rb
#
# Purpose::
# This example will start the system simulating.
#------------------------------------------------------------
require "AS.API.Share"
applicationApi.StartSimulation()
return AS::API::Share::ASAPI_RETURNS.NORMAL_PROCESSING

7-112
 API Reference Manual

7.4.3.23 int StopSimulation()

This method stops any currently running simulation.

Parameters:

NIL No parameters will be set.

Returns:

bool Simulation stopped.

Example:

#------------------------------------------------------------
# Name of File::StoptSimulation.rb
#
# Purpose::
# This example will stop the simulation.
#------------------------------------------------------------
require "AS.API.Share"
applicationApi.StopSimulation()
return AS::API::Share::ASAPI_RETURNS.NORMAL_PROCESSING

Famic Technologies Inc. 7-113

Automation Studio™ – API and Scripting Language

7.4.3.24 int ToggleDialog(ASAPI_METHOD idDialog)

This will force the dialog defined by the id provided to be shown if hidden and hidden if
shown. The runtime version of AS can’t change the visibility of the message output, the
graphical library, or the variables dialog.

Parameters:

idDialog One of the following.

AS::API::Share::ASAPI_METHODS.MTHD_SHOWDLG_LAYERS
AS::API::Share::ASAPI_METHODS.MTHD_SHOWDLG_OUTPUT
AS::API::Share::ASAPI_METHODS.MTHD_SHOWDLG_PROJECT_EXPLORER
AS::API::Share::ASAPI_METHODS.MTHD_SHOWDLG_LIBRARY
AS::API::Share::ASAPI_METHODS.MTHD_SHOWDLG_PLOTTER
AS::API::Share::ASAPI_METHODS.MTHD_SHOWDLG_PLOTTER_ELECTROTECHNIQUE
AS::API::Share::ASAPI_METHODS.MTHD_SHOWDLG_STATUS_BAR
AS::API::Share::ASAPI_METHODS.MTHD_SHOWDLG_VARIABLES

Returns:

bool True indicates success.

Example:
#------------------------------------------------------------
# Name of File::AppShowDialog.rb
# Purpose::
# Make a dialogs visible.
#------------------------------------------------------------
require "AS.API.Share"

mthd = AS::API::Share::ASAPI_METHODS
nlogType = AS::API::Share::LOGTYPE.AS_MESSAGE_SYSTEM
applicationApi.ChangeAllLogOutputs(nlogType);
applicationApi.ToggleDialog(mthd.MTHD_SHOWDLG_LAYERS);
applicationApi.ToggleDialog(mthd.MTHD_SHOWDLG_PROJECT_EXPLORER);
applicationApi.ToggleDialog(mthd.MTHD_SHOWDLG_LIBRARY);
applicationApi.ToggleDialog(mthd.MTHD_SHOWDLG_VARIABLES);
applicationApi.ToggleDialog(mthd.MTHD_SHOWDLG_OUTPUT);

7-114
 API Reference Manual

return AS::API::Share::ASAPI_RETURNS.NORMAL_PROCESSING

Famic Technologies Inc. 7-115

Automation Studio™ – API and Scripting Language

7.4.3.25 String TranslateASElementString(string internalString)

Converts an internal name to a string using the current platform language.

Parameters:

internalString Automation Studio™ internal name that requires a translation.

Returns:

String If the string is not found in the language database the original
name will be returned.

Example:
#------------------------------------------------------------
# Name of File::AppTranslateASElementString.rb
#
# Purpose::
# Shows how to access the translated name of an Automation
# Studio component using an internal name.
#
#------------------------------------------------------------
require "AS.API.Share"

app = applicationApi;
internalName = "_AS_Dynamic Measurements";

str = app.TranslateASElementString(internalName);

applicationApi.LogScriptInformation(str,false);

return AS::API::Share::ASAPI_RETURNS.NORMAL_PROCESSING

7-116
 API Reference Manual

7.5 Project

This is used to access the attributes that are managed by an Automation Studio™ project.

7.5.1.1 Access

To access an instance of a project the following call can be used.

int GetProject();

This method returns the project identifier that initiated the current event. If no project
initiated the event then this will return “-1”. A project will exist if a project that initiated
the event or a child or grandchild etc... initiated the event.

The second method to find a project is to navigate through the project children of the
application.
nCnt = applicationApi.GetChildCount(asTid.PROJECT_API);
nIdx = 0
while (nIdx < nCnt) do
pPrj=applicationApi.GetNthChild(nIdx,asTid.PROJECT_API);
… # Then you use the project object.
nIdx += 1
end

Famic Technologies Inc. 7-117

Automation Studio™ – API and Scripting Language

7.5.2 Supported Events/Hooks

This table represents the list of points in Automation Studio™’s process that a third-party
developer can hook into dependent on a variable on the project. This process entry points
table relates to the project object. The event column indicates the variable that can be
set and that will be tested when the event occurs. The bypass processing column
indicates whether or not any code can be bypassed if the user indicates this should
happen with the correct return from his script.

Project dependent Events and Hooks

Variable On Project Bypass Related method called

Processing

ApiClientMethodClose No When a project object is

just about to be closed.

ApiClientMethodOpen No When a project object is

just about to be
opened.

ApiClientMethodSimPaused No When a project under

simulation is paused
(just after).

ApiClientMethodSimStopped No When a project under

simulation is stopped

7-118
 API Reference Manual

Variable On Project Bypass Related method called

Processing
(just after).

ApiClientMethodSimStart Yes Just before a project

under simulation is run.

ApiClientMethodSimStop No Just before a project

under simulation is
stopped.

Famic Technologies Inc. 7-119

Automation Studio™ – API and Scripting Language

7.5.3 Methods

Methods that can be called from a Project.

7.5.3.1 int CloseProject()

This method closes the project represented by the object. This will not save the project if
modified. Use the CloseProject() from the application object if this is required.

Parameters:

NIL No parameters will be set.

Returns:

int Non-Zero value indicates a problem.

Warning:

This method must be called from a registered event from the application frame. It can’t
be called from an event from an object within the project that is being closed.

Example:
#-------------------------------------------------------
# Name of File::PrjCloseProject.rb
#
# Purpose::
# Demonstrates how to use the projects CloseProject()
# method.
#-------------------------------------------------------
require "AS.API.Share"

prj = applicationApi.GetProjectApi( "P2" );

if (prj)
cmp = prj.CloseProject();
# Warning, the prj object can no longer be used.
end
return AS::API::Share::ASAPI_RETURNS.NORMAL_PROCESSING

7-120
 API Reference Manual

7.5.3.2 int Export(string type)

This method exports all documents, within the project, selected for export to the file type
supplied. This will places the files in the file export directory set by the method
SetExportPath(string pathName)on the application object. The following
naming convention will be used.

<project name><document name>.<file type>

In the case of a .pdf, only one file will be created using the following naming convention.

<project name>.pdf

Parameters:

type Type of file to be saved to. Can be one of dxf, pdf, svg, or tiff.

Returns:

int Non-Zero value indicates a problem.

Example:
#--------------------------------------------------------
# Name of File::PrjExport.rb
#
# Purpose::
# Demonstrates the use of the method Export()
#--------------------------------------------------------
require "AS.API.Share"
applicationApi.SetExportPath( "C:\\temp" );
prj = applicationApi.GetProjectApi( "P1" );
if(prj)
prj.SetToBeExported(true);
prj.Export( "svg" );
prj.Export( "dxf" );
prj.Export( "xml" );

end
return AS::API::Share::ASAPI_RETURNS.NORMAL_PROCESSING

Famic Technologies Inc. 7-121

Automation Studio™ – API and Scripting Language

7-122
 API Reference Manual

7.5.3.3 IComponentApi GetComponent(string intrlCmptId)

This method gets the component within the project that has a component identifier equal
to the one provided in the parameter.

Parameters:

intrlCmptId Identifier of the required component.

Returns:

IComponentApi Required component’s interface. “Null” will be returned if the

component cannot be found.

Example:
#-------------------------------------------------------
# Name of File::PrjGetComponent.rb
#
# Purpose::
# Demonstrates how to use the GetComponent() method.
# This expects a component with the supplied ID".
#-------------------------------------------------------
require "AS.API.Share"

prj = applicationApi.GetProjectApi( "P1" );

if (prj)
cmp = prj.GetComponent("REC1");
if(cmp)
name = cmp.GetName();
end
end
return AS::API::Share::ASAPI_RETURNS.NORMAL_PROCESSING

Famic Technologies Inc. 7-123

Automation Studio™ – API and Scripting Language

7.5.3.4 IDocumentApi GetDocument(string strName)

This method gets the document using its name from within a project that is in memory.

Parameters:

strName Name of the required document within the project.

Returns:

IDocumentApi The interface to the required document. “Null” will be returned

if the document could not be found.

Example:

This example expects that the project containing the document has already been loaded.
#-------------------------------------------------------
# Name of File::PrjGetDocument.rb
#
# Purpose::
# Demonstrates how to use the GetDocument() method.
# This expects a document with the name "D1" exists.
#-------------------------------------------------------
require "AS.API.Share"

prj = applicationApi.GetProjectApi( "P1" );

if (prj)
doc = prj.GetDocument( "D1" );
if(doc)
doc.Maximize();
end
end

return AS::API::Share::ASAPI_RETURNS.NORMAL_PROCESSING

7-124
 API Reference Manual

7.5.3.5 string GetLanguage()

this method gets the current language set to the document.

Parameters:

NIL No parameters will be set.

Returns:

string The language set to the document.

Example:

This example expects that the project containing the document has already been loaded.
#-------------------------------------------------------
# Name of File::PrjGetLanguage.rb
#
# Purpose::
# Tests the method that extracts the current language
# used from the document.
#-------------------------------------------------------
require "AS.API.Share"

msg = "The project’s language is set to ["

prj = applicationApi.GetProjectApi( "P1" );
if(prj)
msg << prj.GetLanguage();
msg << "]"
applicationApi.LogScriptInformation(msg,false);
end

return AS::API::Share::ASAPI_RETURNS.NORMAL_PROCESSING

Famic Technologies Inc. 7-125

Automation Studio™ – API and Scripting Language

7-126
 API Reference Manual

7.5.3.6 int SaveProject(bool saveAs)

This method saves the object’s project. If saveAs is set to true, the method will query
the user with the file “save as” dialog.

Parameters:

saveAs True and the “save as” dialog will pop up.

Returns:

int Non-Zero value indicates a problem.

Example:
#-------------------------------------------------------
# Name of File::PrjSaveProject.rb
#
# Purpose::
# Demonstrates how to use the projects SaveProject
# method.
#-------------------------------------------------------
require "AS.API.Share"

prj = applicationApi.GetProjectApi( "P1" );

if (prj)
prj.SaveProject(true)
end

return AS::API::Share::ASAPI_RETURNS.NORMAL_PROCESSING

Famic Technologies Inc. 7-127

Automation Studio™ – API and Scripting Language

7.5.3.7 bool SetLanguage(string lang)

This method sets the current language for text objects with translation enabled.

Parameters:

lang The language to be used within a document. This string must

be found in the list of supported languages within the project.
These values are saved with the project and will not change if
the project is loaded in a different environment.

“Project Properties”  “Project”  “Translation”

Figure 7-1: Translation within a project

The names to be used within the language table of the project

are selected by the display builder and saved with the file.
When a project is created the language table will contain one
field with the following syntax.

<Create language environment> (<Original>)

7-128
 API Reference Manual

Returns:

bool Internal use

Example:

This example expects that the project containing the document has already been loaded.
#-------------------------------------------------------
# Name of File::PrjSetLanguage.rb
#
# Purpose:
# This ruby script demonstrates the project objects
# SetLanguage method. For this to work the language
# used has to have been added to the projects
# Properties translation language tab.
#------------------------------------------------------
require "AS.API.Share"

prj = applicationApi.GetProjectApi( "P1" );

if(prj)
prj.SetLanguage( "English" );
end

return AS::API::Share::ASAPI_RETURNS.NORMAL_PROCESSING

Famic Technologies Inc. 7-129

Automation Studio™ – API and Scripting Language

7.5.3.8 int SetSimulationMode(AS.API.Share.SIM_MODE eSimMode)

Automation Studio™ supports the following three different types of simulation:

 Current Document’s Simulation;

 Current Project’s Simulation;
 Simulation of selected documents within a project.

The following method is used to change the type of simulation.

Parameters:

eSimMode Type of simulation to be executed.

public enum SIM_MODE
{
Document,
Project,
Selected
}

Returns:

int Non-Zero value indicates a problem.

7-130
 API Reference Manual

Example:

 Note that there are two separate scripts in this example.

#-------------------------------------------------------
# Name of File::PrjSetSimulationMode.rb
#
# Purpose::
# This script sets the next simulation to use
# document simulation mode.
#-------------------------------------------------------
require "AS.API.Share"
applicationApi.StopSimulation();
applicationApi.LoadScript("PrjSetSimValues.rb");

applicationApi.ChangeAllLogOutputs(AS::API::Share::LOGTYPE.AS_MESSAGE_SYSTEM);
prj = applicationApi.GetCurrentProject();

if (prj)
if($simCurMode == 1)
prj.SetSimulationMode(AS::API::Share::SIM_MODE.Selected);
elsif($simCurMode == 2)
prj.SetSimulationMode(AS::API::Share::SIM_MODE.Document);
else
prj.SetSimulationMode(AS::API::Share::SIM_MODE.Project);
$simCurMode = 0;
end
$simCurMode += 1;
end

applicationApi.StartSimulation();
return AS::API::Share::ASAPI_RETURNS.NORMAL_PROCESSING

#------------------------------------------------------------
# Name of File::PrjSetSimValues.rb
#
# Purpose::
# Used to initialize and keep global variable for the
# project scripts.
#------------------------------------------------------------
require "AS.API.Share"
$simCurMode = 1;
return AS::API::Share::ASAPI_RETURNS.NORMAL_PROCESSING

Famic Technologies Inc. 7-131

Automation Studio™ – API and Scripting Language

7.5.3.9 int SetToBeExported(bool bSet)

This method sets the export flag on all documents within a project.

Parameters:

bSet The export document flag is set to this value. Next time the
export process is run, the exportation of each document will be
dependent on this flag.

Returns:

int Non-Zero value indicates a problem.

Example:
#--------------------------------------------------------
# Name of File::PrjSetToBeExported.rb
#
# Purpose::
# Demonstrates the use of the method SetToBeExported
#--------------------------------------------------------
require "AS.API.Share"

applicationApi.SetExportPath( "C:\\temp" );
prj = applicationApi.GetProjectApi( "P1" );
if(prj)
prj.SetToBeExported(true);
prj.Export( "svg" );
end

return AS::API::Share::ASAPI_RETURNS.NORMAL_PROCESSING

7-132
 API Reference Manual

7.5.3.10 int SimulateSnapshot(string snapName)

This method starts a snapshot document.

Parameters:

snapName Name of the snapshot to get the simulation information to.

Returns:

int Non-Zero value indicates a problem

Example:
#-------------------------------------------------------
# Name of File::PrjSimulateSnapshot.rb
#
# Purpose::
# Demonstrates how to use the project’s
# SimulateSnapshot(..) method.
#-------------------------------------------------------
require "AS.API.Share"

snapshotName = "Simulation1";

prj = applicationApi.GetProjectApi( "P1" );

if (prj)
prj.SimulateSnapshot(snapshotName);
end

return AS::API::Share::ASAPI_RETURNS.NORMAL_PROCESSING

Famic Technologies Inc. 7-133

Automation Studio™ – API and Scripting Language

7.5.3.11 int SimulationSelection(string szSimulateList)

This sets a current list of documents within the project that will be simulated when
simulation starts. The current mode will also be modified to simulate only selected
documents. Any documents omitted from the list will not be simulated.

Parameters:

szSimulateList A string of documents to be simulated using the syntax:

<document>[,<document>]

Where document is a name of a valid document within the

project. The name of the document does not include the
extension.

Returns:

int Non-Zero value indicates a problem

Example:
#-------------------------------------------------------
# Name of File::PrjSimulationSelection.rb
#
# Purpose::
# Demonstrates how to use the project’s
# SimulationSelection(..) method.
#-------------------------------------------------------
require "AS.API.Share"

applicationApi.ChangeAllLogOutputs(AS::API::Share::LOGTYPE.AS_MESSAGE_SYSTEM);
prj = applicationApi.GetCurrentProject();
if (prj)
prj.SimulationSelection("D1,D2");
end

return AS::API::Share::ASAPI_RETURNS.NORMAL_PROCESSING

7-134
 API Reference Manual

7.5.3.12 int TakeManualSnapshot()

This method triggers a manual snapshot during simulation.

Parameters:

NIL No parameters will be set.

Returns:

int Non-Zero value indicates a problem

Example:
#-------------------------------------------------------
# Name of File::PrjTakeManualSnapshot.rb
#
# Purpose::
# Demonstrates how to use the project’s
# TakeManualSnapshot(..) method.
#-------------------------------------------------------
require "AS.API.Share"

snapshotName = "Simulation1";

prj = applicationApi.GetProjectApi( "P1" );

if (prj)
prj.TakeManualSnapshot();
end

return AS::API::Share::ASAPI_RETURNS.NORMAL_PROCESSING

Famic Technologies Inc. 7-135

Automation Studio™ – API and Scripting Language

7.6 Document

This is used to access the attributes that are managed by a document.

7.6.1 Access to the Document Object

To access an instance of a document the following call can be used:

int GetDocument();

This method returns the document identifier that initiated the current event. If no
document initiated the event then this will return “-1”. A document will exist if a
document or a child or grandchild initiated the event.

The second method to find a document is to navigate through the document children of a
project.
nCnt = projectApi.GetChildCount(asTid.DOCUMENT_API);
nIdx = 0
while (nIdx < nCnt) do
pPrj = projectApi.GetNthChild(nIdx,
asTid.PROJECT_API);
… # Then you use the project object.
nIdx += 1
end

7-136
 API Reference Manual

7.6.2 Methods

Methods that can be called from a Document.

7.6.2.1 IComponentApi AddArc(ptOrg,ptMin,ptMax, rStart, rEnd)

This method adds an arc to an image. Points used by the interface are of type
System::Drawing::Point.

Parameters:

ptOrt The origin of the arc.

ptMin Minimum reference to the bounding box of the arc.

ptMax Maximum reference to the bounding box of the arc.

rStart Starting Radius in degrees.

iEnd Ending Radius in degrees of arc.

Returns:

bool The arc was successfully added.

Example:
#------------------------------------------------------------
# Name of File::DocAddArc.rb
#
# Purpose::
# Shows how a script writer can add a Arc to a document.
#
#------------------------------------------------------------
require "AS.API.Share"
require 'System.Drawing,
Version=2.0.0.0, Culture=neutral,
PublicKeyToken=b03f5f7f11d50a3a'

Famic Technologies Inc. 7-137

Automation Studio™ – API and Scripting Language

doc = applicationApi.GetDocumentApi( "D1" , "P1" );

if(doc)
ptOrg = System::Drawing::Point.new;
ptMin = System::Drawing::Point.new;
ptMax = System::Drawing::Point.new;

ptOrg.X = 500;
ptOrg.Y = 500;
ptMin.X = 0;
ptMin.Y = 0;
ptMax.X = 400;
ptMax.Y = 400;

doc.AddArc(ptOrg, ptMin, ptMax, 90, 180);

doc.Refresh();
end

return AS::API::Share::ASAPI_RETURNS.NORMAL_PROCESSING

7-138
 API Reference Manual

7.6.2.2 IComponentApi AddCatalogComponent(ptOrg,

szPath,obj,option)

This method adds a reference to a component created from a catalogue.

Parameters:

ptOrt The origin of the line.

szPath Path to the object within the current system catalog structure.

szObj Object to insert.

szOption Option.

Returns:

IComponentApi A reference catalogue component.

Example:
#------------------------------------------------------------
# Name of File::DocAddCatalogComponent.rb
#
# Purpose::
# Shows how a script writer can add a component from a
# catalog.
#------------------------------------------------------------
require "AS.API.Share"
require 'System.Drawing,
Version=2.0.0.0, Culture=neutral,
PublicKeyToken=b03f5f7f11d50a3a'

doc = applicationApi.GetDocumentApi( "D1" , "P1" );

if(doc)
ptOrg = System::Drawing::Point.new;
ptOrg.X = 500;
ptOrg.Y = 500;

Famic Technologies Inc. 7-139

Automation Studio™ – API and Scripting Language

st=doc.AddCatalogComponent(ptOrg,"C:\\ASExamples\\HydraforceIDesign_1.ctg",
20","");
applicationApi.Refresh();
end

return AS::API::Share::ASAPI_RETURNS.NORMAL_PROCESSING

7-140
 API Reference Manual

7.6.2.3 IComponentApi AddConnection(IComponentApi cmp1, int port1,

IComponentApi cmp2, int port2, CPOINT wayPoints[ ])

Alternate Syntax

IComponentApi AddConnection(String cmp1, int port1, String cmp2, int port2,

CPOINT wayPoints[ ])

IComponentApi AddConnection(String cmp1, String port1, String cmp2, String

port2, CPOINT wayPoints[ ])

IComponentApi AddConnection(CPOINT wayPoints[ ])

This provides to the script writer a method to connect components to each other with a
connector. If the second component or both components is/are not supplied, it/they will
be replaced by nodes.

Parameters:

cmp1 First component internal name (string) or the object

(IComponentApi) to connect to.

port1 Port number or display name (string), to connect to, on the

first component.

cmp2 Second component internal name (string) or the object

(IComponentApi) to connect to.

port2 Port number or display name (string), to connect to, on the

second component.

wayPoints Array of interger points to help route the connector. If not

provided the connector will be directly connected to the
nodes. If the components and ports are not supplied the way
points will route the connector.

Famic Technologies Inc. 7-141

Automation Studio™ – API and Scripting Language

Returns:

IComponentApi This returns the component of the connector created. NULL

object will be returned if the method failed to create the
component.

Example:
#------------------------------------------------------------
# Name of File::DocAddConnection.rb
#
# Purpose::
# Add a connectors between two component ports. This expects
# the two components H2 and H3 to exist in the current
# document.
#------------------------------------------------------------
require "AS.API.Share"
require 'System.Drawing,
Version=2.0.0.0, Culture=neutral,
PublicKeyToken=b03f5f7f11d50a3a'

applicationApi.ChangeAllLogOutputs(
AS::API::Share::LOGTYPE.AS_MESSAGE_SYSTEM);
doc = applicationApi.GetCurrentDocument();
prj = applicationApi.GetCurrentProject();

# Add Connection without components or ports.

if(doc)
ptOrg = System::Drawing::Point.new;
listVertex = applicationApi.CreatePointList();

cmp1 = prj.GetComponent( "H2" );

cmp2 = prj.GetComponent( "H3" );

ptValue1 = cmp1.GetDocRelativePortPosition(2);
ptValue2 = cmp2.GetDocRelativePortPosition(2);

ptOrg.X = ptValue1.X;
ptOrg.Y = ptValue1.Y + 100; listVertex.Add(ptOrg);
ptOrg.X = ptOrg.X + 150; listVertex.Add(ptOrg);
ptOrg.Y = ptValue2.Y - 100; listVertex.Add(ptOrg);
ptOrg.X = ptValue2.X; listVertex.Add(ptOrg);
cmpAdded = doc.AddConnection("H2",2,"H3",2,listVertex);
cmpName = cmpAdded.GetName();

7-142
 API Reference Manual

listVertex = applicationApi.CreatePointList();
ptValue1 = cmp1.GetDocRelativePortPosition(1);
ptValue2 = cmp2.GetDocRelativePortPosition(1);
ptOrg.X = ptValue1.X;
ptOrg.Y = ptValue1.Y - 100; listVertex.Add(ptOrg);
ptOrg.X = ptOrg.X + 200; listVertex.Add(ptOrg);
ptOrg.Y = ptValue2.Y + 100; listVertex.Add(ptOrg);
ptOrg.X = ptValue2.X; listVertex.Add(ptOrg);
cmpAdded = doc.AddConnection("H2","A","H3","A",listVertex);
cmpName = cmpAdded.GetName();

listVertex2 = applicationApi.CreatePointList();
ptValue1 = cmp1.GetDocRelativePortPosition(3);
ptOrg.X = ptValue1.X - 300;
ptOrg.Y = ptValue1.Y; listVertex2.Add(ptOrg);
ptOrg.X = ptOrg.Y - 200; listVertex2.Add(ptOrg);
ptOrg.Y = ptOrg.X - 300; listVertex2.Add(ptOrg);
cmpAdded = doc.AddConnection("H2","C","","",listVertex2);
cmpName = cmpAdded.GetName();

listVertex = applicationApi.CreatePointList();
ptValue1 = cmp1.GetDocRelativePortPosition(2);
ptOrg.X = ptValue1.X;
ptOrg.Y = ptValue1.Y + 300; listVertex.Add(ptOrg);
ptOrg.X = ptOrg.X + 200; listVertex.Add(ptOrg);
ptOrg.Y = ptOrg.Y - 100; listVertex.Add(ptOrg);
ptOrg.X = ptOrg.X + 100; listVertex.Add(ptOrg);
cmpAdded = doc.AddConnection(listVertex);
cmpName = cmpAdded.GetName();

applicationApi.Refresh();
end

return AS::API::Share::ASAPI_RETURNS.NORMAL_PROCESSING

Famic Technologies Inc. 7-143

Automation Studio™ – API and Scripting Language

7.6.2.4 IComponentApi AddEllipse (ptOrg,ptMin,ptMax)

This method adds an ellipse to an image. Points used by the interface are of type
System::Drawing::Point.

Parameters:

ptOrt The origin of the arc.

ptMin Minimum reference to the bounding box of the arc.

ptMax Maximum reference to the bounding box of the arc.

Returns:

bool The arc was successfully added.

Example:
#------------------------------------------------------------
# Name of File::DocAddEllipse.rb
#
# Purpose::
# Shows how a script writer can add an ellipse to a document.
#
#------------------------------------------------------------
require "AS.API.Share"
require 'System.Drawing,
Version=2.0.0.0, Culture=neutral,
PublicKeyToken=b03f5f7f11d50a3a'

doc = applicationApi.GetDocumentApi( "D1" , "P1" );

if(doc)
ptOrg = System::Drawing::Point.new;
ptMin = System::Drawing::Point.new;
ptMax = System::Drawing::Point.new;

ptOrg.X = 500;
ptOrg.Y = 300;

7-144
 API Reference Manual
ptMin.X = 0;
ptMin.Y = 0;
ptMax.X = 200;
ptMax.Y = 500;
doc.AddEllipse(ptOrg, ptMin, ptMax);
doc.Refresh();
end

return AS::API::Share::ASAPI_RETURNS.NORMAL_PROCESSING

Famic Technologies Inc. 7-145

Automation Studio™ – API and Scripting Language

7.6.2.5 IComponentApi AddLibraryComponent(ptOrg, szPath)

This method adds a reference to a component created from a library.

Parameters:

ptOrt The origin of the line.

szPath Path to the object within the current system library structure.

szName Component Name

bInternal True indicates internal name false display name (default)

Returns:

IComponentApi A reference library component.

Example:
#------------------------------------------------------------
# Name of File::DocAddLibraryComponent.rb
#
# Purpose::
# Shows how a script writer can add a component from the
# system libraray.
#------------------------------------------------------------
require "AS.API.Share"
require 'System.Drawing,
Version=2.0.0.0, Culture=neutral,
PublicKeyToken=b03f5f7f11d50a3a'
doc = applicationApi.GetDocumentApi( "D1" , "P1" );
if(doc)
ptOrg = System::Drawing::Point.new;
ptOrg.X = 500;
ptOrg.Y = 500;
st = doc.AddLibraryComponent(ptOrg,"Hydraulic\\Flow Lines
and Connections\\Vertical Flexible Line","");
applicationApi.Refresh();
end
return AS::API::Share::ASAPI_RETURNS.NORMAL_PROCESSING

7-146
 API Reference Manual

Famic Technologies Inc. 7-147

Automation Studio™ – API and Scripting Language

7.6.2.6 IComponentApi AddLine(ptOrg,ptFirst,ptLast)

This method adds a line to an image. Points used by the interface are of type
System::Drawing::Point.

Parameters:

ptOrt The origin of the line.

ptFirst First point in the line

ptLast Last point in the line

Returns:

bool The line was successfully added.

Example:
#------------------------------------------------------------
# Name of File::DocAddLine.rb
#
# Purpose::
# Shows how a script writer can add a line to a document.
#
#------------------------------------------------------------
require "AS.API.Share"
require 'System.Drawing,
Version=2.0.0.0, Culture=neutral,
PublicKeyToken=b03f5f7f11d50a3a'

doc = applicationApi.GetDocumentApi( "D1" , "P1" );

if(doc)
ptOrg = System::Drawing::Point.new;
ptFirst = System::Drawing::Point.new;
ptLast = System::Drawing::Point.new;

ptOrg.X = 500;
ptOrg.Y = 500;

7-148
 API Reference Manual
ptFirst.X = 0;
ptFirst.Y = 0;
ptLast.X = 400;
ptLast.Y = 400;

doc.AddLine(ptOrg,ptFirst,ptLast);
ptFirst.X = 700;
doc.AddLine(ptOrg,ptFirst,ptLast);

applicationApi.Refresh();
end

return AS::API::Share::ASAPI_RETURNS.NORMAL_PROCESSING

Famic Technologies Inc. 7-149

Automation Studio™ – API and Scripting Language

7.6.2.7 IComponentApi AddNestedPolygons (ptOrg,listCnt,listPoints)

This method adds a set of polygons to an image. This allows the script builder to add
holes to polygons. Points used by the interface are of type
System::Drawing::Point.

Parameters:

ptOrt The origin of the polygon

listCnt List of number of points in each polygon.

listPoints List of points. The API supplies a method to create a point list
for this method, see IApplicationApi
CreatePointList().

Returns:

IComponentApi The polygon that was successfully added.

Example:
#------------------------------------------------------------
# Name of File::DocAddNestedPolygons.rb
#
# Purpose::
# Shows how a script writer can add nested polygons also
# known as PolyPolygons.
#------------------------------------------------------------
require "AS.API.Share"
require 'System.Drawing,
Version=2.0.0.0, Culture=neutral,
PublicKeyToken=b03f5f7f11d50a3a'

doc = applicationApi.GetDocumentApi( "D1" , "P1" );

if(doc)
ptOrg = System::Drawing::Point.new;
System::Drawing::Point.new;

7-150
 API Reference Manual

listVertex = applicationApi.CreatePointList();

#Polygon 1
ptOrg.X = 0;
ptOrg.Y = 500;
listVertex.Add(ptOrg);
ptOrg.X = 500;
ptOrg.X = ptOrg.X + 100;
listVertex.Add(ptOrg);
ptOrg.Y = ptOrg.Y + 100;
listVertex.Add(ptOrg);
ptOrg.X = ptOrg.X + 100;
listVertex.Add(ptOrg);
ptOrg.Y = ptOrg.Y + 100;
listVertex.Add(ptOrg);
ptOrg.X = ptOrg.X + 100;
listVertex.Add(ptOrg);
ptOrg.Y = ptOrg.Y + 300;
listVertex.Add(ptOrg);

#Polygon 2
ptOrg.X = 300;
ptOrg.Y = 600;
listVertex.Add(ptOrg);
ptOrg.X = 400;
ptOrg.X = ptOrg.X + 100;
listVertex.Add(ptOrg);
ptOrg.Y = ptOrg.Y + 100;
listVertex.Add(ptOrg);
ptOrg.X = ptOrg.X + 100;
listVertex.Add(ptOrg);
ptOrg.Y = ptOrg.Y + 120;
listVertex.Add(ptOrg);

ptOrg.X = 800;
ptOrg.Y = 400;

listCounts = applicationApi.CreateIntList();
listCounts.Add(7);
listCounts.Add(5);

cmp = doc.AddNestedPolygons(ptOrg, listCounts,

Famic Technologies Inc. 7-151

Automation Studio™ – API and Scripting Language
listVertex);
cmp.SetPatternFill(46);
cmp.SetForegroundColor(0xff0000);
cmp.SetColor(0x00ff00);
cmp.SetBackgroundColor(0x0000ff);

applicationApi.Refresh();
end

return AS::API::Share::ASAPI_RETURNS.NORMAL_PROCESSING

7-152
 API Reference Manual

7.6.2.8 IComponentApi AddPolyline (ptOrg,ptCount,listPoints)

This method adds a polygon to an image. Points used by the interface are of type
System::Drawing::Point.

Parameters:

ptOrt The origin of the text.

ptCount Total number of points in the list.

listPoints List of points. The API supplies a method to create a point list
for this method. see IApplicationApi
CreatePointList().

Returns:

bool The polygon was successfully added.

Example:

#------------------------------------------------------------
# Name of File::DocAddPolyline.rb
#
# Purpose::
# Shows how a script writer can add a polyline to a document.
#
#------------------------------------------------------------
require "AS.API.Share"
require 'System.Drawing,
Version=2.0.0.0, Culture=neutral,
PublicKeyToken=b03f5f7f11d50a3a'

doc = applicationApi.GetDocumentApi( "D1" , "P1" );

if(doc)
ptOrg = System::Drawing::Point.new;

Famic Technologies Inc. 7-153

Automation Studio™ – API and Scripting Language
ptOrg.X = 500;
ptOrg.Y = 500;
listVertex = applicationApi.CreatePointList();
listVertex.Add(ptOrg);
ptOrg.X = ptOrg.X + 100;
listVertex.Add(ptOrg);
ptOrg.Y = ptOrg.Y + 100;
listVertex.Add(ptOrg);
ptOrg.X = ptOrg.X + 100;
listVertex.Add(ptOrg);
ptOrg.Y = ptOrg.Y + 100;
listVertex.Add(ptOrg);
ptOrg.X = ptOrg.X + 100;
listVertex.Add(ptOrg);
ptOrg.Y = ptOrg.Y + 100;
listVertex.Add(ptOrg);
ptOrg.X = ptOrg.X + 100;
listVertex.Add(ptOrg);
ptOrg.Y = ptOrg.Y + 100;
listVertex.Add(ptOrg);
ptOrg.X = ptOrg.X + 100;
listVertex.Add(ptOrg);
ptOrg.Y = ptOrg.Y + 100;
listVertex.Add(ptOrg);
ptOrg.X = 600;
ptOrg.Y = 400;
doc.AddPolyline(ptOrg,listVertex);
applicationApi.Refresh();
end

return AS::API::Share::ASAPI_RETURNS.NORMAL_PROCESSING

7-154
 API Reference Manual

7.6.2.9 IComponentApi AddRectangle(ptOrg,ptMin,ptMax)

This method adds a rectangle to an image. Points used by the interface are of type
System::Drawing::Point.

Parameters:

ptOrt The origin of the line.

ptMin Top left point on the rectangle.

ptMax Bottom right point on the rectangle

Returns:

bool The rectangle was successfully added.

Example:
#------------------------------------------------------------
# Name of File::DocAddRectangle.rb
#
# Purpose::
# Shows how a script writer can add a rectangle to
# a document.
#
#------------------------------------------------------------
require "AS.API.Share"
require 'System.Drawing,
Version=2.0.0.0, Culture=neutral,
PublicKeyToken=b03f5f7f11d50a3a'

doc = applicationApi.GetDocumentApi( "D1" , "P1" );

if(doc)
ptOrg = System::Drawing::Point.new;
ptMin = System::Drawing::Point.new;
ptMax = System::Drawing::Point.new;

ptOrg.X = 500;

Famic Technologies Inc. 7-155

Automation Studio™ – API and Scripting Language
ptOrg.Y = 500;
ptMin.X = 0;
ptMin.Y = 0;
ptMax.X = 400;
ptMax.Y = 400;

doc.AddRectangle(ptOrg,ptMin,ptMax);
applicationApi.Refresh();
end

return AS::API::Share::ASAPI_RETURNS.NORMAL_PROCESSING

7-156
 API Reference Manual

7.6.2.10 IComponentApi AddSpline(ptOrg,ptCount,listPoints)

This method adds a spline also known as a curve to an image. Points used by the
interface are of type System::Drawing::Point.

Parameters:

ptOrt The origin of the text.

ptCount Total number of points in the list.

listPoints List of points. The API supplies a method to create a point list.
For this method, see IApplicationApi
CreatePointList().

Returns:

ComponentApi The spline that was successfully added.

Example:
#------------------------------------------------------------
# Name of File::DocAddSpline.rb
#
# Purpose::
# Shows how a script writer can add a spline to a document.
#
#------------------------------------------------------------
require "AS.API.Share"
require 'System.Drawing,
Version=2.0.0.0, Culture=neutral,
PublicKeyToken=b03f5f7f11d50a3a'

doc = applicationApi.GetDocumentApi( "D1" , "P1" );

if(doc)
ptOrg = System::Drawing::Point.new;
ptOrg.X = 500;
ptOrg.Y = 500;

Famic Technologies Inc. 7-157

Automation Studio™ – API and Scripting Language
listVertex = applicationApi.CreatePointList();
listVertex.Add(ptOrg);
ptOrg.X = ptOrg.X + 100;
listVertex.Add(ptOrg);
ptOrg.Y = ptOrg.Y + 100;
listVertex.Add(ptOrg);
ptOrg.X = ptOrg.X + 100;
listVertex.Add(ptOrg);

listCtrlPoints = applicationApi.CreatePointList();

ptOrg.X = 520;
ptOrg.Y = 920;
listCtrlPoints.Add(ptOrg)
ptOrg.X = 540;
ptOrg.Y = 520;
listCtrlPoints.Add(ptOrg)
ptOrg.X = 620;
ptOrg.Y = 500;
listCtrlPoints.Add(ptOrg)
ptOrg.X = 580;
ptOrg.Y = 560;
listCtrlPoints.Add(ptOrg)
ptOrg.X = 620;
ptOrg.Y = 640;
listCtrlPoints.Add(ptOrg)
ptOrg.X = 660;
ptOrg.Y = 640;
listCtrlPoints.Add(ptOrg)
ptOrg.X = 800;
ptOrg.Y = 1800;

doc.AddSpline(ptOrg,listVertex,listCtrlPoints);
applicationApi.Refresh();
end

return AS::API::Share::ASAPI_RETURNS.NORMAL_PROCESSING

7-158
 API Reference Manual

7.6.2.11 IComponentApi AddText (ptOrg,ptMin,ptMax,ht,width,font)

This adds a bounded MTEXT object to the document. Points used by the interface are of
type System::Drawing::Point.

Parameters:

ptOrt The origin of the text.

ptMin Minimum reference to the bounding box of the text.

ptMax Maximum reference to the bounding box of the text.

ht Height of the character.

width Average width of the character

font Font used.

Returns:

bool The text object was successfully added.

Example:
#------------------------------------------------------------
# Name of File::DocAddText.rb
#
# Purpose::
# Shows how a script writer can add text to a document.
#
#------------------------------------------------------------
require "AS.API.Share"
require 'System.Drawing,
Version=2.0.0.0, Culture=neutral,
PublicKeyToken=b03f5f7f11d50a3a'

doc = applicationApi.GetDocumentApi( "D1" , "P1" );

Famic Technologies Inc. 7-159

Automation Studio™ – API and Scripting Language

if(doc)
ptOrg = System::Drawing::Point.new;
ptMin = System::Drawing::Point.new;
ptMax = System::Drawing::Point.new;

ptOrg.X = 500;
ptOrg.Y = 500;
ptMin.X = 0;
ptMin.Y = 0;
ptMax.X = 400;
ptMax.Y = 400;

doc.AddText("The String",ptOrg,ptMin,ptMax,24,24,"Arial");
doc.Refresh();
end

return AS::API::Share::ASAPI_RETURNS.NORMAL_PROCESSING

7-160
 API Reference Manual

7.6.2.12 bool CloseView (string szViewName)

This method closes a view defined by szViewName.

Parameters:

szViewName String of views to be shown. Uses the following format:

<First View Name ie “View2”> or <View number>

The prefix “View” is not mandatory.

“View2” = “2”

Returns:

bool The view was closed.

Example:
#------------------------------------------------------------
# Name of File::DocCloseView.rb
#
# Purpose::
# This method closes a view with the name view2 in
# the current document.#
#------------------------------------------------------------
require "AS.API.Share"

doc = applicationApi.GetDocumentApi( "D1" , "P1" );

if(doc)
doc.CloseView("View2");
applicationApi.Refresh();
end
return AS::API::Share::ASAPI_RETURNS.NORMAL_PROCESSING

Famic Technologies Inc. 7-161

Automation Studio™ – API and Scripting Language

7.6.2.13 IViewApi CreateView (string name)

This method creates a view in the current document if the view does not already exist. If
the view already exists, it will be selected.

Parameters:

name The name of the view to be created.

Returns:

IViewApi An interface to the new view object.

Example:
#------------------------------------------------------------
# Name of File::DocCreateView.rb
#
# Purpose::
# This shows how to create a new view.
#------------------------------------------------------------
require "AS.API.Share"
doc = applicationApi.GetDocumentApi( "D1" , "P1" );
if(doc)
view = doc.CreateView("V1");
end
return AS::API::Share::ASAPI_RETURNS.NORMAL_PROCESSING

7-162
 API Reference Manual

7.6.2.14 string GetStandardName(string szStandardType)

This method returns the standard used by the document.

Parameters:

szStandardType The standard of interest. Could be any of the following.

standards = applicationApi.GetConstantOptionStrings();

 standards.k_VdPageSetupStandard;
 standards.k_VdMapLocatorStandard;
 standards.k_VdReferenceStandard;
 standards.k_VdDimensioningStandard;
 standards.k_VdDrawingToolsStandard;
 standards.k_VdFluidStandard;
 standards.k_VdHydraulicStandard;
 standards.k_VdPneumaticStandard;
 standards.k_VdElectrotechnicalStandard;
 standards.k_VdOneLineStandard;
 standards.k_VdPanelLayoutStandard;
 standards.k_VdSFCStandard;
 standards.k_VdLadderLogicStandard;
 standards.k_VdElectricalStandard;
 standards.k_VdDigitalElectronicStandard;
 standards.k_VdConnectionDiagramStandard;

Returns:

bool Valid layer names where supplied to the process.

Example:

Famic Technologies Inc. 7-163

Automation Studio™ – API and Scripting Language
#------------------------------------------------------------
# Name of File::DocGetStandardName.rb
#
# Purpose::
# To shows an implementation of the documents GetStandard
# method.
#------------------------------------------------------------
require "AS.API.Share"

doc = applicationApi.GetDocumentApi( "D1" , "P1" );

standards = applicationApi.GetConstantOptionStrings();
pageSetup = standards.k_VdPageSetupStandard;

if(doc)
st = doc.GetStandardName(pageSetup);

msg = "Following standard found [" + st.ToString() + "]";

applicationApi.LogScriptInformation(msg,false);
end

return AS::API::Share::ASAPI_RETURNS.NORMAL_PROCESSING

7-164
 API Reference Manual

7.6.2.15 bool HideAllLayers (bool bToHide)

This method hides all layers in the related document.

Parameters:

bToHide true: turn the layer visibility off.

False: turn the layer visibility on.

Returns:

bool Valid layer names where supplied to the process.

Example:
#------------------------------------------------------------
# Name of File::HideAllLayers.rb
#
# Purpose::
# Hides all layers in the current document
#------------------------------------------------------------
require "AS.API.Share"

doc = applicationApi.GetDocumentApi( "D1" , "P1" );

if(doc)
doc.HideAllLayers(true);
end

return AS::API::Share::ASAPI_RETURNS.NORMAL_PROCESSING

Famic Technologies Inc. 7-165

Automation Studio™ – API and Scripting Language

7.6.2.16 bool Maximize()

This method sets the frame of the first view of the document to use the entire window
space.

Parameters:

NIL No parameters will be set.

Returns:

bool The document was maximized.

Example:
#------------------------------------------------------------
# Name of File::DocMaximize.rb
#
# Purpose::
# This maximizes the current document.
#------------------------------------------------------------
require "AS.API.Share"

viewApi = AS::API::Share::ASAPI_OBJ.VIEW_API;

doc = applicationApi.GetDocumentApi( "D1" , "P1" );

if(doc)
doc.Maximize();
doc.Refresh();
end

return AS::API::Share::ASAPI_RETURNS.NORMAL_PROCESSING

7-166
 API Reference Manual

7.6.2.17 bool Minimize()

This method minimizes all views within a document.

Parameters:

NIL No parameters will be set.

Returns:

bool The document was maximized.

Example:
#------------------------------------------------------------
# Name of File::DocMinimize.rb
#
# Purpose::
# This minimizes the current document.
#------------------------------------------------------------
require "AS.API.Share"

viewApi = AS::API::Share::ASAPI_OBJ.VIEW_API;

doc = applicationApi.GetDocumentApi( "D1" , "P1" );

if(doc)
doc.Minimize();
doc.Refresh();
end
return AS::API::Share::ASAPI_RETURNS.NORMAL_PROCESSING

Famic Technologies Inc. 7-167

Automation Studio™ – API and Scripting Language

7.6.2.18 IViewApi GetView( string viewString)

This method searches and returns the view object related to the document.

Parameters:

viewString Name of the required view.

Returns:

IViewApi The view object. Null will be returned if the view does not
exist.

Example:
#------------------------------------------------------------
# Name of File::DocGetView.rb
#
# Purpose::
# To shows an implementation of the documents GetView method.
#------------------------------------------------------------
require "AS.API.Share"

viewApi = AS::API::Share::ASAPI_OBJ.VIEW_API;

doc = applicationApi.GetDocumentApi( "D1" , "P1" );

if(doc)
view = doc.GetView("View2");
if(view)
view.Show(true);
end
end
return AS::API::Share::ASAPI_RETURNS.NORMAL_PROCESSING

7-168
 API Reference Manual

7.6.2.19 bool HideAllLayers (bool bToShow)

Hides all layers within the document.

Parameters:

bToShow True: Turn the layer visibility on.

False: Turn the layer visibility off.

Returns:

bool The layers could be hidden or made visible.

Example:
#------------------------------------------------------------
# Name of File::DocHideAllLayers.rb
#
# Purpose::
# This shows how to use a documents HideAllLayers method.
#------------------------------------------------------------
require "AS.API.Share"

doc = applicationApi.GetDocumentApi( "D1" , "P1" );

if(doc)
doc.HideAllLayers(true);
end
return AS::API::Share::ASAPI_RETURNS.NORMAL_PROCESSING

Famic Technologies Inc. 7-169

Automation Studio™ – API and Scripting Language

7.6.2.20 bool Refresh()

This method refreshes an image after adding an arch to it.

Parameters:

NIL No parameters will be set.

Returns:

bool The document was refreshed.

Example:
#------------------------------------------------------------
# Name of File::DocRefresh.rb
#
# Purpose::
# Shows how a script writer can refresh a document. This
# script adds an arc and then refreshes the image.
#
#------------------------------------------------------------
require "AS.API.Share"
require 'System.Drawing, Version=2.0.0.0, Culture=neutral,
PublicKeyToken=b03f5f7f11d50a3a'
doc = applicationApi.GetDocumentApi( "D1" , "P1" );
if(doc)
ptOrg = System::Drawing::Point.new;
ptMin = System::Drawing::Point.new;
ptMax = System::Drawing::Point.new;
ptOrg.X = 500;
ptOrg.Y = 500;
ptMin.X = 0;
ptMin.Y = 0;
ptMax.X = 400;
ptMax.Y = 400;
doc.AddArc(ptOrg, ptMin, ptMax, 90, 180);
doc.Refresh();
end
return AS::API::Share::ASAPI_RETURNS.NORMAL_PROCESSING

7-170
 API Reference Manual

Famic Technologies Inc. 7-171

Automation Studio™ – API and Scripting Language

7.6.2.21 bool SetSimulateAllLayers(bool bToSim)

Sets the simulation attribute to true on all layers found.

Parameters:

bToSim True: set simulation flat to true

False: set simulation flag to false

Returns:

bool Valid layer names where supplied to the process.

Example:

7-172
 API Reference Manual
#------------------------------------------------------------
# Name of File::SetSimulateAllLayers.rb
#
# Purpose::
# This search for all documents currently loaded and
# sets the simulation flag to false on any layers found
#------------------------------------------------------------
require "AS.API.Share"

iCnt = applicationApi.GetChildCount(1);
i = 0
until i == iCnt
prj = applicationApi.GetNthChild(i, 1);
iCnt2 = prj.GetChildCount(2);
j = 0
until j == iCnt2
doc = prj.GetNthChild(j, 2);
doc.SetSimulateAllLayers(false);
j += 1
end
i += 1
end

applicationApi.StartSimulation();
return AS::API::Share::ASAPI_RETURNS.NORMAL_PROCESSING

Famic Technologies Inc. 7-173

Automation Studio™ – API and Scripting Language

7.6.2.22 bool SetSimulateLayers(string szLayersList, bool bToSim)

This method sets the simulation attribute to true on any layers that match the provided
list. When a project is saved and reopened in a different language environment the layer
names do not change so scripts can be written with these names.

Parameters:

szLayersList This list is a string of layer names separated by commas “,”

bToSim true: set simulation flat to true

false: set simulation flag to false

Returns:

bool Valid layer names where supplied to the process.

Example:

7-174
 API Reference Manual
#------------------------------------------------------------
# Name of File::SetSimulateLayers.rb
#
# Purpose::
# This search for all documents currently loaded and
# sets the simulation flag to false on any layers found
# that match the supplied list.
#------------------------------------------------------------
require "AS.API.Share"

iCnt = applicationApi.GetChildCount(1);
i = 0
until i == iCnt
prj = applicationApi.GetNthChild(i, 1);
iCnt2 = prj.GetChildCount(2);
j = 0
until j == iCnt2
doc = prj.GetNthChild(j, 2);
doc.SetSimulateLayers("Layer 3,Layer 4",false);
doc.SetSimulateLayers("Layer 1,Layer 2",true);

j += 1
end
i += 1
end

applicationApi.StartSimulation();
return AS::API::Share::ASAPI_RETURNS.NORMAL_PROCESSING

Famic Technologies Inc. 7-175

Automation Studio™ – API and Scripting Language

7.6.2.23 bool SetStandard(string szStandardType, string newStand)

This method returns the standard used by the document.

Parameters:

szStandardType The standard of interest. Could be any of the

following.

standards = applicationApi.GetConstantOptionStrings();

 standards.k_VdPageSetupStandard;
 standards.k_VdMapLocatorStandard;
 standards.k_VdReferenceStandard;
 standards.k_VdDimensioningStandard;
 standards.k_VdDrawingToolsStandard;
 standards.k_VdFluidStandard;
 standards.k_VdHydraulicStandard;
 standards.k_VdPneumaticStandard;
 standards.k_VdElectrotechnicalStandard;
 standards.k_VdOneLineStandard;
 standards.k_VdPanelLayoutStandard;
 standards.k_VdSFCStandard;
 standards.k_VdLadderLogicStandard;
 standards.k_VdElectricalStandard;
 standards.k_VdDigitalElectronicStandard;
 standards.k_VdConnectionDiagramStandard;

newStand The new standard to use.

Returns:

true Valid layer names where supplied to the process.

Example:

7-176
 API Reference Manual
#------------------------------------------------------------
# Name of File::DocSetStandard.rb
#
# Purpose::
# Allows a script writer to change the standard of a document
#------------------------------------------------------------
require "AS.API.Share"

doc = applicationApi.GetDocumentApi( "D1" , "P1" );

standards = applicationApi.GetConstantOptionStrings();
pageSetup = standards.k_VdPageSetupStandard;

if(doc)
st = doc.SetStandard(pageSetup,"ISO A3");
applicationApi.Refresh();
end

return AS::API::Share::ASAPI_RETURNS.NORMAL_PROCESSING

Famic Technologies Inc. 7-177

Automation Studio™ – API and Scripting Language

7.6.2.24 int SetToBeExported(bool bSet)

This method sets the export flat on the document.

Parameters:

bSet The export document flag is set to this value. Next time the
export process is run on its project, the exportation of this
document will depend on this flag.

Returns:

int Non-Zero value indicates a problem.

Example:
#--------------------------------------------------------
# Name of File::DocSetToBeExported.rb
#
# Purpose::
# Demonstrates the use of the documents method
# SetToBeExported()
#--------------------------------------------------------
require "AS.API.Share"
prj = applicationApi.GetProjectApi( "P1" );
if(prj)
prj.SetToBeExported(false);
doc = applicationApi.GetDocumentApi( "D1" , "P1" );
if(doc)
doc.SetToBeExported(true);
end
prj.Export("svg");
end

return AS::API::Share::ASAPI_RETURNS.NORMAL_PROCESSING

7-178
 API Reference Manual

7.6.2.25 bool SetZoomAndPan(bool bPan)

This will turn on or off the interface that allows a user to zoom or pan the primary view
of the document.

Parameters:

bPan True: allows a user to zoom and pan the primary view.

False: prevents a user from zooming or panning the primary

view.

Returns:

bool Success or failure of the operation.

Example:
#------------------------------------------------------------
# Name of File::DocSetPanAndZoom.rb
#
# Purpose:
# Demonstrates the use of the document objects method
# SetPanAndZoom().
#------------------------------------------------------------
require "AS.API.Share"

doc = applicationApi.GetDocumentApi( "D1" , "P1" );

if(doc)
doc.SetZoomAndPan(false);
end
return AS::API::Share::ASAPI_RETURNS.NORMAL_PROCESSING

Famic Technologies Inc. 7-179

Automation Studio™ – API and Scripting Language

7.6.2.26 bool Show(bool bShow)

Show the primary view of a document, first view in the array of views.

Parameters:

bShow Optional, default is true which will make the primary view
visible.

Returns:

bool The views where shown.

Example:
#------------------------------------------------------------
# Name of File::DocShow.rb
#
# Purpose::
# Shows the primary view of a document.
#------------------------------------------------------------
require "AS.API.Share"

doc = applicationApi.GetDocumentApi( "D1" , "P1" );

if(doc)
showType = AS::API::Share::SHOW_TYPE.SHOW;
doc.Show(showType);
doc.Refresh();

end

return AS::API::Share::ASAPI_RETURNS.NORMAL_PROCESSING

7-180
 API Reference Manual

7.6.2.27 bool ShowAllViews()

Show all views within the document. the set of views supplied in the list.

Parameters:

bShow Optional, default is true which will make the primary view
visible.

Returns:

bool The views where shown.

Example:
#------------------------------------------------------------
# Name of File::DocShowAllViews.rb
#
# Purpose::
# Shows all views within a document.
#------------------------------------------------------------
require "AS.API.Share"

doc = applicationApi.GetDocumentApi( "D1" , "P1" );

if(doc)
doc.ShowAllViews();
doc.Refresh();
end

return AS::API::Share::ASAPI_RETURNS.NORMAL_PROCESSING

Famic Technologies Inc. 7-181

Automation Studio™ – API and Scripting Language

7.6.2.28 bool ShowLayers (string szLayersList,bool bToShow)

This method shows the set of layers supplied in the layer list szLayerList.

Parameters:

szLayersList This list is a string of layer names separated by commas.

bToShow true: turn the layer visibility on.

False: turn the layer visibility off.

Returns:

bool Valid layer names where supplied to the process.

Example:

7-182
 API Reference Manual
#------------------------------------------------------------
# Name of File::DocShowLayers.rb
#
# Purpose::
# This search for all documents currently loaded and
# shows/hides any layers found that match the supplied list.
#------------------------------------------------------------
require "AS.API.Share"

iCnt = applicationApi.GetChildCount(1);
i = 0
until i == iCnt
prj = applicationApi.GetNthChild(i, 1);
iCnt2 = prj.GetChildCount(2);
j = 0
until j == iCnt2
doc = prj.GetNthChild(j, 2);
doc.ShowLayers("Default Layer,Layer 2,Layer 4",true);
j += 1
end
i += 1
end

return AS::API::Share::ASAPI_RETURNS.NORMAL_PROCESSING

Famic Technologies Inc. 7-183

Automation Studio™ – API and Scripting Language

7.6.2.29 bool ShowView(string szViewsList,SHOW_TYPE type)

Show the set of views supplied in the list.

Parameters:

szViewsList String of views to be shown. Uses the following format:

<First View>[:M<Any additional views>]

The prefix “View” is not mandatory.

type SHOW_TYPE.SHOW (optionial: default is SHOW), Indicates to

show the views instead of hiding them (false):
 SHOW_TYPE.HIDE
 SHOW_TYPE.SHOW
 SHOW_TYPE.HIDE_ALL
 SHOW_TYPE.SHOW_ALL
 SHOW_TYPE.MAXIMIZE
 SHOW_TYPE.MINIMIZE
 SHOW_TYPE.NORMAL

Returns:

bool The views where shown.

Example:

7-184
 API Reference Manual
#------------------------------------------------------------
# Name of File::DocShowView.rb
#
# Purpose::
# This search for a loaded project called AppSelectViews
# that contains at least the document D2 and the views
# view1 and view2 and brings them to the foreground.
#------------------------------------------------------------
require "AS.API.Share"

doc = applicationApi.GetDocumentApi( "D1" , "P1" );

if(doc)
showType = AS::API::Share::SHOW_TYPE.SHOW;
doc.ShowView("View2", showType);
doc.Refresh();
end
return AS::API::Share::ASAPI_RETURNS.NORMAL_PROCESSING

Famic Technologies Inc. 7-185

Automation Studio™ – API and Scripting Language

7.6.2.30 bool ShowViews (string szViewsList, bool bShow)

Show the set of views supplied in the list.

Parameters:

szViewsList String of views to be shown. Uses the following format

<First View>[:M<Any additional views>]

The prefix “View” is not mandatory.

bShow True (optionial: default), Indicates to show the views instead

of hiding them (false).

Returns:

bool The views where shown.

Example:
#------------------------------------------------------------
# Name of File::DocShowViews.rb
#
# Purpose::
# This search for a loaded project called AppSelectViews
# that contains at least the document D2 and the views
# view1 and view2 and brings them to the foreground.
#------------------------------------------------------------
require "AS.API.Share"

doc = applicationApi.GetDocumentApi( "D1" , "P1" );

if(doc)
doc.ShowViews("View1:View2");
doc.ShowViews("View3:View4",false);
doc.Refresh();
end
return AS::API::Share::ASAPI_RETURNS.NORMAL_PROCESSING

7-186
 API Reference Manual

7.6.2.31 bool Zoom(…)

A set of methods to defined the space used by the documents primary view. The units
used will be dependent on the base drawing units of the document. If the display uses
cm the base drawing unit is 1/10 of a millimeter.

bool Zoom(int left, int top, int right, int bottom)

or

bool Zoom(Point minPt, Point maxPt)

or

bool Zoom(IComponentApi cmpObj)

or

bool Zoom(List <ComponentApi> cmpObjs)

Parameters:

left Left most X position to fit into the zoom frame.

top Top most Y position to fit into the zoom frame.

right Right most X position to fit into the zoom frame.

bottom Bottom most Y position to fit into the zoom frame.

minPt Smallest co-ordinate to fit into the zoom frame.

maxPt Largest co-ordinate to fit into the zoom frame.

cmpObj Fit the view to use the bounding box of the provided

Famic Technologies Inc. 7-187

Automation Studio™ – API and Scripting Language

component.

cmpObjs Fit the view to use the bounding box of the provided
component list.

Returns:

bool Indicates success.

Example:
#------------------------------------------------------------
# Name of File::DocZoom.rb
#
# Purpose::
# Demonstartes the views methods related to zooming.
# Expects in memory
# A project with the name ViewZoom.prx
# A component with the name "PPO1"
#------------------------------------------------------------
require "AS.API.Share"
require 'System.Drawing,
Version=2.0.0.0, Culture=neutral,
PublicKeyToken=b03f5f7f11d50a3a'

pt1 = System::Drawing::Point.new;
pt2 = System::Drawing::Point.new;

prj = applicationApi.GetProjectApi( "P1" );

cmp = prj.GetComponent( "REC1" );
# Find the size and location of the component for the zoom
if(cmp)
loc = cmp.GetLocation();
size = cmp.GetSize();
# Calculate the zoom frame around the component
pt1.X = loc.X - 10;
pt1.Y = loc.Y - 10;
pt2.X = loc.X + size.Width + 10;
pt2.Y = loc.Y + size.Height + 10;
# Zoom the first frame using left, top, right, bottom
doc = applicationApi.GetDocumentApi("ViewZoom","P1");
if(doc)
doc.Zoom(pt1, pt2);

7-188
 API Reference Manual
end
end
return AS::API::Share::ASAPI_RETURNS.NORMAL_PROCESSING

Famic Technologies Inc. 7-189

Automation Studio™ – API and Scripting Language

7.6.2.32 bool ZoomExtents()

This method fits all document components into the documents primary views frame.

Parameters:

NIL No parameters will be set.

Returns:

bool Indicates success

Example:
#------------------------------------------------------------
# Name of File::DocZoomExtents.rb
#
# Purpose::
# Demonstrates how to use the documents method ZoomExtents
#------------------------------------------------------------
require "AS.API.Share"

viewApi = AS::API::Share::ASAPI_OBJ.VIEW_API;

doc = applicationApi.GetDocumentApi( "D1" , "P1" );

if(doc)
doc.ZoomExtents();
end

return AS::API::Share::ASAPI_RETURNS.NORMAL_PROCESSING

7-190
 API Reference Manual

7.7 Component

This method is used to access the attributes that are managed by a view.

7.7.1 Access to the Component identifier

To access an instance of a component the following call can be used.

int GetBaseId();

This method returns the identifier of the object that generated the event. If this was not
a component the identifier returned will not work. A component will exist if a component
or a child or grandchild initiated the event.

The second method to find a view is to navigate through the view children of a
document.
nCnt = documentApi.GetChildCount(asTid.COMPONENT_API);
nIdx = 0
while (nIdx < nCnt) do
obj = documentApi.GetNthChild(nIdx,
asTid.COMPONENT_API);
… # Then you use the component object returned.
nIdx += 1
end

Famic Technologies Inc. 7-191

Automation Studio™ – API and Scripting Language

7.7.2 Methods

Methods that can be called from a Component.

7.7.2.1 bool Flip(bool bHorizontal)

Flips the object end to end or top to bottom.

Parameters:

bHorizontal When set to true the object will be flipped end to end
otherwise the component will be flipped top to bottom.

Returns:

bool true success false failure

Example:
#------------------------------------------------------------
# Name of File::CmpFlip.rb
#
# Purpose::
# Demonstrates the two methods of flipping an objects
#------------------------------------------------------------
require "AS.API.Share"

prj = applicationApi.GetProjectApi( "P1" );

# Find the size and location of the component for the zoom
if(prj)
cmp = prj.GetComponent( "PPO1" );
if(cmp)
cmp.Flip(true);
end
cmp = prj.GetComponent( "PPO2" );
if(cmp)
cmp.Flip(false);
end
end

7-192
 API Reference Manual
applicationApi.Refresh();
return AS::API::Share::ASAPI_RETURNS.NORMAL_PROCESSING

7.7.2.2 float GetAngle(bool bDegrees)

This returns how much the component has been rotated.

Parameters:

bDegrees Return a value in degrees, otherwise radians.

Returns:

float Current amount this component has been rotated in degrees or

radians.

Example:
#------------------------------------------------------------
# Name of File::CmpAngle.rb
#
# Purpose:: Demonstrates rotating an object using degrees
# or radians.
#------------------------------------------------------------
require "AS.API.Share"
prj = applicationApi.GetProjectApi( "P1" );
if(prj)
cmp = prj.GetComponent( "PPO1" );
if(cmp)
angle = cmp.GetAngle();
if (angle < 40)
cmp.SetAngle(45);
else
cmp.SetAngle(0);
end
end
end
applicationApi.Refresh();
return AS::API::Share::ASAPI_RETURNS.NORMAL_PROCESSING

Famic Technologies Inc. 7-193

Automation Studio™ – API and Scripting Language

7.7.2.3 Point GetAnchor();

This method is used to get the point in a graphical primitive that is used to lined it up
within a display. A symbol will have its own drawing coordinates, this defines the point
in that system that will be used when the object is moved.

Parameters:

NIL No parameters will be set.

Returns:

Point Position in the symbol coordinate system that will line up with
the insertion point within the display.

Example:
#------------------------------------------------------------
# Name of File::CmpGetAnchor.rb
#
# Purpose:: Get the anchor on the component.
#------------------------------------------------------------
require "AS.API.Share"
applicationApi.ChangeAllLogOutputs(AS::API::Share::LOGTYPE.AS_MESSAGE_SYSTEM);
prj = applicationApi.GetProjectApi( "P1" );
strOut = "Anchor found = [";
if(prj)
cmp = prj.GetComponent( "H1" );
if(cmp)
ptValue = cmp.GetAnchor();
strOut << ptValue.to_s; strOut << "]";
end
end
applicationApi.LogScriptInformation(strOut,false);
return AS::API::Share::ASAPI_RETURNS.NORMAL_PROCESSING

7-194
 API Reference Manual

7.7.2.4 Point GetRotationCenter();

This method is used to get the point within a graphical primitive’s coordinate system that
is used when it is rotated. A symbol will have its own drawing coordinates, this defines
the point in that system that will be used when the object is rotated.

Parameters:

NIL No parameters will be set.

Returns:

Point Position in the symbol coordinate system that will be its center
of rotation.

Example:
#------------------------------------------------------------
# Name of File::CmpGetRotationCenter.rb
#
# Purpose:: Get center point to rotate the object arount.
#------------------------------------------------------------
require "AS.API.Share"
applicationApi.ChangeAllLogOutputs(AS::API::Share::LOGTYPE.AS_MESSAGE_SYSTEM);

prj = applicationApi.GetCurrentProject();
strOut = "Center of rotation found at = [";
cmp = prj.GetComponent( "H1" );
ptValue = cmp.GetRotationCenter();
strOut << ptValue.to_s; strOut << "]";

applicationApi.LogScriptInformation(strOut,false);
return AS::API::Share::ASAPI_RETURNS.NORMAL_PROCESSING

Famic Technologies Inc. 7-195

Automation Studio™ – API and Scripting Language

7.7.2.5 int GetBackGroundColor()

This method returns the background color of the component using an RGB value between
the hexadecimal value 0x00 to 0x00FFFFFF.

Parameters:

NIL No parameters will be set.

Returns:

int RGB value of the component. value between 0x00 to

0x00FFFFFF.

Example:
#------------------------------------------------------------
# Name of File::CmpColor.rb
#
# Purpose:: Moves the different colors between the
# different color attributes on the object. This script
# expects an object PPO1 with different colors on
# each attribute, color, foreground and background.
#------------------------------------------------------------
require "AS.API.Share"
prj = applicationApi.GetProjectApi( "P1" );
if(prj)
cmp = prj.GetComponent( "PPO1" );
if(cmp)
rgbBgColor = cmp.GetBackgroundColor();
cmp.SetForegroundColor(rgbBgColor);
rgbColor = cmp.GetColor();
cmp.SetBackgroundColor(rgbColor);
rgbFColor = cmp.GetForegroundColor();
cmp.SetForegroundColor(rgbFColor);
end
end
applicationApi.Refresh();
return AS::API::Share::ASAPI_RETURNS.NORMAL_PROCESSING

7-196
 API Reference Manual

7.7.2.6 int GetColor()

This method returns the color of the component using an RGB value between the
hexadecimal value 0x00 to 0x00FFFFFF.

Parameters:

NIL No parameters will be set.

Returns:

int RGB value of the components color. value between 0x00 to

0x00FFFFFF.

Example:
#------------------------------------------------------------
# Name of File::CmpColor.rb
#
# Purpose:: Moves the different colors between the
# different color attributes on the object. This script
# expects an object PPO1 with different colors on
# each attribute, color, foreground and background.
#------------------------------------------------------------
require "AS.API.Share"
prj = applicationApi.GetProjectApi( "P1" );
if(prj)
cmp = prj.GetComponent( "PPO1" );
if(cmp)
rgbBgColor = cmp.GetBackgroundColor();
cmp.SetForegroundColor(rgbBgColor);
rgbColor = cmp.GetColor();
cmp.SetBackgroundColor(rgbColor);
rgbFColor = cmp.GetForegroundColor();
cmp.SetForegroundColor(rgbFColor);
end
end
applicationApi.Refresh();
return AS::API::Share::ASAPI_RETURNS.NORMAL_PROCESSING

Famic Technologies Inc. 7-197

Automation Studio™ – API and Scripting Language

7.7.2.7 Point GetDocRelativePortPosition(int portNumber)

This method is used to return the position relative to the document of the port indicated.

Parameters:

portNumber The number of the port required.

Returns:

Point Returns current location of the port relative to the document.

Example:
#------------------------------------------------------------
# Name of File::CmpGetDocRelativePortPosition.rb
#
# Purpose:: Print out the position of all ports existing on
# the component "H1" relative to to their document.
#------------------------------------------------------------
require "AS.API.Share"
applicationApi.ChangeAllLogOutputs(
AS::API::Share::LOGTYPE.AS_MESSAGE_SYSTEM);
prj = applicationApi.GetProjectApi( "P1" );
strOut = "["; i = 0;
if(prj)
cmp = prj.GetComponent( "H1" );
if(cmp)
ptNum = cmp.GetNumberOfPorts();
while (i< ptNum)
ptValue = cmp.GetDocRelativePortPosition(i+1);
i += 1; strOut << "Port["; strOut << i.to_s;
strOut << "]="; strOut << ptValue.to_s; strOut << " : ";
end
end
end
applicationApi.LogScriptInformation(strOut,false);
return AS::API::Share::ASAPI_RETURNS.NORMAL_PROCESSING

7-198
 API Reference Manual

7.7.2.8 int GetNumberOfPorts()

This method is used to return the number of ports that exist on the component.

Parameters:

NIL No parameters will be set.

Returns:

int Returns the number of ports on the component.

Example:
#------------------------------------------------------------
# Name of File::CmpGetNumberOfPorts.rb
#
# Purpose:: Gets the number of ports that exist on the
# component "H2" in the current project.
#------------------------------------------------------------
require "AS.API.Share"
applicationApi.ChangeAllLogOutputs(
AS::API::Share::LOGTYPE.AS_MESSAGE_SYSTEM);
prj = applicationApi.GetCurrentProject();
strOut = "[ Number of ports = "; i = 0;
if(prj)
cmp = prj.GetComponent( "H2" );
if(cmp)
ptNum = cmp.GetNumberOfPorts();
strOut << ptNum.to_s; strOut << " ] : ";
while (i< ptNum)
ptValue = cmp.GetDocRelativePortPosition(i+1);
i += 1; strOut << "Port["; strOut << i.to_s;
strOut << "]="; strOut << ptValue.X.to_s;
end
end
end
applicationApi.LogScriptInformation(strOut,false);
return AS::API::Share::ASAPI_RETURNS.NORMAL_PROCESSING

Famic Technologies Inc. 7-199

Automation Studio™ – API and Scripting Language

7.7.2.9 string GetPortName(int portNumber)

This method is used to return the display name of the port provided.

Parameters:

portNumber The number of the port required.

Returns:

string Returns the name of the port found.

Example:
#------------------------------------------------------------
# Name of File::CmpGetPortName.rb
#
# Purpose:: Get one of the port names found on the component.
#------------------------------------------------------------
require "AS.API.Share"
applicationApi.ChangeAllLogOutputs(AS::API::Share::LOGTYPE.AS_MESSAGE_SYSTEM);
prj = applicationApi.GetCurrentProject();
strOut = "Port Name found = [";
if(prj)
cmp = prj.GetComponent( "H1" );
if(cmp)
ptValue = cmp.GetPortName(2);
strOut << ptValue.to_s; strOut << "]";
end
end
applicationApi.LogScriptInformation(strOut,false);
return AS::API::Share::ASAPI_RETURNS.NORMAL_PROCESSING

7-200
 API Reference Manual

7.7.2.10 Point GetPortPosition(int portNumber)

This method is used to return the position of the port indicated relative to the
component.

Parameters:

portNumber The number of the port required.

Returns:

Point Returns current location of the port relative to the component.

Example:
#------------------------------------------------------------
# Name of File::CmpGetPortPosition.rb
#
# Purpose:: Print out the position of all ports on a
# component
#------------------------------------------------------------
require "AS.API.Share"
applicationApi.ChangeAllLogOutputs(
AS::API::Share::LOGTYPE.AS_MESSAGE_SYSTEM);
prj = applicationApi.GetCurrentProject();
strOut = "["; i = 0;
if(prj)
cmp = prj.GetComponent( "H1" );
if(cmp)
ptNum = cmp.GetNumberOfPorts();
while (i< ptNum)
ptValue = cmp.GetPortPosition(i+1);
i += 1; strOut << "Port["; strOut << i.to_s;
strOut << "]="; strOut << ptValue.to_s; strOut << " : ";
end
end
end
applicationApi.LogScriptInformation(strOut,false);
return AS::API::Share::ASAPI_RETURNS.NORMAL_PROCESSING

Famic Technologies Inc. 7-201

Automation Studio™ – API and Scripting Language

7.7.2.11 int GetForgroundColor()

This method returns the foreground color of the component using an RGB value between
the hexadecimal value 0x00 to 0x00FFFFFF.

Parameters:

NIL No parameters will be set.

Returns:

int RGB value of the components foreground color. a value

between 0x00 to 0x00FFFFFF

Example:
#------------------------------------------------------------
# Name of File::CmpColor.rb
#
# Purpose:: Moves the different colors between the
# different color attributes on the object. This script
# expects an object PPO1 with different colors on
# each attribute, color, foreground and background.
#------------------------------------------------------------
require "AS.API.Share"
prj = applicationApi.GetProjectApi( "P1" );
if(prj)
cmp = prj.GetComponent( "PPO1" );
if(cmp)
rgbBgColor = cmp.GetBackgroundColor();
cmp.SetForegroundColor(rgbBgColor);
rgbColor = cmp.GetColor();
cmp.SetBackgroundColor(rgbColor);
rgbFColor = cmp.GetForegroundColor();
cmp.SetForegroundColor(rgbFColor);
end
end
applicationApi.Refresh();
return AS::API::Share::ASAPI_RETURNS.NORMAL_PROCESSING

7-202
 API Reference Manual

7.7.2.12 string GetLayerName()

This method returns the name of the layer used by the component.

Parameters:

NIL No parameters will be set.

Returns:

string The name of the layer used by the component.

Example:
#------------------------------------------------------------
# Name of File::CmpGetLayerName.rb
#
# Purpose:: Gets the layer of the current component PPO1
#------------------------------------------------------------
require "AS.API.Share"

prj = applicationApi.GetProjectApi( "P1" );

if(prj)
cmp = prj.GetComponent( "PPO1" );
if(cmp)
layerName = cmp.GetLayerName();
cmp.LogScriptInformation(layerName,false);
end
end
applicationApi.Refresh();
return AS::API::Share::ASAPI_RETURNS.NORMAL_PROCESSING

Famic Technologies Inc. 7-203

Automation Studio™ – API and Scripting Language

7.7.2.13 int GetLineStyle()

This method returns the linestyle currently used. The linestyle is an index into a table of
linestyles supported by Automation Studio™.

Parameters:

NIL No parameters will be set.

Returns:

int Index to the linestyle used by the component.

Example:
#----------------------------------------------------------
# Name of File::CmpGetLineStyle.rb
#
# Purpose: Displays the linestyle used by component “POL1”
#----------------------------------------------------------
require "AS.API.Share"

prj = applicationApi.GetProjectApi( "P1" );

if(prj)
cmp = prj.GetComponent( "POL1" );
if(cmp)
linestyle = cmp.GetLineStyle();
cmp.LogScriptInformation(linestyle.to_s,false);
end
end
applicationApi.Refresh();
return AS::API::Share::ASAPI_RETURNS.NORMAL_PROCESSING

7-204
 API Reference Manual

7.7.2.14 int GetLineWidth()

This method returns index to the components line width. The return value is an index
into a table of widths supported by Automation Studio ™.

Parameters:

NIL No parameters will be set.

Returns:

int Index to the components line width.

Example:
#----------------------------------------------------------
# Name of File::CmpLineWidth.rb
#
# Purpose: Changes the line width used by the component
# “PPO1”
#----------------------------------------------------------
require "AS.API.Share"

prj = applicationApi.GetProjectApi( "P1" );

if(prj)
cmp = prj.GetComponent( "POL1" );
if(cmp)
iCnt = cmp.GetLineWidth();
if(iCnt == 20)
iCnt = 1
else
iCnt += 1
end
cmp.SetLineWidth(iCnt);
end
end
applicationApi.Refresh();
return AS::API::Share::ASAPI_RETURNS.NORMAL_PROCESSING

Famic Technologies Inc. 7-205

Automation Studio™ – API and Scripting Language

7.7.2.15 Point GetLocation()

This method provides the insertion point of the component.

Parameters:

NIL No parameters will be set.

Returns:

Point Current location of the object using the project base units, in
th
the case metric this is 1/10 of a mm.

Example:
#------------------------------------------------------------
# Name of File::CmpGetLocation.rb
#
# Purpose::
# Demonstrates the use of the components GetLocation method.
#------------------------------------------------------------
require "AS.API.Share"

prj = applicationApi.GetProjectApi("P1" );
doc = applicationApi.GetDocumentApi( "D1" , "P1" );

if(prj && doc)

cmp = prj.GetComponent( "REC1" );
if (cmp)
pt = cmp.GetLocation();
doc.Zoom((pt.x-300),(pt.y-300),
(pt.x+300),(pt.y+300));
end
end

return AS::API::Share::ASAPI_RETURNS.NORMAL_PROCESSING

7-206
 API Reference Manual

7.7.2.16 int GetPatternFill()

Returns the pattern currently used by the component. The pattern is an index into a table
of patterns supported by Automation Studio ™.

Parameters:

NIL No parameters will be set.

Returns:

int Index to the pattern used by the component.

Example:
#----------------------------------------------------------
# Name of File::CmpGetPatternFill.rb
#
# Purpose: Changes the pattern used by the component “PPO1”
#----------------------------------------------------------
require "AS.API.Share"

prj = applicationApi.GetProjectApi( "P1" );

if(prj)
cmp = prj.GetComponent( "PPO1" );
if(cmp)
iCnt = cmp.GetPatternFill();
if(iCnt == 50)
iCnt = 1
else
iCnt += 1
end
cmp.SetPatternFill(iCnt);
end
end
applicationApi.Refresh();
return AS::API::Share::ASAPI_RETURNS.NORMAL_PROCESSING

Famic Technologies Inc. 7-207

Automation Studio™ – API and Scripting Language

7.7.2.17 Point GetRotationCenter();

This method is used to ges the point within a graphical primitive’s coordinate system that
is used when it is rotated. A symbol will have its own drawing coordinates, this defines
the point in that system that will be used when the object is rotated.

Parameters:

NIL No parameters will be set.

Returns:

Point Position in the symbol coordinate system that will be its center
of rotation.

Example:
#------------------------------------------------------------
# Name of File::CmpGetRotationCenter.rb
#
# Purpose:: Get center point to rotate the object arount.
#------------------------------------------------------------
require "AS.API.Share"
applicationApi.ChangeAllLogOutputs(AS::API::Share::LOGTYPE.AS_MESSAGE_SYSTEM);

prj = applicationApi.GetCurrentProject();
strOut = "Center of rotation found at = [";
cmp = prj.GetComponent( "H1" );
ptValue = cmp.GetRotationCenter();
strOut << ptValue.to_s; strOut << "]";

applicationApi.LogScriptInformation(strOut,false);
return AS::API::Share::ASAPI_RETURNS.NORMAL_PROCESSING

7-208
 API Reference Manual

7.7.2.18 Point GetScale()

This method provides the current scale on the component. Scale is represented as the X
and the Y scale of the object returned in a point.

Parameters:

NIL No parameters will be set.

Returns:

Point Current scale on the width and the height.

Example:
#------------------------------------------------------------
# Name of File::CmpScale.rb
#
# Purpose::
# Demonstartes scaling an object "DAO7"
#------------------------------------------------------------
require "AS.API.Share"

prj = applicationApi.GetProjectApi( "P1" );

cmp = prj.GetComponent( "PPO1" );
# Find the size and location of the component for the zoom
if(cmp)
scale = cmp.GetScale();
if(scale.X != 2.0)
cmp.SetScale(2.0);
else
cmp.SetScale(1.0);
end
end
applicationApi.Refresh();
return AS::API::Share::ASAPI_RETURNS.NORMAL_PROCESSING

Famic Technologies Inc. 7-209

Automation Studio™ – API and Scripting Language

7.7.2.19 Size GetSize()

This method provides the original size in base units of the component. The size of the
object in the image will also be affected by its scale and rotation.

Parameters:

NIL No parameters will be set.

Returns:

Size Current size of the object using the project base units, in the
th
case metric this is 1/10 of a mm.

Example:
#------------------------------------------------------------
# Name of File::CmpGetSize.rb
#
# Purpose::
# Demonstartes the components method GetSize.
# Expects in memory a component with the name "PPO1"
#------------------------------------------------------------
require "AS.API.Share"
prj = applicationApi.GetProjectApi( "P1" );
if(prj)
cmp = prj.GetComponent( "PPO1" );
# Find the size and location of the component for the zoom
if(cmp)
loc = cmp.GetLocation();
size = cmp.GetSize();
# Calculate the zoom frame around the component
Xmin = loc.X - 10;
Ymin = loc.Y - 10;
Xmax = loc.X + size.Width + 10;
Ymax = loc.Y + size.Height + 10;
doc = prj.GetDocumentApi( "D1" );
if(doc)
doc.Zoom(Xmin,Ymin,Xmax,Ymax);
end
end

7-210
 API Reference Manual
end
return AS::API::Share::ASAPI_RETURNS.NORMAL_PROCESSING

Famic Technologies Inc. 7-211

Automation Studio™ – API and Scripting Language

7.7.2.20 string GetText()

This method returns the text used by the component.

Parameters:

NIL No parameters will be set.

Returns:

string The text used by the component.

Example:
#------------------------------------------------------------
# Name of File::CmpGetText.rb
#
# Purpose:: Displays the text found on the component TXT1
#-
#------------------------------------------------------------
require "AS.API.Share"

prj = applicationApi.GetProjectApi( "P1" );

if(prj)
cmp = prj.GetComponent( "TXT1" );
if(cmp)
textStr = cmp.GetText();
cmp.LogScriptInformation(textStr,false);
end
end
applicationApi.Refresh();
return AS::API::Share::ASAPI_RETURNS.NORMAL_PROCESSING

7-212
 API Reference Manual

7.7.2.21 Size Duplicate(IProjectApi prj, IDocumentApi doc, Point pt)

This method provides the current size of the component.

Parameters:

prj Project to copy the object to.

doc Document to copy the object to.

pt Point to place the copy

Returns:

Size

Example:
#------------------------------------------------------------
# Name of File: CmpDuplicate.rb
#
# Purpose::
# This will copy a component and add it to the current doc.
#------------------------------------------------------------
require "AS.API.Share"

objType = AS::API::Share::ASAPI_OBJ.DOCUMENT_API;
prj = applicationApi.GetProjectApi( "P1" );
if(prj)
#Retrieve component with id
cmp =prj.GetComponent( "REC1" );
if(cmp)
#Retrieve parent document of component
parent = cmp.GetParent(objType);

if(parent)
#Retrieve offset values
xOffset = 100;

Famic Technologies Inc. 7-213

Automation Studio™ – API and Scripting Language
yOffset = 100;
#Calculate new component position
location = cmp.GetLocation();
location.Offset(xOffset, yOffset);
#Duplicate component on specified diagram
#at specified position
cmp.Duplicate(prj, parent, location);
end
end
end

applicationApi.Refresh();
return AS::API::Share::ASAPI_RETURNS.NORMAL_PROCESSING

7-214
 API Reference Manual

7.7.2.22 bool MoveTo(Point newPos)

This method moves the object to the point supplied. This uses base display co-ordinates.
This expects the object to be refreshed before the attribute is visible.

Parameters:

newPos New position to move the object to.

Returns:

bool true success false failure

Example:
#------------------------------------------------------------
# Name of File::CmpMoveTo.rb
#
# Purpose:: Moves the component DAO4
#-
#------------------------------------------------------------
require "AS.API.Share"
require 'System.Drawing,
Version=2.0.0.0, Culture=neutral,
PublicKeyToken=b03f5f7f11d50a3a'

prj = applicationApi.GetProjectApi( "P1" );

if(prj)
cmp = prj.GetComponent( "PPO1" );
if(cmp)
ptOrg = System::Drawing::Point.new;
ptOrg.X = 700;
ptOrg.Y = 700;
cmp.MoveTo(ptOrg); end
end

applicationApi.Refresh();
return AS::API::Share::ASAPI_RETURNS.NORMAL_PROCESSING

Famic Technologies Inc. 7-215

Automation Studio™ – API and Scripting Language

7.7.2.23 bool MoveRelativeToPort(int portNumber,Point portLocation);

This method moves the current component to a point in the document which will line up
with the port indicated. This method is expecting Automation Studio™ coordinates.

Parameters:

PortNumber The port number that will line up with the location in the
document provided. These numbers go from 1 to n.

Use bool GetPortNumber(string portName) inorder to get the

port number if you only know the display name of the port.

portLocation The location to move the components port to.

Returns:

bool True is returned if an error did not occur.

Example:
#------------------------------------------------------------
# Name of File::CmpMoveRelativeToPort.rb
#
# Purpose:: Move the component so that the indicated port
# lines up with the point in the display provided.
#------------------------------------------------------------
require "AS.API.Share"
require 'System.Drawing,
Version=2.0.0.0, Culture=neutral,
PublicKeyToken=b03f5f7f11d50a3a'
applicationApi.ChangeAllLogOutputs(AS::API::Share::LOGTYPE.AS_MESSAGE_SYSTEM);
prj = applicationApi.GetCurrentProject();
if(prj)
cmp = prj.GetComponent( "H3" );
if(cmp)
ptOrgNew = System::Drawing::Point.new;
ptOrgNew.X = 950; ptOrgNew.Y = 1100;
ptNum = cmp.GetPortNumber("A");

7-216
 API Reference Manual
# Now move the component so that port B lines
# up with the point 850, 1000
cmp.MoveRelativeToPort(ptNum, ptOrgNew);

ptPortPos = cmp.GetDocRelativePortPosition(ptNum);
ptOrg = cmp.GetPosition();
strOut = "Position ="; strOut << ptOrg.to_s;
strOut << "\nPort ="; strOut << ptPortPos.to_s;
applicationApi.LogScriptInformation(strOut,false);

applicationApi.Refresh();
end
end
return AS::API::Share::ASAPI_RETURNS.NORMAL_PROCESSING

Famic Technologies Inc. 7-217

Automation Studio™ – API and Scripting Language

7.7.2.24 bool SetAngle(float angle,bool bDegrees)

This will rotate the component to the angle specified in relation to the insertion point
using either degrees or radians.

Parameters:

angle The component will be rotated by this angle.

bDegrees True indicates the angle will be in degrees, false indicates an

angle in radians.

Returns:

bool True indicates success.

Example:
#------------------------------------------------------------
# Name of File::CmpAngle.rb
#
# Purpose:: Demonstrates rotating an object using degrees
# or radians.
#------------------------------------------------------------
require "AS.API.Share"
prj = applicationApi.GetProjectApi( "P1" );
if(prj)
cmp = prj.GetComponent( "PPO1" );
if(cmp)
angle = cmp.GetAngle();
if (angle < 40)
cmp.SetAngle(45);
else
cmp.SetAngle(0);
end
end
end
applicationApi.Refresh();
return AS::API::Share::ASAPI_RETURNS.NORMAL_PROCESSING

7-218
 API Reference Manual

Famic Technologies Inc. 7-219

Automation Studio™ – API and Scripting Language

7.7.2.25 bool SetBackGroundColor(int iRgbValue)

This method sets the background color of the component using an RGB value between
the hexadecimal value 0x00 to 0x00FFFFFF.

Parameters:

iRgbValue A RGB color value between 0 and 0x00FFFFFF.

Returns:

bool True indicates success.

Example:
#------------------------------------------------------------
# Name of File::CmpColor.rb
#
# Purpose:: Moves the different colors between the
# different color attributes on the object. This script
# expects an object PPO1 with different colors on
# each attribute, color, foreground and background.
#------------------------------------------------------------
require "AS.API.Share"
prj = applicationApi.GetProjectApi( "P1" );
if(prj)
cmp = prj.GetComponent( "PPO1" );
if(cmp)
rgbBgColor = cmp.GetBackgroundColor();
cmp.SetForegroundColor(rgbBgColor);
rgbColor = cmp.GetColor();
cmp.SetBackgroundColor(rgbColor);
rgbFColor = cmp.GetForegroundColor();
cmp.SetForegroundColor(rgbFColor);
end
end
applicationApi.Refresh();
return AS::API::Share::ASAPI_RETURNS.NORMAL_PROCESSING

7-220
 API Reference Manual

7.7.2.26 bool SetColor(int iRgbValue)

This method sets the color of the component using an RGB value between the
hexadecimal value 0x00 to 0x00FFFFFF.

Parameters:

iRgbValue A RGB color value between 0 and 0x00FFFFFF.

Returns:

bool True indicates success.

Example:
#------------------------------------------------------------
# Name of File::CmpColor.rb
#
# Purpose:: Moves the different colors between the
# different color attributes on the object. This script
# expects an object PPO1 with different colors on
# each attribute, color, foreground and background.
#------------------------------------------------------------
require "AS.API.Share"
prj = applicationApi.GetProjectApi( "P1" );
if(prj)
cmp = prj.GetComponent( "PPO1" );
if(cmp)
rgbBgColor = cmp.GetBackgroundColor();
cmp.SetForegroundColor(rgbBgColor);
rgbColor = cmp.GetColor();
cmp.SetBackgroundColor(rgbColor);
rgbFColor = cmp.GetForegroundColor();
cmp.SetForegroundColor(rgbFColor);
end
end
applicationApi.Refresh();
return AS::API::Share::ASAPI_RETURNS.NORMAL_PROCESSING

Famic Technologies Inc. 7-221

Automation Studio™ – API and Scripting Language

7.7.2.27 bool SetForgroundColor(int iRgbValue)

This method sets the foreground color of the component using an RGB value between
the hexadecimal value 0x00 to 0x00FFFFFF.

Parameters:

iRgbValue A RGB color value between 0 and 0x00FFFFFF.

Returns:

bool True indicates success.

Example:
#------------------------------------------------------------
# Name of File::CmpColor.rb
#
# Purpose:: Moves the different colors between the
# different color attributes on the object. This script
# expects an object PPO1 with different colors on
# each attribute, color, foreground and background.
#------------------------------------------------------------
require "AS.API.Share"
prj = applicationApi.GetProjectApi( "P1" );
if(prj)
cmp = prj.GetComponent( "PPO1" );
if(cmp)
rgbBgColor = cmp.GetBackgroundColor();
cmp.SetForegroundColor(rgbBgColor);
rgbColor = cmp.GetColor();
cmp.SetBackgroundColor(rgbColor);
rgbFColor = cmp.GetForegroundColor();
cmp.SetForegroundColor(rgbFColor);
end
end
applicationApi.Refresh();
return AS::API::Share::ASAPI_RETURNS.NORMAL_PROCESSING

7-222
 API Reference Manual

7.7.2.28 bool SetLayerByName(string layerName)

This method moves the object to the layer specified by the parameter layerName. This
expects the object to be refreshed before the attribute is visible.

It is considered an error if the layer does not exist.

Parameters:

layerName The name of the layer to move the object to.

Returns:

bool true success false failure

Example:
#------------------------------------------------------------
# Name of File::CmpSetLayerByName.rb
#
# Purpose:: Moves the object to a different layer #-
#------------------------------------------------------------
require "AS.API.Share"
prj = applicationApi.GetProjectApi( "P1" );
if(prj)
cmp = prj.GetComponent( "PPO1" );
if(cmp)
cmp.SetLayerByName( "Layer 1" );
end
end
applicationApi.Refresh();
return AS::API::Share::ASAPI_RETURNS.NORMAL_PROCESSING

Famic Technologies Inc. 7-223

Automation Studio™ – API and Scripting Language

7.7.2.29 bool SetLineStyle(int lineStyle)

This sets the linestyle used by the component.

Parameters:

lineStyle The line style to use. The linestyle is a table of styles used by
Automation Studio™.

Returns:

bool true success false failure

Example:
#------------------------------------------------------------
# Name of File::CmpSetLineStyle.rb
#
# Purpose: Changes the linestyle of component PP01
#-#----------------------------------------------------------
require "AS.API.Share"
prj = applicationApi.GetProjectApi( "P1" );
if(prj)
cmp = prj.GetComponent( "PPO1" );
if(cmp)
fontName = cmp.SetLineStyle(8);
end
end
applicationApi.Refresh();
return AS::API::Share::ASAPI_RETURNS.NORMAL_PROCESSING

7-224
 API Reference Manual

7.7.2.30 bool SetLineWidth(int idxWidth)

Sets the width to be used by the component. The idxWidth value is an index into a table
of widths supported by Automation Studio™. This expects the object to be refreshed
before the attribute is visible.

Parameters:

idxWidth The index to the width to be used by the composite.

Returns:

bool true success false failure

Example:
#----------------------------------------------------------
# Name of File::CmpLineWidth.rb
#
# Purpose: Changes the line width used by the component
# “PPO1”
#----------------------------------------------------------
require "AS.API.Share"

prj = applicationApi.GetProjectApi( "P1" );

if(prj)
cmp = prj.GetComponent( "POL1" );
if(cmp)
iCnt = cmp.GetLineWidth();
if(iCnt == 20)
iCnt = 1
else
iCnt += 1
end
cmp.SetLineWidth(iCnt);
end
end
applicationApi.Refresh();
return AS::API::Share::ASAPI_RETURNS.NORMAL_PROCESSING

Famic Technologies Inc. 7-225

Automation Studio™ – API and Scripting Language

7.7.2.31 bool SetText(string text)

This method sets the text used by the component. This expects the object to be
refreshed before the attribute is visible.

Parameters:

text The text to be used by the component.

Returns:

bool true success false failure

Example:
#------------------------------------------------------------
# Name of File::CmpSetText.rb
#
# Purpose:: Sets the text on the component TXT1
#-
#------------------------------------------------------------
require "AS.API.Share"
prj = applicationApi.GetProjectApi( "P1" );
if(prj)
cmp = prj.GetComponent( "TXT1" );
if(cmp)
cmp.SetText( "TXT1 text changed" );
end
end
applicationApi.Refresh();
return AS::API::Share::ASAPI_RETURNS.NORMAL_PROCESSING

7-226
 API Reference Manual

7.7.2.32 bool SetParameter(int paramType, object value)

General method that allows a script writer to change parameters of a component.

Currently the following parameters are supported.

AS::API::Share::ASAPI_PARAM_TYPE.iSetSpoolCurrent
AS::API::Share::ASAPI_PARAM_TYPE.iIsSpoolLocked
AS::API::Share::ASAPI_PARAM_TYPE.iRefreshComponent
AS::API::Share::ASAPI_PARAM_TYPE.iSetSpool
AS::API::Share::ASAPI_PARAM_TYPE.iDoesSpoolExists
AS::API::Share::ASAPI_PARAM_TYPE.iLockCurrentSpool

The object image has to be refreshed before the change will be visible within the image.

Parameters:

paramType The type of parameter to change.

value The value to change it to.

Returns:

bool Return Information.

Example:
#-------------------------------------------------------------------------
# Name of File::CmpSetParameter.rb
#
# Purpose::
#
# This will demonstrate how a script writer can set parameters on
# a component. In this case we will be changing the spool position
# of a directional Valve. The component "1-1V32" must exist in the
# current project.
#-------------------------------------------------------------------------
require "AS.API.Share"

prj = applicationApi.GetCurrentProject();

Famic Technologies Inc. 7-227

Automation Studio™ – API and Scripting Language
setSpool = AS::API::Share::ASAPI_PARAM_TYPE.iSetSpoolCurrent;
lockSpool = AS::API::Share::ASAPI_PARAM_TYPE.iLockCurrentSpool;
refreshSpool = AS::API::Share::ASAPI_PARAM_TYPE.iRefreshComponent;

if( prj )
cmp = prj.GetComponent("H84");

if(cmp)
spoolPos = 1;
cmp.SetParameter(setSpool,spoolPos);
cmp.SetParameter(lockSpool,spoolPos);
cmp.SetParameter(refreshSpool,spoolPos);
end
end

return

7-228
 API Reference Manual

7.7.2.33 bool SetPatternFill(int pattern)

Sets the pattern to be used by the component. The pattern is an index into a table of
patterns supported by Automation Studio™. This expects the object to be refreshed
before the attribute is visible.

Parameters:

pattern The pattern to be used by the composite.

Returns:

bool true success false failure

Example:
#----------------------------------------------------------
# Name of File::CmpSetPatternFill.rb
#
# Purpose: Changes the pattern used by the component “PPO1”
#----------------------------------------------------------
require "AS.API.Share"

prj = applicationApi.GetProjectApi( "P1" );

if(prj)
cmp = prj.GetComponent( "PPO1" );
if(cmp)
iCnt = cmp.GetPatternFill();
if(iCnt == 50)
iCnt = 1
else
iCnt += 1
end
cmp.SetPatternFill(iCnt);
end
end
applicationApi.Refresh();
return AS::API::Share::ASAPI_RETURNS.NORMAL_PROCESSING

Famic Technologies Inc. 7-229

Automation Studio™ – API and Scripting Language

7.7.2.34 bool SetRotationCenter(Point centerPoint);

This method is used to set the point in a graphical primitive that will be used when it is
rotated. A symbol has its own drawing coordinates, this defines the point in that system
that will be used when it is rotated.

Parameters:

centerPoint The new position in the symbol’s coordinate system that will
be used when it is rotated.

Returns:

bool True is returned if an error did not occur.

Example:
#------------------------------------------------------------
# Name of File::CmpSetRotationCenter.rb
#
# Purpose:: Set a components rotation center
#------------------------------------------------------------
require "AS.API.Share"
require 'System.Drawing,
Version=2.0.0.0, Culture=neutral,
PublicKeyToken=b03f5f7f11d50a3a'
applicationApi.ChangeAllLogOutputs(AS::API::Share::LOGTYPE.AS_MESSAGE_SYSTEM);

prj = applicationApi.GetProjectApi( "P1" );

cmp = prj.GetComponent( "H5" );
ptOrg = System::Drawing::Point.new;
ptOrg.X = 0; ptOrg.Y = 0;
cmp.SetRotationCenter(ptOrg);
applicationApi.Refresh();

return AS::API::Share::ASAPI_RETURNS.NORMAL_PROCESSING

7-230
 API Reference Manual

7.7.2.35 bool SetScale(float scale)

bool SetScale(float scaleX, float scaleY)

This sets the width and height scale to the component.

Parameters:

scale Scale applied to X and Y.

scaleX Scale applied to X

scaleY Scale applied to Y.

Returns:

bool true success false failure

Example:
#------------------------------------------------------------
# Name of File::CmpScale.rb
#
# Purpose::
# Demonstartes scaling an object "DAO7"
#------------------------------------------------------------
require "AS.API.Share"

prj = applicationApi.GetProjectApi( "P1" );

cmp = prj.GetComponent( "PPO1" );
# Find the size and location of the component for the zoom
if(cmp)
scale = cmp.GetScale();
if(scale.X != 2.0)
cmp.SetScale(2.0);
else
cmp.SetScale(1.0);
end
end
applicationApi.Refresh();
return AS::API::Share::ASAPI_RETURNS.NORMAL_PROCESSING

Famic Technologies Inc. 7-231

Automation Studio™ – API and Scripting Language

7-232
 API Reference Manual

7.8 View

This is used to access the attributes that are managed by a view.

7.8.1 Access to the View identifier

To access an instance of a view the following call can be used.

int GetBaseId();

This method returns the identifier of the object that generated the event. If this was not
a view the identifier returned will not work. A view will exist if a view, or a child or
grandchild initiated the event.

The second method to find a view is to navigate through the view children of a
document.
nCnt = documentApi.GetChildCount(asTid.VIEW_API);
nIdx = 0
while (nIdx < nCnt) do
view = documentApi.GetNthChild(nIdx,
asTid.VIEW_API);
… # Then you use the view object.
nIdx += 1
end

Famic Technologies Inc. 7-233

Automation Studio™ – API and Scripting Language

7.8.2 Methods

Methods that can be called from a document view.

7.8.2.1 bool Maximize()

This method sets the frame of the view to use the entire window space.

Parameters:

NIL No parameters will be set.

Returns:

bool The view was maximized.

Example:
#------------------------------------------------------------
# Name of File::ViewMaximize.rb
#
# Purpose::
# This maximizes the current view.
#------------------------------------------------------------
require "AS.API.Share"

viewApi = AS::API::Share::ASAPI_OBJ.VIEW_API;

doc = applicationApi.GetDocumentApi("D1","P1");

view = doc.GetView("View3");
if(view)
view.Maximize();
end

return AS::API::Share::ASAPI_RETURNS.NORMAL_PROCESSING

7-234
 API Reference Manual

7.8.2.2 bool Minimize()

This method minimizes all views within a document.

Parameters:

NIL No parameters will be set.

Returns:

bool The document was minimized

Example:
#------------------------------------------------------------
# Name of File::ViewMinimize.rb
#
# Purpose::
# This minimize the current view.
#------------------------------------------------------------
require "AS.API.Share"

viewApi = AS::API::Share::ASAPI_OBJ.VIEW_API;

doc = applicationApi.GetDocumentApi("D1","P1");

view = doc.GetView("View3");
if(view)
view.Minimize();
end
return AS::API::Share::ASAPI_RETURNS.NORMAL_PROCESSING

Famic Technologies Inc. 7-235

Automation Studio™ – API and Scripting Language

7.8.2.3 bool SetAutoZoom(bool bValue)

This method changes how the current view handles the zoom level when the frame size
changes.

Parameters:

bValue True sets the image into a mode so that the same image is
provided no mater what the frame size used, of course the
image will be a different size. False the zoom level will not
change so less or more of the image will be supplied when the
frame size changes.

Returns:

bool Indicates success

Example:
#------------------------------------------------------------
# Name of File::ViewSetAutoZoom.rb
#
# Purpose::
# Sets the view so that the zoom level does not change when
# the view frame changes.
#------------------------------------------------------------
require "AS.API.Share"

viewApi = AS::API::Share::ASAPI_OBJ.VIEW_API;

doc = applicationApi.GetDocumentApi("D1","P1");
view = doc.GetView("View2");
if(view)
view.SetAutoZoom(true);
end

return AS::API::Share::ASAPI_RETURNS.NORMAL_PROCESSING

7-236
 API Reference Manual

7.8.2.4 bool SetVerticalStretch ()

After a call to this method, the user will be able to modify the height of the view’s frame
using the UI.

Parameters:

NIL No parameters will be set.

Returns:

bool Indicates success

Example:
#------------------------------------------------------------
# Name of File::SetVerticalStretch.rb
#
# Purpose::
# Demonstrates the view's vertical stretch method.
#------------------------------------------------------------
require "AS.API.Share"

viewApi = AS::API::Share::ASAPI_OBJ.VIEW_API;

doc = applicationApi.GetDocumentApi("D1","P1");
view = doc.GetView( "View2" );
if(view)
view.SetVerticalStretch();
end

return AS::API::Share::ASAPI_RETURNS.NORMAL_PROCESSING

Famic Technologies Inc. 7-237

Automation Studio™ – API and Scripting Language

7.8.2.5 bool SetHorizontalStretch ()

After a call to this method, the user will be able to modify the width of the view’s frame
using the UI.

Parameters:

NIL No parameters will be set.

Returns:

bool Indicates success

Example:
#------------------------------------------------------------
# Name of File::SetHorizontalStretch.rb
#
# Purpose::
# Sets the horizontal stretch to true. This locks the
# ability of the user to stretch the frame vertically
#------------------------------------------------------------
require "AS.API.Share"

viewApi = AS::API::Share::ASAPI_OBJ.VIEW_API;

doc = applicationApi.GetDocumentApi("D1","P1");
view = doc.GetView("View2");
if(view)
view.SetHorizontalStretch();
end

return AS::API::Share::ASAPI_RETURNS.NORMAL_PROCESSING

7-238
 API Reference Manual

7.8.2.6 bool SetSymmetricStretch ()

After a call to this method, when the user tries to modify the size of the frame using the
UI, proportion between the width and the height will be maintained.

Parameters:

NIL No parameters will be set.

Returns:

bool Indicates success

Example:
#------------------------------------------------------------
# Name of File::ViewSetSymmetricStretch.rb
#
# Purpose::
# Sets any change to the views frame to be done maintaining
# the current frames aspect ratio.
#------------------------------------------------------------
require "AS.API.Share"

viewApi = AS::API::Share::ASAPI_OBJ.VIEW_API;

doc = applicationApi.GetDocumentApi("D1","P1");
view = doc.GetView("View2");
if(view)
view.SetSymmetricStretch();
end

return AS::API::Share::ASAPI_RETURNS.NORMAL_PROCESSING

Famic Technologies Inc. 7-239

Automation Studio™ – API and Scripting Language

7.8.2.7 bool SetStretch ()

After a call to this method, the user will be able to modify the width or the height of the
view’s frame using the UI.

Parameters:

NIL No parameters will be set.

Returns:

bool Indicates success

Example:
#------------------------------------------------------------
# Name of File::ViewSetStretch.rb
#
# Purpose::
# Removes resizing restrictions on the view’s frame.
#------------------------------------------------------------
require "AS.API.Share"

viewApi = AS::API::Share::ASAPI_OBJ.VIEW_API;

doc = applicationApi.GetDocumentApi("D1","P1");
view = doc.GetView("View2");
if(view)
view.SetStretch();
end

return AS::API::Share::ASAPI_RETURNS.NORMAL_PROCESSING

7-240
 API Reference Manual

7.8.2.8 bool SetAlwaysOnTop (bool bSet)

Sets the view to remain on top of the view stack.

Parameters:

bSet true/false to set or unset the attribute that dictates that the
view will remain on top of view stack.

Returns:

bool Indicates success

Example:
#------------------------------------------------------------
# Name of File::SetAlwaysOnTop.rb
#
# Purpose::
# Demonstrates the view's SetAlwaysOnTop method.
#------------------------------------------------------------
require "AS.API.Share"

viewApi = AS::API::Share::ASAPI_OBJ.VIEW_API;

doc = applicationApi.GetDocumentApi("D1","P1");
view = doc.GetView("View2");
if(view)
view.SetAlwaysOnTop(true);
end

return AS::API::Share::ASAPI_RETURNS.NORMAL_PROCESSING

Famic Technologies Inc. 7-241

Automation Studio™ – API and Scripting Language

7.8.2.9 bool SetWindowPosition(Point position)

This method allows the script writer to modify the position of a view on the screen.

Parameters:

position The window position in window co-ordinates using the point

object of type System::Drawing::Point.

Returns:

true Indicates success

Example:
#------------------------------------------------------------
# Name of File::ViewSetWindowPosition.rb
#
# Purpose::
# Demonstrates the SetWindowPosition() method
#------------------------------------------------------------
require "AS.API.Share"

require 'System.Drawing,
Version=2.0.0.0, Culture=neutral,
PublicKeyToken=b03f5f7f11d50a3a'

doc = applicationApi.GetDocumentApi("D1","P1");
if(doc)
view = doc.GetView("View1");
if(view)
ptOrg = System::Drawing::Point.new;
ptOrg.X = 100
ptOrg.Y = 100
view.SetWindowPosition(ptOrg);
end
end

return AS::API::Share::ASAPI_RETURNS.NORMAL_PROCESSING

7-242
 API Reference Manual

7.8.2.10 bool SetWindowSize(Size size)

Allows the script writer to modify a views screen size.

Parameters:

size The window size in window co-ordinates using a size object of

type System::Drawing::Size.

Returns:

bool Indicates success

Example:
#------------------------------------------------------------
# Name of File::ViewSetWindowSize.rb
#
# Purpose:
# How to resize a views window.
#------------------------------------------------------------
require "AS.API.Share"
require 'System.Drawing,
Version=2.0.0.0, Culture=neutral,
PublicKeyToken=b03f5f7f11d50a3a'

doc = applicationApi.GetDocumentApi("D1","P1");
if(doc)
view = doc.GetView("View1");
if(view)
ptOrg = System::Drawing::Size.new;
ptOrg.Width = 300
ptOrg.Height = 300
view.SetWindowSize(ptOrg);
end
end

return AS::API::Share::ASAPI_RETURNS.NORMAL_PROCESSING

Famic Technologies Inc. 7-243

Automation Studio™ – API and Scripting Language

7.8.2.11 bool SetZoomAndPan(bool bPan)

This will turn on or off the interface that allows a user to zoom or pan the view.

Parameters:

bPan True: allows a user to zoom an pan the view.

False: disallows a user from zooming or panning the view.

Returns:

bool Success or failure of the operation.

Example:
#------------------------------------------------------------
# Name of File::ViewSetZoomAndPan.rb
#
# Purpose:
# Demonstrates the use of the view objects method
# SetPanAndZoom().
#------------------------------------------------------------
require "AS.API.Share"

doc = applicationApi.GetDocumentApi("D1","P1");
view = doc.GetView("View1");
if(view)
view.SetZoomAndPan(false);
end

return AS::API::Share::ASAPI_RETURNS.NORMAL_PROCESSING

7-244
 API Reference Manual

7.8.2.12 bool Show(bool toShow)

bool Show(AS::API::Share::SHOW_TYPE)

This method sets the views frame to be visible.

Parameters:

toShow false = hide, true = show, default = show.

Returns:

bool True is returned if successful.

Example:
#------------------------------------------------------------
# Name of File::ViewShow.rb
#
# Purpose::
# Demonstrates the views Show method.
#------------------------------------------------------------
require "AS.API.Share"

viewApi = AS::API::Share::ASAPI_OBJ.VIEW_API;

doc = applicationApi.GetDocumentApi("D1","P1");
if(doc)
view = doc.GetView("View2");
if(view)
showType = AS::API::Share::SHOW_TYPE.SHOW;
view.Show(showType);
doc.Refresh();
end
end

return AS::API::Share::ASAPI_RETURNS.NORMAL_PROCESSING

Famic Technologies Inc. 7-245

Automation Studio™ – API and Scripting Language

7.8.2.13 bool Zoom(…)

A set of methods to defined the space used by a view. The units used will be dependent
on the base drawing units of the document. If the display uses cm the base drawing unit
is 1/10 of a millimeter.

bool Zoom(int left, int top, int right, int bottom)

or

bool Zoom(Point minPt, Point maxPt)

or

bool Zoom(IComponentApi cmpObj)

or

bool Zoom(List <ComponentApi> cmpObjs)

Parameters:

left Left most X position to fit into the zoom frame.

top Top most Y position to fit into the zoom frame.

right Right most X position to fit into the zoom frame.

bottom Bottom most Y position to fit into the zoom frame.

minPt Smallest co-ordinate to fit into the zoom frame.

maxPt Largest co-ordinate to fit into the zoom frame.

cmpObj Fit the view to use the bounding box of the provided

7-246
 API Reference Manual

component.

cmpObjs Fit the view to use the bounding box of the provided
component list.

Returns:

bool Indicates success

Example:
#------------------------------------------------------------
# Name of File::ViewZoom.rb
#
# Purpose::
# Demonstrates the views methods related to zooming.
# Expects in memory the following in the current project.
# A document with the name "D1" and views 1, 2, 3 & 4
# Two components with the names "PPO1" and "DA02"
#------------------------------------------------------------
require "AS.API.Share"
require 'System.Drawing,
Version=2.0.0.0, Culture=neutral,
PublicKeyToken=b03f5f7f11d50a3a'
pt1 = System::Drawing::Point.new;
pt2 = System::Drawing::Point.new;

prj = applicationApi.GetProjectApi( "P1" );

cmp = prj.GetComponent( "PPO1" );
# Find the size and location of the component for the zoom
if(cmp)
# Zoom the first frame using a component.
view = prj.GetViewApi( "View1" , "D1" );
if(view)
view.Zoom(cmp);
end
# Zoom the second frame using a list of components.
view = prj.GetViewApi( "View2" , "D1" );
if(view)
lst = cmp.GetEmptyList();
cmp2 = prj.GetComponent( "PPO2" );
if(cmp2)
lst.Add(cmp2);

Famic Technologies Inc. 7-247

Automation Studio™ – API and Scripting Language
end
lst.Add(cmp);
view.Zoom(lst);
end
# Calculate the zoom frame around the component
loc = cmp.GetLocation();
size = cmp.GetSize();
pt1.X = loc.X - 10;
pt1.Y = loc.Y - 10;
pt2.X = loc.X + size.Width + 10;
pt2.Y = loc.Y + size.Height + 10;
# Zoom the third frame using left, top, right, bottom
view = prj.GetViewApi( "View3" , "D1" );
if(view)
view.Zoom(pt1.X,pt1.Y,pt2.X,pt2.Y);
end
# Zoom the fourth frame using minimum, maximum points.
view = prj.GetViewApi( "View4" , "D1" );
if(view)
view.Zoom(pt1, pt2);
end
end

return AS::API::Share::ASAPI_RETURNS.NORMAL_PROCESSING

7-248
 API Reference Manual

7.8.2.14 bool ZoomExtents()

This method fits all document components into the views frame.

Parameters:

NIL No parameters will be set.

Returns:

bool Indicates success

Example:
#------------------------------------------------------------
# Name of File::SetZoomExtents.rb
#
# Purpose::
# Demonstrates how to use the views method ZoomExtents
#------------------------------------------------------------
require "AS.API.Share"

viewApi = AS::API::Share::ASAPI_OBJ.VIEW_API;

doc = applicationApi.GetDocumentApi("D1","P1");
view = doc.GetView("View1");
if(view)
view.ZoomExtents();
end
return AS::API::Share::ASAPI_RETURNS.NORMAL_PROCESSING

Famic Technologies Inc. 7-249

A Glossary

Discription of the language that is used within the document.

Administrator

The individual responsible to setup the general operational environment of Automation

StudioTM.

API

Application Programming Interface.

Automation Studio™

Drawing and simulation software that includes many workshops such as, electrical,
pneumatics, hydraulics, and the Catalogue module.

AS

Automation Studio™.

Display Builder

Daily user of Automation Studio™.

Boolean

An element that can take two values: True or False.

C#

Programming language supplied in the .NET environment of Microsoft.

Famic Technologies Inc. A-1

Automation Studio™ – API and Scripting Language
Developer

Someone who creates or modifies computer software.

DLL

Dynamic Linked Library.

Dynamic Linked Library

Software assemblies that can contain code and are shared by many applications. They
can contain data code and resources that can be used by a program. The code can be
executed from within the applications that load the DLL.

Entry Point

Entry Point is a term used to define a point in processing within an application

environment that provides the ability to redirect the process control to code written by a
third party developer.

Event

An event is a message generated by the operating system, or an application using the

invokeEvent function; this provides an entry point that allows a third-party developer to
inject their own implementation of the event generated.

The user’s functionality can also be driven by events that occur within Automation
Studio™. These events do not follow a predetermined path.

Events are a little different than hooks; events are generated by the windows operating
system in response to an action. These events can be redirected to the developer’s
module.

Events can be registered with a third-party script or .NET method within any user process
(including the startup process described below.

A-2
 Glossary
Extensibility

The ability to extend a software implementation by a third party developer. An

application that takes into consideration future growth that will be provided by a third
party developer. These additions allow a software package to be enhanced, supplying
additional functionality and the avoidance of early obsolescence.

Hook

Is a point in processing that can be redirected by a third party developer allowing him to
inject their own implementation required for the particular point in processing. This is
much like an “event” except it does not rely on windows event processing.

The users functionality will be driven by points in processing that occur within
Automation Studio™ that can be hooked by the developer.

The concept of redirecting process flow to a users programming model is known as

hooking or the user hooks the action.

Hooks can be registered to a third-party script or .NET method within any user process, or
by adding the required method or script to a component’s hyperlink attribute within a
document.

An example of such a point in processing is when the open file menu option is selected.
Here a user may be interested in affecting how Automation Studio ™ normally handles
this event so he indicates to Automation Studio ™ to call his open file process instead of
AS’s version.

Hyperlink

Generally associated with the Internet, it offers the possibility of opening a text element
or image by clicking on a link that contains an underlying address.

Logical operators

Elements establishing the link between two search criteria. These operators are: “AND”,
“OR”.

Famic Technologies Inc. A-3

Automation Studio™ – API and Scripting Language
Navigate

This term is used with reference to moving around AS’s data model. How can you access
an element of data required from within a .NET module or script.

Script

Is a text file that provides a set of controls that can direct Automation Studio™ to change
its behavior or manipulate its data. Scripts where previously known as batch languages
or job control languages.

Scripting

The process of writing Script files.

Startup

The first point in processing where a user may redirect functionality is during Automation
Studio™ startup. At this point if a client has created a startup .NET method or script it will
be processed.

Within this process the user can then call the register method that will map future events
to the user’s .NET methods or scripts.

Third-Party

Third-Party developer describes anybody who will be extending the runtime behavior of
Automation Studio™ on top of a released version of the software.

A-4
B IronRuby Syntax

This chapter will point out a few elements required to write IronRuby scripts that can be
called from, and interface with, Automation Studio™. This chapter can also be used to
introduce a user to the IronRuby language. Ruby is a significant language which will not
be documented here. For additional information please refer to the following link:

www.ruby-doc.org/docs/ProgrammingRuby/

IronRuby is a scripting language produced and supported by Microsoft that closely

resembles Ruby. The Ruby community considers IronRuby to support about 86% of Ruby.
As time goes by Microsoft should improve this.

Specific to AS User of IronRuby

The AS Scripting Language applies restrictions to the expected scope and use of the
scripts. Due to this environment; it can improve the power of the scripts by adding some
C# protocols to the scripting language.

The other issue is that there is included a significant interface to the Automation Studio™
model that can be used by the scripts.

Case sensitivity

IronRuby is case sensitive.

Comments

Single-line: All text on a line after “#” will be ignored

Multi-line comment syntax, the =begin and =end have to start at the beginning of the
line

Famic Technologies Inc. B-1

Automation Studio™ – API and Scripting Language
=begin
<text to be ignored>
=end

Variables

You do not have to specify variable type in IronRuby, and the moment you assign a
previously assigned value to a different type it will be changed to the new type.

str= "PPO1";
cmp = projectApi.GetComponent(str);
str = 1
count = str + 2

The above code, though difficult to read will work. What does matter is that you supply
the correct data to any interface used. Problems would occur if you assigned str = 1
before you called projectApi.GetComponent(str).

Reserved Words

Here is a list of some of the basic reserved words that exist in the IronRuby language.
__FILE__ __LINE__ alias and begin break case
class def defined? do else elsif end
ensure false for if in module next
nil not or redo rescue retry return
self super then true undef unless until
when while yield

Math

Ruby supports the following operators that can be used within expressions.

( + - * / % ** & | ^

<< >> && || )

It also supports the simplified version for any of the above. (+= -= etc.)

B-2
 IronRuby Syntax
Comparison

Traditional Description
operators

== Two operands equal?

!= Two operands not equal?

> Left operand is greater than the right operand.

< Left operand is less than the right operand.

>= Left operand is greater or equal to the right operand.

<= Left operand is less than or equal to the right operand.

<=> Zero indicates the operands are equal, 1 indicates left is greater than
the right operand, -1 indicates that the left is less than the right
operand.

=== Tests equality with clauses. example (1…10) === 5 returns true

.eql? True if both operands are of the same type and are equal.

.equal? True if the receiver and the argument are the same object

Famic Technologies Inc. B-3

Automation Studio™ – API and Scripting Language
Control Structures

If…else

if conditional [then]
code …
[elsif conditional [then]
code …]
[else
code …]
end

Example:

# The following tests that the returning variable has a value.

readValue = node.GetVariableValue(varName, varType);

if (readValue)
str = "Variable not found!";
return(str);
end

Unless
unless conditional [then]
code
[else
code ]
end

B-4
 IronRuby Syntax
Switch/Case Statement

case expression
[when expression [,
expression ...] [then]

code … ]...
[else

code …]
end

Example:

# The following tests to see what combo box item has been
selected.

case @comboBoxNodeType.SelectedIndex
when 0 : node =
@m_project.GetComponent(@textBoxVarNodeID.Text);
when 1 : node =
@m_project.GetDocument(@textBoxVarNodeID.Text);
when 2 : node = @m_project;
end

Until loop Statement

until conditional [do]
code
end

Example:

Famic Technologies Inc. B-5

Automation Studio™ – API and Scripting Language

# The following example loops though all the projects within an application
:
iCnt = applicationApi.GetChildCount(1);

until i == iCnt
prj = applicationApi.GetNthChild(i, 1);

# Do some work with the aquired project

i += 1
end
:

While Loop
while conditional [do]
code
end

Example:

# The following example also loops though all the projects within an application
:
i = 0
iCnt = applicationApi.GetChildCount(1);

while i != iCnt do
prj = applicationApi.GetNthChild(i, 1);

# Do some work with the aquired project

i += 1
end
:

Function Calls

Functions are defined as follows:

def <method name> [(parameter,…)]
[ function interior ]
return [expr[`,' expr...]]
end

B-6
 IronRuby Syntax
Classes

class <class name>

def <method name> [(parameter,…)]
[ function interior ]
return [expr[`,' expr...]]
end
def <method name> [(parameter,…)]
[ function interior ]
return [expr[`,' expr...]]
end

end

Exceptions

When an exception occurs that relates to improper use of the IronRuby language it is
caught by Automation Studio. Automation Studio™ will provide an error message box
that will include some information that may help the script builder correct the issue.

In a number of the cases the user will be able to choose whether to continue the script.

Famic Technologies Inc. B-7

C Internal Names

Internal names available to the script writer.

Standards

The internal names for different document standards can be accessed through the
following variables. These are not provided through tooltips. In the .NET world the prefix
“AS::API::Share::” can be omitted. The following are the Ruby variables. These
variables will be required in the IDocumentApi.SetStandard(), and
IDocumentApi.GetStandardName(), methods.

standards = applicationApi.GetConstantOptionStrings();

standards.k_VdPageSetupStandard;
standards.k_VdMapLocatorStandard;
standards.k_VdReferenceStandard;
standards.k_VdDimensioningStandard;
standards.k_VdDrawingToolsStandard;
standards.k_VdFluidStandard;
standards.k_VdHydraulicStandard;
standards.k_VdPneumaticStandard;
standards.k_VdElectrotechnicalStandard;
standards.k_VdOneLineStandard;
standards.k_VdPanelLayoutStandard;
standards.k_VdSFCStandard;
standards.k_VdLadderLogicStandard;
standards.k_VdElectricalStandard;
standards.k_VdDigitalElectronicStandard;
standards.k_VdConnectionDiagramStandard;

Famic Technologies Inc. C-1

D Command Line Launch of a Ruby Script

To run a script when Automation Studio™ is just starting, create a shortcut to Automation
Studio™. Select the properties dialog on the shortcut. Add to the target field the
following information.

"/SCRIPT:Getting Started\\IRScriptB.rb"

Figure D-2: Running AS with parameters

When this icon is now selected it will launch AS with the parameter
/SCRIPT:IRScriptB.rb. This registration script will add the “Extended” tab to
Automation Studio™’s ribbon bar. This tab will contain the “Ruby” group with buttons
“User Dialog” and “Export”.

Famic Technologies Inc. D-1