PREV NEXT

Generic Logic, Inc. www.genlogic.com


5 GLG Programming Tools and Utilities

The GLG Toolkit includes three utility programs of some use to GLG application programmers:

datagen
Generates a variety of test data suitable for testing and prototyping GLG drawings.
gcodegen
Creates a memory image of a GLG drawing in the C language format. The output of the utility is a file with .c extension, containing the image of the drawing in a form of the C source code. The output file can be compiled into the program's executable, saving users from having to supply a separate drawing file.
gconvert
A GLG drawing file may have one of three different formats: Binary, ASCII, or Extended. The Binary files are the fastest to load, but the Extended and ASCII files are more portable. The gconvert program converts drawing files from one format to another. The utility can also be used to change resources of a drawing in a batch mode using the script command option.

These tools are described in more detail in this chapter.

The GLG Toolkit also provides support for scripting. Scripting may be used at run time to supply data form a URL to a drawing displayed in a GLG Java applet in a browser. It may also be used for creating drawings using a script as well as editing drawings in the batch mode. Scripting is only one of the ways to create a GLG drawing. The GLG Extended API may also be used to generate a drawing programmatically and provide full access to all GLG functionality at run time.

The GLG Script format as well as the command-line options for using the GLG Builder for scripting are also described in this chapter.

5.1 The Data Generation Utility

The data generation utility is included with the Toolkit and can be used to supply animation data for a GLG drawing during development. It can generate random or incremental data, take data for animation from a file or execute a script.

The datagen utility is embedded into the GLG Builder, which invokes the utility to generate data for prototyping the drawing in the Run mode using the $datagen command in the Run dialog. $datagen instructs the Builder to use an internal version of the datagen utility.

The datagen utility can also be used in stand-alone mode with the -print option to write animation commands into a script file which can be later used with the GLG Builder and GLG Java Bean. The datagen utility is a symbolic link to the GLG Builder executable and can be invoked in the following way:

datagen <datagen options>

On Windows, links are not supported, and the following command must be used:

GlgBuilder -datagen <datagen options>

Command Line Arguments and Options

Datagen requires several parameters, including the name and type of the resource to be set and the low and high range for that resource.

	datagen  <options>  [data_set]  [data_set...]
<options>
are optional parameters applicable to all data sets and may include:
-sleep num_secs
Specifies the number of seconds to sleep after each update
-pack number
Allows supplying a few data iterations for one update. The update is performed only once per specified number of the data values sent. This option also affects generation of string data. If the option is specified, and string data is requested, only one value of the string type data is generated for each pack.
-argf argfile
Allows some or all of the datagen arguments to be specified in the text file specified by this option. The arguments read from the file are placed at the position in the command line where this option is located. Several files may be chained using this option.
-script scriptfile
Specifies a file to use as an input script. The script may have commands for setting specific resources and updating the drawing. The script commands are listed in 1, 2
-print scriptfile
Writes animation commands into an output script file. The script file can be read with the
-script option.
-restore
This option sets the value of any named resource to zero, ignoring the range and data set options.

Data Set Specification

Several data sets may be specified. Each data set specification is composed of a collection of one or more data set options, three parameters defining the type and range of the desired data set, and the name of a resource in the drawing. The data set options and parameters are used to generate a stream of data, and that data is applied to the specified drawing resource

The data set specification looks like this:

<data_set_options>  type  low_range  high_range resource_name

The data set arguments are defined as follows:

type
Specifies the type of the data to be supplied. It should correspond to the type of the resource the data will be assigned, which is specified by resource_name. The type may be one of the following:
d - a double-precision scalar value
g - a "geometrical" value consisting of a set of three scalar values
s - a string
Unless the -datafile or -script option is used, the string data produced by datagen are numerical strings formed by converting a double-precision scalar value into a string using the C-style %d format. Therefore, the difference between low_range and high_range should be more than 1 to obtain strings different from the low range value. The geometrical data generated by datagen has identical x, y, and z coordinates.
low_range
Specifies the lower limit of the data to be generated.
high_range
Specifies the upper limit of the data to be generated.
resource_name
Specifies the name of the resource (or tag if -tag dataset option is used) to which the generated data values are assigned. The actual type of the resource or tag should match the type specified by the type parameter. The resource name or tag source must be defined relative to the viewport whose server receives the datagen message.

Data Set Options

The data set options are applied only to the data set specification in which they are found. If no data set options are specified, datagen produces random data between the data limits. The data set options are:

