Programmer Guide/Macro Library/BDataSet: Difference between revisions

From STX Wiki
Jump to navigationJump to search
No edit summary
No edit summary
Line 1: Line 1:
{{DISPLAYTITLE:{{SUBPAGENAME}} - Project Management}}
{{DISPLAYTITLE:{{SUBPAGENAME}} - Project Management}}
:'''File''': BDataSet.STX, linked to library STX.LIB
:'''File''': BDataSet.STX, linked to library STX.LIB
:'''Class hirarchy''': BDataSet : BXMLDoc : CObj
:'''See also''': [[Programmer_Guide/Macro_Library/BXMLDoc|BXMLDoc]], [[Programmer_Guide/Macro_Library/BXMLDoc|BSTXIni]], [[Programmer_Guide/Macro_Library/DataSetCmd|DataSetCmd]]  
:'''See also''': [[Programmer_Guide/Macro_Library/BXMLDoc|BXMLDoc]], [[Programmer_Guide/Macro_Library/BXMLDoc|BSTXIni]], [[Programmer_Guide/Macro_Library/DataSetCmd|DataSetCmd]]  


Line 40: Line 41:
==Project Properties==
==Project Properties==


===isNewFile===
===IsNewFile===
;Usage: <code>$bdataset isnewfile</code>
;Usage: <code>$bdataset isnewfile</code>
;Result: <code>1</code> if the project file is new (not named and not saved) and <code>0</code> otherwise.
;Result: <code>1</code> if the project file is new (not named and not saved) and <code>0</code> otherwise.
Line 50: Line 51:
===SetLink===
===SetLink===
;Usage: <code>$bdataset setlink <var>mode</var></code>
;Usage: <code>$bdataset setlink <var>mode</var></code>
:;<var>mode</mode>: <code>0</code> (or <code>no</code>) to set project to '''not linked''' and <code>1</code> (or <code>yes</code>) to set it to '''linked'''
:;<var>mode</var>: <code>0</code> (or <code>no</code>) to set project to '''not linked''' and <code>1</code> (or <code>yes</code>) to set it to '''linked'''
;Result: <code>0</code> if the selected mode was enabled and <code>1</code> if the function fails.
;Result: <code>0</code> if the selected mode was enabled and <code>1</code> if the function fails.
;Description: This function changes the project attribute <code>AFile</code> (attribute of the root-element <code>STXDataSet</code>).
;Description: This function change the project attribute <code>AFile</code> (attribute of the root-element <code>STXDataSet</code>).
* <code>AFile=Link</code>: The project is in mode '''linked'''. The segment metadata are stored in {{STx}} metadata files, which are xml-files with the same pathname as the sound file and the filetype '''stxsm'''. The segment metadata files of sound file linked to the project are loaded/saved automatically, when the project is loaded/saved. The project file contains only links to the sound files of the project.
* <code>AFile=Link</code>: The project is in mode '''linked'''. The segment metadata are stored in {{STx}} metadata files, which are xml-files with the same pathname as the sound file and the filetype '''stxsm'''. The segment metadata files of sound file linked to the project are loaded/saved automatically, when the project is loaded/saved. The project file contains only links to the sound files of the project.
* <code>AFile</code> is not assigned: The project is in mode '''not linked'''. All data of the project, including segment metadata, are stored in the project file. A project in this mode may contain multiple links to one sound file (e.g. to manage different segmentations of the same signal).
* <code>AFile</code> is not assigned: The project is in mode '''not linked'''. All data of the project, including segment metadata, are stored in the project file. A project in this mode may contain multiple links to one sound file (e.g. to manage different segmentations of the same signal).
===IsLinked===
;Usage: <code>$bdataset islinked</code>
;Result: <code>1</code> if the project is set to '''linked''' and <code>0</code> otherwise
===SetRelativity===
;Usage: <code>$bdataset setrelativity <var>mode</var></code>
:;<var>mode</var>: <code>0</code> (or <code>no</code>) to disable the relative path feature and <code>1</code> (or <code>yes</code>) to enable it
;Result: <code>0</code> if the selected mode was enabled and <code>1</code> if the function fails.
;Description: This function can be used to enable/disable the relative path option. If the relative path option is enabled, for sound file which are in the same directory as the project file or in subdirectories the relative path is saved in the project. This feature is useful if the project should be copied to other places. The relativity state is saved in the attribute <code>ARelative</code> of the root element of the project. If this attribute has the value <code>yes</code>, relative sound file pathes are used, otherwise (<code>ARelative</code>) equals <code>no</code> or is not set) absolute pathes are used.
===IsRelative===
;Usage: <code>$bdataset isrelative</code>
;Result: <code>1</code> if the project is set to '''relative sound file pathes''' and <code>0</code> otherwise
==Project Element Functions
===AddASet===
;Usage:
:;<code>$bdataset addaset <var>tag ; targetset ; id ; srate ; channels ; update</var>
:;<var>tag</var>: the type off the new audio set
::the name of an existing sound file to be added to the project
::the keyword '''AFile''' or '''*''' to create (via dialog) a new soundfile and add it to the project
::the keyword '''ASequence''' or '''Sequence''' to add a new sequence to the project
:;<var>targetset</var>: the set (folder) where the new audio set should be located; if set to '''*''', the target is selected via a dialog
:;<var>id</var>: the unique id of the new audio set; if set to '''*''' an unique id is choosen automatically
:;<var>srate</var>: the sampling rate in Hz for a new soundfile or a sequence
:;<var>channels</var>: the number of channels for a new soundfile or a sequence
:;<var>update</var>: if set to '''1''' (or '''yes''') the function <code>DataSetCmd RefreshAll</code> is called to refresh the project GUI
;Result: if successfulthe the reference (iref) of the added audio set if returned, otherwise an empty string
:Description: This function add an audio set (sound file or sequence) to the project.




