Programmer Guide/Macro Library/APar

APar : CObj

The APar class implements a parameter interface for the DataSet. An alternative to this class is the ADesc class and its derivatives.

APar Static Functions

The following static functions are implemented:

LoadData

Load existing parameter data.

Usage:

APar LoadData aset ; aseg ; method ; [ xunit [ xuref ]] | NO ; [ yunit [ yuref ]] | NO [; channel ; id ]

Parameters:

aset

The audio set reference or position.

aseg

The audio segment ID.

method

The name of the parameter method (as displayed in the Detail view).

xunit

The unit for the x-scale data. The following keywords are supported:

no, off or false Do not load the x-scale data.

<empty> Load the x-scale data without unit conversion.

unit Load the x-scale data and convert to the selected unit.

yunit

The unit for the y-scale data. The following keywords are supported:

no, off or false Do not load the y-scale data.

<empty> Load the y-scale data without unit conversion.

unit Load the y-scale data and convert to the selected unit.

channel

Passed to the Load command.

id

Passed to the Load command.

Result:

An empty string if load fails or the following (depending on the xunit and yunit arguments).

[ xdata ] [ ydata ]

Load

Load parameter object of type 'method' from the audio segment 'aset ; aseg'.

Usage:

APar Load aset ; aseg ; method [; channel ; id ]

Parameters:

aset

The audio set reference or position.

aseg

The audio segment ID.

method

The name of the parameter method (as displayed in the Detail view).

channel

The channel number of the analysed signal. If specified, the channel attribute CH is included in the parameter selection.

id

The id of the analysed signal. If specified, the id attribute ID is included in the parameter selection.

Result:

An APar instance or empty string

GetAllMethods

Retrieve all parameter extraction methods defined in the STx INI file.

Usage:

APar GetAllMethods

Result:

A semi-colon separated list of methods in the format:

method1 parameterName1 ; method2 parameterName2 ; ...

GetMethodInfo

Retrieve all information about a specific method.

Usage:

APar GetMethodInfo method

Parameters:

method

The method name (as returned by GetAllMethods).

Result:

Information about the method in the following format:

method ; param ; ny ; text ; nx ; xtype ; ytype ; unit

Otherwise an empty string is returned.

GetParameterInfo

Retrieve all information about a parameter type. E.g a fundamental frequency parameter.

Usage:

APar GetParameterInfo param

Result:

If successful, the all information pertaining to the parameter param is returned in the following format:

name ; nx ; text ; xtype ; ytype ; unit

Otherwise an empty string is returned.

Examples:

The call

APar GetParameterInfo F0

returns the string

F0; 1; Fundametal Frequency; time; frequency;

GetTypeInfo

Retrieve information about a scale type.

Usage:

APar GetTypeInfo type

Parameters:

type

A valid unit type (One of the entries returned by GetAllUnitTypes).

Result:

A simple table of defined units or empty string if type does not exist. Each table entry has the following format:

unit ; unitname ; ref ; min ; max

GetAllUnits

Get a list of all units (shortname) of a scale type.

Usage:

APar GetAllUnits type

Parameters:

type

A valid unit type (One of the entries returned by GetAllUnitTypes).

Result:

A blank separated list of the units of the requested type.

GetAllUnitTypes

Retrieve all unit types currently supported. One of these types can then be passed to the functions GetTypeInfo or GetAllUnits.

Usage:

APar GetAllUnitTypes

Result:

A simple table with one entry per unit type.

APar Class Members

The APar class implements the following public member functions. See CObj Member Functions for a list of functions implemented in the parent class.

construct

Initialise the instance. If posref is specified, initialize the instance with parameter data from the element at the position reference (see Load for more details). If table is specified, initialize the instance with a table containing parameters (see NEW for more details).

Usage:

inst construct [ posref | table ]

Parameters:

posref

An IRef to an APar element in the DataSet.

table

The table containing the parameters.

Result:

0 if successful, 1 otherwise.

destruct

Destroy the instance.

getScale

Get the scale domain.

Usage:

inst getScale axis order

Parameters:

axis

The name of the axis (X|Y)

order

The axis order or parameter number.

Result:

The domain of selected scale or an empty string.

getXData

Get x scale data vector.

Usage:

inst getXData order ; length ; unit uref [; table field ]

Parameters:

order

The x-scale order (1 or 2). The default value is 1.

length

The number of values (0|* = original length)

unit, uref

The output unit and reference value. The default unit depends on the parameter type. For time parameters the default unit is seconds (s) whilst for frequency parameters, the default unit is Hz.

table, field

The output table and field (a new table is created if not specified).

Result:

The x-data vector (parameter table with one row) or empty string.

getYData

Get the y scale data vector(s).

Usage:

inst getYData index ; length ; unit uref [; table field ; mvsym ]

Parameters:

index

The index of the y-data to be loaded (0 for all).

length

The number of values (0|* = original length)

unit, uref

The output unit and reference value. If no unit is specified, the unit specified with the last setYData is used.

table, field

The output table and (first) field (a new table is created if not specified).

mvsym

The missing value symbol.

Result:

The y-data vector/s (parameter table) or empty string.

load

Load data from an existing APar in the DataSet into this instance.

Usage:

inst load aparref

Parameters:

aparref

An IRef to an APar in the DataSet.

Result:

An empty string on success or an error message on failure.

new

Initializes a new parameter instance with values from the table. The table must have the following format:

$table[0]	asegposref ; channel
$table[1]	method ; framelength ; frameshift ; framecount ; methodparam
$table[2]	axes order ; unit [ref] ; datavalue|datatable [datafield]
$table[3]	....

Usage:

inst new table

Parameters:

table

The parameter table.

Result:

An empty string on success and an error message on failure.

save

Save local APar file in the DataSet. If a table is specified a new parameter is created by calling the function NEW table.

Usage:

inst save [ replace table edit save ]

Parameters:

replace

1 if the existing parameter should be replace, 0 otherwise.

table

The parameter table to save. See the member function new for details.

edit

Set the edit attribute to 1 or 0.

save

Set the save attribute to 1 or 0.

Result:

An empty string on success or an error message on failure.

setXData

Set the x scale data.

Usage:

inst setXData order ; unit [ uref ]

Parameters:

order

The x-scale order (1|2).

unit

The x-scale unit.

uref

The unit reference value.

Result:

An empty string on success or an error message on failure.

setYData

Set the y scale data.

Usage:

inst setYData order ; unit [ uref ] ; table [ field ]

inst setYData order ; unit [ uref ] ; value

Parameters:

order

The y-scale order (>=1) or order range.

unit

The y-scale unit.

uref

The unit reference value.

table

The data table containing values to set (one value per order).

field

The first table field containing Y vectors.

value

The value to set the y data to or a range of values if an order range was specified.

Result:

An empty string on success or an error message on failure.

getXScale

The definitions of the independent scale x with the specified order.

Usage:

inst getXScale [ order]

Parameters:

order

The order (1 ... ny). The default order is 1.

Result:

'domain ; unit ; uref' or an empty string.

getYScale

The definitions of the independent scale y with the specified order.

Usage:

inst getYScale [ order]

Parameters:

order

The order (1 ... ny). The default order is 1.

Result:

'domain ; unit ; uref' or an empty string.