PREV NEXT

Generic Logic, Inc. www.genlogic.com


2.4 Animating a GLG Drawing with Data Using the Standard API

The GLG Application Program Interface (API) provides a way for a user's C program to animate a GLG drawing. The API consists of a set of functions for querying and changing the resources of a GLG drawing. As a convenience to the programmer, it also provides some functions for frequently needed functions, such as specialized string manipulation, etc.

Note that the drawing must be displayed before it can be animated. For information on displaying a GLG drawing from a program, see Displaying a GLG Drawing on page 31. Though the details of displaying a drawing are platform-dependent, the functions described in this chapter are not. The syntax of the API described in this chapter is the same on X Windows or in Microsoft Windows.

There are three flavors of the GLG API:

The rest of this chapter describes functions of the GLG Standard API.

Overview

Once a GLG drawing is created and displayed, it is a simple matter to animate it. Animating a GLG drawing is done simply by manipulating its resources. This means that the only actions a program need take is to query or to set some resource value, and occasionally to redisplay the drawing with the new resource values.

The simplicity of operation means that the GLG API is quite a small one. It consists of the following functions:

The GLG Standard API also includes the following container methods described GLG Intermediate and Extended API:

The GlgSetResourceObject function of the Intermediate API may also be used with the Standard API for setting global configuration resources.

The GlgAddCallback function is used to add callbacks for handling user input in the form of input, selection and other events. While this function is a part of the GLG Standard API, it is described in detail in Callback Events on page 103.

GlgSetDefaultViewport is provided in the Windows version of the API and is used for setting a default drawing to be used by the GLG Wrapper Widget or GLG Custom Control.

The Standard API also includes functions specific to the Real-Time Chart and GIS objects. These functions are described in Real-Time Chart Functions on page 188 and GIS Object Functions on page 202.

The GLG Standard API also includes the following convenience and utility functions that simplify tasks common to GLG C programs.

Note: Several resources in a GLG drawing may affect the actual object hierarchy of the drawing. The Factor attribute of a series object, for example, controls the number of objects that appear to be members of that series. When manipulating the resources of a drawing with the GLG API, it is useful to set the resources that affect the object hierarchy first, then call GlgUpdate, and then set the resources that only affect the value of objects in that hierarchy. For more information about this distinction between resources, see the H and V Resources section of Integrating GLG Drawings into a Program.

Function Descriptions

To use any of the functions described in this chapter, the application program must include the function definitions from the GLG API header file. Use the following line to include these definitions:

#include "GlgApi.h"

Some resources have enumerated values. For example, the ScrollType resource of a graph may have values GLG_SCROLLED or GLG_WRAPPED. The GlgApi.h file has defined constants to use for setting these resource values.

Note that virtually all of the GLG API library functions have the same first argument: a GlgObject parameter called object. This argument is a handle pointing to an object in the drawing. Usually, it indicates the viewport object that is the widget in the drawing. This handle is returned by the platform-specific display functions described in Using the C/C++ version of the Toolkit. The object parameter may also provide an object ID of a graphical object inside the viewport.

The following describes the interfaces of the GLG Standard Library functions.

GlgAlloc

Allocates memory using the Toolkit's memory allocator.

void * GlgAlloc( size )
	GlgLong size;
Parameters
size
Specifies the size of a memory block in bytes.

The memory must be freed with GlgAlloc when it is no longer used.

GlgChangeObject

Sends a change message to the object without actually changing the object's properties.

void GlgChangeObject( object, resource_name )
	GlgObject object;
	char * resource_name;
Parameters
object
If the resource_name parameter is NULL, specifies the object to send the message to. If the resource_name parameter is not NULL, specifies the object's parent.
resource_name
If not NULL, specifies the resource name of the object inside the parent object specified by the object parameter.

