Standard API Functions

Detailed Description

This group contains functions of the GLG Standard API.

These functions are used to:

• load and display a GLG drawing
• access resources of the drawing
• animate the drawing with live data
• handle user interaction (selecting objects with the mouse, pressing buttons, etc.).

Specialized Chart functions, as well as a variety of utility functions, are also provided.

Include file: GlgApi.h

GlgAppContext	GlgInit (GlgBoolean tk_initialized, GlgAppContext app_context, int argc, char **argv)
	Initializes GLG Toolkit API. More...
void	GlgTerminate (void)
	Terminates the application's use of the GLG Toolkit. More...
GlgObject	GlgLoadWidgetFromFile (char *filename)
	Loads a GLG widget from a GLG drawing file or a URL. More...
GlgObject	GlgLoadWidgetFromImage (void *image, GlgLong size)
	Loads a GLG widget from a memory image. More...
GlgObject	GlgLoadWidgetFromObject (GlgObject object)
	Loads a widget from a GLG object. More...
GlgObject	GlgLoadObject (char *filename)
	Loads an object from a GLG drawing file or a URL. More...
GlgObject	GlgLoadObjectFromImage (void *image, GlgLong size)
	Loads an object from a memory image. More...
void	GlgInitialDraw (GlgObject object)
	Draws a GLG viewport object for the first time after it has been created or loaded. More...
void	GlgDialogInitialDraw (GlgObject object, GlgObject parent)
	Displays a GLG drawing as a floating dialog for the first time after it has been created or loaded. More...
void	GlgSetupHierarchy (GlgObject object)
	Provides an explicit request to set up the object hierarchy without rendering the object. More...
void	GlgResetHierarchy (GlgObject object)
	Resets the object hierarchy. More...
void	GlgDialogSetupHierarchy (GlgObject object, GlgObject parent)
	Provides an explicit request to set up the object hierarchy of a drawing displayed in a dialog window. More...
GlgBoolean	GlgUpdate (GlgObject object)
	Updates a drawing to show new resource values. More...
GlgBoolean	GlgReset (GlgObject object)
	Reinitializes the drawing by resetting the drawing hierarchy, then setting it up again and rendering the drawing. More...
GlgBoolean	GlgConfigureWindow (GlgObject object, GlgLong x, GlgLong y, GlgLong width, GlgLong height, GlgConfigureMask mask, GlgObject parent)
	Sets the size and/or position of a viewport's window. More...
GlgLong	GlgMainLoop (GlgAppContext context)
	Implements an event polling loop in a platform independent way. More...
GlgErrorHandler	GlgSetErrorHandler (GlgErrorHandler new_handler)
	Replaces the GLG Toolkit error handler and returns the previous error handler. More...
void	GlgError (GlgErrorType type, char *message)
	Displays error and information messages using the currently installed error handler. More...
GlgObject	GlgCreateAlarmList (GlgObject object)
	Creates and returns a list of alarms defined in the drawing. More...
GlgAlarmHandler	GlgSetAlarmHandler (GlgAlarmHandler handler)
	Installs a global alarm handler function that will be invoked to process alarms. More...
GlgBoolean	GlgExportPostScript (GlgObject object, char *file, double x, double y, double width, double height, GlgBoolean portrait, GlgBoolean stretch, GlgBoolean center)
	Generates a PostScript output of the current state of the viewport's graphics. More...
GlgBoolean	GlgNativePrint (GlgObject object, PlatformDependent print_context, double x, double y, double width, double height, GlgBoolean stretch, GlgBoolean center)
	GTK and Windows only: Generates printing output of the current state of the viewport's graphics. More...
GlgBoolean	GlgSaveImage (GlgObject object, char *resource_name, char *filename, GlgImageFormat format)
	Generates a JPEG or PNG image of the current state of the viewport's graphics and saves it to a file. More...
GlgBoolean	GlgSaveImageCustom (GlgObject object, char *resource_name, char *filename, GlgImageFormat format, GlgLong x, GlgLong y, GlgLong width, GlgLong height, GlgLong gap)
	Generates a JPEG or PNG image of the specified rectangular region of the viewport's graphics and saves it to a file. More...
PlatformDependent	GlgGenerateImage (GlgObject object, char *resource_name, PlatformDependent image)
	Creates and returns an image of the current state of the viewport's graphics. More...
PlatformDependent	GlgGenerateImageCustom (GlgObject object, char *resource_name, PlatformDependent image, GlgLong x, GlgLong y, GlgLong width, GlgLong height, GlgLong gap)
	Creates an image of the specified rectangular region of the viewport's graphics. More...
void *	GlgAlloc (GlgLong size)
	Allocates memory using the Toolkit's memory allocator. More...
void	GlgFree (void *ptr)
	Frees memory used to store character strings or allocated using GlgAlloc. More...
char *	GlgStrClone (char *string)
	Creates a copy of a character string. More...
char *	GlgConcatStrings (char *string1, char *string2)
	Concatenates two character strings. More...
char *	GlgCreateIndexedName (char *template_name, GlgLong resource_index)
	Creates a string with a name of an enumerated resource. More...
char *	GlgConcatResNames (char *resource_name1, char *resource_name2)
	Creates a composite resource path from two components. More...
GlgBoolean	GlgPreAlloc (GlgLong size, GlgPreAllocType type)
	Preallocates memory under the control of mission critical real-time applications. More...
GlgBoolean	GlgSetDResource (GlgObject object, char *resource_name, double value)
	Sets a new value of a D (double) resource. More...
GlgBoolean	GlgSetDResourceIf (GlgObject object, char *resource_name, double value, GlgBoolean if_changed)
	Sets a new value of a D (double) resource. More...
GlgBoolean	GlgGetDResource (GlgObject object, char *resource_name, double *value)
	Returns the current value of a D (double) resource. More...
GlgBoolean	GlgSetSResource (GlgObject object, char *resource_name, char *value)
	Replaces the string of an S (string) resource. More...
GlgBoolean	GlgSetSResourceIf (GlgObject object, char *resource_name, char *value, GlgBoolean if_changed)
	Replaces the string of an S (string) resource. More...
GlgBoolean	GlgGetSResource (GlgObject object, char *resource_name, char **value)
	Returns the current value of a S (string) resource. More...
GlgBoolean	GlgSetGResource (GlgObject object, char *resource_name, double x_value, double y_value, double z_value)
	Sets new values of a G (geometrical or color) resource. More...
GlgBoolean	GlgSetGResourceIf (GlgObject object, char *resource_name, double x_value, double y_value, double z_value, GlgBoolean if_changed)
	Sets new values of a G (geometrical or color) resource. More...
GlgBoolean	GlgGetGResource (GlgObject object, char *resource_name, double *x_value, double *y_value, double *z_value)
	Returns the current value of a G (geometrical or color) resource. More...
GlgBoolean	GlgSetSResourceFromD (GlgObject object, char *resource_name, char *format, double value)
	Sets the string of an S (string) resource from a double value, converting the value into a string using a printf format string. More...
GlgBoolean	GlgSetSResourceFromDIf (GlgObject object, char *resource_name, char *format, double value, GlgBoolean if_changed)
	Sets the string of an S (string) resource from a double value, converting the value into a string using a printf format string. More...
GlgBoolean	GlgSetResourceFromObject (GlgObject object, char *resource_name, GlgObject value)
	Sets a new value of a data resource to the value of contained in the provided data object of the same data type. More...
GlgBoolean	GlgSetResourceFromObjectIf (GlgObject object, char *resource_name, GlgObject value, GlgBoolean if_changed)
	Sets the value of the data object to the value of another data object of the same data type. More...
GlgBoolean	GlgHasResourceObject (GlgObject object, char *resource_name)
	Checks if a named resource exists. More...
void	GlgChangeObject (GlgObject object, char *resource_path)
	Sends a change message to an object without actually changing the object's properties. More...
GlgBoolean	GlgSetDTag (GlgObject object, char *tag_source, double value, GlgBoolean if_changed)
	Sets a new value of a D (double) tag. More...
GlgBoolean	GlgGetDTag (GlgObject object, char *tag_source, double *value)
	Returns the current value of a D (double) tag. More...
GlgBoolean	GlgSetSTag (GlgObject object, char *tag_source, char *value, GlgBoolean if_changed)
	Replaces the string of an S (string) tag. More...
GlgBoolean	GlgGetSTag (GlgObject object, char *tag_source, char **value)
	Returns the current value of a S (string) tag. More...
GlgBoolean	GlgSetGTag (GlgObject object, char *tag_source, double x_value, double y_value, double z_value, GlgBoolean if_changed)
	Sets new values of a G (geometrical or color) tag. More...
GlgBoolean	GlgGetGTag (GlgObject object, char *tag_source, double *x_value, double *y_value, double *z_value)
	Returns the current value of a G (geometrical or color) tag. More...
GlgBoolean	GlgSetSTagFromD (GlgObject object, char *tag_source, char *format, double value, GlgBoolean if_changed)
	Replaces the string of an S (string) tag with a value specified by an input number and a format string. More...
GlgBoolean	GlgHasTagSource (GlgObject object, char *tag_source)
	Checks if a data tag with a specified tag source exists. More...
GlgBoolean	GlgHasTagName (GlgObject object, char *tag_source)
	Checks if a data tag with a specified tag name exists. More...
GlgObject	GlgCreateTagList (GlgObject object, GlgBoolean unique_tag_sources)
	Creates and returns a list of data tags defined in the drawing. More...
GlgLong	GlgExportTags (GlgObject object, char *filename, GlgLong separator1, GlgLong separator2)
	Writes tag names and tag sources of all data tags defined in a drawing to a tag translation file. More...
GlgLong	GlgImportTags (GlgObject object, char *filename, GlgBoolean verbose)
	Replaces the TagName and TagSource attributes of the data tags in a drawing with information loaded from a tag translation file. More...
void	GlgAddCallback (GlgObject viewport, GlgCallbackType type, GlgCallbackProc callback, GlgAnyType client_data)
	Adds a callback function to a viewport. More...
GlgLong	GlgGetSelectionButton (void)
	Queries the mouse button that initiated the callback. More...
GlgBoolean	GlgSetZoom (GlgObject object, char *resource_name, GlgLong type, double value)
	Provides a programmatic interface to integrated zooming and panning. More...
GlgBoolean	GlgSetZoomMode (GlgObject object, char *resource_name, GlgObject zoom_object, char *zoom_object_resource_name, GlgZoomMode zoom_mode)
	Sets or resets a viewport's zoom mode by supplying a GIS or Chart object to be zoomed. More...
GlgBoolean	GlgInitLocale (char *locale)
	Sets the program locale. More...
GlgLong	GlgExportStrings (GlgObject object, char *filename, GlgLong separator1, GlgLong separator2)
	Writes all text strings defined in the drawing to a string translation file. More...
GlgLong	GlgImportStrings (GlgObject object, char *filename, GlgBoolean verbose)
	Replaces text strings in the drawing with the strings loaded from a string translation file. More...
char *	GlgGetObjectName (GlgObject object)
	Returns an object's name. More...
GlgObjectType	GlgGetObjectType (GlgObject object)
	Returns an object's type. More...
GlgDataType	GlgGetDataType (GlgObject data_object)
	Returns a data object's data type. More...
GlgObject	GlgReferenceObject (GlgObject object)
	Increments an object's reference count. More...
GlgLong	GlgGetRefCount (GlgObject object)
	Returns an object's reference count. More...
void	GlgDropObject (GlgObject object)
	Decrements an object's reference count. More...
GlgLong	GlgAddWorkProc (GlgAppContext context, GlgWorkProc work_proc, GlgAnyType client_data)
	Adds a work procedure in a platform-independent way. More...
void	GlgRemoveWorkProc (GlgLong id)
	Removes a work procedure. More...
GlgLong	GlgAddTimeOut (GlgAppContext context, GlgLong interval, GlgTimerProc callback, GlgAnyType client_data)
	Adds an interval timer in a platform-independent way. More...
void	GlgRemoveTimeOut (GlgLong id)
	Removes a timer procedure. More...
GlgBoolean	GlgGetTime (GlgULong *sec, GlgULong *microsec)
	Returns number of seconds and microseconds since the Epoch. More...
void	GlgSleep (GlgLong millisec)
	Suspends application execution for a specified interval in a platform independent way. More...
void	GlgBell (GlgObject viewport)
	Produces an audio bell in a platform-independent way. More...
double	GlgRand (double low, double high)
	Generates a random number in a platform-independent way. More...
GlgBoolean	GlgSync (GlgObject viewport)
	Flushes the windowing system output to the display. More...
GlgAnyType	GlgGetNativeComponent (GlgObject object, char *resource_name, GlgComponentQueryType type)
	ADVANCED: Returns an ID of a native windowing system component used to render the viewport. More...
char *	GlgGetRelativePath (char *base_path, char *filename)
	Creates a filepath relative to the specified base path. More...
char *	GlgCreateRelativePath (char *base_path, char *filename, GlgBoolean return_null_if_not_found, GlgBoolean check_if_exists)
	Creates a filepath relative to the specified base path and provides options for checking if the path points to an existing file. More...
char *	GlgGetDir (char *path)
	Returns the directory portion of the specified path. More...
char *	GlgFindFile (char *filename, char *path, GlgBoolean check_glg_path)
	Searches for a file, first in the current directory, then in the specified directory and then in the GLG search path. More...
GlgBoolean	GlgSetCursorType (GlgObject viewport, char *resource_name, GlgCursorType cursor_type)
	Sets cursor for a drawing or one of its child viewports. More...
GlgLong	GlgGetMajorVersion (void)
	Returns the library's major version number. More...
GlgLong	GlgGetMinorVersion (void)
	Returns the library's minor version number. More...
GlgBoolean	GlgGetLParameter (char *name, GlgLong *value)
	Queries a value of a global parameter. More...
GlgBoolean	GlgSetLParameter (char *name, GlgLong value)
	Sets a value of a global parameter. More...
void	GlgPrintObjectCounts (void)
	Prints total object count for each of the GLG object types. More...
void	GlgPrintObjectCountChanges (void)
	Prints object count changes since the last call to this function. More...
GlgObject	GlgParseArgs (char *program_name, char *args_string, GlgLong *argc, char ***argv)
	This function is used by the GlgMain generic program entry point on Windows to parse command-line arguments. More...
char *	GlgGetURLCB (char *request, void *reserved)
	Fetches data from a URL and saves it in a temporary file. More...
GlgGetURLCallback	GlgSetGetURLCallback (GlgGetURLCallback callback)
	Installs a custom callback used to fetch data from URLs. More...
GlgBoolean	GlgResetSizeConstraint (GlgObject text_obj)
	Forces GLG_FIT_TO_BOX_TEXT Text objects with a constrained SizeConstraint attribute to renegotiate their font size. More...
GlgBoolean	GlgOnPrint (GlgObject viewport, HDC print_dc)
	Windows only: Provides MFC printing support. More...
GlgBoolean	GlgOnDrawMetafile (GlgObject viewport, HDC print_dc)
	Windows only: Provides MFC metafile output support. More...
GlgBoolean	GlgSetCursor (GlgObject viewport, char *resource_name, GlgLong cursor)
	Windows only: Sets a custom cursor for a drawing or one of its child viewports. More...
char *	GlgGetExePath (void)
	Windows only: Returns the path of the program's executable. More...
void	GlgLoadExeIcon (GlgObject viewport, GlgLong icon_id)
	Windows only: Loads small and big icons from the executable and associates them with the top level window of a viewport. More...
