Programmer Guide/Macro Library/CTemplates: Difference between revisions

From STX Wiki
Jump to navigationJump to search
No edit summary
 
(11 intermediate revisions by 2 users not shown)
Line 1: Line 1:
{{DISPLAYTITLE:{{SUBPAGENAME}}}}
{{DISPLAYTITLE:{{SUBPAGENAME}} - Template Management}}
==CASegTemplate : CObj==
[[Category:Templates]]
:'''File''': Classes.STX, linked to library STX.LIB
:'''Parent class''': [[Programmer Guide/Macro Library/COBJ|CObj]]


A class to manage segment templates (<code>ASegTemplate</code>)<code><code>.</code></code>
A class to manage templates. In {{STx}} templates are used to define attributes for specific data types. The most important data type using a template is '''ASeg''', this is type of elements storing audio segment definitions. Templates of type '''ASegTemplate''' are used to define additional segment attributes for a specific application. Templates are also used to define the content variables and the layout of dialogs managed by the class [[Programmer_Guide/Macro_Library/ModalDialog|ModalDialog]]. The available templates are stored as xml-files in the subdirectory '''templates''' of the {{STx}} installation directory. To ''install'' it is only necessary to copy the xml-file containing the definitions into this directory. The template name (id) is the name of the xml-file and the type is the tag of the root element of the file (see section [[#Example|Example]]).


You can retrieve a list of templates available in the {{STX}} INI file. You can display a dialog offering the user the option of importing from or exporting templates to disk. You can delete templates from the {{STX}} INI file.


====CASegTemplate construction====
==Create Instance==
;Usage:
:<code>ctemplates [ <var>type</var> ]</code>
:<code>cobj new ctemplates [ <var>type</var> ]</code>
:;<var>type</var>: selects the type of templates to be managed (default: '''ASegTemplate''')
;Result: an initialized instance


The <code>CASegTemplate</code> constructor takes no parameters but still needs to be called.
==Delete Instance==
;Usage: <code><var>instance</var> destroy</code>
;Result: none (void)


====CASegTemplate Member Functions====
==GetTable==
;Usage: <code><var>instance</var> gettable</code>
;Result: an extended table containing the id's of the available templates of the selected type (one per entry, field '''id''')


The <code>CASegTemplate</code> class has the following member functions. See CObj Member Functions for a list of functions implemented in the parent class.
==GetList==
;Usage: <code><var>instance</var> getlist</code>
;Result: a semi-colon separated list of the id's of the available templates of the selected type


===List===
==GetAttributeList==
;Usage: <code><var>instance</var> getattributelist <var>id</var></code>
:;<var>id</var>: the id of the template
;Result: an blank separated list of attributes defined in the selected template


List the available templates in either a table or a semi-colon separated list.
==GetValueListForAttribute==
;Usage: <code><var>instance</var> getvaluelistforattribute <var>type ; id ; attr</var></code>
:;<var>type</var>: selects type of result
::'''table''': return a simple table containing on value per line; the default value is stored in the first line
::'''list''': return a blank separated list of values
:;<var>id</var>: the id of the template
:;<var>attr</var>: the name of the attribute
;Result: an blank separated list of defined values or a simple table containing one value per line (see argument <var>type</var>)


=====Usage:=====
==GetDefaultValueForAttribute==
;Usage: <code><var>instance</var> getdefaultvalueforattribute <var>id ; attr</var></code>
:;<var>id</var>: the id of the template
:;<var>attr</var>: the name of the attribute
;Result: the default value


<code><var>inst</var> List [ <var>rType</var> ]</code>
==GetFlags==
;Usage: <code><var>instance</var> getflags <var>id ; attr</var></code>
:;<var>id</var>: the id of the template
:;<var>attr</var>: the name of the attribute
;Result: get the dialog flags defined for the attribute


=====Parameters:=====
==CheckFlag==
;Usage: <code><var>instance</var> checkflag <var>id ; attr ; flag</var></code>
:;<var>id</var>: the id of the template
:;<var>attr</var>: the name of the attribute
:;<var>flag</var>: the flag to be tested
;Result: '''1''' if the flag is set, '''0''' otherwise


;<var>rType</var>
==Manage==
;Usage: <code><var>instance</var> manage</code>
;Result: none (void)
;Description: Display the template management dialog. This dialog implements functions to view, edit (using a text editor), rename and delete templates.


:The type of list to return. Possible values are:
==GetVars==
;Usage: <code><var>instance</var> getvars <var>id</var></code>
:;<var>id</var>: the id of the template
;Result: An extended table contains all definitions of all variables of the selected template. The returns table has the string fields '''Type''', '''Name''', '''Default''', '''Values''' and '''Flags'''.


:<code>table</code> - Return a simple table.
==Example==
This is an example of a template file. This example contains the defintions of the default audio segment template (id: '''DefaultASegTemplate''', type: '''ASegTemplate''').


:<code>list</code> - Return a semi-colon separated list.
<pre>
<?xml version="1.0" encoding="UTF-8"?>
<!--


=====Result:=====
Templates
=========


Depending on <var>rType</var>, a table or a list containing the ids of the segment templates in the current {{STX}} INI file.
(1) Each xml-file in the template directory contains one template. The template type is the defined
by the root element tag of the xml-file. The name of the template is the name of the xml-file
without the extension.
<DialogTemplate> general dialog templates
<ASegTemplate> segment attributes dialog template (used by Viewer1/2 and segment Edit dialoges)
<attrTemplate> set attributes dialog template


===Reload===
(2) The element inside the xml-file defines the properties of the template. Currently following elements are
defined:


Reload the list of templates from the {{STX}} INI file.
<Control    Type="controltype" Name="variablename" Text="controlcaption" Window="row col width height"
Default="defaultvalue" Values="value1 value2 ..." Flags="controloptions"/>
...


=====Usage:=====
controltype    Static, CheckBox, Edit, ComboBox
variablename    Name of variable bound to the control. For segment-dialogs (ASeg) this name is
also used as segment attribute name. This attribute is not used for controls of
type Static and is required for all other control types.
controlcaption  Caption of the control. If not specified, no caption is displayed.
row, col        Position of upper left corner.
width, height  Width and height of control.
defaultvalue    Default value for the control variable.
CheckBox        0 or 1
Edit            any text
ComboBox        a value from the valuelist
valueX          list of choices for controls of type ComboBox
controloptions  List of options to configure the control.
Static      /L|/R|/C        align text left|right|centered
Edit        /I|/N          input must be an integer (/I) or float (/N) number
/L|/R|/A        show caption on left|right (/L|/R) side or above (/A)
/M              multi-line edit box
            /U if editable in an editable table, use the most recently
        entered value as a default
ComboBox    /L|/R|/A        show caption on left|right (/L|/R) side or above (/A)
            /E combobox is editable
            /U if editable in an editable table, use the most recently
        entered value as a default
all types:  /W=xywh        Controls the change of x/y-pos and width/height of the
control if the dialog window is resized.
*      no change
a      automatic
h      half
f      full
e.g.: /W=**f*  only the width is changed (full)


<code><var>inst</var> Reload</code>


=====Result:=====
-->
<ASegTemplate>
<Control Type="Static" Text="Type" Window="0  0  4 1" Flags="/R"/>
<Control Type="ComboBox" Name="Type" Window="0  4  9 1" Flags="/E/U" Default="uncl" Values="uttr phon word syll uncl"/>
<Control Type="Static" Text="Speaker" Window="1  0  7 1" Flags="/R"/>
<Control Type="ComboBox" Name="Spk" Window="1  7  6 1" Flags="/E/U" Default="f1" Values="m1 m2 m3 f1 f2 f3 uncl"/>
<Control Type="Static" Text="Anonymize" Window="2  0  7 1" Flags="/R"/>
<Control Type="ComboBox" Name="Anonymize" Window="2  7  6 1" Flags="/E/U" Default="no" Values="no yes"/>
<Control Type="Static" Text="TR1" Window="2 13  3 1" Flags="/R"/>
<Control Type="Edit" Name="TR1" Window="2 16 37 3" Flags="/M/W=**ff" Font="Userfont"/>
<Control Type="Static" Text="TR2" Window="1 13  3 1" Flags="/R"/>
<Control Type="Edit" Name="TR2" Window="1 16 37 1" Flags="/W=**f*" Font="Userfont"/>
<Control Type="Static" Text="TR3" Window="0 13  3 1" Flags="/R"/>
<Control Type="Edit" Name="TR3" Window="0 16 37 1" Flags="/W=**f*" Font="Userfont"/>
</ASegTemplate>


An empty string.
</pre>
 
===Manage===
 
Show user a dialog asking user to select segment templates to import, export, delete or reload from file.
 
=====Usage:=====
 
<code><var>inst</var> Manage</code>
 
=====Result:=====
 
An empty string.
 
===Import===
 
Import a segment template from disk into the {{STX}} INI file. If no template path is specified, the user is asked to select one from disk.
 
=====Usage:=====
 
<code><var>inst</var> Import [ <var>path</var> ] [ ; <var>confirmReplace</var>=1 ]</code>
 
=====Parameters:=====
 
;<var>path</var>
 
:The path to the segment template to import. If this parameter is not specified, the user is asked to select a template from disk.
 
;<var>confirmReplace</var>
 
:<code>1</code> if the user should be prompted when replacing existing templates. <code>0</code> otherwise. The default is <code>1</code>.
 
Result:
 
The id of the valid segment template or an empty string
 
===Export===
 
Export an existing ASegTemplate to disk.
 
=====Usage:=====
 
<code><var>inst</var> Export <var>asegtemplate</var></code>
 
;<var>asegtemplate</var>
 
:The id of a segment template currently in the {{STX}} INI file.
 
=====Result:=====
 
An empty string.
 
===Remove===
 
Remove an existing segment template from the current {{STX}} INI file.
 
=====Usage:=====
 
<code><var>inst</var> Remove <var>asegtemplate</var></code>
 
;<var>asegtemplate</var>
 
:The id of a segment template currently in the {{STX}} INI file.
 
=====Result:=====
 
An empty string.
 
===ReloadFromFile===
 
Reload an existing segment template from file.
 
=====Usage:=====
 
<code><var>inst</var> Reload <var>asegtemplate</var></code>
 
;<var>asegtemplate</var>
 
:The id of a segment template currently in the {{STX}} INI file.
 
=====Result:=====
 
An empty string.
 
===ViewTemplate===
 
Display a dialog based on a segment template.
 
=====Usage:=====
 
<code><var>inst</var> ViewTemplate <var>asegtemplate</var></code>
 
=====Parameters:=====
 
;<var>asegtemplate</var>
 
:The id of a segment template currently in the {{STX}} INI file.

Latest revision as of 08:06, 6 April 2018

File: Classes.STX, linked to library STX.LIB
Parent class: CObj

A class to manage templates. In STx templates are used to define attributes for specific data types. The most important data type using a template is ASeg, this is type of elements storing audio segment definitions. Templates of type ASegTemplate are used to define additional segment attributes for a specific application. Templates are also used to define the content variables and the layout of dialogs managed by the class ModalDialog. The available templates are stored as xml-files in the subdirectory templates of the STx installation directory. To install it is only necessary to copy the xml-file containing the definitions into this directory. The template name (id) is the name of the xml-file and the type is the tag of the root element of the file (see section Example).


Create Instance

Usage
ctemplates [ type ]
cobj new ctemplates [ type ]
type
selects the type of templates to be managed (default: ASegTemplate)
Result
an initialized instance

Delete Instance

Usage
instance destroy
Result
none (void)

GetTable

Usage
instance gettable
Result
an extended table containing the id's of the available templates of the selected type (one per entry, field id)

GetList

Usage
instance getlist
Result
a semi-colon separated list of the id's of the available templates of the selected type

GetAttributeList

Usage
instance getattributelist id
id
the id of the template
Result
an blank separated list of attributes defined in the selected template

GetValueListForAttribute

Usage
instance getvaluelistforattribute type ; id ; attr
type
selects type of result
table: return a simple table containing on value per line; the default value is stored in the first line
list: return a blank separated list of values
id
the id of the template
attr
the name of the attribute
Result
an blank separated list of defined values or a simple table containing one value per line (see argument type)

GetDefaultValueForAttribute

Usage
instance getdefaultvalueforattribute id ; attr
id
the id of the template
attr
the name of the attribute
Result
the default value

GetFlags

Usage
instance getflags id ; attr
id
the id of the template
attr
the name of the attribute
Result
get the dialog flags defined for the attribute

CheckFlag

Usage
instance checkflag id ; attr ; flag
id
the id of the template
attr
the name of the attribute
flag
the flag to be tested
Result
1 if the flag is set, 0 otherwise

Manage

Usage
instance manage
Result
none (void)
Description
Display the template management dialog. This dialog implements functions to view, edit (using a text editor), rename and delete templates.

GetVars

Usage
instance getvars id
id
the id of the template
Result
An extended table contains all definitions of all variables of the selected template. The returns table has the string fields Type, Name, Default, Values and Flags.

Example

This is an example of a template file. This example contains the defintions of the default audio segment template (id: DefaultASegTemplate, type: ASegTemplate). 

<?xml version="1.0" encoding="UTF-8"?>
<!--

	Templates
	=========

	(1) Each xml-file in the template directory contains one template. The template type is the defined
		by the root element tag of the xml-file. The name of the template is the name of the xml-file
		without the extension.
		
			<DialogTemplate>		general dialog templates
			<ASegTemplate>			segment attributes dialog template (used by Viewer1/2 and segment Edit dialoges)
			<attrTemplate>			set attributes dialog template

	(2)	The element inside the xml-file defines the properties of the template. Currently following elements are
		defined:

			<Control    Type="controltype" Name="variablename" Text="controlcaption" Window="row col width height"
						Default="defaultvalue" Values="value1 value2 ..." Flags="controloptions"/>
				...

				controltype     Static, CheckBox, Edit, ComboBox
				variablename    Name of variable bound to the control. For segment-dialogs (ASeg) this name is
								also used as segment attribute name. This attribute is not used for controls of
								type Static and is required for all other control types.
				controlcaption  Caption of the control. If not specified, no caption is displayed.
				row, col        Position of upper left corner.
				width, height   Width and height of control.
				defaultvalue    Default value for the control variable.
								CheckBox        0 or 1
								Edit            any text
								ComboBox        a value from the valuelist
				valueX          list of choices for controls of type ComboBox
				controloptions  List of options to configure the control.
								Static      /L|/R|/C        align text left|right|centered
								Edit        /I|/N           input must be an integer (/I) or float (/N) number
											/L|/R|/A        show caption on left|right (/L|/R) side or above (/A)
											/M              multi-line edit box
						        		    /U				if editable in an editable table, use the most recently
						        							entered value as a default
								ComboBox    /L|/R|/A        show caption on left|right (/L|/R) side or above (/A)
						        		    /E				combobox is editable
						        		    /U				if editable in an editable table, use the most recently
						        							entered value as a default
								all types:  /W=xywh         Controls the change of x/y-pos and width/height of the
															control if the dialog window is resized.
															*       no change
															a       automatic
															h       half
															f       full
															e.g.: /W=**f*   only the width is changed (full)


-->
<ASegTemplate>
	<Control Type="Static" Text="Type" Window="0  0  4 1" Flags="/R"/>
	<Control Type="ComboBox" Name="Type" Window="0  4  9 1" Flags="/E/U" Default="uncl" Values="uttr phon word syll uncl"/>
	<Control Type="Static" Text="Speaker" Window="1  0  7 1" Flags="/R"/>
	<Control Type="ComboBox" Name="Spk" Window="1  7  6 1" Flags="/E/U" Default="f1" Values="m1 m2 m3 f1 f2 f3 uncl"/>
	<Control Type="Static" Text="Anonymize" Window="2  0  7 1" Flags="/R"/>
	<Control Type="ComboBox" Name="Anonymize" Window="2  7  6 1" Flags="/E/U" Default="no" Values="no yes"/>
	<Control Type="Static" Text="TR1" Window="2 13  3 1" Flags="/R"/>
	<Control Type="Edit" Name="TR1" Window="2 16 37 3" Flags="/M/W=**ff" Font="Userfont"/>
	<Control Type="Static" Text="TR2" Window="1 13  3 1" Flags="/R"/>
	<Control Type="Edit" Name="TR2" Window="1 16 37 1" Flags="/W=**f*" Font="Userfont"/>
	<Control Type="Static" Text="TR3" Window="0 13  3 1" Flags="/R"/>
	<Control Type="Edit" Name="TR3" Window="0 16 37 1" Flags="/W=**f*" Font="Userfont"/>
</ASegTemplate>
Retrieved from "https://mediawiki.kfs.oeaw.ac.at/stx/docs/wiki/index.php?title=Programmer_Guide/Macro_Library/CTemplates&oldid=9971"

Navigation menu

Personal tools