home *** CD-ROM | disk | FTP | other *** search
/ The Best of Mecomp Multimedia 2 / MECOMP-CD-II.iso / amiga / programmieren / gui / gadutil / docs / gadutil_dev.readme < prev    next >
Encoding:
Text File  |  1997-10-05  |  18.5 KB  |  423 lines
  1. Short:    GUI creation library - developer v37.10
  2. Author:   P-O Yliniemi / Staffan Hämälä
  3. Uploader: peoyli@algonet.se (P-O Yliniemi)
  4. Version:  37.10
  5. Type:     dev/gui
  6. Replaces: dev/gui/gutil_dev_379.lha
  7.  
  8. Some examples may have weird names (for those who don't understand swedish),
  9. and some text files may be in swedish. This will be fixed in a later release.
  10. Contact me if there is any problem using any of the examples or the docs.
  11.  
  12. Two versions of the .library file is available with this developer package.
  13. One is the "normal" library, and the other one prints out a lot of info when
  14. executing a program that uses GadUtil.
  15.  
  16. If you need to use the debug version, rename the normal version in libs:,
  17. copy the debug version to libs, and rename it to gadutil.library. Reverse
  18. this to change back to the normal version. Don't forget to "flush" all
  19. unused libraries or reboot before testing the program again.
  20.  
  21. All necessary files for Asm & C development are included.
  22.  
  23. Changes overview:
  24. ~~~~~~~~~~~~~~~~~
  25. * 37.10 (28-Sep-97)
  26.         GU_NoCreate now works on individual gadgets. Useful to create invisible
  27.         gadgets that helps you place the other objects in the window.
  28.  
  29.         6 new tags added that will allow you to save the object's calculated left,
  30.         top, right and bottom edge, as well as the gadget's width and height.
  31.  
  32.         E includes added to the distribution.
  33.  
  34. * 37.9  (22-Dec-96)
  35.         6 new tags added for the help functions. It is now possible to set a default
  36.         help text that will be shown if no gadget is under the pointer.
  37.  
  38.         GU_DefWTitle            - default window title
  39.         GU_DefLocWTitle         - localized window title
  40.         GU_DefSTitle            - default screen title
  41.         GU_DefLocSTitle         - localized screen title
  42.         GU_DefHelpText          - default help text
  43.         GU_DefLocHelpText       - localized help text
  44.  
  45.         A little bug removed from the help routines. Versions beore 37.9 could
  46.         display two different help text at the same time (in different gadgets or
  47.         the screen or window title).
  48.  
  49.         A new include file is included in the distribution now. Now it should be
  50.         possible to compile the examples with older versions of the system include
  51.         files (OS 2.0x includes are supported now)
  52.  
  53.         A third archive with the HTML version of the GadUtil documentation is
  54.         included in the distribution now. Also included with this archive is some
  55.         pictures of applications using GadUtil.
  56.  
  57.         The distribution has changed a bit, resulting in that the archive with all
  58.         files became smaller (developer archive only).
  59.  
  60. * 37.8  (15-Jul-96)
  61.         Some bug fixes in the new help functions. If 0 was used as data on a GU_HelpText
  62.         tag with a gadget that shows the help text in the window's or screen's title,
  63.         there were some enforcer hits
  64.  
  65.         Deleted the separate autodoc files. Appended some information on the contents of
  66.         the GU_Public structure to the autodocs. More info about SCRTITLE_HELP and
  67.         WINTITLE_HELP was also appended.
  68.  
  69.         Changed the help function so that all gadgets and title bars that are used to
  70.         display help strings is cleared if the mouse pointer is outside all gadgets that
  71.         have help texts.
  72.  
  73. * 37.7  (12-Jul-96)
  74.     Bug fix in the prototype for GU_ChangeStr (two parameters was mixed up).
  75.  
  76.     GU_ChangeStr now works for both STRING_KIND and TEXT_KIND gadgets. If the
  77.     gadget isn't a STRING or TEXT gadget nothing is done.
  78.  
  79.     Bug fix in GU_CoordsInGadBox function. The register D3 was trashed in all
  80.     earlier versions of GU.
  81.  
  82.     Three new tags allows any STRING or TEXT_KIND gadget to show a (localized)
  83.     help text for each gadget in the window. These tags also works with the
  84.     special gadgets (BEVELBOX, LABEL, PROGRESS). The gadgets attached to the
  85.     window is scanned in sequential order. If a BEVELBOX_KIND gadget matches
  86.     the pointer position, this gadget's help string will have the lowest
  87.     priority. If another BEVELBOX is found inside this, the help string for
  88.     that one will be used if there is no gadget inside that box. The help
  89.     text can also be displayed in the window/screen title.
  90.  
  91.     The TEXT_KIND, STRING_KIND, NUMBER_KIND and INTEGER_KIND gadget's current
  92.     value can now be read from the gu_Active field in the structure    that
  93.     gg_UserData points to.
  94.  
  95. * 37.6  (15-Jun-96)
  96.     gu_Active in the structure that gg_UserData points to was not updated
  97.     when using any routine that used GU_SetGadgetAttrsA(). Now it checks
  98.     the gu_Active value to see if it is out of the gadget's limits.
  99.  
  100.     gng_Flags and gng_GadgetText is now cleared before creation of every
  101.     new gadget.
  102.  
  103.     The LAYOUTA_Spacing tag for LISTVIEW_KIND gadgets is now used to
  104.     determine the height of the gadget. If the height of a gadget should
  105.     be about 4 lines (GU_HeightFactor, 4), the height of the gadget is
  106.     calculated to 4*(font height+value of LAYOUTA_Spacing tag). The same
  107.     method is used for the GU_AddHeiLines tag.
  108.  
  109.     Hotkeys for LISTVIEW_KIND gadgets works as they should again. In v37.5
  110.     of GadUtil (and probably some earlier ones), the listview didn't scroll
  111.     down when you selected the next entry.
  112.  
  113.     Inserted pragmas and prototypes for tagcalls (pragmas only for SAS/C).
  114.     It is possible to create stub routines for the tagcalls for other
  115.     compilers by using fd2pragma 2.0.
  116.  
  117.     Inserted links to the include files in the index file for GadUtil.guide.
  118.  
  119. * 37.5  (29-May-96)
  120.     Bug in PROGRESS_KIND gadget removed. If the gadget was set to
  121.     show x/0 (also 0/0), a division by zero was done.
  122.  
  123.     Two new constants added to the include files: GADUTIL_VER and
  124.     GADUTIL_REV.
  125.     
  126.     Bug fixes in test (demo) programs. The FPF_DISKFONT flag in the
  127.     TextAttr structure was unset in all demo programs. Replaced the
  128.     manual version check in the demo programs with the GadUtil function
  129.     GU_CheckVersion. Removed unnecessary IDCMP flags from the demo
  130.     programs and replaced GadTools IDCMP with the GU_MinimumIDCMP tag.
  131.  
  132. * 37.4  (14-May-96)
  133.     Created a new gadget kind: LABEL_KIND. This gadget kind is used
  134.     to place text relative to other gadgets, bevel boxes, and other
  135.     texts. Can use the same type of shadows that the text for the
  136.     bevel box.
  137.  
  138.     Implemented a new function in the library: GU_CloseFont. Works
  139.     like graphics CloseFont, but takes the parameter in A0 instead
  140.     of A1.
  141.  
  142.     Replaced the list sort routine with a new one that sorts better.
  143.  
  144.     Wrote a new document, "GadUtil.index", that have a list over all
  145.     gadutil functions, sorted by what they do. There are also some
  146.     shortcuts to all tags for gadutil's own gadget kinds.
  147.  
  148.     Created two new flags for BEVELBOX_KIND and LABEL_KIND:
  149.     BB_3DTEXT - can be used as a replacement for GUBB_3DText, TRUE
  150.     LB_3DTEXT - can be used as a replacement for GULB_3DText, TRUE
  151.     
  152. * 37.3  (10-May-96)
  153.     Enforcer hits fixed in the code that handles the GU_AdjustLeft
  154.     and GU_AdjustRight tags.
  155.  
  156.     A new function to clear the inner part of a window was added.
  157.  
  158.     A new function to size (and move, if necessary) a window was
  159.     added.
  160.  
  161.     Bug fix in assembly language include file.
  162.  
  163. * 37.2  (02-May-96)
  164.     Started programming in StormC and did some tests with the library,
  165.     noticed that there was a couple of errors in some include files.
  166.  
  167.     GU_UpdateProgress was wrongly specified in the FD/clib files.
  168.     The output of GU_GetGadgetPtr was specified as (struct Gadget *),
  169.     this is now corrected.
  170.  
  171.     Included an example in C that uses the PROGRESS_KIND gadget.
  172.  
  173. * 37.1  (01-May-96)
  174.     IMAGE_KIND gadget bug fix. The color of the unselected image of
  175.     the gadget was wrong, if the image used more than 4 colors.
  176.  
  177. * 37.0  (29-Apr-96)
  178.     A new function that checks the library's revision added.
  179.     Two new tags added: GU_FractWidth and GU_FractHeight. Suggested
  180.     by Morten Amundsen.
  181.  
  182.     Some small bug fixes in 'C' include files (unterminated comments).
  183.     Cleaned up BetterTest.c a bit (removed some {}). Bug fix on the
  184.     last line of the example (GT_ReplyIMsg -> GU_ReplyIMsg).
  185.  
  186.     Added support for StormC in both installer script and include-
  187.     file installer. Created dictionary for StormC, so that all words
  188.     that belongs to GadUtil (functions, tags and constants) is shown
  189.     in another color.
  190.  
  191. * 36.60 (24-Feb-96)
  192.     Uses the screen's font as the gadget font if no GU_DefTextAttr or
  193.     GU_TextAttr tag is used. Bug fix from v36.59. Changed some docs,
  194.     assembled all examples,    changed installation scripts.
  195.  
  196. * 36.59 (06-Jan-96)
  197.     More docs completed (all docs, finally). Bug fix in the GU_AutoWidth,
  198.     GU_AdjustLeft and GU_AdjustRight tags. The underscore character was
  199.     counted as a normal one. This made gadgets without hotkeys one char
  200.     smaller than other gadgets. A new function that sorts one or two
  201.     lists was added. Some new constants added in include files.
  202.     Changed GU_MinimumIDCMP to support hotkeys. Changed PROGRESS_KIND
  203.     to use GU_GadgetText and GU_LocaleText. Uses the screen's font as
  204.     the gadget font if no GU_DefTextAttr or GU_TextAttr tag is used.
  205.  
  206. * 36.58 (01-Jan-96)
  207.     SLIDER_KIND and SCROLLER_KIND gadgets returned wrong result in
  208.     im->Code if the gadget was changes using the hotkey. Bug reported
  209.     by Lukasz Szelag.
  210.  
  211. * 36.57 (10-Dec-95)
  212.     Some more docs finished. A memory loss bug was fixed.
  213.  
  214. * 36.56 (10-Oct-95)
  215.     Changed some routines, so that hotkeys can't be used on disabled
  216.     gadgets. Made it possible to disable IMAGE_KIND, FILE_KIND and
  217.     DRAWER_KIND gadgets.
  218.  
  219. * 36.55 (30-Sep-95)
  220.     Bug fix in the hotkey part of the library. Wrong code were sent back
  221.     when using GU_LabelHotkey with a LISTVIEW_KIND gadget. A new gadget
  222.     kind was created, PROGRESS_KIND.
  223.  
  224. * 36.54 (06-Jul-95)
  225.     Added support for GU_AutoWidth to CYCLE_KIND gadgets.
  226.  
  227. * 36.53 (05-Jul-95) 
  228.     3 new tags and 4 new flags was added for the BEVELBOX_KIND gadget.
  229.     BEVELBOX_KIND gadgets can now have a shadow added to the text in the
  230.     border. The "sun" can be placed in 4 different places. GU_MinimumIDCMP
  231.     tag was added.
  232.  
  233. * 36.52 (25-Jun-95)
  234.     First public release. Some new flags for the BEVELBOX_KIND gadget was
  235.     added. Supports a total of 100 bevelbox kinds.
  236.  
  237.                                           P-O 961222
  238.                                           ~~~~~~~~~~
  239. ------------------------------------------------------------------------------
  240.  
  241.                             GadUtil.library v37.9
  242.                             ~~~~~~~~~~~~~~~~~~~~~
  243.     GadUtil is another gui library which main goal was to make it easy to
  244.     create font sensitive user interfaces. The library has grown away from
  245.     this main goal, and become another useful-routine-library.
  246.  
  247.   ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
  248.     Distribution:
  249.  
  250.         1) Distribution of this library is allowed in two ways:
  251.              ¹) Only the .library file(s)
  252.              ²) The complete distribution
  253.  
  254.         2) Programmers of totally free software can use and distribute this
  255.           library for free.
  256.  
  257.         3) Programmers of Shareware, Licensware, commercial products and other
  258.            programs that the programmer get any kind of profit from shall send
  259.            a fully working (and registered) copy of the program and its docs to
  260.            us. All larger updates of the program should also be sent to us.
  261.           
  262.         4) Programmers of non-free software not covered by 1) and 2) (my Diskware
  263.            concept belongs to this group) shall be treated as in 3) (a fully
  264.            working and registered copy...).
  265.  
  266.         5) All programs (except commercial products in some cases) must state
  267.            that gadutil.library is used. This may be done in either the About
  268.            requester or in the documentation, but best of all in both places.
  269.  
  270.            Demonstration programs for gadutil.library (that includes the full
  271.            source) may be distributed without this note.
  272.  
  273.            Example for inclusion in About requester:
  274.  
  275.                 "This program uses gadutil.library, which
  276.                  is Copyright © 1994-1996 by P-O Yliniemi
  277.                  and Staffan Hämälä."
  278.  
  279.         6) All localized programs that uses this library should include the
  280.            .ct file(s) to allow anyone to translate that program into their
  281.            own language.
  282.  
  283.  
  284.   ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
  285.     Below is a list of some of the main functions covered by this library.
  286.  
  287.     * FAST (NO OR VERY SMALL DIFFERENCE AGAINST GADTOOLS) AND SMALL (LESS THAN 13k).
  288.       WRITTEN IN ASSEMBLY LANGUAGE. NO F*CKING 'C' or any other slow language!
  289.  
  290.     * Font adaptive. Use any of the system fonts and most other fonts for
  291.       gadgets, texts and menus. All gadgets are placed relative to each
  292.       other, but can be placed at absolute positions (needed for the first
  293.       gadget).
  294.  
  295.     * No need to use GIMMEZEROZERO windows, as this is automatically handled
  296.       by the library. If you specify a gadget position of 10,10 the gadget
  297.       will be placed at 10,10 within the window's border.
  298.  
  299.     * Localized. It is really easy to localize all your (new) programs by
  300.       using this library. Functions and macros for creating localized menus
  301.       are supplied.
  302.  
  303.     * Both assembly and 'C' language support. This is one of the things that is
  304.       missing in most of the other gui libraries. Some extra macros are defined
  305.       for assembly language users, and will make the gadget and menu creating
  306.       process even more easy.
  307.  
  308.     * All GadTools gadgets are supported. Some extra functions are provided
  309.       for ListViews. BUTTON_KIND (and IMAGE_KIND) gadgets have some extra tags,
  310.       including a toggle-select option.
  311.  
  312.       6 extended gadget types are handled by the library:
  313.     
  314.         · FILE_KIND     - gadget for selecting a file.
  315.  
  316.         · DRAWER_KIND   - gadget for selecting a drawer. Most programs also
  317.                          use this gadget for file selection.
  318.  
  319.         · IMAGE_KIND    - uses an intuition image for the gadget. Can use
  320.                           different images for selected and non-selected state.
  321.  
  322.         · BEVELBOX_KIND - gadtools bevelboxes, with some extensions. All
  323.                           gadtools bevelboxes are supported (even with v37).
  324.                           Extensions allows text to be placed above, in or below
  325.                           the upper line of the box. All kinds can be inverted.
  326.  
  327.                           New for v36.52: Bevelbox text placement extended.
  328.                           3 new placements available together with the old
  329.                           ones: centered, left adjusted & right adjusted.
  330.  
  331.                           BFT_BUTTON   - GT v37 BUTTON_KIND border
  332.                           BFT_RIDGE    - GT v37 STRING_KIND border
  333.                           BFT_DROPBOX  - GT v39 BBFT_ICONDROPBOX border
  334.                           BFT_HORIZBAR - A horizontal shadowed line
  335.                           BFT_VERTBAR  - A vertical shadowed line
  336.  
  337.                           This makes it a total of 100 bevel box types. The bevel
  338.                           boxes are treated as gadgets by the library, and you
  339.                           can obtain the structure for the bevelbox in the same
  340.                           way as you get the gadget pointer.
  341.  
  342.                           New for v36.53: Added optional shadow on bevel box text.
  343.                           The shadow has a selectable color/pen and the "sun" can
  344.                           be placed in four different positions.
  345.  
  346.         · PROGRESS_KIND - progress indicator gadget. Background and fill color
  347.                           can be selected. Supports values up to 4.294.967.295,
  348.                           but maximum value should not exceed 4.294.967.295/width.
  349.                           v36.55.
  350.  
  351.     · LABEL_KIND    - a text label that can be placed relative to other texts,
  352.               gadgets, bevelboxes and progress indicators.
  353.  
  354.     * Can create the minimum required IDCMP mask so that all gadgets works.
  355.  
  356.     * A new OpenFont (graphics.library and diskfont.library replacement) is supplied.
  357.       This function will open any font (from RAM, ROM or load it from disk).
  358.  
  359.     * Functions for listviews include adding nodes (memory for the string is
  360.       allocated by the function), counting nodes, getting node pointers, clearing
  361.       a listview, attach and detach lists, moving nodes up and down. A function
  362.       that allows you to sort one or two lists is included from v36.59.
  363.  
  364.     * No need to open gadtools.library anymore, since all gadtools functions are
  365.       provided through this library. Some (the most useable) functions from locale
  366.       library are also provided by gadutil.
  367.  
  368.     * Many libraries are opened through gadutil.library, and these library bases
  369.       are available for your own use (you don't have to open or close some libs).
  370.  
  371.     * All gadgets are created using tag lists. Every next gadget will use the
  372.       previous gadgets values as defaults. Only one call to the gadget making
  373.       routine is needed for every gadget list.
  374.  
  375.     * All gadgets can have their own hotkey. No extra work is needed by the
  376.       programmer (only one extra tag).
  377.  
  378.     * All gadgets (and bevelboxes, texts and progress displays) can have a help
  379.       string attached to it. If the pointer is moved above that object, a
  380.       selectable string or text gadget will be used to display the help string.
  381.       The help string can be localized.
  382.  
  383.     * Distributed with lots of examples, mostly in assembly language, but also
  384.       in 'C'.
  385.  
  386.     * Other functions include:
  387.  
  388.         · Status change for toggle select buttons.
  389.  
  390.         · String change for STRING and TEXT_KIND gadgets.
  391.  
  392.         · Disable functions for all gadget kinds (new for 36.56).
  393.  
  394.         · Routines to set up a busy-pointer (available for both v37 and v39). These
  395.           routines also blocks the input to the main window of the program.
  396.  
  397.         · Routine to check if the mouse pointer is within a gadgets box. Useful
  398.           for mouse-position sensitive appwindows.
  399.  
  400.         · Bevelbox and window refreshing functions.
  401.  
  402.     · Functions to clear and size/move windows
  403.  
  404.     * FAST (NO OR VERY SMALL DIFFERENCE AGAINST GADTOOLS) AND SMALL (LESS THAN 13k).
  405.       WRITTEN IN ASSEMBLY LANGUAGE. NO F*CKING 'C' or any other slow language!
  406.  
  407.  
  408.   ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
  409.   ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
  410.         Per-Olof Yliniemi                           Staffan Hämälä
  411.         Aspvägen 4E                                 Vegagatan 2 3TR
  412.         SE-957 32 Övertorneå                        SE-172 34 Sundbyberg
  413.         SWEDEN                                      SWEDEN
  414.  
  415.         email:                                      email:
  416.           peoyli@algonet.se                           staham@algonet.se
  417.  
  418.         phone:
  419.           +46-(0)927-12293
  420.  
  421.   ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
  422.   ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
  423.