Documented field and value types

git-svn-id: svn://svn.code.sf.net/p/magicseteditor/code/trunk@596 0fc631ac-6414-0410-93d0-97cfa31319b6

doc/type/choice.txt

@@ -0,0 +1,43 @@
+Data type: choice for a choice field
+
+A possible choice for a choice [[type:field]].
+
+--Properties--
+! Property		Type			Default		Description
+| @name@		[[type:string]]		''Required''	Name of this choice, displayed in the drop down list.
+| @line below@		[[type:boolean]]	@false@		Display a line below this item?
+| @group choice@	[[type:string]]		''no''		Can this submenu of choices itself be selected?
+| @choices@		[[type:list]] of [[type:choice]]s	 	Submenu of choices.
+| @enabled@		[[type:scriptable]] [[type:boolean]]	 	Is this choice selectable?
+| @type@		@"check"@ or @"radio"@	@"check"@	How should this choice be displayed? As a checkbox or a radio box?<br/>
+			 			 		Only applies to multiple choice fields.
+
+A choice can also be given in a short form, in that case only the name is specified.
+
+--Names--
+
+The full name of a choice is that of the choice and its parents, separated by spaces.
+This is the value actually stored in values and manipulated by scripts.
+
+For example
+>field:
+>	type: choice
+>	choice:
+>		name: large
+>		choice: red
+>		choice: blue
+>	choice:
+>		name: small
+>		group choice: just small
+>		choice: green
+>		choice: yellow
+
+The choice red is called @"large red"@, while green is @"small green"@.
+The group choice 'just small' gets the name of the group, @"small"@.
+
+--Example--
+In short form:
+>choice: apples
+Is the same as:
+>choice:
+>	name: apples

doc/type/color_choice.txt

@@ -0,0 +1,13 @@
+Data type: choice for a color field
+
+A possible choice for a color [[type:field]].
+
+--Properties--
+! Property	Type		Description
+| @name@	[[type:string]]	Name of this choice, displayed in the drop down list.
+| @color@	[[type:color]]	Color this choice corresponds with.
+
+--Example--
+>choice:
+>	name: red
+>	color: rgb(255,0,0)

doc/type/export_template.txt

@@ -0,0 +1,51 @@
+File type: Export template
+
+--Overview--
+
+An export template describes a way for a set to be exported to a HTML or other text files.
+
+--Package format--
+An export template is described in a [[file:package]] with the <tt>.mse-export-template</tt> file extension.
+Its name should begin with <tt><i>game</i>-</tt> where <i>game</i> is the name of the game the template is made for.
+It should contain a [[file:format|data file]] called <tt>export-template</tt> with the following properties.
+
+--Properties--
+! Property		Type			Default	Description
+| '''Common to all packages'''	<<<	<<<	<<<
+| @mse version@		[[type:version]]	''required''	Version of MSE this export template is made for.
+| @short name@		[[type:string]]		file name	A short name of this export template, for the 'new set' and style panel lists.
+| @full name@		[[type:string]]		file name	A longer name of this export template.
+| @icon@		[[type:filename]]	''none''	Filename of an icon / preview for this export template, for the 'export to HTML' dialog.
+| @position hint@	[[type:int]]		&infin;		Where to place this item in the list? Lower numbers come first.
+| @version@		[[type:version]]	@0.0.0@		Version number of this package.
+| @depends on@		[[type:list]] of [[type:dependency]]s
+			 			 		Packages this package depends on.
+	
+| '''Specific to export template'''		<<<	<<<	<<<
+| @game@		Name of a [[type:game]]	''required''	Game this export template is made for
+| @file type@		[[type:string]]		@"HTML files (*.html)|*.html"@
+			 			 		File type to use, this is a list separated by @|@ characters.
+			 			 		Alternatingly, a human description and a file pattern to match are given.
+| @create directory@	[[type:boolean]]	@false@		Should a directory for data files be created? This is required for some script function.
+| @option fields@	[[type:list]] of [[type:field]]s	 	Fields for additional options to show.
+| @option style@	[[type:indexmap]] of [[type:style]]s	 	Styling for the @option fields@.
+| @script@		[[type:script]]		 		Script that generates the text that will be written to the exported file.
+
+During the evaluation of the script the following variables are available:
+| @game@	The current game.
+| @style@	The current stylesheet.
+| @set@		The set being exported.
+| @options@	The values of the @option fields@.
+| @directory@	Name of the directory created (if @create directory@ is set).
+
+--See also--
+The following functions are made specifically for exporting to html:
+| [[fun:to_html]]		Convert [[type:tagged text]] to html.
+| [[fun:symbols_to_html]]	Convert text to html using a [[type:symbol font]].
+| [[fun:to_text]]		Remove all tags from tagged text.
+| [[fun:copy_file]]		Copy a file from the [[type:export template]] to the output directory.
+| [[fun:write_text_file]]	Write a text file to the output directory.
+| [[fun:write_image_file]]	Write an image file to the output directory.
+
+--Example--
+Look at the @"magic-spoiler.mse-export-template"@ for an example.

