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 Widget. 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 widget from a program, see Displaying a GLG Drawing on page 17. Though the details of displaying a widget 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.
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:
GlgSetDResource, GlgSetDResourceIf and GlgSetDTag set a scalar resource or tag. For information about the different attribute data types (geometrical, scalar, and string), see The Attribute Object in Structure of a GLG Drawing.
GlgSetGResource , GlgSetGResourceIf and GlgSetGTag set a geometrical resource or tag.
GlgSetSResource , GlgSetSResourceIf and GlgSetSTag set a string resource or tag.
GlgSetSResourceFromD , GlgSetSResourceFromDIf and GlgSetSTagFromD set a string resource or tag from a scalar according to a chosen format.
GlgSetResourceFromObject Sets a resource using another object.
GlgGetDResource and GlgGetDTag return a scalar resource or tag.
GlgGetGResource and GlgGetGTag return a geometrical resource or tag.
GlgGetSResource and GlgGetSTag return a string resource or tag.
GlgHasResourceObject and GlgHasTagObject check if a named resource or tag exists.
GlgCreateTagList returns a list of tags defined in the drawing.
GlgSetZoom and GlgSetGISZoom provide programmatic access to the integrated zooming and panning features.
GlgUpdate redisplays the drawing using the current resource values. All resource changes are stored until this function is called or until a previously hidden object is exposed. (This is an expose event .)
GlgPrint saves a PostScript image of the widget's current state into a file.
GlgWinPrint invokes the native Microsoft Windows printing function.
GlgSaveImage and GlgSaveImageCustom save an image of the drawing in the JPEG format.
GlgReset reinitializes a widget drawing.
GlgSendMessage sends a message to an object to request some action to be performed.
GlgExportStrings exports all text strings defined in the drawing into a string translation file.
GlgImportStrings imports translated text strings from a string translation file.
GlgExportTags exports all tag names defined in the drawing into a file.
GlgImportTags replaces tag names in the drawing with the tag names imported from a tag translation file.
The GLG API also includes the following convenience functions. These functions simplify several tasks common to GLG C programs.
GlgStrClone creates a copy of a string.
GlgCreateIndexedName creates an enumerated resource name.
GlgConcatResNames creates composite resource names from components.
GlgConcatStrings creates a new string from two input stings.
GlgFree frees the memory allocated by some other API functions.
GlgSetErrorHandler replaces the GLG Toolkit error handler.
GlgGetSelectionButton is used inside a selection callback procedure to query for the mouse button that caused the selection event.
GlgError displays error and information messages.
GlgGISConvert performs coordinate conversion from the GIS coordinates of the GIS Object to the GLG coordinates of the drawing and vise versa.
GlgSetReadOnlyStrings sets read-only or writable strings mode.
GlgGetMajorVersion and GlgGetMinorVersion retrieve the library's version numbers.
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 H and V Resources of Details of using GLG Standard API for C and C++.
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 following describes the interfaces of the GLG Widget Library functions.
Creates a composite resource name from two components.
char * GlgConcatResNames( resource_name1, resource_name2 ) char * resource_name1, * 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/DataSample2Multiple 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/ValueConcatenates two character strings.
char * GlgConcatStrings( string1, string2 ) char * 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 );Creates a string with a name for an enumerated resource.
char * GlgCreateIndexedName( template_name, resource_index ) char * template_name; GlgLong resource_index;A character string containing the template name to be expanded. This name uses the % character to define the expansion position.
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.
produces the following output:
Name: XLabelGroup/XLabel0/String Name: XLabelGroup/XLabel1/String Name: XLabelGroup/XLabel2/StringThe 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/ValueCreates and returns a list of tags.
GlgObject GlgCreateTagList( object, unique_tags ) GlgObject object; GlgBoolean unique_tags;An object whose tags are queried. The top level viewport may be used to query the list of tags of the whole drawing.
If set to GlgTrue , only one instance of tags with same tag name will be added to the list. If the parameter value is set to GlgFalse , all instances with the same tag name 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.
Displays error and information messages using the Toolkit's error handler.
void GlgError( type, message ) GlgErrorType type; char * message;Specifies the type of the message, may have the following values:
GLG_INTERNAL_ERROR - reserved for the Toolkit's internal usage.
GLG_USER_ERROR - generates an error message dialog.
GLG_WARNING - generates a warning message dialog
GLG_INFO - logs the message into the GLG log file.
In the Unix environment, all messages are also printed in the program standard error output regardless of their message types.
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;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 101 of the GLG User's Guide and Builder Reference Manual for information about the string translation file format.
Writes all tag names defined in the drawing into a file:
GlgLong GlgExportTags( object, filename, separator1, separator2 ) GlgObject object; char * filename; GlgLong separator1; GlgLong 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 101 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.
Frees the memory used to store character strings.
void GlgFree( pointer ) char * pointer;Specifies a character string that is no longer needed by the application.
This function is used to free memory occupied by a simple object. 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 advantage this function has over the standard C memory management function is that it checks for NULL address pointers, and will not fail or generate an error message if one is passed.
Returns 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_name, d_value_ptr ) GlgObject object; char * tag_name; double * 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 .
Returns 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_name, g_value1_ptr, g_value2_ptr, g_value3_ptr ) GlgObject object; char * tag_name; double * g_value1_ptr, * g_value2_ptr, * gvalue3_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.
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.
Returns 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_name, s_value_ptr ) GlgObject object; char * tag_name; char ** 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.
Performs coordinate conversion from the GIS coordinates of the GIS Object to the GLG coordinates of the drawing and visa versa.
GlgBoolean GlgGISConvert( object, resource_name, coord_type, coord_to_lat_lon, in_point, out_point ) GlgObject object; char * resource_name; GlgCoordType coord_type; GlgBoolean coord_to_lat_lon; GlgPoint * in_point; GlgPoint * out_point;If the resource_name parameter is NULL, specifies the GIS object whose coordinate system to use for conversion. If the resource_name parameter is not NULL, specifies a parent of the GIS object.
If not NULL, specifies the resource name of the GIS object inside the parent object specified by the object parameter.
The type of the GLG coordinate system to convert to or from: GLG_SCREEN_COORD for screen coordinates or GLG_OBJECT_COORD for world coordinates.
GlgTrue to convert from GLG coordinates to GIS longitude and latitude, GlgFalse to convert from GIS to GLG coordinates.
A pointer to the GlgPoint structure that receives converted coordinate values.
The function returns GlgTrue if conversion succeeds. When converting from GLG to GIS coordinates, the Z coordinate is set to a negative value for points on the invisible part of the globe.
The GlmConvert function of may be used to perform coordinate conversion between GIS and GLG coordinates without the use of the GIS object.
Replaces text strings in the drawing with the strings loaded from a string translation file:
GlgLong GlgImportStrings( object, filename ) GlgObject object; char * 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 101 of the GLG User's Guide and Builder Reference Manual for information about the string translation file format.
Replaces tag names in the drawing with the tag names loaded from a tag translation file:
GlgLong GlgImportTags( object, filename ) GlgObject object; char * 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 101 of the GLG User's Guide and Builder Reference Manual for information about the file format.
The function returns the number of imported tag names or -1 in case of an error.
.Provides MFC metafile output support (Microsoft 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;Provides MFC printing support (Microsoft 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;Generates a PostScript output of the current state of the widget's graphics.
GlgBoolean GlgPrint( object, file, xpos, ypos, width, height, portrait, stretch ) GlgObject object; char * file; double xpos, ypos, width, height; GlgBoolean portrait, stretch;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.
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.
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 FALSE, 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 GlgUpdat e 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.
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 .
Generates a JPEG image of the current state of the widget's graphics and saves it into a file:
GlgBoolean GlgSaveImage( object, res_name, filename, format ) GlgObject object; char * res_name; char * filename; GlgImageFormat format; GlgBoolean GlgSaveImageCustom( object, res_name, filename, format, x, y, width, height, gap ) GlgObject object; char * res_name; char * filename; GlgImageFormat format; GlgLong x, y, width, height, gap;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.
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.
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.
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.
Sends a message to an object to request some action to be performed.
GlgAnyType GlgSendMessage( object, res_name, message, param1, param2, param3, param4 ) GlgObject object; char * res_name; char * message; GlgAnyType param1, param2, param3, param4;Refer to Input Objects on page 103 of the GLG User's Guide and Builder Reference Manual for a list of messages supported by each type of the available input handlers.
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 res_name parameter.
Message parameters whose type depends on the message type.
The function is used 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's result. The types of the function's parameters and its returned value are explained in the chapters that describe the object that supports each message.
Sets the object for browsing with Glg resource or tag browser widget.
void GlgBoolean GlgSetBrowserObject( browser, object ) GlgObject browser; GlgObject object;Sets 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_name, d_value, if_changed ) GlgObject object; char * tag_name; double d_value; GlgBoolean 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 must be set to GlgFalse when updating entry points of graphs to allow plotting straight lines when the graph's 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 .
Replaces the GLG Toolkit error handler.
GlgErrorHandler GlgSetErrorHandler( new_handler ) GlgErrorHandler 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 ) char * error_message;For more information about error handlers, see Error Processing of Details of using GLG Standard API for C and C++.
Sets 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_name, g_value1, g_value2, g_value3, if_changed ) GlgObject object; char * tag_name; double g_value1, g_value2, g_value3; GlgBoolean 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 must be set to GlgFalse when updating entry points of graphs to allow plotting straight lines when the graph's 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 .
Sets read-only or writable strings mode.
GlgBoolean GlgSetReadOnlyStrings( read_only ) GlgBoolean read_only;Specifies the read-only strings (True) or writable strings mode (False).
In writable strings mode resource names are parsed in-place, which is a bit faster. The read-only strings mode may need to be set for compatibility with environments that require read-only strings, such as the latest versions of the Visual Studio on Windows, which requires read-only strings for its Edit and Continue debugging feature. The default setting is read-only strings on Windows and writable strings for the Unix version of the library.
The GLG_READ_ONLY_STRINGS environment variable may be set to True or False to override the default setting without changing the application's source code. This may be used for a quick troubleshooting of problems related to the string mode settings.
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 66.)
Replaces 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_name, s_value, if_changed ) GlgObject object; char * tag_name; char * s_value; GlgBoolean 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 must be set to GlgFalse when updating entry points of graphs to allow plotting straight lines when the graph's 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.
Replaces 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_name, format, d_value, if_changed ) GlgObject object; char * tag_name; char * format; double d_value; GlgBoolean if_changed;Specifies the format to use when setting the resource or tag string. This is a printf-style format string.
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 must be set to GlgFalse when updating entry points of graphs to allow plotting straight lines when the graph's 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 .
Provides a programmatic interface to integrated zooming and panning.
GlgBoolean GlgSetZoom( object, res_name, type, value ) GlgObject object; char * res_name; GlgLong type; double value;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.
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 by the factor specified by the value parameter (the value of 2 is used as a default if value=0)
`o' - zoom out by the factor specified by the value parameter (the value of 2 is used as a default if value=0)
`t' - start ZoomTo mode (click and drag the mouse to ZoomTo, value is ignored)
`T' - start custom ZoomTo mode (click and drag the mouse to ZoomTo, value is ignored). Custom zoom mode draws a zoom rectangle but does not perform the zoom operation. An application can handle Zoom events in input callback to perform a custom zoom operation. Refer to Appendix B: Message Object Resources of the GLG Programming Reference Manual for details of the Zoom event.
`e' - abort ZoomTo mode, value is ignored
`f' - fit the drawing to the visible area of the viewport, value is ignored
`F' - fit the area of the drawing defined by an object named GlgFitArea to the visible area of the viewport, value is ignored
`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.
`N' - reset zoom, value is ignored.
`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)
`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)
`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)
`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)
`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
`Y' - pan vertically by the distance in world coordinates specified by the value parameter, the sign of the value defines the pan direction
`U' - anchor on the upper edge, value is ignored
`D' - anchor on the lower edge, value is ignored
`R' - anchor on the right edge, value is ignored
`L' - anchor on the lower edge, value is ignored
`A' - rotate the drawing clockwise around X axis by the angle specified by the value parameter
`a' - rotate the drawing counterclockwise around X axis by the angle specified by the value parameter
`B' - rotate the drawing clockwise around Y axis by the angle specified by the value parameter
`b' - rotate the drawing counterclockwise around Y axis by the angle specified by the value parameter
`C' - rotate the drawing clockwise around Z axis by the angle specified by the value parameter
`c' - rotate the drawing counterclockwise around Z axis by the angle specified by the value parameter
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. 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 False.
Sets or resets a viewport's GIS Zoom Mode. If the GIS zoom mode is set, any zooming and panning operations invoked 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.
GlgBoolean GlgSetGISZoom( object, res_name, gis_object, gis_name ) GlgObject object; char * res_name; GlgObject gis_object; char * gis_name;Specifies the resource name of a child viewport whose GIS Zoom Mode to set, or NULL to set the GIS Zoom Mode of the viewport specified by the object parameter. The resource name is relative to the viewport specified by the object parameter.
If the parameter is NULL, the GIS object supplied by the gis_object parameter is selected as the GIS object to be zoomed. If the parameter is not NULL, it specifies the resource name of the GIS object to be zoomed. The resource name is relative to the gis_object parameter, or to the viewport specified by the object and res_name parameters if the gis_object parameter is NULL.
The function may be invoked with gis_object=NULL and gis_name=NULL to reset the GIS Zoom Mode.
Updates a widget to show new resource values.
GlgBoolean GlgUpdate( object ) GlgObject object;Specifies a viewport to update.
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 H and V Resources of Details of using GLG Standard API for C and C++.
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;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.
A low level function that performs coordinate conversion from the GIS coordinates of a map to the GLG coordinates of the drawing and visa versa without the help of a GLG GIS Object. Since the function does not rely on a GIS Object being displayed and set up, it may be used before the drawing is rendered or without a drawing at all.
void GlmConvert( projection, stretch, coord_type, coord_to_lat_lon, center, extent, angle,The type of the GLG coordinate system to convert to or from: GLG_SCREEN_COORD for screen coordinates or GLG_OBJECT_COORD for world coordinates.
GlgTrue to convert from GLG coordinates to GIS longitude and latitude, GlgFalse to convert from GIS to GLG coordinates.
A pointer to the GlgPoint structure containing lat/lon coordinates of the map center. The Z coordinate must be set to 0.
A pointer to the GlgPoint structure containing X and Y extent of the map in the selected projection: in degrees for the rectangular projection or in meters for orthographic. The Z extent must be set to 0. Refer to GIS Object on page 54 of the GLG User's Guide and Builder Reference for more details.
A map extent in the selected coordinate system. To get X/Y coordinates relative to the map image origin, use min_x=0, min_y=0, max_x=image_width, max_y=image_height .
A pointer to the GlgPoint structure that receives converted coordinate values.
When converting from X/Y to lat/lon coordinates in the orthographic projection, the Z coordinate is set to a negative value for points on the invisible part of the globe or outside the globe area, and to zero for points on the edge of the globe. The coordinates of the returned point may be outside of the visible portion of the map for all projections.
Every viewport object inside a GLG Widget includes a built-in communications server . This allows the viewport to display data sent it from other, client , processes. Under this scenario, the server process creates a GLG Widget with some graphical objects inside it and then waits for clients to supply data for animation, updating the widget's graphics or executing resource value queries upon client request. This is not an exclusive arrangement. A server process may supply its own data as well as getting it from a client.
A client process works in the same way, and with the same functions, as a process that contains the animated drawing. The only difference is in how the application program creates a handle to attach to the viewport containing the drawing. Where the integrated process uses a wrapper widget or the custom control apparatus to display the drawing and to return a handle, the client process uses a link ID in its place. This lets you access the resources of the server viewport using the same function API you would use to access the viewport's resources directly. The application program uses the GLG Communication Library to query the server process for this ID.
The GLG Client/Server Communication Library is a subset of the GLG API, and functions identically in the X Windows and MS Windows environments. The Library contains the following functions:
GlgCreateLink establishes a connection with a desired GLG server, and returns the link ID.
GlgSync synchronizes a link with a GLG server.
GlgLinkActive checks the state of a link.
GlgDestroyLink closes a connection to a GLG server.
The GLG Communication Library handles all the details of establishing and maintaining the connection between the client and server processes. The client process must only specify the name of the viewport communication server to which to connect. (Under X Windows, a client must also give the name of the display on which the drawing is displayed.) The server name is controlled with a viewport attribute.
The Communication Library is platform-independent and may be used transparently on both X Windows and MS Windows. In the X Windows environment, it is implemented on top of the X Protocol for portability. In the MS Windows environment, the library is implemented using the Dynamic Data Exchange protocol (DDE). It is not necessary to be familiar with either protocol to use the library.
Though the architecture of the communication server allows an application programmer to use the same API to communicate with a remote viewport server and with a local viewport, there are some differences in usage.
The server name, used to create a link between the client and the server, is specified with the ServerName resource of a viewport. A drawing may contain several viewports that have enabled servers. If several currently displayed servers have the same name, only the last one created receives the messages.
Note : When changing the ServerName and ServerEnabled attributes of a viewport with the GLG Graphics Builder, occasionally you may need to reset the drawing in order to activate the server. This is often necessary if some of the servers in the drawing have conflicting names. So, if after changing server names the Data Generation Utility, or any other client process, cannot open a connection, quit the Run mode, reset the whole Drawing Area and run the drawing again.
When connected to a remote process, the querying functions from the GLG API take longer to execute, since they require a round trip to the GLG server. The GlgSync function also requires a message to the GLG server and back again, so it should be called as rarely as possible. It is generally reserved for use after a batch of changes or to wait for error messages after an important request.
Messages to the viewport server are buffered. Both the GlgUpdate and GlgSync functions flush the buffers, so calling them after setting every individual resource should be avoided, if possible, to increase the data transfer rate and update speed. However, periodic syncing is recommended.
Functions for querying resource values return GlgFalse if a resource with the given name and type does not exist in the specified server viewport. If the connection is lost, GlgFalse is returned and the link is marked as inactive. This can be checked by querying the link ID with the GlgLinkActive function.
Functions for setting resources and printing function return GlgFalse only if the connection is lost. In this case the link is marked as inactive. If the incorrect resource name or type is specified, or if a printing request fails for some reason, these functions do not return GlgFalse . Instead, error handlers are called on both the server and client sides using appropriate error messages.
The GlgUpdate and GlgReset functions return GlgFalse if the connection is lost, marking the link as inactive.
If the connection is lost because the server process is terminated, any function called with a link ID as its first parameter returns immediately. If the connection is lost and the GLG server does not respond for some other reason, the function returns after a 15 second timeout. In both cases the link is marked inactive, and cannot be used any more.
Calling the GlgReset function sets all a viewport's currently active links to an inactive state. The links should be destroyed with the GlgDestroyLink function and recreated again using the GlgCreateLink function in order to continue communication with the server. Before recreating the links, make sure the client process waits long enough (depending on the complexity of the drawing) to let the server finish the reset operation. Any attempt to open a link before the server finishes will fail.
The drawing area of the GLG Graphics Builder is a viewport, whose server name is GlgDrawingAreaServer . This server may be accessed as any other server when the Builder is in the Run mode. An application may use the communication API library to connect to this server and animate the drawing. This allows a user to write an application-specific data generator for demonstrations.
To use any of the functions described in this section, the application program must include the function definitions from the GLG API header file. Use the following line to include those definitions:
#include "GlgApi.h"Establishes a connection with a GLG server.
GlgObject GlgCreateLink( display_name, comm_name ) char * display_name; char * server_name;Specifies the name of the display the server viewport resides on. On MS Windows, this parameter is ignored and must be NULL.
Specifies the name of the server; corresponds to the ServerName attribute of the server viewport. Note that this is not necessarily the same as the name of the viewport object.
This function creates a communication link with the viewport defined by the server name and returns its handle. The handle is also known as the link ID . If an attempt to create a link fails, the function returns NULL.
Closes a connection with a specific server.
void GlgDestroyLink( link ) GlgObject link;Specifies the communication link to query.
This function returns GlgTrue if the link is active, and GlgFalse otherwise. If the link is not active, this implies that the connection was lost for some reason. The most common reasons for a lost connection are the termination of the server process or quitting the Run mode of the GLG Graphics Builder (if the Builder is being used as a server).
Synchronizes a link with between a GLG client and its server.
GlgBoolean GlgSync( link ) GlgObject link;The handle of the target server.
This function causes a link to wait until the server finishes executing all requests. It returns GlgTrue if the link is still active and all requests (except query requests), after the last call to the GlgSync function, were successful. If some requests failed, it returns GlgFalse . If the connection is broken, it returns GlgFalse and marks the link as inactive. The state of the link can be checked using the GlgLinkActive function.
Query request failures are reported immediately by the return value of the querying function and do not affect the return value of the GlgSync function.
If a client sends a lot of requests to its server, GlgSync may be used after every GlgUpdate call to make sure the server does not lag behind. Note, however, that using this function uses server time and communication bandwidth. You may, therefore, choose to optimize by calling it just once for several calls to GlgUpdate .
If gathering data by the client application is a time-consuming operation, it may be useful to call the GlgSync function before the GlgUpdate call instead of the other way around. Using this scenario, the time while the server is busy updating the drawing is used by the client to gather the data.
Since error messages on the client side are printed asynchronously, the GlgSync function may be used as a debugging aid. If the function is executed after each call to a resource-setting or printing function, then if any error is detected, an error handler is called before return from the GlgSync function, and the return value is GlgFalse .
The following two code examples present two simple programs which open a connection with a GLG viewport server named temperature_graph on the sparc:0.0 display, query the value of the DataGroup/DataSample5/Value resource, and set the color of the DataGroup/DataSample5/FillColor resource to be red if the value of the first resource is greater then 80.
Again, note that the server name is the value of the ServerName attribute of a viewport object and may be different from the viewport's name.
The first example ignores any error conditions. Though this is not good coding style, it makes the illustration easier to understand by showing only the bare bones:
#include <stdio.h> #include "GlgApi.h" main() { GlgObject link; double temperature5;