home *** CD-ROM | disk | FTP | other *** search
/ OS/2 Shareware BBS: 10 Tools / 10-Tools.zip / guit01.zip / EXTIF.TXT < prev    next >
Text File  |  1993-11-30  |  6KB  |  179 lines
  1. Guidelines Technical Note 001.           Guidelines Tech Support  27nov93
  2.  
  3.  
  4.               Interfacing to External Code from Guidelines
  5.               --------------------------------------------
  6.  
  7.  
  8. Whilst many applications may be completely written in the JOT language, many 
  9. developers prefer to write the bulk of their code in C or C++, especially the 
  10. 'engines' behind the user interface.
  11.  
  12. This note demonstrates how external code may be interfaced to Guidelines 
  13. generated code.
  14.  
  15. In the examples, a simple C++ class (DirList) is used which creates a list of 
  16. the filenames in a specified directory. The directory path is to be specified 
  17. in an entry field, and the list of names is then displayed in a listbox. The
  18. 'Refresh' button causes the list to be updated with the current filespec. 
  19.  
  20. Note that a filespec (including wildcards) is required in the entry field, not 
  21. just a path. The object beeps when the filespec is invalid, or thare are no 
  22. files in the directory. The sample itself is trivial, and does the minimum 
  23. required to demonstrate the interfacing techniques.
  24.  
  25. ----------------------------------------------------------------------------
  26. The first approach (EXTLIST1) uses embedded C++ to create the interface. 
  27. Guidelines is not made aware of any external functions.
  28.  
  29. 1. The DIRLIST.OBJ and DIRLIST.HPP files containing the directory list object 
  30. code and interface definitions are 'registered' with Guidelines, by adding 
  31. them as an external file group. (Edit Menu, External Files... option).
  32.  
  33. When this is done, Guidelines emits a 
  34.  
  35.  #include "DIRLIST.HPP"
  36.  
  37. line in the generated code (.CPP), and places a reference to the DIRLIST.OBJ 
  38. in the makefile (.MAK). 
  39.  
  40. The LIB and INCLUDE variables in the "Paths" section of the Environments 
  41. dialog can be set to point to these files if they are not in the standard 
  42. Guidelines directories (GUIDE\SYS).
  43.  
  44.  
  45. 2.  The interface code is placed in one code module, called RefreshList. This 
  46. is a mixture of JOT and C++. The C: at the start of a line causes Guidelines 
  47. to pass the following code straight through into the generated output, and no 
  48. syntax checking is performed.
  49.  
  50.  
  51. VOID RefreshList()
  52.  
  53.     STRING Item
  54.     SHORT  ItemCount
  55.  
  56.     Frame1.Listbox1.ClearItems ()
  57.  
  58. C:  DirList *List = new DirList(DirPath);
  59. C:  ItemCount = List->GetCount();
  60.     Frame1.Msg.Text = Str(ItemCount)
  61.  
  62. C:  for (int i = 0; i < ItemCount; i++)
  63. C:      {
  64. C:      Item = *List->ReadItem(i);
  65.         Frame1.Listbox1.AppendItem (Item)
  66. C:      }
  67.  
  68. end
  69.  
  70.  
  71. Notes:
  72.  
  73. The function creates a local instance of the DirList object, queries how many 
  74. entries it contains, then appends these seqentially to the list in the 
  75. list box. Note:
  76.  
  77.  - The directory path is held in a global variable called DirPath.
  78.  
  79.  - The DirList class uses the Guidelines String class, making the interfacing 
  80.    easier.
  81.  
  82.  - The DirList object is destroyed when it goes out of scope at the end of 
  83.    the function.
  84.  
  85.  
  86. The files for this example are:
  87.  
  88.  EXTLIST1.GUI    - Guidelines User Interface definition
  89.  DIRLIST.CPP     - C++ Directory list class code
  90.  DIRLIST.HPP     - C++ Directory list class definition
  91.  EXTIF.MAK       - Nmake Makefile to create external obj file
  92.  
  93. DIRLIST.OBJ is created from the CPP files, externally to Guidelines, but 
  94. using the same compiler switches as defined in the Guidelines environment.
  95.  
  96. -----------------------------------------------------------------------------
  97.  
  98. The second approach (EXTLIST2) requires no embedded C/C++, but uses instead 
  99. the "External Functions" facility of Guidelines.
  100.  
  101. 1. C wrapper functions for the member functions to be called are written. 
  102. This is necessary because Guidelines/JOT doesn't currently support 
  103. definitions of objects, so the interface must use a C syntax.
  104.  
  105. In the example, these are placed in the DIRINT.CPP file. This is then 
  106. compiled into DIRINT.OBJ, and registered (along with the corresponding 
  107. DIRINT.HPP file) as an external file.
  108.  
  109.  String ReadList (ULONG List, short Item);
  110.  short  ListLen(ULONG List);
  111.  short  UpdateList (ULONG List, String DirName);
  112.  void   DestroyList(ULONG List);
  113.  ULONG  InitList (String DirName);
  114.  
  115.  
  116. 2. External Function definitions are added to the External Functions module 
  117. within the Action Editor. This makes Guidelines aware of then, and they 
  118. become usable within JOT.
  119.  
  120.  functions
  121.     LONG   InitList(STRING)
  122.     VOID   DestroyList(LONG)
  123.     SHORT  UpdateList(LONG, STRING)
  124.     SHORT  ListLen(LONG)
  125.     STRING ReadList(LONG, SHORT) 
  126.  end
  127.  
  128.  
  129. 3. The RefreshList() function, written in JOT, calls the functions in an 
  130. appropriate order whenever the list is to be refreshed:
  131.  
  132.         
  133. VOID RefreshList()
  134.  
  135.     STRING Item
  136.     SHORT Counter
  137.  
  138.     Frame1.Listbox1.ClearItems ()
  139.     UpdateList(List, DirPath)
  140.     
  141.     Counter = ListLen(List)
  142.     Frame1.Msg.Text = Str (Counter)    
  143.  
  144.     while Counter > 0
  145.         Counter = Counter - 1
  146.         Item = ReadList (List, Counter)
  147.         Frame1.Listbox1.AppendItem (Item)
  148.     endwhile
  149. end
  150.  
  151.  
  152. Notes:
  153.  
  154. Because pointers cannot currently be declared within Guidelines as
  155. global variables, the List variable is declared as a LONG in "Global
  156. Variables". The InitList function in DIRINT.CPP returns the new
  157. instance of the DirList class cast as a ULONG. The access functions
  158. address the object via this LONG value passed to them (it acts as a handle
  159. for the object).
  160.  
  161. In this example, only one instance of the DirList class is created (at 
  162. application startup), and the same instance refreshes its list each time. 
  163. This contrasts with the previous example, where a new instance is created and 
  164. destroyed each time (which could also be done).
  165.  
  166. The files for this example are:
  167.  
  168.  EXTLIST2.GUI    - Guidelines User Interface definition
  169.  DIRLIST.CPP     - C++ Directory list class code
  170.  DIRLIST.HPP     - C++ Directory list class definition
  171.  DIRINT.CPP      - C Wrapper functions
  172.  DIRINT.HPP      - C Wrapper function prototypes
  173.  EXTIF.MAK       - Nmake Makefile to create external obj files
  174.  
  175. DIRLIST.OBJ and DIRINT.OBJ are created from the CPP files, externally to 
  176. Guidelines, but using the same compiler switches as defined in the Guidelines 
  177. environment. Use NMAKE -f EXTIF.MAK  and ensure that your INCLUDE environment
  178. variable includes the GUIDE\SYS directory (for guirun.h).
  179.