home *** CD-ROM | disk | FTP | other *** search
/ Frozen Fish 1: Amiga / FrozenFish-Apr94.iso / bbs / alib / d5xx / d583 / tpledit.lha / TplEdit / TplEdit.doc < prev    next >
Text File  |  1992-01-04  |  16KB  |  379 lines
  1.  
  2.  
  3.  
  4.             ›1mNote****************************************************
  5.             If you paid more than 5 $US/DM/£UK for a disk including
  6.             this program - your dealer is a thief and you're a fool.
  7.             **************************************************Koessi›0m
  8.  
  9.  
  10.                             ›1mTplEdit›0m.DOC
  11.  
  12.                             V 2.00 BETA
  13.  
  14.     ›1mTplEdit›0m is a ›1mgadtools›0m template editor used to edit display templates
  15.     that can then be compiled into a program.
  16.  
  17.             ›1mTplEdit›0m ONLY RUNS UNDER 2.0 !   THIS IS A BETA
  18.  
  19.                         Additional code done by
  20.                   Koessi 11.1991 - phone Germany 02192 7630
  21.               This is version 2.0. Placed in the public domain.
  22.             Parts of this docfile still reflect 1.0 situation. \8-)
  23.  
  24.     ›1mUSAGE›0m
  25.         from Cli    you can start immediately with a project if you add
  26.                     its filename as a parameter on the commandline.
  27.                     e.g.  "›1mTplEdit›0m tplcontrol"
  28.  
  29.         from WorkBench
  30.                     you can start immediately with a project if you
  31.                     doubleclick on that projects icon with its default
  32.                     tool set to ›1mTplEdit›0m or shift-click it together
  33.                     with the ›1mTplEdit›0m-icon.
  34.                     In WorkBench-mode ›1mTplEdit›0m will create a projecticon
  35.                     when first time saving a project.
  36.  
  37.  
  38.     ›1mMENUS›0m
  39.  
  40.       Project
  41.         Save        save database.
  42.  
  43.         SaveC...    save database as C code.
  44.           Excl Main() only includable.
  45.           Incl Main() completely standalone to test.
  46.                     See section SOURCE CODE GENERATION for further information.
  47.  
  48.         SaveAs      save database as (you pick the name)
  49.  
  50.         SaveAsC...  save C source as (you pick the name)
  51.           Excl Main() only includable.
  52.           Incl Main() completely standalone to test.
  53.                     See section SOURCE CODE GENERATION for further information.
  54.  
  55.         Load        load a new project.
  56.  
  57.         Merge       merge another project into the actual one.
  58.  
  59.         Quit        quit program - same as closing any window.
  60.  
  61.       Gadgets       Specify the appropriate gadget type, do not specify
  62.                     ›3mInvisible›0m(not implemented yet).
  63.  
  64.       Edit
  65.         LockLinkTo  Create a ›3mListView›0m and ›3mString›0m gadget.  Select the
  66.                     ›3mListView›0m gadget so that it's information is displayed
  67.                     in the control window.  Then select the LOCKTO menu
  68.                     option.  Finally, click on the ›3mString›0m gadget.
  69.                     Due to bugs in ›1mgadtools›0m, the ›3mString›0m gadget's dimensions
  70.                     will be forced to conform.
  71.                     To create a specific size for the ›3mListView›0m try different
  72.                     values of Buf/Space.
  73.  
  74.         UnLockLink  To unlock a link select the ›3mListView›0m gadget so that it's
  75.                     information is displayed in the control window.  Then
  76.                     select this menu option.
  77.  
  78.         SortRegions Sorts created gadgets and ›3mBevelBoxes›0m to ease hitting them.
  79.                     NOTE: This option changes the order of building the gadgets
  80.                     and various defines ! So if you are already working with
  81.                     other codefiles that depend on the generated code you MUST
  82.                     recompile them all !
  83.  
  84.       Snap          The mouse coordinates may be snapped to various
  85.                     intervals.
  86.  
  87.         NOTE:   ›1mTplEdit›0m is only able to load database format files which
  88.                 are saved via SAVE or SAVEAS.  ›1mTplEdit›0m cannot reverse
  89.                 engineer C source files it generates.
  90.                 ›1mTplEdit›0m 2.0 can still read database files done with
  91.                 version 1.0 - but some minor errors may appear.
  92.  
  93.                 ›1mTplEdit›0m will warn you if you quit without saving, or try
  94.                 to load a new project without having saved the old one.
  95.  
  96.         Menus can be accessed from either window.
  97.  
  98.     ›1mTPL CONTROL WINDOW:›0m
  99.  
  100.         The control window allows you to edit gadgets in the project window.
  101.  
  102.         Actions:
  103.  
  104.           NEW
  105.             Press this to create a brandnew one.
  106.             Move the mouse to the project window and specify a square
  107.             by placing the mouse in the starting position, holding down
  108.             the select while moving the mouse to the ending position and
  109.             release the mouse.  The gadget now exists.
  110.           COPY
  111.             Press this and klick on an already created gadget in the project
  112.             window. It will be doubled (the region name will have a numeric
  113.             appendix) and you can move the original directly to its new place.
  114.           MOVE
  115.             Press this and move the gadgets you select in the project window.
  116.           SIZE
  117.             Press this and resize the gadgets you select in the project window.
  118.             Sizing always modifies the lower right hand corner of an existing
  119.             gadget. ›3mCheckBox›0m and ›3mMX›0m gadgets cannot be sized!
  120.           EXCL
  121.             Press this after selecting some gadget in the project window.
  122.             The next gadget you select will belong to the same ExclGroup as the
  123.             last one. If they are ›3mButton›0m or ›3mCheckBox›0m they will exclude each
  124.             other from staying selected; others will disable eachother.
  125.             To free a gadget from any exclusion, exclude it with itself. \8-)
  126.           DEL
  127.             Press this and delete the next gadget you select in the project
  128.             window.
  129.           TEST
  130.             Press this to play around in the project window.
  131.  
  132.         Gadgets:
  133.             Specify the appropriate gadget type, do not specify ›3mInvisible›0m
  134.             (not implemented yet).
  135.  
  136.         TextPos:
  137.             This will specify text placement if it applies.
  138.             It also specifies the GTSL_LevelPlace for ›3mSlider›0m-gadgets
  139.  
  140.         Values:
  141.           MaxVal
  142.             This slider will specify the GTSL_Max for ›3mSlider›0m-gadgets
  143.             and the maximum legal colournumber for ›3mPalette›0m-gadgets.
  144.             It also shows you the maximum possible value for the default
  145.             selection in ›3mListView›0m, ›3mMX›0m and ›3mCycle›0m gadgets.
  146.           Buf/Space
  147.             This slider will specify the GTSL_MaxLevelLen for ›3mSlider›0m-gadgets
  148.             and the spaces set between the items of ›3mListView›0m and ›3mMX›0m gadgets.
  149.           DefVal
  150.             This slider will specify the GTSL_Level for ›3mSlider›0m-gadgets,
  151.             the default selection in ›3mListView›0m, ›3mMX›0m, ›3mCycle›0m and
  152.             ›3mPalette›0m-gadgets.
  153.  
  154.         List of Items:
  155.             You might want to specify a non-empty string list for ›3mListView›0m,
  156.             ›3mMX›0m or ›3mCycle›0m gadgets. This is done by typing in the ›3mString›0m-gadget
  157.             and hitting return.
  158.           add
  159.             The same as hitting return.
  160.           up
  161.             This will sort the selected item one step higher.
  162.           down
  163.             This will sort the selected item one step lower.
  164.           del
  165.             This will delete the selected item.
  166.  
  167.         SpecialFlags:
  168.           CHECKED
  169.             Preselect ›3mMX›0m or ›3mButton›0m gadgets.
  170.           BORDER
  171.             Draw a border around ›3mText›0m or ›3mNumber›0m gadgets.
  172.           RECESSED
  173.             Draw a ›3mBevelBox›0m in recessed manner.
  174.           HIGHLABEL
  175.             Highlight the labelstring of gadgets using one.
  176.           VERTICAL
  177.             Select vertical orientation for ›3mSlider›0m or ›3mScroller›0m gadgets.
  178.           READONLY
  179.             Make the items of a ›3mListView›0m gadget uneditable. They will be
  180.             shown in an automatically created ›3mText›0m gadget.
  181.           IMMEDIATE
  182.           RELVERIFY
  183.             Sets the corresponding flags for ›3mSlider›0m or ›3mScroller›0m Gadgets.
  184.           DISABLED
  185.             Makes the gadget appear ghosted.
  186.  
  187.         Region Name:
  188.             You MUST specify a REGION name.
  189.             EACH GADGET MUST HAVE A UNIQUE REGION NAME!
  190.  
  191.         Label/Format:
  192.             Edit the labelstring you want to apply to your gadget.
  193.             If the gadget is a ›3mSlider›0m, this can be a printf-styled format
  194.             string (default: "%4ld"). the "%ld" will be replaced by decimal
  195.             digits by default. The function DispFunc() is declared in the
  196.             produced code to perform this.
  197.  
  198.         Default Str:
  199.             Edit the default string you want to apply to your ›3mString›0m gadgets.
  200.  
  201.         UPDATE
  202.             You can change various parameters, including the items in a
  203.             select/cycle list, by clicking on the appropriate gadget from
  204.             TEST mode, making the appropriate modifications in the TPL CONTROL
  205.             window, and then hitting UPDATE.
  206.  
  207.             WARNING WARNING:  To copy a ›3mString›0m gadget's info to the
  208.             TPL CONTROL window you must hit RETURN in the window after
  209.             activating it!  Otherwise you might update the wrong gadget's info.
  210.  
  211.         NOTE: ›3mListView›0m, ›3mMX›0m, ›3mText›0m and ›3mNumber›0m gadgets cannot be deactivated
  212.               and so their hit boxes remain active.  There is a two pixel
  213.               boundary around every gadget which you can click on to 'grab'
  214.               such gadgets, or grab ›3mString›0m gadgets without clicking in them.
  215.               Use SortRegions in the menus to cleanup - especially to push
  216.               ›3mBevelBoxes›0m (borders) into the back.
  217.  
  218.     ›1mSOURCE CODE GENERATION:›0m
  219.  
  220.               To generate source code select the SaveC or SaveAsC menu options.
  221.  
  222.         "Excl Main()" will create only includable files.
  223.         "Incl Main()" will create completely standalone code to test.
  224.  
  225.               The C source files generated are named by appending
  226.               "_defs.h" and ".c" at the project's name denoted as xxx below:
  227.  
  228.       "xxx_defs.h"  - the headerfile
  229.               If standalone code is created, this will do proper includes.
  230.               It contains variables references for easy access / modification
  231.               by the host program.
  232.               For example, the Buf_REGION pointers point to the stringbuffer
  233.               for the associated ›3mString›0m gadget after it is created so you do
  234.               not have to figure it out.
  235.  
  236.         Variables are generated for each gadget based on its REGION name.
  237.         denoted as %% below:
  238.  
  239.         NG_%%           These #define's yield a pointer to the proper
  240.                         NewGadget structure from NGAry based on the
  241.                         REGION name.
  242.  
  243.         NGAry           Array of NewGadget structures, ng_VisualInfo and
  244.                         ng_TextAttr initialized by InitGads() call (for now,
  245.                         eventually this will be specifiable from the editor)
  246.  
  247.         GAD_%%          A #define representing the GadgetID for a given
  248.                         gadget.  Eventually you will be able to specify
  249.                         a #define of your own to offset all the id's.
  250.  
  251.         Gad_%%          A pointer to the gadget after creation, useful
  252.                         when making GT_SetGadgetAttrs() calls.
  253.  
  254.         Buf_%%          A pointer to the string buffer (›3mString›0m) after
  255.                         it is created.
  256.  
  257.         NodeAry_%%      If any items are specified for a ›3mListView›0m, ›3mMX›0m or
  258.                         ›3mCycle›0m, they are stored in this array, with
  259.                         Succ and Pred fields linked together and to
  260.                         the List_%% list.
  261.  
  262.         List_%%         A LIST structure (›3mListView›0m), already initialized
  263.                         to either an empty list or linked into a
  264.                         NodeAry_%% array of nodes.  May be modified
  265.                         before the gadget is created or afterwords,
  266.                         following ›1mgadtools›0m guidelines.
  267.  
  268.         Ary_%%          A char ** array pointer (›3mCycle›0m, ›3mMX›0m), preset
  269.                         to the cycle specification.  Points to
  270.                         StatAry_%%.  The reason this is simply a
  271.                         pointer to another global array is to allow
  272.                         the host program to modify it before creating
  273.                         the gadgets.
  274.  
  275.         StatAry_%%      holds static array (›3mCycle›0m, ›3mMX›0m) of char *'s.
  276.  
  277.         Other Defines
  278.  
  279.         WLEF            window placement parameters.  These parameters
  280.         WTOP            generate a window of exactly the same screen
  281.         WWID            positioning and dimensions as was last saved.
  282.         WHEI
  283.  
  284.         GLEF_%d         gadget placement parameters.
  285.         GTOP_%d
  286.         GWID_%d
  287.         GHEI_%d
  288.  
  289.         BLEF_%d         BevelBorder placement parameters.
  290.         BTOP_%d
  291.         BWID_%d
  292.         BHEI_%d
  293.  
  294.  
  295.       "xxx.c"           If InclMain() is chosen from the menus this
  296.                         generated c-sourcefile will include "xxx_defs.h"
  297.                         and can simply be compiled (using DICE) like:
  298.  
  299.                           dcc xxx.c -otest -2.0
  300.  
  301.                         If ExclMain() was chosen it will include "defs.h"
  302.                         that has to be supported by the host program.
  303.                         "defs.h" should also contain
  304.  
  305.                           #include "xxx_defs.h"
  306.  
  307.                         The host program should declare the following
  308.                         variables:
  309.                           Window  *EWin;
  310.                           struct   VisualInfo *VisInfo;
  311.                           Screen  *Src;
  312.  
  313.                         The following routines are declared in xxx.c:
  314.  
  315.                           void    FreeGads(void);
  316.                           int     InitGads(void);
  317.                           void    drawborders(void);
  318.                           __geta4 long DispFunc(Gadget *, WORD);
  319.  
  320.     ›1mNOTES›0m   /*  partly from Matt's version 1.0 */
  321.  
  322.         Some ›1mgadtools›0m types / flags are as yet unsupported.
  323.  
  324.         I intend to change the variable naming conventions so as to
  325.         support linking with multiple ›1mTplEdit›0m generated object files,
  326.         including separating out the #include's and #define's.  I will
  327.         retain single-application mode variable-naming conventions as
  328.         an option.
  329.  
  330.         SOURCE CODE:    Source code generated by ›1mTplEdit›0m should be
  331.         completely portable.  However, the example TEST code and
  332.         ›1mTplEdit›0m source is DICE specific in that it assumes all
  333.         libraries will be openned automatically.
  334.  
  335.         Other compilers will most likely generate undefined symbol
  336.         errors during linking.  In fact, DICE may even do so if you
  337.         do not have the absolute latest version (I just added some
  338.         of the below to the auto library).  Shouldn't be a big deal
  339.         though...
  340.  
  341.             intuition.library
  342.             graphics.library
  343.             asl.library
  344.             gadtools.library
  345.  
  346.         The test program makes similar assumptions.  I will eventually
  347.         do this myself so as to make the program portable.  Please note
  348.         that this is an BETA release.
  349.  
  350.  
  351.         I may not have a lot of time to refine this program and invite
  352.         anybody who wishes to take it on as a major project to contact
  353.         me!  I only ask that the general design philosophy be retained
  354.         and the code placed in the public domain.
  355.  
  356.         BIX:        mdillon
  357.         INTERNET:   dillon@overload.Berkeley.CA.US
  358.  
  359.     ›1mSOURCE›0m:       /*  updated to version 2.0 by Koessi 11.91 */
  360.         I have included the project "tplcontrol", that will produce
  361.         (using ExclMain() from SaveC-menu) exactly the files
  362.         "tplcontrol.c" and "tplcontrol_defs.h" which are used
  363.         for the whole design of the TPLCONTROL window.
  364.  
  365.                   /*  guess which was first ? \8-)  */
  366.  
  367.         Try "›1mTplEdit›0m tplcontrol" to play around.
  368.         Using InclMain() will produce standalone code resulting in
  369.         an executable like the supplied "test".
  370.         I don't have any access to SAS or Aztec Compilers, so I can't
  371.         check for compatibility.
  372.         Have Fun. Koessi.
  373.  
  374.     ›1mBUGS›0m:
  375.         When I resize the project-window, having a project just
  376.         loaded but no gadget yet selected my machine blacks out ...
  377.  
  378.  
  379.