Standard API Methods

Detailed Description

This group lists GLG Standard API methods of the GlgObjectC class.

These methods 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 methods, as well as a variety of utility functions, are also provided.

The C Standard API contains additional C Standard API functions that can be used in the C++ code.

See GlgObjectC for a complete list of methods in all APIs.

Include file: GlgClass.h

Functions
	GlgObjectC (char *filename)
	Constructor: Loads an object from a file. More...
	GlgObjectC (GlgObject object)
	Constructor: Creates a C++ class from GlgObject. More...
	GlgObjectC (void *image, GlgLong size)
	Constructor: loads an object from a generated memory image. More...
	GlgObjectC (void)
	Default constructor: Creates a null object. More...
virtual	~GlgObjectC (void)
	Destructor: Destroys an instance of GlgObjectC and dereferences the GlgObject object it contains. More...
GlgObject	AddPlot (char *resource_name, GlgObjectC &plot)
	Adds a plot to this chart. More...
GlgObject	CreateAlarmList (void)
	Creates and returns a list of alarms defined in this object. More...
GlgObject	CreateTagList (GlgBoolean unique_tag_sources)
	Creates and returns a list of data tags defined in this object. More...
GlgBoolean	DeletePlot (char *resource_name, GlgObjectC &plot)
	Deletes a plot from this chart. More...
void	DialogInitialDraw (GlgObjectC &parent)
	Displays a GLG drawing as a floating dialog for the first time after it has been created or loaded. More...
void	DialogSetupHierarchy (GlgObjectC &parent)
	Provides an explicit request to set up the object hierarchy of a drawing displayed in a dialog window. More...
void	Drop (void)
	Explicitly dereferences the GLG object contained in this instance. More...
void	EnableCallback (GlgCallbackType callback_type, GlgObject callback_viewport=NULL)
	Enables Input, Select, Trace and Hierarchy callbacks of this object. More...
GlgBoolean	ExportPostScript (char *filename="out.ps", double x=0., double y=0., double width=2000., double height=2000., GlgBoolean portrait=True, GlgBoolean stretch=True, GlgBoolean center=True)
	Generates a PostScript output of the current state of the viewport's graphics. More...
PlatformDependent	GenerateImage (char *resource_name=NULL, PlatformDependent image=NULL)
	Creates and returns an image of the current state of the viewport's graphics. More...
