home *** CD-ROM | disk | FTP | other *** search
/ Gold Fish 3 / goldfish_volume_3.bin / files / gfx / show / superview-lib / docs / svsupport-docs / cpinfoformat.doc < prev    next >
Encoding:
Text File  |  1995-05-28  |  7.7 KB  |  188 lines
  1.  
  2.   The ControlPadInfo-FileFormat V6.4 (30.4.95)
  3.   ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
  4.   Some applications might wish to enable the user to interactively
  5.   specify controlpad settings just when reading, writing or
  6.   processing an image and not before or after by setting preferences.
  7.  
  8.   Until this will be managed by superview.library, superviewsupport.library
  9.   or the single modules by introducing new functions for handling this,
  10.   applications may take this information from ".cpinfo" files, where
  11.   the specific ControlPad entries are dynamically described.
  12.  
  13.   Every CPInfo-File is constructed like an usual ControlPad file,
  14.   but in this case, the _order_ of the entries becomes meaningful.
  15.   These files are separated into SECTIONs, where any necessary
  16.   information about specific ControlPad entries are stored.
  17.  
  18.   To allow easy enhancements and improvments on this format, there's
  19.   an important note:
  20.  
  21.       - the number of sections is not limited
  22.       - each SECTION _must_ contain at least the entries described below
  23.       - each SECTION _may_ contain more entries, so that it might be
  24.         necessary to skip all the following entries until another "SECTION"
  25.         entry will be reached
  26.       - the order of the entries is _fixed_
  27.       - if any of the following _needed_ entries makes no sense,
  28.         it will still be present as a "dummy", thus just a Keyword
  29.         is placed there and no value is given via "="
  30.  
  31.   A CPInfo-File has the following structure:
  32.  
  33.       CPINFO                               ; identification
  34.       SECTION=<Name of ControlPad entry>   ; the name of the entry
  35.       TYPE=<INTEGER|FLOAT|ASCII|NONE>      ; type of data, signed or
  36.                                            ; unsigned might be detected
  37.                                            ; via min and max.
  38.                                            ; NONE is used for KeyWords.
  39.       MIN=<Value>                          ; - minimum value for numbers
  40.                                            ; - minimum length for strings
  41.                                            ; - or empty ("MIN")
  42.       MAX=<Value>                          ; - maximum value for numbers
  43.                                            ; - maximum length for strings
  44.                                            ; - or empty ("MAX")
  45.       DEFAULT=<Default value for entry>    ; what will be used if nothing
  46.                                            ; is specified ?!
  47.                                            ; May be empty, if optional.
  48.       DESCRIPTION=<descriptive text>       ; what does it do ?
  49.       MASK=<input mask>                    ; this one allows to separate
  50.                                            ; choices and "free" enterings
  51.       WHEN=<READ|WRITE|ALWAYS|PREFS|NEVER> ; ask for it, when the user
  52.                                            ; does reading or writing
  53.                                            ; (SVObjects) ? Or always
  54.                                            ; (SVDrivers/SVOperators) ?
  55.                                            ; Or never ? (Undocumented)
  56.                                            ; Or Just handle it as a real
  57.                                            ; preferences thing ?
  58.  
  59.     A few words to the MASK entry:
  60.  
  61.     Any entries which don't have a specific meaning (just comments)
  62.     or mutual exclude entries do have to begin with "<" and end with
  63.     ">". Anything else are control sequences, qhich either are
  64.     to be supported or have to be ignored.
  65.  
  66.     a) "<...>" or "<...|...|...>"
  67.  
  68.     Usually you should print out this text as a little help for
  69.     the user, how to enter the data, e.g. into a string/integer gadget.
  70.     But if the string included by "<" and ">" does contain one or
  71.     more "|" these are meant as exclusice choices, which e.g.
  72.     might be represented as mx-, cycle- or listview-gadgets.
  73.     So you may a) present this mask to the user while editing a
  74.     string/integer gadget or b) parse it and just "filter" the input
  75.     via supplying appropriate input gadgets.
  76.     Please note, that the "MIN" and "MAX" values (if specified)
  77.     still have to be valid for this input (if the file definition
  78.     has been done correctly ;-)
  79.     So for a "MASK=<8|24>" these would equal "MIN=8" and "MAX=24".
  80.     But note, that this "mask" is not really meant to define ranges
  81.     with gaps, like "anything between 5 and 37, but except the numbers
  82.     between 33.3 und 36.5" 8-)
  83.  
  84.     b) Control Sequences
  85.  
  86.     MASK=_SVOBJECT                means, that a file from "LIBS:svobjects"
  87.                                   has to be requested, which matches
  88.                                   "#?.svobject".
  89.     MASK=_SVDRIVER                means, that a file from "LIBS:svdrivers"
  90.                                   has to be requested, which matches
  91.                                   "#?.svdriver".
  92.     MASK=_SVOPERATOR              means, that a file from "LIBS:svoperators"
  93.                                   has to be requested, which matches
  94.                                   "#?.svoperator".
  95.     MASK=_FILE                    a file to be selected e.g. fromout a
  96.                                   requester (it is supposed, that the user
  97.                                   does the right choice).
  98.  
  99.     Well, so an entry for a KeyWord might look like this:
  100.  
  101.     SECTION=ANYDATATYPES
  102.     TYPE=NONE
  103.     MIN
  104.     MAX
  105.     DEFAULT
  106.     DESCRIPTION=Switches Datatypes support to ANY
  107.     MASK
  108.     WHEN=PREFS
  109.  
  110.  
  111.     An entry for a float value:
  112.  
  113.     SECTION=SCALE_FACTOR
  114.     TYPE=FLOAT
  115.     MIN=0.1
  116.     MAX=2.0
  117.     DEFAULT=1.0
  118.     DESCRIPTION=Factor for scaling graphics
  119.     MASK=<Value>
  120.     WHEN=ALWAYS
  121.  
  122.  
  123.     An entry for an ASCII text:
  124.  
  125.     SECTION=PACKMETHOD
  126.     TYPE=ASCII
  127.     MIN=4
  128.     MAX=4
  129.     DEFAULT=NUKE
  130.     DESCRIPTION=How to pack the written data
  131.     MASK=<XPK-Packer>
  132.     WHEN=WRITE
  133.  
  134.  
  135.     An example for an ignoreable Keyword:
  136.  
  137.     SECTION=DEBUGMODE
  138.     TYPE=NONE
  139.     MIN
  140.     MAX
  141.     DEFAULT
  142.     DESCRIPTION=Enables debugging mode with Confirm-Requesters
  143.     MASK
  144.     WHEN=NEVER
  145.  
  146.  
  147.   So you see, that it's easy to describe any of the existing ControlPad
  148.   variations this way.
  149.   The "WHEN" statement is just a help for applications to decide, whether
  150.   requesting any specific entry would _really_ be useful to the user
  151.   (BTW: the user should always be able to deactivate any kind of
  152.         automatic requests. Maybe add sort of an "expert mode" for
  153.         those stuff).
  154.  
  155.  
  156.   Future:
  157.  
  158.   A. First "maybe" (most likely)
  159.   In the future, there might be a function in superview.library, which
  160.   allows passing a controlpad list to it, which then might be passed
  161.   to the attached SVObject/Driver/Operator as a "local" setting,
  162.   which will override the "global" ControlPad files.
  163.   So the CPInfo Files would be useful for the applications on how
  164.   to find out, which ControlPads might be possibly set.
  165.  
  166.   B. Second "maybe" (my former favorite idea: no longer)
  167.   Also there might be a way to allow superviewsupport.library
  168.   to "filter" any incoming ControlPad entry.
  169.   If it's content is equal to the KeyWord "REQUEST"
  170.   (e.g. "DITHERMODE=REQUEST"), the library might read the CPInfo-File
  171.   and then open a requester asking for an appropriate value.
  172.   This would be again a global setting, but would also work with
  173.   older superview-based applications sine no new functions are needed
  174.   (but applications, which don't use superviewsupport.library for
  175.    ControlPad-parsing would lose at this point).
  176.  
  177.   C. Third "maybe" (unlikely, since it would restrict applications too much)
  178.   superview.library might parse the CPInfo-Files for specific modules
  179.   and ask for values, if it comes to the conclusion, that it's
  180.   necessary ("WHEN" statement).
  181.  
  182.  
  183.   If you're an application programmer please let me know, what's your
  184.   favoured idea.
  185.   Work is still in progress, nothing's fixed.
  186.  
  187.  - Andy
  188.