Programmer Guide/Macro Library/BSTXIni: Difference between revisions

From STX Wiki
Jump to navigationJump to search
No edit summary
 
(17 intermediate revisions by 2 users not shown)
Line 1: Line 1:
{{DISPLAYTITLE:{{SUBPAGENAME}}}}
{{DISPLAYTITLE:{{SUBPAGENAME}} - Workspace Document}}
{{TOC limit|3}}
:'''File''': BSTXIni.STX, linked to library STX.LIB
This class implements the XML 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 object must (!) be used to access the Workspace document.
:'''Parent class''': [[Programmer Guide/Macro Library/BXMLDoc|BXMLDoc]]
:'''See also''': [[Programmer_Guide/Macro_Library/BDataSet|BDataSet]]


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 DataSet file history.
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 <code>BSTXINI</code> 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.
 
The automatic Workspace version update and some installation and licence checks are also implemented by this class, but not described in this documentation.
 
Please use the ATTACH and DETACH functions from the base class [[Programmer Guide/Class Library/BXMLDoc : CObj|BXMLDOC]] before carrying out any actions on shared documents.


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


==BSTXIni Member Functions==
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.
 
The <code>BSTXIni</code> 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===
 
=====Deletes the specified profile element.=====
 
=====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:=====
 
<code>inst GetApp [ <var>appName</var> ]</code>
 
=====Parameters:=====
 
;<var>appName</var>
 
: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:=====
 
<code>3.7.6 ; Unicode ; 25 September 2005 ; 2887</code>
 
===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<nowiki>-</nowiki>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<nowiki>-</nowiki>scheme profile.
 
=====Usage:=====
 
<code><var>inst</var> LoadColorSetup [ <var>profile</var> ]</code>
 
=====Parameters:=====
 
;<var>profile</var>
 
:The color scheme profile to load. If this is not specified, the color scheme 'default' is used.
 
=====Result:=====
 
The id's of four tables.
 
<code>screenColors printColors screenPalette printPalette</code>
 
 
 
===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:=====
 
<code><var>inst</var> LoadSetupElement <var>tag</var> ; <var>id</var> ; <var>templateid</var> ; <var>ref</var></code>
 
=====Parameters:=====
 
;<var>tag</var>
 
:The profile element tag.
 
;<var>id</var>
 
:The profile element id.
 
;<var>templateid</var>
 
:The profile element id or * to use the value of <var>id</var>.
 
;<var>ref</var>
 
: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<nowiki>-</nowiki>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<nowiki>-</nowiki>scheme profile.
 
=====Usage:=====
 
<code><var>inst</var> SaveColorSetup [ <var>profile</var> ] ; <var>delete</var> ; <var>screenColors</var> ; <var>printColors</var> ; <var>screenPalette</var> ; <var>printPalette</var></code>
 
=====Parameters:=====