==Management of Temporary Audio-Sets==
==Management of Temporary Audio-Sets==


===
===OpenAutoAFile===
 
===RemoveTmpSet===
 
===RestoreTmpSet===
 
 
 
 
 
==Project File Management==
 
===Validate===
;Usage: <code>$bdataset validate <var>showmsg</var></code>
:;<var>showmsg</var>: if set to <code>1</code> a message is displayed also if no invalid elements were detected; default: no message if no invalid elements were found
;Result: number of invalid elements (<code>0</code> for none)
;Description: This function checks all elements (sound files, segments, ...) of the project for validity. If invalid elements are detected, they can be displayed and the user is asked if they should be deleted or not.




Revision as of 15:14, 26 February 2018

File: BDataSet.STX, linked to library STX.LIB
Class hirarchy: BDataSet : BXMLDoc : CObj
See also: BXMLDoc, BSTXIni, DataSetCmd

This class implements the project document. The project document is the global database available to all STx applications and scripts and contains all data and links of the current project. The content of the project document is stored in a XML file item The programmer must not create or destroy the project object because these functions are performed by the application startup and cleanup macros.

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

At application startup a BDataSet instance is created and linked to the global project document which is created and managed by the STx master shell. The name of this instance is stored in the shell variable BDATASET. This object must be used to access the project document.

The class BDataSet is derived from the class BXMLDoc. Beware of using the base class functions, since they do not update the BDataSet member variables! No static commands are implemented by this class; a call to the macro BDataSet (e.g. bdataset save) will do nothing, returning an empty string.

Before a shell or a script uses or changes the content of the project document, it should be attached (locked) using the function call $bdataset attach (see: Attach & Detach).


Attach & Detach

