more updates to glyph and config

doc/Design_notes/index.html

+<!-- $Id: -->
 
 <h2>ZMap Design Documentation</h2>
 

doc/Design_notes/modules/zmapConfig.html

-<!-- $Id: zmapConfig.html,v 1.5 2010-03-19 16:26:47 mh17 Exp $ -->
+<!-- $Id: zmapConfig.html,v 1.6 2010-04-19 11:01:43 mh17 Exp $ -->
 <h2> zmapConfig - configuration file handler </h2>
 <fieldset> <legend>Summary</legend>
 <p>This page refers to the zmapConfig directory as of 09 Dec 2009.</p>
@@ -125,7 +125,22 @@ External (ie visible from outside) to the zmapConfig module there is a <b>ZMapCo
 <h3>Default values</h3>
 <p>The GLib code does not deal with default values itself, but it is possible to supply GLib with an initialised stanza struct - for an example look at <b>zmapConfigLoader.c/create_config_style()</b> which uses an array of <b>ZMapKeyValueStruct</b>, defined in <b>zmapConfigStanzaStructs.h</b>.  This gets passed to <b>zmapConfigLoader.c/fetch_referenced_stanzas()</b> via <b>zMapConfigIniContextGetReferencedStanzas()</b>, which calls <b>fill_stanza_key_value()</b> which has the chance to fill in default values but does not.  This is probably because we wish to have Styles data flagged as set or not-set.  This could be changed to allow defaults to be set on other kinds of stanza.
 </p>
-
+<h3>Adding new options</h3>
+<p>
+If it's a new style option you have to do a bit more than a simple config thingy.
+<ul>
+<li>Add a new string for the option in zmapStyle.h or zmapConfigStrings.h
+<li>If there is a list of explicit options add this following the examples eg in zmapStyle.h
+<li>Add some macros eg as in zmapStyleUtils.h and some prototypes for the functions defined in zmapStyle.h
+<li>Add some macros in zmapStyle.h
+<li>Add the new option to <i>two</i> tables in zmapConfigLoader.c for the relevant stanza
+<li>Edit the stanza update function in zmapConfigLoader.c to handle your new option
+<li>Add a new style property in zmapStyle.h
+<li>Add a new type (eg for enums) in zmapStyle_I.h and follow the instructions in the comment in the code
+<li>Add some structure member to hold the data in zmapStyle_I.h
+<li>Add a new item in the parameter table in zmapStyle.c
+</ul>
+</p>
 
 </fieldset>
 

doc/Design_notes/notes/glyph_style.html

-<!-- $Id: glyph_style.html,v 1.4 2010-04-15 10:44:49 mh17 Exp $ -->
+<!-- $Id: glyph_style.html,v 1.5 2010-04-19 11:01:43 mh17 Exp $ -->
 <h2>Style definitions for Glyphs</h2>
 <fieldset><legend>Summarised</legend>
 <p>
@@ -46,14 +46,16 @@ glyph-5 = shape               # shape to draw (top end)
 
 glyph-score-mode = width height size # change size according to score
 
-glyph-score-mode = alt               # change colour according to threshold
+glyph-score-mode = alt        # change colour according to threshold
 glyph-threshold = X
 
-glyph-strand = flip-x flip-y         # invert if on reverse strand
+glyph-strand = flip-x flip-y  # invert if on reverse strand
 
-glyph-align = left centre right      # (defaults to centre)
+glyph-align = left right      # (defaults to centre if not specified)
+                              # style width must be set
+                              # see 'Aligning Glyphs' below for some useful comments
 
-glyph-colours = pink                 # for sub feature glyphs
+glyph-colours = pink          # for sub feature glyphs
 glyph-alt-colours = turquoise
 </pre>
 
@@ -199,6 +201,18 @@ maximum size and when 'glyph-score-mode' is set as width or height then the
 pixel coordinates will be adjusted accordingly.</p>
 <p>A glyph that scores less than the minimum will not be displayed and a glyph exceeding the maximum will be displayed as for max-score. 'min-score' will likely be one pixel across.</p>
 
+<h3>Aligning Glyphs</h3>
+<p>It's a simple concept but there are a few nuances to consider.
+<ul>
+<li>If not specified, a glyph will be aligned to the centre of its column or feature.
+<li>If aligned to the left or right of the column then the style must specify the width
+<li>If aligned to the left then the glyph shape must consist of points with +ve x coordinates
+<li>If aligned to the right the glyph shape must consist of points with -ve x coordinates
+<li>If you used glyph-strand=flip-x then it's best not to use alignment and stick with the centre
+<li>Glyphs not conforming to the above may be painted, but may look a bit messy, especially if score-mode=width is used
+</ul>
+</p>
+
 </fieldset>
 
 <a name="impl"></a>

doc/user_doc/configuration.html

@@ -2,7 +2,7 @@
 <!--#include virtual="/perl/header"-->
 
 <!--#set var="author" value="edgrif@sanger.ac.uk" -->
-<!-- $Id: configuration.html,v 1.2 2010-03-19 16:26:47 mh17 Exp $ -->
+<!-- $Id: configuration.html,v 1.3 2010-04-19 11:01:43 mh17 Exp $ -->
 <style>
 pre{ width: 95%; background-color: #DDDDDD; border-style: solid; border-width: 1px; padding: 10px }
 .example{ border-color: #000000 }
@@ -298,7 +298,9 @@ read if a file has been specified in the [ZMap] stanza, otherwise the
 source should provide the styles itself. By default a featureset will
 use a style of the same name.<p>
 </p></td></tr>
-</tbody></table>
+<tr>
+<th>"stylesfile" </th><td>string </td><td>"" </td><td>If specified the source will read styles data from this file. This is mandatory for pipe and file Servers, and optional for database (eg ACEDB or DAS).  If not specified the Server must supply its own styles.<p>
+</p></td></tr></tbody></table>
 </fieldset>
 
 <a  name="featuresets"></a>
@@ -307,7 +309,7 @@ use a style of the same name.<p>
 <p>By default, any feature requested from a pipe or other server that does not support the REQ_FEATURESETS request will be mapped to
 a column of the same name - this will produce a wider than normal display, but the data will at least be visible.</p>
 <p>
-The stanza [featuresets] may be used to override this default mapping and will contain lines of the form:
+The stanza <b>[featuresets]</b> may be used to override this default mapping and will contain lines of the form:
 <pre>
 column = source1; source2; ... sourceN
 </pre>
@@ -318,7 +320,7 @@ where 'column' is the name of the column that is used to display all the sources
 
 <a name="style"></a>
 <fieldset><legend>Style Options</legend>
-<p>NB: this stanza appears in a separate config file specified in [ZMap] stylesfile=xxx.  Available options are given <a href="user_doc/styles.shtml">here</a>.</p>
+<p>NB: these stanzas appear in a separate config file specified in [ZMap] stylesfile=xxx.  Available options are given <a href="user_doc/styles.shtml">here</a>.  Each style is specified in a stanza of the same name as the style.</p>
 </p>
 </fieldset>