home *** CD-ROM | disk | FTP | other *** search
/ Amiga ISO Collection / AmigaUtilCD1.iso / GFX / viewer / TCE-SV51.LHA / SuperViewEL / SuperViewLibrary / Docs / SVSupport-Docs / CPInfoFormat.doc < prev    next >
Encoding:
Text File  |  1995-10-14  |  7.6 KB  |  192 lines
  1.  
  2.   The ControlPadInfo-FileFormat V6.9 (10.9.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.  
  14.   Structure in general
  15.   --------------------
  16.   Every CPInfo-File is constructed like an usual ControlPad file,
  17.   but in this case, the _order_ of the entries becomes meaningful.
  18.   These files are separated into SECTIONs, where any necessary
  19.   information about specific ControlPad entries are stored.
  20.  
  21.   To allow easy enhancements and improvements on this format, there's
  22.   an important note:
  23.  
  24.       - the number of sections is not limited
  25.       - each SECTION _must_ contain at least the entries described below
  26.       - each SECTION _may_ contain more entries, so that it might be
  27.         necessary to skip all the following entries until another "SECTION"
  28.         entry will be reached
  29.       - the order of the entries is _fixed_
  30.       - if any of the following _needed_ entries makes no sense,
  31.         it will still be present as a "dummy", thus just a Keyword
  32.         is placed there and no value is given via "="
  33.       - any single line should not exceed 255 characters
  34.       - as with usual ControlPad files, comments and blank lines are allowed
  35.  
  36.   Structure in detail
  37.   -------------------
  38.       CPINFO                               ; identification
  39.       SECTION=<Name of ControlPad entry>   ; the name of the entry
  40.       TYPE=<INTEGER|FLOAT|ASCII|NONE>      ; type of data
  41.                                            ; (signed or unsigned for
  42.                                            ;  INTEGER or FLOAT may
  43.                                            ;  be detected via MIN and MAX).
  44.                                            ; NONE is used for KeyWords.
  45.       MIN=<Value>                          ; - minimum value for numbers
  46.                                            ; - minimum length for strings
  47.                                            ; - or empty ("MIN")
  48.                                            ; Empty with KeyWords.
  49.       MAX=<Value>                          ; - maximum value for numbers
  50.                                            ; - maximum length for strings
  51.                                            ; - or empty ("MAX")
  52.                                            ; Empty with KeyWords.
  53.       DEFAULT=<Default value for entry>    ; what will be used if nothing
  54.                                            ; is specified ?!
  55.                                            ; Empty e.g. with KeyWords.
  56.       DESCRIPTION=<descriptive text>       ; what does it do ?
  57.       MASK=<input mask>                    ; this one allows to separate
  58.                                            ; choices and "free" enterings
  59.                                            ; Empty with KeyWords.
  60.       WHEN=<READ|WRITE|ALWAYS|PREFS|NEVER> ; ask for it, when the user
  61.                                            ; does reading or writing
  62.                                            ; (SVObjects) ? Or always
  63.                                            ; (SVDrivers/SVOperators) ?
  64.                                            ; Or never ? (Undocumented)
  65.                                            ; Or Just handle it as a real
  66.                                            ; preferences thing ?
  67.  
  68.     Structure Entry Description in detail
  69.     -------------------------------------
  70.     o A few words to the MASK entry:
  71.  
  72.       Any entries which don't have a specific meaning (just comments)
  73.       or mutual exclude entries do have to begin with "<" and end with
  74.       ">". Anything else are control sequences, qhich either are
  75.       to be supported or have to be ignored.
  76.  
  77.       a) "<...>" or "<...|...|...>"
  78.  
  79.       Usually you should print out this text as a little help for
  80.       the user, how to enter the data, e.g. into a string/integer gadget.
  81.       But if the string included by "<" and ">" does contain one or
  82.       more "|" these are meant as exclusice choices, which e.g.
  83.       might be represented as mx-, cycle- or listview-gadgets.
  84.       So you may a) present this mask to the user while editing a
  85.       string/integer gadget or b) parse it and just "filter" the input
  86.       via supplying appropriate input gadgets.
  87.       Please note, that the "MIN" and "MAX" values (if specified)
  88.       still have to be valid for this input (if the file definition
  89.       has been done correctly ;-)
  90.       So for a "MASK=<8|24>" these would equal "MIN=8" and "MAX=24".
  91.       But note, that this "mask" is not really meant to define ranges
  92.       with gaps, like "anything between 5 and 37, but except the numbers
  93.       between 33.3 und 36.5" 8-)
  94.  
  95.       b) Control Sequences
  96.  
  97.       MASK=_SVOBJECT                means, that a file from "LIBS:svobjects"
  98.                                     has to be requested, which matches
  99.                                     "#?.svobject".
  100.       MASK=_SVDRIVER                means, that a file from "LIBS:svdrivers"
  101.                                     has to be requested, which matches
  102.                                     "#?.svdriver".
  103.       MASK=_SVOPERATOR              means, that a file from "LIBS:svoperators"
  104.                                     has to be requested, which matches
  105.                                     "#?.svoperator".
  106.       MASK=_FILE                    a file to be selected e.g. fromout a
  107.                                     requester (it is supposed, that the user
  108.                                     does the right choice).
  109.  
  110.     Examples
  111.     --------
  112.  
  113.     Anentry for a KeyWord might look like this:
  114.  
  115.     SECTION=ANYDATATYPES
  116.     TYPE=NONE
  117.     MIN
  118.     MAX
  119.     DEFAULT
  120.     DESCRIPTION=Switches Datatypes support to ANY
  121.     MASK
  122.     WHEN=PREFS
  123.  
  124.  
  125.     An entry for a float value:
  126.  
  127.     SECTION=SCALE_FACTOR
  128.     TYPE=FLOAT
  129.     MIN=0.1
  130.     MAX=2.0
  131.     DEFAULT=1.0
  132.     DESCRIPTION=Factor for scaling graphics
  133.     MASK=<Value>
  134.     WHEN=ALWAYS
  135.  
  136.  
  137.     An entry for an ASCII text:
  138.  
  139.     SECTION=PACKMETHOD
  140.     TYPE=ASCII
  141.     MIN=4
  142.     MAX=4
  143.     DEFAULT=NUKE
  144.     DESCRIPTION=How to pack the written data
  145.     MASK=<XPK-Packer>
  146.     WHEN=WRITE
  147.  
  148.  
  149.     An example for an ignoreable Keyword:
  150.  
  151.     SECTION=DEBUGMODE
  152.     TYPE=NONE
  153.     MIN
  154.     MAX
  155.     DEFAULT
  156.     DESCRIPTION=Enables debugging mode with Confirm-Requesters
  157.     MASK
  158.     WHEN=NEVER
  159.  
  160.  
  161.   Last Words and Exceptions
  162.   -------------------------
  163.   So you see, that it's easy to describe any of the existing ControlPad
  164.   variations this way.
  165.  
  166.   The "WHEN" statement is a help for applications to decide, whether
  167.   and when to allow changing of specific ControlPad entries.
  168.  
  169.   Applications should either ignore entries of type "WHEN=NEVER"
  170.   or prepared to handle slightly differing entries, like
  171.   e.g. TYPE=INTEGER entries with a non-set default value.
  172.   (An example had been the "AVAILMEM" switch of interim versions
  173.    of JPEG.svobject - which was both: a keyword and a common setting,
  174.    but should never be changed during runtime.)
  175.  
  176.   "WHEN=NEVER" is just for options with experimental state or
  177.   debugging purposes.
  178.  
  179.  
  180.   Future
  181.   ------
  182.   In the future, there may be a function in superview.library, which
  183.   allows passing a controlpad list to it, which then may be passed
  184.   to the attached SVObject/SVDriver/SVOperator as a "local" setting,
  185.   which will override the "global" ControlPad files.
  186.  
  187.   So the CPInfo Files will be helpful for applications on how
  188.   to find out, which ControlPads might be possibly set.
  189.  
  190.  
  191.  - Andy, 10.9.95
  192.