GlgObject	GlgGetNamedPlot (GlgObject object, char *resource_name, char *plot_name)
	Given a name of a chart's plot, returns the plot's object ID. More...
GlgObject	GlgGetSelectedPlot (void)
	Returns the plot object corresponding to the last legend item selected with the mouse, if any. More...
GlgObject	GlgAddPlot (GlgObject object, char *resource_name, GlgObject plot)
	Adds a plot line to a chart object. More...
GlgBoolean	GlgDeletePlot (GlgObject object, char *resource_name, GlgObject plot)
	Deletes a plot line from a chart. More...
GlgObject	GlgAddTimeLine (GlgObject object, char *resource_name, GlgObject time_line, double time_stamp)
	Adds a vertical time line to a chart object. More...
GlgBoolean	GlgDeleteTimeLine (GlgObject object, char *resource_name, GlgObject time_line, double time_stamp)
	Deletes a time line from a chart. More...
GlgObject	GlgAddAnnotation (GlgObject object, char *resource_name, GlgObject annotation, double position_x, double position_y, GlgBoolean add_box)
	Adds an annotation to a chart object. More...
GlgBoolean	GlgDeleteAnnotation (GlgObject object, char *resource_name, GlgObject annotation, double position_x, double position_y)
	Deletes an annottion from a chart. More...
GlgBoolean	GlgClearDataBuffer (GlgObject object, char *resource_name)
	Clears accumulated data samples of a real-time chart or one of its plots. More...
GlgBoolean	GlgUpdateChartTimeAxis (GlgObject object, char *resource_name, double time_stamp, GlgBoolean initialize)
	Scrolls the chart forward to show all data samples up to the provided time stamp or index. More...
GlgBoolean	GlgUpdateChartState (GlgObject object, char *resource_name, GlgChartState state)
	Triggers updating a chart's state after prefilling it with data using the quick mode of GlgAddDataSampleNode. More...
GlgBoolean	GlgSetLinkedAxis (GlgObject object, char *resource_name, GlgObject axis_object, char *axis_resource_name)
	Associates a chart's plot, level line or annotation object with an Y axis for automatic rescaling. More...
GlgBoolean	GlgGetChartDataExtent (GlgObject object, char *resource_name, GlgMinMax *min_max, GlgBoolean x_extent, GlgBoolean visible_only)
	Queries the minimum and maximum extent of the data accumulated in a chart or in one of its plots in the specified X or Y direction. More...
GlgBoolean	GlgSetLabelFormatter (GlgObject object, char *resource_name, GlgLabelFormatter formatter)
	Attaches a custom label formatter to a chart axis or a stand-alone axis object. More...
GlgBoolean	GlgSetChartFilter (GlgObject object, char *resource_name, GlgChartFilter chart_filter, void *client_data)
	Attaches a custom data filter to a chart's plot. More...
GlgBoolean	GlgGISConvert (GlgObject object, char *resource_name, GlgCoordType coord_type, GlgBoolean coord_to_lat_lon, GlgPoint *in_point, GlgPoint *out_point)
	Performs coordinate conversion from the GIS coordinates of the GIS Object to the GLG coordinates of the drawing and visa versa. More...
void	GlmConvert (GlgProjectionType projection, GlgBoolean stretch, GlgCoordType coord_type, GlgBoolean coord_to_lat_lon, GlgPoint *center, GlgPoint *extent, double angle, double min_x, double max_x, double min_y, double max_y, GlgPoint *in_point, GlgPoint *out_point)
	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. More...
GlgBoolean	GlgGISGetElevation (GlgObject object, char *resource_name, char *layer_name, double lon, double lat, double *elevation)
	Returns an elevation of a lat/lon point on a map. More...
GlgObject	GlgGISCreateSelection (GlgObject object, char *resource_name, char *layers, GlgLong x, GlgLong y, GlgLong select_labels)
	Returns a message object containing information about GIS features located at a specified position on the map. More...
GlgObject	GlgGISGetDataset (GlgObject object, char *resource_name)
	Returns a dataset object associated with the GIS Object. More...
void	GlgSetBrowserObject (GlgObject browser, GlgObject object)
	Sets the object for browsing with the GLG Resource, Tag and Alarm browser widgets. More...
GlgBoolean	GlgSetBrowserSelection (GlgObject object, char *resource_name, char *selection, char *filter)
	Sets a new value of a browser's Selection and Filter text boxes of the Resource, Tag, Alarm and Data browser widgets after the browser object has already been set up. More...
GlgBoolean	GlgSetEditMode (GlgObject viewport, char *resource_name, GlgBoolean edit_mode)
	Sets the viewport's edit mode to disable input objects in the viewport while the drawing is being edited. More...
GlgObject	GlgArrayCreate (GlgLong init_size, GlgLong increment)
	Creates a Simple Array object. More...
void	GlgArrayFlush (GlgObject object, GlgLong size)
	Set the size of a Simple Array. More...
GlgLong	GlgArrayGetSize (GlgObject object)
	Queries the size of a Simple Array. More...
GlgAnyType	GlgArrayGetElement (GlgObject object, GlgLong index)
	Returns the element at the specified position in a Simple Array. More...
GlgBoolean	GlgArraySetElement (GlgObject object, GlgLong elem_index, GlgAnyType elem)
	Sets the value of an element at the specified position in a Simple Array. More...
GlgBoolean	GlgArrayAddToBottom (GlgObject object, GlgAnyType elem)
	Add an element at the end of the Simple Array. More...
GlgBoolean	GlgArrayAddToTop (GlgObject object, GlgAnyType elem)
	Add an element at the beginning of the Simple Array. More...
GlgBoolean	GlgArrayAddAt (GlgObject object, GlgAnyType elem, GlgLong add_index)
	Insert an element at the specified position in the Simple Array. More...
GlgBoolean	GlgArrayDeleteLast (GlgObject object)
	Deletes the last element of the Simple Array. More...
GlgBoolean	GlgArrayDeleteFirst (GlgObject object)
	Deletes the first element of the Simple Array. More...
GlgBoolean	GlgArrayDeleteAt (GlgObject object, GlgLong delete_index)
	Delete an element at the specified position in the Simple Array. More...
GlgLong	GlgArrayGetIndex (GlgObject object, GlgAnyType elem)
	Returns the index of the first occurrence of an element in the Simple Array. More...

Function Documentation

GlgAddAnnotation()

GlgObject GlgAddAnnotation	(	GlgObject	object,
		char *	resource_name,
		GlgObject	annotation,
		double	position_x,
		double	position_y,
		GlgBoolean	add_box
	)

Adds an annotation to a chart object.

Parameters

object	A chart or a parent object containing the chart.
resource_name	A resource path for accessing the chart inside the parent. Use NULL when the object parameter specifies the chart.
annotation	An object ID of Text object that will be used as an annotation. NULL may be used to create a new annotation.
position_x	An annotation's position relative to the X axis.
position_y	An annotation's position relative to the Y axis.
add_box	If True, a text box will be added to the annotation's text object.

Returns

an object ID of the added annotation on success, or NULL on failure.

If the annotation parameter is NULL, the returned annotation is referenced only by the chart's annotation array it has been added to and may be destroyed when the chart scrolls. The program should increase the annotation's reference count if it needs to keep a persistent reference to it.

The chart's NumAnnotations attribute should be set to -1 in order to use this function

GlgAddCallback()

void GlgAddCallback	(	GlgObject	viewport,
		GlgCallbackType	type,
		GlgCallbackProc	callback,
		GlgAnyType	client_data
	)

Adds a callback function to a viewport.

Parameters

viewport	Specifies the viewport the callback will be added to. For the GLG_INPUT_CB callbacks, it may also be a light viewport.
type	Specifies the type of a callback to be added: GLG_INPUT_CB - adds Input callback GLG_SELECT_CB - adds Select callback GLG_TRACE_CB - adds Trace callback GLG_TRACE2_CB - adds Trace2 callback GLG_HIERARCHY_CB - adds Hierarchy callback.
callback	Specifies a callback function to be called.
client_data	Specifies client data to be passed to the callback function when it is called.

This function adds the specified callback to a viewport. A callback is a user-supplied function that is called by the GLG Toolkit upon some action:

• Input callback is invoked when an input widgets, such as a slider or a toggle, receives some user input. It is also invoked when an object in the viewport is selected.
• Select callback is invoked when a user selects an object in the widget's drawing area.
• Trace callback is invoked for every native windowing system event received by the viewport or its child viewports and may be used to handle these events.
• Hierarchy callback may be used to initialize loaded subdrawings.

See GlgInputCallback, GlgSelectCallback, GlgTraceCallback and GlgHierarchyCallback for the description of the available callback types.

Only one callback of each callback type may be added to an individual viewport. Any subsequent invocations of this function with the same callback type will overwrite the previous value of the viewport's callback. To remove a callback, call GlgAddCallback with NULL as a value of the callback parameter.

Note: Callbacks must be added before the drawing's hierarchy is set up.

Several callbacks of the same type may be added to different viewports on different levels of the drawing hierarchy. However, only the first encountered callback on the lowest level of the hierarchy will be called. For example, if an input callback is attached to a viewport and its child viewport, only the child viewport's callback will be invoked when input event occurs in the child viewport.

The viewport's ProcessMouse attribute controls processing of the mouse selection events and tooltips inside the viewport and its child viewports.

The GLG Wrapper Widgets also provide functions for adding callbacks to the drawings used by each widget.

See the Callback Events section of the Handling User Input and Other Events chapter of the GLG Programming Reference Manual for more information.

GlgAddPlot()

GlgObject GlgAddPlot	(	GlgObject	object,
		char *	resource_name,
		GlgObject	plot
	)

Adds a plot line to a chart object.

Parameters

object	A chart or a parent object containing the chart.
resource_name	A resource path for accessing the chart inside the parent. Use NULL when the object parameter specifies the chart.
plot	An object ID of a plot object. NULL may be used to create a new plot.

Returns

An object ID of the added plot on success, or NULL on failure.

If the plot parameter is NULL, the returned plot is referenced only by the chart's plot array it has been added to and may be destroyed when the number of plots changes. The program should increase the plot's reference count if it needs to keep a persistent reference to the plot.

GlgAddTimeLine()

GlgObject GlgAddTimeLine	(	GlgObject	object,
		char *	resource_name,
		GlgObject	time_line,
		double	time_stamp
	)

Adds a vertical time line to a chart object.

Parameters

object	A chart or a parent object containing the chart.
resource_name	A resource path for accessing the chart inside the parent. Use NULL when the object parameter specifies the chart.
time_line	An object ID of a Level Line object to be used as a time line. NULL may be used to create a new time line.
time_stamp	The time stamp to position the time line at. This value will be assigned to the time line's Level attribute.

Returns

An object ID of the added time line on success, or NULL on failure.

If the time_line parameter is NULL, the returned time line is referenced only by the chart's time line array it has been added to and may be destroyed when the chart scrolls. The program should increase the time line's reference count if it needs to keep a persistent reference to the time line.

The chart's NumTimeLines attribute should be set to -1 in order to use this function.

GlgAddTimeOut()

GlgLong GlgAddTimeOut	(	GlgAppContext	context,
		GlgLong	interval,
		GlgTimerProc	callback,
		GlgAnyType	client_data
	)

Adds an interval timer in a platform-independent way.

Parameters

context	The application context returned by GlgInit.
interval	Time interval in milliseconds.
callback	A callback function to be called when the time expires.
client_data	Client data to be passed to the callback when it is called.

Returns

The timer ID that can be used by GlgRemoveTimeOut.

This function adds a callback function which is called when the specified time interval expires. See GlgTimerProc for the timer callback prototype.

The interval timer is called only once and is removed immediately after it has been called. GlgRemoveTimeOut may be used to remove an active timeout. If you want the timer procedure to be called continuously, the timer callback itself should call GlgAddTimeOut.

GlgAddWorkProc()

GlgLong GlgAddWorkProc	(	GlgAppContext	context,
		GlgWorkProc	work_proc,
		GlgAnyType	client_data
	)

Adds a work procedure in a platform-independent way.

Parameters

context	The application context returned by GlgInit.
work_proc	A work procedure function to be called repeatedly.
client_data	Client data to be passed to the work procedure when it is called.

Returns

The work procedure ID that can be used by GlgRemoveWorkProc.

This function adds a work procedure. A work procedure is a function to be called repeatedly while the application is waiting for an event. See GlgWorkProc for the work procedure prototype.

If a work procedure returns True, it is removed and will not be called again. If it returns false, it will be called continuously until the application calls the GlgRemoveWorkProc function.

Several work procedures may be added to be performed one at a time. Work procedures must return quickly to avoid response time delays.

GlgAlloc()

void* GlgAlloc

(

GlgLong

size

)

Allocates memory using the Toolkit's memory allocator.

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

Parameters

size	Specifies the size of a memory block in bytes.

Returns

Pointer to the allocated memory.

GlgArrayAddAt()

GlgBoolean GlgArrayAddAt	(	GlgObject	object,
		GlgAnyType	elem,
		GlgLong	add_index
	)

Insert an element at the specified position in the Simple Array.

Parameters

object	Simple Array object.
elem	The element to add.
add_index	The position at which the new element will be inserted.

Returns

Success or failure status. If the specified index is invalid, an error message is generated and False is returned.

All elements at and below the insertion point will be shifted down inside the array.

GlgArrayAddToBottom()

GlgBoolean GlgArrayAddToBottom	(	GlgObject	object,
		GlgAnyType	elem
	)

Add an element at the end of the Simple Array.

Parameters

object	Simple Array object.
elem	The element to add.

Returns

Success or failure status.

GlgArrayAddToTop()

GlgBoolean GlgArrayAddToTop	(	GlgObject	object,
		GlgAnyType	elem
	)

Add an element at the beginning of the Simple Array.

Parameters

object	Simple Array object.
elem	The element to add.

Returns

Success or failure status.

GlgArrayCreate()

GlgObject GlgArrayCreate	(	GlgLong	init_size,
		GlgLong	increment
	)

Creates a Simple Array object.

Parameters

init_size	Initial size of the dynamic array. A default size is used if the parameter value is 0.
increment	Size increment used to increase the size of the array. A default increment is used if the parameter value is 0.

Returns

A dynamic array of the initial size, with all elements initialized with zeros.

The created dynamic array has elements of GlgAnyType that can hold either GlgLong elements or pointers. The array is created with the initial size specified by the initial_size parameter. When new elements are added to the array, it will increase its size using the specified size increment.

GlgArrayDeleteAt()

GlgBoolean GlgArrayDeleteAt	(	GlgObject	object,
		GlgLong	delete_index
	)

Delete an element at the specified position in the Simple Array.

Parameters

object	Simple Array object.
delete_index	The index of the element to delete.

Returns

Success or failure status. If the specified index is invalid, an error message is generated and False is returned.

All elements below the deleted element will be shifted up inside the array.

GlgArrayDeleteFirst()

GlgBoolean GlgArrayDeleteFirst

(

GlgObject

object

)

Deletes the first element of the Simple Array.

Parameters

object

Simple Array object.

Returns

Success or failure status.

All remaining array elements will be shifted up inside the array.

GlgArrayDeleteLast()

GlgBoolean GlgArrayDeleteLast

(

GlgObject

object

)

Deletes the last element of the Simple Array.

Parameters

object

Simple Array object.

Returns

Success or failure status.

GlgArrayFlush()

void GlgArrayFlush	(	GlgObject	object,
		GlgLong	size
	)

Set the size of a Simple Array.

Parameters

object	Simple Array object.
size	The new size.

