home *** CD-ROM | disk | FTP | other *** search
/ Amiga ISO Collection / AmigaUtilCD2.iso / Programming / Misc / rs60-2.dms / rs60-2.adf / Docs / UserSymbols.doc < prev   
Encoding:
Text File  |  1994-04-20  |  10.6 KB  |  238 lines
  1. * Documentation for User-defined symbols                           April 1994
  2. * ======================================
  3. * Starting vith version 4.00, ReSource will accept user-defined symbols. 
  4. * This document will show you how to construct your own symbol bases for use
  5. * in ReSource.
  6. *
  7. * A symbol base starts with a longword pointer to the name for this symbol
  8. * base.  Only the first 23 characters of this name will be used in the
  9. * menus.
  10. *
  11. * There are 2 basic types of user-defined symbol bases.  The most used type
  12. * will be one in which any particular value can only equate to one symbol.
  13. *
  14. * In the other type the target number is considered to be one or more groups
  15. * of bit fields, and each field may or may not equate to a symbol.  The
  16. * resulting symbols are OR'd together, to create the final string.  For
  17. * example, "MEMF_CLEAR!MEMF_CHIP" is comprised of two symbols, the first
  18. * equates to $10000; the second equates to 2.  Therefore, the number that
  19. * created this string must have been $10002.
  20. *
  21. * ReSource looks at the byte following the name pointer to know which type of
  22. * symbol base is being defined.
  23. *
  24. * If bit 7 is clear, this is the first type, a simple symbol base.  ReSource
  25. * will also need to know whether the values in this symbol base are signed,
  26. * and also their size (byte/word/longword).  Bit 4 is set for signed values,
  27. * cleared for unsigned.  The lower nibble of this byte is 1 for bytes, 2 for
  28. * words, and 3 for longwords.
  29. *
  30. * If bit 7 is set, the second symbol base, or compound type using OR'd
  31. * symbols, is being defined.
  32. *
  33. * Simple Symbol Base
  34. * ------------------
  35. * Following the symbol base type byte are zero or more entries, each
  36. * consisting of a null-terminated string, followed immediately by the value
  37. * assigned to that string.  Word and longword values are NOT expected to be
  38. * word-aligned, although the entire structure IS; make sure you enter a CNOP
  39. * after the name.  The order of these entries must be such that the values
  40. * are in ascending (unsigned) order.
  41. *
  42. * Compound Symbol Base
  43. * --------------------
  44. * Following the symbol base type byte are zero or more entries, each
  45. * consisting of a null-terminated string, followed immediately by 2
  46. * longwords.  ReSource AND's the target value with the first longword value,
  47. * and compares the result to the second longword value.  If the comparison
  48. * succeeds, the string defined in this entry becomes part of the produced
  49. * string.  If there is more than one symbol produced, it is OR'ed with the
  50. * others, and the entire string is surrounded by parentheses.
  51. *
  52. * In either case the last entry must be followed by a -1 byte, which
  53. * terminates the symbol base.  Following are a few macros and equates which
  54. * may be handy when creating symbol bases.  Remember, except for the
  55. * structure itself, no word alignment of word or longword fields is expected
  56. * or desired; if you do use any pad bytes, incorrect symbols may be produced.
  57. * Once you have written a compete symbol base, assemble it, link it, and the
  58. * resulting executable can be loaded into ReSource.
  59. *
  60. * Loading User Symbol Bases
  61. * -------------------------
  62. * Use the SYMBOLS gadget to bring up the Symbols ListView and select
  63. * "UserSymbols" from the directory gadget, "User Symbols" from the file
  64. * gadget, and any base from the "Symbol Base" gadget.  Then click on
  65. * "Load user symbols" to actually load your previously defined symbol base
  66. * into ReSource.  When the requester pops up, select the pathname of your
  67. * symbol base.
  68. *
  69. * Now that your symbol base has been loaded, whenever you wish to assign a
  70. * symbol, select your base from the "Individual SymbolBases" gadget to create
  71. * a symbol using that particular base. 
  72. *
  73. * To unload a symbol base, select it from the "Individual SymbolBases" gadget
  74. * and then select CANCEL on the requester.
  75.  
  76. ByteSymbol     macro
  77.                dc.b    '\1'
  78.                dc.b    0
  79.                dc.b    (\2)
  80.                endm
  81.  
  82. WordSymbol     macro
  83.                dc.b    '\1'
  84.                dc.b    0
  85.                dc.b    ((\2>>8)&$FF)
  86.                dc.b    (\2&$FF)
  87.                endm
  88.  
  89. LongSymbol     macro
  90.                dc.b    '\1'
  91.                dc.b    0
  92.                dc.b    ((\2>>24)&$FF)
  93.                dc.b    ((\2>>16)&$FF)
  94.                dc.b    ((\2>>8)&$FF)
  95.                dc.b    (\2&$FF)
  96.                endm
  97.  
  98. ORedSymbol     macro
  99.                dc.b    '\1'
  100.                dc.b    0
  101.                dc.b    ((\2>>24)&$FF)
  102.                dc.b    ((\2>>16)&$FF)
  103.                dc.b    ((\2>>8)&$FF)
  104.                dc.b    (\2&$FF)
  105.                dc.b    ((\3>>24)&$FF)
  106.                dc.b    ((\3>>16)&$FF)
  107.                dc.b    ((\3>>8)&$FF)
  108.                dc.b    (\3&$FF)
  109.                endm
  110.  
  111. OREDSYM        equ     1<<7            ;Symbol base using OR'd symbols
  112. SIGNEDSYM      equ     1<<4            ;Symbol base using signed symbols
  113. BYTESYM        equ     1<<0            ;Symbol base using byte symbols
  114. WORDSYM        equ     1<<1            ;Symbol base using word symbols
  115. LONGSYM        equ     BYTESYM!WORDSYM ;Symbol base using long symbols
  116. ENDBASE        equ     $FF             ;Token to end symbol base
  117.  
  118.  
  119. In this example, we will create a symbol base for a standard list node
  120. structure.  This has only 6 symbols in it, and the largest of these has a
  121. value of only $0E (LN_SIZE).  Because of this, we shall define the values as
  122. bytes.  None of the values are considered to be signed, so our first byte
  123. of symbol base will be BYTESYM:
  124.  
  125.                dc.l       listnodename
  126.                dc.b       BYTESYM
  127.                ByteSymbol <LN_SUCC>,$00
  128.                ByteSymbol <LN_PRED>,$04
  129.                ByteSymbol <LN_TYPE>,$08
  130.                ByteSymbol <LN_PRI>,$09
  131.                ByteSymbol <LN_NAME>,$0A
  132.                ByteSymbol <LN_SIZE>,$0E
  133.                dc.b       ENDBASE       ;Required to terminate symbol base
  134. listnodename   dc.b       'List Node',0 ;This will appear in the menu in ReSource
  135.                cnop       0,2
  136.  
  137.  
  138. * This example demonstrates the use of signed word values.  The actual
  139. * symbols and values are similar to those in the "console library" symbol
  140. * base in ReSource:
  141.  
  142.                dc.l       consolename
  143.                dc.b       SIGNEDSYM!WORDSYM  ;Signed word
  144.                WordSymbol <LIB+LN_SUCC>,$00
  145.                WordSymbol <LIB+LN_PRED>,$04
  146.                WordSymbol <LIB+LN_TYPE>,$08
  147.                WordSymbol <LIB+LN_PRI>,$09
  148.                WordSymbol <LIB+LN_NAME>,$0A
  149.                WordSymbol <LIB_FLAGS>,$0E
  150.                WordSymbol <LIB_pad>,$0F
  151.                WordSymbol <LIB_NEGSIZE>,$10
  152.                WordSymbol <LIB_POSSIZE>,$12
  153.                WordSymbol <LIB_VERSION>,$14
  154.                WordSymbol <LIB_REVISION>,$16
  155.                WordSymbol <LIB_IDSTRING>,$18
  156.                WordSymbol <LIB_SUM>,$1C
  157.                WordSymbol <LIB_OPENCNT>,$20
  158.                WordSymbol <LIB_SIZE>,$22
  159.                WordSymbol <_LVOSetDefaultKeyMap>,-$3C
  160.                WordSymbol <_LVOAskDefaultKeyMap>,-$36
  161.                WordSymbol <_LVORawKeyConvert>,-$30
  162.                WordSymbol <_LVOCDInputHandler>,-$2A
  163.                WordSymbol <LIB_EXTFUNC>,-$24
  164.                WordSymbol <LIB_EXPUNGE>,-$18
  165.                WordSymbol <LIB_CLOSE>,-$12
  166.                WordSymbol <LIB_OPEN>,-$6
  167.                dc.b       ENDBASE            ;Terminate symbol base
  168. consolename    dc.b       'Console library',0
  169.                cnop       0,2
  170.  
  171.  
  172. * This example introduces a compound symbol base.  Use this type when
  173. * several symbols may have to be OR'ed together to get the required value.
  174. * To create a compound symbol base, the first byte after the symbol base
  175. * name pointer must have bit 7 set.  The actual symbol base used here is
  176. * similar to the one for memory attributes in ReSource:
  177.  
  178.                dc.l       memattrname
  179.                dc.b       OREDSYM              ;OR'ed symbols
  180.                OredSymbol <MEMF_ANY>,-1,0      ;Must match exactly
  181.                OredSymbol <MEMF_PUBLIC>,1<<0,1<<0
  182.                OredSymbol <MEMF_CHIP>,1<<1,1<<1
  183.                OredSymbol <MEMF_FAST>,1<<2,1<<2
  184.                OredSymbol <MEMF_CLEAR>,1<<16,1<<16
  185.                OredSymbol <MEMF_LARGEST>,1<<17,1<<17
  186.                dc.b       ENDBASE              ;Terminate symbol base
  187. memattrname    dc.b       'Memory attributes',0
  188.                cnop       0,2
  189.  
  190. * Notice that each entry has TWO values, where previous symbol bases had only
  191. * one.  ReSource AND's the target value with the first number, and compares
  192. * it with the second.  If the comparison succeeds, the symbol gets OR'ed with
  193. * the rest of the entries which succeed.
  194. *
  195. * Thus, if the target value was "$00010001", the actual symbol produced would
  196. * be "MEMF_CLEAR!MEMF_PUBLIC".  This type of symbol base is already used in
  197. * ReSource for Memory Attributes, Alert Codes, Font Flags, MenuItem Flags and
  198. * many more.
  199.  
  200.  
  201. * The next example is similar to the "Alert codes" symbol base, but has been
  202. * much reduced in size:
  203.  
  204.                dc.l       alertcodename
  205.                dc.b       OREDSYM!LONGSYM    ;OR'ed symbols, unsigned, longword
  206.                LongSymbol <AT_DeadEnd>,$80000000,$80000000
  207.                LongSymbol <AT_Recovery>,$80000000,$00000000
  208.                LongSymbol <AG_NoSignal>,$000F0000,$00070000
  209.                LongSymbol <AG_IOError>,$000F0000,$00060000
  210.                LongSymbol <AG_OpenRes>,$000F0000,$00050000
  211.                LongSymbol <AG_OpenDev>,$000F0000,$00040000
  212.                LongSymbol <AG_OpenLib>,$000F0000,$00030000
  213.                LongSymbol <AG_MakeLib>,$000F0000,$00020000
  214.                LongSymbol <AG_NoMemory>,$000F0000,$00010000
  215.                LongSymbol <AO_GraphicsLib>,$0000FFFF,$00008002
  216.                LongSymbol <AO_ExecLib>,$0000FFFF,$00008001
  217.                LongSymbol <AO_DiskRsrc>,$0000FFFF,$00008021
  218.                LongSymbol <AO_MiscRsrc>,$0000FFFF,$00008022
  219.                LongSymbol <AO_BootStrap>,$0000FFFF,$00008030
  220.                LongSymbol <AO_Workbench>,$0000FFFF,$00008031
  221.                dc.b       ENDBASE            ;Terminate symbol base
  222. alertcodename  dc.b       'Alert codes',0
  223.  
  224. * The above example is much smaller than the actual "Alert codes" symbol
  225. * base in ReSource.  However, it does demonstate that individual bit fields
  226. * can be masked out, and the remainder compared, to produce the required
  227. * symbols.
  228. *
  229. * It is interesting to note that because of the first 2 entries, ALL symbols
  230. * produced will start with either "AT_DeadEnd" or "AT_Recovery".  Every bit
  231. * other than bit 31 is masked out, and then compared.  If bit 31 is set, the
  232. * symbol will start with "AT_DeadEnd", otherwise "AT_Recovery".  If you wish
  233. * to compare the entire longword, the first value should be -1.  In this
  234. * case, only if the target number is EXACTLY equal to the second longword,
  235. * will the symbol for that entry be used.
  236.  
  237.                end
  238.