home *** CD-ROM | disk | FTP | other *** search
/ Amiga MA Magazine 1998 #6 / amigamamagazinepolishissue1998.iso / coders / biblioteki / c_library / gadtools34 / docsitaliano / gadtools34.doc < prev    next >
Text File  |  1998-05-21  |  13KB  |  289 lines
  1.  
  2.  
  3.  
  4.                    GadTools Library 34.1 e GTE.lib 1.0
  5.  
  6.                      di Massimo Tantignone (27/01/93)
  7.                           Una produzione MT Soft
  8.  
  9.  
  10.  
  11.    1. INTRODUZIONE
  12.  
  13.    Gadtools.library 34.1 è una versione 1.3-compatibile dell'omonima
  14. libreria presente normalmente nel Kickstart 2.04 o superiori.
  15.    Per essere precisi, è una libreria di tipo shared che si propone di
  16. emulare la gadtools.library V37 e funziona anche sotto sistemi operativi
  17. anteriori al 2.0, come appunto l'OS 1.3.
  18.    GTE.lib è invece una libreria di moduli oggetto per il linker e svolge
  19. lo stesso compito.
  20.    Queste due librerie di pubblico dominio permettono di scrivere e/o usare
  21. programmi che usufruiscano anche sotto 1.3 dei molti vantaggi offerti dalla
  22. gadtools.library nella costruzione e gestione della propria interfaccia
  23. utente grafica (purché ovviamente tali programmi non richiedano altre
  24. funzionalità specifiche dell'OS 2.0).
  25.  
  26.    Entrambe le librerie sono dedicate principalmente ai programmatori, che
  27. potranno distribuire liberamente gadtools.library 34.1 insieme ai loro
  28. programmi, oppure collegare direttamente il codice di GTE.lib a questi
  29. ultimi (mediante il linker).
  30.    Se tuttavia fossero in circolazione programmi già fatti che usino la
  31. gadtools.library E NESSUN'ALTRA LIBRERIA O FUNZIONE DEL 2.0, anche questi
  32. dovrebbero funzionare dopo l'installazione di gadtools.library 34.1 nella
  33. propria directory LIBS: del Workbench 1.3 (ovviamente tali programmi
  34. possono essere individuati solo sperimentalmente).
  35.    In questo senso gadtools.library 34.1 può risultare utile anche
  36. all'utente finale (anche se dubito che al momento esistano già programmi
  37. del genere).
  38.    Nella directory di distribuzione di gadtools.library 34.1 e di GTE.lib
  39. ho incluso due programmi di test: uno (TestLinked) è stato linkato con
  40. GTE.lib e perciò contiene il codice di emulazione di gadtools, invece
  41. l'altro (TestShared) fa uso della gadtools.library esterna. Il primo può
  42. essere eseguito in qualsiasi momento, mentre per eseguire il secondo è
  43. necessario installare prima gadtools.library 34.1 come specificato nel
  44. prossimo paragrafo (oppure lanciarlo sotto 2.0 o superiori, ma in quel caso
  45. userebbe la VERA gadtools.library).
  46.    Nota: a parte il formato (shared library o linker library) le due
  47. librerie sono ASSOLUTAMENTE IDENTICHE nel funzionamento, infatti sono state
  48. ottenute dagli stessi sorgenti.
  49.  
  50.  
  51.    2. UTILIZZO DI GADTOOLS.LIBRARY 34.1
  52.  
  53.    Per utilizzare gadtools.library 34.1 è sufficiente copiarla nella
  54. directory LIBS: del proprio Workbench 1.3 (floppy o hard disk). Ogni
  55. programma che tenti di aprire la gadtools.library funzionerà da questo
  56. momento anche sotto 1.3 e aprirà questa libreria invece di quella "vera"
  57. del sistema operativo 2.0, senza accorgersi della differenza.
  58.    Ovviamente, sotto 1.3, il programma non deve fare uso di altre librerie
  59. riservate al 2.0 diverse dalla gadtools.library.
  60.    Questa libreria NON va invece copiata nella directory LIBS: di un
  61. Workbench 2.0, poichè il sistema operativo 2.0 dispone già di una propria
  62. gadtools.library.
  63.    Nota: la libreria è distribuita con il nome di "gadtools_34.library"
  64. per motivi di copyright. Dopo averla copiata in LIBS: dovete rinominarla
  65. esattamente "gadtools.library" altrimenti non funzionerà.
  66.    Se non volete copiare manualmente la libreria potete lanciare lo script
  67. di installazione automatica chiamato "InstallGadTools34".
  68.  
  69.  
  70.    3. UTILIZZO DI GTE.LIB
  71.  
  72.    GTE.lib, essendo una libreria per il linker, risulta utile solo ai
  73. programmatori.
  74.    Per sfruttare questa libreria è sufficiente scrivere il proprio sorgente
  75. come lo si scriverebbe se si usasse la vera gadtools.library, ma
  76. anteponendo il prefisso "NL_" (enne elle sottolineatura) al nome di ogni
  77. funzione di gadtools chiamata.
  78.    Naturalmente dopo la compilazione occorre eseguire il linking con
  79. GTE.lib, e si otterrà un programma funzionante sotto qualsiasi sistema
  80. operativo e avente un'interfaccia utente che emula la gadtools.library V37
  81. sotto 1.x mentre fa uso direttamente di quest'ultima sotto 2.x.
  82.    Anteponendo il prefisso "EF_" (e effe sottolineatura) invece di "NL_",
  83. il programma risulterà di dimensioni leggermente inferiori ma funzionerà
  84. in emulazione ANCHE sotto 2.x.
  85.    In entrambi i casi occorre #includere nel proprio sorgente il file
  86. header "nl_gadtools.h" fornito insieme a GTE.lib.
  87.  
  88.  
  89.    4. MOTIVO DELL'ESISTENZA DI QUESTE DUE LIBRERIE
  90.  
  91.    La gadtools.library è certamente tra le più utili librerie fornite
  92. a partire dalla versione 2.0 del sistema operativo di Amiga,
  93. poiché permette a tutti i programmi di presentare delle interfacce utente
  94. grafiche che siano consistenti e simili tra loro nell'aspetto e nel
  95. funzionamento.
  96.    Purtroppo, per quanto utile, questa libreria non è compatibile con il
  97. sistema operativo 1.3 (o precedenti), che, sebbene obsoleto, rimarrà di
  98. certo in circolazione sui più vecchi Amiga ancora per qualche anno.
  99.    Ogni nuova applicazione che faccia uso della gadtools.library per la
  100. propria interfaccia utente risulta pertanto inutilizzabile sotto l'OS 1.3,
  101. anche se non utilizza nessun'altra funzionalità specifica del 2.0.
  102.    Per risolvere questo problema ho scritto una libreria che emula la
  103. gadtools.library V37 e che può essere integrata nei propri applicativi.
  104.    In effetti ho realizzato due versioni di essa; una shared library
  105. (gadtools.library 34.1) e una libreria di moduli oggetto per il linker,
  106. chiamata GTE.lib (GadTools Emulation Library).
  107.  
  108.  
  109.    5. DETTAGLI TECNICI SU GTE.LIB
  110.  
  111.    Occorre qualche precisazione circa l'utilizzo di GTE.lib.
  112.    Al momento è disponibile solo la versione adatta al sistema SAS/C 6.0.
  113.    Non ritengo questa una limitazione in quanto prima o poi tutti i
  114. programmatori "seri" dovranno aggiornarsi a questa versione (ed ora hanno
  115. un motivo di più per farlo).
  116.    Usando il compilatore SAS 6.0 si può utilizzare GTE.lib con
  117.  
  118.    SC LINK LIB=GTE.lib <Nomi dei propri sorgenti>.
  119.  
  120.    La GTE.lib supporta ed emula tutte le funzioni della gadtools.library
  121. versione 37. Tali funzioni vengono fornite in due versioni: le funzioni con
  122. prefisso "EF_" e quelle con prefisso "NL_".
  123.    Le prime sono le vere e proprie funzioni di emulazione e chiamandole
  124. sotto qualsiasi sistema operativo (1.x o 2.x) verrà eseguito il codice che
  125. emula la gadtools.library.
  126.    Le altre sono dette "funzioni di interfaccia": esse, se chiamate,
  127. decideranno in base al sistema operativo sotto cui il programma sta
  128. girando se eseguire il codice di emulazione (chiamare cioè le funzioni EF_)
  129. oppure saltare direttamente alle vere funzioni della gadtools.library.
  130.    In breve, aggiungendo il prefisso NL_ a tutte le chiamate a funzioni di
  131. gadtools nel proprio codice sorgente ed eseguendo poi il linking con
  132. GTE.lib, si otterrà un programma che usa la vera gadtools.library sotto il
  133. sistema operativo 2.0 (o superiori) mentre esegue il codice di emulazione
  134. della stessa sotto 1.3.
  135.    Questo naturalmente comporta l'aumento delle dimensioni del proprio
  136. eseguibile di circa 30-40K.
  137.    In alternativa si possono compilare due versioni dello stesso sorgente,
  138. una utilizzante solo autentiche chiamate a gadtools, l'altra chiamante
  139. solo le funzioni di emulazione, senza passare attraverso quelle di
  140. interfaccia (il cui codice oggetto non verrà quindi unito al programma) e
  141. realizzare due versioni dello stesso applicativo, una di dimensioni
  142. inferiori funzionante solo sotto 2.x, e un'altra più lunga e funzionante
  143. sotto entrambi i sistemi operativi ma sempre e comunque in emulazione.
  144.    Sarà in questo caso dell'utente la scelta circa quale utilizzare.
  145.    Naturalmente tutto ciò è valido solo assumendo che il programma non
  146. faccia uso di nessun'altra nuova funzione o libreria dell'OS 2.0
  147. all'infuori delle funzioni della gadtools.library.
  148.    Nota: se l'aumento di dimensioni dell'eseguibile non è accettabile
  149. l'unica alternativa è usare la versione shared della libreria di emulazione
  150. (gadtools.library 34.1).
  151.  
  152.  
  153.    6. ESEMPIO DI UTILIZZO DI GTE.LIB
  154.  
  155.    Vediamo ora un esempio per chiarire le idee:
  156.  
  157.    Un classico programma che utilizzi gadtools potrebbe ad esempio
  158. contenere questo frammento:
  159.  
  160.    if (gad = CreateContext(&glist))
  161.    {
  162.       gad = CreateGadget(MX_KIND,gad,&ng,GTMX_Labels,labels,TAG_END);
  163.    }
  164.  
  165. e sarebbe utilizzabile solo sotto 2.0 o superiori.
  166.    Usando GTE.lib si può modificarlo in
  167.  
  168.    if (gad = NL_CreateContext(&glist))
  169.    {
  170.       gad = NL_CreateGadget(MX_KIND,gad,&ng,GTMX_Labels,labels,TAG_END);
  171.    }
  172.  
  173. rendendolo funzionante sotto qualsiasi sistema operativo, in emulazione
  174. sotto 1.x e chiamando la vera gadtools.library sotto 2.x.
  175.    Alternativamente si può modificarlo così:
  176.  
  177.    if (gad = EF_CreateContext(&glist))
  178.    {
  179.       gad = EF_CreateGadget(MX_KIND,gad,&ng,GTMX_Labels,labels,TAG_END);
  180.    }
  181.  
  182.    Anche questa versione è funzionante con ogni sistema operativo, ma
  183. operando sempre in emulazione anche sotto 2.x, il che permette di diminuire
  184. leggermente le dimensioni dell'eseguibile, ma ovviamente non è il meglio in
  185. termini di efficienza e impedisce al programma di trarre vantaggio da
  186. eventuali futuri miglioramenti della vera gadtools.library.
  187.  
  188.    Quale metodo usare è ovviamente una scelta del programmatore; ciò che
  189. conta, se si usa GTE.lib, è rispettare sempre le seguenti cinque regole:
  190.  
  191.    · #includere SEMPRE nel proprio sorgente il file "nl_gadtools.h",
  192.      fornito insieme a GTE.lib;
  193.    · NON usare mai nel proprio programma altre funzioni o librerie
  194.      compatibili solo con il 2.x oltre a quelle della gadtools.library;
  195.    · NON usare più di un metodo nello stesso programma: o usare tutte vere
  196.      funzioni di gadtools, o tutte funzioni EF_, o tutte funzioni NL_;
  197.    · APRIRE sempre la gadtools.library se si è sotto 2.x e si usano le
  198.      funzioni NL_ (o direttamente quelle vere, ma questo è ovvio);
  199.    · APRIRE sempre la intuition.library e la graphics.library.
  200.  
  201.  
  202.    7. NOTA IMPORTANTE CIRCA GTE.LIB
  203.  
  204.    Esaminando il file GTE.lib con "OML GTE.lib l" si noterà che contiene
  205. anche molte altre funzioni oltre a quelle dell'emulazione di gadtools.
  206.    Queste sono utilizzate dalle funzioni di emulazione stesse e per il
  207. momento NON dovete tentare di chiamarle direttamente.
  208.    In futuro distribuirò queste funzioni (e molte altre ancora) in una
  209. libreria linked separata completa di documentazione e forse anche in una
  210. shared library.
  211.    Le uniche funzioni (presenti sia in versione NL_ che in versione EF_)
  212. che potete già ora utilizzare sono le seguenti:
  213.  
  214.    NL_FindTagItem(), NL_GetTagData(), NL_NextTagItem();
  215.    EF_FindTagItem(), EF_GetTagData(), EF_NextTagItem();
  216.  
  217. che emulano tre funzioni della utility.library (altra nuova libreria 2.0).
  218.    Per l'utilizzo di queste valgono le stesse regole esposte per le
  219. funzioni di emulazione di gadtools; inoltre occorre #includere nel proprio
  220. sorgente il file "nl_utility.h", fornito con GTE.lib.
  221.    In futuro queste tre funzioni saranno distribuite in una libreria
  222. di emulazione parziale o completa della utility.library.
  223.  
  224.  
  225.    8. NOTA IMPORTANTE CIRCA GADTOOLS.LIBRARY 34.1 E GTE.LIB
  226.  
  227.    La funzione GetVisualInfoA() di gadtools.library 34.1, come anche le sue
  228. corrispondenti funzioni EF_ e NL_ di GTE.lib, e a differenza dell'omonima
  229. funzione della vera gadtools.library, accetta anche un NULL come primo
  230. argomento, cioè come puntatore allo schermo; in questo caso infatti
  231. assume che si intenda lo schermo del Workbench.
  232.    Lo scopo di ciò è evitare di dovere rintracciare lo schermo del
  233. Workbench: infatti la funzione di intuition LockPubScreen(), che sotto 2.0
  234. si usa proprio a questo scopo, non esiste sotto 1.3 (e non deve quindi
  235. essere chiamata!!!!).
  236.    Occorrerà pertanto usare qui del codice condizionale, poichè purtroppo
  237. la funzione GetVisualInfoA() della VERA gadtools.library V37 NON accetta un
  238. NULL come argomento.
  239.    Esempio:
  240.  
  241.    if (SysBase->lib_Version >= 36)   /* Se siamo sotto 2.0 o superiori */
  242.    {
  243.       screen = LockPubScreen(NULL);
  244.       if (!screen) Errore("Niente Workbench");
  245.    }
  246.    else                              /* Se siamo sotto 1.3 o inferiori */
  247.    {
  248.       screen = NULL;
  249.    }
  250.  
  251.    visualinfo = GetVisualInfoA(screen,NULL);
  252.  
  253.    ...  /* Resto del programma qui */
  254.  
  255.    FreeVisualInfo(visualinfo);
  256.    if (screen) UnLockPubScreen(NULL,screen);
  257.  
  258.  
  259.    9. DIFFERENZE
  260.  
  261.    Ci sono naturalmente delle lievi differenze tra il funzionamento di
  262. GTE.lib (o gadtools.library 34.1) e quello della vera gadtools.library, e
  263. sono tutte elencate nel file "Differenze.doc". Si tratta comunque di
  264. dettagli minimi e di secondaria importanza (almeno secondo il mio parere).
  265.  
  266.  
  267.    10. CONCLUSIONE
  268.  
  269.    Questa è la prima versione di gadtools.library 34.x e di GTE.lib
  270. resa pubblica, pertanto è possibilissimo che vengano riscontrati dei bug
  271. nel funzionamento. Se dovesse accadere, prego chiunque ne fosse vittima
  272. di segnalarmi il problema che sarà (se possibile) eliminato nelle prossime
  273. versioni.
  274.  
  275.    Scrivete a:
  276.  
  277.    Massimo Tantignone
  278.    via Campagnoli, 4
  279.    28100 Novara (NO)
  280.    ITALIA
  281.  
  282.    Per concludere, vorrei segnalare che sto lavorando all'emulazione di
  283. altre librerie 2.x e distribuirò anche queste quando saranno ultimate.
  284.  
  285.  
  286.                                     Massimo Tantignone, 27 gennaio 1993
  287.  
  288.  
  289.