home *** CD-ROM | disk | FTP | other *** search
/ Amiga MA Magazine 1998 #6 / amigamamagazinepolishissue1998.iso / coders / biblioteki / c_library / gadtools34 / docsenglish / gadtools34.doc < prev    next >
Text File  |  1998-05-21  |  12KB  |  280 lines
  1.  
  2.  
  3.  
  4.                   GadTools Library 34.1 and GTE.lib 1.0
  5.  
  6.                      by Massimo Tantignone (27/01/93)
  7.                            A MT Soft production
  8.  
  9.  
  10.  
  11.    1. INTRODUCTION
  12.  
  13.    Gadtools.library 34.1 is a 1.3-compatible version of the library with
  14. the same name normally present in the Kickstart 2.04 or higher.
  15.    To be precise, it's a shared library whose aim is to emulate the
  16. gadtools.library V37 and that works even under operating systems previous
  17. to 2.0, such as the OS 1.3.
  18.    GTE.lib is, instead, an object module linker library and performs the
  19. same task.
  20.    These two public domain libraries allow to write and/or use programs
  21. taking advantage even under 1.3 of the gadtools.library in the building and
  22. handling of a graphical user interface (as long as these programs don't
  23. require other 2.0-specific functions).
  24.  
  25.    Both libraries are dedicated mainly to programmers, which will be able
  26. to freely distribute gadtools.library 34.1 along with their programs, or
  27. to directly link the code of GTE.lib to these programs (using the linker).
  28.    If nevertheless there were in circulation already made programs using
  29. the gadtools.library AND NO OTHER 2.0 LIBRARY OR FUNCTION, these should
  30. also work after the installation of gadtools.library 34.1 into your
  31. Workbench 1.3's LIBS: directory (of course such programs can be found out
  32. only by trying them).
  33.    For that, gadtools.library 34.1 can come out useful also to the final
  34. user (but I doubt at the moment there be already such programs).
  35.    In the distribution directory of gadtools.library 34.1 and GTE.lib you
  36. find two test programs: one of them (TestLinked) was linked with GTE.lib
  37. and therefore contains the gadtools emulation code, the other (TestShared)
  38. uses instead the external gadtools.library. The first can be executed
  39. anytime, while to execute the other you need to install first the
  40. gadtools.library 34.1 as explained in the next paragraph (or run it under
  41. 2.0 or higher, but in that case it would use the REAL gadtools.library).
  42.    Note: with the exception of the format (shared library or linker
  43. library) the two libraries are ABSOLUTELY IDENTICAL in their working,
  44. as they were obtained from the same source code.
  45.  
  46.  
  47.    2. USAGE OF GADTOOLS.LIBRARY 34.1
  48.  
  49.    To use gadtools.library 34.1 you must only copy it into your Workbench
  50. 1.3's LIBS: directory (floppy or hard disk). Every program attempting to
  51. open the gadtools.library will work from that moment on even under 1.3 and
  52. it will open this library instead of the "true" one of the 2.0 operating
  53. system, without noticing any difference.
  54.    Obviously, under 1.3, the program must not make use of other libraries
  55. reserved to 2.0 different from the gadtools.library.
  56.    This library must NOT be instead copied into the LIBS: directory of
  57. a Workbench 2.0, as the 2.0 operating system already has its own
  58. gadtools.library.
  59.    Note: the library is distributed with the name "gadtools_34.library"
  60. for copyright reasons. After you have copied it into LIBS: you must
  61. rename it exactly to "gadtools.library", or else it won't work.
  62.    If you don't want to manually copy the library you can run the automatic
  63. installation script named "InstallGadTools34".
  64.  
  65.  
  66.    3. USAGE OF GTE.LIB
  67.  
  68.    GTE.lib, as it is a linker library, is useful only to programmers.
  69.    To take advantage of this library you must only write your source code
  70. as you would write it if you did use the true gadtools.library, but adding
  71. the prefix "NL_" to the name of each gadtools function you call.
  72.    Of course after the compilation you need to link with GTE.lib, and you
  73. will obtain a program working under any operating system and having an user
  74. interface that emulates the gadtools.library V37 under 1.x while directly
  75. uses it under 2.0.
  76.    By adding the prefix "EF_" instead of "NL_", the program will be
  77. slightly shorter but it will work in emulation mode EVEN under 2.0.
  78.    In both cases you need to #include into your source code the header
  79. file "nl_gadtools.h" supplied with GTE.lib.
  80.  
  81.  
  82.    4. WHY THESE TWO LIBRARIES EXIST
  83.  
  84.    The gadtools.library is certainly one of the most useful libraries
  85. supplied starting with the 2.0 version of the Amiga operating system, as
  86. it allows every program to implement graphical user interfaces that are
  87. consistent and similar to each other in the look and feel.
  88.    Alas, however useful, that library isn't compatible with the 1.3 (or
  89. lower) operating system, that, although obsolete, will be certainly used
  90. on the oldest Amigas for some years yet.
  91.    Every new application making use of the gadtools.library for its own
  92. user interface is thus useless under the 1.3 OS, even if it doesn't use
  93. any other 2.0-specific function.
  94.    To remedy this problem I wrote a library that emulates version 37 of
  95. the gadtools.library and can be integrated into one's own applications.
  96.    Actually I did two versions of it; a shared library (gadtools.library
  97. 34.1) and an object module linker library, that I named GTE.lib (GadTools
  98. Emulation Library).
  99.  
  100.  
  101.    5. TECHNICAL DETAILS ON GTE.LIB
  102.  
  103.    Some precisation about the usage of GTE.lib must be done.
  104.    At the moment it's only available the version for the SAS/C 6.x system.
  105.    I don't see this as a limitation, as sooner or later all "serious"
  106. programmers should update to this version (and now they got one more reason
  107. to do so).
  108.    With the SAS 6.x compiler you can use GTE.lib with
  109.  
  110.    SC LINK LIB=GTE.lib <Your source code file names>
  111.  
  112.    GTE.lib supports and emulates all gadtools.library V37 functions. These
  113. functions are supplied in two versions: the functions with the prefix "EF_"
  114. and those with the prefix "NL_".
  115.    The first are the true emulation functions and by calling them under
  116. any operating system (1.x or 2.x) it'll be executed the code that emulates
  117. the gadtools.library.
  118.    The others are named "interface functions": they, if called, will decide
  119. on the basis of the operating system under which the program is running
  120. whether to execute the emulation code (i. e. to call the EF_ functions) or
  121. jump directly to the true gadtools.library functions.
  122.    Briefly, by adding the NL_ prefix to all gadtools function calls in
  123. your source code and by linking then with GTE.lib, you will get a program
  124. using the true gadtools.library under the 2.0 (or higher) operating system
  125. while executing the emulation code under 1.3 (or lower).
  126.    This of course implies the increase of the size of your executable by
  127. about 30-40K.
  128.    Alternatively you can compile two versions of the same source code, the
  129. one using only true calls to gadtools, the other calling only the emulation
  130. functions, without passing through the interface ones (whose object code
  131. won't be thus linked to the program) and make two versions of the same
  132. application, a smaller one working only under 2.0, and a larger one working
  133. under both operating systems but always in emulation mode.
  134.    In this case the choice about which one to use will be of the user.
  135.    Of course all this is valid only assuming that the program doesn't make
  136. use of any other new 2.0 function or library except the gadtools.library
  137. functions.
  138.    Note: if the increase in size of the executable is unacceptable the
  139. only alternative is to use the shared version of the emulation library
  140. (gadtools.library 34.1).
  141.  
  142.  
  143.    6. GTE.LIB USAGE EXAMPLE
  144.  
  145.    Let's see now an example to make things clear:
  146.  
  147.    A classic program using gadtools could for instance contain this
  148. fragment:
  149.  
  150.    if (gad = CreateContext(&glist))
  151.    {
  152.       gad = CreateGadget(MX_KIND,gad,&ng,GTMX_Labels,labels,TAG_END);
  153.    }
  154.  
  155. and it would work only under 2.0 or higher.
  156.    By using GTE.lib you can modify it into
  157.  
  158.    if (gad = NL_CreateContext(&glist))
  159.    {
  160.       gad = NL_CreateGadget(MX_KIND,gad,&ng,GTMX_Labels,labels,TAG_END);
  161.    }
  162.  
  163. making it working under any operating system, in emulation mode under 1.x
  164. and calling the true gadtools.library under 2.x.
  165.    Alternatively you can modify it so:
  166.  
  167.    if (gad = EF_CreateContext(&glist))
  168.    {
  169.       gad = EF_CreateGadget(MX_KIND,gad,&ng,GTMX_Labels,labels,TAG_END);
  170.    }
  171.  
  172.    This version also works with any operating system, but it operates
  173. always in emulation mode even under 2.x, and that allows to reduce slightly
  174. the executable's size, but obviously it isn't the best in terms of
  175. efficiency and prevents the program from taking advantage of possible
  176. future enhancements of the true gadtools.library.
  177.  
  178.    Which method to use is each programmer's choice; that which is really
  179. important, if you use GTE.lib, is to always respect the following five
  180. rules:
  181.  
  182.    · ALWAYS #include into your source code the file "nl_gadtools.h",
  183.      supplied along with GTE.lib;
  184.    · DON'T ever use in your program other 2.x-only functions or libraries
  185.      except for the gadtools.library;
  186.    · DON'T use more than one method in the same program: the functions
  187.      you use must be all true gadtools functions, or all EF_, or all NL_;
  188.    · Always OPEN the gadtools.library if you are under 2.x and you use the
  189.      NL_ functions (or directly the true ones, but this is obvious);
  190.    · Always OPEN the intuition.library and graphics.library.
  191.  
  192.  
  193.    7. IMPORTANT NOTE ABOUT GTE.LIB
  194.  
  195.    If you examine the file GTE.lib with "OML GTE.lib l" you'll notice that
  196. it also contains many others functions other than those of the emulation
  197. of gadtools.
  198.    They are used by the emulation functions and for the moment you must NOT
  199. attempt to directly call them.
  200.    In the future I'll distribute these functions (and many other too) as
  201. a stand-alone linked library with full documentation and perhaps even as a
  202. shared library.
  203.    The only functions (that are present both in NL_ and EF_ version) that
  204. you already can use are the following:
  205.  
  206.    NL_FindTagItem(), NL_GetTagData(), NL_NextTagItem();
  207.    EF_FindTagItem(), EF_GetTagData(), EF_NextTagItem();
  208.  
  209. emulating three functions of the utility.library (another new 2.0 library).
  210.    For the usage of these you must follow the same rules I listed for the
  211. gadtools emulation functions; besides, you must #include into your source
  212. code the file "nl_utility.h", supplied with GTE.lib.
  213.    In the future these three functions will be distributes in a library
  214. partially or fully emulating the utility.library.
  215.  
  216.  
  217.    8. IMPORTANT NOTE ABOUT GADTOOLS.LIBRARY 34.1 AND GTE.LIB
  218.  
  219.    The GetVisualInfoA() function of gadtools.library 34.1, just like its
  220. corresponding EF_ and NL_ functions of GTE.lib, and unlike the omonymous
  221. function of the true gadtools.library, accepts even a NULL as the first
  222. argument, that is as the pointer to the screen; in this case it assumes
  223. you mean the Workbench screen.
  224.    The purpose of this is to avoid to have to find the Workbench screen:
  225. in fact, the intuition LockPubScreen() function, that under 2.x is used
  226. just in order to do this, doesn't exist under 1.3 (and thus it must not
  227. be called!!!!).
  228.    You'll need then to use some conditional code here, as the true
  229. gadtools.library V37's GetVisualInfoA() function DOESN'T accept a NULL as
  230. an argument.
  231.    Example:
  232.  
  233.    if (SysBase->lib_Version >= 36)   /* If we are under 2.0 or higher */
  234.    {
  235.       screen = LockPubScreen(NULL);
  236.       if (!screen) Error("No Workbench");
  237.    }
  238.    else                              /* If we are under 1.3 or lower */
  239.    {
  240.       screen = NULL;
  241.    }
  242.  
  243.    visualinfo = GetVisualInfoA(screen,NULL);
  244.  
  245.    ...  /* Rest of the program here */
  246.  
  247.    FreeVisualInfo(visualinfo);
  248.    if (screen) UnLockPubScreen(NULL,screen);
  249.  
  250.  
  251.    9. DIFFERENCES
  252.  
  253.    There are of course some slight differences between the working of
  254. GTE.lib (or gadtools.library 34.1) and that of the true gadtools.library,
  255. and they are all listed in the file "Differences.doc". It is however a
  256. matter of minimal and secondary details (at least I think so).
  257.  
  258.  
  259.    10. CONCLUSION
  260.  
  261.    This is the first version of gadtools.library 34.x and of GTE.lib
  262. I released, therefore there is a high chance of finding bugs in its
  263. working. If this should happen, please report the problem to me and I
  264. will fix it (if possible) in a next release.
  265.  
  266.    Write to:
  267.  
  268.    Massimo Tantignone
  269.    via Campagnoli, 4
  270.    28100 Novara (NO)
  271.    ITALY
  272.  
  273.    To conclude, I wish to mention that I'm working on the emulation of
  274. other 2.x libraries and I'll distribute them also when they are finished.
  275.  
  276.  
  277.                                     Massimo Tantignone, 27 january 1993
  278.  
  279.  
  280.