-tag
The datagen will handle the resource_name parameter as a tag source.
-lin
-incr
Generates linear data. The data start at the range lower limit and increase monotonically until the upper limit is reached. After the upper limit is reached, the generated data start again from the lower limit. The increment added to the data between iterations is determined by the total range and the defined data period. The default period is 100 iterations.
-sin
Generates data using a sine function. The data start at the range lower limit and vary sinusoidally between the range limits. The oscillation period is measured in data iterations, and can be controlled with the -period option. The default period is 100 iterations.
-cos
Generates data using a cosine function. The data start at the range higher limit and vary sinusoidally between the range limits. The oscillation period is measured in data iterations, and can be controlled with the -period option. The default period is 100 iterations.
-period number
Specifies a period of the sinusoidal or incremental data for the -sin, -cos or -incr option. The supplied number defines the number of iterations that compose one period. The default period is 100 iterations.
-surf
Generates data for animating a surface graph. The number of rows and columns has to be specified with the -row and -column options. The -pack option may be used to update a graph just once when the complete surface is generated. In this case a pack number should be greater than or equal to the number of rows times the number of columns.
-row number
Specifies the number of points in a row on a polysurface. This is one greater than the number of polygon patches in the row.
-col number
Specifies the number of points in a column on a polysurface. This is one greater than the number of polygon patches in the column.
-datafile data_file
Specifies the name of a data file. If such a file is specified, the data is read from this data file instead of being generated. The low_range and high_range parameters are ignored, but still must be included in the data set specification. The format of the data file is outlined below.

Data File Format

The data file is used when testing a drawing requires data not easily generated with the available datagen data set options. The file contains ASCII data corresponding to the type of the resource. For a scalar resource the file should be an array of numbers separated by spaces or new lines. A scalar data file might look like this:

1 1.1 1.2 1.3 1.4 1.5
1.6 1.7 1.8 1.9 2 2.1
2.2 2.3 2.4 2.5 2.6 2.7
...

For a geometrical resource the file should be an array of numbers as well, but the number of values in the array should be a factor of 3, and there must be an integral number of points per line of data.

1 1 0
1.1 1.1 -0.1
1.2 1.2 -0.2
1.3 1.3 -0.3
...

There may be more than one geometrical value per line. The following is also a valid way to specify the same geometrical series shown above:

1 1 0 1.1 1.1 -0.1 1.2 1.2 -0.2
1.3 1.3 -0.3 1.4 1.4 -0.4 1.5 1.5 -0.5
...

For a string resource, the array should have strings separated by the new line character:

October 1996
November 1996
Deember 1996
January 1997
February 1997
March 1997
April 1997
...

5.2 GLG Script

Overview

The GLG Script serves a variety of functions in the Toolkit:

GLG Script includes a small set of commands which can be used to set the value of some resource, update the drawing, synchronize the connection or produce a PostScript output. A script file is an ASCII file with a single command on each line. The script provides Database Record Support extension to simplify usage of database records to supply data for animation.

The script also provides an extended command set for creating and deleting objects. These commands may be used for creating drawings using a script, or for editing drawings using the batch mode of the GLG Builder. The extended command set is available only in the Enterprise Edition of the GLG Graphics Builder. To create drawings programmatically at run time, use the GLG Extended API, which provides this functionality and more.

The syntax of the script commands is described below.

Standard Command Set

# <comment>

Specifies a comment line. Any line that starts with the "#" character is interpreted as a comment. The "#" character can be preceded with spaces and tabs.

set_value

Sets the value of a particular resource.

set_value <resource_name> <resource_type> <value(s)>

The command arguments define the name, type, and new value of the resource. This syntax is the same as the syntax for the dynamic resources, described in the Setting the Drawing Resources section of Using the C/C++ version of the Toolkit on page 27.

