Programmer Guide/Macro Library/BDataSet: Difference between revisions

From STX Wiki
Jump to navigationJump to search
No edit summary
Line 1: Line 1:
{{TODO}}
{{DISPLAYTITLE:{{SUBPAGENAME}} - Project Management}}
This class implements the XML 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 programmer must not create or destroy the project object because these functions are performed by the application startup and cleanup macros. So, deleting them manually would cause them to be deleted twice, causing the need for a new instance to be created for no instance to be left.
:'''File''': BDataSet.STX, linked to library STX.LIB
:'''See also''':
 
This class implements the XML 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 programmer must not create or destroy the project object because these functions are performed by the application startup and cleanup macros.  


At application startup a <code>BDATASET</code> instance is created and linked to the global Project document which is created and managed by the {{STx}} master shell and/or the application Project. The name of this instance is stored in the shell variable <var>BDATASET</var>. This object must be used to access the project document.
At application startup a <code>BDATASET</code> instance is created and linked to the global Project document which is created and managed by the {{STx}} master shell and/or the application Project. The name of this instance is stored in the shell variable <var>BDATASET</var>. This object must be used to access the project document.
Line 20: Line 23:
<span style="color: red">Beware of using the base class functions, since they do not update the <code>BDataSet</code> member variables!</span>
<span style="color: red">Beware of using the base class functions, since they do not update the <code>BDataSet</code> member variables!</span>


==Public Functions==
===AddASet===
===AFileIsLinked===
===Attach===
Lock the xml-fileitem of the document, this function should be called before the xml-content is changed or a find/query is started. Note: the current position is saved and restored when DETACH is called!
$bdataset attach
;result:Returns an asterisk if the project file cannot be locked, otherwise returns the project file item.
===AttrListView===
===BackupEmpty===
===BackupLoad===
===BackupSave===
===Construct===
DO NOT USE!
===CreateWave===
Create a [[Programmer_Guide/Shell_Items/Wave|wave object]] for an audio element.
;usage:<code><var>instance</var> CREATEWAVE <var>aset</var> ; <var>aseg</var> ; <var>channels</var> ; <var>mode</var></code>
;<var>aset</var>:an audio set reference
;<var>aseg</var>:segment reference, segment name, segment expression, * (whole audio set), *x (append segment of length 'x' to sound file)
;<var>channels</var>:0 or * all channels
:CHANNELS channels defined in the segment element
:ch1 [..chN] channel numbers
;<var>mode</var>:wave item for MULTIPLE or SINGLE access (sequences only)
;result: empty string or a 'waveitem'
===CreateWaveEx===
===DeleteWave===
===Destruct===
DO NOT USE!
===Detach===
===DialogEditSegment===
===DialogGetAttributes===
===DialogSelectSegment===
===EvalSegment===
===ExportSD0===
===FindSegment===
===GetASetInfo===
instance GETASETINFO [aset [; type]]
Retrieve information about the currently selected audio set (a sound file or a sequence). Note that the currently selected audio set (&asetPos) is not necessarily the selected element in the XML file!
;Result:empty string or 'Soundfile;id;sr;ch;file' or 'Sequence;id;sr;ch
{{TODO}}
===GetAttributes===
Get a list of attributes defined in the selected set or segment.
$bdataset GetAttributes <var>type</var> <var>table</var>|list <var>autoExclude</var> <var>excludeList</var>
;<var>table</var>|list: If a table item is specified, then the attribute list is returned in a table. If 'list' is specified, then a blank separated list of attributes is returned.
{{TODO}}
===GetBaseDirectory===
instance GetBaseDirectory <var>fileitem</var>|<var>filepath</var>
Return the base directory for the specified file item or file path path.
===GetPath===
===GetReservedAttributes===
===GetSegment===
Get attributes of segment.
instance GETSEGMENT aset; aseg; attr1; ...
;aset:audio set reference (iref | xmlPos | *)
;aseg:segment reference or name of segment
;attrX: requested attribute
{|class="einrahmen"
! attrX
! valueX
|-
| ID or NAME
| segmentname
|-
| IREF
| iref of segment (reference)
|-
| SEGMENT [unit]
| segmentexpression
|-
| POSITION or BEGIN [unit]
| begin
|-
| END [unit]
| end
|-
| LENGTH [unit]
| length
|-
| CHANNEL
| channel-number (* for all channels)
|-
| attribute
| attributevalue
|-
|}
;result:empty string on error or requested attributes (separated by semi-colons if more than 1)
;notes: If the segment was found, the database position is set to the segment element
:To select the database element of a segment, an empty attribute list can be used
:If an empty attributelist is used, the result is set to '*' to indicate success
===GetTemplateForCurrentTag===
===GetWaveInfo===
===ImportSD0===
===ImportXML===
===IsLinked===
===IsNewFile===
===IsRelative===
===IsReservedAttribute===
===Load===
===MakeChannelList===
===OpenAutoAFile===
===OpenAutoAFileEx===
===RemoveTmpSet===
===RestoreTmpSet===
===Save===
===SelectASeg===
Select a segment.
$bdataset selectaseg aset; aseg
;aset:An audio set reference. E.g. <code>/Samples.wav</code>
;aseg:The XML position, IREF or ID of a segment
;result:0 or errorcode


===SelectASet===
===Attach/Detach===
instance SELECTASET aset [; type]
Select an audio set.
;aset:audio set reference (or a reference to an element inside the audio set
;type:audio set type (AFile, Soundfile, ASequence, Sequence or * = default
;Result:0 or errorcode


===SetLink===
The function <code>ATTACH</code> 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 <code>DETACH</code>.
===SetRelativity===
===SetSegment===
===Validate===


Multiple calls of <code>ATTACH</code> (by the same shell) are possible, but for each call of <code>ATTACH</code> also the function <code>DETACH</code>must be called.


*'''File''': BDATASET.STX, linked to library STX.LIB
// example for using ATTACH / DETACH
*'''Title''': the project document.
// first attach call - lock project document and save current xml-position (pos1)
*'''Parent class''': [[Programmer Guide/Macro Library/BXMLDoc|BXMLDoc]]
#projectFileItem := $bdataset attach
...
// second attach call - save xml-position (pos2)
...
// first detach call - restore xml-position pos2
...
// second detach call - restore xml-position 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

Revision as of 09:32, 26 February 2018

File: BDataSet.STX, linked to library STX.LIB
See also:

This class implements the XML 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 programmer must not create or destroy the project object because these functions are performed by the application startup and cleanup macros.

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 and/or the application Project. The name of this instance is stored in the shell variable BDATASET. This object must be used to access the project document.

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

If the project content is changed by a command (or during a block of commands), or if a longer operation is performed on the project, the ATTACH and DETACH functions should be called: 

$bdataset ATTACH

 // ...project commands...

$bdataset DETACH

No static commands are implemented; a call to the macro BDataSet (e.g. bdataset save) will do nothing, returning an empty string.

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!


Attach/Detach

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 of ATTACH also the function DETACHmust be called. 

// example for using ATTACH / DETACH
// first attach call - lock project document and save current xml-position (pos1)
#projectFileItem := $bdataset attach
... 
//	second attach call - save xml-position (pos2)
...
// first detach call - restore xml-position pos2
...
//	second detach call - restore xml-position 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
Retrieved from "https://mediawiki.kfs.oeaw.ac.at/stx/docs/wiki/index.php?title=Programmer_Guide/Macro_Library/BDataSet&oldid=9758"

Navigation menu

Personal tools