This function sets the array size to the requested size. If the new size is less than the current array size, extra elements are removed. If the new size is greater than the current size, the function adds elements by making a copy of the last element in the array.

It is the responsibility of an application to free any associated memory (if any) when elements are deleted from the array.

GlgArrayGetElement()

GlgAnyType GlgArrayGetElement	(	GlgObject	object,
		GlgLong	index
	)

Returns the element at the specified position in a Simple Array.

Parameters

object	Simple Array object.
index	Element position inside the array.

Returns

The element at the specified index.

If the specified index is invalid, an error message is generated and NULL is returned.

GlgArrayGetIndex()

GlgLong GlgArrayGetIndex	(	GlgObject	object,
		GlgAnyType	elem
	)

Returns the index of the first occurrence of an element in the Simple Array.

Parameters

object	Simple Array object.
elem	The element to search for.

Returns

Index of the element, or -1 if the element was not found in the array.

GlgArrayGetSize()

GlgLong GlgArrayGetSize

(

GlgObject

object

)

Queries the size of a Simple Array.

Parameters

object

Simple Array object.

Returns

Array size.

GlgArraySetElement()

GlgBoolean GlgArraySetElement	(	GlgObject	object,
		GlgLong	elem_index,
		GlgAnyType	elem
	)

Sets the value of an element at the specified position in a Simple Array.

Parameters

object	Simple Array object.
elem_index	The index of the array element whose value to set.
elem	The new element value.

Returns

Success or failure status. If the specified index is invalid, an error message is generated and False is returned.

GlgBell()

void GlgBell

(

GlgObject

viewport

)

Produces an audio bell in a platform-independent way.

Parameters

viewport

Specifies a viewport or a light viewport. This viewport object must be displayed; it specifies the display at which to produce the bell. On Windows, this parameter is ignored and may be NULL.

GlgChangeObject()

void GlgChangeObject	(	GlgObject	object,
		char *	resource_path
	)

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

Parameters

object	The object to send the message to.
resource_path	If 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 path. The resource path is relative to the object parameter.

This function may be used to send a change message an object's attribute. Sending the message to an object attribute is equivalent to setting the attribute to the same value as its current value using one of the GlgSetDResource, GlgSetSResource or GlgSetDResource functions.

For example, sending the message to the Factor attribute of a volatile series object forces the series to recreate its instances without actually changing the value of the Factor. If the 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).

Sending the change message to a drawable object forces the object to redraw. If the message is sent to an object like a polygon or a text object, the area of the object's bounding box gets invalidated and redrawn. If an object is a viewport, it redraws its content.

GlgClearDataBuffer()

GlgBoolean GlgClearDataBuffer	(	GlgObject	object,
		char *	resource_name
	)

Clears accumulated data samples of a real-time chart or one of its plots.

Parameters

object	Specifies a chart, a plot or a parent object containing them.
resource_name	If not NULL, specifies a resource path for accessing the chart or one of its plots inside the container specified by the object parameter. Use NULL when the object parameter specifies a chart or plot object.

Returns

Success or failure status.

For a Chart object, GlgClearDataBuffer discards data samples in all plots of the chart. For a Plot object, it discards only the data samples of that plot.

GlgConcatResNames()

char* GlgConcatResNames	(	char *	resource_name1,
		char *	resource_name2
	)

Creates a composite resource path from two components.

Parameters

resource_name1	Specifies the first resource path component.
resource_name2	Specifies the second resource path component.

Returns

Created resource path.

This function creates and returns a resource path formed by concatenating the two components with the / character between them. The function checks if a trailing / separator is already present in the first string, and adds it only if the separator is not present.

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 path should be freed later with GlgFree.

Examples

The following code:

char * resource_path = GlgConcatResNames( "DataGroup", "DataSample2" );
printf( "resource_path: %s\n", resource_path );
GlgFree( resource_path );

produces the following output:

resource_path: DataGroup/DataSample2

Multiple calls to GlgConcatResNames may be used to create composite paths from more than two components:

char * temp_name = GlgConcatResNames( "DataGroup", "DataSample2" );
char * resource_path = GlgConcatResNames( temp_name, "Value" );
GlgFree( temp_name )
printf( "resource_path: %s\n", resource_path );
GlgFree( resource_path );

producing the following output:

resource_path: DataGroup/DataSample2/Value

GlgConcatStrings()

char* GlgConcatStrings	(	char *	string1,
		char *	string2
	)

Concatenates two character strings.

Parameters

string1	The first string to be concatenated.
string2	The second string to be concatenated.

Returns

The concatenated string.

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 GlgFree. GlgFree also handles NULL pointers, so the following code may be used without needing to check for NULL values:

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

GlgConfigureWindow()

GlgBoolean GlgConfigureWindow	(	GlgObject	object,
		GlgLong	x,
		GlgLong	y,
		GlgLong	width,
		GlgLong	height,
		GlgConfigureMask	mask,
		GlgObject	parent
	)

Sets the size and/or position of a viewport's window.

This function is new in the GLG release 4.5.

Parameters

object	Specifies the viewport to be configured.
x	Specifies X coordinate of the window origin.
y	Specifies Y coordinate of the window origin.
width	Specifies window width.
height	Specifies window height.
mask	Specifies bitwise flags that control the action to perform, set size, set position or both: GLG_POSITION_MASK Requests to set window position using x and y parameters and ignore the position defined by the viewport's control points. For top-level viewports, the x and y parameters specify position in screen coordinates relative to the origin of the screen. For child viewports and embedded dialog viewports, position parameters specify position relative to the origin of their parent viewport's window. GLG_SIZE_MASK Requests to set window size using width and height parameters and ignore the width and height defined by the viewport's control points. GLG_POSITION_AND_SIZE_MASK Requests to set both the size and position, is equivalent to: GLG_POSITION_MASK | GLG_SIZE_MASK GLG_RESET_POSITION_MASK Resets the position request to restore the position defined by the viewport's control points. GLG_RESET_SIZE_MASK Resets the size request to restore the width and height defined by the viewport's control points. The set and reset flags are exclusive and can't be used together for the same size or position attribute.
parent	Specifies an optional parent viewport for dialog viewports displayed via the GlgDialogSetupHierarchy or GlgDialogInitialDraw functions, or NULL otherwise.

Returns

Success or failure status.

Once the viewport's size or position is set using GlgConfigureWindow, the viewport's control points are no longer used for controlling the viewport's size and/or position. If only the viewport's position is set and not its size, the size will be still controlled by the viewport's control points, and vice versa if only the size is set and not the position. The mask parameter of the function contains options to restore the use of the control points for determining the viewport's size or position after it was set with GlgConfigureWindow.

GlgCreateAlarmList()

GlgObject GlgCreateAlarmList

(

GlgObject

object

)

Creates and returns a list of alarms defined in the drawing.

Parameters

object

An object whose alarms are queried. The top level viewport may be used to query a list of alarms of the whole drawing.

Returns

A group containing all alarm objects, or NULL if no alarm objects were found. The returned group object must be dereferenced using GlgDropObject when it is no longer needed.

Each element of the returned group is an data object that has an alarm attached. The GlgGetElement and GlgGetSize functions of the Intermediate API may be used within the Standard API to handle the returned group object.

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

Example

The following code prints information about all alarms defined in the drawing:

char * alarm_label;
 
GlgObject alarm_list = GlgCreateAlarmList( viewport );
if( alarm_list )
{
   int size = GlgGetSize( alarm_list );
   for( int i=0; i<size; ++i )
   {
      // The data object the alarm is attached to.
      GlgObject data_object = GlgGetElement( alarm_list, i );
 
      // AlarmLabel may be unnamed, extract it as the XformAttr1 resource of the alarm object.
      GlgGetSResource( data_object, "Alarm/XformAttr1", &alarm_label );
      printf( "AlarmLabel: %s\n", alarm_label );
    }
    GlgGropObject( alarm_list );
 }

GlgCreateIndexedName()

char* GlgCreateIndexedName	(	char *	template_name,
		GlgLong	resource_index
	)

Creates a string with a name of an enumerated resource.

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 the % character in the template name.

Returns

Created resource 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 GlgFree.

Examples

The following code:

