home *** CD-ROM | disk | FTP | other *** search
/ No Fragments Archive 10: Diskmags / nf_archive_10.iso / MAGS / ST_USER / 1992 / USERJN92.MSA / RTCCCH_RTCCCH.TXT < prev    next >
Text File  |  1992-03-01  |  13KB  |  290 lines
  1.     INSTRUCTIONS FOR
  2.  
  3.       RESOURCE TO C CODE CONVERTER V1.2 (RTCCCH.PRG)
  4.  
  5.     Machine: Atari ST/TT range
  6.     Resolution: ST-Low, ST-Med, ST-High, TT-Low, TT-Med, TT-High
  7.     Memory: 512K
  8.  
  9.  
  10.     Hello fellow ATARI ST programmers,
  11.       This utility program converts any standard  ST  resource file into a C
  12.     code file, which can be easily  imported  into  your own C programs.  It
  13.     effectively performs the error prone  task  of hard-coding your resource
  14.     files.   Naturally,  this  program  requires   the  use  of  a  resource
  15.     construction set (RCS) and an implementation  of the C language.  It has
  16.     been specifically designed to  work  with  the  Lattice C V5 Development
  17.     System, produced by HiSoft.
  18.  
  19.       I will assume, that you have some elementary knowledge of object trees
  20.     and resource files, but if you don't, there are a number of books on the
  21.     subject.
  22.  
  23.     Why hard-code resources?
  24.       If you look at your collection  of  GEM software, the chances are that
  25.     most of them will make use of an external resource  file which is stored
  26.     in the same directory.  However, once  in  a  while you'll come across a
  27.     program that uses menus and  dialog  boxes,  but  there isn't a resource
  28.     file to be found anywhere.  In this  case, the resources have been hard-
  29.     coded into the program.  There  are  advantages  to  both methods and it
  30.     depends really on the preference of the programmer.
  31.  
  32.       The classic argument for keeping  resources  external, is that you can
  33.     make limited changes to  the  resources  without  recompiling the source
  34.     code.  Thus, if the program makes extensive  use of a resource file, the
  35.     program can be translated into  a  different language, without having to
  36.     refer back to the  source  code.   However,  these  changes are severely
  37.     limited, as the structure  of  the  resource  has  to  be preserved.  No
  38.     objects may be  added  or  deleted  and  only  their  contents, size and
  39.     location may be changed.
  40.  
  41.       On the other hand, if the  resources  are included in the source file,
  42.     they become human readable, can easily be printed for a permanent record
  43.     and are far easier to  document.   Small  changes  can  be made from the
  44.     editor, but is only recommended if you know what you are doing.
  45.  
  46.       The RTCCCH program automatically  assigns  each structure occurrence a
  47.     unique identifier, so they can be  directly  accessed without the use of
  48.     indirection.  For example, if you wished  to  access an input field in a
  49.     form, you can directly access  the  string in the appropriate occurrence
  50.     of the TEDINFO structure.  No longer  will  you have to find the address
  51.     of the structure  through  the  ob_spec  field  of  the  object.   In my
  52.     opinion, this makes programming  with  resources much easier, especially
  53.     for beginning GEM programmers.
  54.  
  55.       The third reason is that resources may now be optimized.  For example,
  56.     a form contains two  similar  bit  images,  which  are duplicated in the
  57.     object tree.  Space could be saved  if  the only the first occurrence of
  58.     the bit image is kept and the  pointer to the now 'missing' bit-image is
  59.     redirected to the first image.
  60.  
  61.       The fourth reason,  perhaps  the  most  important  reason  where the C
  62.     language  is  concerned,  resources  can  now  be  local  to  files  and
  63.     functions.  C is a structured  language,  in  which a function's data is
  64.     local and hidden from other functions  and  modules, this concept can be
  65.     extended to resources as well.   In  a  huge  project, where hundreds of
  66.     functions are scattered across a dozen  or so files, local resources are
  67.     far easier to manage than one large resource file.  Local resources also
  68.     enable the creation of stand-alone C libraries that use resources.
  69.  
  70.       If your program is to run in more than one resolution, you may have to
  71.     use more than one resource file.   The resolution in which RTCCCH.PRG is
  72.     executed DOES affect the  resulting  code  file.   The program loads the
  73.     resource using  the  rsrc_load()  function,  which  automatically  makes
  74.     adjustments to the coordinates to conform to the current resolution.
  75.       So remember to run RTCCCH.PRG in  the resolution in which the resource
  76.     is to be used.
  77.       There are basically two ways to deal with the resolution problem,  one
  78.     is to have access to several version of the same resource, or to write a
  79.     piece of  code  which  alters  the  object  tree  as  required.   What I
  80.     recommend, is that you  create  several  versions  of  the resource file
  81.     using your RCS and then convert them all and then compare them.  That is
  82.     what I have done when I wrote RTCCCH.  Let experience is your tutor.
  83.  
  84.     How to use RTCCCH.PRG
  85.       When running RTCCCH.PRG, you are presented  with a dialog that handles
  86.     every function of the program.  The  Input File field should contain the
  87.     name for the resource file which  is  to  be converted.  The Output File
  88.     field should contain the name  of  the  resultant  C code file.  The two
  89.     'Ask' buttons call up the file selector for the respective fields.
  90.       You may not always wish to  convert  the whole resource file, thus you
  91.     can specify a range of trees to convert.  The first tree has an index of
  92.     zero, the second and index of 1  and  so on.  The default indexes of are
  93.     set to zero, so only the first object tree is converted.
  94.       When dealing with  a  huge  object  tree,  it  is  quite  difficult to
  95.     determine the index of a particular object  (unless you want to refer to
  96.     the header file produced by the RCS), therefore RTCCCH.PRG gives you the
  97.     option of including  the  index  number  in  front  of  every  object in
  98.     comments.
  99.       You also have  the  option  of  producing  external declarations only,
  100.     which is useful if the actual  object  tree  is to be located in another
  101.     module.
  102.       The 'OK' button will  perform  the  conversion  and  the 'Exit' button
  103.     quits the program.
  104.  
  105.       Some care must be taken  when  this  program  is  run.  The input file
  106.     should be a standard resource file  and  the indexes of the object trees
  107.     to be converted must be a valid range, otherwise the program may produce
  108.     unpredictable results.
  109.  
  110.       WARNING: The output file produced will OVERWRITE an existing file.
  111.  
  112.       A C code object tree will consist of several occurrences of structures
  113.     followed by an array  of  objects.   The  objects  in  the array will be
  114.     linked to each other using indexes (short integers) and may be linked to
  115.     a structure using a label.
  116.       A label is generated as follows:  The  name  of the type of the object
  117.     is followed by the tree  index.   Structures  other than the object tree
  118.     will be followed by an  underline  symbol  and  the object index number.
  119.     This is to ensure that there are  no duplicate labels, while still being
  120.     reasonably readable.
  121.  
  122.       NOTE: If a object tree should  use  ProgDefs, a reference label is set
  123.     up as outlined before, but it is left up to the programmer to define.
  124.  
  125.  
  126.       Following is an example of how to effectively use this program.
  127.  
  128.       We are going to write a program, that displays a dialog box with a bit
  129.     image of a smiling face, two strings  'Are you' and 'happy?' and a 'Yes'
  130.     and 'No' button, all within a border.   Below is an approximation of how
  131.     it is going to look like.
  132.  
  133.                        -------------------
  134.                       |  ------           |   (Diagram not to scale -
  135.                       | | O  O |          |   In reality the bit image
  136.                       | |      |  Are You |   will be much smaller)
  137.                       | | |  | |  happy?  |
  138.                       | |  --  |          |
  139.                       |  ------           |
  140.                       |                   |
  141.                       |  -----    ----    |
  142.                       | | Yes |  | No |   |
  143.                       |  -----    ----    |
  144.                        -------------------
  145.  
  146.       The first step is to load a  resource construction set and create this
  147.     dialog box and save it to disk, say under the name 'DIALOG1.RSC'.
  148.     Any other files the RCS may produce are unnecessary.
  149.       The next step is to  load  up  RTCCCH.   The  resource name and C code
  150.     should be set to 'DIALOG1.RSC' and 'DIALOG1.C', respectively.  Remember,
  151.     that you may use  full  path  names  with drive letters.  Alternatively,
  152.     press the 'Ask' buttons to use the file selector.
  153.       Because there is only one object tree  in the file, the indexes should
  154.     be left as they are.
  155.       Then simply press the 'OK' button.   A  message should come up to tell
  156.     you that the  resource  has  been  successfully  converted  and  you are
  157.     returned to the dialog.   Simply  press  the  'Exit'  button to quit the
  158.     program.
  159.  
  160.       The above instruction should produce  a  file that look something like
  161.     this:
  162.  
  163.   short bi_pdata0_1[] =
  164.   {    0x0000,0x03C0,0x0C30,0x1008,0x2004,0x2664,0x4662,0x4002,0x4002,0x4002,
  165.        0x2424,0x23C4,0x1008,0x0C30,0x03C0,0x0000
  166.   };
  167.  
  168.   BITBLK bitblk1 =
  169.   {    bi_pdata1,   2,  16,   0,   0,   1
  170.   };
  171.  
  172.   OBJECT object_tree0[] =
  173.   {    -1, 1, 5,G_BOX,   0x0000,0x0000,(void *)0x021181,16,16,152,96,
  174.         2,-1,-1,G_IMAGE, 0x0000,0x0000,(void *)&bitblk0_1,16,16,16,16,
  175.         3,-1,-1,G_STRING,0x0000,0x0000,(void *)"Are you",56,16,56,16,
  176.         4,-1,-1,G_STRING,0x0000,0x0000,(void *)"happy?",56,32,48,16,
  177.         5,-1,-1,G_BUTTON,0x0005,0x0000,(void *)" Yes ",16,64,56,16,
  178.         0,-1,-1,G_BUTTON,0x0025,0x0000,(void *)" No ",88,64,48,16
  179.   };
  180.  
  181.  
  182.       Once we give the object trees  some  sensible  names, you are ready to
  183.     write the program to handle the object tree.  The full program is below.
  184.  
  185.   #include <aes.h>
  186.  
  187.   short happy_image[] =
  188.   {    0x0000,0x03C0,0x0C30,0x1008,0x2004,0x2664,0x4662,0x4002,0x4002,0x4002,
  189.        0x2424,0x23C4,0x1008,0x0C30,0x03C0,0x0000
  190.   };
  191.  
  192.   BITBLK happy_block =
  193.   {    happy_image,   2,  16,   0,   0,   1
  194.   };
  195.  
  196.   OBJECT ask_if_happy[] =
  197.   {    -1, 1, 5,G_BOX,   0x0000,0x0000,(void *)0x021181,16,16,152,96,
  198.         2,-1,-1,G_IMAGE, 0x0000,0x0000,(void *)&happy_block,16,16,16,16,
  199.         3,-1,-1,G_STRING,0x0000,0x0000,(void *)"Are you",56,16,56,16,
  200.         4,-1,-1,G_STRING,0x0000,0x0000,(void *)"happy?",56,32,48,16,
  201.         5,-1,-1,G_BUTTON,0x0005,0x0000,(void *)" Yes ",16,64,56,16,
  202.         0,-1,-1,G_BUTTON,0x0025,0x0000,(void *)" No ",88,64,48,16
  203.   };
  204.  
  205.   int main(void)
  206.   {    short x, y, w, h;
  207.  
  208.        /* initialize the application */
  209.        appl_init();
  210.  
  211.        /* center the dialog box */
  212.        form_center(ask_if_happy, &x, &y, &w, &h);
  213.  
  214.        /* reserve the necessary workspace */
  215.        form_dial(FMD_START, 0, 0, 0, 0, x, y, w, h);
  216.        form_dial(FMD_GROW, 0, 0, 0, 0, x, y, w, h);
  217.  
  218.        /* draw the dialog box */
  219.        objc_draw(ask_if_happy, ROOT, MAX_DEPTH, x, y, w, h);
  220.  
  221.        /* handle dialog box */
  222.        form_do(ask_if_happy, 0);
  223.  
  224.        /* remove the dialog box and return the workspace */
  225.        form_dial(FMD_SHRINK, 0, 0, 0, 0, x, y, w, h);
  226.        form_dial(FMD_FINISH, 0, 0, 0, 0, x, y, w, h);
  227.  
  228.        /* terminate the application */
  229.        appl_exit();
  230.  
  231.        /* return to calling program */
  232.        return 0;
  233.   }
  234.  
  235.       That's all there is  to  it.   Why  don't  you  try  lifting the above
  236.     section out of this file, compile and run it.
  237.  
  238.  
  239.       Menus are handled much in the same fashion, but you use the menu_bar()
  240.     function to  display  the  menu  bar  and  use  either  evnt_mesag()  or
  241.     evnt_multi() to use them.  Below  is  a  rough  skeleton of what you are
  242.     expected to do.
  243.  
  244.   #include <aes.h>
  245.   ...
  246.   OBJECT menu[] =         \
  247.   {    ...                 |  This is the output of RTCCCH.PRG
  248.        ...                 |
  249.   };                      /
  250.  
  251.  
  252.   int main(void)
  253.   {    short message[8];
  254.  
  255.        /* initialize the application */
  256.        appl_init();
  257.  
  258.        /* install the menu */
  259.        menu_bar(menu, 1);
  260.  
  261.        /* wait for a menu event */
  262.        do
  263.        {    evnt_mesag(message);
  264.        } while (message[0] != MN_SELECTED);
  265.  
  266.        /* deinstall the menu */
  267.        menu_bar(menu, 0);
  268.  
  269.        /* terminate the application */
  270.        appl_exit();
  271.  
  272.        return 0;
  273.   }
  274.  
  275.       If you have any problems with this  program  or have some ideas on how
  276.     to improve it, do not hesitate to contact me.
  277.  
  278.       Arnd Hurlbrink
  279.       8 Mahonia Place
  280.       Duncraig  WA  6023
  281.       West Australia
  282.  
  283.       Watch out for an assembler  version  of  this  program sometime in the
  284.     future.  Well, that's all from me for now.  Happy programming!
  285.  
  286.  
  287.     Written 04/11/91
  288.     Updated 20/02/92
  289.     End Of File
  290.