Programmer Guide/Macro Library/BSTXIni

File: BSTXIni.STX, linked to library STX.LIB

Parent class: BXMLDoc

See also: BDataSet

This class implements the workspace document. The workspace document contains the STx configuration and the settings and is implemented as a global object which can be accessed from all STx applications and scripts. The user must not create or destroy the workspace object because these functions are performed by the application startup and cleanup macros. At application startup, a BSTXINI instance is created and linked to the global workspace document. The name of is instance is stored in the shell variable BSTXINI. This instance must (!) be used to access the workspace document.

!! Never call the member functions CONSTRUCT, DESTRUCT, CLOSE or LOAD !!

This class also implements a set of static functions which are used by the master application and the application DataSet to manage to file STX.INI which contains the name of the last used workspace file (for program startup) and the project file history. The automatic workspace version update and some installation and licence checks are also implemented by this class, but not described in this documentation.

Important note: A shell or a script should only access or change the content of the workspace document, while it is attached (locked). This is very important, because this document can be (and is often) accessed by all running shells (e.g. STx applications or scripts). A code section accessing the workspace content should start with $bstxini attach and end with $bstxini detach. See BXMLDoc access control for details.

BSTxIni Static Functions

The following functions can be called without a BSTXINI instance.

Get last workspace file

Usage

bstxini ?

Result

the full path of the last used workspace file

Set last workspace file

Usage

bstxini ? file

file

the full path of the workspace file to be set

Get the project history

Usage

bstxini *

Result

a simple table containing the full path of recently used project files (one per entry)

Add project file to the history

Usage

bstxini + file

file

the full path of the project file to be added; if the file is already in the history, it is moved to the top

Remove project file from the history

Usage

bstxini - file

file

the full path of the project file to be removed

Select a project file via a dialog

Usage

bstxini selectdataset

Result

the selected or created project file or an empty string if the cancel button was pressed

Note

This function displays the standard startup dialog of STx.

Get recently used scripts

Usage

bstxini scripts

Result

a simple table containing the full path of recently used script files (one per entry)

Add script file to the history

Usage

bstxini scripts add file

file

the full path of the script file to be added; if the file is already in the history, it is moved to the top

BSTXIni Member Functions

The BSTXIni class has the following member functions. See BXMLDoc Member Functions for a list of functions implemented in the parent class.

DELETESETUPELEMENT tag ; id ; templateid ; ref

usage:

tag	profile element tag
id	profile element id
ref	relative profile set reference

result:

none

DIALOGNEWSETUPELEMENT title ; tag ; ref

usage:

title	dialog window caption
tag	profile element tag
ref	relative profile set reference

result:

name of created profile or empty string for error/cancel

description:

Opens a dialog to enter a profile name and creates an empty profile element.

GetApp

Get an applications shell by name.

Usage:

inst GetApp [ appName ]

Parameters:

appName

The name of an installed application.

Result:

The shell id of the running application.

GetVersion

Retrieve program version information. The build type is either Unicode or ASCII.

Result:

'version-number ; build-type ; release-date ; revision'

Examples:

3.7.6 ; Unicode ; 25 September 2005 ; 2887

LISTPROFILES table ; tag ; id ; ref

usage:

table	name of target table or * to create a new table
tag	profile element tag
id	id of default/selected profile
ref	relative reference of element containing profiles

result:

table containing list of profile id's and the index of the default/selected profile ('table index')

description:

Creates a sorted list of the id's of all child elements of the specified profile set with the specified tag.

LOADAPPSETUP app ; subapp ; profile

usage:

app	name of application
subapp	name of sub-application or function
profile	name of application profile

result:

none

description:

Load all application settings for the specified application and convert loaded settings to shell or global variables.

LoadColorSetup

Load graphics settings, colors and palettes from a color-scheme profile.

Usage:

inst LoadColorSetup [ profile ]

Parameters:

profile

The color scheme profile to load. If this is not specified, the color scheme 'default' is used.

Result:

The id's of four tables.

screenColors printColors screenPalette printPalette

LoadSetupElement

Load the specified profile element data and return the loaded data. If the profile do not exist, the specified profile template element is used to create it.

Usage:

inst LoadSetupElement tag ; id ; templateid ; ref

Parameters:

tag

The profile element tag.

id

The profile element id.

templateid

The profile element id or * to use the value of id.

ref

The relative profile set reference.

Result:

The name of table containing loaded data or empty string if load fails

SAVEAPPSETUP app ; subapp ; profile

usage:

app	name of application
subapp	name of sub-application or function
profile	name of application profile

result:

none

description:

Store all application setup variables into a table and save the table into the setup elements specified by the arguments.

SaveColorSetup

Save graphics settings, colors and palettes in a color-scheme profile.

Usage:

inst SaveColorSetup [ profile ] ; delete ; screenColors ; printColors ; screenPalette ; printPalette

Parameters:

profile

The color scheme profile to load. If this is not specified, the color scheme 'default' is used.

delete

Set to 1 if the tables arguments should be deleted before returning.

screenColors, printColors, screenPalette, printPalette

The id's of tables containing the settings.

Result:

None.

SaveSetupElement

Save the table in the specified profile element. If the profile does not exist it is created.

Usage:

inst SaveSetupElement table ; del ; tag ; id ; ref

Parameters:

table

The table containing the profile data.

del

If 1, the table is deleted after saving. If 0, the table is not deleted.

tag

The XML element tag to save to. One of the following values:

Table - if table is a simple table

XTable - If you table is an extended table

id

The value to set the XML attribute 'ID' to.

ref

The relative profile set reference .

Result:

0 for success or non-zero error code