PlatformDependent	GenerateImageCustom (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...
GlgBoolean	GetChartDataExtent (char *resource_name, GlgMinMax *min_max, GlgBoolean x_extent, GlgBoolean visible_only)
	Queries the minimum and maximum extent of the data accumulated in thischart or in one of its plots. More...
GlgBoolean	GetDResource (char *resource_name, double *value)
	Returns the current value of a D (double) resource of this object. More...
GlgBoolean	GetDTag (char *tag_name, double *value)
	Returns the current value of a D (double) tag. More...
GlgObject	GetGlgObject (void)
	Returns an object ID of the stored GlgObject object. More...
GlgBoolean	GetGResource (char *resource_name, double *x_value, double *y_value, double *z_value)
	Returns the current value of a G (geometrical or color) resource of this object. More...
GlgBoolean	GetGTag (char *tag_name, double *x_value, double *y_value, double *z_value)
	Returns the current value of a G (geometrical or color) tag. More...
GlgObject	GetNamedPlot (char *resource_name, char *plot_name)
	Given a name of this chart's plot, returns the plot's object ID. More...
GlgBoolean	GetResource (char *resource_name, char **value)
	Returns the current value of a S (string) resource of this object. More...
GlgBoolean	GetResource (char *resource_name, double *value)
	Returns the current value of a D (double) resource of this object. More...
GlgBoolean	GetResource (char *resource_name, double *x_value, double *y_value, double *z_value)
	Returns the current value of a G (geometrical or color) resource of this object. More...
GlgBoolean	GetSResource (char *resource_name, char **value)
	Returns the current value of a S (string) resource of this object. More...
GlgBoolean	GetSTag (char *tag_name, char **value)
	Returns the current value of a S (string) tag. More...
GlgBoolean	GetTag (char *tag_name, char **value)
	Returns the current value of a S (string) tag. More...
GlgBoolean	GetTag (char *tag_name, double *value)
	Returns the current value of a D (double) tag. More...
GlgBoolean	GetTag (char *tag_name, double *x_value, double *y_value, double *z_value)
	Returns the current value of a G (geometrical or color) tag. More...
GlgBoolean	HasResourceObject (char *resource_name)
	Checks if a named resource of this object exists. More...
GlgBoolean	HasTagName (char *tag_name)
	Checks if a data tag with a specified tag name exists. More...
GlgBoolean	HasTagSource (char *tag_source)
	Checks if a data tag with a specified tag source exists. More...
virtual void	Hierarchy (GlgObjectC &callback_viewport, GlgHierarchyCBStruct *hierarchy_info)
	A Hierarchy callback is used to get access to the drawing to be displayed in the SubWindow and SubDrawing objects before the drawing is displayed. More...
void	InitialDraw (void)
	Draws a GLG viewport object for the first time after it has been created or loaded. More...
virtual void	Input (GlgObjectC &callback_viewport, GlgObjectC &message_object)
	An Input callback is used to handle user interaction with input objects, as well as object selection and action processing. More...
GlgBoolean	IsNull (void)
	Checks if a non-null object is stored in this instance. More...
GlgBoolean	Load (char *filename, char *resource_name=NULL)
	Loads an object from a file or a URL, replacing the previously stored object. More...
GlgBoolean	Load (void *image, GlgLong size, char *resource_name=NULL)
	Loads an object from a generated memory image, replacing the previously stored object. More...
void	LoadNullObject (void)
	Releases the stored object. More...
GlgBoolean	LoadWidget (char *filename)
	Loads a GLG widget from a file or a URL. More...
GlgBoolean	LoadWidget (GlgObjectC &parent)
	Extracts a GLG widget contained inside another object. More...
GlgBoolean	LoadWidget (void *image, GlgLong size)
	Loads a GLG widget from a generated memory image. More...
void	OnDrawMetafile (CDC *print_dc)
	Windows only: Provides MFC metafile output support. More...
void	OnPrint (CDC *print_dc)
	Windows only: Provides MFC printing support. More...
	operator GlgObject (void)
	Type converter to GlgObject. More...
GlgBoolean	operator! (void)
	Checks if a non-null object is stored in this instance. More...
GlgObjectC &	operator++ (int)
	Postfix operator: References an object. More...
GlgObjectC &	operator++ (void)
	Prefix operator: References an object. More...
GlgObjectC &	operator-- (int)
	Postfix operator: Dereferences an object. More...
GlgObjectC &	operator-- (void)
	Prefix operator: Dereferences an object. More...
GlgObjectC &	operator= (const GlgObjectC &object)
	Assignment operator: Stores a GLG object in this instance. More...
GlgBoolean	Print (PlatformDependent print_context, double x=0., double y=0., double width=2000., double height=2000., GlgBoolean portrait=True, GlgBoolean stretch=True, GlgBoolean center=True)
	GTK and Windows only: Generates printing output of the current state of the viewport's graphics. More...
void	Reference (void)
	Explicitly references the GLG object contained in this instance. More...
GlgBoolean	Reset (void)
	Reinitializes the drawing by resetting the drawing hierarchy, then setting it up again and rendering the drawing. More...
void	ResetHierarchy (void)
	Resets the object hierarchy. More...
GlgBoolean	Same (GlgObject object)
	Compares two GLG objects. More...
GlgBoolean	Same (GlgObjectC &object)
	Compares two GLG objects. More...
GlgBoolean	SaveImage (char *resource_name, char *filename, GlgImageFormat format=GLG_JPEG)
	Generates a JPEG or PNG image of the current state of this viewport's graphics and saves it to a file. More...
GlgBoolean	SaveImageCustom (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...
virtual void	Select (GlgObjectC &callback_viewport, char **name_array)
	A simplified selection callback is used to process object selection using object names. More...
GlgAnyType	SendMessage (char *resource_path, char *message, GlgAnyType param1=NULL, GlgAnyType param2=NULL, GlgAnyType param3=NULL, GlgAnyType param4=NULL)
	Sends a message to an object to request some action to be performed. More...
GlgBoolean	SetDResource (char *resource_name, double value)
	Sets a new value of a D (double) resource of this object. More...
GlgBoolean	SetDResourceIf (char *resource_name, double value, GlgBoolean if_changed)
	Sets a new value of a D (double) resource of this object. More...
GlgBoolean	SetDTag (char *tag_name, double value, GlgBoolean if_changed)
	Sets a new value for a D (double) tag. More...
void	SetGlgObject (GlgObject object)
	Low-level utility: Stores the specified GlgObject object in this object and references the stored object. More...
GlgBoolean	SetGResource (char *resource_name, double x_value, double y_value, double z_value)
	Sets new values of a G (geometrical or color) resource of this object. More...
GlgBoolean	SetGResourceIf (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 of this object. More...
GlgBoolean	SetGTag (char *tag_name, double x_value, double y_value, double z_value, GlgBoolean if_changed)
	Sets new values of a G (geometrical or color) tag. More...
GlgBoolean	SetResource (char *resource_name, char *format, double value)
	Replaces the string of an S (string) resource of this object with a value specified by an input number and a format string. More...
GlgBoolean	SetResource (char *resource_name, char *format, double value, GlgBoolean if_changed)
	Replaces the string of an S (string) resource of this object with a value specified by an input number and a format string. More...
GlgBoolean	SetResource (char *resource_name, char *value)
	Replaces the string of an S (string) resource of this object. More...
GlgBoolean	SetResource (char *resource_name, char *value, GlgBoolean if_changed)
	Replaces the string of an S (string) resource of this object. More...
GlgBoolean	SetResource (char *resource_name, double value)
	Sets a new value of a D (double) resource of this object. More...
GlgBoolean	SetResource (char *resource_name, double value, GlgBoolean if_changed)
	Sets a new value of a D (double) resource of this object. More...
GlgBoolean	SetResource (char *resource_name, double x_value, double y_value, double z_value)
	Sets new values of a G (geometrical or color) resource of this object. More...
GlgBoolean	SetResource (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 of this object. More...
GlgBoolean	SetResource (char *resource_name, GlgObjectC &value)
	Sets the value of a data or matrix object using another object of the same type and data type. More...
GlgBoolean	SetResource (char *resource_name, GlgObjectC &value, GlgBoolean if_changed)
	Sets the value of a data or matrix object using another object of the same type and data type. More...
GlgBoolean	SetResourceFromObject (char *resource_name, GlgObjectC &value)
	Sets the value of a data or matrix object using another object of the same type and data type. More...
GlgBoolean	SetResourceFromObjectIf (char *resource_name, GlgObjectC &value, GlgBoolean if_changed)
	Sets the value of a data or matrix object using another object of the same type and data type. More...
GlgBoolean	SetSResource (char *resource_name, char *value)
	Replaces the string of an S (string) resource of this object. More...
GlgBoolean	SetSResourceFromD (char *resource_name, char *format, double value)
	Replaces the string of an S (string) resource of this object with a value specified by an input number and a format string. More...
GlgBoolean	SetSResourceFromDIf (char *resource_name, char *format, double value, GlgBoolean if_changed)
	Replaces the string of an S (string) resource of this object with a value specified by an input number and a format string. More...
GlgBoolean	SetSResourceIf (char *resource_name, char *value, GlgBoolean if_changed)
	Replaces the string of an S (string) resource of this object. More...
GlgBoolean	SetSTag (char *tag_name, char *value, GlgBoolean if_changed)
	Replaces the string of an S (string) tag. More...
GlgBoolean	SetSTagFromD (char *tag_name, 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	SetTag (char *tag_name, 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	SetTag (char *tag_name, char *value, GlgBoolean if_changed)
	Replaces the string of an S (string) tag. More...
GlgBoolean	SetTag (char *tag_name, double value, GlgBoolean if_changed)
	Sets a new value for a D (double) tag. More...
GlgBoolean	SetTag (char *tag_name, double x_value, double y_value, double z_value, GlgBoolean if_changed)
	Sets new values of a G (geometrical or color) tag. More...
void	SetupHierarchy (void)
	Provides an explicit request to set up the object hierarchy without rendering the object. More...
GlgBoolean	SetZoom (char *resource_name, GlgLong type, double value=0.)
	Provides a programmatic interface to integrated zooming and panning. More...
GlgBoolean	SetZoomMode (char *resource_name, GlgObjectC *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	Sync (void)
	Flushes the windowing system output for this viewport to the display. More...
virtual void	Trace (GlgObjectC &callback_viewport, GlgTraceCBStruct *trace_info)
	A Trace callback is used to handle native windowing events. More...
virtual void	Trace2 (GlgObjectC &callback_viewport, GlgTraceCBStruct *trace_info)
	A Trace2 callback is used to handle native windowing events. More...
GlgBoolean	Update (void)
	Updates a drawing to show new resource values. More...

Function Documentation

GlgObjectC() [1/4]

GlgObjectC

(

char *

filename

)

Constructor: Loads an object from a file.

This is a wrapper for GlgLoadObject.

Parameters

filename

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

GlgObjectC() [2/4]

GlgObjectC

(

GlgObject

object

)

Constructor: Creates a C++ class from GlgObject.

This constructor makes it possible to assign GlgObject to a GlgObjectC object class:

GlgObjectC object = GetResourceObject( ... );

Parameters

object

C API object of the GlgObject type.

GlgObjectC() [3/4]

GlgObjectC	(	void *	image,
		GlgLong	size
	)

Constructor: loads an object from a generated 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.

This is a wrapper for GlgLoadObjectFromImage, see GlgLoadObjectFromImage for more information.

GlgObjectC() [4/4]

GlgObjectC

(

void

)

Default constructor: Creates a null object.

~GlgObjectC()

virtual ~GlgObjectC ( void  )

virtual

Destructor: Destroys an instance of GlgObjectC and dereferences the GlgObject object it contains.

AddPlot()

GlgObject AddPlot	(	char *	resource_name,
		GlgObjectC &	plot
	)

Adds a plot to this chart.

This is a wrapper for GlgAddPlot.

Parameters

resource_name	A resource path for accessing the chart inside this object. Use NULL when this object is 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 if it fails.

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 can store the plot in a GlgObjectC instance to keep a persistent reference to the plot.

CreateAlarmList()

GlgObject CreateAlarmList

(

void

)

Creates and returns a list of alarms defined in this object.

The top level viewport may be used to query the list of alarms of the whole drawing. This is a wrapper for GlgCreateAlarmList.

Returns

A group containing all alarm objects, or NULL if no alarm objects were found. The returned group is a GlgObject object that must be explicitly dereferenced. If it is assigned to a GlgObjectC instance, use the instance's Drop method to dereference the returned group as shown in the example below.

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

If this object is not a viewport, the returned alarm list will include only the 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;
 
GlgObjectC alarm_list = viewport.CreateAlarmList();
alarm_list.Drop();
 
if( !alarm_list.IsNull() )
{
   int size = alarm_list.GetSize();
   for( int i=0; i<size; ++i )
   {
      // The data object the alarm is attached to.
      GlgObjectC data_object = alarm_list.GetElement( i );
 
      // AlarmLabel may be unnamed, extract it as the XformAttr1 resource of the alarm object.
      data_object.GetSResource( "Alarm/XformAttr1", &alarm_label );
      printf( "AlarmLabel: %s\n", alarm_label );
    }
 }

CreateTagList()

GlgObject CreateTagList

(

GlgBoolean

unique_tag_sources

)

Creates and returns a list of data tags defined in this object.

The top level viewport may be used to query the list of tags of the whole drawing. This is a wrapper for GlgCreateTagList.

Parameters

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 is a GlgObject object that must be explicitly dereferenced. If it is assigned to a GlgObjectC instance, use the instance's Drop method to dereference the returned group as shown in the example below.

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

If this 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.
GlgObjectC tag_list = viewport.CreateTagList( False );
tag_list.Drop();
 
if( !tag_list.IsNull() )
{
   int size = tag_list.GetSize();
   for( int i=0; i<size; ++i )
   {
      // Query TagName and TagSource of each tag.
      GlgObjectC tag_object = tag_list.GetElement( i );
      tag_object.GetSResource( "TagName", &tag_name );
      tag_object.GetSResource( "TagSource", &tag_source );
      printf( "TagName: %s, TagSource: %s\n", tag_name, tag_source );
   }
}

Tag Access Performance Optimization

Since tags returned by CreateTagList 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 SetDTag:

viewport.SetDTag( tag_source, new_value, True );

the stored object IDs may be used with the the SetDResource method 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:

tag_object.SetDResourceIf( new_value, True );

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

The GetTagObject and QueryTags methods of the Intermediate API provide extended functionality for querying both data and export tags.

DeletePlot()

GlgBoolean DeletePlot	(	char *	resource_name,
		GlgObjectC &	plot
	)

Deletes a plot from this chart.

This is a wrapper for GlgDeletePlot.

Parameters

resource_name	A resource path for accessing the chart inside this object. Use NULL when this object is the chart.
plot	The plot to delete.

Returns

True if the plot was successfully deleted.

DialogInitialDraw()

void DialogInitialDraw

(

GlgObjectC &

parent

)

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

This is a wrapper for GlgDialogInitialDraw.

Parameters

parent

Specifies the viewport of the main drawing the dialog will be a child of.

This method is similar to InitialDraw, 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.

DialogSetupHierarchy()

void DialogSetupHierarchy

(

GlgObjectC &

parent

)

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

This is a wrapper for GlgDialogSetupHierarchy.

Parameters

parent

Specifies the viewport of the main drawing the dialog will be a child of.

This method similar to SetupHierarchy, 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 SetupHierarchy method may be used for all objects, including the dialog.

Drop()

void Drop

(

void

)

Explicitly dereferences the GLG object contained in this instance.

This is a wrapper for GlgDropObject.

EnableCallback()

void EnableCallback	(	GlgCallbackType	callback_type,
		GlgObject	callback_viewport = NULL
	)

Enables Input, Select, Trace and Hierarchy callbacks of this object.

Parameters

callback_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_viewport	If not NULL, specifies the child viewport of this object to add the callbacks to. If NULL, the callbacks will be added to this viewport.

This method enables the specified callback of a viewport object. The GlgObjectC class provides several callbacks that are invoked by the GLG Toolkit upon various actions. An application can subclass the GlgObjectC class to provide custom implementation of the callbacks that overrides the callbacks of the base class.

The following callbacks are provided:

• 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 Input, Select, Trace and Hierarchy callbacks 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 method with the same callback type will overwrite the previous value of the viewport's callback.

Note: Callbacks must be enabled 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.

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

ExportPostScript()

GlgBoolean ExportPostScript	(	char *	filename = "out.ps",
		double	x = 0.,
		double	y = 0.,
		double	width = 2000.,
		double	height = 2000.,
		GlgBoolean	portrait = True,
		GlgBoolean	stretch = True,
		GlgBoolean	center = True
	)

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

This is a wrapper for GlgExportPostScript, which receives the method's parameters. See GlgExportPostScript for parameter descriptions.

Parameters

filename	See GlgExportPostScript for parameter description.
x,y	See GlgExportPostScript for parameter description.
width,height	See GlgExportPostScript for parameter description.
portrait	See GlgExportPostScript for parameter description.
stretch	See GlgExportPostScript for parameter description.
center	See GlgExportPostScript for parameter description.

Returns

Success or failure status.

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

GenerateImage()

PlatformDependent GenerateImage	(	char *	resource_name = NULL,
		PlatformDependent	image = NULL
	)

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

This is a wrapper for GlgGenerateImage.

Parameters

resource_name	Specifies the resource path of a child viewport whose image to save, or NULL to save the image of this viewport. The resource path is relative to this viewport.
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.

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

GenerateImageCustom()

PlatformDependent GenerateImageCustom	(	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.

This is a wrapper for GlgGenerateImageCustom.

Parameters

resource_name	Specifies the resource path of a child viewport whose image to save, or NULL to save the image of this viewport. The resource path is relative to this viewport.
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 GetBoxPtr.

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.

GetChartDataExtent()

GlgBoolean GetChartDataExtent	(	char *	resource_name,
		GlgMinMax *	min_max,
		GlgBoolean	x_extent,
		GlgBoolean	visible_only
	)

Queries the minimum and maximum extent of the data accumulated in thischart or in one of its plots.

This is a wrapper for GlgGetChartDataExtent.

Parameters

resource_name	Specifies a resource path for accessing a child chart, plot or axis object inside this object. NULL may be used if this object is a Chart, Plot or Axis object.
min_max	Returned data extent.
x_extent	If True, the method returns the X extent, otherwise it returns the Y extent.
visible_only	If True, the method considers only visible data samples when calculating data extent, otherwise all samples are considered.

Returns

Success or failure status.

For a Chart object, the data extent of all plots in the chart is returned. For a Plot object, the data extent of that plot is returned.

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

GetDResource()

GlgBoolean GetDResource	(	char *	resource_name,
		double *	value
	)

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

This is a wrapper for GlgGetDResource.

Parameters

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 method copies its current value into the address specified by the value pointer and returns True, otherwise it generates an error message and returns False.

GetDTag()

GlgBoolean GetDTag	(	char *	tag_name,
		double *	value
	)

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

This is a wrapper for GlgGetDTag.

Parameters

tag_name	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 method copies its current value into the address specified by the value pointer and returns True, otherwise it generates an error message and returns False.

GetGlgObject()

GlgObject GetGlgObject

(

void

)

Returns an object ID of the stored GlgObject object.

Returns

A stored GlgObject ID, or NULL if no object is stored.

GetGResource()

GlgBoolean GetGResource	(	char *	resource_name,
		double *	x_value,
		double *	y_value,
		double *	z_value
	)

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

This is a wrapper for GlgGetGResource.

Parameters

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

GetGTag()

GlgBoolean GetGTag	(	char *	tag_name,
		double *	x_value,
		double *	y_value,
		double *	z_value
	)

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

This is a wrapper for GlgGetGTag.

Parameters

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

GetNamedPlot()

GlgObject GetNamedPlot	(	char *	resource_name,
		char *	plot_name
	)

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

This is a wrapper for GlgGetNamedPlot.

Parameters

resource_name	A resource path for accessing the chart inside this object. Use NULL when this object is the chart.
plot_name	The plot name.

Returns

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

GetResource() [1/3]

GlgBoolean GetResource	(	char *	resource_name,
		char **	value
	)

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

This is an overloaded version of GetSResource.

Parameters

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

GetResource() [2/3]

GlgBoolean GetResource	(	char *	resource_name,
		double *	value
	)

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

This is an overloaded version of GetDResource.

Parameters

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 method copies its current value into the address specified by the value pointer and returns True, otherwise it generates an error message and returns False.

GetResource() [3/3]

GlgBoolean GetResource	(	char *	resource_name,
		double *	x_value,
		double *	y_value,
		double *	z_value
	)

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

This is an overloaded version of GetGResource.

Parameters

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

GetSResource()

GlgBoolean GetSResource	(	char *	resource_name,
		char **	value
	)

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

This is a wrapper for GlgGetSResource.

Parameters

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

GetSTag()

GlgBoolean GetSTag	(	char *	tag_name,
		char **	value
	)

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

This is a wrapper for GlgGetSTag.

Parameters

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

GetTag() [1/3]

GlgBoolean GetTag	(	char *	tag_name,
		char **	value
	)

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

This is an overloaded version of GetSTag.

Parameters

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

GetTag() [2/3]

GlgBoolean GetTag	(	char *	tag_name,
		double *	value
	)

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

This is an overloaded version of GetDTag.

Parameters

tag_name	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 method copies its current value into the address specified by the value pointer and returns True, otherwise it generates an error message and returns False.

GetTag() [3/3]

GlgBoolean GetTag	(	char *	tag_name,
		double *	x_value,
		double *	y_value,
		double *	z_value
	)

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

This is an overloaded version of GetGTag.

Parameters

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

HasResourceObject()

GlgBoolean HasResourceObject

(

char *

resource_name

)

Checks if a named resource of this object exists.

This is a wrapper for GlgHasResourceObject.

Parameters

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 it returns False without generating an error message.

HasTagName()

GlgBoolean HasTagName

(

char *

tag_name

)

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

This is a wrapper for GlgHasTagName.

Parameters

tag_name

Specifies the tag name to query.

Returns

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

HasTagSource()

GlgBoolean HasTagSource

(

char *

tag_source

)

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

This is a wrapper for GlgHasTagSource.

Parameters

tag_source

Specifies the tag source to query.

Returns

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

Hierarchy()

virtual void Hierarchy ( GlgObjectC &  callback_viewport, GlgHierarchyCBStruct *  hierarchy_info  )

virtual

A Hierarchy callback is used to get access to the drawing to be displayed in the SubWindow and SubDrawing objects before the drawing is displayed.

It is a virtual callback method to be overridden by a derived class and is enabled via EnableCallback.

SubWindow objects may be used to switch drawings displayed in them, and an application may want to install a separate Input callback for each loaded drawing to handle user interaction instead of having one giant Input callback that handles input events from all drawings. An Input callback has to be added to the viewport of a drawing displayed in the subwindow before the drawing is set up and drawn. The Hierarchy callback is invoked with the ID of the subwindow's drawing after it has been loaded but before its hierarchy has been set up, making it possible to add Input callbacks as well as to initialize the drawing with data before it is painted on the screen.

The Hierarchy callback can also be used to set up data tags defined in a SubDrawing object when an instance of the subdrawing is created.

The Hierarchy callback may be added to the top level viewport or any of its children viewports. If any of a subwindow's (or subdrawing's) parent viewports has a Hierarchy callback added, the callback of the closest parent viewport will be invoked each time a subwindow loads a new drawing or a subdrawing loads its template.

The Hierarchy callback is invoked multiple times for each template drawing: when the drawing is loaded but before it is set up, when the drawing is set up but before it is drawn, as well as before and after the drawing is reset. The condition field of the hierarchy_info structure provides information on when the callback is invoked.

The SCADAViewer/CPP/GlgViewer.cpp file in the GLG installation directory provides an elaborate example of using the Hierarchy callback.

Parameters

callback_viewport	The viewport the callback is attached to.
hierarchy_info	The structure containing information about the subdrawing triggered the callback. See GlgHierarchyCBStruct for more information.

Reimplemented in GlgWrapperC.

InitialDraw()

void InitialDraw

(

void

)

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

This is a wrapper for GlgInitialDraw.

The method 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 method 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 GlgWrapperC or GtkmmGlgWidget widgets are used on Linux/Unix, or the GlgControlC control is used on Windows, this method is invoked automatically, and need not be explicitly called.

InitialDraw is equivalent to the following sequence:

SetupHierarchy();
Update();

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

Input()

virtual void Input ( GlgObjectC &  callback_viewport, GlgObjectC &  message_object  )

virtual

An Input callback is used to handle user interaction with input objects, as well as object selection and action processing.

It is a virtual callback method to be overridden by a derived class and is enabled via EnableCallback.

Parameters

callback_viewport	The viewport the callback is attached to.
message_object	The message object containing information about the event or action that triggered the callback.

See the Appendix B: Message Object Resources section of the Appendices chapter of the GLG Programming Reference Manual for a description of data contained in the message object.

The example below demonstrates a very simple input callback which terminates the application when a Quit button is pressed. The example demonstrates how to handle the default input object events and process attached command actions.

void GlgExample::Input( GlgObjectC& callback_viewport, GlgObjectC& message_object )
{
   const char 
       origin; // Name of the input object.
       format; // Message type
       action, // Reason the callback was invoked.
       command_type; // Command to be executed for <i>Command</i> action types.
 
   // Query message format.
   message_object.GetSResource( "Format", &format );
 
   // Handle default input object events.
   if( strcmp( format, "Button" ) == 0 ) // A message from a push button.
   {
      // Query the action that triggered the callback.
      message_object.GetSResource( "Action", &action );
 
      // Query the name of the button input object that triggered the callback.
      message_object.GetSResource( "Origin", &origin );
 
      // Check is the button was pressed (<i>Activate</i> action) and the button name was "Quit".
      if( strcmp( action, "Activate" ) == 0 && strcmp( origin, "Quit" ) == 0 )
        exit( 0 );
   }
   // Handle command actions attached to a button or an object.
   else if( strcmp( format, "Command" ) == 0 )   // <i>Command</i> action was triggered.
   {
      // Query command type.
      message_object.GetSResource( "ActionObject/Command/CommandType", &command_type );
 
      // Act based on the command type.
      if( strcmp( command_type, "Quit" ) == 0 )
        exit( 0 );
   }
}

The examples_c_cpp/RealTimeChart_cpp/GlgChart.cpp file in the GLG installation directory provides an elaborate example of using the Input callback. Other GLG Demos and Examples also provide coding examples of using the callback.

Reimplemented in GlgWrapperC.

IsNull()

GlgBoolean IsNull

(

void

)

Checks if a non-null object is stored in this instance.

Returns

True if this instance contains a GLG object.

Load() [1/2]

GlgBoolean Load	(	char *	filename,
		char *	resource_name = NULL
	)

Loads an object from a file or a URL, replacing the previously stored object.

This is a wrapper for GlgLoadObject.

Parameters

filename	Specifies the file or the URL to load the object from. For details of using URLs on Linux, see GlgGetURLCB.
resource_name	An optional resource path. If NULL, the whole drawing is loaded. If not NULL, the method extracts and loads only an object inside the loaded drawing that is found using the resource_name. GlgGetResourceObject is used to extract the loaded object, which requires Intermediate API.

Returns

Success or failure status.

Load() [2/2]

GlgBoolean Load	(	void *	image,
		GlgLong	size,
		char *	resource_name = NULL
	)

Loads an object from a generated memory image, replacing the previously stored object.

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.
resource_name	An optional resource path. If NULL, the whole drawing is loaded. If not NULL, the method extracts and loads only an object inside the loaded drawing that is found using the resource_name. GlgGetResourceObject is used to extract the loaded object, which requires Intermediate API.

Returns

Success or failure status.

This is a wrapper for GlgLoadObjectFromImage, see GlgLoadObjectFromImage for more information.

LoadNullObject()

void LoadNullObject

(

void

)

Releases the stored object.

Replaces the currently loaded object with a null object.

LoadWidget() [1/3]

GlgBoolean LoadWidget

(

char *

filename

)

Loads a GLG widget from a file or a URL.

Loads the "$Widget" viewport from a GLG drawing file or a URL, replacing the previously stored object. This is a wrapper for GlgLoadWidgetFromFile.

Parameters

filename

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

Returns

Success or failure status.

LoadWidget() [2/3]

GlgBoolean LoadWidget

(

GlgObjectC &

parent

)

Extracts a GLG widget contained inside another object.

Finds the "$Widget"viewport inside the parent object, and stores it, replacing the previously stored object. This is a wrapper for GlgLoadWidgetFromObject.

Parameters

parent

The parent object containing the "$Widget" viewport.

Returns

Success or failure status.

LoadWidget() [3/3]

GlgBoolean LoadWidget	(	void *	image,
		GlgLong	size
	)

Loads a GLG widget from a generated memory image.

Loads the "$Widget" viewport from a generated memory image, replacing the previously stored object.

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

Success or failure status.

This is a wrapper for GlgLoadWidgetFromImage, see GlgLoadWidgetFromImage for more information.

OnDrawMetafile()

void OnDrawMetafile

(

CDC *

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.

If this object is a light viewport, the output will be generated for its parent viewport.

Parameters

print_dc

Specifies the printing device context for metafile output.

OnPrint()

void OnPrint

(

CDC *

print_dc

)

Windows only: Provides MFC printing support.

Is used by the MFC container's OnPrint method to print GLG child window. This is a wrapper for GlgOnPrint.

If this object is a light viewport, the output will be generated for its parent viewport.

Parameters

print_dc

Specifies the printing device context.

operator GlgObject()

operator GlgObject

(

void

)

Type converter to GlgObject.

This type converter allows using C++ GlgObjectC object instances as the GlgObject parameters of the C API functions.

operator!()

GlgBoolean operator!

(

void

)

Checks if a non-null object is stored in this instance.

Returns

True if this instance contains a GLG object.

operator++() [1/2]

GlgObjectC& operator++

(

int

)

Postfix operator: References an object.

This is a wrapper for GlgReferenceObject.

Returns

A pointer to this object.

operator++() [2/2]

GlgObjectC& operator++

(

void

)

Prefix operator: References an object.

This is a wrapper for GlgReferenceObject.

Returns

A pointer to this object.

operator--() [1/2]

GlgObjectC& operator--

(

int

)

Postfix operator: Dereferences an object.

This is a wrapper for GlgDropObject.

Returns

A pointer to this object.

operator--() [2/2]

GlgObjectC& operator--

(

void

)

Prefix operator: Dereferences an object.

This is a wrapper for GlgDropObject.

Returns

A pointer to this object.

operator=()

GlgObjectC& operator=

(

const GlgObjectC &

object

)

Assignment operator: Stores a GLG object in this instance.

Parameters

object

The object to store.

Returns

A pointer to this object.

Print()

GlgBoolean Print	(	PlatformDependent	print_context,
		double	x = 0.,
		double	y = 0.,
		double	width = 2000.,
		double	height = 2000.,
		GlgBoolean	portrait = True,
		GlgBoolean	stretch = True,
		GlgBoolean	center = True
	)

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

This is a wrapper for GlgNativePrint, which receives the method's parameters. See GlgNativePrint for parameter descriptions.

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

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

Parameters

print_context	See GlgExportPostScript for parameter description.
x,y	See GlgExportPostScript for parameter description.
width,height	See GlgExportPostScript for parameter description.
portrait	See GlgExportPostScript for parameter description.
stretch	See GlgExportPostScript for parameter description.
center	See GlgExportPostScript for parameter description.

Returns

Success or failure status.

Reference()

void Reference

(

void

)

Explicitly references the GLG object contained in this instance.

This is a wrapper for GlgReferenceObject.

Reset()

GlgBoolean Reset

(

void

)

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

This is a wrapper for GlgReset.

Returns

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

Calling Reset 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 method should be invoked only for the top-level viewports, not the child viewports.

ResetHierarchy()

void ResetHierarchy

(

void

)

Resets the object hierarchy.

This is a wrapper for GlgResetHierarchy.

Resets the object hierarchy of a top-level viewport or drawing. If the object was displayed using the Generic API, this method must be called before the top-level object is destroyed.

This method should not be called for the top-level viewports used in the integrated GLG widgets, such as the GlgWrapperC or GlgControlC.

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

Same() [1/2]

GlgBoolean Same

(

GlgObject

object

)

Compares two GLG objects.

Parameters

object

The object to compare with.

Returns

True if this object refers to the same GLG object as the object parameter

Same() [2/2]

GlgBoolean Same

(

GlgObjectC &

object

)

Compares two GLG objects.

Parameters

object

The object to compare with.

Returns

True if this object refers to the same GLG object as the object parameter

SaveImage()

GlgBoolean SaveImage	(	char *	resource_name,
		char *	filename,
		GlgImageFormat	format = GLG_JPEG
	)

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

This is a wrapper for GlgSaveImage.

Parameters

resource_name	Specifies the resource path of a child viewport whose image to save, or NULL to save the image of this viewport. The resource path is relative to this viewport.
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.

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

SaveImageCustom()

GlgBoolean SaveImageCustom	(	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.

This is a wrapper for GlgSaveImageCustom.

Parameters

resource_name	Specifies the resource path of a child viewport whose image to save, or NULL to save the image of this viewport. The resource path is relative to this viewport.
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 GetBoxPtr.

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.

Select()

virtual void Select ( GlgObjectC &  callback_viewport, char **  name_array  )

virtual

A simplified selection callback is used to process object selection using object names.

It is a virtual callback method to be overridden by a derived class and is enabled via EnableCallback.

Select callback uses object names to handle selection. A more versatile Input callback may be used to handle object selection using object IDs, which will also handle unnamed objects.

Alternatively, an Action attached to an object provides the most effective way to handle object selection. An Input callback is used to process selection triggered by the Action objects.

GlgGetSelectionButton may be used inside the Select callback to query the mouse button that triggered the callback.

Parameters

callback_viewport	The viewport the callback is attached to.
name_array	A NULL-terminated list of names of all named selected objects.

The name array contains names of all objects that overlap with the given rectangle completely or partially. Both the selected objects at the bottom of the hierarchy and all their named parents will be included.

Objects in the array are listed in the reversed order compared to their drawing order, so that the objects that are at the bottom of the drawing list and are drawn on top of other objects will be listed first in the array.

The name string is a complete resource path name (relative to viewport) which can be used to access resources of the object:

// Erase the object when it is clicked on.    
char * visiblity_res_name = GlgConcatStrings( path_name, "/Visibility" );
callback_viewport.SetDResource( visiblity_res_name, 0. );
GlgFree( visiblity_res_name );

The examples_c_cpp/animation/GlgAnimationG.cpp file in the GLG installation directory provides an example of using the Select callback.

Reimplemented in GlgWrapperC.

SendMessage()

GlgAnyType SendMessage	(	char *	resource_path,
		char *	message,
		GlgAnyType	param1 = NULL,
		GlgAnyType	param2 = NULL,
		GlgAnyType	param3 = NULL,
		GlgAnyType	param4 = NULL
	)

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

This is a wrapper for GlgSendMessage.

Parameters

resource_path	If NULL, the message is sent to this object, otherwise the message is sent to the object's child specified by the resource path. The resource path is relative to this object. For example, to send the message to a viewport's handler, invoke the viewport's SendMessage with "Handler" as the resource_path parameter.
message	A string defining the type of the message.
param1	Message type dependent.
param2	Message type dependent.
param3	Message type dependent.
param4	Message type dependent.

Returns

The query result of messages that execute some query, is ignored otherwise.

This method is used to send a message to an input object with a request to execute some action. For example, a program can send an "Activate" message to a push button widget to simulate a user click, which will activate any click processing Action objects attached to the button. "Set" and "Reset" messages may be sent to a toggle button widget to change its value, which will also process any Action objects attached to the toggle.

The method also serves as an escape mechanism for actions that can not be easily accomplished by setting or querying a single resource, such us adding items to a list widget or querying a state of a multiple-selection list.

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

Some messages return an object that is is owned by the called and should be dereferenced. If the returned object is assigned to a GlgObjectC instance, use the instance's Drop method to dereference it.

SetDResource()

GlgBoolean SetDResource	(	char *	resource_name,
		double	value
	)

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

This is a wrapper for GlgSetDResource.

Parameters

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

SetDResourceIf()

GlgBoolean SetDResourceIf	(	char *	resource_name,
		double	value,
		GlgBoolean	if_changed
	)

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

This is a wrapper for GlgSetDResourceIf.

Parameters

resource_name	Specifies the name 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 SetDResource). 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 method 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.

SetDTag()

GlgBoolean SetDTag	(	char *	tag_name,
		double	value,
		GlgBoolean	if_changed
	)

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

This is a wrapper for GlgSetDTag.

Parameters

tag_name	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 method sets their new values and returns True, otherwise it generates an error message and returns False.

See Tag Access Performance Optimization for more.

SetGlgObject()

void SetGlgObject

(

GlgObject

object

)

Low-level utility: Stores the specified GlgObject object in this object and references the stored object.

Parameters

object

The object to store.

SetGResource()

GlgBoolean SetGResource	(	char *	resource_name,
		double	x_value,
		double	y_value,
		double	z_value
	)

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

This is a wrapper for GlgSetGResource.

Parameters

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 method sets its new values and returns True, otherwise it generates an error message and returns False.

See Resource Access Performance Optimization for more.

SetGResourceIf()

GlgBoolean SetGResourceIf	(	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 of this object.

This is a wrapper for GlgSetGResourceIf.

Parameters

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 SetGResource). 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 method sets its new values and returns True, otherwise it generates an error message and returns False.

See Resource Access Performance Optimization for more.

SetGTag()

GlgBoolean SetGTag	(	char *	tag_name,
		double	x_value,
		double	y_value,
		double	z_value,
		GlgBoolean	if_changed
	)

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

This is a wrapper for GlgSetGTag.

Parameters

tag_name	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 method sets their new value and returns True, otherwise it generates an error message and returns False.

See Tag Access Performance Optimization for more.

SetResource() [1/10]

GlgBoolean SetResource	(	char *	resource_name,
		char *	format,
		double	value
	)

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

This is an overloaded version of SetSResourceFromD.

Parameters

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

SetResource() [2/10]

GlgBoolean SetResource	(	char *	resource_name,
		char *	format,
		double	value,
		GlgBoolean	if_changed
	)

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

This is an overloaded version of SetSResourceFromDIf.

Parameters

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 SetSResourceFromD). 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 method 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.

SetResource() [3/10]

GlgBoolean SetResource	(	char *	resource_name,
		char *	value
	)

Replaces the string of an S (string) resource of this object.

This is an overloaded version of SetSResource.

Parameters

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

SetResource() [4/10]

GlgBoolean SetResource	(	char *	resource_name,
		char *	value,
		GlgBoolean	if_changed
	)

Replaces the string of an S (string) resource of this object.

This is an overloaded version of SetSResourceIf.

Parameters

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 SetSResource). 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 method 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.

SetResource() [5/10]

GlgBoolean SetResource	(	char *	resource_name,
		double	value
	)

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

This is an overloaded version of SetDResource.

Parameters

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

SetResource() [6/10]

GlgBoolean SetResource	(	char *	resource_name,
		double	value,
		GlgBoolean	if_changed
	)

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

This is an overloaded version of SetDResourceIf.

Parameters

resource_name	Specifies the name 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 SetDResource). 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 method 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.

SetResource() [7/10]

GlgBoolean SetResource	(	char *	resource_name,
		double	x_value,
		double	y_value,
		double	z_value
	)

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

This is an overloaded version of SetGResource.

Parameters

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 method sets its new values and returns True, otherwise it generates an error message and returns False.

See Resource Access Performance Optimization for more.

SetResource() [8/10]

GlgBoolean SetResource	(	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 of this object.

This is an overloaded version of SetGResourceIf.

Parameters

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 SetGResource). 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 method sets its new values and returns True, otherwise it generates an error message and returns False.

See Resource Access Performance Optimization for more.

SetResource() [9/10]

GlgBoolean SetResource	(	char *	resource_name,
		GlgObjectC &	value
	)

Sets the value of a data or matrix object using another object of the same type and data type.

This is an overloaded version of SetResourceFromObject.

Parameters

resource_name	Specifies the name of the resource of this object to be set.
value	Specifies the object containing the new value.

Returns

Success or failure status.

If a resource of a matching type at the given resource path exists, the method 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 for the data object) of the resource specified by the resource path should match the type of the value object.

See Resource Access Performance Optimization for more.

SetResource() [10/10]

GlgBoolean SetResource	(	char *	resource_name,
		GlgObjectC &	value,
		GlgBoolean	if_changed
	)

Sets the value of a data or matrix object using another object of the same type and data type.

This is an overloaded version of SetResourceFromObjectIf.

Parameters

resource_name	Specifies the name of the resource of this object 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 method 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 for the data object) of the resource specified by the resource path should match the type of the value object.

See Resource Access Performance Optimization for more.

SetResourceFromObject()

GlgBoolean SetResourceFromObject	(	char *	resource_name,
		GlgObjectC &	value
	)

Sets the value of a data or matrix object using another object of the same type and data type.

This is a wrapper for GlgSetResourceFromObject.

Parameters

resource_name	Specifies the name of the resource of this object to be set.
value	Specifies the object containing the new value.

Returns

Success or failure status.

If a resource of a matching type at the given resource path exists, the method 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 for the data object) of the resource specified by the resource path should match the type of the value object.

See Resource Access Performance Optimization for more.

SetResourceFromObjectIf()

GlgBoolean SetResourceFromObjectIf	(	char *	resource_name,
		GlgObjectC &	value,
		GlgBoolean	if_changed
	)

Sets the value of a data or matrix object using another object of the same type and data type.

This is a wrapper for GlgSetResourceFromObjectIf.

Parameters

resource_name	Specifies the name of the resource of this object 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 method 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 for the data object) of the resource specified by the resource path should match the type of the value object.

See Resource Access Performance Optimization for more.

SetSResource()

GlgBoolean SetSResource	(	char *	resource_name,
		char *	value
	)

Replaces the string of an S (string) resource of this object.

This is a wrapper for GlgSetSResource.

Parameters

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

SetSResourceFromD()

GlgBoolean SetSResourceFromD	(	char *	resource_name,
		char *	format,
		double	value
	)

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

This is a wrapper for GlgSetSResourceFromD.

Parameters

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

SetSResourceFromDIf()

GlgBoolean SetSResourceFromDIf	(	char *	resource_name,
		char *	format,
		double	value,
		GlgBoolean	if_changed
	)

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

This is a wrapper for GlgSetSResourceFromDIf.

Parameters

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

SetSResourceIf()

GlgBoolean SetSResourceIf	(	char *	resource_name,
		char *	value,
		GlgBoolean	if_changed
	)

Replaces the string of an S (string) resource of this object.

This is a wrapper for GlgSetSResourceIf.

Parameters

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 SetSResource). 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 method 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.