;<var>profile</var>
'''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 <code>$bstxini attach</code> and end with <code>$bstxini detach</code>. See [[Programmer_Guide/Macro_Library/BXMLDoc#Access_control|BXMLDoc access control]] for details.


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


;<var>delete</var>
==Static Functions==
The following functions can be called without a BSTXINI instance.


:Set to 1 if the tables arguments should be deleted before returning.
===Get last workspace file===
;Usage: <code>bstxini ?</code>
;Result: the full path of the last used workspace file


;<var>screenColors, printColors, screenPalette, printPalette</var>
===Set last workspace file===
;Usage: <code>bstxini ? <var>file</var></code>
:;<var>file</var>: the full path of the workspace file to be set


:The id's of tables containing the settings.
===Get the project history===
;Usage: <code>bstxini *</code>
;Result: a simple table containing the full path of recently used project files (one per entry)


=====Result:=====
===Add project file to the history===
;Usage: <code>bstxini + <var>file</var></code>
:;<var>file</var>: the full path of the project file to be added; if the file is already in the history, it is moved to the top


None.
===Remove project file from the history===
;Usage: <code>bstxini - <var>file</var></code>
:;<var>file</var>: the full path of the project file to be removed


===SaveSetupElement===
===Select a project file via a dialog===
;Usage: <code>bstxini selectdataset</code>
;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}}.


Save the table in the specified profile element. If the profile does not exist it is created.
===Get recently used scripts===
;Usage: <code>bstxini scripts</code>
;Result: a simple table containing the full path of recently used script files (one per entry)


=====Usage:=====
===Add script file to the history===
;Usage: <code>bstxini scripts add <var>file</var></code>
:;<var>file</var>: the full path of the script file to be added; if the file is already in the history, it is moved to the top


<code><var>inst</var> SaveSetupElement <var>table</var> ; <var>del</var> ; <var>tag</var> ; <var>id</var> ; <var>ref</var></code>
==Misc. Member Functions==


=====Parameters:=====
===Get {{STx}} Version===
;Usage: <code>$bstxini getversion</code>
;Result: the full version information string '<var>version ; revision ; freeflag</var>'
::* <var>version</var>: the version number in the format ''major.minor.bugfixrelease''
::* <var>revision</var>: the source code revision number
::* <var>freeflag</var>: '''1''' for the freeware version and '''0''' for the commercial version


;<var>table</var>
===Get Workspace File Path===
;Usage: <code>$bstxini getpath</code>
;Result: the full path of the loaded workspace file


:The table containing the profile data.
===Get Application Shell or Name===
;Usage: <code>$bstxini getapp <var>appname shellid=*</var></code>
;Result:
::* if <var>shellid</var> equals '''*''': return the shell-id of the application named <var>appname</var> or an empty string if not running; if multiple instances of this application are running, a blank separated list of shell-ids is returned
::* otherwise: return the name the application executed by the shell with the specified <var>shellid</var>


;<var>del</var>
==Member Functions for Setup Element (Profile) Handling==
Setup elements (profiles) are xml elements containing settings of {{STx}}. All profiles are stored inside the element '''/CurrentSetup''' (iref). The argument <var>subsets</var> of the profile functions is appended to the iref ('''/CurrentSetup/<var>subsets</var>).


:If 1, the table is deleted after saving. If 0, the table is not deleted.
===Get a List of Profiles===
;Usage: <code>$bstxini listprofiles <var>table ; tag ; id ; subset</var></code>
:;<var>table</var>: a simple table to store results; if no table is passed, it is created
:;<var>tag</var>: the xml tag of the profiles
:;<var>id</var>: the id of the current/selected profile of '''*'''
:;<var>subsets</var>: the xml path (partial iref) of the element containing the profiles
;Result: '<var>table index</var>'
::* <var>table</var>: the passed or created table containing the profile names (one per entry)
::* <var>index</var>: the index of the profile named <var>id</var> (set to '''0''' if not found)


;<var>tag</var>
===Load a Profile===
;Usage: <code>$bstxini loadsetupelement <var>tag ; id ; tid ; subset</var></code>
:;<var>tag</var>: the xml tag of the profile
:;<var>id</var>: the id of the profile
:;<var>tid</var>: the id of the profile template
:;<var>subsets</var>: the xml path (partial iref) of the element containing the profile
;Result: Returns a simple or extended table (depends on the profile) containing the profile settings. If the profile <var>id</var> do not exist, it is created from the template <var>tid</var> and then loaded.


:The XML element tag to save to. One of the following values:
===Save a Profile===
;Usage: <code>$bstxini savesetupelement <var>table ; del ; tag ; id ; subset</var></code>
:;<var>table</var>: a table (simple or extended, deponds on profile) containing the profile data to be saved
:;<var>del</var>: if set to '''1''' the passed table is deleted after saving
:;<var>tag</var>: the xml tag of the profile
:;<var>id</var>: the id of the profile
:;<var>subsets</var>: the xml path (partial iref) of the element containing the profile
;Result: '''0''' for success or a non-zero error code
;Description: Saves the table in the profile element. If the profile named <var>id</var> exists already, it is replaced, otherwise it is created. If the option <var>del</var> is set to '''1''' the data table is deleted after saving.


:Table - if <var>table</var> is a simple table
===Delete a profile===
;Usage: <code>$bstxini deletesetupelement <var>tag ; id ; subsets</var></code>
:;<var>tag</var>: the xml tag of the profile
:;<var>id</var>: the id of the profile
:;<var>subsets</var>: the xml path (partial iref) of the element containing the profile
;Result: '''0''' if profile was deleted for successfully or a non-zero error code


:XTable - If you <var>table</var> is an extended table
==Uncommon Functions and Functions for internal use only==


