home *** CD-ROM | disk | FTP | other *** search
/ TopWare Tools / TOOLS.iso / tools / top1089 / files1.lzh / EWAPI.SUP < prev    next >
Encoding:
Text File  |  1993-11-29  |  9.3 KB  |  229 lines
  1.  
  2. This  file  contains  additions  or modifications made to the original
  3. EW  API  documentation distributed to the registered users of previous
  4. versions.  New  users  will  receive  an updated documentation. So, if
  5. you  don't  already  have  a  copy of the API documentation, you don't
  6. need to keep this file on your disk.
  7.  
  8. ********************************************************************
  9.         EW API 1.1 ADDITIONAL INFORMATION AND CORRECTIONS
  10. ********************************************************************
  11.  
  12. WARNING !! The following modifications mean that existing EWDs must be
  13. be recompiled. We provide updated versions of previous EWDs but you'll
  14. have to recompile your own Extension DLLs.
  15.  
  16.  
  17. EWExecute now takes a WORD parameter
  18. ************************************
  19.  
  20. The following has been added to section 2.1
  21.  
  22. EWExecute parameter:
  23.  
  24. EWExecute accepts a single parameter of type WORD. This parameter is called
  25. the RoutineId and is the basic component of the Menu Dispatching feature.
  26.  
  27. The ANSIOEM sample EWD is a good example of how to use the Menu Dispatching
  28. feature. This EWD implements the conversion of text from ANSI to OEM or from
  29. OEM to ANSI. Since these functions are quite similar it would be rather
  30. inefficient to write two different DLLs to do this job. However, an EWD has
  31. a single entry point which is EWExecute. Also, what if the EWD author wants
  32. to add two different entries in the User Menu if only one entry point exists
  33. in the EWD?
  34.  
  35. The RoutineId is a simple way to do Menu Dispatching and to specify which
  36. subroutine within the EWD has to be executed when a specific command has been
  37. selected from the User Menu.
  38.  
  39. The EWAddMenuEntry function now accepts an additional parameter, defined by
  40. the EWD author: the RoutineId. This WORD value will be stored with the other
  41. relevant data making up the User Menu entry. When the user selects that
  42. item in the User Menu, E! will call EWExecute, passing it the relevant
  43. RoutineId. This way, the EWD will be able to know which command has been
  44. choosen by the user.
  45.  
  46. The Key Assignment dialog box and the User Menu Definition dialog box also
  47. allow to define a RoutineId when assigning an EWD to a key or a Menu Item.
  48. By default, E! sets this value to 0.
  49.  
  50. ANSIOEM.EWD uses this feature to determine whether the user wants to
  51. translate from ANSI to OEM or from OEM to ANSI. ANSIOEM installs two entries
  52. in the User Menu: "Convert to OEM" (RoutineId = 1) and "Convert to ANSI"
  53. (RoutineId = 2). When EWExecute is called, ANSIOEM checks the value passed by
  54. E!. If it is equal to 0, this means that the command has been triggered from
  55. the "Execute User Extension" dialog box. In that case, a message box is
  56. displayed, prompting the user for a choice. Otherwise, it knows which kind
  57. of translation has to be done.
  58.  
  59. The EWD author using the RoutineId feature has to let the user know which
  60. RoutineIds are used to trigger which functions. This way, the user will be
  61. able to assign these functions to a key.
  62.  
  63. Please read the code of ANSIOEM.PAS to fully understand how the RoutineId
  64. parameter can be used.
  65.  
  66.  
  67. Section 3.1 has been changed to reflect the new EWExecute function:
  68.  
  69.   TExecFunc = function(MenuId : word) : integer;
  70.   int  (FAR PASCAL* TExecFunc)(unsigned int MenuId);
  71.  
  72.     General form of the EWExecute function called when execution of the
  73.     EWD has been requested by the user.
  74.  
  75.  
  76. The EWAddMenyEntry function has been changed accordingly:
  77.  
  78. function  EWAddMenuEntry(Command, Title : PChar;
  79.                          RoutineId  : word;
  80.                          AssignMode : word
  81.                          RoutineId  : word) : longint;
  82. long FAR PASCAL EWAddMenuEntry(char FAR* Command,
  83.                                char FAR* Title,
  84.                                unsigned int RoutineId,
  85.                                unsigned int AssignMode
  86.                                unsigned int RoutineId);
  87.  
  88. This function adds an entry in the User Menu. This entry will appear in all
  89. User Menus but will not be saved along with the user items. Normally, this
  90. function will be called once in the initialization part of an active EWD if
  91. you want the EWD to insert itself automatically in the user menu. See
  92. COUNTER.EWD.
  93.  
  94. Command       Command to be executed when the user selects the menuitem.
  95.               The meaning of the Command string depends on the assignment
  96.               mode. It is ignored if AssignMode is equal to
  97.               EWAssign_Command.
  98.  
  99. Title         Text of the menu item appearing in the User Menu.
  100.  
  101. CommandId     This value is used only if the AssignMode is equal to
  102.               EWAssign_Command. In that case, Command will be ignored and
  103.               CommandId will be the code of an editing function. These codes
  104.               are defined in EWUSER.INC and EWAPI.H.
  105.  
  106. AssignMode    May take one of the following value
  107.  
  108.                 EWAssign_Program    Command = DOS or WINDOWS command
  109.                 EWAssign_Command    CommandId = editing function code
  110.                 EWAssign_Macro      Command = 8 character macro name
  111.                 EWAssign_Extension  Command = 8 character extension name
  112.                                               (EWD)
  113.  
  114. RoutineId     This is a programmer defined value that will be passed to
  115.               EWExecute whenever the user selects this menu entry. Please
  116.               see the discussion about RoutineIds in the EWExecute section.
  117.               ANSIOEM.EWD uses the RoutineId to do Menu Dispatching.
  118.  
  119.  
  120. Return Value:
  121.  
  122. The function returns a long that can be used as the new menu item
  123. identifier. This identifier will be needed when using the EWRemoveMenuEntry
  124. function. If the function fails, it returns -1.
  125.  
  126.  
  127. _______________________________________________________________________________
  128.  
  129.  
  130. The following functions were added to the API:
  131.  
  132. function  EWGetInstance : word;
  133. unsigned int FAR PASCAL EWGetInstance(void);
  134.  
  135. Give the instance handle of EW.
  136.  
  137.  
  138. Return Value:
  139.  
  140. The function returns the instance handle of the running copy of E! allowing
  141. the extension DLL to register window procedures.
  142.  
  143.  
  144. _______________________________________________________________________________
  145. function  EWGetTextWindowHandle : word;
  146. unsigned int FAR PASCAL EWGetTextWindowHandle(void);
  147.  
  148. Give the handle of the active Text Window. The Text Window is a child window
  149. of the Edit Window. The Edit Window client area contains several child
  150. windows: the Ribbon, the Text Window and the Status Windows. The Text Window
  151. also has a child window which is named the Control Area.
  152.  
  153.  
  154. Return Value:
  155.  
  156. The function returns the handle of the current Text Window. If this value is
  157. null, there's no active window.
  158.  
  159.  
  160. _______________________________________________________________________________
  161. procedure EWSetModified; export;
  162. void FAR PASCAL EWSetModified(void);
  163.  
  164. Set the "text modified" flag of the current Editor. Use this function when
  165. you have changed the current text directly without using an editing
  166. function. Failing to do so will prevent E! from recognizing the change and
  167. will allow exiting the editor without saving the file.
  168.  
  169.  
  170. ********************************************************************
  171.         EW API 1.2 ADDITIONAL INFORMATION AND CORRECTIONS
  172. ********************************************************************
  173. _______________________________________________________________________________
  174. function EWIsModified; export;
  175. unsigned int FAR PASCAL EWIsModified(void);
  176.  
  177. Retrieve the "text modified" flag of the current Editor. Use this function
  178. to know whether the current text has been modified. The function will return
  179. 0 if the text has not been modified and a non null value otherwise.
  180.  
  181. _______________________________________________________________________________
  182.  
  183.  
  184.  
  185. EWGlbRepaint and EWGlbStripJoin Global Flags
  186. ********************************************
  187.  
  188. Two additional global option flags are now supported:
  189.  
  190. EWGlbRepaint: this flag defines which method will be used to refresh the text
  191. window when scrolling.
  192.  
  193. EWGlbStripJoin: this flag specifies whether trailing and leading spaces will
  194. be stripped when joining lines (the JoinLine routine is also used when
  195. deleting text marked in Stream mode).
  196.  
  197. EWLclbAutoIndent Local Flag
  198. ***************************
  199.  
  200. This new Local flag allows to toggle the AutoIndent feature.
  201.  
  202. EWGetEditorLocalFlag and EWSetEditorLocalFlag functions
  203. ********************************************************
  204.  
  205. The existing functions (EWGetLocalFlag and EWSetLocalFlag) were acting on
  206. the local options stored in the Control Center. These new functions have
  207. exactly the same syntax. The only difference is that they modify or read
  208. the current Editor's Local Options only. They leave the Control Center
  209. Local Defaults settings unchanged.
  210.  
  211. More on the EWEditFile function
  212. *******************************
  213.  
  214. The documentation fails to mention that trying to load a file that is
  215. already edited will cause this function to return a null value. The
  216. Editor containing this file will be put in the foreground.
  217.  
  218. _______________________________________________________________________________
  219. function  EWSaveAll : integer;
  220. int FAR PASCAL EWSaveAll();
  221.  
  222. Save all modified files.
  223.  
  224.  
  225. Return Value:
  226.  
  227. This function always returns 0.
  228. _______________________________________________________________________________
  229.