SetSTag()

GlgBoolean SetSTag	(	char *	tag_name,
		char *	value,
		GlgBoolean	if_changed
	)

Replaces the string of an S (string) tag.

This is a wrapper for GlgSetSTag.

Parameters

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

SetSTagFromD()

GlgBoolean SetSTagFromD	(	char *	tag_name,
		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.

This is a wrapper for GlgSetSTagFromD.

Parameters

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

SetTag() [1/4]

GlgBoolean SetTag	(	char *	tag_name,
		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.

This is a wrapper for GlgSetSTagFromD.

Parameters

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

SetTag() [2/4]

GlgBoolean SetTag	(	char *	tag_name,
		char *	value,
		GlgBoolean	if_changed
	)

Replaces the string of an S (string) tag.

This is an overloaded version of SetSTag.

Parameters

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

SetTag() [3/4]

GlgBoolean SetTag	(	char *	tag_name,
		double	value,
		GlgBoolean	if_changed
	)

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

This is an overloaded version of SetDTag.

Parameters

tag_name	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 method sets their new values and returns True, otherwise it generates an error message and returns False.

See Tag Access Performance Optimization for more.

SetTag() [4/4]

GlgBoolean SetTag	(	char *	tag_name,
		double	x_value,
		double	y_value,
		double	z_value,
		GlgBoolean	if_changed
	)

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

This is an overloaded version of SetGTag.

Parameters

tag_name	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 method sets their new value and returns True, otherwise it generates an error message and returns False.

See Tag Access Performance Optimization for more.

SetupHierarchy()

void SetupHierarchy

(

void

)

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

This is a wrapper for GlgSetupHierarchy.

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 Update, SetupHierarchy sets up the object without repainting it

SetZoom()

GlgBoolean SetZoom	(	char *	resource_name,
		GlgLong	type,
		double	value = 0.
	)

Provides a programmatic interface to integrated zooming and panning.

This is a wrapper for GlgSetZoom.

Parameters

resource_name	Specifies the resource path of a child viewport to zoom or pan, or NULL to zoom or pan this viewport object. The resource path is relative to this viewport object.
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. See GlgSetZoom for a list of possible values.
value	Specifies a value for zoom and pan operations.

Returns

True if zoom operation succeeded, otherwise False.

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

SetZoomMode()

GlgBoolean SetZoomMode	(	char *	resource_name,
		GlgObjectC *	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.

This is a wrapper for GlgSetZoomMode.

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

resource_name	Specifies the resource path of a child viewport whose zoom mode to set, or NULL to zoom or pan this viewport object. The resource path is relative to this viewport object.
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 viewport defined by the resource_name parameter if zoom_object 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.

Sync()

GlgBoolean Sync

(

void

)

Flushes the windowing system output for this viewport to the display.

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

Returns

Success or failure status.

Trace()

virtual void Trace ( GlgObjectC &  callback_viewport, GlgTraceCBStruct *  trace_info  )

virtual

A Trace callback is used to handle native windowing events.

It is a virtual callback method to be overridden by a derived class and is enabled via EnableCallback.

Parameters

callback_viewport	The viewport the callback is attached to.
trace_info	The structure containing information about the native windowing event that triggered the callback. See GlgTraceCBStruct for more information.

The trace callback is used as an escape mechanism to provide low-level access to native windowing events. It is invoked whenever a viewport receives a native windowing event and passes the event to the application code for processing. If a viewport object has a trace callback attached, the trace callback will be invoked for all events received by the viewport and all of its child viewports.

There are two trace callbacks: the Trace callback is invoked before the event is dispatched for processing, and the Trace2 callback is invoked after the event has been processed. If the same method is used to handle both callbacks, the reason field of the trace_info structure can be used to find which callback is invoked, GLG_TRACE_CB or GLG_TRACE2_CB.

The examples_c_cpp/GIS_cpp/GlgMapViewer.cpp file in the GLG installation directory provides an elaborate example of using the Trace callback.

Reimplemented in GlgWrapperC.

Trace2()

virtual void Trace2 ( GlgObjectC &  callback_viewport, GlgTraceCBStruct *  trace_info  )

virtual

A Trace2 callback is used to handle native windowing events.

It is a virtual callback method to be overridden by a derived class and is enabled via EnableCallback.

The Trace2 callback is similar to Trace, but is invoked after the event has been processed. See Trace for more information.

Parameters

callback_viewport	The viewport the callback is attached to.
trace_info	The structure containing information about the native windowing event that triggered the callback. See GlgTraceCBStruct for more information.

Reimplemented in GlgWrapperC.

Update()

GlgBoolean Update

(

void

)

Updates a drawing to show new resource values.

Returns

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

If this object is a light viewport, an update of its parent viewport will be performed. All resource changes are held until the Update method 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 Update or SetupHierarchy method 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 Update or SetupHierarchy method should be called before accessing resources of the series' instances.