doc/type/field.txt

@@ -0,0 +1,114 @@
+Data type: field
+
+--Overview--
+
+A field is a description of a kind of 'container' to hold a value.
+
+For example the [[type:value]] of a 'text field' is a piece of text, that of a 'color field' a [[type:color]], etc.
+
+Things that are fields are, "card color" and "card name".
+Not a particular color or name, but a description of what a card color and a card name are for a particular [[type:game]].
+
+Fields are part of the [[file:style triangle]]:
+| Description		Looks			Data
+| [[type:Game]]		[[type:Stylesheet]]	[[type:Set]]
+| '''Field'''		[[type:Style]]		[[type:Value]]
+
+--Properties--
+! Property		Type			Default		Description
+| @type@		One of:			''required''	Type of field.
+			* @text@
+			* @choice@
+			* @multiple choice@
+			* @boolean@
+			* @image@
+			* @symbol@
+			* @color@
+			* @info@
+| @name@		[[type:string]]		''required''	Name of the field.
+| @description@		[[type:string]]		@""@		Description of the field, shown in the status bar when the mouse is over the field.
+| @icon@		[[type:filename]]	 		Filename of an icon for this field, used for automatically generated [[type:statistics category]]s.
+| @editable@		[[type:boolean]]	@true@		Can values of this field be edited?
+| @save value@		[[type:boolean]]	@true@		Should values of this field be saved to files? Should be disabled for values that are generated by scripts.
+| @show statistics@	[[type:boolean]]	@true@		Should a [[type:statistics dimension]] and [[type:statistics category|category]] be made for this field,
+			 			 		causing it to be listed on the statistics panel?
+| @identifying@		[[type:boolean]]	@false@		Does this field give the name of the [[type:card]] or [[type:set]]?
+| @card list column@	[[type:int]]		@0@		On what position in the card list should this field be put?
+| @card list width@	[[type:int]]		@100@		Width of the card list column in pixels.
+| @card list visible@	[[type:boolean]]	@false@		Should this field be shown in the card list by default?
+| @card list allow@	[[type:boolean]]	@true@		Should this field be allowed in the card list at all?
+| @card list name@	[[type:string]]		field name	Alternate name to use for the card list, for example an abbreviation.
+| @card list alignment@	[[type:alignment]]	@left@		Alignment of the card list column.
+| @sort script@		[[type:script]]				Alternate way to sort the card list when using this column to sort the list.
+| @tab index@		[[type:int]]		@0@		Index for moving through the fields with the tab key. The default is from left to right and then top to bottom.
+
+The @type@ determines what values of this field contain:
+! Type			Values contain
+| @text@		Text with markup (a [[type:tagged string]])
+| @choice@		A choice from a list
+| @multiple choice@	Zero or more choices from a list
+| @boolean@		@yes@ or @no@
+| @image@		Any image
+| @symbol@		A [[type:symbol]] edited with the symbol editor
+| @info@		An informational message, for example to group fields together.
+
+Additional properties are available, depending on the type of field:
+
+! Type		Property	Type		Default		Description
+| @"text"@	@script@	[[type:script]]		 	Script to apply to values of this field after each change.
+| ^^^		@default@	[[type:script]]		 	Script to determine the value when it is in the default state (not edited).
+| ^^^		@default name@	[[type:string]]	@"Default"@	Name of the default state, currently not used.
+| ^^^		@multi line@	[[type:boolean]]	@false@	Can values of this field contain line breaks?
+	
+| @"choice"@	@script@	[[type:script]]		 	Script to apply to values of this field after each change.
+| ^^^		@default@	[[type:script]]		 	Script to determine the value when it is in the default state (not edited).
+| ^^^		@initial@	[[type:string]]		 	Initial value for new values for this field.
+| ^^^		@default name@	[[type:string]]	@"Default"@	Name of the default state.
+| ^^^		@choices@	[[type:list]] of [[type:choice]]s	 	Possible values for this field.
+	
+| @"multiple choice"@	 	<<<	<<<	<<<
+		'' Multiple choice fields have the same attributes as normal choice fields.''<br/>
+		To refer to a combination of values in the initial attribute use @choice1, choice2, choice3@.<br/>
+		These choices must apear in the same order as they do in the @choices@ property.
+	
+| @"boolean"@	''A boolean field is a choice field with the choices @"yes"@ and @"no"@.''	<<<	<<<	<<<
+	
+| @"color"@	@script@	[[type:script]]		 	Script to apply to values of this field after each change.
+| ^^^		@default@	[[type:script]]		 	Script to determine the value when it is in the default state (not edited).
+| ^^^		@initial@	[[type:string]]		 	Initial color for new values for this field.
+| ^^^		@default name@	[[type:string]]	@"Default"@	Name of the default state.
+| ^^^		@allow custom@	[[type:boolean]]	@true@	Are colors other then those from the choices allowed?
+| ^^^		@choices@	[[type:list]] of [[type:color choice]]s	 	Possible values for this field.
+	
+| @"image"@	''no extra properties''	<<<	<<<	<<<
+	
+| @"symbol"@	''no extra properties''	<<<	<<<	<<<
+	
+| @"info"@	@script@	[[type:script]]		 	Script to determine the value to show.
+
+--Example--
+The @title@ field gives the title of a set:
+>set field:
+>	type: text
+>	name: title
+>	identifying: true
+
+The border color of cards can be selected from a list of choices, but other values are also possible.
+The default is based on a set field. Statistics don't make much sense for the border color.
+>card field:
+>	type: color
+>	name: border color
+>	default: set.border_color
+>	choice:
+>		name: black
+>		color: rgb(0,0,0)
+>	choice:
+>		name: white
+>		color: rgb(255,255,255)
+>	choice:
+>		name: silver
+>		color: rgb(128,128,128)
+>	choice:
+>		name: gold
+>		color: rgb(200,180,0)
+>	show statistics: false

