This group contains miscellaneous utility functions. More...

Detailed Description

This group contains miscellaneous utility functions.

Functions
GlgLong	GlgAddTimeOut (GlgAppContext context, GlgLong interval, GlgTimerProc callback, GlgAnyType client_data)
	Adds an interval timer in a platform-independent way. More...

GlgLong	GlgAddWorkProc (GlgAppContext context, GlgWorkProc work_proc, GlgAnyType client_data)
	Adds a work procedure in a platform-independent way. More...

void	GlgBell (GlgObject viewport)
	Produces an audio bell in a platform-independent way. More...

char *	GlgCreateRelativePath (char base_path, char filename, GlgBoolean return_null_if_not_found, GlgBoolean check_if_exists)
	Creates a filepath relative to the specified base path and provides options for checking if the path points to an existing file. More...

char *	GlgFindFile (char filename, char path, GlgBoolean check_glg_path)
	Searches for a file, first in the current directory, then in the specified directory and then in the GLG search path. More...

char *	GlgGetDir (char *path)
	Returns the directory portion of the specified path. More...

char *	GlgGetExePath (void)
	Returns the path of the program's executable. More...

GlgBoolean	GlgGetLParameter (char name, GlgLong value)
	Queries a value of a global parameter. More...

GlgLong	GlgGetMajorVersion (void)
	Returns the library's major version number. More...

GlgLong	GlgGetMinorVersion (void)
	Returns the library's minor version number. More...

GlgAnyType	GlgGetNativeComponent (GlgObject object, char *resource_name, GlgComponentQueryType type)
	ADVANCED: Returns an ID of a native windowing system component used to render the viewport. More...

char *	GlgGetRelativePath (char base_path, char filename)
	Creates a filepath relative to the specified base path. More...

GlgBoolean	GlgGetTime (GlgULong sec, GlgULong microsec)
	Returns number of seconds and microseconds since the Epoch. More...

char *	GlgGetURLCB (char request, void reserved)
	Fetches data from a URL and saves it in a temporary file. More...

GlgObject	GlgParseArgs (char program_name, char args_string, GlgLong argc, char **argv)
	This function is used by the GlgMain generic program entry point on Windows to parse command-line arguments. More...

void	GlgPrintObjectCountChanges (void)
	Prints object count changes since the last call to this function. More...

void	GlgPrintObjectCounts (void)
	Prints total object count for each of the GLG object types. More...

double	GlgRand (double low, double high)
	Generates a random number in a platform-independent way. More...

void	GlgRemoveTimeOut (GlgLong id)
	Removes a timer procedure. More...

void	GlgRemoveWorkProc (GlgLong id)
	Removes a work procedure. More...

GlgBoolean	GlgResetSizeConstraint (GlgObject text_obj)
	Forces GLG_FIT_TO_BOX_TEXT Text objects with a constrained SizeConstraint attribute to renegotiate their font size. More...

GlgBoolean	GlgSetCursorType (GlgObject viewport, char *resource_name, GlgCursorType cursor_type)
	Sets cursor for a drawing or one of its child viewports. More...

GlgGetURLCallback	GlgSetGetURLCallback (GlgGetURLCallback callback)
	Installs a custom callback used to fetch data from URLs. More...

GlgBoolean	GlgSetLParameter (char *name, GlgLong value)
	Sets a value of a global parameter. More...

void	GlgSleep (GlgLong millisec)
	Suspends application execution for a specified interval in a platform independent way. More...

GlgBoolean	GlgSync (GlgObject viewport)
	Flushes the windowing system output to the display. More...

Function Documentation

◆ GlgAddTimeOut()

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

Adds an interval timer in a platform-independent way.

Parameters

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

Returns: The timer ID that can be used by GlgRemoveTimeOut.

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

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

◆ GlgAddWorkProc()

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

Adds a work procedure in a platform-independent way.

Parameters

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

Returns: The work procedure ID that can be used by GlgRemoveWorkProc.

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

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

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

◆ GlgBell()

void GlgBell ( GlgObject viewport )

Produces an audio bell in a platform-independent way.

Parameters

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

◆ GlgCreateRelativePath()

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

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

Parameters

