home *** CD-ROM | disk | FTP | other *** search
/ Club Amiga de Montreal - CAM / CAM_CD_1.iso / files / 514a.lha / TplEdit_v1.00_alpha / tpledit.doc.pp / tpledit.doc
Text File  |  1991-06-08  |  8KB  |  233 lines
  1.  
  2.                 TPLEDIT.DOC
  3.  
  4.                 V1.00 ALPHA
  5.  
  6.     TPLEDIT is a GADTOOLS template editor used to edit display templates
  7.     that can then be compiled into a program.
  8.  
  9.         TPLEDIT ONLY RUNS UNDER 2.0 !   THIS IS AN ALPHA
  10.         TPLEDIT ONLY RUNS UNDER 2.0 !   THIS IS AN ALPHA
  11.         TPLEDIT ONLY RUNS UNDER 2.0 !   THIS IS AN ALPHA
  12.         TPLEDIT ONLY RUNS UNDER 2.0 !   THIS IS AN ALPHA
  13.         TPLEDIT ONLY RUNS UNDER 2.0 !   THIS IS AN ALPHA
  14.  
  15.     (1) MENUS
  16.  
  17.     Save        save database
  18.     SaveC        save database as C code (appends .C to project name)
  19.     SaveAs        save database as (you pick the name)
  20.     SaveAsC     save C source as (you pick the name)
  21.     Load        Load a new project
  22.     Merge        Merge another project into this one
  23.     Quit        quit program
  24.  
  25.     LockTo        See below (ATTACH STRING GADGETS...)
  26.  
  27.     Snap        The mouse coordinates may be snapped to various
  28.             intervals.
  29.  
  30.     NOTE:    TPLEDIT is only able to load database format files which
  31.         are saved via SAVE or SAVEAS.  TPLEDIT cannot reverse
  32.         engineer C source files it generates.
  33.  
  34.         Currently, TPLEDIT does not warn you if you quit without
  35.         saving, or load a new project without saving the old.
  36.  
  37.     Menus can be accessed from either window
  38.  
  39.     (2) TPL CONTROL WINDOW
  40.  
  41.     The control window allows you edit gadgets in the project window.
  42.  
  43.     CREATE NEW GADGET:
  44.  
  45.         Specify the appropriate gadget type, do not specify invisible
  46.         (not implemented yet).  'entry' is a string gadget, I haven't
  47.         renamed it yet.
  48.  
  49.         Then, specify text placement if it applies.
  50.  
  51.         You MUST specify a REGION name.  EACH GADGET MUST HAVE A UNIQUE
  52.         REGION NAME! The gadget label, default text, and buffer length
  53.         specifications depend on the type of gadget you pick.  Note
  54.         that the BUFLEN only applies to string gadgets type=entry, and
  55.         DEFAULT for CYCLE or SELLIST, if specified, is an integer item
  56.         number.
  57.  
  58.         You might want to specify a non-empty string list for CYCLE and
  59.         SELLIST gadgets.  This is done by typing in the ENUM string
  60.         window and hitting return.
  61.  
  62.         hit the NEW gadget.
  63.  
  64.         Move the mouse to the project window and specify a square
  65.         by placing the mouse in the starting position, holding down
  66.         the select while moving the mouse to the ending position and
  67.         release the mouse.    The gadget now exists.
  68.  
  69.     ATTACHING STRING GADGETS TO LISTVIEWS
  70.  
  71.         Create a listview and string gadget.  Select the listview
  72.         gadget so that it's information is displayed in the control
  73.         window.  Then select the LOCKTO menu option.  Finally,
  74.         click on the string gadget.
  75.  
  76.         Due to bugs in GADTOOLS, the string gadget's dimensions will be
  77.         forced to conform.    To unlock you must either delete the
  78.         listview or the stringgadget (for now).
  79.  
  80.     DELETE A GADGET
  81.     MOVE A GADGET
  82.     SIZE A GADGET
  83.  
  84.         To delete a gadget hit the DEL button and click on gadgets
  85.         to delete.
  86.  
  87.         Moving and Sizing work the same.  Sizing always modifies
  88.         the lower right hand corner of an existing gadget.
  89.  
  90.     WANDER
  91.  
  92.         Wander enables all gadgets and lets you play with them.
  93.  
  94.     UPDATE
  95.  
  96.         You can change various parameters, including the items in
  97.         a select/cycle list, by clicking on the appropriate gadget
  98.         from WANDER mode, making the appropriate modifications in
  99.         the TPL CONTROL window, and the hitting UPDATE.
  100.  
  101.         WARNING WARNING:  To copy a string gadget's info to the
  102.         TPL CONTROL window you must hit RETURN in the window after
  103.         activating it!  Otherwise you might update the wrong
  104.         gadget's info.
  105.  
  106.         A CYCLE/SELLIST list may be modified by adding new items
  107.         in the string gadget just above the ENUM text, or deleting
  108.         items by selecting the item and hitting the DEL gadget
  109.         below the ENUM text.
  110.  
  111.     NOTE: SELLIST (LISTVIEW_KIND .. I'll rename it eventually) gadgets
  112.     cannot be deactivated and so their hit boxes remain active.  There
  113.     is a two pixel boundry around every gadget which you can click on
  114.     to 'grab' such gadgets, or grab string gadgets without clicking
  115.     in them.
  116.  
  117.     (3) SOURCE CODE GENERATION
  118.  
  119.     To generate source code select the SaveC or SaveAsC menu options.
  120.     The C source file generates all manipulations required to setup
  121.     the gadtools gadgets in a window... everything except the openning
  122.     of the window itself.
  123.  
  124.     Additionally, the code generates variables references for easy
  125.     access / modification by the host program.  For example, the
  126.     Buf_REGION pointers point to the string buffer for the associated
  127.     string gadget after it is created so you do not have to figure
  128.     it out.
  129.  
  130.     Variables are generated for each gadget based on its REGION name,
  131.     denoted as %% below:
  132.  
  133.     NG_%%        These #define's yield a pointer to the proper
  134.             NewGadget structure from NGAry based on the
  135.             REGION name.
  136.  
  137.     NGAry        Array of NewGadget structures, ng_VisualInfo and
  138.             ng_TextAttr initialized by InitGads() call (for now,
  139.             eventually this will be specifiable from the editor)
  140.  
  141.     GAD_%%        A #define representing the GadgetID for a given
  142.             gadget.  Eventually you will be able to specify
  143.             a #define of your own to offset all the id's.
  144.  
  145.     Gad_%%        A pointer to the gadget after creation, useful
  146.             when making GT_SetGadgetAttrs() calls.
  147.  
  148.     Buf_%%        A pointer to the string buffer (ENTRY) after
  149.             it is created.
  150.  
  151.     DefText_%%    A pointer to the default text, or set to NULL.
  152.             May be modified before init.  Only applies to
  153.             ENTRY (string) gadgets.
  154.  
  155.     NodeAry_%%    If any items are specified for a SELLIST or
  156.             CYCLE, they are stored in this array, with
  157.             Succ and Pred fields linked together and to
  158.             the List_%% list.
  159.  
  160.     SelNo_%%    LONG variable (SELLIST, CYCLE), set to preselected
  161.             item number.
  162.  
  163.     List_%%     A LIST structure (SELLIST), already initialized
  164.             to either an empty list or linked into a
  165.             NodeAry_%% array of nodes.  May be modified
  166.             before the gadget is created or afterwords,
  167.             following gadtools guidelines.
  168.  
  169.     Ary_%%        A char ** array pointer (CYCLE), preset to the
  170.             cycle specification.  Points to StatAry_%%.  The
  171.             reason this is simply a pointer to another
  172.             global array is to allow the host program to
  173.             modify it before creating the gadgets.
  174.  
  175.     StatAry_%%    holds static array (CYCLE) of char *'s.
  176.  
  177.     Other Defines
  178.  
  179.     WIN_LEFT    window placement parameters.  These parameters
  180.     WIN_TOP     generate a window of exactly the same screen
  181.     WIN_WIDTH    positioning and dimensions as was last saved.
  182.     WIN_HEIGHT
  183.  
  184.     Routines
  185.  
  186.     GList = InitGads(Scr)
  187.     (void)  FreeGads()
  188.  
  189.  
  190.     (4) NOTES
  191.  
  192.     Many GADTOOLS types / flags are as yet unsupported.
  193.  
  194.     I intend to change the variable naming conventions so as to support
  195.     linking with multiple TPLEDIT generated object files, including
  196.     separating out the #include's and #define's.  I will retain
  197.     single-application mode variable-naming conventions as an option.
  198.  
  199.     SOURCE CODE:    Source code generated by TPLEDIT should be
  200.     completely portable.  However, the example TEST code and
  201.     TPLEDIT source is DICE specific in that it assumes all libraries
  202.     will be openned automatically.
  203.  
  204.     Other compilers will most likely generate undefined symbol
  205.     errors during linking.    In fact, DICE may even do so if you
  206.     do not have the absolute latest version (I just added some
  207.     of the below to the auto library).  Shouldn't be a big deal
  208.     though...
  209.  
  210.         intuition.library
  211.         graphics.library
  212.         asl.library
  213.         gadtools.library
  214.  
  215.     The test program makes similar assumptions.  I will eventually do
  216.     this myself so as to make the program portable.  Please note that
  217.     this is an ALPHA release.
  218.  
  219.  
  220.     I may not have a lot of time to refine this program and invite
  221.     anybody who wishes to take it on as a major project to contact
  222.     me!  I only ask that the general design philosophy be retained
  223.     and the code placed in the public domain.
  224.  
  225.     BIX:        mdillon
  226.     INTERNET:   dillon@overload.Berkeley.CA.US
  227.  
  228.     -----------------------------------------------------------------------
  229.  
  230.                     TECH NOTES
  231.  
  232.  
  233.