doc/type/index.txt

@@ -36,7 +36,7 @@ These contain several properties, similair to the file types. But they are part
 			* item
 			* item
 			* item
-| [[type:indexmap|'index' map]]	Lists indexed by field name
+| [[type:indexmap]]	Lists indexed by field name
 			<table><tr><td>name:</td><td>someone</td></tr>
 			<tr><td>type:</td><td>something</td></tr></table>
 | [[type:map]]		Lists indexed by other text

doc/type/indexmap.txt

@@ -0,0 +1,33 @@
+Collection type: field map
+
+--Overview--
+
+A 'field map' is a [[type:map]], but indexed by [[type:field]]s.
+
+For instance if a game specifies the fields:
+>field:
+>	type: text
+>	name: field1
+>field:
+>	type: color
+>	name: field2
+
+Then the a field map of ''things'' for those fields would look like:
+>field1: thing
+>field2: thing
+
+A field map of [[type:style]]s would be:
+>field1: # some text style for field1 goes here
+>field2: # some color style for field2 goes here
+
+And a field map of [[type:value]]s would be:
+>field1: text goes here
+>field2: rgb(1,2,3)
+
+--Script syntax--
+
+In a script field maps can be accessed like normal [[type:map]]s based on the field name.
+So:
+>card.field1 # retrieve the value of field1
+>card["field" + 1] # the same thing
+>card_style.field2 # retrieve the styling for field2

doc/type/list.txt

@@ -1,14 +1,14 @@
-Data type: Lists
+Collection type: List
 
 --File syntax--
 In files a list is represented as multiple keys, one for each element.
 The keys are all in the singular for of the name of the list,
 if the list is named for instance @symbols@ each key will be named @symbol@.
-] symbol:
+>symbol:
-]	# first symbol here
+>	# first symbol here
-] symbol:
+>symbol:
-]	# second symbol here
+>	# second symbol here
-] # etc.
+># etc.
 
 --Script syntax--
 In a script lists can be declared using square brackets.
@@ -18,12 +18,18 @@ In a script lists can be declared using square brackets.
 
 Lists can be accessed using either the bracket operator, or the dot operator.
 The first element of a list is numbered 0, the next 1, etc.
