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 to a drawing from a URL in web environment (Java Applet or ActiveX Control deployment). 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.

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.

Using datagen to Prototype Drawings in the Builder

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 and to ignore the -display, -server and -gsync options.

If a command different from $datagen is used in the Run dialog (for example, datagen without a leading dollar sign), the Builder spawns a new process with the given command. That process may be a custom program that uses the GLG Communication API to supply data to the drawing in the Builder, allowing to implement elaborate demo animations. If the process specified by the command cannot be started or not found, an error message will be displayed.

Using datagen in Stand-Alone mode

The datagen utility can also be used in stand-alone mode, in which case it uses the GLG Communication API to communicate with a viewport object displayed in the Builder or in any GLG containers outside the Builder.

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>

A GLG drawing may have several viewport objects inside it. Each viewport object may have act as a server to allow remote access to the resources of this specific viewport. Several instances of datagen may be run sequentially or simultaneously in order to communicate to more than one server of a drawing.

The name of the server is defined by the ServerName attribute of the viewport object and may be changed using the GLG Graphics Builder or the GLG Extended API. A viewport's communication server is disabled by default. Use the ServerEnabled attribute of the viewport to enable the server.

For example, invoking the utility in the following way:

datagen -server ValueGraph d 0 1 DataGroup/EntryPoint

causes the utility to generate random scalar values in the range [0,1] and to assign them to the DataGroup/EntryPoint resource. The data for setting the resource is sent to a viewport which has the ServerName attribute set to "ValueGraph."

The Data Generation Utility can be used with the GLG Graphics Builder to prototype drawing animation. The default server name of the Builder's main drawing area is "GLGDrawingAreaServer", which is also the default server name for datagen . The Builder must be in the Run mode for the server to be activated. If the Builder is not in Run mode, datagen produces an error message.

Command Line Arguments and Options

Datagen requires several parameters, including the name and type of the resource to be set, the low and high range for that resource, and the name of the communication server to which the data is to be sent.

datagen <options> [data_set] [data_set...]
<options>

are optional parameters applicable to all data sets and may include:

-display name

Specifies the X Windows display name where the GLG Wrapper Widget is displayed. The default display name is used by default. Do not use this argument on Microsoft Windows.

-server name

Specifies the server name to which the data is to be sent. If no name is specified datagen will use "GLGDrawingAreaServer." This is the default server name for the main viewports of the GLG Graphics Builder, the GLG Wrapper Widget and the GLG Custom Control. A server name is defined by the value of the ServerName attribute of the viewport.

-sleep num_secs

Specifies the number of seconds to sleep after each update

-gsync number

Specifies the number of updates after which the synchronization of the server and client processes is performed. The default value is 10. Specifying a large value speeds up the data transfer, but increases the server "lag" time. Specifying a value equal to 1 causes a synchronization to be performed 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 a script. The script may have commands for setting specific resources and updating the drawing. The script commands are listed in GLG Script on page 269. If this option is used, the data_set parameters are ignored and may be omitted.

-print scriptfile

Writes commands into a script file that will reproduce this invocation of datagen . 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.

-period number

Specifies a period of the sinusoidal or incremental data for the -sin 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
...

GLG Script

Overview

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

used with the -script option of the d atagen Data Generation Utility to prototype a drawing in the GLG Graphics Builder with custom data.

used to supply data from URLs to GLG components displayed in the browser and web environment, such as the GLG Bean and Java applet, the GLG Netscape plug-in and the GLG ActiveX control.

used with the -command and -script options of the gconvert File Conversion Utility to edit a collection of drawings using the batch mode or create a drawing using a script.

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

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 Setting the Drawing Resources of Using the C/C++ version of the Toolkit on page 19.

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 objects selected with the select_object or select_container commands of the extended command set, respectively. For example, ./FillColor may be used to access the FillColor attribute of the selected 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 with index=3.

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 GlgStrClone of Animating a GLG Drawing Using the Standard API.

sync

Synchronizes the connection between the data generating process and the drawing server.

sync

Issuing this command causes the utility to wait for the viewport communication server to finish updating before it sends new data. For more information about synchronizing this connection, see GlgSync of Animating a GLG Drawing 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 or ActiveX control, the data 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 or ActiveX control:

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 using a script. 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 extended command set introduces the notion of a selected object and selected container. The object or 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 selected object and container, respectively. For example, ./FillColor may be used to access the FillColor attribute of the selected 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 with index=3. Registers may also be used as an optional destination parameter of the select_object and select_container commands.

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.

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

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_register>]

The resource_name parameter defines the resource name of the object. Use the "."symbol in the resource_name parameter of other commands to reference the selected object. The selected object may be used as an implicit argument for other script commands (such as reference or drop). It may also be used by other script command by using "." as their resource_name parameter. An optional destination_register parameter may be used to store the object in a register. Registers are specified using the %n notation, where n is a register's index in the range from 0 to 9. Use $null to unselect the currently selected object.

select_container

Selects a container for adding or deleting elements:

select_container <resource_name>

The resource_name argument defines the resource name of the container. Use the "/"symbol in the resource_name parameter of other commands to reference the selected container. Commands for adding and deleting objects use the selected container as an implicit argument. Use $null to unselect the currently selected container.

select_element

Selects an element of a container:

select_element <resource_name> <element_index>
[<destination_register>]

The command arguments define the resource name of the container and the index of the element inside the container to select. Use the "."symbol in the resource_name parameter of other commands to reference the selected element, or use register. An optional destination_register parameter may be used to store the container in a register. Registers are specified using the %n notation, where n is a register's index in the range from 0 to 9.

load_object

Loads an object from a file and selects it:

load_object <filename>

Use the "."symbol in the resource_name parameter of other commands to reference the object loaded with this command.

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 selected object:

reference

This command uses the selected object as an implicit argument, which must be set.

drop

Decreases the reference count of the selected object:

drop

This command uses the selected object as an implicit argument, which must be set.

create

Creates an object of the specified type, and selects it 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 rectangular parallelogram; 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 of the rectangle'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.

add_new

Same as create, but also adds the 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.

add_copy

Creates a strong copy of the selected object, names it, adds it to the selected container and selects the copy for later use:

add_copy <copy_name>

The command argument define the name of the copy. 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. The attributes of the copies may be constrained by setting the attribute's Global flag to GLOBAL before copying the object. Both the selected object and selected container are used as implicit arguments and must be set externally.

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 selects it, so we can use "." to
# access it.
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 selects the copy for later use:

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 in the resource_name parameter of other commands to reference the cloned object.

delete

Deletes the selected object from the selected container:

delete

The deleted object is still selected and may be added to another container. Both the selected object and selected container are used as implicit arguments and must be set.

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.

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 GlgLoadObjectFromImage 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.

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.

The conversion utility is called "gconvert" and is invoked in the following way:

gconvert <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.

-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.

-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.

-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 Overview for more information.

-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 from the converted file using advanced script commands. Refer to Overview for more information.

-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.

-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.

 

C/C++ Graph Layout Component