for( int i=0; i<3; ++i )
{
   char * 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

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

char * name1 = GlgCreateIndexedName( "Chart%/Plots/Plot#%/Value", 4 );
char * name2 = GlgCreateIndexedName( name1, 3 );
GlgFree( name1 );
printf( "Name: %s\n", name2 );
GlgFree( name2 );

produces the following output:

Name: Chart4/Plots/Plot#3/Value

GlgCreateRelativePath()

char* GlgCreateRelativePath	(	char *	base_path,
		char *	filename,
		GlgBoolean	return_null_if_not_found,
		GlgBoolean	check_if_exists
	)

Creates a filepath relative to the specified base path and provides options for checking if the path points to an existing file.

Parameters

base_path	Specifies a base path. NULL can be used on Windows to use the location of the program's executable.
filename	A filename or a relative filepath. If an absolute path is specified, it will be used as is.
return_null_if_not_found	Controls the return value in case when check_if_exists=True and the file pointed to by the created relative path does not exist. If True, NULL is returned, otherwise a copy of the filename string is returned.
check_if_exists	Specifies if the function should check if the file pointed to by the created relative path exists.

Returns

An allocated file path string that has to be freed with GlgFree.

This function is an extended version of GlgGetRelativePath that checks if the file exists and provides additional options for handing non-existent files.

If filename specifies an absolute path, it will be used as is. Otherwise, GlgCreateRelativePath extracts the directory portion of base_path using GlgGetDir and appends filename. If base_path is a directory path that does not point to an existing directory, it must end with '/', or either '/' or '\' on Windows.

If check_if_exists=True, the function checks is the created file path points to an existing file and handles it depending on the setting of the return_null_if_not_found parameter. If check_if_exists=False, the created file path is returned without any checking.

GlgCreateTagList()

GlgObject GlgCreateTagList	(	GlgObject	object,
		GlgBoolean	unique_tag_sources
	)

Creates and returns a list of data tags defined in the drawing.

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 True, only the first encountered tag of the highest priority will be added to the list for tags with the same tag source. Input tags are prioritized over output tags, and enabled tags over disabled tags. If False, all instances with the same tag source will be included.

Returns

A group containing all data tag objects, or NULL if no tags were found. The returned group object must be dereferenced using GlgDropObject when it is no longer needed.

Each element of the returned group is an attribute object that has a data tag attached. The GlgGetElement and GlgGetSize functions of the Intermediate API may be used within the Standard API to handle the returned group object.

If object is not a viewport, the returned tag list 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 prints information about all tags defined in the drawing:

char * tag_name, * tag_source;
 
// Query list of tags defined in the drawing.
GlgObject tag_list = GlgCreateTagList( viewport, False );
if( tag_list )
{
   int size = GlgGetSize( tag_list );
   for( int i=0; i<size; ++i )
   {
      // Query TagName and TagSource of each tag.
      GlgObject tag_object = GlgGetElement( tag_list, i );
      GlgGetSResource( tag_object, "TagName", &tag_name );
      GlgGetSResource( tag_object, "TagSource", &tag_source );
      printf( "TagName: %s, TagSource: %s\n", tag_name, tag_source );
   }
   // Free the tag list.
   GlgGropObject( tag_list );
}

Tag Access Performance Optimization

Since tags returned by GlgCreateTagList are actually data objects the tags are attached to, their object IDs may be stored and then used repeatedly to optimized tag access performance when tags are used to supply data for a drawing with large number of tags.

Instead of setting new tag values with GlgSetDTag:

GlgSetDTag( viewport, tag_source, new_value, True );

the stored object IDs may be used with the the GlgSetDResource function using NULL as the resource_name parameter to set a new value of each data object directly without an overhead of searching the drawing for each tag by its TagSource:

GlgSetDResourceIf( tag_object, NULL, new_value, True );

The GlgAddDataSampleNode function of the Intermediate API can also be used instead of setting values of chart entry points to prefill a chart with a large number of data samples.

The GlgGetTagObject and GlgQueryTags functions of the Intermediate API provide extended functionality for querying both data and export tags.

GlgDeleteAnnotation()

GlgBoolean GlgDeleteAnnotation	(	GlgObject	object,
		char *	resource_name,
		GlgObject	annotation,
		double	position_x,
		double	position_y
	)

Deletes an annottion from a chart.

Parameters

object	A chart or a parent object containing the chart.
resource_name	A resource path for accessing the chart inside the parent. Use NULL when the object parameter specifies the chart.
annotation	The annotation object to delete. If NULL, the annotation with the time stamp specified by the position_x and position_y parameters will be deleted.
position_x	The X position of the annotation to be deleted when the annotation parameter is NULL. The parameter is ignored if annotation is not NULL.
position_y	The Y position of the annotation to be deleted when the annotation parameter is NULL. The parameter is ignored if annotation is not NULL.

Returns

True if the annotation was successfully deleted.

The chart's NumAnnotations attribute should be set to -1 in order to use this function.

GlgDeletePlot()

GlgBoolean GlgDeletePlot	(	GlgObject	object,
		char *	resource_name,
		GlgObject	plot
	)

Deletes a plot line from a chart.

Parameters

object	A chart or a parent object containing the chart.
resource_name	A resource path for accessing the chart inside the parent. Use NULL when the object parameter specifies the chart.
plot	The plot object to delete.

Returns

True if the plot was successfully deleted.

GlgDeleteTimeLine()

GlgBoolean GlgDeleteTimeLine	(	GlgObject	object,
		char *	resource_name,
		GlgObject	time_line,
		double	time_stamp
	)

Deletes a time line from a chart.

Parameters

object	A chart or a parent object containing the chart.
resource_name	A resource path for accessing the chart inside the parent. Use NULL when the object parameter specifies the chart.
time_line	The object ID of the time line to delete. If NULL, the time line with the time stamp specified by time_stamp will be deleted.
time_stamp	The time stamp of the time line to be deleted when the time_line parameter is NULL. The parameter is ignored if time_line is not NULL.

Returns

True if the time line was successfully deleted.

The chart's NumTimeLines attribute should be set to -1 in order to use this function.

GlgDialogInitialDraw()

void GlgDialogInitialDraw	(	GlgObject	object,
		GlgObject	parent
	)

Displays a GLG drawing as a floating dialog for the first time after it has been created or loaded.

Parameters

object	Specifies the viewport containing the dialog's drawing.
parent	Specifies the viewport of the main drawing the dialog will be a child of.

This function is similar to GlgInitialDraw, with the only difference that the drawing will be displayed as a child dialog of the main drawing specified by the parent parameter.

GlgConfigureWindow may be used to set the dialog's size and position.

GlgDialogSetupHierarchy()

void GlgDialogSetupHierarchy	(	GlgObject	object,
		GlgObject	parent
	)

Provides an explicit request to set up the object hierarchy of a drawing displayed in a dialog window.

Parameters

object	Specifies the viewport containing the dialog's drawing.
parent	Specifies the viewport of the main drawing the dialog will be a child of.

This function similar to GlgSetupHierarchy, with the only difference that the drawing will be set up as a child dialog of the main drawing specified by the parent parameter.

This method needs to be invoked only on the initial draw of the dialog. After the dialog has been set up, a generic GlgSetupHierarchy function may be used for all objects, including the dialog.

GlgDropObject()

void GlgDropObject

(

GlgObject

object

)

Decrements an object's reference count.

Parameters

object

The object to be dereferenced.

This function decreases the object's reference count by 1. If the reference count goes to 0, the object is destroyed. Destroying an object dereferences all its subsidiary objects and may destroy them as well if their reference counts become zero.

GlgDropObject should be used to dereference the object after creating, copying, loading or referencing the object, as was shown in the first coding example for the GlgReferenceObject function.

GlgError()

void GlgError	(	GlgErrorType	type,
		char *	message
	)

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

See GlgErrorType for details on how different message types are handled by the default error handler.

Parameters

type	Specifies the type of the error message.
message	The message to be displayed.

GlgExportPostScript()

GlgBoolean GlgExportPostScript	(	GlgObject	object,
		char *	file,
		double	x,
		double	y,
		double	width,
		double	height,
		GlgBoolean	portrait,
		GlgBoolean	stretch,
		GlgBoolean	center
	)

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

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.
x	Defines the X coordinate of the upper left corner of the rectangle on the page containing the PostScript output. All coordinates are specified in the world coordinate system, which maps a rectangle defined by the points (0;0) and (2000;2000) to a page.
y	Defines the Y coordinate of the upper left corner of the rectangle.
width	Defines the width of the rectangle.
height	Defines the height of the rectangle.
portrait	Specifies the orientation of the PostScript output on the page. If True, 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 True, the PostScript output will be stretched to fit the rectangle exactly. This may distort printed objects. If False, 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.
center	Specifies whether or not PostScript output should be centered inside the specified output rectangle when stretch=False results in unused space on the sides of the rectangle. If True, the output will be centered inside the output area, otherwise it will be anchored in the upper left corner of the rectangle.

Returns

True if PostScript output was successfully written to the file, otherwise False.

The drawing's hierarchy must be set up in order to generate PostScript output. Use GlgUpdate before calling GlgExportPostScript to make sure the drawing is up to date.

GlgExportStrings()

GlgLong GlgExportStrings	(	GlgObject	object,
		char *	filename,
		GlgLong	separator1,
		GlgLong	separator2
	)

Writes all text strings defined in the drawing to a string translation file.

Parameters

object	Specifies a viewport or an object whose text strings to export.
filename	Specifies the filename of the string translation file.
separator1	Defines the first separator character to be used in the generated file.
separator2	Defines the second separator character to be used in the generated file.

Returns

The number of exported strings or -1 in case of an error.

This function exports all strings defined in the drawing to an ASCII string translation file that can be edited using a text editor.

The function exports strings of the S (string) resource objects, such as the String attribute of a text object. It does not export strings that are not values of the S resource objects, such as object names, tag names and tag sources, which makes sure that the program logic is not affected by the string changes.

The string translation file contains a line for each exported string. Each string entry contains the name of a string resource which helps identify how the string is used, and two copies of the string: the current value and the new value. Each item in the string entry is separated by two separator characters. The name of the string resource and the first copy of the string are used to identify the string and should not be changed.

When the file is translated, the second copy of the string (the new value) may be replaced with a new string representing the text in the local language and local character set. Multiple copies of the file can be created, one for each supported language.

The GlgImportStrings function can be used at run time to display a localized drawing. An application can load different versions of the translated file to display localized drawings for different language environments.

This function provides a programming interface for exporting strings from a drawing. The File, Export Strings option of the GLG editors can be used to export strings from the loaded drawing, in which case two double quotation characters are used as the default separators. This can be changed by defining the GLG_STRING_SEPARATOR environment variable to supply a two character string to be used as a separator.

Refer to the Localization Support section of the GLG User's Guide and Builder Reference Manual for more information about the string translation file format.

GlgExportTags()

GlgLong GlgExportTags	(	GlgObject	object,
		char *	filename,
		GlgLong	separator1,
		GlgLong	separator2
	)

Writes tag names and tag sources of all data tags defined in a drawing to a tag translation file.

Parameters

object	Specifies a viewport or an object whose tags to export.
filename	Specifies the filename of the tag translation file.
separator1	Defines the first separator character to be used in the generated file.
separator2	Defines the second separator character to be used in the generated file.

Returns

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

This function exports all data tags defined in the drawing to an ASCII tag file that can be edited using a text editor.

Each tag entry contains two copies of the tag's TagName and TagSource attributes separated by two separator characters. The first copy of the TagName and TagSource attributes contains the current values. It is used to identify the tag and should not be changed.

The second copy of the attributes contains new values that may be changed to modify the tag. The new value of the TagSource attribute supplies the data source variable associated with the tag. Tag names can also be localized by translating new values of the TagName attributes to different languages.

The file can be edited to modify new values, and then imported into the drawing using GlgImportTags.

This makes it possible to use the drawing as a template, and modify it on the fly to use a different set of tags. This technique may be used to create a single drawing, and then use it at run time to display different sections of a plant or different rooms of a data center. Alternatively, tag remapping may also be done programmatically as shown in the GLG demos.

This function provides a programming interface for exporting tag from a drawing. The File, Export Tags option of the GLG editors can be used to export tags from the loaded drawing, in which case two double quotation characters are used as the default separators. This can be changed by defining the GLG_STRING_SEPARATOR environment variable to supply a two character string to be used as a separator.

Refer to the Tag Export and Import Features for Run-Time Tag Mapping section of the GLG User's Guide and Builder Reference Manual for more information about the tag file format.

GlgFindFile()

char* GlgFindFile	(	char *	filename,
		char *	path,
		GlgBoolean	check_glg_path
	)

Searches for a file, first in the current directory, then in the specified directory and then in the GLG search path.

Parameters

filename	A relative filename to search for. If an absolute path is specified, it will be used as is.
path	If not NULL, specifies a directory to be searched before using the GLG search path.
check_glg_path	If True, the GLG search path will be included in the search.

Returns

A filepath pointing to the found file. If the file was not found, a copy of the filename is returned. The returned string has to be freed with GlgFree.

Searches for a file specified by filename, first in the current directory, then in the directory provided by the path parameter and then in the GLG search path.

If the file was found, the function returns its file path, otherwise it returns a copy of the filename parameter. The returned file path can be passed to fopen to open the file.

GlgFree()

void GlgFree

(

void *

ptr

)

Frees memory used to store character strings or allocated using GlgAlloc.

Parameters

ptr	Specifies a memory pointer to be freed.

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

The function checks for NULL address pointers, and will not fail or generate an error message if a NULL pointer is passed.

GlgGenerateImage()

PlatformDependent GlgGenerateImage	(	GlgObject	object,
		char *	resource_name,
		PlatformDependent	image
	)

Creates and returns an image of the current state of the viewport's graphics.

Parameters

object	Specifies a viewport object or a viewport's parent.
resource_name	Specifies the resource path of a child viewport whose image to generate, or NULL to generate the image of the viewport specified by the object parameter. The resource path is relative to the object specified by the object parameter.
image	If not NULL, specifies a platform-dependent image to be used. This image will be filled and returned instead of creating and returning a new image. The type of the image is platform-dependent: cairo_surface_t* in GTK Pixmap on X11 HBITMAP on Windows.

Returns

The generated image or NULL if image generation failed. The type of the returned image is platform-dependent:

• cairo_surface_t* in GTK
• Pixmap on X11
• HBITMAP on Windows.

GlgGenerateImage creates an image of the visible part of the viewport, clipping out the parts of the drawing that extends outside of it.

For a light viewport, the output will be generated for its parent viewport. The drawing's hierarchy must be set up in order to generate an image.

GlgGenerateImageCustom()

PlatformDependent GlgGenerateImageCustom	(	GlgObject	object,
		char *	resource_name,
		PlatformDependent	image,
		GlgLong	x,
		GlgLong	y,
		GlgLong	width,
		GlgLong	height,
		GlgLong	gap
	)

Creates an image of the specified rectangular region of the viewport's graphics.

Parameters

object	Specifies a viewport object or a viewport's parent.
resource_name	Specifies the resource path of a child viewport whose image to generate, or NULL to generate the image of the viewport specified by the object parameter. The resource path is relative to the object specified by the object parameter.
image	If not NULL, specifies a platform-dependent image to be used. This image will be filled and returned instead of creating and returning a new image. The type of the image is platform-dependent: cairo_surface_t* in GTK Pixmap on X11 HBITMAP on Windows.
x	Specifies the X coordinate of the area used for generating an image. It defines an offset in screen pixels relative to the origin of the viewport's window, which has screen coordinates of (0,0).
y	Specifies the Y coordinate of the area used for generating an image. It defines an offset in screen pixels relative to the origin of the viewport's window, which has screen coordinates of (0,0).
width	Specifies the width in screen pixels of the area used for generating an image.
height	Specifies the height in screen pixels of the area used for generating an image.
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.

Returns

The generated image or NULL if image generation failed. The type of the returned image is platform-dependent:

• cairo_surface_t* in GTK
• Pixmap on X11
• HBITMAP on Windows.

The x, y, width and height 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 using GlgGetBoxPtr.

If width and height parameters are 0, the image of the whole drawing is generated using the drawing's bounding rectangle as the image generation area, without clipping to just the visible area. 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.

For a light viewport, the output will be generated for its parent viewport. The drawing's hierarchy must be set up in order to generate an image.

GlgGetChartDataExtent()

GlgBoolean GlgGetChartDataExtent	(	GlgObject	object,
		char *	resource_name,
		GlgMinMax *	min_max,
		GlgBoolean	x_extent,
		GlgBoolean	visible_only
	)

Queries the minimum and maximum extent of the data accumulated in a chart or in one of its plots in the specified X or Y direction.

Parameters

object	A chart, a plot or a parent object containing the chart.
resource_name	A resource path to access the chart or the plot inside the object. Use NULL when the object parameter specifies a chart or a plot. The resource path is relative to the object specified by the object parameter.
min_max	The receiver of the returned data extent.
x_extent	If True, the function returns the X extent, otherwise it returns the Y extent.
visible_only	If True, the function considers only visible data samples when calculating data extent, otherwise all samples are considered.

Returns

Success or failure status.

If the object and resource_name parameters point to a chart object, the data extent of all plots in the chart is returned. If object and resource_name point to a plot, the data extent of that plot is returned.

The object hierarchy must be set up for this function to succeed.

GlgGetDataType()

GlgDataType GlgGetDataType

(

GlgObject

data_object

)

Returns a data object's data type.

Parameters

data_object

A data object.

Returns

An object's data type.

GlgGetDir()

char* GlgGetDir

(

char *

path

)

Returns the directory portion of the specified path.

Parameters

path	A file or directory path.

Returns

A copy of the path string with the filename component removed from the path. The returned string has to be freed with GlgFree.

The filename is the last component after the last file separator (a forward slash on Linux/Unix, either a forward or backward slash on Windows). A trailing file separator is not removed from the returned string.

If NULL is passed as the path parameter, NULL will be returned. An allocated string representing a current directory ("./" or ".\" on Windows) will be returned if an empty string is passed as path.

A copy of the path string will be returned without changing it (except for an added trailing file separator, if needed) if:

• the path ends with the file separator, in which case it is considered a directory path
• the path points to a real directory on the file system
• the path represents the current directory (".") or the parent directory (".."), with or without a trailing file separator.

GlgGetDResource()

GlgBoolean GlgGetDResource	(	GlgObject	object,
		char *	resource_name,
		double *	value
	)

Returns the current value of a D (double) resource.

Parameters

object	Specifies a GLG object.
resource_name	Specifies the resource path of the scalar resource to query.
value	Specifies a pointer used to return the resource value.

Returns

Success or failure status.

If a scalar resource with the given resource path exists, this function copies its current value into the address specified by the value pointer and returns True, otherwise it generates an error message and returns False.

GlgGetDTag()

GlgBoolean GlgGetDTag	(	GlgObject	object,
		char *	tag_source,
		double *	value
	)

Returns the current value of a D (double) tag.

Parameters

object	Specifies a GLG object.
tag_source	Specifies the TagSource of the scalar tag to query.
value	Specifies a pointer used to return the tag value.

Returns

Success or failure status.

If a scalar tag with the given TagSource exists, this function copies its current value into the address specified by the value pointer and returns True, otherwise it generates an error message and returns False.

GlgGetExePath()

char* GlgGetExePath

(

void

)

Windows only: Returns the path of the program's executable.

Returns

An allocated string that has to be freed with GlgFree.

GlgGetGResource()

GlgBoolean GlgGetGResource	(	GlgObject	object,
		char *	resource_name,
		double *	x_value,
		double *	y_value,
		double *	z_value
	)

Returns the current value of a G (geometrical or color) resource.

Parameters

object	Specifies a GLG object.
resource_name	Specifies the resource path of the G resource to query.
x_value	Specifies a pointer used to return the X value of a geometrical resource or an R component of the color resource.
y_value	Specifies a pointer used to return the Y value of a geometrical resource or a G component of the color resource.
z_value	Specifies a pointer used to return the Z value of a geometrical resource or a B component of the color resource.

Returns

Success or failure status.

If a G resource or with the given resource path exists, this function copies its current three values to the addresses specified with the x_value, y_value and z_value pointers and returns True. Otherwise, it generates an error message and returns False.

GlgGetGTag()

GlgBoolean GlgGetGTag	(	GlgObject	object,
		char *	tag_source,
		double *	x_value,
		double *	y_value,
		double *	z_value
	)

Returns the current value of a G (geometrical or color) tag.

Parameters

object	Specifies a GLG object.
tag_source	Specifies the TagSource of the G tag to query. All object's tags with the specified TagSource will be set to the supplied values.
x_value	Specifies a pointer used to return the X value of a geometrical tag or an R component of the color tag.
y_value	Specifies a pointer used to return the Y value of a geometrical tag or a G component of the color tag.
z_value	Specifies a pointer used to return the Z value of a geometrical tag or a B component of the color tag.

Returns

Success or failure status.

If a G tag with the given TagSource exists, this function copies its current three values to the addresses specified with the x_value, y_value and z_value pointers and returns True. Otherwise, it generates an error message and returns False.

GlgGetLParameter()

GlgBoolean GlgGetLParameter	(	char *	name,
		GlgLong *	value
	)

Queries a value of a global parameter.

Parameters

name	Parameter name.
value	A pointer used to return a parameter's value.

Returns

Success or failure status.

Refer to the Appendix D: Global Parameters section of the GLG Programming Reference Manual for information on available global parameters.

GlgGetMajorVersion()

GlgLong GlgGetMajorVersion

(

void

)

Returns the library's major version number.

Returns

Major version number.

The GLG_MAJOR_VERSION macro also provides the major version number.

GlgGetMinorVersion()

GlgLong GlgGetMinorVersion

(

void

)

Returns the library's minor version number.

Returns

Minor version number.

The GLG_MINOR_VERSION macro also provides the minor version number.

GlgGetNamedPlot()

GlgObject GlgGetNamedPlot	(	GlgObject	object,
		char *	resource_name,
		char *	plot_name
	)

Given a name of a chart's plot, returns the plot's object ID.

Parameters

object	A chart or a parent object containing a chart.
resource_name	A resource path for accessing the chart inside the parent. Use NULL when the object parameter specifies the chart.
plot_name	The plot name.

Returns

The found plot, or NULL if a plot with the specified name was not found.

GlgGetNativeComponent()

GlgAnyType GlgGetNativeComponent	(	GlgObject	object,
		char *	resource_name,
		GlgComponentQueryType	type
	)

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

The function provides an access to native windowing components used to render the viewport, making it possible to set their windowing system specific properties.

Parameters

object	A viewport or a viewport's parent.
resource_name	A resource path for accessing the child viewport inside its parent. Use NULL when the object parameter specifies the viewport.
type	The type of a component to retrieve: GLG_WIDGET_QUERY returns an ID of the native component used to render the viewport: a window handle on Windows when using the GTK version of the GLG library on Linux, returns a GTK container widget that holds the content of the viewport a Motif widget ID when using the legacy X11 version of the GLG library on Linux/Unix an X11 window ID when using the libglg_x11.a library for the Qt integration on Linux/Unix. This window ID will be NULL if a viewport uses a native Qt widget, such as a text box or a list GLG_SHELL_QUERY returns an ID of the viewport's top-level parent: a window handle of the top-level window on Windows a top level GTK window when using the GTK version of the GLG library on Linux a top level Motif shell ID the viewport belongs to when using the legacy X11 version of the GLG library on Linux/Unix in the Qt integration that uses the libglg_x11.a library on Linux/Unix, it returns an X11 window ID of the top parent's Qt 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 In the GTK version of the GLG library on Linux, returns the widget ID of a native input widget, such as a text or combo box, or NULL if the viewport doesn't use native widgets. In the legacy X11 version of the GLG library on Linux/Unix, returns a widget ID of a child Motif 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 and GLG_H_SCROLLBAR_QUERY In the legacy X11 version of the GLG library on Linux/Unix, returns a Motif widget ID of a requested scrollbar widget for native widgets that use a scroll pane. GLG_DISPLAY_QUERY In the X11 versions of the GLG library, returns the X11 display pointer for the viewport's window. GLG_WINDOW_QUERY In the X11 versions of the GLG library, returns an X11 window ID of the viewport's window. In Qt integration that uses the libglg_x11.a library on Linux/Unix, 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 the Qt integration that uses the libglg_x11.a library on Linux/Unix, 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 the Qt integration that uses the libglg_x11.a on Linux/Unix, returns the Qt parent widget of the top viewport, such as QGlgWidget.

Returns

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

GlgGetObjectName()

char* GlgGetObjectName

(

GlgObject

object

)

Returns an object's name.

Parameters

object

A object to query.

Returns

An object's name or NULL if an object is unnamed.

GlgGetObjectType()

GlgObjectType GlgGetObjectType

(

GlgObject

object

)

Returns an object's type.

Parameters

object

A object to query.

Returns

An object's type.

GlgGetRefCount()

GlgLong GlgGetRefCount

(

GlgObject

object

)

Returns an object's reference count.

Parameters

object

An object to query.

Returns

The object's reference count.

GlgGetRelativePath()

char* GlgGetRelativePath	(	char *	base_path,
		char *	filename
	)

Creates a filepath relative to the specified base path.

Parameters

base_path	Specifies a base path. NULL can be used on Windows to use the location of the program's executable.
filename	A filename or a relative filepath. If an absolute path is specified, it will be returned as is.

Returns

An allocated file path string that has to be freed with GlgFree.

If filename specifies an absolute path, it will be returned as is. Otherwise, GlgGetRelativePath extracts the directory portion of base_path using GlgGetDir, appends filename and returns the resulting string. If base_path is a directory path that does not point to an existing directory, it must end with '/', or either '/' or '\' on Windows.

To use this function for determining location of a drawing file relative to the program's executable, an executable path can be passed as the base_path parameter. On Linux/Unix, or if the GlgMain cross-platform entry point is used, the location of the executable is provided by the argv[0] parameter. On Windows, GlgGetExePath may be used to get the path of the executable, or NULL may be used to automatically determine the path.

GlgGetSelectedPlot()

GlgObject GlgGetSelectedPlot

(

void

)

Returns the plot object corresponding to the last legend item selected with the mouse, if any.

Returns

Selected plot object ID or NULL if no plots were selected.

The setting of the chart's viewport ProcessMouse attribute controls when legend selection happens:

• GLG_NO_MOUSE_EVENTS disables legend selection.
• for GLG_MOUSE_CLICK, a plot is selected when a legend items is clicked on, and the selected plot is stored until it is replaced by a new selection.
• for GLG_MOUSE_OVER_SELECTION, a plot is selected when a mouse moves over a legend item, and the selected plot is reset when the mouse moves away from the item.
• for GLG_MOUSE_OVER_TOOLTIP, a plot is selected when a mouse is hovering over a legend item, and the selected plot is stored until it is replaced by a new selection.
• for a combination of GLG_MOUSE_CLICK and GLG_MOUSE_OVER_SELECTION, the selection will happen on both mouse click and mouse over events, but the selected plot will be reset when the mouse moves away from the item.
• for a combination of GLG_MOUSE_CLICK and GLG_MOUSE_OVER_TOOLTIP, the selection will happen on both the mouse click and mouse hover events, and the selected plot will be stored until it is replaced by a new selection.

This function can be used in conjunction with a mouse click Action attached to the Legend object. The DEMOS/RealTime_StripChart/stripchart.c file in the GLG installation directory provides an example of using this technique to highlight a plot when its legend icon is clicked on.

See also GlgGetLegendSelection.

GlgGetSelectionButton()

GlgLong GlgGetSelectionButton

(

void

)

Queries the mouse button that initiated the callback.

Returns

1, 2, or 3 to indicate which button caused the callback to be invoked.

The function may be used only inside callback functions that are activated on a mouse click, otherwise the return value is undefined.

GlgGetSResource()

GlgBoolean GlgGetSResource	(	GlgObject	object,
		char *	resource_name,
		char **	value
	)

Returns the current value of a S (string) resource.

Parameters

object	Specifies a GLG object.
resource_name	Specifies the resource path of the string resource to query.
value	Specifies a pointer used to return the resource value.

Returns

Success or failure status.

If a string resource with the given resource path exists, this function copies the string pointer into the address specified by value pointer and returns True, otherwise it generates an error message and returns False.

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 GlgGetSResource. To store the returned string, create a copy of it using GlgStrClone.

GlgGetSTag()

GlgBoolean GlgGetSTag	(	GlgObject	object,
		char *	tag_source,
		char **	value
	)

Returns the current value of a S (string) tag.

Parameters

object	Specifies a GLG object.
tag_source	Specifies the TagSource of the string tag to query.
value	Specifies a pointer used to return the tag value.

Returns

Success or failure status.

If a string tag with the given TagSource exists, this function copies the string pointer into the address specified by value pointer and returns True, otherwise it generates an error message and returns False.

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 GlgGetSTag. To store the returned string, create a copy of it using GlgStrClone.

GlgGetTime()

GlgBoolean GlgGetTime	(	GlgULong *	sec,
		GlgULong *	microsec
	)

Returns number of seconds and microseconds since the Epoch.

Parameters

sec	A pointer used to return the number of seconds.
microsec	A pointer used to return the number of microseconds.

Returns

Success or failure status.

GlgGetURLCB()

char* GlgGetURLCB	(	char *	request,
		void *	reserved
	)

Fetches data from a URL and saves it in a temporary file.

By default, this function is used for fetching URLs for the GLG editors on all platforms, as well as for the GLG C API runtime on Windows. GlgSetGetURLCallback may be used to activate the default callback for the GLG C API runtime on Linux:

GlgSetGetURLCallback( GlgGetURLCB );

To use it on Linux, the GLG_WGET_PATH environment variable should be set and contain the path to the wget command that will used for fetching URLs.

Parameters

request	The URL string to fetch the data from, or NULL to delete the previously fetched temporary file.
reserved	This parameter is reserved for future implementations and must be null.

Returns

Temporary file name containing the fetched data or NULL if fetching failed. It is also NULL if the callback is invoked to delete the previously fetched temporary file.

When GlgGetURLCB is invoked to fetch the next URL, it deletes a temporary file containing the previously fetched URL.

GlgGISConvert()

GlgBoolean GlgGISConvert	(	GlgObject	object,
		char *	resource_name,
		GlgCoordType	coord_type,
		GlgBoolean	coord_to_lat_lon,
		GlgPoint *	in_point,
		GlgPoint *	out_point
	)

Performs coordinate conversion from the GIS coordinates of the GIS Object to the GLG coordinates of the drawing and visa versa.

Parameters

object	If resource_name is NULL, specifies the GIS Object whose coordinate system to use for conversion. If resource_name is not NULL, specifies a parent of the GIS Object.
resource_name	If not NULL, specifies the resource path of the GIS Object inside the parent object specified by the object parameter.
coord_type	The type of the GLG coordinate system to convert to or from: GLG_SCREEN_COORD for screen coordinates GLG_OBJECT_COORD for world coordinates.
coord_to_lat_lon	True to convert from GLG coordinates to GIS longitude and latitude False to convert the GIS longitude and latitude to GLG coordinates.
in_point	A pointer to the GlgPoint structure containing coordinate values to be converted.
out_point	A pointer to the GlgPoint structure that will receive converted coordinate values (x/y in the selected coordinate system or lon/lat)

Returns

Success or failure status.

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. Coordinates of the returned point may be outside of the visible portion of the map for all projections.

This function performs coordinate conversion using the current settings of the GIS object, which must be setup and rendered.

The GlmConvert function may be used to perform coordinate conversion between GIS and GLG coordinates without the use of the GIS object, which could be done before the drawing is rendered, without a drawing at all, or without a GIS object being present.

GlgGISCreateSelection()

GlgObject GlgGISCreateSelection	(	GlgObject	object,
		char *	resource_name,
		char *	layers,
		GlgLong	x,
		GlgLong	y,
		GlgLong	select_labels
	)

Returns a message object containing information about GIS features located at a specified position on the map.

This function provides a high-level interface to the map server's GlmGetSelection function and may be used to query GIS selection at the point selected by the mouse click.

Parameters

object	If resource_name is NULL, specifies the GIS Object whose coordinate system to use for conversion. If resource_name is not NULL, specifies a parent of the GIS Object.
resource_name	If not NULL, specifies the resource path of the GIS Object inside the parent object specified by the object parameter.
layers	A list of layers to query.
x,y	Coordinates of a point in the screen coordinates of a viewport that contains the GIS object.
select_labels	Specifies the label selection mode, can have the following values (defined in the GlmLabelSelectionMode enum in the GlmApi.h file): GLM_LBL_SEL_NONE - GIS features' labels are not considered for the GIS selection. GLM_LBL_SEL_IN_TILE_PRECISION - enables labels to be considered for the GIS selection. For a faster selection, this option does not check labels that belong to GIS features in a different tile but extend to the current tile. GLM_LBL_SEL_MAX_PRECISION - enables labels to be considered for the GIS selection and performs selection with the maximum label precision. The layer's settings have precedence over the select_labels parameter. The labels will be considered for selection only for the layers that do not override it by setting their LABEL SELECTION MODE=NONE in the layer's LIF file. If LABEL SELECTION MODE=INTILE, the labels will always be considered using the IN_TILE precision.

Returns

A message object containing information about the selected GIS features. The message object has to be dereferenced using GlgDropObject when finished.

If the GIS verbosity level is set to 2000 or 2001, extended information is also written to the error log file and printed to the terminal on Linux/Unix for debugging purposes.

Refer to the GlmGetSelection section of the GLG Map Server Reference Manual for information on the structure of the returned message object as well as a programming example that demonstrates how to handle it.

GlgGISGetDataset()

GlgObject GlgGISGetDataset	(	GlgObject	object,
		char *	resource_name
	)

Returns a dataset object associated with the GIS Object.

The function may be invoked after the GIS Object has been set up to retrieve its dataset. The dataset may be used to dynamically change attributes of individual layers displayed in the GIS Object. The program can use SetResourcefunctions for changing layer attributes. Refer to the GLG Map Server Reference Manual for information on layer attributes. The GLG GIS Demo provides an example of changing layer attributes programmatically.

Parameters

object	If resource_name is NULL, specifies the GIS Object whose coordinate system to use for conversion. If resource_name is not NULL, specifies a parent of the GIS Object.
resource_name	If not NULL, specifies the resource path of the GIS Object inside the parent object specified by the object parameter.

Returns

A dataset object.

GlgGISGetElevation()

GlgBoolean GlgGISGetElevation	(	GlgObject	object,
		char *	resource_name,
		char *	layer_name,
		double	lon,
		double	lat,
		double *	elevation
	)

Returns an elevation of a lat/lon point on a map.

Parameters

object	If resource_name is NULL, specifies the GIS Object whose coordinate system to use for conversion. If resource_name is not NULL, specifies a parent of the GIS Object.
resource_name	If not NULL, specifies the resource path of the GIS Object inside the parent object specified by the object parameter.
layer_name	The name of the layer with elevation data to query.
lon,lat	The lon/lat coordinates of a point on the map.
elevation	A pointer to the variable of a double type that will receive the returned elevation data.

Returns

• False if the point is outside of the map in the ORTHOGRAPHIC projection, or if there is no elevation data for the specified location.
• True, if the elevation value is returned.

This function may be used to query elevation at the point selected by the mouse click.

The returned value is in the units (such as meters or feet) defined by the elevation data file.

GlgHasResourceObject()

GlgBoolean GlgHasResourceObject	(	GlgObject	object,
		char *	resource_name
	)

Checks if a named resource exists.

Parameters

object	Specifies a GLG object whose resource to query.
resource_name	Specifies the resource path of the resource object to query.

Returns

True if a resource object with the given resource path exists, otherwise returns False without generating an error message.

GlgHasTagName()

GlgBoolean GlgHasTagName	(	GlgObject	object,
		char *	tag_source
	)

Checks if a data tag with a specified tag name exists.

Parameters

object	Specifies a GLG object whose tag to query.
tag_source	Specifies the TagName to query.

Returns

True if a tag with the given TagName exists, otherwise returns False without generating an error message.

GlgHasTagSource()

GlgBoolean GlgHasTagSource	(	GlgObject	object,
		char *	tag_source
	)

Checks if a data tag with a specified tag source exists.

Parameters

object	Specifies a GLG object whose tag to query.
tag_source	Specifies the tag source to query.

Returns

True if a tag with the given tag source exists, otherwise returns False without generating an error message.

GlgImportStrings()

GlgLong GlgImportStrings	(	GlgObject	object,
		char *	filename,
		GlgBoolean	verbose
	)

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

Parameters

object	Specifies a viewport or an object whose text strings to replace.
filename	Specifies the string translation file to load.
verbose	If True, generates an error for each string that was not changed to a new value because it was missing a matching entry in the string translation file.

Returns

The number of imported strings or -1 in case of an error.

This function can be used at run time to display a localized drawing. An application can load different versions of the translated file to display localized drawings for different language environments. See GlgExportStrings for more information.

This function provides a run time interface for importing translated strings into a drawing to display it in a different language environment. The File, Import Strings option of the GLG editors can be used to import strings into the currently loaded drawing for testing.

GlgImportTags()

GlgLong GlgImportTags	(	GlgObject	object,
		char *	filename,
		GlgBoolean	verbose
	)

Replaces the TagName and TagSource attributes of the data tags in a drawing with information loaded from a tag translation file.

Parameters

object	Specifies a viewport or an object whose tags to change.
filename	Specifies the tags translation file to load.
verbose	If True, generates an error for each tag that was not modified because it was missing a matching entry in the tag translation file.

Returns

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

This function can be used at run time to modify the data tags used by the drawing. It load the specified tag translation file and uses it to modify the drawing's data tags. See GlgExportStrings for more information.

This function provides a run time interface for importing modified tags into a drawing. The File, Import Tags option of the GLG editors can be used to import tags into the currently loaded drawing for testing.

GlgInit()

GlgAppContext GlgInit	(	GlgBoolean	tk_initialized,
		GlgAppContext	app_context,
		int	argc,
		char **	argv
	)

Initializes GLG Toolkit API.

On Linux/Unix, this function is automatically invoked if the GLG library is deployed using one of the native GLG widget wrappers.

On Windows, the dynamically linked library (DLL) version of the GLG library automatically calls this function as well. If the static version of the GLG library is used, the function has to be explicitly called by the application.

In either case, it's always a good idea to explicitly call this function at the beginning of the application code, in which case it will also process command-line options recognized by the Toolkit and passed via the argc and argv parameters.

Parameters

tk_initialized	Toolkit initialization parameter. Use False for GTK and Windows. With the legacy X11 version of the GLG library, this parameter specifies whether or not X Toolkit was already initialized by the program. It allows using the GLG Toolkit in an application that creates its own application context. If this parameter is False, the X Toolkit will be initialized by the function. Otherwise, it is assumed that the program has already initialized it.
app_context	Application context initialization parameter. With the legacy X11 version of the GLG library, this argument specifies the Xt application context if it has already been created by the program. If NULL is passed, an application context will be created by this function. Otherwise, the provided application context will be used. With the GTK version of the GLG library, the argument is not used and must be NULL. On Windows, the argument specifies an application instance handle. If the GLG library is used in the form of a DLL, the application instance handle is obtained automatically and the value of NULL may be used for the argument. If a static GLG library is used, an application instance handle must be supplied explicitly. Application instance handle is supplied by a parameter of the GlgMain or WinMain program entry points. In an MFC application, a call to AfxGetInstanceHandle function may be used to obtain application instance handle.
argc	Specifies the number of command line parameters. On Windows, it will be provided by the GlgMain cross-platform entry point, otherwise zero may be used.
argv	Specifies the command line parameter list. On Windows, it will be provided by the GlgMain cross-platform entry point, otherwise zero may be used.

Returns

If the function creates an application context, it returns the created context, otherwise it returns the application context that was passed to it. The return value is later used with some other functions of the GLG Generic API.

See Generic API Application Example for a cross-platform example of using this function.

GlgInitialDraw()

void GlgInitialDraw

(

GlgObject

object

)

Draws a GLG viewport object for the first time after it has been created or loaded.

Parameters

object

Specifies a viewport containing a GLG drawing.

The function displays a viewport's drawing in a platform-independent way on both Windows and Linux/Unix, and is part of the GLG Generic API.

The function creates a top level window and renders the viewport's drawing in it. Depending on the used version of the GLG library and the configuration settings, different rendering engines may be used for rendering graphics:

• GDI or OpenGL on Windows
• GTK, X11 or OpenGL on Linux/Unix.

If the GlgWrapper Widget is used on Linux/Unix, or the GLG Custom Control is used on Windows, this function is called automatically, and need not be explicitly called.

GlgInitialDraw is equivalent to the following sequence:

GlgSetupHierarchy( viewport );
GlgUpdate( viewport );

See Generic API Application Example for a cross-platform example of using this function.

GlgInitLocale()

GlgBoolean GlgInitLocale

(

char *

locale

)

Sets the program locale.

The function invokes setlocale( LC_ALL, locale ). In the X11 environment, it also performs X11 locale initialization.

If it is used, the function must be invoked before the GlgInit function.

Refer to the Internationalization and Localization Support chapter of the GLG User's Guide and Builder Reference Manual for information on string encoding, as well as using the UTF8 locale.

Parameters

locale

Specifies a program locale, or NULL to use the current system locale.

Returns

Success or failure status.

GlgLoadExeIcon()

void GlgLoadExeIcon	(	GlgObject	viewport,
		GlgLong	icon_id
	)

Windows only: Loads small and big icons from the executable and associates them with the top level window of a viewport.

The function should be invoked after the drawing hierarchy has been set up.

Parameters

viewport	The drawing viewport.
icon_id	An icon ID in the resource file.

GlgLoadObject()

GlgObject GlgLoadObject

(

char *

filename

)

Loads an object from a GLG drawing file or a URL.

Parameters

filename

Specifies the file or the URL to load the object from. For details of using URLs on Linux, see GlgGetURLCB.

Returns

The loaded object or NULL if loading failed.

This function loads an object from the specified file or URL and returns the object ID. If the file or the URL is not accessible or is not in the GLG save format, an error message is generated and NULL is returned.

If the object is loaded successfully, the reference count of the returned object is set to 1. The loaded object has to be explicitly dereferenced with GlgDropObject after it has been used to avoid memory leaks. See GlgReferenceObject for details on the reference counting.

GlgLoadObjectFromImage()

GlgObject GlgLoadObjectFromImage	(	void *	image,
		GlgLong	size
	)

Loads an object from a memory image.

Parameters

image	Specifies the address of the drawing image generated by the GLG Code Generation Utility gcodegen.
size	Specifies the image size. This is also generated by gcodegen.

Returns

The loaded object or NULL if loading failed.

This function loads an object from the specified drawing's memory image and returns the object ID. If the memory is corrupted, an error message is generated and NULL is returned.

If the object is loaded successfully, the reference count of the returned object is set to 1. The loaded object must be explicitly dereferenced with GlgDropObject after it has been used to avoid memory leaks.

See GlgReferenceObject function for details on the reference counting.

For information about the Code Generation Utility, see the GLG Programming Tools and Utilities chapter of the GLG Programming Reference Manual.

GlgLoadWidgetFromFile()

GlgObject GlgLoadWidgetFromFile

(

char *

filename

)

Loads a GLG widget from a GLG drawing file or a URL.

Parameters

filename

Specifies the name of the widget's drawing file or a URL. For details of using URLs on Linux, see GlgGetURLCB.

Returns

The loaded widget drawing or NULL if loading failed.

This function loads a drawing from a file or a URL and searches the drawing for a viewport object named $Widget. If the viewport is found, it references and returns a handle to it, otherwise it produces an error message and returns NULL.

After the viewport has been used, it may be dereferenced using GlgDropObject to avoid memory leaks. See GlgReferenceObject for details on the reference counting.

See Generic API Application Example for a cross-platform example of using this function.

GlgLoadWidgetFromImage()

GlgObject GlgLoadWidgetFromImage	(	void *	image,
		GlgLong	size
	)

Loads a GLG widget from a memory image.

Parameters

image	Specifies the address of the widget's drawing image generated by the GLG Code Generation Utility gcodegen.
size	Specifies the image size. This is also generated by gcodegen.

Returns

The loaded widget drawing or NULL if loading failed.

This function loads a drawing from the drawing image and searches the drawing for a viewport named $Widget. If the viewport is found, it references and returns it, otherwise it produces an error message and returns NULL. After the viewport has been used, it may be dereferenced using GlgDropObject to avoid memory leaks. See GlgReferenceObject for details on the reference counting.

GlgLoadWidgetFromObject()

GlgObject GlgLoadWidgetFromObject

(

GlgObject

object

)

Loads a widget from a GLG object.

Parameters

object

Specifies a GLG object to be used as a widget's drawing.

Returns

The loaded widget drawing or NULL if loading failed.

This function searches the object to be used as a drawing for a viewport named $Widget. If the viewport is found, it references and returns it, otherwise it produces an error message and returns NULL.

After the viewport has been used, it may be dereferenced using GlgDropObject. See GlgReferenceObject for details on the reference counting.

For information about the Code Generation Utility, see the GLG Programming Tools and Utilities chapter of the GLG Programming Reference Manual.

GlgMainLoop()

GlgLong GlgMainLoop

(

GlgAppContext

context

)

Implements an event polling loop in a platform independent way.

Parameters

context

Specifies the application context returned by GlgInit.

Returns

Exit code on Windows, GLG_EXIT_OK on X11 and in GTK.

On Windows, the return value of this function may be used as the return value of GlgMain.

See Generic API Application Example for a cross-platform example of using this function.

GlgNativePrint()

GlgBoolean GlgNativePrint	(	GlgObject	object,
		PlatformDependent	print_context,
		double	x,
		double	y,
		double	width,
		double	height,
		GlgBoolean	stretch,
		GlgBoolean	center
	)

GTK and Windows only: Generates printing output of the current state of the viewport's graphics.

Parameters

object	Specifies a viewport. If object is a light viewport, the output will be generated for its parent viewport.
print_context	A platform-depended print context: GtkPrintContext* in GTK HDC on Windows
x	Defines the X coordinate of the upper left corner of the rectangle on the page containing the output. All coordinates are specified in the world coordinate system, which maps a rectangle defined by the points (0;0) and (2000;2000) to a page.
y	Defines the Y coordinate of the upper left corner of the rectangle.
width	Defines the width of the rectangle.
height	Defines the height of the rectangle.
stretch	Specifies whether or not printed output should be stretched when mapping it to the specified rectangle: If True, the printed output will be stretched to fit the rectangle exactly. This may distort printed objects. If False, the ratio of height to width of the widget will be preserved in the printed output. This may leave some parts of the specified rectangle blank.
center	Specifies whether or not printed output should be centered inside the specified output rectangle when stretch=False results in unused space on the sides of the rectangle. If True, the output will be centered inside the output area, otherwise it will be anchored in the upper left corner of the rectangle.

Returns

True if printing output was successfully generated, otherwise False.

The drawing's hierarchy must be set up in order to print the drawing. Use GlgUpdate before printing to make sure the drawing is up to date.

In the MFC environment on Windows, GlgOnPrint may be used to support printing of the GlgControlC MFC wrapper.

GlgOnDrawMetafile()

GlgBoolean GlgOnDrawMetafile	(	GlgObject	viewport,
		HDC	print_dc
	)

Windows only: Provides MFC metafile output support.

Is used by the MFC container's OnDrawMetafile method to produce metafile for the GLG child window.

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 for metafile output.

Returns

True if printing succeeds, otherwise returns False.

GlgOnPrint()

GlgBoolean GlgOnPrint	(	GlgObject	viewport,
		HDC	print_dc
	)

Windows only: Provides MFC printing support.

Is used by the MFC container's OnPrint method to print GLG child window.

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

True if printing succeeds, otherwise returns False.

GlgParseArgs()

GlgObject GlgParseArgs	(	char *	program_name,
		char *	args_string,
		GlgLong *	argc,
		char ***	argv
	)

This function is used by the GlgMain generic program entry point on Windows to parse command-line arguments.

Parameters

program_name	The path to the program executable. If NULL, GlgGetExePath will be used to obtain the path.
args_string	A command line string containing all command-line parameters (the lpCmdLine parameter of WinMain).
argc	A pointer to the returned number of parsed command-line arguments.
argv	A pointer to the returned argv list of parsed command-line arguments.

Returns

An array of strings representing parsed command line parameters. The array holds parameter's strings while they are processed and should be deleted using GlgDropObject when done.

GlgPreAlloc()

GlgBoolean GlgPreAlloc	(	GlgLong	size,
		GlgPreAllocType	type
	)

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

Parameters

size

The size of the memory to allocate.

type

The allocation type that controls the meaning of the size parameter: GLG_PREALLOC_MEMORY - allocates a specified number of spare memory blocks. GLG_PREALLOC_POLYGON_POINT_BUFFERS - allocates a buffer of the requested size to be used for rendering large polygons. It can be set to the maximum expected number of points in one polygon. GLG_PREALLOC_GRAPH_POINT_BUFFERS - allocates a buffer of the requested size used for rendering plots of real-time charts. It can be set to the maximum expected number of points in one plot. GLG_PREALLOC_TESS_BUFFERS - allocates a buffer of the requested size for tessellation vertices. The buffer is used by the OpenGL driver for tessellating filled polygons; it is not used by the GDI driver or in GTK.

Returns

Success or failure status.

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.

GlgPrintObjectCountChanges()

void GlgPrintObjectCountChanges

(

void

)

Prints object count changes since the last call to this function.

This function may be used to diagnose memory and object leaks.

On Windows, object counts output is stored in the glg_error.log file. On Linux/Unix, the output is also printed to stdout.

GlgPrintObjectCounts()

void GlgPrintObjectCounts

(

void

)

Prints total object count for each of the GLG object types.

This function may be used to diagnose memory and object leaks.

On Windows, object counts output is stored in the glg_error.log file. On Linux/Unix, the output is also printed to stdout.

GlgRand()

double GlgRand	(	double	low,
		double	high
	)

Generates a random number in a platform-independent way.

Parameters

low	The low range of the generated random number.
high	The high range of the generated random number.

Returns

The random number in the specified range.

This function produces a random number in the specified range by using the platform's rand function.

GlgReferenceObject()

GlgObject GlgReferenceObject

(

GlgObject

object

)

Increments an object's reference count.

Parameters

object

The object to be referenced.

Returns

The object.

This function increases the reference count of an object by 1 and returns the object's ID. The GlgDropObject function may be used to dereference the object when it is not needed any more.

When an object is created, its reference count is set to 1. Any object you create programmatically has to be explicitly dereferenced using the GlgDropObject function after the object has been used, otherwise memory leaks will occur. It is a good practice to dereference objects immediately after they have been added to a group or used as a part of other objects; this guarantees that you will not forget to dereference the object later. The following example illustrates this:

{
   // Create a polygon object with default values of the attributes.
   GlgObject polygon = GlgCreateObject( GLG_POLYGON, NULL, NULL, NULL, NULL,NULL );
 
   // Add the polygon to a group.
   GlgAddObjectToBottom( group, polygon );
 
   // Adding polygon to a group references it; we may dereference it now to let the group manage it.
   GlgDropObject( polygon );
}

Dereferencing an object does not necessarily destroy the object. The object may still be referenced by groups it was added to or by other objects that use it. An object may also be referenced programmatically to make sure it is kept around and is not destroyed automatically by the Toolkit.

The object is actually destroyed only when the last reference to it is dropped. The GlgReferenceObject function may be used to keep objects around, and to make sure that an object ID is still valid. Simply use the function to increment the reference count of the object, and then decrement the count with GlgDropObject when the object is no longer needed.

GlgReferenceObject may also be used to keep an object while it is being deleted from one group and added to another group. Deleting the object from a group decrements its reference count and may destroy the object if it is not referenced by anything else. Referencing the object using GlgReferenceObject prevents the object from being destroyed. GlgDropObject is used after the operation is completed to return the object's reference count to its initial state, as shown in the following code:

GlgReferenceObject( object ); // Keeping the object around.
 
// Deleting the object from group1 automatically dereferences the object and may destroy it if it's not referenced.
if( GlgContainsObject( group1, object ) )
  GlgDeleteThisObject( group1, object );
 
// Adding the object to the group2 automatically references it, so that it is safe to dereference it now.
GlgAddObjectToBottom( group2, object );
 
GlgDropObject( object ); // We may drop it now.

In general, it is good practice to increment the reference count of an object before performing any operation on it and then dereference the object when the operation is complete. This provides a guarantee that the object will not be inadvertently destroyed during the operation.

GlgRemoveTimeOut()

void GlgRemoveTimeOut

(

GlgLong

id

)

Removes a timer procedure.

Parameters

id	The ID of a timer procedure to be removed. The ID was returned by GlgAddTimeOut.

This function removes an active timer. If the timer has already been removed and is not active, the results are undefined.

GlgRemoveWorkProc()

void GlgRemoveWorkProc

(

GlgLong

id

)

Removes a work procedure.

Parameters

id	The ID of a work procedure to be removed. The ID was returned by GlgAddWorkProc.

This function removes an active work procedure. If the work procedure has already been removed and is not active, the results are undefined.

GlgReset()

GlgBoolean GlgReset

(

GlgObject

object

)

Reinitializes the drawing by resetting the drawing hierarchy, then setting it up again and rendering the drawing.

Parameters

object

Specifies a viewport to reset.

Returns

True if the drawing has been successfully reinitialized, otherwise False.

Calling GlgReset restores all volatile resource changes to the values the resources had when the widget was first drawn. It also discards currently displayed chart data, unless the chart Persistent attribute is set to True.

The function should be invoked only for the top-level viewports, not the child viewports or the light viewports.

GlgResetHierarchy()

void GlgResetHierarchy

(

GlgObject

object

)

Resets the object hierarchy.

Parameters

object

Specifies the object to be reset.

Resets the object hierarchy of a top-level viewport or drawing. If the object was displayed using the Generic API, this function must be called before destroying a top-level object with GlgDropObject.

This function should not be called for the top-level viewports used in the integrated GLG widgets, such as the GlgWrapper Widget or GLG Custom Control.

Warning: Do not confuse this function with the GlgReset function, which is used to redraw a displayed drawing and to regenerate the object hierarchy.

GlgResetSizeConstraint()

GlgBoolean GlgResetSizeConstraint

(

GlgObject

text_obj

)

Forces GLG_FIT_TO_BOX_TEXT Text objects with a constrained SizeConstraint attribute to renegotiate their font size.

Parameters

text_obj

A Text object of the GLG_FIT_TO_BOX_TEXT subtype that has a constrained SizeConstraint attribute.

Returns

Success or failure status.

GlgSaveImage()

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

Generates a JPEG or PNG image of the current state of the viewport's graphics and saves it to a file.

Parameters

object	Specifies a viewport object or a viewport's parent.
resource_name	Specifies the resource path of a child viewport whose image to save, or NULL to save the image of the viewport specified by the object parameter. The resource path is relative to the object 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.

Returns

True if the image was successfully saved, otherwise False.

GlgSaveImage saves an image of the visible part of the viewport, clipping out the parts of the drawing that extends outside of it.

For a light viewport, the output will be generated for its parent viewport. The drawing's hierarchy must be set up in order to generate an image.

GlgSaveImageCustom()

GlgBoolean GlgSaveImageCustom	(	GlgObject	object,
		char *	resource_name,
		char *	filename,
		GlgImageFormat	format,
		GlgLong	x,
		GlgLong	y,
		GlgLong	width,
		GlgLong	height,
		GlgLong	gap
	)

Generates a JPEG or PNG image of the specified rectangular region of the viewport's graphics and saves it to a file.

Parameters

object	Specifies a viewport object or a viewport's parent.
resource_name	Specifies the resource path of a child viewport whose image to save, or NULL to save the image of the viewport specified by the object parameter. The resource path is relative to the object 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	Specifies the X coordinate of the area used for generating an image. It defines an offset in screen pixels relative to the origin of the viewport's window, which has screen coordinates of (0,0).
y	Specifies the Y coordinate of the area used for generating an image. It defines an offset in screen pixels relative to the origin of the viewport's window, which has screen coordinates of (0,0).
width	Specifies the width in screen pixels of the area used for generating an image.
height	Specifies the height in screen pixels of the area used for generating an image.
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.

Returns

True if the image was successfully saved, otherwise False.

The x, y, width and height 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 using GlgGetBoxPtr.

If width and height parameters are 0, the image of the whole drawing is generated using the drawing's bounding rectangle as the image generation area, without clipping to just the visible area. 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.

For a light viewport, the output will be generated for its parent viewport. The drawing's hierarchy must be set up in order to generate an image.

GlgSetAlarmHandler()

GlgAlarmHandler GlgSetAlarmHandler

(

GlgAlarmHandler

handler

)

Installs a global alarm handler function that will be invoked to process alarms.

Alarms are generated by the Alarm objects attached to objects in the drawing and activated when their controlled values go outside the ranges specified in the Alarm objects.

Parameters

handler

Specifies a function that will be invoked to process alarm messages generated by the application's drawings.

Returns

The previously installed alarm handler function, or NULL.

See GlgAlarmHandler for more information.

GlgSetBrowserObject()

void GlgSetBrowserObject	(	GlgObject	browser,
		GlgObject	object
	)

Sets the object for browsing with the GLG Resource, Tag and Alarm browser widgets.

Parameters

browser	A viewport of the Resource, Tag or Alarm browser widget.
object	An object to browse.

The browser widget will display the object's resources, tags or alarms depending on the type of the browser widget.

GlgSetBrowserSelection()

GlgBoolean GlgSetBrowserSelection	(	GlgObject	object,
		char *	resource_name,
		char *	selection,
		char *	filter
	)

Sets a new value of a browser's Selection and Filter text boxes of the Resource, Tag, Alarm and Data browser widgets after the browser object has already been set up.

Parameters

object	A viewport of the browser widget or its parent.
resource_name	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	A new selection string.
filter	A new filter string.

Returns

Success or failure status.

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

GlgSetChartFilter()

GlgBoolean GlgSetChartFilter	(	GlgObject	object,
		char *	resource_name,
		GlgChartFilter	chart_filter,
		void *	client_data
	)

Attaches a custom data filter to a chart's plot.

A data filter is a function which is invoked by a chart to aggregate the plot's data. See GlgChartFilter for more information.

Parameters

object	A chart's plot, a chart or a parent object containing the chart.
resource_name	A resource path for accessing the plot inside the parent. Use NULL when the object parameter specifies the plot.
chart_filter	A custom data filter.
client_data	Data to be passed to the custom filter when it is invoked.

Returns

True if a custom filter was successfully attached.

GlgSetCursor()

GlgBoolean GlgSetCursor	(	GlgObject	viewport,
		char *	resource_name,
		GlgLong	cursor
	)

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

Parameters

viewport	A viewport object or a viewport's parent.
resource_name	The resource path 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 path is relative to the object specified by the viewport parameter.
cursor	One of the predefined Windows cursor types.

Returns

Success or failure status.

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

While GlgSetCursorType uses only predefined cross-platform subset of cursor types, GlgSetCursor can use all cursor types defined on Windows.

GlgSetCursorType()

GlgBoolean GlgSetCursorType	(	GlgObject	viewport,
		char *	resource_name,
		GlgCursorType	cursor_type
	)

Sets cursor for a drawing or one of its child viewports.

Parameters

viewport	A viewport object or a viewport's parent.
resource_name	The resource path 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 path is relative to the object specified by the viewport parameter.
cursor_type	One of the system cursor types to be used: GLG_DEFAULT_CURSOR GLG_CROSSHAIR_CURSOR GLG_WAIT_CURSOR GLG_HAND_CURSOR GLG_MOVE_CURSOR.

Returns

Success or failure status.

This function uses a subset of cursor types that can be used in a cross-platform way. On Windows, GlgSetCursor can be used to use all available Windows cursor types.

The specified cursor will be used when the mouse moves inside the viewport the cursor is assigned to. In the GTK version of the GLG library on Linux, the cursor will be changed for the top window that contains the viewport.

The drawing's hierarchy must be set up in order to set cursor type.

GlgSetDResource()

GlgBoolean GlgSetDResource	(	GlgObject	object,
		char *	resource_name,
		double	value
	)

Sets a new value of a D (double) resource.

Parameters

object	Specifies a GLG object.
resource_name	Specifies the name of the scalar resource to be set.
value	Specifies a new value.

Returns

Success or failure status.

If a scalar resource with the given resource path exists, this function sets it to a new value and returns True, otherwise it generates an error message and returns False.

See Resource Access Performance Optimization for more.

GlgSetDResourceIf()

GlgBoolean GlgSetDResourceIf	(	GlgObject	object,
		char *	resource_name,
		double	value,
		GlgBoolean	if_changed
	)

Sets a new value of a D (double) resource.

Parameters

object	Specifies a GLG object.
resource_name	Specifies the resource path of the scalar resource to be set.
value	Specifies a new value.
if_changed	If set to False, the graphical updates will be performed even if the new value is the same as the old one (equivalent to GlgSetDResource). Setting if_changed=True optimizes performance of applications that set resource 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.

Returns

Success or failure status.

If a scalar resource with the given resource path exists, this function sets it to a new value and returns True, otherwise it generates an error message and returns False.

See Resource Access Performance Optimization for more.

GlgSetDTag()

GlgBoolean GlgSetDTag	(	GlgObject	object,
		char *	tag_source,
		double	value,
		GlgBoolean	if_changed
	)

Sets a new value of a D (double) tag.

Parameters

object	Specifies a GLG object.
tag_source	Specifies TagSource of the scalar tag to be set. All object's tags with the specified TagSource will be set to the supplied value.
value	Specifies a new value.
if_changed	If set to False, the graphical updates will be performed even if the new value is the same as the old one. Setting if_changed=True optimizes performance of applications that set 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.

Returns

Success or failure status.

If scalar tags with the given TagSource exist, this function sets their new values and returns True, otherwise it generates an error message and returns False.

See Tag Access Performance Optimization for more.

GlgSetEditMode()

GlgBoolean GlgSetEditMode	(	GlgObject	viewport,
		char *	resource_name,
		GlgBoolean	edit_mode
	)

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

Parameters

viewport	A viewport object (either a Viewport or a Light Viewport) to set the editing mode of, or its parent.
resource_name	A resource path to access the viewport from the parent supplied by the viewport parameter, or NULL to set the editing mode of the viewport specified by the viewport parameter.
edit_mode	True to set the editing mode False to cancel the editing mode.

Returns

Success or failure status.

If the viewport's edit mode is turned on, 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 inherited by all child viewports.

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 Graphics 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. A viewport's edit mode is inherited by all its child viewports.

GlgSetErrorHandler()

GlgErrorHandler GlgSetErrorHandler

(

GlgErrorHandler

new_handler

)

Replaces the GLG Toolkit error handler and returns the previous error 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.

Returns

The previous error handler.

The GLG default error handler installed by default emits an audio beep and logs error in the glg_error.log file, see glg_error.log for more information. On Linux/Unix, the error message is also printed to the console using stdout.

For more information about error handlers, see the Error Processing and Debugging section of the GLG Programming Reference Manual.

GlgSetGetURLCallback()

GlgGetURLCallback GlgSetGetURLCallback

(

GlgGetURLCallback

callback

)

Installs a custom callback used to fetch data from URLs.

URLs may be used to load drawing files from remote servers, as well as to use map server installed at a remote web server. See GlgGetURLCB for details of the default URL fetching callback.

Parameters

callback

A custom callback to use for fetching URLs.

Returns

The previously installed callback, if any, otherwise NULL.

GlgSetGResource()

GlgBoolean GlgSetGResource	(	GlgObject	object,
		char *	resource_name,
		double	x_value,
		double	y_value,
		double	z_value
	)

Sets new values of a G (geometrical or color) resource.

Parameters

object	Specifies a GLG object.
resource_name	Specifies the resource path of the geometrical or color resource to be set.
x_value	Specifies the new X value.
y_value	Specifies the new Y value.
z_value	Specifies the new Z value.

Returns

Success or failure status.

If a G resource with the given resource path exists, this function sets its new values and returns True, otherwise it generates an error message and returns False.

See Resource Access Performance Optimization for more.

GlgSetGResourceIf()

GlgBoolean GlgSetGResourceIf	(	GlgObject	object,
		char *	resource_name,
		double	x_value,
		double	y_value,
		double	z_value,
		GlgBoolean	if_changed
	)

Sets new values of a G (geometrical or color) resource.

Parameters

object	Specifies a GLG object.
resource_name	Specifies the resource path of the geometrical or color resource to be set.
x_value	Specifies the new X value.
y_value	Specifies the new Y value.
z_value	Specifies the new Z value.
if_changed	If set to False, the graphical updates will be performed even if the new values are the same as the old one (equivalent to GlgSetGResource). Setting if_changed=True optimizes performance of applications that set resource values regardless whether the values have changed.

Returns

Success or failure status.

If a G resource with the given resource path exists, this function sets its new values and returns True, otherwise it generates an error message and returns False.

See Resource Access Performance Optimization for more.

GlgSetGTag()

GlgBoolean GlgSetGTag	(	GlgObject	object,
		char *	tag_source,
		double	x_value,
		double	y_value,
		double	z_value,
		GlgBoolean	if_changed
	)

Sets new values of a G (geometrical or color) tag.

Parameters

object	Specifies a GLG object.
tag_source	Specifies the TagSource of the geometrical or color tag to be set. All object's tags with the specified TagSource will be set to the supplied values.
x_value	Specifies the new X value.
y_value	Specifies the new Y value.
z_value	Specifies the new Z value.
if_changed	If set to False, the graphical updates will be performed even if the new value is the same as the old one. Setting if_changed=True optimizes performance of applications that set tag values regardless whether the values have changed.

Returns

Success or failure status.

If G tags with the given TagSource exist, this function sets their new value and returns True, otherwise it generates an error message and returns False.

See Tag Access Performance Optimization for more.

GlgSetLabelFormatter()

GlgBoolean GlgSetLabelFormatter	(	GlgObject	object,
		char *	resource_name,
		GlgLabelFormatter	formatter
	)

Attaches a custom label formatter to a chart axis or a stand-alone axis object.

See GlgLabelFormatter for more information.

Parameters

object	A chart or a parent object containing the chart.
resource_name	A resource path for accessing the chart inside the parent. Use NULL when the object parameter specifies the chart.
formatter	A custom label formatter.

Returns

True if the formatter was successfully attached.

GlgSetLinkedAxis()

GlgBoolean GlgSetLinkedAxis	(	GlgObject	object,
		char *	resource_name,
		GlgObject	axis_object,
		char *	axis_resource_name
	)

Associates a chart's plot, level line or annotation object with an Y axis for automatic rescaling.

Parameters

object	A plot, a level line or an annotation to be linked with the axis, or a parent object containing them.
resource_name	A resource path for accessing the plot, the level line of the annotation inside the parent. Use NULL when the object parameter specifies a plot, a level line or an annotation object. The resource path is relative to the object specified by the object parameter.
axis_object	The axis to link with, or the axis' parent.
axis_resource_name	A resource path for accessing the axis inside axis_object, or inside the object if axis_object is NULL. Use NULL when the axis_object parameter specifies an axis.

Returns

Success or failure status.

GlgSetLParameter()

GlgBoolean GlgSetLParameter	(	char *	name,
		GlgLong	value
	)

Sets a value of a global parameter.

Parameters

name	Parameter name.
value	Parameter value.

Returns

Success or failure status.

Refer to the Appendix D: Global Parameters section of the GLG Programming Reference Manual for information on available global parameters.

GlgSetResourceFromObject()

GlgBoolean GlgSetResourceFromObject	(	GlgObject	object,
		char *	resource_name,
		GlgObject	value
	)

Sets a new value of a data resource to the value of contained in the provided data object of the same data type.

Parameters

object	Specifies a GLG object.
resource_name	Specifies the name of the D, S or G resource to be set.
value	An object of the matching data type containing the new value.

Returns

Success or failure status.

If a resource of a matching type at the given resource path exists, the function sets the value of the resource to a value defined by the value object and returns True, otherwise it generates an error message and returns False.

The object type and data type of the resource specified by the resource path should match the corresponding types of the value object.

See Resource Access Performance Optimization for more.

GlgSetResourceFromObjectIf()

GlgBoolean GlgSetResourceFromObjectIf	(	GlgObject	object,
		char *	resource_name,
		GlgObject	value,
		GlgBoolean	if_changed
	)

Sets the value of the data object to the value of another data object of the same data type.

Parameters

object	Specifies a GLG object.
resource_name	Specifies the name of the resource to be set.
value	Specifies the object containing the new value.
if_changed	If set to False, the graphical updates will be performed even if the new value is the same as the old one (equivalent to GlgSetResourceFromObject). Setting if_changed=True optimizes performance of applications that set resource values regardless whether the values have changed.

Returns

Success or failure status.

If a resource of a matching type at the given resource path exists, the function sets the value of the resource to a value defined by the value object and returns True, otherwise it generates an error message and returns False.

The object type and data type of the resource specified by the resource path should match the corresponding types of the value object.

See Resource Access Performance Optimization for more.

GlgSetSResource()

GlgBoolean GlgSetSResource	(	GlgObject	object,
		char *	resource_name,
		char *	value
	)

Replaces the string of an S (string) resource.

Parameters

object	Specifies a GLG object.
resource_name	Specifies the resource path of the string resource to be set.
value	Specifies a new string.

Returns

Success or failure status.

If a string resource with the given resource path exists, this function creates a copy of the input string, sets that copy as the new value of the resource and returns True, otherwise it generates an error message and returns False.

The memory associated with the old string is automatically freed.

See Resource Access Performance Optimization for more.

GlgSetSResourceFromD()

GlgBoolean GlgSetSResourceFromD	(	GlgObject	object,
		char *	resource_name,
		char *	format,
		double	value
	)

Sets the string of an S (string) resource from a double value, converting the value into a string using a printf format string.

Parameters

object	Specifies a GLG object.
resource_name	Specifies the resource path of the string resource to be set.
format	Specifies the printf-style format to use when setting the resource string.
value	Specifies the numerical value to be converted to a string according to the specified format.

Returns

Success or failure status.

If a string resource with the given resource path exists, this function sets it to a new string containing the value parameter formatter using the format argument and returns True, otherwise it generates an error message and returns False.

The memory associated with the old string is automatically freed.

See Resource Access Performance Optimization for more.

GlgSetSResourceFromDIf()

GlgBoolean GlgSetSResourceFromDIf	(	GlgObject	object,
		char *	resource_name,
		char *	format,
		double	value,
		GlgBoolean	if_changed
	)

Sets the string of an S (string) resource from a double value, converting the value into a string using a printf format string.

Parameters

object	Specifies a GLG object.
resource_name	Specifies the resource path of the string resource to be set.
format	Specifies the printf-style format to use when setting the resource string.
value	Specifies the numerical value to be converted to a string according to the specified format.
if_changed	If set to False, the graphical updates will be performed even if the new value is the same as the old one (equivalent to GlgSetSResourceFromD). Setting if_changed=True optimizes performance of applications that set resource values regardless whether the values have changed.

Returns

Success or failure status.

If a string resource with the given resource path exists, this function sets it to a new string containing the value parameter formatted using the format argument and returns True, otherwise it generates an error message and returns False.

The memory associated with the old string is automatically freed.

See Resource Access Performance Optimization for more.

GlgSetSResourceIf()

GlgBoolean GlgSetSResourceIf	(	GlgObject	object,
		char *	resource_name,
		char *	value,
		GlgBoolean	if_changed
	)

Replaces the string of an S (string) resource.

Parameters

object	Specifies a GLG object.
resource_name	Specifies the resource path of the string resource to be set.
value	Specifies a new string.
if_changed	If set to False, the graphical updates will be performed even if the new value is the same as the old one (equivalent to GlgSetSResource). Setting if_changed=True optimizes performance of applications that set resource values regardless whether the values have changed.

Returns

Success or failure status.

If a string resource with the given resource path exists, this function creates a copy of the input string, sets that copy as the new value of the resource and returns True, otherwise it generates an error message and returns False.

The memory associated with the old string is automatically freed.

See Resource Access Performance Optimization for more.

GlgSetSTag()

GlgBoolean GlgSetSTag	(	GlgObject	object,
		char *	tag_source,
		char *	value,
		GlgBoolean	if_changed
	)

Replaces the string of an S (string) tag.

Parameters

object	Specifies a GLG object.
tag_source	Specifies TagSource of the string tag to be set. All object's tags with the specified TagSource will be set to the supplied value.
value	Specifies a new string.
if_changed	If set to False, the graphical updates will be performed even if the new value is the same as the old one. Setting if_changed=True optimizes performance of applications that set tag values regardless whether the values have changed.

Returns

Success or failure status.

If string tags with the given TagSource exist, this function creates copies of the input string, sets these copies as new values of the tags and returns True, otherwise it generates an error message and returns False.

The memory associated with the old strings is automatically freed.

See Tag Access Performance Optimization for more.

GlgSetSTagFromD()

GlgBoolean GlgSetSTagFromD	(	GlgObject	object,
		char *	tag_source,
		char *	format,
		double	value,
		GlgBoolean	if_changed
	)

Replaces the string of an S (string) tag with a value specified by an input number and a format string.

Parameters

object	Specifies a GLG object.
tag_source	Specifies the TagSource of the string tag to be set. All object's tags with the specified TagSource will be set to the supplied values.
format	Specifies the printf-style format to use when setting the tag string.
value	Specifies the numerical value to be converted to a string according to the specified format.
if_changed	If set to False, the graphical updates will be performed even if the new value is the same as the old one. Setting if_changed=True optimizes performance of applications that set tag values regardless whether the values have changed.

Returns

Success or failure status.

If string tags with the given TagSource exist, this function replaces their strings with new strings containing the value parameter formatted using the format argument and returns True, otherwise it generates an error message and returns False.

The memory associated with the old strings is automatically freed.

See Tag Access Performance Optimization for more.

GlgSetupHierarchy()

void GlgSetupHierarchy

(

GlgObject

object

)

Provides an explicit request to set up the object hierarchy without rendering the object.

Parameters

object

Specifies an object to be set up.

When invoked on a drawing which has been loaded but not yet displayed, the method sets up the drawing's object hierarchy to prepare the drawing for rendering. The drawing should contain either a top-level viewport object, or a group containing several top-level viewports.

After the initial draw (when the object hierarchy has already been set up), the method can be used to set up any type of object after its resources were changed. Unlike GlgUpdate, GlgSetupHierarchy sets up the object without repainting it.

GlgSetZoom()

GlgBoolean GlgSetZoom	(	GlgObject	object,
		char *	resource_name,
		GlgLong	type,
		double	value
	)

Provides a programmatic interface to integrated zooming and panning.

Parameters

object	Specifies a viewport or a light viewport, or its parent.
resource_name	Specifies the resource path of a child viewport to zoom or pan, or NULL to zoom or pan the viewport specified by the object parameter. The resource path is relative to the object specified by the object parameter.
type	A char value that specifies the type of the zoom or pan operation to perform. For example, 'i' may be used to zoom in. The value of this parameter matches the corresponding zooming and panning accelerators: i - zooms 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 - zooms 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 - starts 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. _ - starts 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 to zoom the chart along the time axis. | - starts 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 to zoom the chart along the value axis. @ - starts ZoomToXY mode (left-click and drag the mouse to finish, value is ignored). T - starts 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 - aborts ZoomTo mode, value is ignored. s - starts 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. ^ - starts 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. > - starts 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. & - starts XY dragging mode (left-click and drag the drawing with the mouse to pan or scroll). f - fits 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 - fits 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 - resets 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 panning 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 - resets 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 - pans 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 - pans 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 - pans 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 - pans 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 - pans horizontally by the distance in screen coordinates specified by the value parameter, the sign of the value defines the pan direction. y - pans vertically by the distance in screen coordinates specified by the value parameter, the sign of the value defines the pan direction. X - pans 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 - pans 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 - anchors on the upper edge, value is ignored (Drawing Zoom Mode only). D - anchors on the lower edge, value is ignored (Drawing Zoom Mode only). R - anchors on the right edge, value is ignored (Drawing Zoom Mode only). L - anchors on the lower edge, value is ignored (Drawing Zoom Mode only). A - rotates the drawing clockwise around X axis by the angle specified by the value parameter (Drawing Zoom Mode only). a - rotates the drawing counterclockwise around X axis by the angle specified by the value parameter (Drawing Zoom Mode only). B - rotates the drawing clockwise around Y axis by the angle specified by the value parameter (Drawing Zoom Mode only). b - rotates the drawing counterclockwise around Y axis by the angle specified by the value parameter (Drawing Zoom Mode only). C - rotates 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 - rotates 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.

Returns

True if zoom operation succeeded, otherwise False.

This function performs a specified zoom or pan operation regardless of the setting of the viewport's Pan and ZoomEnabled attributes.

Zooming and panning keyboard accelerators may also be used by settings a viewport's ZoomEnabled attribute to True (the user may have to click on the viewport first to set the keyboard focus). This is especially useful for interactive testing of integrated zooming and panning in the GLG Graphics Builder.

The viewport's Pan attribute can be used to activate integrated scrollbars for scrolling the drawing, as well as scrolling charts and GIS maps.

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

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()

GlgBoolean GlgSetZoomMode	(	GlgObject	object,
		char *	resource_name,
		GlgObject	zoom_object,
		char *	zoom_object_resource_name,
		GlgZoomMode	zoom_mode
	)

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

Parameters

object	Specifies a viewport object or a viewport's parent.
resource_name	Specifies the resource path 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 path is relative to the object specified by the object parameter.
zoom_object	GIS or Chart object to be zoomed in the GIS and Chart zooming modes (or NULL for the Drawing zoom mode): If not NULL, specifies the GIS or Chart object (or its parent if zoom_object_resource_name is not NULL). If NULL, zoom_object_resource_name is used to to specify the GIS or Chart object in the GIS and Chart zooming modes as describe below.
zoom_object_resource_name	Resource path of the GIS or Chart object. If NULL, the GIS or Chart object supplied by the zoom_object parameter is selected as the GIS or Chart object to be zoomed. If not NULL, specifies the resource path of the GIS or Chart object to be zoomed. The resource path is relative to the zoom_object parameter, or to the object specified by the object and resource_name parameters if the zoom_object parameter is NULL.
zoom_mode	The zoom mode to set: GLG_DRAWING_ZOOM_MODE to zoom the drawing GLG_GIS_ZOOM_MODE to zoom a GIS Object's map GLG_CHART_ZOOM_MODE to zoom a Chart object.

Returns

Success or failure status.

GlgSleep()

void GlgSleep

(

GlgLong

millisec

)

Suspends application execution for a specified interval in a platform independent way.

Parameters

millisec

Sleep interval in milliseconds.

GlgStrClone()

char* GlgStrClone

(

char *

string

)

Creates a copy of a character string.

The copy should later be freed with GlgFree.

Parameters

string

The string to be copied. If a NULL pointer is passed, the return value will also be NULL.

Returns

The cloned string.

GlgSync()

GlgBoolean GlgSync

(

GlgObject

viewport

)

Flushes the windowing system output to the display.

If OpenGL is used, it also flushes OpenGL buffers. In X11, it also waits for all requests to be processed.

Parameters

viewport

The viewport object whose buffers will be flushed.

Returns

Success or failure status.

GlgTerminate()

void GlgTerminate

(

void

)

Terminates the application's use of the GLG Toolkit.

This function destroys all created GLG structures and frees allocated memory, flushing the internal memory pools. No GLG functions may be called after a call to GlgTerminate.

GlgUpdate()

GlgBoolean GlgUpdate

(

GlgObject

object

)

Updates a drawing to show new resource values.

Parameters

object

Specifies a viewport to update.

Returns

True if the drawing has been successfully updated, otherwise False.

If object is a light viewport, an update of its parent viewport will be performed. All resource changes are held until the GlgUpdate function is called or until the viewport's window receives an expose event. (That is, it must be redrawn because another window that was obscuring a part of the viewport's window has been moved. This causes the viewport to redraw itself, using its new data.)

Note: Some drawing resources affect the object hierarchy of the drawing. For example, the Factor attribute of a series object controls the number of template instances that will be created by the series. If a number of instances is increased by setting the series' Factor, the new instances will be created and their resources can be accessed only after the GlgUpdate or GlgSetupHierarchy function is invoked. If the series object is not persistent, any change (either increase or decrease) of its Factor attribute recreates its instances, and either the GlgUpdate or GlgSetupHierarchy function should be called before accessing resources of the series' instances.

GlgUpdateChartState()

GlgBoolean GlgUpdateChartState	(	GlgObject	object,
		char *	resource_name,
		GlgChartState	state
	)

Triggers updating a chart's state after prefilling it with data using the quick mode of GlgAddDataSampleNode.

Parameters

object	A chart or a parent object containing the chart.
resource_name	A resource path for accessing the chart inside the parent. Use NULL when the object parameter specifies the chart.
state	Contains binary flags that specify the state to be updated: GLG_CHART_AUTOSCALE_STATE - updates chart's autoscale GLG_CHART_BUFFER_STATE - triggers trimming of the chart data buffer based on the chart's BufferXSpan and BufferSize attributes. GLG_CHART_SCROLLBAR_STATE - updates position of the chart's scrollbars, if any. Multiple flags can be combined with bitwise OR operator.

Returns

Success or failure status.

This function marks the selected chart states for updating. The actual update happens on the next invocation of the GlgUpdate or GlgSetupHierarchy functions.

GlgUpdateChartTimeAxis()

GlgBoolean GlgUpdateChartTimeAxis	(	GlgObject	object,
		char *	resource_name,
		double	time_stamp,
		GlgBoolean	initialize
	)

Scrolls the chart forward to show all data samples up to the provided time stamp or index.

Parameters

object	A chart or a parent object containing the chart.
resource_name	A resource path for accessing the chart inside the parent. Use NULL when the object parameter specifies the chart.
time_stamp	A time stamp (or an index for a chart with an index X axis).
initialize	May be set to True for initializing an empty sweep chart, positioning the sweep bar at the start of the plot instead of the plot end.

Returns

Success or failure status.

While a strip chart's X axis can be updated by simply setting its EndValue resource to the time stamp, a sweep chart needs to update the sweep bar and update the X axis only if needed.

GlgUpdateChartTimeAxis should be used to properly update sweep charts after using the quick mode of the GlgAddDataSampleNode function to supply a large number of data samples. The function handles both strip and sweep charts.

GlmConvert()

void GlmConvert	(	GlgProjectionType	projection,
		GlgBoolean	stretch,
		GlgCoordType	coord_type,
		GlgBoolean	coord_to_lat_lon,
		GlgPoint *	center,
		GlgPoint *	extent,
		double	angle,
		double	min_x,
		double	max_x,
		double	min_y,
		double	max_y,
		GlgPoint *	in_point,
		GlgPoint *	out_point
	)

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, without a drawing at all, or without a GIS object being present.

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. Coordinates of the returned point may be outside of the visible portion of the map for all projections.

Parameters

projection	A GIS map projection: GLG_RECTANGULAR_PROJECTION or GLG_ORTHOGRAPHIC_PROJECTION.
stretch	Specifies if the map preserves the X/Y ratio (False) or not (True).
coord_type	The type of the GLG coordinate system to convert to or from: GLG_SCREEN_COORD for screen coordinates GLG_OBJECT_COORD for world coordinates.
coord_to_lat_lon	True to convert from GLG coordinates to GIS longitude and latitude False to convert from GIS longitude and latitude to GLG coordinates.
center	A pointer to the GlgPoint structure containing lat/lon coordinates of the map center. The Z coordinate must be set to 0.
extent	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 the GIS Object section of the GLG User's Guide and Builder Reference Manual for more details.
angle	A map rotation angle in degrees.
min_x,max_x,min_y,max_y	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.
in_point	A pointer to the GlgPoint structure containing coordinate values to be converted (x/y in the selected coordinate system or lon/lat).
out_point	A pointer to the GlgPoint structure that will receive converted coordinate values (x/y in the selected coordinate system or lon/lat).