-> list.0  # The first element of the list 'list'
+> list.0    # The first element of the list 'list'
-> list[0] # The same thing
+> list[0]   # The same thing
+> list[0+0] # The same thing
+
+It is possible to iterate over lists using the @for@ construct:
+> for x in [1,2,3] do "x = {x}. "
+evaluates to:
+> "x = 1. x = 2. x = 3. "
 
 --Functions--
 There are several functions for working with lists:
 | [[fun:position]]		Find the position of an element in a list
-| [[fun:number_of_items]]	Find the number of items in a list
+| [[fun:number_of_items]]	Return the number of items in a list
 | [[fun:sort_list]]		Sort a list
 | [[fun:filter_list]]		Filter a list, keeping only elements that match a predicate

doc/type/map.txt

@@ -0,0 +1,26 @@
+Collection type: Map
+
+A map is like a [[type:list]] with [[type:string]] keys.
+
+--File syntax--
+In files a map is represented as key/value pairs.
+For instance a map of [[type:color]]s could be:
+>some map:
+>	red:   rgb(255,0,0)
+>	green: rgb(0,255,0)
+>	blue:  rgb(0,0,255)
+
+--Script syntax--
+In a script maps can be declared using square brackets.
+> []      # An empty map
+> [key:1] # A map with a single element, the value 1 under the key "key"
+> [red:rgb(255,0,0), green:rgb(0,255,0)] # A map with two elements
+
+Like lists, maps can be accessed using either the bracket operator, or the dot operator.
+> map.key       # The elment named "key"
+> map["k"+"ey"] # The same thing
+
+It is possible to iterate over the values maps using the @for@ construct:
+> for x in [one: 1, two: 2] do "x = {x}. "
+evaluates to:
+> "x = 1. x = 2. "

doc/type/regex.txt

@@ -1,2 +1,10 @@
 Primitive type: regular expression
 
+Regular expressions (regexes) are things that can match parts of [[type:string]]s.
+
+Regexes are represented by normal [[type:string]]s.
+Note that to escape something in a regex the backslash is used, in script code this also needs to be escaped.
+For example, in a script, the regex matching a single backslash is @"\\\\"@.
+
+For more information, see
+[[http://www.wxwidgets.org/manuals/stable/wx_wxresyn.html|the wxWidgets regular expression documentation]].

doc/type/settings.txt

@@ -0,0 +1,13 @@
+File type: Settings
+
+--Overview--
+
+The MSE settings are stored in a separate file.
+
+--Location--
+
+On Windows XP the settings are located in:
+> "C:\Documents and Settings\Application Data\Magic Set Editor\mse8.config"
+
+--Properties--
+See the settings file for the properties.

doc/type/stylesheet.txt

@@ -1,4 +1,4 @@
-Object type: Stylesheet
+File type: Stylesheet
 
 --Overview--
 

doc/type/value.txt

@@ -1 +1,36 @@
-== Object type: Field value ==
+Data type: Field value
+
+--Overview--
+
+A value is something that is 'stored in' a [[type:field]].
+
+Values are part of the [[file:style triangle]]:
+| Description		Looks			Data
+| [[type:Game]]		[[type:Stylesheet]]	[[type:Set]]
+| [[type:Field]]	[[type:Style]]		'''Value'''
+
+--Possible types--
+
+The type of a value depends on the corresponding field:
+! Field type		Value data type			Description
+| @"text"@		[[type:tagged string]]		A piece of text, possibly with markup.
+| @"choice"@		[[type:string]]			One of the choices of the field.
+| @"multiple choice"@	[[type:string]]			A list of choices from the field, separated by commas.<br/>
+			 				For example: @"red, green, blue"@.
+| @"boolean"@		@"yes"@ or @"no"@		This can be directly used as a [[type:boolean]] value in scripts.
+| @"image"@		[[type:filename]]		Filename of an image file in the [[type:set]] package.
+| @"symbol"@		[[type:filename]]		Filename of a [[type:symbol]] file in the [[type:set]] package.<br/>
+			 				When accessed from a script, image fields can be directly used as [[type:image]]s.
+| @"color"@		[[type:color]]			A color.
+| @"info"@		[[type:string]]			A label for the information box.
+
+--Example--
+For the field:
+>field:
+>	type: choice
+>	name: card color
+>	choice: red
+>	choice: green
+>	choice: blue
+A value could be:
+>card color: red