base_path	Specifies a base path. If NULL, the path of the program's executable will be used. Note: For Linux/Unix platforms, passing argc and argv to GlgInit (or to the GlgSessionC constructor in C++) is required to identify the path of the executable when base_path is NULL.
filename	A filename or a relative filepath. If an absolute path is specified, it will be used as is.
return_null_if_not_found	Controls the return value in case when check_if_exists=True and the targeted file or directory does not exist. If True, NULL is returned, otherwise a copy of the filename string is returned.
check_if_exists	Specifies if the function should check if the file or directory pointed to by the created relative path exists.

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

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

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

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

◆ GlgFindFile()

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

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

Parameters

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

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

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

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

◆ GlgGetDir()

char* GlgGetDir ( char * path )

Returns the directory portion of the specified path.

Parameters

path	A file or directory path.

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

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

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

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

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

◆ GlgGetExePath()

char* GlgGetExePath ( void )

Returns the path of the program's executable.

Returns: An allocated string that has to be freed with GlgFree.

This function provides a cross-platform way to retrieve the executable's path across both Windows and Linux/Unix systems.

Note: For Linux/Unix platforms, passing argc and argv to GlgInit (or to the GlgSessionC constructor in C++) is required to identify the path of the executable.

◆ GlgGetLParameter()

GlgBoolean GlgGetLParameter	(	char *	name,
		GlgLong *	value
	)

Queries a value of a global parameter.

Parameters

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

Returns: Success or failure status.

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

◆ GlgGetMajorVersion()

GlgLong GlgGetMajorVersion ( void )

Returns the library's major version number.

Returns: Major version number.

The GLG_MAJOR_VERSION macro also provides the major version number.

◆ GlgGetMinorVersion()

GlgLong GlgGetMinorVersion ( void )

Returns the library's minor version number.

Returns: Minor version number.

The GLG_MINOR_VERSION macro also provides the minor version number.

◆ GlgGetNativeComponent()

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

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

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

Parameters

object	A viewport or a viewport's parent.
resource_name	A resource path for accessing the child viewport inside its parent. Use NULL when the object parameter specifies the viewport.
type	The type of a component to retrieve: GLG_WIDGET_QUERY returns an ID of the native component used to render the viewport: a window handle on Windows when using the GTK version of the GLG library on Linux, returns a GTK container widget that holds the content of the viewport a Motif widget ID when using the legacy X11 version of the GLG library on Linux/Unix an X11 window ID when using the libglg_x11.a library for the Qt integration on Linux/Unix. This window ID will be NULL if a viewport uses a native Qt widget, such as a text box or a list GLG_SHELL_QUERY returns an ID of the viewport's top-level parent: a window handle of the top-level window on Windows a top level GTK window when using the GTK version of the GLG library on Linux a top level Motif shell ID the viewport belongs to when using the legacy X11 version of the GLG library on Linux/Unix in the Qt integration that uses the libglg_x11.a library on Linux/Unix, it returns an X11 window ID of the top parent's Qt widget, or an X11 window ID of the first encountered parent viewport with ShellType set to either GLG_DIALOG_SHELL or GLG_APPLICATION_SHELL. GLG_CHILD_WIDGET_QUERY In the GTK version of the GLG library on Linux, returns the widget ID of a native input widget, such as a text or combo box, or NULL if the viewport doesn't use native widgets. In the legacy X11 version of the GLG library on Linux/Unix, returns a widget ID of a child Motif widget inside a scroll pane for a native widget that uses a scroll pane, such as a text edit or list widget. For these widgets, GLG_WIDGET_QUERY returns the widget ID of the scroll pane, and GLG_CHILD_WIDGET_QUERY returns the list or text widget itself. GLG_V_SCROLLBAR_QUERY and GLG_H_SCROLLBAR_QUERY In the legacy X11 version of the GLG library on Linux/Unix, returns a Motif widget ID of a requested scrollbar widget for native widgets that use a scroll pane. GLG_DISPLAY_QUERY In the X11 versions of the GLG library, returns the X11 display pointer for the viewport's window. GLG_WINDOW_QUERY In the X11 versions of the GLG library, returns an X11 window ID of the viewport's window. In Qt integration that uses the libglg_x11.a library on Linux/Unix, this window ID will be NULL for a viewport that uses a native Qt widget, such as a text box or a list. For these viewports, GLG_NB_WIDGET_QUERY may be used to get the Qt widget used by the viewport. on Windows, returns a viewport's window handle (same as GLG_WIDGET_QUERY). GLG_NB_WIDGET_QUERY - in the Qt integration that uses the libglg_x11.a library on Linux/Unix, returns a Qt widget used by the viewport, or NULL if the viewport does not use a native Qt widget. GLG_TOP_WIDGET_QUERY In the Qt integration that uses the libglg_x11.a on Linux/Unix, returns the Qt parent widget of the top viewport, such as QGlgWidget.

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

