DataSetCmd - Interface to Main Application and GUI

From STX Wiki
< Programmer Guide‎ | Macro Library
Revision as of 14:28, 27 September 2019 by Jw (talk | contribs) (GetSelected)
Jump to navigation Jump to search
File: DataSet.STX, linked to library STX.LIB
See also: Workspace, BDataSet

This macro implements a set of functions for the project management and for the communication with the main application shell DataSet (Workspace) and its GUI.

Get/Set Selected Elements

GetSelected

Usage
datasetcmd getselected type
type
selects from which part of the GUI selected elements should be retrieved
Result
An empty string or a simple table item containing the selected elements. The line format of the table depends on type
Description
This function retrieves attributes of elements selected in of the lists/regions of the workspace GUI.
type = sets
Get sets selected in the detail view of the workspace. The detail view displayes a list of sets, if an element of type Set (folder) or the root element (STXDataSet) is selected in the overview.
table entry format: elementTag ; elementID ; elementIRef [; srate ; channels [; soundfilepath]]
  • The values srate and channels are set for selected audio sets (AFile, ASequence)
  • The value soundfilepath is set only for audio sets of type AFile
type = segments
Get ASeg elements (segments) selected in the detail view of the workspace. The detail view displayes a list of segments, if an audio set (AFile, ASequence, ASegList) is selected in the overview.
table entry format: audioSetIRef ; segmentID ; segmentCH
type = parameters
Get APar elements (saved parameters) selected in the detail view of the workspace. The detail view displays a list of parameters, if an audio set (AFile, ASequence, ASegList) is selected in the overview.
table entry format: audioSetIRef ; segmentID ; segmentCH ; aparMethod ; aparType
type = element
Get the element selected in the overview.
table entry format: elementTag ; elementIRef ; elementID
Example
 // process all selected segments
 if '$(#seglist := datasetcmd getselected segments)[?]' == table then
	for #i := 0 to $#i < $#seglist[] step #i := int $#i+1
		readtab $#seglist #aset';'#id';'#ch';'# /del
		
		// do something
		
	end
	delete $#seglist
 end

GetSegment & GetWave

Usage
datasetcmd getsegment aset; aseg; ach; mode
datasetcmd getwave aset; aseg; ach; mode
aset
audio set reference (iref) or * to use the selected segment
aseg
audio segment id or * to use the selected segment
mode
0 for normal return and 1 for cancel-caller
Result
  • an empty string if anything fails
  • getsegment → 'aset ; aseg ; ach ; amax ; aref '
  • getwave → 'aset ; aseg ; ach ; amax ; aref ; waveitem'
with:
  • aset audio set reference
  • aseg audio segment id
  • ach audio channel index (passed value)
  • amax, aref calibration factor and reference amplitude (0dB); values are depending on the calibration settings for the audio set
  • waveitem a wave item to access the signal of the returned segment created with $bdataset createwave
Description
If one of the arguments aset/aseg equals *, the function retrieves the first selected segment from the workspace GUI, otheriwse the specified audio set and segment id is used. The function checks if the segment is valid and calls the callibration functions to get the callibration data (amax, aref) of the audio set. If getwave is called, a wave item to access the segment is created.

The error handling is controlled by the argument mode. If mode is set to 0 (normal) the function returns an empty string on error. If it is set to 1 (cancel) an error message is displayed in a dialog box and the calling macro is canceled. This mode can be used in scripts to simplify the error handling.

SetSelected

Usage
datasetcmd setselected iref; id1; id2; ...
iref
reference of an element to be selected in the overview
id1; id2; ...
id's of elements to be selected in detail view
Result
  • none (void); an error message is displayed, if the element iref could not be selected
Description
This function selects first the element iref in the overview and than the elements specified in the id-list in the detail view. Currently it only works for audio sets!

Update GUI

RefreshDetail

Usage
datasetcmd refreshdetail
Description
Refresh the detail view. Call this function if a script has changed or created segments.

RefreshAll

Usage
datasetcmd refreshall
Description
Refresh all parts of the GUI of the main application. Call this function if a script has changed the project document.

Uncommon Functions and Functions for internal use only

All DataSetCmd functions not documented here are strictly reserved for the use by the main application DataSet (Workspace). Some of these functions are described in the kernal page DataSetCmd.