Programmer Guide/Macro Library/CTemplates: Difference between revisions

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>

Programmer Guide/Macro Library/CTemplates: Difference between revisions

Latest revision as of 08:06, 6 April 2018

Contents

Create Instance

Delete Instance

GetTable

GetList

GetAttributeList

GetValueListForAttribute

GetDefaultValueForAttribute

GetFlags

CheckFlag

Manage

GetVars

Example

Navigation menu

Page actions

Page actions

Personal tools

Navigation

Search

Tools

@@ 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 S_TOOLS-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 S_TOOLS-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 S_TOOLS-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 S_TOOLS-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 S_TOOLS-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 S_TOOLS-STx INI file.
-=====Result:=====
-An empty string.
-===Remove===
-Remove an existing segment template from the current S_TOOLS-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 S_TOOLS-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 S_TOOLS-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 S_TOOLS-STx INI file.