◆ GlgGetRelativePath()

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

Creates a filepath relative to the specified base path.

Parameters

base_path	Specifies a base path. If NULL, the path of the program's executable will be used. Note: For Linux/Unix platforms, passing argc and argv to GlgInit (or to the GlgSessionC constructor in C++) is required to identify the path of the executable when base_path is NULL.
filename	A filename or a relative filepath. If an absolute path is specified, it will be returned as is.

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

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

◆ GlgGetTime()

GlgBoolean GlgGetTime	(	GlgULong *	sec,
		GlgULong *	microsec
	)

Returns number of seconds and microseconds since the Epoch.

Parameters

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

Returns: Success or failure status.

◆ GlgGetURLCB()

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

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

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

GlgSetGetURLCallback( GlgGetURLCB );

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

Parameters

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

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

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

◆ GlgParseArgs()

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

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

Parameters

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

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

◆ GlgPrintObjectCountChanges()

void GlgPrintObjectCountChanges ( void )

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

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

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

◆ GlgPrintObjectCounts()

void GlgPrintObjectCounts ( void )

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

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

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

◆ GlgRand()

double GlgRand	(	double	low,
		double	high
	)

Generates a random number in a platform-independent way.

Parameters

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

Returns: The random number in the specified range.

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

◆ GlgRemoveTimeOut()

void GlgRemoveTimeOut ( GlgLong id )

Removes a timer procedure.

Parameters

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

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

◆ GlgRemoveWorkProc()

void GlgRemoveWorkProc ( GlgLong id )

Removes a work procedure.

Parameters

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

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

◆ GlgResetSizeConstraint()

GlgBoolean GlgResetSizeConstraint ( GlgObject text_obj )

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

Parameters

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

Returns: Success or failure status.

◆ GlgSetCursorType()

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

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

Parameters

viewport	A viewport object or a viewport's parent.
resource_name	The resource path of a child viewport to set the cursor of, or NULL to set the cursor of the viewport specified by the viewport parameter. The resource path is relative to the object specified by the viewport parameter.
cursor_type	One of the system cursor types to be used: GLG_DEFAULT_CURSOR GLG_CROSSHAIR_CURSOR GLG_WAIT_CURSOR GLG_HAND_CURSOR GLG_MOVE_CURSOR.

Returns: Success or failure status.

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

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

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

◆ GlgSetGetURLCallback()

GlgGetURLCallback GlgSetGetURLCallback ( GlgGetURLCallback callback )

Installs a custom callback used to fetch data from URLs.

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

Parameters

callback A custom callback to use for fetching URLs.

Returns: The previously installed callback, if any, otherwise NULL.

◆ GlgSetLParameter()

GlgBoolean GlgSetLParameter	(	char *	name,
		GlgLong	value
	)

Sets a value of a global parameter.

Parameters

name	Parameter name.
value	Parameter value.

Returns: Success or failure status.

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

◆ GlgSleep()

void GlgSleep ( GlgLong millisec )

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

Parameters

millisec Sleep interval in milliseconds.

◆ GlgSync()

GlgBoolean GlgSync ( GlgObject viewport )

Flushes the windowing system output to the display.

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

Parameters

viewport The viewport object whose buffers will be flushed.

Returns: Success or failure status.

Detailed Description

Functions

Function Documentation

◆ GlgAddTimeOut()

◆ GlgAddWorkProc()

◆ GlgBell()

◆ GlgCreateRelativePath()

◆ GlgFindFile()

◆ GlgGetDir()

◆ GlgGetExePath()

◆ GlgGetLParameter()

◆ GlgGetMajorVersion()

◆ GlgGetMinorVersion()

◆ GlgGetNativeComponent()

◆ GlgGetRelativePath()

◆ GlgGetTime()

◆ GlgGetURLCB()

◆ GlgParseArgs()

◆ GlgPrintObjectCountChanges()

◆ GlgPrintObjectCounts()

◆ GlgRand()

◆ GlgRemoveTimeOut()

◆ GlgRemoveWorkProc()

◆ GlgResetSizeConstraint()

◆ GlgSetCursorType()

◆ GlgSetGetURLCallback()

◆ GlgSetLParameter()

◆ GlgSleep()

◆ GlgSync()