The function may be used to force a drawable object (such as a viewport) to redraw its content. It may also be used to send a change message to the Factor attribute of a series object to force the series to recreate its instances without actually changing the value of the Factor. If a change message is sent to the ImageFile attribute of an image object, the image will reload the image file (the image's EnableCache attribute should be set to NO to disable cache for images that need to be reloaded).

GlgConcatResNames

Creates a composite resource name from two components.

char * GlgConcatResNames( resource_name1, resource_name2 )
	char * resource_name1, * resource_name2;
Parameters
resource_name1
Specifies the first path component.
resource_name2
Specifies the second path component.

This function creates and returns a resource name formed by concatenating the two components with the / character between them. Either argument may be NULL, in which case the returned string will precisely equal the input value of the other argument. The string containing the returned resource name should be freed later with the GlgFree function.

For example, the following code fragment:

char * resource_name;

resource_name = 
		GlgConcatResNames( "DataGroup", "DataSample2" );
printf( "resource_name = %s\n", resource_name );
GlgFree( resource_name );

produces the following output:

resource_name = DataGroup/DataSample2

Multiple calls to the GlgConcatResNames function may be used to create composite names from more than two components:

char
	* temp_name,
	* resource_name;

temp_name = 
		GlgConcatResNames( "DataGroup", "DataSample2" );
resource_name = GlgConcatResNames( temp_name, "Value" );
GlgFree( temp_name )
printf( "resource_name = %s\n", resource_name );
GlgFree( resource_name );

produces the following output:

resource_name = DataGroup/DataSample2/Value

GlgConcatStrings

Concatenates two character strings.

char * GlgConcatStrings( string1, string2 )
	char * string1, string2;
Parameters
string1, string2
The strings to be concatenated.

This function creates a new string from two input strings. Either input string may be NULL, in which case the returned string is a copy of the non-NULL input string. If both strings are NULL, then NULL is returned. The output of this function must be freed with the GlgFree function. That function also understands null data, so the following code may be used without needing to check for NULL values:

string3 = GlgConcatStrings( string1, string2 );
	...
	GlgFree( string3 );

GlgCreateIndexedName

Creates a string with a name for an enumerated resource.

char * GlgCreateIndexedName( template_name, resource_index )
	char * template_name;
	GlgLong resource_index;
Parameters
template_name
A character string containing the template name to be expanded. This name uses the % character to define the expansion position.
resource_index
Specifies the number to use for expanding a % character in the template name.

This function creates and returns a resource name by replacing the first (leftmost) occurrence of the % expansion character within the template name with the number corresponding to the resource_index parameter. If the template name does not contain the expansion character, the number is added to the end of the name. The returned expanded name should later be freed with the GlgFree function.

Example

The following code fragment:

char * name;
int i;
for( i=0; i<3; ++i )
{
	name = GlgCreateIndexedName( "XLabelGroup/XLabel%/String", i );
	printf( "Name: %s\n", name );
	GlgFree( name );
}

produces the following output:

Name: XLabelGroup/XLabel0/String
Name: XLabelGroup/XLabel1/String
Name: XLabelGroup/XLabel2/String

The GlgCreateIndexedName function may be used repeatedly if a template name has more than one expansion character. For example, the following code fragment:

char * name1, * name2;
name1 = 
	GlgCreateIndexedName( "Graph%/DataSample%/Value", 4 );
name2 = GlgCreateIndexedName( name1, 5 );
GlgFree( name1 );
printf( "Name: %s\n", name2 );
GlgFree( name2 );

produces the following output:

Name: /Graph4/DataSample5/Value

GlgCreateTagList

Creates and returns a list of tags.

GlgObject GlgCreateTagList( object, unique_tag_sources )
	GlgObject object;
	GlgBoolean unique_tags;
Parameters
object
An object whose tags are queried. The top level viewport may be used to query the list of tags of the whole drawing.
unique_tag_sources
If set to GlgTrue, only one instance of tags with same tag source will be added to the list. If the parameter value is set to GlgFalse, all instances with the same tag source will be reported.

This function creates and returns a group containing all named tag objects, or NULL if no tags were found. Each element of the group is an attribute object whose tag field is not empty. The GlgGetElement and GlgGetSize functions may be used within the Standard API to handle the returned group object. The returned group object must be dereferenced using the GlgDropObject function when it is no longer needed.

If an object is not a viewport, the returned list of tags will include only the tags contained inside the object. For a viewport, the tag list will contain all tags defined in the viewport's drawing.

Example

The following code fragment prints tag information for all tags defined in the drawing:

char * tag_name, * tag_source;
int i, size;
GlgObject tag_list, tag_object;

tag_list = GlgCreateTagList( viewport, GlgFalse );
if( tag_list )
{
	size = GlgGetSize( tag_list );
	for( i=0; i<size; ++i )
	{
		tag_object = GlgGetElement( group, i );
		GlgGetSResource( tag_object, "TagName", &tag_name );
		GlgGetSResource( tag_object, "TagSource", &tag_source );
		printf( "TagName: %s, TagSource: %s\n", tag_name, tag_source );
	}
	GlgGropObject( tag_list );
}

GlgError

Displays error and information messages using the currently installed error handler.

void GlgError( error_type, message )
	GlgErrorType error_type;
	char * message;
Parameters
error_type
Specifies the type of the message, may have the values listed below. The list includes a description of the action performed by the default error handler for each message type:
GLG_INTERNAL_ERROR
reserved for the Toolkit's internal use; generates an error message, emits an audio beep and logs the error into the glg_error.log file
GLG_USER_ERROR
generates an error message and emits an audio beep; on Windows, also logs the error into the glg_error.log file
GLG_WARNING
generates a warning message and emits an audio beep; on Windows, also logs the warning into the glg_error.log file
GLG_INFO
on Windows, logs the message into the glg_error.log file; on Unix/Linux, prints the message on the terminal.
The location of the glg_error.log file is determined by the GLG_LOG_DIR and GLG_DIR environment variables as described in 1, 2
message
The message to be displayed.

GlgExportStrings

Writes all text strings defined in the drawing into a string translation file:

GlgLong GlgExportStrings( object, filename, separator1, separator2 )
	GlgObject object;
	char * filename;
	GlgLong separator1;
	GlgLong separator2;
Parameters
object
Specifies a viewport or drawing object whose text strings to export.
filename
Specifies the string translation file to write.
separator1, separator2
Defines characters to be used as string separators in the generated file.

The function returns the number of exported strings or -1 in case of an error. Refer to Localization Support on page 230 of the GLG User's Guide and Builder Reference Manual for information about the string translation file format.

GlgExportTags

Writes tag names and tag sources of all tags defined in a drawing into a file:

GlgLong GlgExportTags( object, filename, separator1, separator2 )
	GlgObject object;
	char * filename;
	GlgLong separator1;
	GlgLong separator2;
Parameters
object
Specifies a viewport or drawing object whose tags to export.
filename
Specifies the tag file to write.
separator1, separator2
Defines characters to be used as string separators in the generated file.

The function uses the same file format as the GlgExportStrings function. Refer to Localization Support on page 230 of the GLG User's Guide and Builder Reference Manual for information about the file format.

The function returns the number of exported tags or -1 in case of an error.

GlgFindFile

Searches for a file, first in the current directory, then in the directory provided by the path parameter and then in the GLG search path. Returns a file path name if the file was found, on NULL otherwise.

void GlgFindFile( filename, path, check_glg_path )
	char * filename;
	char * path;
	GlgBoolean check_glg_path;
Parameters
filename
Specifies a relative filename to search for.
path
Specifies an additional search path to be searched before the GLG search path.
check_glg_path
If set to GlgTrue, the GLG search path will be included in the search.

GlgFree

Frees the memory used to store character strings.

void GlgFree( pointer )
	char * pointer;
Parameters
pointer
Specifies a character string that is no longer needed by the application.

This function is used to free memory allocated by GlgAlloc and GLG string utilities. This is not to be used to free the memory occupied by any GLG object (GlgObject). Use GlgDropObject and GlgReferenceObject to manage those objects. The function checks for NULL address pointers, and will not fail or generate an error message if one is passed.

GlgGetDataType

Returns the data type (GLG_D, GLG_S or GLG_G) of a data or attribute object.

GlgDataType GlgGetDataType( data_object )
	GlgObject data_object;
Parameters
data_object
Specifies a data or attribute object to query.

GlgGetDResource

GlgGetDTag

Return the current value of a scalar resource or tag.

GlgBoolean GlgGetDResource( object, resource_name, d_value_ptr )
	GlgObject object;
	char * resource_name;
	double * d_value_ptr;
GlgBoolean GlgGetDTag( object, tag_source, d_value_ptr )
	GlgObject object;
	char * tag_source;
	double * d_value_ptr;

Parameters
object
Specifies a GLG object.
resource_name, tag_source
Specifies the name of the double resource or tag to query.
d_value_ptr
Specifies a pointer with which to return the resource or tag value.

If a scalar resource or tag with the input name exists, this function copies its current value into the address specified by d_value_ptr and returns GlgTrue, otherwise it generates an error message and returns GlgFalse.

GlgGetGResource

GlgGetGTag

Return the set of three values making up a geometrical resource or tag:

GlgBoolean GlgGetGResource( object, resource_name, g_value1_ptr, 
g_value2_ptr, g_value3_ptr )
	GlgObject object;
	char * resource_name;
	double * g_value1_ptr, * g_value2_ptr, * gvalue3_ptr;
GlgBoolean GlgGetGTag( object, tag_source, g_value1_ptr, g_value2_ptr, 
g_value3_ptr )
	GlgObject object;
	char * tag_source;
	double * g_value1_ptr, * g_value2_ptr, * gvalue3_ptr;
Parameters
object
Specifies a GLG object.
resource_name, tag_source
Specifies the name of the geometrical resource or tag to query.
g_value0_ptr, g_value1_ptr, g_value2_ptr
Specify pointers to the locations to which the XYZ or RGB values of the resource or tag are returned.

If a geometrical resource or tag with the input name exists, this function copies its current three values to the addresses specified with the g_value pointers and returns GlgTrue. Otherwise it generates an error message and returns GlgFalse.

For a geometrical point, g_value0_ptr, g_value1_ptr and g_value2_ptr are set to the X, Y and Z coordinates of the point, respectively. For a color resource or tag, they will be set to the R, G and B values of the color, respectively.

GlgGetLParameter

Queries a value of a global parameter.

GlgBoolean GlgSetLParameter( char * name, GlgLong * value )
	char * name;
	GlgLong value;
Parameters
name
Specifies parameter name.
value
A pointer used to return a parameter's value.

Refer to the Appendix D: Global Parameters section on page 478 for information on available global parameters. The function returns GlgTrue on success.

GlgGetMajorVersion

GlgGetMinorVersion

Return library's major and minor version numbers.

GlgLong GlgGetMajorVersion( void )
GlgLong GlgGetMinorVersion( void )

GlgGetModifierState

Return the state of the requested modifier.

GlgBoolean GlgGetModifierState( modifier )
	GlgModifierType modifier;
Parameters
modifier
Specifies a modifier to query: GLG_SHIFT_MOD, GLG_CONTROL_MOD or GLG_DOUBLE_CLICK_MOD.

GlgGetNativeComponent

Returns an ID of a native windowing system component used to render the viewport:

GlgAnyType GlgGetNativeComponent( GlgObject object, 

char * resource_name, GlgComponentQueryType type )
Parameters
object
Specifies a viewport or a viewport's parent.
resource_name
Specifies a resource name for accessing the child viewport inside its parent. Use NULL when the object parameter specifies the viewport.
type
Specifies the type of a component to retrieve:
GLG_WIDGET_QUERY
Returns an ID of the native component used to render the viewport:
a widget ID when using libglg.a on X Windows
when using libglg_x11.a on X Windows (Qt/GTK integration), returns a viewport's X11 window ID.
This window ID will be NULL if a viewport uses a native Qt widget, such as a text box or a list (see the Native Widgets section on page 260 GLG User's Guide and Builder Reference Manual).
a window handle on Windows.
GLG_SHELL_QUERY
Returns an ID of the viewport's top-level parent:
a widget ID of the top level shell the viewport belongs to when using libglg.a on
X Windows
a window handle of the top-level window on Windows
when using libglg_x11.a on X Windows (Qt/GTK integration), returns an X11 window ID of the top parent's Qt/GTK widget, or an X11 window ID of the first encountered parent viewport with ShellType set to either GLG_DIALOG_SHELL or GLG_APPLICATION_SHELL.
GLG_CHILD_WIDGET_QUERY
When using libglg.a on X Windows, returns a widget ID of a child widget inside a scroll pane for a native widget that uses a scroll pane, such as a text edit or list widget. For these widgets, GLG_WIDGET_QUERY returns the widget ID of the scroll pane, and GLG_CHILD_WIDGET_QUERY returns the list or text widget itself.
GLG_V_SCROLLBAR_QUERY
GLG_H_SCROLLBAR_QUERY
When using libglg.a on X Windows, returns a widget ID of a requested scrollbar widget for native widgets that use a scroll pane.
GLG_DISPLAY_QUERY
On X Windows, returns the display pointer for the viewport's window.
GLG_WINDOW_QUERY
on X Windows, returns an X11 window ID of the viewport's window.
In Qt integration that uses libglg_x11.a library on X Windows, this window ID will be NULL for a viewport that uses a native Qt widget, such as a text box or a list. For these viewports, GLG_NB_WIDGET_QUERY may be used to get the Qt widget used by the viewport.
on Windows, returns a viewport's window handle (same as GLG_WIDGET_QUERY).
GLG_NB_WIDGET_QUERY
In Qt integration that uses libglg_x11.a library on X Windows, returns a Qt widget used by the viewport, or NULL if the viewport does not use a native Qt widget.
GLG_TOP_WIDGET_QUERY
In Qt/GTK integration that uses libglg_x11.a on X Windows, returns Qt/GTK parent widget of the top viewport, such as QGlgWidget or gtk_glg.

The function returns NULL if the requested component doesn't exist in the current runtime environment or hasn't yet been created.

GlgGetObjectName

Returns an object's name. It returns a pointer to the internal string that should not be modified or freed.

char * GlgGetObjectName( object )
	GlgObject object;
Parameters
object
Specifies an object to query.

GlgGetObjectType

Returns an object's type (GLG_PLOYGON, GLG_TEXT, etc.).

GlgObjectType GlgGetObjectType( object )
	GlgObject object;
Parameters
object
Specifies an object to query.

GlgGetSelectionButton

Queries which mouse button initiated the selection callback.

GlgLong GlgGetSelectionButton( void )

This function returns 1, 2, or 3 to indicate which button caused the callback to be invoked. It may be used only inside a selection callback function. If it is called outside of a selection callback, the return value is undefined.

GlgGetSResource

GlgGetSTag

Return the value of a string resource or tag.

GlgBoolean GlgGetSResource( object, resource_name, s_value_ptr )
	GlgObject object;
	char * resource_name;
	char ** s_value_ptr;
GlgBoolean GlgGetSTag( object, tag_source, s_value_ptr )
	GlgObject object;
	char * tag_source;
	char ** s_value_ptr;
Parameters
object
Specifies a GLG object.
resource_name, tag_source
Specifies the name of the string resource or tag to query.
s_value_ptr
A pointer with which to return the resource or tag value.

If a string resource or tag with the given name exists, this function copies the current resource or tag string into an internal buffer, sets the s_value_ptr to point to the buffer and returns GlgTrue. Otherwise it returns GlgFalse.

Warning: The returned pointer points to GLG internal data structures and should not be modified. The pointer is valid only immediately after a call to the GlgGetSResource function. To store the returned string, create a copy of it using the GlgStrClone function.

GlgHasResourceObject

Checks if a named resource exists:

GlgBoolean GlgHasResourceObject( object, resource_name )
	GlgObject object;
	char * resource_name;
Parameters
object
Specifies a GLG object whose resource or tag to query.
resource_name
Specifies the name of the resource object to query.

If a resource object with the input name exists, this function returns GlgTrue, otherwise it returns GlgFalse.

GlgHasTagName

GlgHasTagSource

Check if a tag with a specified tag name or tag source exists:

GlgBoolean GlgHasTagName( object, tag_name )
	GlgObject object;
	char * tag_name;
GlgBoolean GlgHasTagSource( object, tag_source )
	GlgObject object;
	char * tag_source;
Parameters
object
Specifies a GLG object whose tag to query.
tag_name, tag_source
Specifies the tag name or tag source to query.

If a tag with the input tag name or tag source exists, this function returns GlgTrue, otherwise it returns GlgFalse.

GlgImportStrings

Replaces text strings in the drawing with the strings loaded from a string translation file:

GlgLong GlgImportStrings( object, filename )
	GlgObject object;
	char * filename;
Parameters
object
Specifies the viewport or drawing object whose text strings to replace.
filename
Specifies the string translation file to load.

The function returns the number of imported strings or -1 in case of an error. Refer to Localization Support on page 230 of the GLG User's Guide and Builder Reference Manual for information about the string translation file format.

GlgImportTags

Replaces tag names and tag sources of tags in a drawing with information loaded from a tag translation file:

GlgLong GlgImportTags( object, filename )
	GlgObject object;
	char * filename;
Parameters
object
Specifies the viewport or drawing object whose tag to change.
filename
Specifies the tags translation file to load.

The function uses the same file format as the GlgImportStrings function. Refer to Localization Support on page 230 of the GLG User's Guide and Builder Reference Manual for information about the file format.

The function returns the number of imported tags or -1 in case of an error.

GlgOnDrawMetafile

.Provides MFC metafile output support (Windows only). Is used by the MFC container's OnDrawMetafile method to produce metafile for the GLG child window.

GlgBoolean GlgOnDrawMetafile( viewport, print_dc )
	GlgObject viewport;
	HDC print_dc;
Parameters
viewport
Specifies a viewport object.
print_dc
Specifies the printing device context for metafile output.

Returns GlgTrue if metafile generation succeeds, otherwise returns GlgFalse.

GlgOnPrint

Provides MFC printing support (Windows only). Is used by the MFC container's OnPrint method to print GLG child window.

GlgBoolean GlgOnPrint( viewport, print_dc )
	GlgObject viewport;
	HDC print_dc;
Parameters
viewport
Specifies a viewport. If viewport is a light viewport, the output will be generated for its parent viewport.
print_dc
Specifies the printing device context.

Returns GlgTrue if printing succeeds, otherwise returns GlgFalse.

GlgPreAlloc

Preallocates memory under the control of mission critical real-time applications:

GlgBoolean GlgPreAlloc( size, type )
	GlgLong size;
	GlgPreAllocType type;
Parameters
size
Specifies the size of the memory to allocate.
type
Specifies the allocation type. The following lists available types and the meaning of the corresponding size parameter:

Mission-critical applications can use this function to preallocate memory on start-up and then allocate more memory as needed outside of the application's critical sections. The GlgGetLParameter function can be used to query the amount of spare memory in the preallocated memory blocks.

If the buffers are not preallocated, they are allocated and automatically adjusted as needed.

The function returns GlgTrue on success.

GlgPrint

Generates a PostScript output of the current state of the viewport's graphics.

GlgBoolean GlgPrint( object, file, xpos, ypos, width, height, portrait, 
      stretch )
	GlgObject object;
	char * file;
	double xpos, ypos, width, height;
	GlgBoolean portrait, stretch;
Parameters
object
Specifies a viewport. If object is a light viewport, the output will be generated for its parent viewport.
file
Specifies a filename in which to save the generated PostScript output.
xpos, ypos, width, height
Specify the rectangle on the page that will contain the Postscript output: xpos and ypos define the coordinates of the upper left corner of the rectangle, width and height define its dimensions. All coordinates are specified in the world coordinate system, which maps a rectangle defined by the points (-1000 -1000) and (1000 1000) to a page.
portrait
Specifies the orientation of the PostScript output on the page. If the value of this parameter is GlgTrue, a portrait orientation is used. Otherwise, a landscape orientation is used.
stretch
Specifies whether or not PostScript output should be stretched when mapping it to the specified rectangle. If the value of this parameter is GlgTrue, the PostScript output will be stretched to fit the rectangle exactly. This may distort printed objects. If the value is GlgFalse, the ratio of height to width of the widget will be preserved in the PostScript output. This may leave some parts of the specified rectangle blank.

This function saves a PostScript image of the current state of the drawing into the specified file. The xpos, ypos, 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 xpos and ypos 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 a page. The portrait parameter defines portrait (TRUE) or landscape (FALSE) mode. If the stretch parameter is set to GlgFalse, the X/Y ratio of the drawing is preserved.

The drawing's hierarchy must be set up in order to generate PostScript output. Use the GlgUpdate function before calling GlgPrint to make sure the widget is up to date. The function returns GlgTrue if PostScript output is successfully written into the file.

GlgReset

Reinitializes the widget.

GlgBoolean GlgReset( object )
	GlgObject object;
Parameters
object
Specifies a viewport object.

Calling GlgReset restores all volatile resource changes to the values the resources had when the widget was first drawn. This discards currently displayed graph data, unless the data group series of a graph was exploded.

The function returns GlgTrue if the widget is successfully reinitialized; otherwise it returns GlgFalse.

GlgSaveImage

GlgSaveImageCustom

Generate a JPEG image of the current state of the viewport's graphics and saves it into a file:

GlgBoolean GlgSaveImage( object, resource_name, filename, format )
	GlgObject object;
	char * resource_name;
	char * filename;
	GlgImageFormat format;
GlgBoolean GlgSaveImageCustom( object, resource_name, filename,

                   format, x, y, width, height, gap )
	GlgObject object;
	char * resource_name;
	char * filename;
	GlgImageFormat format;
	GlgLong x, y, width, height, gap;
Parameters
object
Specifies a viewport object.
resource_name
Specifies the resource name of a child viewport whose image to save, or NULL to save the image of the viewport specified by the object parameter. The resource name is relative to the viewport specified by the object parameter.
filename
Specifies a filename in which to save the generated image.
format
Specifies an image format, must be GLG_JPEG or GLG_PNG.
x, y, width, height
Specifies the area of the drawing for generating an image with GlgSaveImageCustom, which can be bigger or smaller than the visible area of the viewport. The x and y parameters define the offset in screen pixels relative to the origin of the viewport's window, which has screen coordinates of (0,0). The width and height parameters define the width and height of the generated image in screen pixels. These parameters may be obtained by querying the bounding box of either the whole drawing or of the area of the drawing for which the image needs to be generated.
If the width and height parameters are 0, the image for the whole drawing is generated using the drawing's bounding rectangle as the image generation extent. If the viewport is zoomed in, this area may be significantly bigger than the visible area of the viewport, and the image size may be quite large. The viewport's zoom factor defines the scaling factor for objects in the drawing when the image is saved.
gap
Specifies the padding space between the extent of the drawing and the border of the generated image in case when zero width and height parameters are specified for GlgSaveImageCustom.

For a light viewport, the output will be generated for its parent viewport.

The GlgSaveImage function saves image of the visible part of the viewport, clipping out the parts of the drawing that extends outside of it. The GlgSaveImageCustom saves the whole drawing without such clipping (if width and height parameters are 0), or saves just the specified area of the drawing.

The drawing's hierarchy must be set up in order to generate an image. The function returns GlgTrue if the image was successfully generated.

GlgGenerateImage

GlgGenerateImageCustom

Creates an image of the current state of the viewport's graphics and returns it as a pixmap on Linux/Unix, or a bitmap on Windows. The PIXMAP is defined as Pixmap on Linux/Unix, and HBITMAP on Windows.

PIXMAP GlgGenerateImage( object, resource_name, image )
	GlgObject object;
	char * resource_name;
	PIXMAP image;


PIXMAP GlgGenerateImageCustom( object, resource_name, pixmap,

                    x, y, width, height, gap )
	GlgObject object;
	char * resource_name;
	PIXMAP image;
	GlgLong x, y, width, height, gap;
Parameters
object
Specifies a viewport object.
resource_name
Specifies the resource name of a child viewport whose image to generate, or NULL to generate the image of the viewport specified by the object parameter. The resource name is relative to the viewport specified by the object parameter.
image
If not NULL, specifies the pixmap or the bitmap to be used. This pixmap or bitmap will be filled and returned instead of creating and returning a new pixmap or bitmap.
x, y, width, height, gap
Specify parameters of a custom image. Refer to the GlgSaveImageCustom function described above for detailed information.

GlgSendMessage

Sends a message to an object to request some action to be performed.

GlgAnyType GlgSendMessage( object, resource_name, message, 

               param1, param2, param3, param4 )
	GlgObject object;
	char * resource_name;
	char * message;
	GlgAnyType param1, param2, param3, param4;

Refer to Input Objects on page 237 of the GLG User's Guide and Builder Reference Manual for a list of messages supported by each type of the available input handlers.

Parameters
object
Specifies an object to send the message to. In most cases, it is a viewport with a GLG input handler attached, such as a button or a slider.
resource_name
If the parameter is set to NULL, the message is sent to the object specified by the object parameter. Otherwise, the message is sent to the object's child specified by the resource name. The resource path is relative to the object parameter. For example, to send the message to a viewport's handler, use the viewport as the object parameter and "Handler" as the value of the resource_name parameter.
message
A string defining the type of the message.
param1, param2, param3, param4
Message parameters whose type depends on the message type.

The function serves as an escape mechanism for actions that can not be easily accomplished by setting or querying a single resource, such us adding items to a list widget or querying a state of a multiple-selection list. For messages that execute some query, the function returns the query result, otherwise it just executes the requested action.

Refer to Input Objects on page 237 of the GLG User's Guide and Builder Reference Manual for the description of the function's parameters and returned value for each of the GLG input handlers.

GlgSetAlarmHandler

Sets the function that will process alarm messages.

void GlgSetAlarmHandler( alarm_handler )
	GlgAlarmHandler alarm_handler;
Parameters
alarm_handle
Specifies a global function that will be invoked to process all alarm messages generated by application's drawings.

An alarm handler has the following function prototype:

typedef void (*GlgAlarmHandler)( data_object, alarm_object, 
alarm_label, action, subaction, reserved )
	GlgObject data_object;
	GlgObject alarm_object;
	char * alarm_label;
	char * action;
	char * subaction;
	GlgAnyType reserved;

The data_object parameter is the resource whose value has changed. The alarm_object parameter is the alarm attached to the data_object to monitor its value; it is the alarm that generated the alarm message. The alarm_label parameter supplies the AlarmLabel used to identify alarm_object. The action and subaction parameters provide details about the condition that caused the alarm; refer to the Alarm Messages section on page 197 of the GLG User's Guide and Builder Reference Manual for more information.

An alarm handler should not change object hierarchy by actions such as adding or deleting objects from the drawing or changing a factor of a series object.

GlgSetBrowserObject

Sets the object for browsing with the GLG resource, tag or alarm browser widgets.

void GlgSetBrowserObject( browser, object )
	GlgObject browser;
	GlgObject object;
Parameters
browser
Specifies a viewport of the browser widget.
object
Specifies an object to browse.

The browser will display the object's resources, tags or alarms.

GlgSetBrowserSelection

Sets a new value of a browser's selection and filter text boxes for resource, tag, alarm and data browsers after the browser object has been set up. Setting a new selection will display a new list of matching entries.

void GlgSetBrowserSelection( object, resource_name, selection, 

filter )
	GlgObject object;
	char * resource_name;
	char * selection;
	char * filter;
Parameters
object
Specifies a viewport of the browser widget or its parent.
resource_name
Specifies a resource path to access the browser from the parent supplied by the object parameter, or NULL if the object parameter supplies the browser's viewport.
selection
Specifies a new selection string.
filter
Specifies a new filter string.

The browser will display a new list of matching items. Before the browser's drawing hierarchy has been set up, the selection and filter may be set via corresponding resources. To change selection or filter after hierarchy setup, this function should be used.

GlgSetCursor

Sets a custom cursor for a drawing or one of its child viewports (Windows only).

GlgBoolean GlgSetCursor( viewport, resource_name, cursor )
	GlgObject viewport;
	char * cursor
	GlgLong cursor;
Parameters
viewport
Specifies a viewport.
resource_name
Specifies the resource name of a child viewport to set the cursor of, or NULL to set the cursor of the viewport specified by the viewport parameter. The resource name is relative to the viewport specified by the viewport parameter.
cursor
Specifies one of the predefined Windows cursor types.

The custom cursor will be used when the mouse moves inside the viewport the custom cursor is assigned to.

GlgSetDefaultViewport

Sets a drawing to be used by the GLG Custom Control on Windows.

void GlgSetDefaultViewport( viewport )
	GlgObject viewport;
Parameters
viewport
Specifies a GLG viewport object to be used as a widget. The viewport object may be loaded using GlgLoadWidgetFromFile, GlgLoadWidgetFromImage, or GlgLoadWidgetFromObject functions. It may also be created programmatically using functions from the GLG Extended API.

One instance of a viewport may be used to create only one GLG Custom Control since every control needs its own copy of the viewport. To create several custom controls with the same drawing, load a new instance of the drawing for each control or use GlgCopyObject to create instances of the drawing, then select them using GlgSetDefaultViewport before creating each control or widget. This function references the viewport object.

GlgSetDResource

GlgSetDResourceIf

GlgSetDTag

Set a new value for a resource or tag of type D. For information about the data types used by GLG objects, see Structure of a GLG Drawing.

GlgBoolean GlgSetDResource( object, resource_name, d_value )
	GlgObject object;
	char * resource_name;
	double d_value;
GlgBoolean GlgSetDResourceIf( object, resource_name, d_value, 
if_changed )
	GlgObject object;
	char * resource_name;
	double d_value;
	GlgBoolean if_changed;
GlgBoolean GlgSetDTag( object, tag_source, d_value, if_changed )
	GlgObject object;
	char * tag_source;
	double d_value;
	GlgBoolean if_changed;
Parameters
object
Specifies a GLG object.
resource_name, tag_source
Specifies the name of the scalar resource or tag to be set. For tags, all tags with the specified tag_source will be set to the supplied value.
d_value
Specifies a new value for the resource or tag.
if_changed
If set to GlgFalse, the graphical updates will be performed even if the new value is the same as the old one (equivalent to GlgSetDResource function). Setting the parameter to GlgTrue optimizes performance of applications that set resource or tag values regardless whether the values have changed. The parameter is ignored when updating chart entry points to allow plotting straight lines when the plotted value does not change over time.

If a scalar resource or tag with the given name exists, this function sets it to a new value and returns GlgTrue, otherwise it prints an error message and returns GlgFalse.

GlgSetEditMode

Sets the viewport's edit mode which disables input objects in the viewport while the drawing is being edited.

GlgBoolean GlgSetEditMode( viewport, resource_name, edit_mode )
	GlgObject viewport;
	char * resource_name;
	GlgBoolean edit_mode;
Parameters
viewport
Specifies a viewport object (either a viewport or a light viewport).
resource_name
Specifies the resource name of a child viewport to set the editing mode of, or NULL to set the editing mode of the viewport specified by the viewport parameter. The resource name is relative to the viewport specified by the viewport parameter.
edit_mode
GlgTrue to set the editing mode, or GlgFalse to reset.

If the viewport's edit mode is turned on, the input objects in the viewport will not react to the mouse and keyboard events. The rest of the input objects outside of the viewport will still be active. The edit mode is usually set for viewports that serve as a drawing area; the edit mode ensures that the input objects do not react to mouse clicks when they are dragged with the mouse to a new position. This is similar to the behavior of the Builder's Drawing Area.

The edit mode is global and may be set only for one viewport used as a drawing area. Setting the edit mode of a new viewport resets the edit mode of the previous viewport. The viewport's edit mode is inherited by all its child viewports. The function returns GlgTrue for success, otherwise it generates an error message and returns GlgFalse.

GlgSetErrorHandler

Replaces the GLG Toolkit error handler and returns the previous error handler.

GlgErrorHandler GlgSetErrorHandler( new_handler )
	GlgErrorHandler new_handler;
Parameters
new_handler
Specifies a new error handler, supplied by the user, to be called on an error condition. This does not include internal errors of the GLG Toolkit, if any are detected: they are still reported using the default handler.

The function prototype for the new handler is as follows:

void new_handler( error_message, error_type )
	char * error_message;
	GlgErrorType error_type;

The error_type parameter may have the following values:

GLG_INTERNAL_ERROR
GLG_USER_ERROR
GLG_WARNING
GLG_INFO

Refer to the description of the GlgError function on page 71 for more information on the error types.

For more information about error handlers, see the Error Processing and Debugging section on page 49.

GlgSetFocus

Sets the keyboard focus to an object's viewport. If the object is a viewport, sets the focus to this viewport, otherwise sets the focus to the parent viewport of the object.

void GlgSetFocus( object, resource_name )
	GlgObject object;
	char * resource_name;
Parameters
object
Specifies an object.
resource_name
Specifies the resource name of a child object to use, or NULL to use the object specified by the object parameter. The resource name is relative to the object specified by the object parameter.

GlgSetGResource

GlgSetGResourceIf

GlgSetGTag

Set the values of a geometrical resource or tag.

GlgBoolean GlgSetGResource( object, resource_name, g_value1, g_value2, 
g_value3 )
	GlgObject object;
	char * resource_name;
	double g_value1, g_value2, g_value3;
GlgBoolean GlgSetGResourceIf( object, resource_name, g_value1, 
g_value2, g_value3, if_changed )
	GlgObject object;
	char * resource_name;
	double g_value1, g_value2, g_value3;
	GlgBoolean if_changed;
GlgBoolean GlgSetGTag( object, tag_sourcee, g_value1, g_value2, 
g_value3, if_changed )
	GlgObject object;
	char * tag_source;
	double g_value1, g_value2, g_value3;
	GlgBoolean if_changed;
Parameters
object
Specifies a GLG object.
resource_name, tag_source
Specifies the name of the geometrical resource or tag to be set. For tags, all tags with the specified tag_source will be set to the supplied values.
g_value0, g_value1, g_value2
Specify the new XYZ or RGB values for the resource or tag.
if_changed
If set to GlgFalse, the graphical updates will be performed even if the new value is the same as the old one (equivalent to GlgSetDResource function). Setting the parameter to GlgTrue optimizes performance of applications that set resource or tag values regardless whether the values have changed. The parameter is ignored when updating chart entry points to allow plotting straight lines when the plotted value does not change over time.

If a geometrical resource or tag with the given name exists, this function sets it to the input values and returns GlgTrue. Otherwise, the function prints an error message and returns GlgFalse.

GlgSetLParameter

Sets a value of a global parameter.

GlgBoolean GlgSetLParameter( char * name, GlgLong value )
	char * name;
	GlgLong value;
Parameters
name
Specifies parameter name.
value
Specifies parameter value.

Refer to the Appendix D: Global Parameters section on page 478 for information on available global parameters. The function returns GlgTrue on success.

GlgSetResourceFromObject

Sets a data or matrix resource object's value using another object.

GlgBoolean GlgSetResourceFromObject( object, resource_name, 
data_or_matrix_object )
	GlgObject object;
	char * resource_name;
	GlgObject data_or_matrix_object;

Sets the value of the resource specified with the object and resource name to a value defined by the data_or_matrix_object. The object type (and data type for the data object) of the resource specified by the resource name should match the type of the data_or_matrix_object.

Note that unlike the rest of the resource functions, this function does not work from a remote process.

Also unlike the rest of the resource functions, The GlgGetResourceObject function returns NULL without generating an error message if the resource cannot be found. This allows this function to be used to query the presence or absence of an object. The rest of the functions (GlgGet/SetXResource) return GlgFalse and generate an error message, which may be intercepted by installing a custom error handler. (See GlgSetErrorHandler, page 90.)

GlgSetSResource

GlgSetSResourceIf

GlgSetSTag

Replace the string in a string resource or tag.

GlgBoolean GlgSetSResource( object, resource_name, s_value )
	GlgObject object;
	char * resource_name;
	char * s_value;
GlgBoolean GlgSetSResourceIf( object, resource_name, s_value, 
if_changed )
	GlgObject object;
	char * resource_name;
	char * s_value;
	GlgBoolean if_changed;
GlgBoolean GlgSetSTag( object, tag_source, s_value, if_changed )
	GlgObject object;
	char * tag_source;
	char * s_value;
	GlgBoolean if_changed;
Parameters
object
Specifies a GLG object.
resource_name, tag_source
Specifies the name of the string resource or tag to be set. For tags, all tags with the specified tag_source will be set to the supplied value.
s_value
Specifies the new string for the resource or tag.
if_changed
If set to GlgFalse, the graphical updates will be performed even if the new value is the same as the old one (equivalent to GlgSetDResource function). Setting the parameter to GlgTrue optimizes performance of applications that set resource or tag values regardless whether the values have changed. The parameter is ignored when updating chart entry points to allow plotting straight lines when the plotted value does not change over time.

If a string resource or tag with the given name exists, this function creates a copy of the input string, and sets that copy as the new value of the resource or tag. The function returns GlgTrue if the resource or tag has been successfully changed, otherwise it generates an error message and returns GlgFalse. The memory associated with the old string is automatically freed.

GlgSetSResourceFromD

GlgSetSResourceFromDIf

GlgSetSTagFromD

Replace the string in a string resource or tag with a value specified by an input number and a format string.

GlgBoolean GlgSetSResourceFromD( object, resource_name, format, 
d_value )
	GlgObject object;
	char * resource_name;
	char * format;
	double d_value;
GlgBoolean GlgSetSResourceFromDIf( object, resource_name, format, 
d_value, if_changed )
	GlgObject object;
	char * resource_name;
	char * format;
	double d_value;
	GlgBoolean if_changed;
GlgBoolean GlgSetSTagFromDIf( object, tag_source, format, d_value, 
if_changed )
	GlgObject object;
	char * tag_source;
	char * format;
	double d_value;
	GlgBoolean if_changed;
Parameters
object
Specifies a GLG object.
resource_name, tag_source
Specifies the name of the string resource or tag to be set.
format
Specifies the format to use when setting the resource or tag string. This is a printf-style format string.
d_value
Specifies the numerical value to be converted to a string according to the format.
if_changed
If set to GlgFalse, the graphical updates will be performed even if the new value is the same as the old one (equivalent to GlgSetDResource function). Setting the parameter to GlgTrue optimizes performance of applications that set resource or tag values regardless whether the values have changed. The parameter is ignored when updating chart entry points to allow plotting straight lines when the plotted value does not change over time.

If a string resource or tag with the input name exists, this function sets it to a new string containing the d_value parameter in the format specified with the format argument. The function returns GlgTrue for success, otherwise it generates an error message and returns GlgFalse.

GlgSetTooltipFormatter

Supplies a custom tooltip formatter, returns the previously set formatter, if any.

GlgTooltipFormatter GlgSetTooltipFormatter( formatter )
	GlgTooltipFormatter formatter;
Parameters
formatter
Specifies a custom tooltip formatter.

A tooltip formatter is a function which is invoked every time a new tooltip string needs to be generated. It can create and return a tooltip string, or return NULL to use a default tooltip string. When the tooltip string is no longer needed, it will be freed by the Toolkit using the GlgFree call. Therefore, it must be allocated using GlgAlloc or one of the GLG string utility functions, such as GlgStrClone or GlgConcatStrings.

A custom tooltip formatter has the following function prototype:

typedef char * (*GlgTooltipFormatter)

( GlgObject viewport, GlgObject object,

  GlgObject tooltip_string, 

  GlgLong root_x, GlgLong root_y )

A custom tooltip formatter is invoked with the following parameters:

viewport
The parent viewport of the object.
object
The object with the tooltip action.
tooltip_string
The data object of S (string) type containing the tooltip string.
root_x
The X coordinate of the cursor relative to the root window.
root_y
The Y coordinate of the cursor relative to the root window.

GlgSetZoom

Provides a programmatic interface to integrated zooming and panning.

GlgBoolean GlgSetZoom( object, resource_name, type, value )
	GlgObject object;
	char * resource_name;
	GlgLong type;
	double value;
Parameters
object
Specifies a viewport or a light viewport.
resource_name
Specifies the resource name of a child viewport to zoom or pan, or NULL to zoom or pan the viewport specified by the object parameter. The resource name is relative to the viewport specified by the object parameter.
type
Specifies the type of the zoom or pan operation to perform. The value of this parameter matches the corresponding zooming and panning accelerators and may have the following values:
`i' - zoom in relatively to the center of the drawing by the factor specified by the value parameter (the value of 2 is used as a default if value=0).
In the Chart Zoom Mode, it zooms in only in the X/Time direction.
`I' - same as `i', but zooms in relatively to the current mouse position.
In the Chart Zoom Mode, it zooms out only in the Y direction.
`o' - zoom out relatively to the center of the drawing by the factor specified by the value parameter (the value of 2 is used as a default if value=0).
In the Chart Zoom Mode, it zooms out only in the X/Time direction.
`O' - same as `o', but zooms out relatively to the current mouse position.
In the Chart Zoom Mode, it zooms out only in the Y direction.
`t' - start generic ZoomTo mode ( left-click and drag the mouse to finish, value is ignored).
In the Chart Zoom Mode, if the first point of the ZoomTo box is located within the X or Y axis area, zooming will be performed only in the direction of the selected axis. For example, if the user defines the ZoomTo box in the X axis area, the chart will be zoomed only in the X direction.
`_' - start ZoomToX mode, which zooms only in the X direction and preserves the Y scale
( left-click and drag the mouse to finish, value is ignored). It is especially useful in the Chart Zoom Mode.
`|' - start ZoomToY mode, which zooms only in the Y direction preserves the X scale ( left-click and drag the mouse to finish, value is ignored). It is especially useful in the Chart Zoom Mode.
`@' - start ZoomToXY mode (left-click and drag the mouse to finish, value is ignored)
`T' - start custom ZoomTo mode (left-click and drag the mouse to ZoomTo, value is ignored). A custom zoom mode lets the user define the ZoomTo area without performing the zoom operation. An application can use the selected ZoomTo rectangle as the input to implement custom zooming or object selection logic. An application can handle Zoom events in input callback to perform a custom zoom operation. Refer to the Appendix B: Message Object Resources section of the GLG Programming Reference Manual for details of the Zoom event.
`e' - abort ZoomTo mode, value is ignored
`s' - start generic dragging mode ( left-click and drag the drawing with the mouse to pan or scroll).
In the Chart Zoom Mode, if the user clicks and drags the mouse within the X or Y axis area, scrolling will be performed in the direction matching the direction of the selected axis.
`^' - start vertical dragging mode ( left-click and drag the drawing with the mouse to pan or scroll in the vertical direction). It is especially useful in the Chart Zoom Mode.
`>' - start horizontal dragging mode ( left-click and drag the drawing with the mouse to pan or scroll in the horizontal direction). It is especially useful in the Chart Zoom Mode.
`&' - start XY dragging mode ( left-click and drag the drawing with the mouse to pan or scroll).
`f' - fit the drawing to the visible area of the viewport, value is ignored (Drawing Zoom Mode only). The X/Y ratio is maintained depending on the setting of the viewport's Stretch attribute.
`F' - fit the area of the drawing defined by an object named GlgFitArea to the visible area of the viewport, value is ignored (Drawing Zoom Mode only). The X/Y ratio is maintained depending on the setting of the viewport's Stretch attribute.
`n' - reset zoom, value is ignored.
In the GIS zoom mode with map in the ORTHOGRAPHIC   projection, resets zooming, but keeps the GIS center unchanged. In the RECTANGULAR projection, resets zooming and paning, but keeps the rotation angle unchanged.
In the Chart Zoom Mode, resets the Y range to fit all chart plots in the visible area of the chart in Y direction.
`N' - reset zoom, value is ignored.
In the Chart Zoom Mode, resets the Y range and changes the chart's X span to show all accumulated data samples in the visible area of the chart.
`u' - pan up by the fraction of the widow height specified by the value parameter (the value of 0.5 is used as a default if value=0).
In the Chart Zoom Mode, scroll the chart up by a fraction of the chart's data area height.
`d' - pan down by the fraction of the widow height specified by the value parameter (the value of 0.5 is used as a default if value=0).
In the Chart Zoom Mode, scroll the chart down by a fraction of the chart's data area height.
`l' - pan left by the fraction of the widow width specified by the value parameter (the value of 0.5 is used as a default if value=0).
In the Chart Zoom Mode, scroll the chart left by a fraction of the chart's data area width.
`r' - pan right by the fraction of the widow width specified by the value parameter (the value of 0.5 is used as a default if value=0).
In the Chart Zoom Mode, scroll the chart right by a fraction of the chart's data area width.
`x' - pan horizontally by the distance in screen coordinates specified by the value parameter, the sign of the value defines the pan direction
`y' - pan vertically by the distance in screen coordinates specified by the value parameter, the sign of the value defines the pan direction
`X' - pan horizontally by the distance in world coordinates specified by the value parameter, the sign of the value defines the pan direction.
In the GIS Zoom Mode, pans by the latitude degrees.
In the Chart Zoom Mode, scrolls by the units of the X axis.
`Y' - pan vertically by the distance in world coordinates specified by the value parameter, the sign of the value defines the pan direction.
In the GIS Zoom Mode, pans by the longitude degrees.
In the Chart Zoom Mode, scrolls by the units of the first Y axis.
`U' - anchor on the upper edge, value is ignored (Drawing Zoom Mode only)
`D' - anchor on the lower edge, value is ignored (Drawing Zoom Mode only)
`R' - anchor on the right edge, value is ignored (Drawing Zoom Mode only)
`L' - anchor on the lower edge, value is ignored (Drawing Zoom Mode only)
`A' - rotate the drawing clockwise around X axis by the angle specified by the value parameter (Drawing Zoom Mode only)
`a' - rotate the drawing counterclockwise around X axis by the angle specified by the value parameter (Drawing Zoom Mode only)
`B' - rotate the drawing clockwise around Y axis by the angle specified by the value parameter (Drawing Zoom Mode only)
`b' - rotate the drawing counterclockwise around Y axis by the angle specified by the value parameter (Drawing Zoom Mode only)
`C' - rotate the drawing clockwise around Z axis by the angle specified by the value parameter (Drawing Zoom Mode or GIS Zoom Mode with the rectangular projection only)
`c' - rotate the drawing counterclockwise around Z axis by the angle specified by the value parameter (Drawing Zoom Mode or GIS Zoom Mode with the rectangular projection only)
value
Specifies a value for zoom and pan operations as described above.

The function performs a specified zoom or pan operation regardless of the setting of the viewport's Pan and ZoomEnabled attributes. In the Drawing Zoom Mode, if the function attempts to set a very large zoom factor which would result in the overflow of the integer coordinate values used by the native windowing system, the zoom operation is not performed and the function returns GlgFalse.

The left mouse button is the default button for performing the ZoomTo operation, as well as for panning and scrolling the drawing by dragging it with the mouse. These defaults can be changed by setting the GlgZoomToButton and GlgPanDragButton global configuration resources. If the default is changed, the left-click used in the description of the affected operations changes to the click with the mouse button assigned to the respective ZoomTo or Pan operation.

GlgSetZoomMode

Sets or resets a viewport's zoom mode by supplying a GIS or Chart object to be zoomed. In the Drawing Zoom Mode (default), the drawing displayed in the viewport is zoomed and panned. If the GIS Zoom Mode is set, any zooming and panning operation performed by the GlgSetZoom method will zoom and pan the map displayed in the viewport's GIS Object, instead of being applied to the viewport's drawing. In the Chart Zoom Mode, the content of the chart is zoomed and panned.

GlgBoolean GlgSetZoom( object, resource_name, 

           zoom_object, zoom_object_name )
	GlgObject object;
	char * resource_name;
	GlgObject zoom_object;
	char * zoom_object_name;
Parameters
object
Specifies a viewport object.
resource_name
Specifies the resource name of a child viewport whose zoom mode to set, or NULL to set the Zoom Mode of the viewport specified by the object parameter. The resource name is relative to the viewport specified by the object parameter.
zoom_object
Specifies a GIS or Chart object (or its parent if zoom_object_name is not NULL).
zoom_object_name
If the parameter is NULL, the GIS or Chart object supplied by the zoom_object parameter is selected as the GIS or Chart object to be zoomed. If the parameter is not NULL, it specifies the resource name of the GIS or Chart object to be zoomed. The resource name is relative to the zoom_object parameter, or to the viewport specified by the object and resource_name parameters if the zoom_object parameter is NULL.

The function may be invoked with zoom_object=NULL and zoom_name=NULL to reset the zoom mode to the default Drawing Zoom Mode.

GlgStrClone

Creates a copy of a character string.

char * GlgStrClone( string )
	char * string;
Parameters
string
The string to be copied. This can be a NULL pointer, in which case the return value is also NULL.

This function creates and returns a copy of the input string. The copy should later be freed with the GlgFree function.

GlgUpdate

Updates a widget to show new resource values.

GlgBoolean GlgUpdate( object )
	GlgObject object;
Parameters
object
Specifies a viewport to update. If object is a light viewport, update of its parent viewport will be performed.

All resource changes are held until the GlgUpdate function is called or until the widget window receives an expose event. (That is, it must be redrawn because another window that had obscured part of the window has been moved.) This causes the widget to redraw itself, using its new data. The function returns GlgTrue if the widget has been successfully updated; otherwise it returns GlgFalse.

Note: Some GLG drawing resources affect the object hierarchy of the drawing (these are the H resources), while others affect the values of objects in the hierarchy (V resources). The Factor attribute of a series affects whether or not there is a Sample5/FillColor instance object in that series. A request to change the Factor resource to 3 might therefore conflict with a request to change the Sample5/FillColor resource to red. Even if Factor was changed to 6 in the same batch of resource changes, the act of redrawing the series to accommodate the new attribute value might delete the color change of a series instance. To avoid these conflicts, it is advisable to execute GlgUpdate after any H resources have been changed, and before changing any other resources. For more information about these resources, see the H and V Resources section of Integrating GLG Drawings into a Program.

GlgWinPrint

Invokes Microsoft Windows native printing.

void GlgWinPrint( viewport, print_dc, x,y, width, height, reserved, 
   stretch )
	GlgObject viewport;
	HDC print_dc;
	double xpos, ypos, width, height;
	GlgBoolean reserved, stretch;
Parameters
viewport
Specifies the viewport whose contents are to be printed. If viewport is a light viewport, the output will be generated for its parent viewport.
print_dc
The printer device context, acquired from a call to the PrintDlg function.
xpos, ypos, width, height, stretch
These arguments are used in the same way as the corresponding arguments to the GlgPrint function, described above.

Given the printer device context, this function prints the contents of a viewport and all its children viewports into that device context. It is the responsibility of the application to set the abort procedure, provide a cancel printing dialog, disable the application window during printing, and call the StartDoc, StartPage, EndDoc, and EndPage functions before and after calling this function. These procedures and the use of these functions is described in the Win32 Programmer's Reference.

There is no orientation parameter with the Microsoft Windows native printing. The page orientation is determined by the user through the print dialog.

The GlgWinPrint function can be used to add GLG printing output to a page which already had some output on it. In this case, that other output may set the printer device context parameters to values incompatible with the GLG output. Before calling this function, therefore, the device transformations must be reset to the state they were in right after calling the PrintDlg function.

This function is only available under the Microsoft Windows environment.

GlgXPrintDefaultError

Prints information about an X error on a console or logs it into a file. The function can be used for printing error information in custom X error handlers and is available only under the X Windows environment on Linux/Unix.

GlgBoolean GlgXPrintDefaultError( display, event, file )
	Display *display;
	XErrorEvent *event;
	FILE * file;
Parameters
display
Specifies the connection to the X server.
event
X error event.
file
File to log the output to. stdout may be used to print the output on the console.

The function returns GlgTrue if it detects OpenGL GLX errors, otherwise it returns GlgFalse.


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