Usage
$bdataset attach [ iref ]
$bdataset detach
iref
reference or position of an element of the project document, if specified the element is selected after attaching
Result
the name of the xml-file item containing the project document data
Description
The function attach locks the project document and returns the internal xml-file item containing the project data. Only the calling shell can now access the project content, all other shells are blocked. The project document remains locked until the next call to detach. Multiple calls of attach (by the same shell) are possible, but for each call also the function detachmust be called.
Example
// first attach call - lock project document and save current xml-position (pos1)
$bdataset attach
... 
//	second attach call - save xml-position (pos2)
$bdataset attach
...
// first detach call - restore xml-position pos2, project document remains locked!
$bdataset detach
...
//	second detach call - restore xml-position pos1 and unlock project document, 
//	if the project document was changed by the code between first attach and second detach,
// the message "DATASETCHANGED" is sent to all running shells
$bdataset detach

Project Properties

IsNewFile

Usage
$bdataset isnewfile
Result
1 if the project file is new (not named and not saved) and 0 otherwise.

GetPath

Usage
$bdataset getpath
Result
the full path of the project file or an empty string

SetLink

Usage
$bdataset setlink mode
mode
0 (or no) to set project to not linked and 1 (or yes) to set it to linked
Result
0 if the selected mode was enabled and 1 if the function fails.
Description
This function change the project attribute AFile (attribute of the root-element STXDataSet).
  • AFile=Link: The project is in mode linked. The segment metadata are stored in STx metadata files, which are xml-files with the same pathname as the sound file and the filetype stxsm. The segment metadata files of sound file linked to the project are loaded/saved automatically, when the project is loaded/saved. The project file contains only links to the sound files of the project.
  • AFile is not assigned: The project is in mode not linked. All data of the project, including segment metadata, are stored in the project file. A project in this mode may contain multiple links to one sound file (e.g. to manage different segmentations of the same signal).

IsLinked

Usage
$bdataset islinked
Result
1 if the project is set to linked and 0 otherwise

SetRelativity

Usage
$bdataset setrelativity mode
mode
0 (or no) to disable the relative path feature and 1 (or yes) to enable it
Result
0 if the selected mode was enabled and 1 if the function fails.
Description
This function can be used to enable/disable the relative path option. If the relative path option is enabled, for sound file which are in the same directory as the project file or in subdirectories the relative path is saved in the project. This feature is useful if the project should be copied to other places. The relativity state is saved in the attribute ARelative of the root element of the project. If this attribute has the value yes, relative sound file pathes are used, otherwise (ARelative) equals no or is not set) absolute pathes are used.

IsRelative

Usage
$bdataset isrelative
Result
1 if the project is set to relative sound file pathes and 0 otherwise



==Project Element Functions

AddASet

Usage
$bdataset addaset tag ; targetset ; id ; srate ; channels ; update
tag
the type off the new audio set
the name of an existing sound file to be added to the project
the keyword AFile or * to create (via dialog) a new soundfile and add it to the project
the keyword ASequence or Sequence to add a new sequence to the project
targetset
the set (folder) where the new audio set should be located; if set to *, the target is selected via a dialog
id
the unique id of the new audio set; if set to * an unique id is choosen automatically
srate
the sampling rate in Hz for a new soundfile or a sequence
channels
the number of channels for a new soundfile or a sequence
update
if set to 1 (or yes) the function DataSetCmd RefreshAll is called to refresh the project GUI
Result
if successfulthe the reference (iref) of the added audio set if returned, otherwise an empty string
Description: This function add an audio set (sound file or sequence) to the project.





Management of Temporary Audio-Sets

OpenAutoAFile

RemoveTmpSet

RestoreTmpSet

Project File Management

Validate

Usage
$bdataset validate showmsg
showmsg
if set to 1 a message is displayed also if no invalid elements were detected; default: no message if no invalid elements were found
Result
number of invalid elements (0 for none)
Description
This function checks all elements (sound files, segments, ...) of the project for validity. If invalid elements are detected, they can be displayed and the user is asked if they should be deleted or not.


Save

Load

Undocumented Functions

  • getBaseDirecory - used by memeber function Save to verify file path
Retrieved from "https://mediawiki.kfs.oeaw.ac.at/stx/docs/wiki/index.php?title=Programmer_Guide/Macro_Library/BDataSet&oldid=9766"

Navigation menu

Personal tools