The strings used for setting values of resources of the S (string) type can be surrounded with double quotes, in which case they may contain spaces as well as the new line characters for multi-line strings. The `\' escape character may also be used to define simple escape sequences, such as "\n", "\r", "\t", "\b", "\"" and "\\". Use "$null" to set the new attribute value to null.

Using set_value with the Extended Command Set

The "." and "/" symbols may be used in resource_name to reference the current object and the container selected with the select_object or select_container commands of the extended command set, respectively (see page 328). For example, ./FillColor may be used to access the FillColor attribute of the current object, and /Visibility may be used to access the visibility of the selected container.

Registers may be used in script commands instead of resource names. For example, %3/FillColor may be used to access the FillColor attribute of the object stored in register 3. The content of a register is set using the select_object command of the extended command set described on page 328.

The $last_value symbol may be used instead of the value parameters, to refer to the value(s) obtained by the last get_value or get_tag command of the extended command set.

set_tag

Same as set_value, but uses a tag_source.

set_tag <tag_source> <tag_type> <value(s)>

update

Updates the drawing to reflect the new values of resources.

update

For more information about the update action, see the GlgStrClone section of Animating a GLG Drawing with Data Using the Standard API.

print

Print the server's viewport by producing a PostScript output and saving it into a specified file:

		print <filename> <x> <y> <width> <height> <portrait> <stretch>

The x, y, width, and height parameters define the PostScript page layout. The origin is defined to be in the middle of the page, the left edge of the page is at -1000, and the right edge is at 1000. The top and bottom of the page are similarly defined to be at 1000 and -1000, respectively. The x and y parameters define the lower left corner of the drawing, while width, and height give the dimensions of the drawing area. As an example, the default page layout you get when you print a drawing by setting the PrintFile property puts the lower left corner of the drawing area at (-900 -900), while the dimensions are 1800 by 1800. This makes the drawing about as large as it can be while still keeping a small border all the way around the page. The portrait parameter defines portrait (TRUE) or landscape (FALSE) mode. If the stretch parameter is set to FALSE, the aspect ratio of the drawing is preserved.

The generated PostScript output corresponds to the currently visible state of the server's viewport after the last update command or expose event. The PostScript output is saved on the server's side, so the filename should be defined for the file system of the server host machine. If the filename is defined relative to the current directory, the current directory of the process is assumed.

Database Record Support Commands

Database record support is a feature of a GLG script that allows using the output of database report generators as input data for GLG Netscape plug-in, GLG ActiveX control or as prototyping data for the GLG Graphics Builder.

When used with the GLG Java Bean, the data file may be placed on a web site as files and updated periodically, or the database report generator may be invoked as a CGI program with parameters for querying a required slice of data.

If a regular GLG script is used, each supplied data value needs resource name and type information. Using database record support feature, the information for associating the value with a resource may be supplied just once in a separate setup script and the data file will contain just the raw data generated by a database report generator.

The database record support consists of the following additional GLG script commands:

create_record

Creates a record with a named defined by the record_name parameter:

create_record record_name

add_field

Adds a field to a record defined by the record_name parameter:

add_field 
	record_name resource_name resource_type <separator> 

resource_name parameter specifies a resource to be associated with the field and the resource_type parameter supplies the GLG resource type - d for double resources, s for string resources, and g for points and colors defined by 3 coordinates. A dummy field with "u" as a separator value may be used to update the drawing in the middle of reading records, in which case the resource_name and resource_type fields are ignored.

The separator parameter has to be enclosed in angle brackets and supplies a character used to separate the next field. If a space is used as a separator, spaces and tabulation characters may be used as actual separators.

delete_record

Deletes a record defined by the record_name parameter.

delete_record record_name

read_records

Starts reading records from a script:

read_records record_name 

The format of the records is defined by the record_name parameter. Each record should start on a new line and should not continue to the next line. A dummy field with "u" as a separator value may be used to update the drawing in the middle of reading records.

end_read

Stops the process of reading records defined by the last read_records command.

read_one_record

Reads one records from a script.

read_one_record record_name 

The format of the records is defined by the record_name parameter.

Database Record Support Example

You can use the following script as a SetupDataURL script for the GLG Java Bean:

create_record graph_record 
add_field graph_record DataGroup/EntryPoint d <,> 
add_field graph_record XLabelGroup/EntryPoint s < > 
add_field graph_record dummy u <,> 

The last field is a dummy field which causes display to be updated after reading each record without waiting for all of them to be read.

Then, you can use the following data as the DataURL script:

read_records graph_record 
0.1,Label 1 
0.2,Label 2 
0.3,Label 3 
0.4,Label 4 
0.5,Label 5 
0.6,Label 6 
0.7,Label 7 
0.8,Label 8 
0.9,Label 9 
end_read 

The data file used as a DataURL may also be produced on the fly by a database report generator.

Extended Command Set

The extended command set includes commands for creating and deleting objects, properties and tags using script. The extended command set is available only with the Enterprise Edition of the GLG Graphics Builder and can be used to modify multiple drawings with a script in a batch mode using the -script option of the Drawing File Conversion utility. The utility can be used to apply the script to multiple files, and can also be used to process all files in a directory and all its subdirectories using the recursive mode. Refer to Drawing File Conversion Utility on page 339 for more information.

The extended command set provides a subset of the Extended API functionality in the scripting mode, making it possible to perform elaborate drawing modifications without a need to write a program. Alternatively, the GLG Extended API can be used at run time to modify the drawings or create drawings programmatically.

The extended command set introduces the notion of a current object and a selected container. The current object and container may be selected using the select_object and select_container commands, and then used by other script commands, providing a way to access them efficiently.

The "." and "/" symbols may be used in resource names to reference the current object and the selected container, respectively. For example, ./FillColor may be used to access the FillColor attribute of the current object, and /Visibility may be used to access the visibility of the selected container.

The script engine also provides 10 registers that can be used to store object IDs. The registers are referred in the script using the %n notation, where n is a number from 0 to 9 that specifies the register's index. Registers may be used in script commands instead of resource names. For example, %3/FillColor may be used to access the FillColor attribute of the object stored in register 3. The content of a register is set using the select_object command.

The $last_value symbol may be used instead of the value parameters of the set_value and set_tag command to refer to the value(s) obtained by the last get_value or get_tag command of the extended command set.

Quotes can be used to define strings that contain spaces, such as values of the S resources and tag comments. The $null symbol may be used to define a NULL string.

The following list contains the commands of the extended command set:

skip_if_no_resource

If no resource is found, suspends processing of the script's commands until the skip_end command is read or the end of the script is reached, whichever comes first:

skip_if_no_resource <resource_name> 

The resource_name parameter specifies the resource name to be tested. Nested skip commands are supported.

skip_if_resource

If the resource is found, suspends processing of the script's commands until the skip_end command is read or the end of the script is reached, whichever comes first:

skip_if_resource <resource_name> 

The resource_name parameter specifies the resource name to be tested. Nested skip commands are supported.

skip_end

Resumes processing of the script's commands:

skip_end

get_value

Queries the value(s) of a particular resource and stores them for later use:

get_value <resource_name> <resource_type> 

The command arguments define the name and type of the resource. Use the $last_value symbol instead of the value parameters of the set_value or set_tag command to reference the values returned by the last get_value or get_tag command.

get_tag

Same as get_value, but uses a tag source:

get_tag <tag_source> <resource_type> 

select_object

Selects an object for later access:

select_object <resource_name> [destination]

The resource_name parameter defines the resource name of the object to be selected. Use the "$null" string as the resource_name to unselect the object at the targeted destination.

A destination parameter can be used to specify one of the registers that can store selected objects. Registers are specified using the %n notation, where n is a register's index in the range from 0 to 9. An object stored in a register can be referenced in other script commands, for example:

# Store the $Widget viewport in register 0
select_object $Widget %0
# Set the FillColor of the object stored in register 0
set_value %0/FillColor g 1 1 1
# Store an object from register 0 in register 3
select_object %0 %3

The "." string may be used as a destination to store the object as the current object, which can be referenced in other script commands as ".":

# Select the $Widget viewport as the current object
select $Widget .
# Set the FillColor of the current object
set_value ./FillColor g 1 1 1
# Store the current object in register 2
select_object . %2

The destination parameter is optional. If it is committed, the current object is used as a destination.

Note: The setting of the current object is volatile: some commands, such as create, add_custom_property, add_public_property, etc., store the created object or the added property as the current object for a possible later access. To persistently store an object for referencing it later in the script use registers described above.

The current object is also used as an implicit argument for other script commands (such as reference or drop).

select_container

Selects a container for adding or deleting elements:

select_container <resource_name> 

The resource_name argument defines the resource name of the object to be selected as the container. Use $null to unselect the currently selected container. The container is used as an implicit argument by commands that add or delete objects.

The selected container can be referenced in other script commands by using the "/" symbol:

# Set visibilty of the currently selected container to 1
set_value /Visibility d 1

select_element

Selects an element of a container object, such as a group or a viewport, or selects a control point of a polygon:

select_element <resource_name> <element_index> [<destination>]

The command arguments define the resource name of the container object and the index of the element inside the container to select. The destination parameter can specify a register to store the selected element using the %n notation, where n is a register's index in the range from 0 to 9. If the "." string is used as the destination parameter, or the parameter is omitted, the selected element is stored as the current object.

The stored element can then be accessed using the "." or "%n" notation, depending on where it was stored.

load_object

Loads an object from a file and selects it:

load_object <filename>

The loaded object is stored as the current object and can be accessed using the "." symbol.

set_resource_object

ADVANCED: Sets a new value of the specified resource of the selected object:

set_resource_object <resource_name> <resource_name_of_new_value>

The resource_name parameter defines the name of the selected object's attribute. The resource_name_of_new_value parameter specifies the object to be used as a new value of the attribute. Use "$null" to set the new attribute value to null.

reference

Increases the reference count of the current object:

reference 

This command uses the current object set by the select_object command as an implicit argument. If the current object is not set, an error is generated.

drop

Decreases the reference count of the current object:

drop 

This command uses the current object set by the select_object command as an implicit argument. If the current object is not set, an error is generated.

add_custom_property

Adds a custom property to an object:

add_custom_propery <target> <property_name> <type> <value> 

The target parameter specifies the resource path of the object the custom property is added to.

The property_name, type (d, s or g) and value parameters provide the corresponding attributes of the custom property. For custom properties of D and S types, the value parameter provides a double or string value, respectively. For custom properties of the G type, the value is supplied as a triplet of double values.

The added custom property is stored as the current object for a possible later use.

Refer to Drawing File Conversion Utility on page 339 for description of command-line options that control verbosity of the diagnostic output.

add_public_property

Adds a public property to an object attribute:

add_public_propery <target> <property_name> [<comment>]

The target parameter specifies the resource path of the object attribute the public property is added to.

The property_name and an optional comment parameters provide the corresponding attributes of the public property.

The added export tag is stored as the current object for a possible later use.

Note: The -setup command-line option of the utility must be used to set up the drawing hierarchy, which is needed to process this command in case when the target is specified using a named resource instead of a default resource name. Refer to Drawing File Conversion Utility on page 339 for description of this and other command-line options that control verbosity of the diagnostic output.

add_export_tag

Same as add_public_property, but also allows specifying an export tag type:

add_export_tag <target> <tag_name> <type> [<comment>]

The type parameter specifies the export tag type and may be set to the following string values: EXPORT, EXPORT_DYN or EXPORT_BOTH. Refer to Drawing File Conversion Utility on page 339 for description of command-line options that control verbosity of the diagnostic output.

The added export tag is stored as the current object for a possible later use.

add_data_tag

Adds a data tag to an object attribute:

add_data_tag <target> <tag_name> <tag_source> <access_type> 
[<comment>]

The target parameter specifies the resource path of the object attribute the data tag is added to. The tag_name, tag_source and an optional comment parameters provide the corresponding attributes of the public property. The access_type parameter specifies the tag's access type and may be set to the following values: 0 for INPUT tags, 1 for INIT tags and 2 for OUTPUT tags.

The $null string can be used to specify NULL values for string parameters, such as tag_name, tag_source and comment. Refer to Drawing File Conversion Utility on page 339 for description of command-line options that control verbosity of the diagnostic output.

The added data tag is stored as the current object for a possible later use.

get_export_tag

Finds a named custom property of an object:

get_export_tag <target> <property_name>

The target parameter specifies the resource path of the object to search for, and property_name specifies the name of the custom property. If found, the custom property is stored as the current object accessible via the "." symbol. If a named custom property is not found, NULL is stored.

delete_custom_property

Deletes a custom property from an object:

delete_custom_property <target> <property_name>

The target parameter specifies the resource path of the object to delete the custom property from, and property_name specifies the name of the custom property to be deleted.

Refer to Drawing File Conversion Utility on page 339 for description of command-line options that control verbosity of the diagnostic output.

delete_public_property
delete_export_tag

Deletes a public property or an export tag from an object's attribute:

delete_public_property <target>
delete_export_tag <target>

The target parameter specifies the resource path of the object attribute to delete the public property or the export tag from.

Refer to Drawing File Conversion Utility on page 339 for description of command-line options that control verbosity of the diagnostic output.

delete_data_tag

Deletes a data tag from an object's attribute:

delete_data_tag <target>

The target parameter specifies the resource path of the object attribute to delete the data tag from.

Refer to Drawing File Conversion Utility on page 339 for description of command-line options that control verbosity of the diagnostic output.

create

Creates an object of the specified type, and stores it as the current object for later use:

create <object_type> <name> <parameters>

The command arguments define the type of object and its name, as well as any parameters required by some object types. The rest of the attribute values may be set using the script's set_value command after the object has been created. The following lists the supported object types and parameters:

polygon

Parameters:

<num_points> x1 y1 z1 x2 y2 z2 ... xn yn zn

Creates a polygon. Requires the number of points and a list of vertex values for polygon points. The rest of the polygon's attributes may be set using the set_value command.

parallelogram

Parameters:

x1 y1 z1 x2 y2 z2 x3 y3 z3

Creates a parallelogram. Requires the list of values of the parallelogram's three vertices. The rest of the parallelogram's attributes may be set using the set_value command.

rectangle

Parameters:

x y width height

Creates a rectangle; requires the rectangle's origin, width and height parameters. The rest of the rectangle's attributes may be set using the set_value command.

text

Parameters:

<text_sring>

Creates a text object. Requires a text string. The position and other attributes of the text object may be set using the set_value command.

image

Parameters:

<image_file>

Creates an image object. Requires the name of an image file. The position and other attributes of the image object may be set using the set_value command.

arc

Parameters: None

Creates an arc. The arc's parameters may be set using the set_value command.

rounded

Parameters:

x1 y1 z1 x2 y2 z2 x3 y3 z3

Creates a rounded rectangle (or ellipse, depending on the values of the object's attributes). Requires a list of values for the object's three vertices. The rest of the attributes may be set using the set_value command.

marker

Parameters: None

Creates a marker. The marker's position and other attributes may be set using the set_value command.

viewport

Parameters: None

Creates a viewport. The viewport's position and the rest of its attributes may be set using the set_value command. The viewport may be selected as a container in order to add other objects to it.

group

Parameters: None

Creates a group. The group may be selected as a container in order to add other objects to it.

gis

Parameters:

<image_file>

Creates a GIS Object. Requires the name of a data file. The position and other attributes of the GIS Object may be set using the set_value command.

rendering_attr

Parameters: None

Creates a rendering object containing extended rendering attributes, such as gradient. The rendering may be added to an object by using the set_resource_object script command.

box_attr

Parameters: None

Creates a text box attributes object. The text box may be added to a text object by using the set_resource_object script command.

The created object is stored as the current object that can be accessed using the "." symbol.

add_new

Same as create, but also adds the created object to the selected container:

add_new <object_type> <name> <options>

This command has the same arguments as create; see description of the create command for details. The selected container is used as an implicit argument and must be set externally using the select_container command, otherwise an error is generated.

add_copy

Creates a strong copy of the current object, names it, adds it to the selected container and stores the copy as the current object:

add_copy <copy_name> 

The command argument define the name of the copy. Both the current object and the selected container are used as implicit arguments and must be set, otherwise an error is generated.

The command may be used repeatedly to add a number of copies, so that add_copy may be used instead of create in cases when a number of objects with similar attributes have to be created. The attributes of individual copies may be set using the set_value command that uses the "." symbol (current object) in the resource_name parameter to reference the newly added copy.

The attributes of the copies may be constrained by setting the attribute's Global flag to GLOBAL before copying the object.

For example, the following script may be used to add 3 text labels to the drawing:

# Select the $Widget viewport as a container to add the labels to
select_container $Widget
# Create a text object and set its font type and size.
# Creating the text selects it for use in add_copy.
create text Label
set_value ./FontType 2
set_value ./FontSize 2
# Set TextType to FIXED
set_value ./TextType 1
# Add three copies of the text setting their position and label.
# Adding a copy stores it as the current object, accessed as "." later.
add_copy Label1
set_value ./String This is Label1
set_value Point -500 500 0
add_copy Label2
set_value ./String This is Label2
set_value Point -500 0 0
add_copy Label3
set_value ./String This is Label3
set_value Point -500 -500 0

copy

Creates a copy of an object using a specified clone type and stores the copy as the current object:

copy <resource_name> <clone_type>

The resource_name argument defines an object to copy. The clone_type parameter may have the following values:

f - full clone
w - weak clone
s - strong clone
c - constrained clone

Use the "."symbol (current object) in the resource_name parameter of other commands to reference the cloned object.

delete

Deletes the current object from the selected container:

delete

The deleted object is still stored as the current object and may be added to another container. Both the current object and selected container are used as implicit arguments and must be set, otherwise an error is generated.

constrain_object

ADVANCED: Constraints one object's attribute to another:

constrain_object <from_resource_name> <to_resource_name>

The from_resource_name parameter specifies the attribute to be constrained and must use default attribute name to reference the attribute. The to_resource_name parameter specifies the attribute to constrain to.

5.3 Code Generation Utility

The GLG Code Generation Utility is used to convert a drawing file in one of the GLG file formats into plain C code. The generated code represents a memory image of the drawing, which can be later compiled and linked with the program in order to have all necessary drawings included in the executable. This increases the size of the executable file, but makes it unnecessary to supply additional files with an application.

NOTE: loading drawings from memory images doesn't support drawing compression. Save drawings with the drawing compression option disabled to use them as images.

The generated C code takes the form of an array, which is used by the GlgLoadObjectFromImage function. For more information about this function, see the GlgLoadObjectFromImage section of the GLG Intermediate and Extended API.

The Code Generation Utility is called gcodegen and requires three command line arguments:

gcodegen  in_file  out_file  variable

The arguments are defined as follows:

in_file
Specifies the name of the drawing file. This file may exist in any of the three GLG file formats (ASCII, binary, or extended).
out_file
Specifies the name of the file containing the generated code.
variable
Specifies the name of the program variable to be used for the array with produced data.

For example, the following command:

gcodegen  bar1.g bar1.c  bar1_data

produces a file called bar1.c containing the image of the bar1.g drawing in the following format:

/* Generated by the Generic Logic Toolkit */
long bar1_data[] = { <...data for the memory image are placed here...> 
};
long bar1_dataSize = sizeof( bar1_data );

The address of bar1_data array and the value of the bar1_dataSize variable are required to load a drawing from an image with the GlgLoadObjectFromImage function.

Code generation does not change the saved format of the drawing, so you must make sure the drawing file is in the correct format before running gcodegen. If the drawing was saved in the ASCII or EXTENDED format, the generated memory image is in that format, increasing the size of the produced code and making loading the drawing from the resulting image slower. Since the version of the linked memory image is guaranteed to match the version of the library after it has been linked correctly, it is safe to use the BINARY format, which makes loading drawings faster.

5.4 Drawing File Conversion Utility

The GLG Drawing File Format Conversion Utility is supplied with the Toolkit and can be used to convert a drawing file into a different saved format. It may also be used for setting resource values of GLG drawings in a batch mode using scripting commands.

The utility is a symbolic link to the GLG Builder executable and may be invoked in the following way:

gconvert <conversion utility options>

On Windows, symbolic links are not supported and the following command must be used:

GlgBuilder -convert <conversion utility options>

A GLG drawing can be saved in one of three different formats:

BINARY format is the fastest format to use for loading drawing files, but not compatible between hardware platforms with different binary data representations.
ASCII format is slower to load than BINARY and is compatible between different hardware platforms, but is not compatible between different versions of the Toolkit.
EXTENDED format is the slowest format to load, but provides the ability to transfer drawing files between different versions of the Toolkit as well as between different hardware platforms.

In addition to converting the drawing file format, the utility can be used to export or import strings and tags, modify drawings using the supplied script, adjust font sizes, as well as change other drawing settings.

On Unix/Linux, error and information messages are displayed in the terminal. On Windows, the messages are stored in the glg_error.log file in the GLG installation directory. The GLG_LOG_DIR environment variable may be set locally to define a different directory for the generated glg_error.log file.

The utility is invoked in the following way:

On Unix/Linux:    gconvert <options> file [file...]
On Windows:    GlgBuilder -convert <options> file [file...]

The file argument specifies the name of the drawing file to be converted. By default, converted files are saved under their original names, overwriting the original files. The available options are as follows:

-a
Converts file into the ASCII format. This is the default if none of the conversion options (-a, -b, or -e) are specified.
-b
Converts file into the BINARY format.
-e
Convert file into the EXTENDED format, is available with the Enterprise Edition of the Graphics Builder.
-c
Compresses the converted drawing. This is the default if none of the compression options (-c or -u) are specified.
-u
Saves the converted drawing uncompressed.
-r
If this option is specified, and the file argument is a directory, gconvert converts all the files in that directory, recursively descending into all subdirectories.
-p pattern
A regular expression pattern that can be used with the -r option for processing multiple files in the directory and all its subdirectories: only files with pathnames matching the pattern will be processed. The pattern can contain ? and * wildcard characters for matching a single or multiple characters in a filename. On Unix/Linux, the special characters must be either escaped using the backslash character (\), or the pattern string should be surrounded with quotes.
Pattern matching is performed on a complete filename path, not just on the filename. For example, while the *.g pattern will match files with the .g extension in any directory, the following pattern should be used to match files in any subdirectory with filenames starting with button and ending with the .g extension:
	"*/button*.g"        (Unix/Linux)
	*\button*.g          (Windows)
However, using the button*.g pattern instead of the above examples would not select any files, since it would not match a complete filename path that starts with the directory path.
The following pattern could be used to process button files in all subdirectories whose name starts with controls (i.e. controls1, controls2, controls_misc, etc.):
	"*/controls*/button\*.g"        (Unix/Linux)
	*\controls*\button*.g           (Windows)
-verbose-pattern-match
-vpm
Generates diagnostic information about files skipped due to a pattern mismatch.
-quiet
Suppresses information messages about processed files.
-o out_file
Defines the name of the output file. When this option is omitted, the converted file replaces the original file. This option is ignored if more than one input file is specified or if the -r option is used.
-export-strings strings_file
Instead of converting the drawing file to a new format, save all text strings defined in the drawing into the specified strings file.
-import-strings strings_file
In addition to converting the drawing file, replace its strings with the corresponding strings from the specified string translation file.
-export-tags tags_file
Instead of converting the drawing file to a new format, save all tags defined in the drawing into the specified tags file.
-import-tags tags_file
In addition to converting the drawing file, replace tags defined in the drawing with the corresponding tags from the specified tags file.
-multiple-export-import
-mei
When this option is specified, the supplied string_file and tag_file parameters of the strings and tags export/import options are interpreted as suffixes to be added to the input filename to form the filename of the corresponding strings or tags file for each of the processed files. In the absence of this option, the strings_file and tags_file parameters are treated literally, and the same strings or tags file is used for all input files.
-command "scripting_command"
Defines the set_value or set_tag command in the GLG Script Format to be executed on each converted drawing, and is used to change a resource value of the converted drawing. Refer to 1, 2
-script script_file
Defines the name of a script file in the GLG Script Format containing script commands to be executed on each converted drawing. It is used to change resource values of the converted drawing, as well as add or delete objects and properties from the converted file using advanced script commands. Refer to 1, 2
-print-commands
-pc
Used with the -script option to print script commands as they are executed to assist debugging of the script errors.
-new
Used with the -script option in cases when the file doesn't exist and the drawing will be created by the script. The new drawing will be saved into a file specified by the -o option.
-setup
Used with the -script option to set up the hierarchy of the loaded drawing before executing the script. This may be required to process the add_public_property and add_export_tag script commands.
-skip-missing-targets
-smt
Used with the -script option to skip missing targets of the commands that add or delete properties or tags. In the absence of the option, error messages are generated for missing targets of these commands.
-skip-duplicate-properties
-sdp
Used with the -script option to skip duplicate properties or tags in the commands that add properties or tags. In the absence of the option, error messages are generated when trying to add duplicate properties or tags.
-skip-missing-properties
-smp
Used with the -script option to skip missing properties or tags in the commands that delete properties or tags. In the absence of the option, error messages are generated when trying to delete non-existent properties or tags.
-verbose-skip
-vs
Used with the -script option to provide diagnostic output about skipped commands without generating an error.
-font-size-change int_value
Used to adjust the size of all text objects in the drawing by a specified integer value.
-set-utf8
Sets the UTF8Encoding flag of all S data objects in the drawing without re-encoding their strings.
-reset-utf8
Resets the UTF8Encoding flag of all S data objects in the drawing without re-encoding their strings.

For example,

gconvert *.g

converts all the GLG drawing files in the current directory (indicated with the ".g" suffix) into the ASCII format. The following command:

gconvert -b -r directory1

converts all the GLG files in the directory named "directory1" into the BINARY save format. All the GLG drawing files in any subdirectory will also be converted. The following command:

gconvert -o file2.g file1.g

converts the GLG drawing file named file1.g into the ASCII format and saves the new file under name file2.g.

The following command:

gconvert -command "set_value \$Widget/FillColor g 0. 0. 1." drawing.g

is an example of using the utility for setting resources of a drawing.


Generic Logic, Inc.
www.genlogic.com
PREV NEXT