;<var>id</var>
The following functions are not often used and not so important for user script programming. If you want to know more about these functions look at the comments in the source file '''BSTXIni.stx'''


:The value to set the XML attribute 'ID' to.
* <code>LoadAppSetup</code>: load settings of {{STx}} standard applications
* <code>SaveAppSetup</code>: save settings of {{STx}} standard applications


;<var>ref</var>
* <code>LoadDefinition</code>: load a xml-doctype definition or the entry defintion of an extended table from the {{STx}} configuration


:The relative profile set reference .
* <code>CheckVersion</code>: check {{STx}} and workspace version and update/upgrade workspace file if necessary


=====Result:=====
* <code>Save</code>: save workspace document
* <code>Save</code>: close workspace document - only used by application manager!


0 for success or non-zero error code
* <code>DialogNewSetupElement</code>: a dialog to create a settings profile

Latest revision as of 10:41, 23 July 2018

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.


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

Misc. Member Functions

Get STx Version

Usage
$bstxini getversion
Result
the full version information string 'version ; revision ; freeflag'
  • version: the version number in the format major.minor.bugfixrelease
  • revision: the source code revision number
  • freeflag: 1 for the freeware version and 0 for the commercial version

Get Workspace File Path

Usage
$bstxini getpath
Result
the full path of the loaded workspace file

Get Application Shell or Name

Usage
$bstxini getapp appname shellid=*
Result
  • if shellid equals *: return the shell-id of the application named appname or an empty string if not running; if multiple instances of this application are running, a blank separated list of shell-ids is returned
  • otherwise: return the name the application executed by the shell with the specified shellid

Member Functions for Setup Element (Profile) Handling

Setup elements (profiles) are xml elements containing settings of STx. All profiles are stored inside the element /CurrentSetup (iref). The argument subsets of the profile functions is appended to the iref (/CurrentSetup/subsets).

Get a List of Profiles

Usage
$bstxini listprofiles table ; tag ; id ; subset
table
a simple table to store results; if no table is passed, it is created
tag
the xml tag of the profiles
id
the id of the current/selected profile of *
subsets
the xml path (partial iref) of the element containing the profiles
Result
'table index'
  • table: the passed or created table containing the profile names (one per entry)
  • index: the index of the profile named id (set to 0 if not found)

Load a Profile

Usage
$bstxini loadsetupelement tag ; id ; tid ; subset
tag
the xml tag of the profile
id
the id of the profile
tid
the id of the profile template
subsets
the xml path (partial iref) of the element containing the profile
Result
Returns a simple or extended table (depends on the profile) containing the profile settings. If the profile id do not exist, it is created from the template tid and then loaded.

Save a Profile

Usage
$bstxini savesetupelement table ; del ; tag ; id ; subset
table
a table (simple or extended, deponds on profile) containing the profile data to be saved
del
if set to 1 the passed table is deleted after saving
tag
the xml tag of the profile
id
the id of the profile
subsets
the xml path (partial iref) of the element containing the profile
Result
0 for success or a non-zero error code
Description
Saves the table in the profile element. If the profile named id exists already, it is replaced, otherwise it is created. If the option del is set to 1 the data table is deleted after saving.

Delete a profile

Usage
$bstxini deletesetupelement tag ; id ; subsets
tag
the xml tag of the profile
id
the id of the profile
subsets
the xml path (partial iref) of the element containing the profile
Result
0 if profile was deleted for successfully or a non-zero error code

Uncommon Functions and Functions for internal use only

The following functions are not often used and not so important for user script programming. If you want to know more about these functions look at the comments in the source file BSTXIni.stx

  • LoadAppSetup: load settings of STx standard applications
  • SaveAppSetup: save settings of STx standard applications
  • LoadDefinition: load a xml-doctype definition or the entry defintion of an extended table from the STx configuration
  • CheckVersion: check STx and workspace version and update/upgrade workspace file if necessary
  • Save: save workspace document
  • Save: close workspace document - only used by application manager!
  • DialogNewSetupElement: a dialog to create a settings profile
Retrieved from "https://mediawiki.kfs.oeaw.ac.at/stx/docs/wiki/index.php?title=Programmer_Guide/Macro_Library/BSTXIni&oldid=10087"

Navigation menu

Personal tools