PROGRAMMERS GUIDE TO THE E EDITOR TOOLKIT. VERSION 2.0 January 13, 1993 Gennaro (Jerry) Cuomo (GCUOMO at YKTVMV) Jason Crawford (JASON at YKTVMV) John Ponzo (JPONZO at YKTVMV) OS/2 Applications & Tools IBM T.J. Watson Research Center P.O. Box 218 Yorktown Heights, NY 10958 ----------------------------------------------------------------------------- ii Programmers Guide to the E Editor Toolkit. Version 2.0 CONTENTS ________ DISCLAIMER - READ FIRST! . . . . . . . . . . . . . . 1 INTRODUCTION. . . . . . . . . . . . . . . . . . . . . 3 WRITTING PROGRAMS USING THE E TOOLKIT . . . . . . . . 5 GETTING STARTED. . . . . . . . . . . . . . . . . . . 7 ETKExxx.DLL - The "Heart" of the E-Toolkit . . . . . 7 ETKRxxx.DLL - Utility Resources . . . . . . . . . . . 7 E-Macros - Utility Resources . . . . . . . . . . . . 8 Your Application/Sample Programs . . . . . . . . . . 8 Special Notes!!! . . . . . . . . . . . . . . . . . . 9 E TOOLKIT FUNCTIONS AT A GLANCE. . . . . . . . . . 11 Register, Create, Delete functions (The basics) . . 11 Special Access- E-MLE Manipulation . . . . . . . . 11 REGISTER, CREATE, DELETE FUNCTIONS (THE BASICS) . . 15 EtkRegister . . . . . . . . . . . . . . . . . . . . 16 EtkCreate . . . . . . . . . . . . . . . . . . . . . 17 EtkDestroy . . . . . . . . . . . . . . . . . . . . 19 EtkVersion . . . . . . . . . . . . . . . . . . . . 20 SPECIAL ACCESS FUNCTIONS- E-MLE MANIPULATION . . . 21 Event Execution. . . . . . . . . . . . . . . . . . 21 EtkExecuteCommand . . . . . . . . . . . . . . . . . 22 EtkProcessEditKey . . . . . . . . . . . . . . . . . 23 Text Manipulation . . . . . . . . . . . . . . . . . 25 EtkQueryText . . . . . . . . . . . . . . . . . . . 26 EtkDeleteText . . . . . . . . . . . . . . . . . . . 27 EtkReplaceText . . . . . . . . . . . . . . . . . . 28 EtkInsertText . . . . . . . . . . . . . . . . . . . 29 EtkQueryTextBuffer . . . . . . . . . . . . . . . . 30 EtkInsertTextBuffer . . . . . . . . . . . . . . . . 31 EtkFindAttribute. . . . . . . . . . . . . . . . . . 32 Text Selection. . . . . . . . . . . . . . . . . . . 33 EtkQuerySelectionType . . . . . . . . . . . . . . . 34 EtkQuerySelection . . . . . . . . . . . . . . . . . 35 EtkSetSelection . . . . . . . . . . . . . . . . . . 37 File Information . . . . . . . . . . . . . . . . . 39 EtkQueryFileID . . . . . . . . . . . . . . . . . . 40 EtkSetFileField . . . . . . . . . . . . . . . . . . 41 EtkQueryFileField . . . . . . . . . . . . . . . . . 42 E TOOLKIT MESSAGES . . . . . . . . . . . . . . . . 45 EPM_FRAME_STATUSLINE . . . . . . . . . . . . . . . 48 EPM_FRAME_MESSAGELINE . . . . . . . . . . . . . . . 50 EPM_EDIT_VERSION . . . . . . . . . . . . . . . . . 51 ----------------------------------------------------------------------------- Contents iii EPM_EDIT_TURN_OFF_HIGHLIGHT . . . . . . . . . . . . 52 EPM_EDIT_QUERY_HELP_INSTANCE . . . . . . . . . . . 53 EPM_BROADCASTHELP . . . . . . . . . . . . . . . . . 54 EPM_EDIT_DELETEFILE . . . . . . . . . . . . . . . . 55 EPM_EDIT_ACTIVATEFILEID . . . . . . . . . . . . . . 56 EPM_EDIT_CHAR . . . . . . . . . . . . . . . . . . . 57 EPM_EDIT_CLIPBOARDCOPY . . . . . . . . . . . . . . 58 EPM_EDIT_COMMAND . . . . . . . . . . . . . . . . . 59 EPM_EDIT_COMMAND2 . . . . . . . . . . . . . . . . . 61 EPM_EDIT_CHANGEFONT . . . . . . . . . . . . . . . . 62 EPM_EDIT_TASKLIST . . . . . . . . . . . . . . . . . 63 EPM_EDIT_RETCODE . . . . . . . . . . . . . . . . . 64 EPM_EDIT_CURSORMOVE . . . . . . . . . . . . . . . . 65 EPM_EDIT_ACTIVEHWND . . . . . . . . . . . . . . . . 66 EPM_EDIT_OPTIONS . . . . . . . . . . . . . . . . . 67 EPM_EDIT_ID . . . . . . . . . . . . . . . . . . . . 70 EPM_EDIT_SHOW . . . . . . . . . . . . . . . . . . . 71 EPM_EDIT_NEWFILE . . . . . . . . . . . . . . . . . 72 EPM_EDIT_DESTROYNOTIFY . . . . . . . . . . . . . . 74 EPM_EXTRAWINDOW_REFRESH . . . . . . . . . . . . . . 75 EPM_EDIT_CONTROLTOGGLE . . . . . . . . . . . . . . 76 EPM_EDIT_RECORDKEY- . . . . . . . . . . . . . . . . 78 EPM_EDIT_ENDRECORDKEY- . . . . . . . . . . . . . . 79 EPM_EDIT_PLAYKEY . . . . . . . . . . . . . . . . . 80 EPM_EDIT_QUERYRECORDKEY . . . . . . . . . . . . . . 81 EPM_EDIT_ASKTOQUIT . . . . . . . . . . . . . . . . 82 EPM_EDIT_ASKTOCLOSE . . . . . . . . . . . . . . . . 83 EPM_EDIT_ASKTODONE . . . . . . . . . . . . . . . . 84 EPM_EDIT_ASKTOFAILED . . . . . . . . . . . . . . . 85 ERES.DLL . . . . . . . . . . . . . . . . . . . . . 87 ERES.DLL - Exported Functions . . . . . . . . . . . 88 ERESRegisterEtkFunctions . . . . . . . . . . . . . 89 ERESCommonWndProc . . . . . . . . . . . . . . . . . 90 ERESSaveLists . . . . . . . . . . . . . . . . . . . 91 ERESRetrieveLists . . . . . . . . . . . . . . . . . 92 ERESOpenEditWindow . . . . . . . . . . . . . . . . 93 ERESCountEWindows . . . . . . . . . . . . . . . . . 94 ERESPopDlgBox . . . . . . . . . . . . . . . . . . . 95 ERESIsAnEditWin . . . . . . . . . . . . . . . . . . 97 ERESEwindowValid . . . . . . . . . . . . . . . . . 98 ERESSendOpenMsgToApp . . . . . . . . . . . . . . . 99 ERESShutDown . . . . . . . . . . . . . . . . . . . 100 ERESInitEResStruct . . . . . . . . . . . . . . . . 101 ERESCheckVersion . . . . . . . . . . . . . . . . . 102 ERESProcessCommands . . . . . . . . . . . . . . . . 103 ERESEditwindowList . . . . . . . . . . . . . . . . 104 ERES.DLL - EXPORTED DIALOG BOX PROCEDURES . . . . . 105 ERESOpen1DlgProc . . . . . . . . . . . . . . . . . 106 ERESCommandDlgProc . . . . . . . . . . . . . . . . 108 ERESFindChangeDlgProc . . . . . . . . . . . . . . . 110 ERESConfigDlgProc . . . . . . . . . . . . . . . . . 111 EntryBoxDlgProc . . . . . . . . . . . . . . . . . . 113 ----------------------------------------------------------------------------- iv Programmers Guide to the E Editor Toolkit. Version 2.0 ListBoxDlgProc . . . . . . . . . . . . . . . . . . 115 QuitBoxDlgProc . . . . . . . . . . . . . . . . . . 117 EXAMPLE E TOOLKIT APPLICATION . . . . . . . . . . . 121 APPENDIX . . . . . . . . . . . . . . . . . . . . . 123 Appendix A - . . . . . . . . . . . . . . . . . . . 123 Appendix A1 - . . . . . . . . . . . . . . . . . . . 127 Appendix B - . . . . . . . . . . . . . . . . . . . 128 Appendix C - . . . . . . . . . . . . . . . . . . . 129 Appendix E - . . . . . . . . . . . . . . . . . . . 134 Appendix F - . . . . . . . . . . . . . . . . . . . 137 Appendix G - . . . . . . . . . . . . . . . . . . . 139 ----------------------------------------------------------------------------- Contents v ----------------------------------------------------------------------------- vi Programmers Guide to the E Editor Toolkit. Version 2.0 DISCLAIMER - READ FIRST! ________________________ The sample code for using the current version (5.51) of the E Toolkit and its Enhanced Multi-Line Edit control (E-MLE) is being made available for the benefit of those who need to use it now. It is being released "as-is", with no promise of support, enhancement, or bug fixes. In addition, you should be aware that we are currently working on a new, cleaner, API for the next major update to EPM, which is not necessarily compatible with the one used in this package. In mentioning the "next major update", we are not guaran- teeing that this will ever be released outside of IBM. (That is not a decision that we can make.) We are cur- rently developing EPM 5.60, which includes long line support, pop-up menus, and much more, and EPM 6.00, which is essentially a 32-bit version of EPM 5.60. If you have a need to develop on top of the newer E-MLE, then please send a note to Gennaro Cuomo (gcuomo at watson.IBM.com) describing why you need it. This will help us demonstrate demand for the new code, and *might* get you on our beta-test list. ----------------------------------------------------------------------------- Disclaimer - read first! 1 ----------------------------------------------------------------------------- 2 Programmers Guide to the E Editor Toolkit. Version 2.0 INTRODUCTION. _____________ The E-Toolkit assists a software developer in building applications that edit multiple lines of text. The E-Toolkit gives developers access to OS/2 functions and PM messages that enable the creation and manipulation of an advanced multi-line edit control window. This multi- line edit window contains an advanced text editor engine based on the "E" text editor technology. (The E Family of text editors include, E3 for DOS, E3AIX for AIX, EOS2 for Full Screen OS/2, EPM and EPM/G for OS/2 Presentation Manager.) This multi-line edit window is referred to as the E-MLE. The E-MLE is a versatile control window that supports many primitive operations which allow easy access to powerful text editing capabilities. For example, The E-MLE supports the editing of large files (limited only by system memory). Each E-MLE can store multiple files, each of which can be viewed one at a time. (The feature is known as a "file RING") The E-MLE supports text with associated attribute informa- tion. Using the attribute feature your application can display text in Multiple Fonts, Multiple colors, and even associate commands with regions of text. (Associating commands with regions of text can be a way of imple- menting HyperText.) An advanced feature is available which allows other window classes to be overlayed with in a E-MLE. Using this "Overlay Window" feature, a E-MLE can incorporate images along with text. The E based editor engine runs in its own separate work thread. Therefore, when primitive commands are executed (i.e. Load a file) the main process is not blocked. This built-in feature leads to programs that efficiently use the computers CPU. The behavior of an E-MLE can be enhanced by adding new methods of behavior in any of the following ways. The E-MLE can be sub-classed using traditional PM functions written in C. (i.e WinSubclassWindow(...)). New methods can also be added to an E-MLE by simply extending event definitions by writing E or REXX macros. This document describes the Application Program Interface (API) of the E-Toolkit. Examples are provided that dem- onstrate some of the more popular way in which an E-MLE can be used. ----------------------------------------------------------------------------- Introduction. 3 As mentioned above, The E-MLE can also be extended by writing Macros. The E Technical Reference manual describes how macros can be written. ----------------------------------------------------------------------------- 4 Programmers Guide to the E Editor Toolkit. Version 2.0 WRITTING PROGRAMS USING THE E TOOLKIT _____________________________________ There are four basic steps to creating an E-MLE window. The first step is to Register the E-MLE window class. After Registration, a data structure, describing the desired characteristics of your E-MLE, must be created. The next step involves actually creating the E-MLE and an receiving a handle to the E-MLE in return. This handle can now be used to manipulate the E-MLE window. 1) Register the E-MLE window Class. 2) Fill in Data Structure. 3) Create the E-MLE. 4) Manipulate E-MLE ----------------------------------------------------------------------------- Writting programs using the E Toolkit 5 ----------------------------------------------------------------------------- 6 Programmers Guide to the E Editor Toolkit. Version 2.0 GETTING STARTED. ________________ In order to write application programs using the E-Toolkit you first need to download the latest EPM/G package from OS2TOOLS. You will also need copies of the OS/2 1.3 Programmers ToolKit, and the IBM C/2 compiler. (We currently provide language bindings to the 'C' pro- gramming language. ('ETOOLKT.H') Unpack the FLSBIN files that make up the EPM/G package. (Use LOADRAM to unpack FLSBIN files.) There are four major pieces that are essential to the building of your own custom editor application. 1) ETKExxx.DLL - Heart of the E-Toolkit 2) ETKRxxx.DLL - Utility Resources 3) E-Macros - Utility Resources 4) Your Application/Sample Programs ETKEXXX.DLL - THE "HEART" OF THE E-TOOLKIT __________________________________________ The first file is ETKExxx.DLL. This is the dynamic link library that contains the powerful functions that will allow you to create your own custom E-MLE windows. Both messages and functions are available for a user to sub- class the behavior of an E-MLE. Sample functions include: EtkInsertText, EtkProcessEditKey, and EtkSetFileField, and EtkQueryText Sample message include the EPM_EDIT_COMMAND message allows any of the editor commands to be issued against the receiving edit window. The API to this library is described in detail in this document. ETKRXXX.DLL - UTILITY RESOURCES _______________________________ The second file of interest is ETKRxxx.DLL. This file contains Utility Resources. We call this our ERES-Toolkit. It contains widgets that enhance produc- tivity when working with E-MLE's. Dialogs boxes such as the Search, Bookmark, and Error Message dialog can be displayed using the EResPopDialog(...) function. Other utility functions like EResCountEditWindow(...) and EResOpenEditWindow(...) are examples of functions pro- vided so programmers need not write some of the most common actions taken upon E-MLE windows. The API to this library is described in detail in this document. ----------------------------------------------------------------------------- Getting Started. 7 E-MACROS - UTILITY RESOURCES ____________________________ The set of E macros files can be use to build your own custom macros which will enhance your applications E-MLE. For example, you can build new commands using the E macros "defc" construct that can be executed in C using either the EtkExecuteCommand function of the EPM_EDIT_COMMAND message. YOUR APPLICATION/SAMPLE PROGRAMS ________________________________ This is the program that you write. For example EPM.EXE. EPM.EXE is small piece of code that creates E-MLE's and provides the proper glue needed to tie in dialogs, help, macros, and etc. (The *source code* to EPM.EXE ver 5.50 is available via request to EOS2. It will become a per- manent piece of our toolkit package.) Note: It is important that the two dynalink libraries are placed in a sub-directory that is specified in your LIBPATH environment variable. (Your LIBPATH environment variable is found in your CONFIG.SYS file.) Before you attempt to write you own application, you should examine the sample programs provided with this package. A sample program named ESIMPLE is provided to demonstrate the "basics" of an E-MLE application. The sample contains two source files: o ESIMPLE.C o ESIMPLE.E ESIMPLE.C creates a parent window containing a single E-MLE window. The parent monitors cursor movement within the E-MLE by processing the EPM_EDIT_CURSORMOVE message. When this message is received, a status line is painted containing the line and column of the cursor. ESIMPLE.E contains a definition of a handful of keys. ESIMPLE.MAK is provided to compile and link all compo- nents of the ESIMPLE example. (When you build your own custom application, be sure to use the same link and compile options as used in the example. You are now ready to write your own editor application using the Editor Toolkit. ----------------------------------------------------------------------------- 8 Programmers Guide to the E Editor Toolkit. Version 2.0 SPECIAL NOTES!!! ________________ 1) PM Queue size. Take note of the PM Queue Size specified in the ESIMPLE program. hmq = WinCreateMsgQueue(hab, 0x100); // Create Queue We strongly recommend the above PM queue definition because the E-MLE requires a large queue for message passing. 2) E-MLE window handles. (E-MLE Positioning) The E-MLE window is a standard PM window. At minimum, it contains a frame window as well as a client window. (You can us the PMstyle flag to add any other standard window control as well.) To posi- tion the E-MLE window one must use the frame window handle. The EtkCreate function returns a handle to the E-MLE client window. The following is an example of positioning an E-MLE window. VOID PositionMLE( HWND hwndMLE, SHORT x, SHORT y, SHORT cx, SHORT cy) { HWND hMLEFrame=WinQueryWindow( hwndMLE, QW_PARENT, FALSE ); WinSetWindowPos(hMLEFrame, NULL, x ,y ,cx ,cy, SWP_MOVE | SWP_SIZE); } ----------------------------------------------------------------------------- Getting Started. 9 ----------------------------------------------------------------------------- 10 Programmers Guide to the E Editor Toolkit. Version 2.0 E TOOLKIT FUNCTIONS AT A GLANCE. ________________________________ The following functions are used to create and manage E-MultiLine Edit (E-MLE) windows: REGISTER, CREATE, DELETE FUNCTIONS (THE BASICS) _______________________________________________ The following Dynalink functions are used to registra- tion, initialization, and destroy E-MLE windows. ETKREGISTER Register the E-MLE window class. ETKCREATE Create an E-MLE Window. ETKDESTROY Destroy a Edit Window. ETKVERSION Retrieve the ETKxxx.DLL version number. ETKGETPROCADDRS Retrieve function address of the "basic" func- tions. SPECIAL ACCESS- E-MLE MANIPULATION __________________________________ The following Dynalink functions are used to manipulate various aspects of an E-MLE. ---------------- EVENT EXECUTION. ETKEXECUTECOMMAND Execute an command ETKPROCESSEDITKEY Execute a "built-in" key action ----------------- TEXT MINIPULATION ETKDELETETEXT Delete a line of text. ETKREPLACETEXT Replace a line of text with a new line. ETKINSERTTEXT Insert a new line of text. ----------------------------------------------------------------------------- E Toolkit functions at a glance. 11 ETKQUERYTEXT Retreive a line of text. ETKQUERYTEXTBUFFER Retreive a range of lines. ETKINSERTTEXTBUFFER Insert a stream of text. ETKFINDATTRIBUTE Search for an attribute associated with a line. -------------- TEXT SELECTION ETKSETSELECTION Select text ETKQUERYSELECTION Query selection region. ETKQUERYSELECTIONTYPE Query Selection Type. ---------------- FILE INFORMATION ETKQUERYFILEID Query the active files id. ETKSETFILEFIELD Set file related information ETKQUERYFILEFIELD Query file related information ETKQUERYFILEFIELDSTRING Query file related information ----- FONTS ETKREGISTERFONT Register a new font ETKREGISTERFONT2 Register a new fixed pitch font. --------------- SPECIAL ACCESS. ETKACCESSLOWLEVELDATA It's a secret. :-) ----------------------------------------------------------------------------- 12 Programmers Guide to the E Editor Toolkit. Version 2.0 ----------------------------------------------------------------------------- E Toolkit functions at a glance. 13 ----------------------------------------------------------------------------- 14 Programmers Guide to the E Editor Toolkit. Version 2.0 REGISTER, CREATE, DELETE FUNCTIONS (THE BASICS) _______________________________________________ ----------------------------------------------------------------------------- Register, Create, Delete functions (The basics) 15 ETKREGISTER - _____________ (REGISTER AN E-MULTI-LINE EDIT WINDOW) ______________________________________ ----------------------------------------------------------------------------- Register the E-Multi-Line Edit Window Class for this process. +-------------------------------------------------------+ | ETKREGISTER (HAB, CLASS_STYLE, Window_Class_Name ) | _________________ +-------------------------------------------------------+ PARAMETERS HAB (HAB) - input _____ Application anchor block CLASS_STYLE (ULONG) - input _______ Default window style. This can be any of the standard PM class styles CS_*. RETURNS WINDOW_CLASS_NAME (PSZ) - _____ Pointer to window-class-name string in which the editor window was registered under. REMARKS This call only needs to be called once per applica- tion. This function issues a WinRegisterClass. Your application can customize this registration process. The first 16 bytes of window storage is reserved for the E-MLE window. You can use EtkWndProc as the default window procedure for your custom class. EXAMPLE WinRegisterClass( // Register Window Class (HAB)hab, // Anchor block handle (PSZ)classEwindow, // Window Class name (PFNWP)EtkWndProc, // Address of Window Procedure (ULONG)class_style, // class style (USHORT)16 // ETK uses the first 16bytes of ); // the reserved long. ----------------------------------------------------------------------------- 16 Programmers Guide to the E Editor Toolkit. Version 2.0 ETKCREATE - ___________ (CREATE A E-MULTI-LINE EDIT CONTROL WINDOW) ___________________________________________ ----------------------------------------------------------------------------- Create a new E-Multi-line edit control window con- taining specified file(s). +-------------------------------------------------------+ | ETKCREATE (EPM_P, HWND_P, rc ) | __ +-------------------------------------------------------+ PARAMETERS EPM_P (PEDITORINFO) - input _____________ Pointer to Text Editor Information Structure. .---------------------------------------------------------------------------. | Editor Information Structure defined in 'C' | |---------------------------------------------------------------------------| | typedef struct EDIT_INFO_TYPE { | | HAB hab; // application anchor block | | HWND hwndparent; // handle to parent of edit window | | HWND hwndowner; // handle to owner of edit window | | PRECTL pswp // positioning of edit window | | PSZ filename; // file to be edited (with wildcard) | | HPOINTER hEditPtr; // handle to editor pointer icon. | | HPOINTER hMarkPtr; // handle to mark pointer icon. | | PVOID hEditorIcon; // editor ICON. | | ULONG editorstyle; // internal editor options | | ULONG pmstyle; // PM standard window styles (FCF_xxxx) | | USHORT font; // - Not used in versions greater than 5.20 | | PSZ exfile; // pre-compiled macro code file (EPM.EX) | | PSZ *topmkr; // top and bottom of file marker | | PSZ *botmkr; // | | SHORT editid; // unique window id specified for edit window | | PSZ exsearchpath; // a set of paths to search for ex's files | | PSZ exe_path; // path where the application started | | HINI hini; // handle to an opened ini profile | | } EDITORINFO; | | | '---------------------------------------------------------------------------' See Appendix A for a detailed description of the EDITORINFO structure. HWND_P (PHWND) - output _______ Pointer to E-MLE's client window. RETURNS RC (USHORT) - ________ TRUE if a error occurred during E-MLE window cre- ation. REMARKS This call creates a unique E-MLE window. Each E-MLE is a complete new instance of the text editor. Therefore, it knows little about any other E-MLE windows that have been previously created. Each ----------------------------------------------------------------------------- Register, Create, Delete functions (The basics) 17 E-MLE window has it's own marks, tabs, margins, and etc. Starting with version 5.50, the E-MLE's use GPI fonts for text I/O. An E-MLE window can render text in multiple font faces and sizes. (See Appendix ???????) An application can create as many E-MLE's as system memory will permit. Each E-MLE instance can contain a ring a files. A RING can contain as many files as system memory will permit. ----------------------------------------------------------------------------- 18 Programmers Guide to the E Editor Toolkit. Version 2.0 ETKDESTROY - ____________ (DESTROY A MULTI-LINE EDIT CONTROL WINDOW) __________________________________________ ----------------------------------------------------------------------------- Close a E-MLE window. +-------------------------------------------------------+ | ETKDESTROY (HAB, HWNDOWNER, HWNDEDIT, rc ) | __ +-------------------------------------------------------+ PARAMETERS HAB (HAB) - input _____ Anchor block HWNDOWNER (HWND) - input ______ Handle of the owner of the E-MLE window. Usually this is the application client window. HWNDEDIT (HWND) - input ______ E-MLE window to destroy RETURNS RC (USHORT) - ________ One of the following messages are returned. (These messages are defined in EDLL.H) o EPM_RC_DESTROYOK - E-MLE window has suc- cessfully closed. o EPM_RC_DESTROYTIMEOUT - the interpreter has timed out because it was either running a very long command, or it was executing a defexit that had a problem. o EPM_RC_DESTROYCANCEL - the user did not wish to close the E-MLE window. REMARKS Since E is a memory based editor, the destroy func- tion will not effect the most recent copy of the text file on disk. The destroy function generates a WM_DESTROY message. It is this message that actu- ally closes the edit window. You may choose to send this message directly instead of using the destroy function. It is important to check the return code when sending the E-MLE window a WM_DESTROY. If the E-MLE window receives a destroy message, and a modi- fied file exists in its ring, an EPM_EDIT_ASKTOCLOSE message is sent to the application. (See EPM_EDIT_ASKTOCLOSE message in the section "Editor Toolkit Messages" ) This message gives the applica- tion a chance to display a dialog box asking the user if they want to "really close" the window. ----------------------------------------------------------------------------- Register, Create, Delete functions (The basics) 19 ETKVERSION - ____________ (DYNALINK VERSION) __________________ ----------------------------------------------------------------------------- Get the version of the Editor dynalink library(ETKExxx.DLL) +-------------------------------------------------------+ | ETKVERSION (VERSION_STR, ) | +-------------------------------------------------------+ PARAMETERS VERSION_STR (PSZ) - output _____ Pointer to a buffer of memory. This will be filled with the current dynalink version. The return string is in the following format: byte [1] - length of string to follow. byte [2 - length] - Null terminated version string. RETURNS VOID REMARKS A constant, 'EVERSION', is provided in the EDLL.H file. This constant is to be compared to the results of the EtkVersion procedure. An example follows: EXAMPLE CHAR EDLLVersion[20]; EtkVersion( EDLLVersion ); // Get Version from .DLL vercmp=strcmp( EDLLVersion, EVERSION ); // compare version numbers if (vercmp) { WinMessageBox ((HWND)HWND_DESKTOP, // Display editor return code (HWND)hwndAppFrame, (PSZ)"Version Mismatch", (PSZ)"Check ETKExxx.DLL version", NULL, MB_ICONEXCLAMATION ); return(1); } ----------------------------------------------------------------------------- 20 Programmers Guide to the E Editor Toolkit. Version 2.0 SPECIAL ACCESS FUNCTIONS- E-MLE MANIPULATION ____________________________________________ EVENT EXECUTION. ________________ ----------------------------------------------------------------------------- Special Access Functions- E-MLE Manipulation 21 ETKEXECUTECOMMAND - ___________________ (EXECUTE AN E -COMMAND) _______________________ ----------------------------------------------------------------------------- This function will execute any predefined command. +-------------------------------------------------------+ | ETKEXECUTECOMMAND (HWNDEDIT, COMMAND, rc ) | __ +-------------------------------------------------------+ PARAMETERS HWNDEDIT (HWND) - input ______ Window handle to the E-MLE in which the specified command will execute. COMMAND (PSZ) - input _____ An asciiz command string that is defined as either an internal command, an E macro, or a REXX macro. RETURNS RC (ULONG) - _______ TRUE if action failed. REMARKS This is one of the more versatile commands available in the E Toolkit. Three classes of commands can be executed: o Internal Commands. (examples - SAVE, L[ocate], and C[hange]). o Predefined E macros. (examples - ADD, DRAW, and GET) o REXX macros commands. (examples - RX SORT.ERX, RX ADDMENU.ERX, RX NEW.ERX) An example of how to use this function follows. EXAMPLE { HWND hwndEdit=QueryEditHandle( ); // issue a "save" command to an E-MLE. The data is saved in // a file called temp.tmp. EtkExecuteCommand( hwndEdit, "SAVE temp.tmp") ; } ----------------------------------------------------------------------------- 22 Programmers Guide to the E Editor Toolkit. Version 2.0 ETKPROCESSEDITKEY - ___________________ (EXECUTE A EDITOR ACTION) _________________________ ----------------------------------------------------------------------------- Execute a primitive editor action. +-------------------------------------------------------+ | ETKPROCESSEDITKEY (HWNDEDIT, KEY, rc ) | __ +-------------------------------------------------------+ HWNDEDIT (HWND) - input ______ Window handle of the E-MLE. KEY (USHORT) - input ________ Built in key primitives: ADJUST_BLOCK BACKTAB Tab to the left. BACKTAB_WORD Tab to the left one word. BEGIN_LINE Move the cursor to the beginning of the line. BOTTOM Move the cursor to the last line in the file. COPY_MARK Copy the current selection to the cursor location. DELETE_CHAR Delete the character in which the cursor is located. DELETE_LINE Delete the line in which the cursor is located. DELETE_MARK Delete the current selection. DOWN Scroll down one line. END_LINE Move the cursor to the end of the current line. ERASE_END_LINE Erase from the cursor to the end of the line. INSERT_LINE Insert a new line after the cursor. INSERT_TOGGLE Toggle between insert and replace cursor. JOIN Join next line with the line in which the cursor is located. LEFT Scroll one character to the left. MOVE_MARK Move the current selection to the cursor location. NEXT_FILE Go to the next file in the Ring. OVERLAY_BLOCK Overlay the current block selection to the cursor location. PAGE_DOWN Scroll one page down. PAGE_UP Scroll one page up. PREVFILE_OP Go to the previous file in the Ring. REFLOW Reflow the text according to the margins settings. REPEAT_FIND Repeat the last find. RIGHT Scroll right one character. ----------------------------------------------------------------------------- Special Access Functions- E-MLE Manipulation 23 RUBOUT Move cursor to the left and delete char- acter. SHIFT_LEFT Shift the selected text one character to the left. SHIFT_RIGHT Shift the selected text one character to the right. SPLIT Split the current line at the cursor. TAB Move cursor to the next tab position. TAB_WORD Tab to the right one word. TOP Move the cursor to the first line in the file. UNDO_LINE Return the current line to its original state. UNMARK Clear the current selection. UP Scroll up one line. REMARKS EXAMPLE ----------------------------------------------------------------------------- 24 Programmers Guide to the E Editor Toolkit. Version 2.0 TEXT MANIPULATION _________________ ----------------------------------------------------------------------------- Special Access Functions- E-MLE Manipulation 25 ETKQUERYTEXT - ______________ (RETRIEVE A LINE) _________________ ----------------------------------------------------------------------------- Retrieve a line of text and its associated attri- butes. +-------------------------------------------------------+ | ETKQUERYTEXT (HWNDEDIT, FILEID, LINENUM, TEXT, ATTRS, | | ALATTR, rc ) | __ +-------------------------------------------------------+ PARAMETERS HWNDEDIT (HWND) - input ______ Window handle to the E-MLE that will contain the selected text. FILEID (ULONG) - input _______ the fileid of the file containing the specified line. If 0 is specified, the line will be retrieved from the visible file. LINENUM (ULONG) - input _______ line number of interest. TEXT (PSZ *) - output _______ Returns an indirect pointer to the text found on the specified line. ATTRS (PVOID) - output _______ returns a pointer to an attribute structure that describes the attributes (i.e. font, color) associ- ated with that line. ALATTRS (PVOID) - output _______ returns a pointer to an attribute structure that describes the attributes (i.e. font, color) associ- ated with that line. RETURNS RC (ULONG) - _______ TRUE if action failed. REMARKS **************************************************************************** *** TODO - Need a section on how to interpret the attribute structures *** **************************************************************************** EXAMPLE ----------------------------------------------------------------------------- 26 Programmers Guide to the E Editor Toolkit. Version 2.0 ETKDELETETEXT - _______________ (DELETE TEXT) _____________ ----------------------------------------------------------------------------- Delete an area of text. +-------------------------------------------------------+ | (HWNDEDIT, FILEID, STARTLINE, NUMBER_OFLINES, rc ) | __ +-------------------------------------------------------+ PARAMETERS HWNDEDIT (HWND) - input ______ Window handle to the E-MLE. FILEID (ULONG) - input _______ the fileid of the file containing the specified line. If filid=0 is specified, the line will be retrieved from the visible file. STARTLINE (ULONG) - input _______ starting line number NUM_OF_LINES (ULONG) - input _______ number of lines to delete. If (-1L) then lines are deleted from the start line through the last line in the file. RETURNS RC (ULONG) - _______ TRUE if action failed. REMARKS EXAMPLE ----------------------------------------------------------------------------- Special Access Functions- E-MLE Manipulation 27 ETKREPLACETEXT - ________________ (REPLACE A LINE) ________________ ----------------------------------------------------------------------------- Replace a line with a new single attributed string +-------------------------------------------------------+ | ETKREPLACETEXT (HWNDEDIT, FILEID, LINENUM, | | ATTRSTRING, rc ) | __ +-------------------------------------------------------+ PARAMETERS HWNDEDIT (HWND) - input ______ Window handle to the E-MLE that will contain the selected text. FILEID (ULONG) - input _______ the fileid of the file containing the specified line. If 0 is specified, the line will be retrieved from the visible file. LINENUM (ULONG) - input _______ starting line number ATTRS (PVOID) - input _______ a pointer to an attribute structure that describes the attributes (i.e. font, color) associated with that line. RETURNS RC (ULONG) - _______ TRUE if action failed. REMARKS **************************************************************************** *** TODO - Need a section on how to interpret the attribute structures *** **************************************************************************** EXAMPLE ----------------------------------------------------------------------------- 28 Programmers Guide to the E Editor Toolkit. Version 2.0 ETKINSERTTEXT - _______________ (ADD A LINE) ____________ ----------------------------------------------------------------------------- Insert a single attributed string +-------------------------------------------------------+ | ETKINSERTTEXT (HWNDEDIT, FILEID, LINENUM, ATTRSTRING, | | rc ) | __ +-------------------------------------------------------+ PARAMETERS HWNDEDIT (HWND) - input ______ Window handle to the E-MLE that will contain the selected text. FILEID (ULONG) - input _______ the fileid of the file containing the specified line. If 0 is specified, the line will be retrieved from the visible file. LINENUM (ULONG) - input _______ starting line number ATTRS (PVOID) - input _______ A pointer to an attribute structure that describes the attributes. (i.e. font, color) associated with that line. RETURNS RC (ULONG) - _______ TRUE if action failed. REMARKS **************************************************************************** *** TODO - Need a section on how to interpret the attribute structures *** **************************************************************************** EXAMPLE ----------------------------------------------------------------------------- Special Access Functions- E-MLE Manipulation 29 ETKQUERYTEXTBUFFER - ____________________ (QUERY TEXT BUFFER) ___________________ ----------------------------------------------------------------------------- Retrieve a stream of text within a specified line range. +-------------------------------------------------------+ | ETKQUERYTEXTBUFFER (HWNDEDIT, STARTLINE, LASTLINE, | | TOTALLEN, BUFFER, characters ) | __________ +-------------------------------------------------------+ PARAMETERS HWNDEDIT (HWND) - input ______ Window handle of the E-MLE. STARTLINE (ULONG) - input _______ First line in text range. LASTLINE (ULONG) - input _______ Last Line in range. TOTALLEN (ULONG) - input _______ Size of buffer BUFFER (PSZ) - output _____ Buffer where text stream will be returned. RETURNS CHARACTERS (ULONG) - _______ The number of characters in the buffer is returned. If 0 is returned, it is likely that a problem occured. (Most likely an invalid line number) REMARKS If startline and lastline are zero (0), the entire file will be returned. The Buffer contains a stream of characters where each line ends in CR-LF. ----------------------------------------------------------------------------- 30 Programmers Guide to the E Editor Toolkit. Version 2.0 ETKINSERTTEXTBUFFER - _____________________ (INSERT TEXT BUFFER) ____________________ ----------------------------------------------------------------------------- Enter a stream of text starting at a specified point. +-------------------------------------------------------+ | ETKINSERTTEXTBUFFER (HWNDEDIT, STARTLINE, TOTALLEN, | | TEXT, lines ) | _____ +-------------------------------------------------------+ PARAMETERS HWNDEDIT (HWND) - input ______ Window handle of the E-MLE. STARTLINE (ULONG) - input _______ Insert starting at this line. TOTALLEN (ULONG) - input _______ Size of buffer TEXT (PSZ) - input _____ Text stream to insert. RETURNS LINES (ULONG) - _______ The number of lines inserted in to the E-MLE. If 0 is returned, it is likely that a problem occured. (Most likely an invalid line number) REMARKS If startline is zero (0), the Text is inserted at the current cursor position. The Text buffer should contain a stream of charac- ters where each line ends in CR-LF. EXAMPLE { UCHAR string[512], strcpy(string, "1: This is a test\r\n2: This is line 2\r\n"); EtkInsertTextBuffer( hwndEdit, 1, strlen(string), string); } ----------------------------------------------------------------------------- Special Access Functions- E-MLE Manipulation 31 ETKFINDATTRIBUTE. - ___________________ (RETRIEVE A LINE ATTRIBUTE) ___________________________ ----------------------------------------------------------------------------- Search for an attribute associated with a line. +-------------------------------------------------------+ | ETKFINDATTRIBUTE (HWNDEDIT, FILEID, LINENUM, COLUMN, | | COLUMNOFFSET, ATTRIBUTE, PFOUND, rc ) | __ +-------------------------------------------------------+ PARAMETERS HWNDEDIT (HWND) - input ______ Window handle to the E-MLE that will contain the selected text. FILEID (ULONG) - input _______ the fileid of the file containing the specified line. If 0 is specified, the line will be retrieved from the visible file. LINENUM (ULONG) - input _______ starting line number COLUMN (USHORT) - input ________ starting column COLUMNOFFSET (USHORT) - input ________ Column Offset. ATTRS (PVOID) - input _______ A pointer to an attribute structure that describes the attributes (i.e. font, color) associated with that line. PFOUND (BOOLEAN *) - output ___________ found flag. RETURNS RC (ULONG) - _______ TRUE if action failed. REMARKS **************************************************************************** *** TODO - Need a section on how to interpret the attribute structures *** **************************************************************************** EXAMPLE ----------------------------------------------------------------------------- 32 Programmers Guide to the E Editor Toolkit. Version 2.0 TEXT SELECTION. _______________ ----------------------------------------------------------------------------- Special Access Functions- E-MLE Manipulation 33 ETKQUERYSELECTIONTYPE - _______________________ (QUERY CURRENT SELECTION TYPE) ______________________________ ----------------------------------------------------------------------------- Returns the current selection type. The E Toolkit supports three types of text selection. Character, Line, and Block. +-------------------------------------------------------+ | ETKQUERYSELECTIONTYPE (HWNDEDIT, MARKTYPE, rc ) | __ +-------------------------------------------------------+ PARAMETERS HWNDEDIT (HWND) - input ______ Window handle of the E-MLE. MARKTYPE (PUSHORT) - output _________ The E Toolkit will fill this value with a constant that represents the type of mark contained in the visible file. #define LINEMARK 0 #define CHARMARK 1 #define BLOCKMARK 2 #define CHARMARKG 3 #define BLOCKMARKG 4 #define NOMARK -1 RETURNS RC (USHORT) - ________ TRUE if action failed. REMARKS EXAMPLE { HWND hwndEdit=QueryEditHandle( ); USHORT marktype; UCHAR outmsg[MAXSTR]; strcpy( outmsg, "Your file contains "); EtkQuerySelectionType( hwndEdit, &marktype); switch (marktype) { case LINEMARK: strcat( outmsg, "a Line Mark"); break; case CHARMARK: strcat( outmsg, "a Character Mark"); break; case CHARMARKG: strcat( outmsg, "a Special Character Mark");break; case BLOCKMARK: strcat( outmsg, "a Block Mark"); break; case BLOCKMARKG: strcat( outmsg, "a Special Block Mark"); break; default: strcat( outmsg, "no mark."); break; } } ----------------------------------------------------------------------------- 34 Programmers Guide to the E Editor Toolkit. Version 2.0 ETKQUERYSELECTION - ___________________ (SELECTION LOCATION) ____________________ ----------------------------------------------------------------------------- Returns the coordinates of the selected text area. +-------------------------------------------------------+ | ETKQUERYSELECTION (HWNDEDIT, FIRSTLINE, LASTLINE, | | FIRSTCOL, LASTCOL, MARKFILEID, RESPECTATTRIBUTES, | | RELATIVE2FILE, rc ) | __ +-------------------------------------------------------+ PARAMETERS HWNDEDIT (HWND) - input ______ Window handle of the E-MLE that contains selected text. FIRSTLINE, LASTLINE (PULONG) - output ________ returns the first and last lines in the selected area. FIRSTCOL, LASTCOL (PUSHORT) - output _________ returns the first and last columns in the selected area. MARKFILEID (PULONG) - output ________ returns the fileid of the file containing the selected text. RESPECTATTRIBUTES (PUSHORT) - output _________ If TRUE, Font and color attribute information will be taken into consideration. RELATIVE2FILE (PUSHORT) - output _________ Should always be set to TRUE. RETURNS RC (USHORT) - ________ TRUE if action failed. REMARKS EXAMPLE ----------------------------------------------------------------------------- Special Access Functions- E-MLE Manipulation 35 { ULONG firstline, lastline; USHORT firstcol, lastcol; LONG markfileid; SHORT marktype; USHORT respectattributes=FALSE, relative2file=TRUE; EtkQuerySelectionType( hwndEdit, &marktype); if (marktype!=NOMARK) { EtkQuerySelection(QueryActiveEdit(), &firstline, &lastline, &firstcol, &lastcol, &markfileid, respectattributes, relative2file); } } ----------------------------------------------------------------------------- 36 Programmers Guide to the E Editor Toolkit. Version 2.0 ETKSETSELECTION - _________________ (SELECT TEXT) _____________ ----------------------------------------------------------------------------- Specifiy the type of selection along with the area of text to be selected. +-------------------------------------------------------+ | ETKSETSELECTION (HWNDEDIT, FIRSTLINE, LASTLINE, | | FIRSTCOL, LASTCOL, FIRSTOFF, LASTOFF, MARKTYPE, | | FILEID, rc ) | __ +-------------------------------------------------------+ PARAMETERS HWNDEDIT (HWND) - input ______ Window handle to the E-MLE that will contain the selected text. FIRSTLINE, LASTLINE (ULONG) - input _______ The first and last lines in the selected area. FIRSTCOL, LASTCOL (USHORT) - input ________ The first and last columns in the selected area. FIRSTOFF, LASTOFF (USHORT) - input ________ The attribute offset associated with the first and last column. (If color or font attributes are not being used, set to 0) MARKTYPE (USHORT) - input ________ #define LINEMARK 0 #define CHARMARK 1 #define BLOCKMARK 2 #define CHARMARKG 3 #define BLOCKMARKG 4 #define NOMARK -1 MARKFILEID (USHORT) - input ________ the fileid of the file containing the selected text. If -1 is specified, the text will be selected in the visible file. RETURNS RC (USHORT) - ________ TRUE if action failed. REMARKS EXAMPLE ----------------------------------------------------------------------------- Special Access Functions- E-MLE Manipulation 37 { ULONG firstline, lastline; USHORT firstcol, lastcol; LONG markfileid; SHORT marktype; USHORT respectattributes=FALSE, relative2file=TRUE; EtkQuerySelectionType( hwndEdit, &marktype); if (marktype!=NOMARK) { HWND hwndEdit=QueryActiveEdit(); EtkQuerySelection(hwndEdit, &firstline, &lastline, &firstcol, &lastcol, &markfileid, respectattributes, relative2file); // extend the mark one line. EtkSetSelection(hwndEdit, firstline, lastline+1, firstcol, lastcol, 0, 0, marktype, markfileid); } } ----------------------------------------------------------------------------- 38 Programmers Guide to the E Editor Toolkit. Version 2.0 FILE INFORMATION ________________ ----------------------------------------------------------------------------- Special Access Functions- E-MLE Manipulation 39 ETKQUERYFILEID - ________________ (QUERY A FILES IDENTIFIER) __________________________ ----------------------------------------------------------------------------- Retrieve the visible files file identifier. +-------------------------------------------------------+ | ETKQUERYFILEID (HWNDEDIT, FILEID, rc ) | __ +-------------------------------------------------------+ PARAMETERS HWNDEDIT (HWND) - input ______ Window handle to the E-MLE that will contain the selected text. FILEID (PUSHORT) - input _________ returns the fileid of the visible file. RETURNS RC (USHORT) - ________ TRUE if action failed. REMARKS The file identifier is an constant that is used by certian functions to identify a particular file in an E-MLE window Ring. EXAMPLE ----------------------------------------------------------------------------- 40 Programmers Guide to the E Editor Toolkit. Version 2.0 ETKSETFILEFIELD - _________________ SET SOME FILE CHARACTERISTIC ____________________________ ----------------------------------------------------------------------------- Set information pertaining to some aspect of a file. (i.e. Margin, Name, etc) +-------------------------------------------------------+ | ETKSETFILEFIELD (HWNDEDIT, FIELD, FILEID, INDATA, rc | __ | ) | +-------------------------------------------------------+ PARAMETERS HWNDEDIT (HWND) - input ______ Window handle of the E-MLE. FIELD. (ULONG) - input _______ SEE APPENDIX A1 FOR FIELD CONSTANTS AND VALUES EXPECTED BY EACH FIELD. FILEID (ULONG) - input _______ the fileid INDATA (PVOID) - input _______ The input data varies depending on the field being set. SEE APPENDIX A-1 FOR FIELD CONSTANTS AND VALUES EXPECTED BY EACH FIELD. RETURNS RC (USHORT) - ________ TRUE if action failed. REMARKS EXAMPLE { UCHAR s[MAXSTR]; ULONG Browse; Browse = 0L; // turn OFF browse mode - the file can now be modified. EtkSetFileField(hwndMLE,(ULONG)READONLY_FIELD,(ULONG)0,(PVOID)Browse); // Insert a stream of text... strcpy( s,"Hello World\r\nAnother Line\r\nAnd another..."); EtkInsertTextBuffer( hwndMLE, 1, strlen(s), s); Browse = 1L; // turn ON browse mode - the file is now read only! EtkSetFileField(hwndMLE,(ULONG)READONLY_FIELD,(ULONG)0,(PVOID)Browse); } ----------------------------------------------------------------------------- Special Access Functions- E-MLE Manipulation 41 ETKQUERYFILEFIELD - ___________________ (QUERY SOME FILE CHARACTERISTIC) ________________________________ ----------------------------------------------------------------------------- Query information pertaining to some aspect of a file. (i.e. Margin, Name, etc) +-------------------------------------------------------+ | ETKQUERYFILEFIELD (HWNDEDIT, FIELD, FILEID, | | RETURNDATA, rc ) | __ +-------------------------------------------------------+ PARAMETERS HWNDEDIT (HWND) - input ______ Window handle of the E-MLE. FIELD. (ULONG) - input _______ SEE APPENDIX A1 FOR FIELD CONSTANTS AND VALUES EXPECTED BY EACH FIELD. FILEID (ULONG) - input _______ the fileid RETURNDATA (PVOID) - output _______ data returned. This data varies depending on the field being queried. SEE APPENDIX A1 FOR FIELD CON- STANTS AND VALUES EXPECTED BY EACH FIELD. RETURNS RC (USHORT) - ________ TRUE if action failed. REMARKS EXAMPLE { ULONG numlines; // query the number of lines in a given file. EtkQueryFileField(hwndMLE,(ULONG)LAST_FIELD,(ULONG)0,(PVOID)&numlines); } ----------------------------------------------------------------------------- 42 Programmers Guide to the E Editor Toolkit. Version 2.0 ----------------------------------------------------------------------------- Special Access Functions- E-MLE Manipulation 43 ----------------------------------------------------------------------------- 44 Programmers Guide to the E Editor Toolkit. Version 2.0 E TOOLKIT MESSAGES __________________ Purpose The following messages are used to interact with an edit window object. Remarks The numbering of the following messages are: (using C and PM standards) ----------------------------------------------------------------------------- E Toolkit Messages 45 EPM_BROADCASTHELP EPM_EDIT_OPTION EPM_EDIT_PLAYKEY EPM_EDIT_ACTIVATEFILEID EPM_EDIT_POSTDONE EPM_EDIT_ACTIVEHWND EPM_EDIT_ASKTOCLOSE EPM_EDIT_ASKTODONE EPM_EDIT_ASKTOFAILED EPM_EDIT_QUERYRECORDKEY EPM_EDIT_ASKTOQUIT EPM_EDIT_QUERY_HELP_INSTANCE EPM_EDIT_CHANGEFONT * (to be implemented for 5.50) EPM_EDIT_RECORDKEY EPM_EDIT_CHAR EPM_EDIT_RETCODE EPM_EDIT_CLIPBOARDCOPY EPM_EDIT_SAYERROR EPM_EDIT_CLIPBOARDPASTE EPM_EDIT_COMMAND EPM_EDIT_SHOW EPM_EDIT_COMMAND2 EPM_EDIT_TURN_OFF_HIGHLIGHT EPM_EDIT_CONTROLTOGGLE * ( need access to CONTROL constants.) EPM_EDIT_CURSORMOVE EPM_EDIT_VERSION EPM_EDIT_WIN2DOC * (Jason needs to document this one.) EPM_EDIT_DESTROYNOTIFY EPM_EDIT_DESTROYRC EPM_EXTRAWINDOW_REFRESH EPM_EDIT_DOC2WIN * (Jason needs to document this one.) EPM_FRAME_MESSAGELINE EPM_FRAME_STATUSLINE EPM_EDIT_ENDRECORDKEY EPM_EDIT_TASKLIST ------------- TODO ---------------- EPM_EDIT_EXEC_DYNALINK * (GAC has to document this one.) EPM_GET_ERROR_MESSAGE EPM_EDIT_EXEC_PROC EPM_IS_HELP_LOADED EPM_EDIT_GETMEM EPM_PRINT_RENDERPAGE EPM_EDIT_GETPROFILE EPM_PRINT_RENDERPAGERC EPM_EDIT_HELPNOTIFY EPM_QHELP_TABLE EPM_EDIT_ID EPM_QUERY_GLOBDATA EPM_EDIT_MINMAXFRAME EPM_SEND_MACROS_ERRORS EPM_EDIT_NEWFILE ----------------------------------- ----------------------------------------------------------------------------- 46 Programmers Guide to the E Editor Toolkit. Version 2.0 Note: Editor messages are either SEND messages or ____ RECEIVE messages. The SEND messages are sent from _______ ____ your application to the edit window. The RECEIVE _______ messages are sent by an edit window to the regis- tered owner's window procedure. ----------------------------------------------------------------------------- E Toolkit Messages 47 EPM_FRAME_STATUSLINE ____________________ ---------------------------------------------- (UPDATE STATUS LINE) - SENT TO AN E-MLE WINDOW Purpose Updates the status line's template and color. Message Parameter 1 STATUS_TEMPLATE (PSZ) Status temple string to be ________________ filled in by status line. (See Remarks for status_template format) Message Parameter 2 STATUSLINE_COLOR( USHORT) ________________ (LOCHAR)foreground color (HICHAR)background color Return NULL Remarks: If a color is not specified, then the current color is used. The pointer passed in _______________________ Message Parameter 1 IS FREED by this message. It ________________________________________________ must be allocated using DosAllocSeg, because it is freed using DosFreeSeg. The following tags are supported in the status tem- plate: %L current line number. %C current column number. %F files in E-MLE Ring. %M displays "Modified" if visible file is modified. %I Displays "Insert" or "Replace" %Z - %X Displays character at cursor is ascii(%z) or in hex(%x). %S Total number of lines in file. %A Autosave value. ----------------------------------------------------------------------------- 48 Programmers Guide to the E Editor Toolkit. Version 2.0 For example, if the following template string was passed: Line=%l Column=%C Mode=%i, The Ring contains %f The status line would display: Line=1290 Column=72 Mode=Insert, The Ring contains 2 Files. ----------------------------------------------------------------------------- E Toolkit Messages 49 EPM_FRAME_MESSAGELINE _____________________ ----------------------------------------------- (UPDATE MESSAGE LINE) - SENT TO AN E-MLE WINDOW Purpose Updates the message line's text and color. Message Parameter 1 MESSAGE (PSZ) string to appear on message line ________ Message Parameter 2 MESSAGELINE COLOR( USHORT) _________________ (LOCHAR)foreground color (HICHAR)background color Return NULL Remarks: If a color is not specified, then the current color is used. The pointer passed in ________________________ Message Parameter 1 IS FREED by this message. It ________________________________________________ must be allocated using DosAllocSeg, because it is freed using DosFreeSeg. ----------------------------------------------------------------------------- 50 Programmers Guide to the E Editor Toolkit. Version 2.0 EPM_EDIT_VERSION ________________ ----------------------------------------- (E-MLE VERSION) - SENT TO AN E-MLE WINDOW Purpose Return the E-Toolkit version number. Message Parameter 1 NOT USED (LONG) _________ Message Parameter 2 NOT USED() ________ Return NULL Remarks: ----------------------------------------------------------------------------- E Toolkit Messages 51 EPM_EDIT_TURN_OFF_HIGHLIGHT ___________________________ ---------------------------------------------- (TURN OFF HIGHLIGHT) - SENT TO AN E-MLE WINDOW Purpose Clear text circled by the CIRCLEIT macro. Message Parameter 1 NOT USED (LONG) _________ Message Parameter 2 NOT USED() ________ Return NULL Remarks: ----------------------------------------------------------------------------- 52 Programmers Guide to the E Editor Toolkit. Version 2.0 EPM_EDIT_QUERY_HELP_INSTANCE ____________________________ ------------------------------------------------- (QUERY HELP INSTANCE) - SENT FROM AN E-MLE WINDOW Purpose The following is a request from the etoolkit for the handle of the help instance Message Parameter 1 NOT USED (LONG) _________ Message Parameter 2 NOT USED() ________ Return NULL Remarks: This is how EPM.EXE handles this messages. case EPM_EDIT_QUERY_HELP_INSTANCE: if(!GlobData->hwndHelpInstance) { GlobData->hwndHelpInstance = WinCreateHelpInstance(GlobData->hAB,&GlobData->hmiHelpData); } return(GlobData->hwndHelpInstance); break; ----------------------------------------------------------------------------- E Toolkit Messages 53 EPM_BROADCASTHELP _________________ ---------------------------------- (BROADCAST HELP) - SENT FROM E-MLE Purpose EPM_BROADCASTHELP is sent a E-MLE applica- tion when the help instance has been initialized. To insure that all existing edit windows add their helpsub tables to the help instance EPM_QHELP_TABLE is broadcasted to all edit windows on the desktop informing them that help has been loaded. If no edit windows are running then EPM_EDIT_QUERY_HELP_INSTANCE is issued to the shell in order to create the help instance. Message Parameter 1 NOT USED (LONG) _________ Message Parameter 2 NOT USED() ________ Return NULL Remarks: This is how EPM.EXE handles this messages. case EPM_BROADCASTHELP: { USHORT rc; rc=ERESBroadcastMsgToEditWindows(GlobData, EPM_QHELP_TABLE, 0L,0L); if(!rc) { WinSendMsg(GlobData->eres.hwndAppClient, EPM_EDIT_QUERY_HELP_INSTANCE, 0L, 0L); } } break; ----------------------------------------------------------------------------- 54 Programmers Guide to the E Editor Toolkit. Version 2.0 EPM_EDIT_DELETEFILE ___________________ ----------------------- (DELETE FILE FROM DISK) Purpose Delete the file specified in mp1 from disk and free pointer Message Parameter 1 FILENAME(PSZ) Fully qualified file name. ________ Message Parameter 2 NOT USED() ________ Return NULL Remarks : ----------------------------------------------------------------------------- E Toolkit Messages 55 EPM_EDIT_ACTIVATEFILEID _______________________ ----------------- (ACTIVATE A FILE) Purpose Activate a file corresponding to the speci- fied file identifier. Message Parameter 1 FILEID (LONG) A file identifier that could be _______ obtained using the EtkQueryFileID function. Message Parameter 2 NOT USED() ________ Return NULL Remarks: ----------------------------------------------------------------------------- 56 Programmers Guide to the E Editor Toolkit. Version 2.0 EPM_EDIT_CHAR _____________ ------------------------- (ISSUE A WM_CHAR MESSAGE) Purpose An alternitive to the WM_CHAR message. It is handled exactly in the same manner as WM_CHAR. Message Parameter 1 MP1(MPARAM) See WM_CHAR in the PM Tech. Ref. ___ Message Parameter 2 MP2(MPARAM) See WM_CHAR in the PM Tech. Ref. ___ Return Remarks: ----------------------------------------------------------------------------- E Toolkit Messages 57 EPM_EDIT_CLIPBOARDCOPY ______________________ ----------------------------------- (INSERT TEXT INTO THE PM CLIPBOARD) Purpose Fast path to inserting text into the PM Clipboard. Message Parameter 1 PTEXTBUF(PVOID) Pointer to a memory buffer con- ________ taining text to copy to the clipboard. The text is in a format described by mp2. Message Parameter 2 MP2() Flag that describes what format of the memory ___ buffer, which was passed in mp1. 0 = CF_TEXT type buffer, terminated by nul 1 = EPM shared memory buffer (32byte head) Return Remarks: When the contents of mp1 is copied to the clipboard a EPM defc event is called by the name of PROCESSCLIPBOARDCOPY. Arg(1) of this function is the original buffer passed in as mp1. The caller may choose to free the buffer during this command. If zero is passed as arg(1), an error was encountered. An error message should be displayed at this point. ----------------------------------------------------------------------------- 58 Programmers Guide to the E Editor Toolkit. Version 2.0 EPM_EDIT_COMMAND ________________ -------------------------------- (EDITOR COMMAND MESSAGE - E-MLE) Purpose Issue a command to the E-MLE Message Parameter 1 EDIT COMMAND (PSZ) Any legal editor command. (See _______________ Appendix B for a complete list of commands) Message Parameter 2 COMMAND FLAGS(USHORT) The following command flags _____________ can be set with the EPM_EDIT_COMMAND message: o COMMAND_SYNC - the command is sent to the edit interpreter thread and is executed imme- diately or after the last command. o COMMAND_FREESEL - free the selector of parameter one when done. o COMMAND_GETABLE - the selector in parameter one is a getable shared segment. Returns void Remarks This message is the main source of communi- cation to editor windows. To send a message to a specific file, send any legal editor command (in string form) to the associated edit window handle. Legal editor commands consist of any of the base editor commands or any user defined commands. User commands can be created within the editor macro lan- guage via DEFC's. For command return codes see the EPM_EDIT_RETCODE ________________ message. See Appendix B for a complete list of commands By default all commands sent or posted to edit windows are copied and posted to the editor inter- ----------------------------------------------------------------------------- E Toolkit Messages 59 preter thread. By setting the COMMAND_SYNC flag the command is sent to the editor interpreter, therefore it will be executed immediately or after the last command is finished executing. When an application other then the one that created an edit window wishes to send a command to an edit window, that application must allocate a shared segment for the command string (parameter one). The COMMAND_GETABLE flag notifies the E Toolkit that the pointer in parameter one is that of a getable shared segment. When an application wants the selector sent in parameter one to be freed after it is used by the E Toolkit, the COMMAND_FREESEL flag must be set. This flag is only valid for selectors allocated within the application that created the edit window. A selector of a getable shared segment can't be freed by the E Toolkit with this message. ----------------------------------------------------------------------------- 60 Programmers Guide to the E Editor Toolkit. Version 2.0 EPM_EDIT_COMMAND2 _________________ ------------------------------------------- (EXECUTE COMMAND) - SENT TO AN E-MLE WINDOW Purpose Same as EPM_EDIT_COMMAND, but if the command does not exist, no error message is generated. Message Parameter 1 See EPM_EDIT_COMMAND Message Parameter 2 See EPM_EDIT_COMMAND Return See EPM_EDIT_COMMAND Remarks ----------------------------------------------------------------------------- E Toolkit Messages 61 EPM_EDIT_CHANGEFONT ___________________ --------------------- (CHANGE E-MLE'S FONT) Purpose Change E-MLE's base font. Message Parameter 1 NAME(PSZ) ____ Font Face Name. Message Parameter 2 SIZE(USHORT) ____ Point Size. STYLE(USHORT) _____ Attribute Style. Remarks ----------------------------------------------------------------------------- 62 Programmers Guide to the E Editor Toolkit. Version 2.0 EPM_EDIT_TASKLIST _________________ -------------------------- (SHOW/HIDE TASK LIST ENTY) Purpose This message can either show or hide a task list entry corresponding to an E-MLE window. It also allows an application to set a prefix string before the task list entry, which typically contains the name of the visible file. Message Parameter 1 FLAG(LOUSHORT) ____ Show task list entry flag TRUE=Show entry FALSE = Hide entry Message Parameter 2 PREFIX_STRING(PSZ) _____________ String to be pre-pended to the task list entry Remarks This message can be either sent of posted, however, if this message is posted, the application is responsible for freeing the string. ----------------------------------------------------------------------------- E Toolkit Messages 63 EPM_EDIT_RETCODE ________________ ------------------------------------ (EDITOR COMMAND MESSAGE RETURN CODE) Purpose Send to the registered owner in response to a edit command. Message Parameter 1 RETURN STRING (PSZ) ______________ Text describing the return code. Message Parameter 2 RETURN CODE (USHORT) ____________ specific editor return code. Remarks Sent to owner registered in the Editor Information structure. (See Appendix A for more details on the Edit Information structure.) This message is in response to a internal editor return code/ error code. See Appendix C for editor return codes. ----------------------------------------------------------------------------- 64 Programmers Guide to the E Editor Toolkit. Version 2.0 EPM_EDIT_CURSORMOVE ___________________ --------------------- (EDITOR CURSOR MOVED) Purpose The cursor has changed position in the edit window. Message Parameter 1 ROW (ULONG) ____ row of cursor in file Message Parameter 2 COLUMN (ULONG) _______ column of cursor in file Remarks Sent to owner registered in the Editor Information structure. (See Appendix A for more details on the Edit Information structure.) This message gives the owner the capability to track the editor's cursor. ----------------------------------------------------------------------------- E Toolkit Messages 65 EPM_EDIT_ACTIVEHWND ___________________ ----------------------- (EDITOR RECEIVED FOCUS) Purpose Notify application that a specific edit window has become active. Message Parameter 1 EDIT WINDOW HANDLE (HWND) ___________________ Handle of active edit window. Message Parameter 2 ACTIVE FILE NAME (PSZ) _________________ Full path of top most file being edited in active edit window. Remarks Processing this message is useful if more than one edit window is being used by a given application. The application does not need to keep global infor- mation on each edit window because it is returned via this message. ----------------------------------------------------------------------------- 66 Programmers Guide to the E Editor Toolkit. Version 2.0 EPM_EDIT_OPTIONS ________________ ----------------------------------------------- (GET EDITOR OPTION INFORMATION) - SENT TO E-MLE Purpose Get a specified piece of editor information. Message Parameter 1 OPTION NUMBER (LONG) ______________ OPTIONS_xxxxx constant. (See Remarks.) Message Parameter 2 [BUFFER](PVOID) ________ Used by some options. Return The returned value depends on the option selected. Constant that specifies one of the following options: OPTIONS_MARGINS Returns 4 bytes containing (lo to hi): left marg (CHAR), right marg (CHAR), paragraph margin (CHAR), 0 (CHAR). OPTIONS_LINE Returns line of file that contains the cursor. (ULONG) OPTIONS_COLUMN Returns column of file that contains the cursor. (ULONG) OPTIONS_INSERT Returns TRUE if cursor is in insert mode. (ULONG) OPTIONS_AUTOSAVE Returns the number of changes before autosave. (ULONG) OPTIONS_NTABS Returns the number of tab stops. (ULONG) ----------------------------------------------------------------------------- E Toolkit Messages 67 OPTIONS_NROWS Returns the total number of rows visible in the E-MLE. (uses the default font height as a measument.) OPTIONS_NCOLS Returns the total number of columns visible in the E-MLE. (uses the default font width as a measument.) (ULONG) OPTIONS_MODIFY Returns TRUE if the file has been modified. (last save) (ULONG) OPTIONS_TAB Returns a pointer to a byte-table of tab values. The table is terminated by a NULL character. (PBYTE) OPTIONS_SEARCH Returns the last string searched by locate or change. (PSZ) OPTIONS_GETTEXT Returns the line of text specified by high word of option parameter. If high word is NULL the the line in which the cursor is currently on is returned. Parameter 2 must contain a pointer to a 255 byte character array. The specified line will be placed into this buffer. (PSZ) OPTIONS_NAME Returns the name of the visible file. OPTIONS_HWNDEXTRA Returns the handle to the extra area window. (HWND) OPTIONS_HWNDEIOBJECT Returns the handle to the EI Work Thread. (PVOID) OPTIONS_TEXTCOLOR Returns the text Foreground (LOUSHORT) and Background (HIUSHORT). OPTIONS_RING Returns a buffer filled with the name of the files within the E-MLE ring. The buffer has the following format: USHORT - length of filenames UCHAR - delimitor ULONG - fileid CHAR[] - delimited string OPTIONS_FILEID Returns the File ID of the visible file. OPTIONS_QSELECTION Returns the type of selection. This message is send to a edit window to get a spec- ified option. All options are returned in the form ----------------------------------------------------------------------------- 68 Programmers Guide to the E Editor Toolkit. Version 2.0 of a 4 byte return code. Here is an example of using the Option message to get the total numbers of visible lines in a edit window. VisibleLines = (ULONG)WinSendMsg( hwndEditWindow, EPM_EDIT_OPTIONS, OPTIONS_NROWS, 0L ); ----------------------------------------------------------------------------- E Toolkit Messages 69 EPM_EDIT_ID ___________ ---------------------- QUERY EDITOR ID NUMBER Purpose Determine if a window handle is your E-MLE window. Message Parameter 1 NULL ____ not used Message Parameter 2 NULL ____ not used Remarks This message is used to determine if a window handle is a edit window handle. This message returns a 4byte return code. The way to determine if the specified handle is a edit window is by checking if the Hi-order word contains the value of EPM_EDIT_ID and the Lo-order word contains the value specified in the create structure field, 'editid'. If a match is found in the Hi-order word then the window handle is a edit window. If a match is found in both the Hi-order word and the Lo-order word, then the window handle is a edit window created by your application. An example follows: result = WinSendMsg( hwndE, EPM_EDIT_ID, 0L, 0L ); match = MPFROM2SHORT(epm.editid,EPM_EDIT_ID); if (result==match) { /* Edit window found */ } ----------------------------------------------------------------------------- 70 Programmers Guide to the E Editor Toolkit. Version 2.0 EPM_EDIT_SHOW _____________ ------------------------------------ (MAKE EDIT WINDOW VISIBLE/INVISIBLE) Purpose Refresh and Show/Hide the edit window speci- fied. Message Parameter 1 SHOW FLAG(Bool) _________ TRUE = Show and Refresh edit window FALSE = Hide edit window Message Parameter 2 NULL ____ not used Remarks When an edit window is created (using EtkCreate) the WS_VISIBLE flag is not used as a window style. Therefore, the edit window is not visible upon cre- ation. It is recommended that an EPM_EDIT_SHOW message be sent to the edit window to be displayed instead of WinShowWindow(...). The difference between sending the EPM_EDIT_SHOW verses the WinShowWindow is that the EPM_EDIT_SHOW forces a window repaint. ----------------------------------------------------------------------------- E Toolkit Messages 71 EPM_EDIT_NEWFILE ________________ ------------------------ (OPEN A NEW EDIT WINDOW) Purpose Open a new edit window with the specified file. Message Parameter 1 FILE NAME(PSZ) _________ Asciiz string pointer to any legal file name. (Wildcards are supported) Message Parameter 2 STRING FLAGS (MPARAM) _____________ Flags specifying how to handle the pointer in parameter one. The following are flags that can be set. o COMMAND_GETABLE - The pointer is a getable shared segment. Use DosGetSeg(SELECTOROF(mp1) ) to access the pointer. o COMMAND_FREESEL - The selector must be freed after it is used by the application. Use DosFreeSeg( FP_SEG(mp1) ) to free the selector. Returns void Remarks An edit window is requesting that another edit window be opened. This message should be handled by calling EtkCreate.: The macros used by the EPM editor use this message to implement the 'OPEN' command. The Flags in parameter two are checked by anding parameter two with the constants COMMAND_GETABLE and ----------------------------------------------------------------------------- 72 Programmers Guide to the E Editor Toolkit. Version 2.0 COMMAND_FREESEL. For example to check if the COMMAND_GETABLE flag is set do the folowing: if( LONGFROMMP(mp2) & COMMAND_FREESEL ) { /* the free selector flag is set */ } ----------------------------------------------------------------------------- E Toolkit Messages 73 EPM_EDIT_DESTROYNOTIFY ______________________ ------------------------- (A E-MLE HAS BEEN CLOSED) Purpose Notify owner that an E-MLE window has been closed. Message Parameter 1 EDIT HANDLE(HWND) ___________ Handle to the client window of the E-MLE window that was just closed. Message Parameter 2 MESSAGE QUEUE(HMQ) Handle to the message queue ______________ formally being used by the E-MLE window that was just closed. Returns void Remarks Sent to owner registered in the Editor Information structure. (See Appendix A for more details on the Edit Information structure.) This message gives the owner the ability to take some action when a edit window is closed. Note that the window handle passed is not valid. It is to be used for reference only. ----------------------------------------------------------------------------- 74 Programmers Guide to the E Editor Toolkit. Version 2.0 EPM_EXTRAWINDOW_REFRESH _______________________ ------------------------------ (REFRESH EXTRA WINDOW CONTROL) Purpose Repaint the optional editor extra window, updating all values. Message Parameter 1 NULL(MPARAM) ____ not used Message Parameter 2 NULL (MPARAM) _____ not used Returns VOID Remarks The Extra Window control can provide two extra lines of text, the status area and the message area.: To obtain the extra window handle, send a EPM_EDIT_OPTION message to the edit window in ques- tion. When sending the option message specify OPTION_HWNDEXTRA as message parameter one. ----------------------------------------------------------------------------- E Toolkit Messages 75 EPM_EDIT_CONTROLTOGGLE ______________________ --------------------------------------------------------- (TOGGLE OR QUERY THE STATUS OF A BASE EDIT WINDOW CONTROL) Purpose Toggle a editor control on/off or force the control on/off. Message Parameter 1 ID(LOUSHORT) __ Control identifier; See table below. RCE ON/OFF(HIUSHORT) __________ Set to 2=ON, or 1=OFF Message Parameter 2 QUERY FLAG (MPARAM) ___________ TRUE if control is to be Queried, otherwise FALSE. Returns void Remarks This message is send to an edit window to toggle (turn ON or OFF) some editor control window. The message can also be used to force a particular control on or off.: The lo-ordered short of the first message parameter contains an id number that determines the control window. The id constants are as follows: EDITSTATUSAREA Status area of extra window control. EDITMSGAREA Message area of extra window control EDITVSCROLL Vertical scroll bar EDITHSCROLL Horizontal scroll bar EDITTITLEBAR Stops automatic updating of title bar with filename. This is useful if the application requires the title bar to display text other then the current file being edited. EDITCURSOR Editor cursor ----------------------------------------------------------------------------- 76 Programmers Guide to the E Editor Toolkit. Version 2.0 The hi-ordered short of the first message parameter contains an optional value. If the value is null then the control is toggled. If it is non- zero the control status is set to one less the value. This value should be set to 2 if you want to force the control on, or one if you want to force the control off. Parameter contain the Query Flag. If parameter is non-zero the status of the specified control is returned. That is, TRUE is returned if the control is active or FALSE if it is not. ----------------------------------------------------------------------------- E Toolkit Messages 77 EPM_EDIT_RECORDKEY- ___________________ ---------------------------- (START RECORDING KEYSTROKES) Purpose Start the recording of keystrokes (WM_CHAR messages) sent to the edit window. Message Parameter 1 NULL (MPARAM) _____ not used Message Parameter 2 NULL (MPARAM) _____ not used Returns void Remarks ----------------------------------------------------------------------------- 78 Programmers Guide to the E Editor Toolkit. Version 2.0 EPM_EDIT_ENDRECORDKEY- ______________________ ------------------------- (STOP STORING KEYSTROKES) Purpose Terminates the storing of keystrokes (WM_CHAR messages) started by the EPM_EDIT_RECORDKEY message. Message Parameter 1 NULL (MPARAM) _____ not used Message Parameter 2 NULL (MPARAM) _____ not used Returns void Remarks ----------------------------------------------------------------------------- E Toolkit Messages 79 EPM_EDIT_PLAYKEY ________________ ---------------------------------------------- (EXECUTE STORED KEYSTROKES) - SENT TO AN E-MLE Purpose Generate keystrokes (WM_CHAR messages) saved since the EPM_EDIT_RECORDKEY message has been sent. Message Parameter 1 NULL (MPARAM) _____ not used Message Parameter 2 NULL (MPARAM) _____ not used Returns void Remarks It is recommend that a EPM_EDIT_ENDRECORDKEY message be sent before this message is sent. If the edit window is still in record mode when the message is sent an error message is sent to the owner window. ----------------------------------------------------------------------------- 80 Programmers Guide to the E Editor Toolkit. Version 2.0 EPM_EDIT_QUERYRECORDKEY _______________________ ---------------------------- (DETERMINE RECORD KEY STATE) Purpose Returns TRUE if edit window is recording keys. Message Parameter 1 NULL (MPARAM) _____ not used Message Parameter 2 NULL (MPARAM) _____ not used Returns TRUE = edit window is recording keys. Remarks ----------------------------------------------------------------------------- E Toolkit Messages 81 EPM_EDIT_ASKTOQUIT __________________ --------------------------------- (REQUEST TO QUIT A MODIFIED FILE) Purpose Notify application that a request has been sent to quit a file which has been modified. Message Parameter 1 FILENAME (PSZ) _________ Name of file that has been modified. Message Parameter 2 HEDITWND (HWND) _________ The edit window's handle. Remarks This message is sent after the E toolkit has received notice to quit a modified file. The appli- cation must respond to this message by sending an EPM_EDIT_ASKTODONE message. When an application receives this message it is a good time to pop a dialog to the user asking what action to take. (See the Quitbox dialog for an example ) Related Messages EPM_EDIT_ASKTOCLOSE EPM_EDIT_ASKTOFAILED EPM_EDIT_ASKTODONE ----------------------------------------------------------------------------- 82 Programmers Guide to the E Editor Toolkit. Version 2.0 EPM_EDIT_ASKTOCLOSE ___________________ --------------------------------- (REQUEST TO CLOSE AN EDIT WINDOW) Purpose Notify application that a request has be sent to close an edit window which contains a file that has been modified. Message Parameter 1 FILENAME (PSZ) _________ Name of file that has been modified. Message Parameter 2 HEDITWND (HWND) _________ The edit window's handle. Remarks This message is sent after the E toolkit has received notice to close an edit window which con- tains a modified file. The application must respond to this message by sending an EPM_EDIT_ASKKTODONE message. Related Messages EPM_EDIT_ASKTOQUIT EPM_EDIT_ASKTOFAILED EPM_EDIT_ASKTODONE ----------------------------------------------------------------------------- E Toolkit Messages 83 EPM_EDIT_ASKTODONE __________________ -------------------------------------- (RESPOND TO EPM_EDIT_ASKTOXXX MESSAGE) Purpose Respond to one of the EPM_EDIT_ASKTOxxx mes- sages from the E toolkit. Message Parameter 1 RETCODE (MPFROMSHORT) ________ Response message sent to E toolkit. One of the fol- lowing messages can be used: o ERES_CANCEL - Cancel the closing of the file or edit window. o ERES_DISCARD - Discard the modifications and continue closing. o ERES_SAVE - Save file as message parameter two and continue closing. Message Parameter 2 FILENAME (PSZ) Name of file to save modifications in _________ if EPM_SAVE is sent. This pointer must be the same pointer sent to the applications with one of the EPM_EDIT_ASKTOxxx messages. Remarks This message allows the application control the saving or discarding of a modified file when an edit window is closing, a quit file message has been sent, or when a previous EPM_EDIT_ASKTODONE message returned EPM_EDIT_ASKTOFAILED. Related Messages EPM_EDIT_ASKTQUIT EPM_EDIT_ASKTOCLOSE EPM_EDIT_ASKTODONE ----------------------------------------------------------------------------- 84 Programmers Guide to the E Editor Toolkit. Version 2.0 EPM_EDIT_ASKTOFAILED ____________________ -------------------------------- (LAST EPM_EDIT_ASKTODONE FAILED) Purpose Notify application that the file name sent with the last EPM_EDIT_ASKTODONE message could not be saved with the name specified. Message Parameter 1 FILENAME (filename) _________ File name used which caused an error in saving. Message Parameter 2 HEDITWND (HWND) _________ The edit window's handle. Remarks This message informs the application that the file name sent with the EPM_EDIT_ASKTODONE message and message parameter EPM_SAVE, was a bad file name. The application should correct the file name and send another EPM_EDIT_ASKTODONE message. Related Messages EPM_EDIT_ASKTQUIT EPM_EDIT_ASKTOCLOSE EPM_EDIT_ASKTOFAILED ----------------------------------------------------------------------------- E Toolkit Messages 85 ----------------------------------------------------------------------------- 86 Programmers Guide to the E Editor Toolkit. Version 2.0 ERES.DLL ________ ERES.DLL exports a set a general purpose functions that can be used by an application that contains E-MLE's. These functions are detailed in this section. IN ORDER TO USE THESE FUNCTIONS AN APPLI- __________________________________________ CATION MUST DO THE FOLLOWING IN THE ORDER GIVEN: _________________________________________________ 1) Include ETOOLKT.H in all source files that use ERES.DLL functions. The main source file of the application should define the constant INCL_DONT_EXT_GLOB before including etoolkt.h. For example: #define INCL_DONT_EXT_GLOB #include 2) Declare a variable of type GLOBDATA in the main source file of the application. 3) Load the ERES.DLL module and initialize the "eresModule" field of the GLOBDATA variable with the ERES.DLL module handle. // Note that GlobData is a variable of type GLOBDATA DosLoadModule((PSZ)NULL,(USHORT)0,(PSZ)"ERES", (PHMODULE)&GlobData.eresModule ); 4) The following three function calls must be called next. ERESRegisterEtkFunctions((PFN) EtkCreate, CREATE_FUNC); ERESRegisterEtkFunctions((PFN) EtkDestroy, DESTROY_FUNC); ERESRegisterEtkFunctions((PFN) EtkVersion, VERSION_FUNC); (See ERESRegisterEtkFunctions in the section "ERES.DLL Exported Functions" for an explanation of these function calls) 5) Call the function ERESInitEresGlob() in order to initialize the internal data of ERES.DLL. 6) Required fields of the variable of type GLOBDATA must be initialized. These are: ----------------------------------------------------------------------------- ERES.DLL 87 o eres.exfilename - name of the applications EX file. o ApplicationName - name of the application. o ExSearchPath - search path for EX files. Set to NULL if search path includes only the current directory. o ApplicationID - a unique ID that distin- guishes the edit windows of the application. ERES.DLL - EXPORTED FUNCTIONS _____________________________ The following functions are exported from ERES.DLL .--------------------------------------------------------------------------. | Dynalink functions found in ERES.DLL | |--------------------------------------------------------------------------| | | | ERESRegisterEtkFunctions - Register pointer to E.DLL functions | | ERESCommonWndProc - Common window procedure | | EresSaveLists - Saves internal list data to ini file | | ERESRetrieveLists - Retrieves internal list data from ini file | | ERESOpenEditWindow - Opens a new edit window | | ERESCountEWindows - Counts the number of edit windows | | ERESPopDlgBox - Pop Dialog box | | ERESIsAnEditWin - Is an edit window | | ERESEwindowValid - Edit window valid | | ERESSendOpenMsgToApp - Send open message to application | | ERESShutDown - Shut down all edit windows | | ERESInitEResStruct - Initialize the ERES structure | | ERESCheckVersion - Check the E.DLL version | | ERESProcessCommands - Process command messages. | | ERESEditWindowlist - Show listing of available edit windows. | | | .--------------------------------------------------------------------------. ----------------------------------------------------------------------------- 88 Programmers Guide to the E Editor Toolkit. Version 2.0 ERESREGISTERETKFUNCTIONS - __________________________ (REGISTERS POINTERS TO E.DLL FUNCTIONS) _______________________________________ ----------------------------------------------------------------------------- Allows ERES.DLL to call E.DLL functions without having to import them. +-------------------------------------------------------+ | ERESREGISTERETKFUNCTIONS (, ) | +-------------------------------------------------------+ PARAMETERS FUNCPTR (PFN) - input _____ Pointer to E.DLL function. One of the following can be used: o EtkCreate o EtkDestroy o EtkVersion ID (USHORT) - input ________ Function identifier. One of the following can be used: o CREATE_FUNC - EditWindowCreate o DESTROY_FUNC - EditWindowDestroy o VERSION_FUNC - EditVersion RETURNS Void REMARKS Currently an application must send the pointers of E.DLL functions required by ERES.DLL in order to avoid reloading of the E.DLL module. Due to an a debug in the operating system if two modules in the same application import the same module, that module is reloaded. Therefore, this function avoids the costly reloading of the E.DLL module. Util this problem is resolved the following code must be placed after an application loades eres.dll: EXAMPLE ERESRegisterEtkFunctions((PFN) EtkCreate, CREATE_FUNC); ERESRegisterEtkFunctions((PFN) EtkDestroy, DESTROY_FUNC); ERESRegisterEtkFunctions((PFN) EtkVersion, VERSION_FUNC); ----------------------------------------------------------------------------- ERES.DLL 89 ERESCOMMONWNDPROC _________________ ------------------------- (COMMON WINDOW PROCEDURE) Purpose Handles default window message processing of E toolkit applications. Prototype: ERESCOMMONWNDPROC ____________________ Parameters HWND (HWND) _____ The window handle of the application. MSG (HWND) ____ The window message. MP1 (MPARAM) ____ Message parameter one. MP2 (MPARAM) ____ Message parameter two. Returns VOID Remarks Applications that choose to call this function as their default window procedure will have the default message processing for E toolkit messages. (See Appendix H for a description of these messages) The Window ULONG of the applications window handle must be set to the address of the GLOBDATA structure in order to process application specific information. ----------------------------------------------------------------------------- 90 Programmers Guide to the E Editor Toolkit. Version 2.0 ERESSAVELISTS _____________ -------------------------------------- (SAVES INTERNAL LIST DATA TO INI FILE) Purpose Saves the internal data structures of the Open File, List Box, and Command Dialog boxes in the ini file specified in the GLOBDATA structure. Prototype: ERESSAVELISTS ________________ Parameters GLOBDATA (GLOBDATA *) _________ Pointer to application instance data. Returns Void Remarks GlobData->IniApplicationName contains the name of the ini file to store the structures in. GlobData->eres contains the structures cmd, msg, and open1 which are the structures used by the three dialog boxes. ----------------------------------------------------------------------------- ERES.DLL 91 ERESRETRIEVELISTS _________________ -------------------------------------------- (RETRIEVES INTERNAL LIST DATA FROM INI FILE) Purpose Retrieves the internal data structures of the Open File, List Box, and Command Dialog boxes from the ini file specified in the GLOBDATA struc- ture. Prototype: ERESRETRIEVELISTS ____________________ Parameters GLOBDATA (GLOBDATA *) _________ Pointer to application instance data. Returns VOID Remarks GlobData->IniApplicationName contains the name of the ini file to retrieve the structures from. GlobData->eres contains the structures cmd, msg, and open1 which are the structures used by the three dialog boxes. These will be filled with the data in the specified ini file. ----------------------------------------------------------------------------- 92 Programmers Guide to the E Editor Toolkit. Version 2.0 ERESOPENEDITWINDOW __________________ ------------------------- (OPENS A NEW EDIT WINDOW) Purpose Initializes the EDITORINFO structure with application specific data and calls the EPM_CreateEditWindow function of E.DLL . Prototype: ERESOPENEDITWINDOW _____________________ Parameters FILENAME (char far *) _________ Pointer to the string containing the file to edit. GLOBDATA (GLOBDATA *) _________ Application instance data. Returns HWNDEDIT (HWND) The window handle of the new _________ edit window. Remarks ----------------------------------------------------------------------------- ERES.DLL 93 ERESCOUNTEWINDOWS _________________ ------------------------------------------------ (COUNTS THE NUMBER OF E-MULTI-LINE EDIT WINDOWS) Purpose Determines the number of available edit windows. Prototype: ERESCOUNTEWINDOWS ____________________ Parameters GLOBDATA (GLOBDATA *) Pointer to application __________ instance data. Returns COUNT (USHORT) The total number of E-Multi- ______ line edit windows that belong to an application. Remarks GlobData->CountOnlyVisibleWindows determines whether to count only visible windows. Some applications might create edit windows, keep them hidden, and use them at some later time. ----------------------------------------------------------------------------- 94 Programmers Guide to the E Editor Toolkit. Version 2.0 ERESPOPDLGBOX _____________ ---------------- (POP DIALOG BOX) Purpose Display the specified dialog box. If the dialog is already being displayed bring it to the top. Prototype: ERESPOPDLGBOX( _________________ Parameters PROC (PFNWP) Pointer to the window procedure of the ______ dialog. DLGIN (USHORT) Pointer to dialog input information. ______ MODULETYPE (PSZ) Specifies the module that contains ___________ the dialogs resource information excluding the ".DLL" extension. If set to NULL then the dialog resource is contained in ERES.DLL. OWNERTYPE (USHORT) The owner of the dialog. This can __________ be set to one of four values: o OT_DEFAULT - Checks the value of the active edit window. If it is valid make it the owner, else make the handle to the applications frame the owner. o OT_ACTIVE_EDIT - Make the active edit window the owner. o OT_APP_FRAME - Make the applications frame the owner. o OT_DESKTOP - Make the desktop window the owner. GLOBDATA (GLOBDATA *) Application instance data. _________ Returns VOID ----------------------------------------------------------------------------- ERES.DLL 95 Remarks ----------------------------------------------------------------------------- 96 Programmers Guide to the E Editor Toolkit. Version 2.0 ERESISANEDITWIN _______________ ------------------- (IS AN EDIT WINDOW) Purpose Test if a given window is an edit window. Prototype: ERESISANEDITWIN __________________ Parameters HWND (HWND) Window handle of the window to test. ______ GLOBDATA (GLOBDATA *) Pointer to application ___________ instance data. Returns RC(BOOL) __ o TRUE - The window is an edit window. o FLASE - The window is not an edit window. Remarks ----------------------------------------------------------------------------- ERES.DLL 97 ERESEWINDOWVALID ________________ ------------------------- (IS AN EDIT WINDOW VALID) Purpose Tests whether the active edit window of the application instance data is valid. Prototype: ERESEWINDOWVALID ___________________ Parameters GLOBDATA (GLOBDATA *) Pointer to application __________ instance data. Returns RC(BOOL) __ o TRUE - The the active edit window handle is valid. o FLASE - The the active edit window handle is not valid. Remarks ----------------------------------------------------------------------------- 98 Programmers Guide to the E Editor Toolkit. Version 2.0 ERESSENDOPENMSGTOAPP ____________________ ---------------------------------- (SEND OPEN MESSAGE TO APPLICATION) Purpose Finds the handle of applications client window, and posts it a message to open the files in the shared message buffer of the application instance data. Prototype: ERESSENDOPENMSGTOAPP _______________________ Parameters ID (USHORT) Message response to sending the ____ EPM_BOOK_ID message to the applications window. Returns VOID Remarks This function traverses through all existing frame windows searching for the applications window. The Custom message EPM_BOOK_ID is used to test whether a windows is that of the application. If a window responds to an EPM_BOOK_ID message with ID then it is the applications window. GlobData->ShrMsgBuff contains the name of the file to open. ----------------------------------------------------------------------------- ERES.DLL 99 ERESSHUTDOWN ____________ ----------- (SHUT DOWN) Purpose Systematically closes all E-MLE's associated with an application. Prototype: ERESSHUTDOWN _______________ Parameters GLOBDATA (GLOBDATA *) Pointer to application ___________ instance data. Returns RC(BOOL) __ o TRUE - A given file in an edit window does not wish to close down because it has yet to be saved. o FLASE - Shut down of all edit windows completed. Remarks ----------------------------------------------------------------------------- 100 Programmers Guide to the E Editor Toolkit. Version 2.0 ERESINITERESSTRUCT __________________ ------------------------------- (INITIALIZE THE ERES STRUCTURE) Purpose Initializes the eres field of the GlobData structure. Prototype: ERESINITERESSTRUCT _____________________ Parameters HWND (HWND) The window handle of the applications _____ client window. GLOBDATA (GLOBDATA *) Pointer to applications ___________ instance data. Returns VOID Remarks The pointer to this structure is copied and used internally in ERES.DLL. ----------------------------------------------------------------------------- ERES.DLL 101 ERESCHECKVERSION ________________ ------------------------ (CHECK ERES.DLL VERSION) Purpose Compare the ERES.DLL's version number with that of E.DLL . Prototype: ERESCHECKVERSION ___________________ Parameters No Parameters Returns RC (BOOL) ___ o TRUE - The Version numbers are the same. o FLASE - Version conflict exits. ----------------------------------------------------------------------------- 102 Programmers Guide to the E Editor Toolkit. Version 2.0 ERESPROCESSCOMMANDS ___________________ -------------------------- (PROCESS COMMAND MESSAGES) Purpose Process WM_COMMAND messages sent to the applications default window procedure. Prototype: ERESPROCESSCOMMANDS ______________________ Parameters MP1 (MPARAM) WM_COMMAND message parameter. ____ MP2 (MPARAM) Pointer to dialog input information. ____ GLOBDATA (GLOBDATA *) Pointer to application __________ instance data. Returns VOID Remarks This functions is used when ERESCommonWndProc() is the default window procedure of the application. ----------------------------------------------------------------------------- ERES.DLL 103 ERESEDITWINDOWLIST __________________ ---------------------------------------- (SHOW LISTING OF AVAILABLE EDIT WINDOWS) Purpose Create a Popup menu that contains the names of the available edit windows which the user can transfer control to. Prototype: ERESEDITWINDOWLIST _____________________ Parameters GLOBDATA (GLOBDATA *) Pointer to application ___________ instance data. Returns VOID Remarks GlobData->EditWindowListStyle controls the posi- tioning of the edit list window dialog relative to the applications client window. (See Appendix F for the available options) ----------------------------------------------------------------------------- 104 Programmers Guide to the E Editor Toolkit. Version 2.0 ERES.DLL - EXPORTED DIALOG BOX PROCEDURES _________________________________________ The following dialog box procedures are exported by ERES.DLL. In order to use any of these dialogs an application must adhere to the required code out- lined in the previous section. o ERESOPENDLGPROC Open dialog procedure. Full file _______________ selection dialog box includes fields specifying drives, directories, files, path name, and a file name entry field. o ERESOPEN1DLGPROC Open dialog procedure. Contains ________________ a list of previously entered file names, and an entry field. o ERESCOMMANDDLGPROC Edit window command dialog __________________ box. o FINDCHANGEDLGPROC Allows find/change commands to _________________ be enter from dialog box. o CONFIGDLGPROC Configuration edit window dialog _____________ procedure. o ENTRYBOXDLGPROC General purpose entry dialog _______________ box. o LISTBOXDLGPROC List box dialog. ______________ o QUITBOXDLGPROC ______________ Quit box dialog. ----------------------------------------------------------------------------- ERES.DLL - Exported Dialog Box Procedures 105 ERESOPEN1DLGPROC ________________ --------------------------- (OPEN DIALOG PROCEDURE ONE) Purpose Open1 dialog box procedure. Prototype: ERESOPEN1DLGPROC ___________________ Parameters HWND (HWND) _____ The handle to the dialog box. MESSAGE (USHORT) ________ Window message. LPARM1 (MPARAM) _______ Message parameter one. LPARM2 (MPARAM) _______ Message parameter two. Returns VOID Remarks This dialog contains a list of previously entered file names, and an entry field. This dialog can be called using the WinDlgBox() function. For example: WinDlgBox(Parent, Owner, DlgProc, Resource, Dlgid, CreatParam); o Parent - Window handle of the parent of the dialog o Owner - Window handle of the owner of the dialog o DlgProc - Window procedure of the dialog (ERESOpen1DlgProc) o Resource - Where the dialog resource is located (ERES) o Dlgid - Dialog id (DLG_OPEN1) o CreateParam - Dialog creation parameter. Must be set to(&GlobData->eres). ----------------------------------------------------------------------------- 106 Programmers Guide to the E Editor Toolkit. Version 2.0 ----------------------------------------------------------------------------- ERES.DLL - Exported Dialog Box Procedures 107 ERESCOMMANDDLGPROC __________________ -------------------------- (COMMAND DIALOG PROCEDURE) Purpose Edit window command line dialog procedure. Prototype: ERESCOMMANDDLGPROC _____________________ Parameters HWND (HWND) _____ The handle to the dialog box. MESSAGE (USHORT) ________ Window message. LPARM1 (MPARAM) _______ Message parameter one. LPARM2 (MPARAM) _______ Message parameter two. Returns VOID Remarks This is an edit window command line dialog box, which includes an entry field and a scrollable list of previous commands. This dialog can be called using the WinDlgBox() function. For example: WinDlgBox(Parent, Owner, DlgProc, Resource, Dlgid, CreatParam); o Parent - Window handle of the parent of the dialog o Owner - Window handle of the owner of the dialog o DlgProc - Window procedure of the dialog (ERESCommandDlgProc) o Resource - Where the dialog resource is located (ERES) o Dlgid - Dialog id (IDM_COMMANDS) ----------------------------------------------------------------------------- 108 Programmers Guide to the E Editor Toolkit. Version 2.0 o CreateParam - Dialog creation parameter. Must be set to(&GlobData->eres). ----------------------------------------------------------------------------- ERES.DLL - Exported Dialog Box Procedures 109 ERESFINDCHANGEDLGPROC _____________________ ------------------------------ (FIND/CHANGE DIALOG PROCEDURE) Purpose Find/Change commands dialog procedure. Prototype: ERESFINDCHANGEDLGPROC ________________________ Parameters HWND (HWND) _____ The handle to the dialog box. MESSAGE (USHORT) ________ Window message. LPARM1 (MPARAM) _______ Message parameter one. LPARM2 (MPARAM) _______ Message parameter two. Returns VOID Remarks This dialog allows find/change commands to be entered directly from it. This dialog can be called using the WinDlgBox() function. For example: WinDlgBox(Parent, Owner, DlgProc, Resource, Dlgid, CreatParam); o Parent - Window handle of the parent of the dialog o Owner - Window handle of the owner of the dialog o DlgProc - Window procedure of the dialog (ERESFindChangeDlgProc) o Resource - Where the dialog resource is located (ERES) o Dlgid - Dialog id (DLG_CHANGE). o CreateParam - Dialog creation parameter. Must be set to(&GlobData->eres). ----------------------------------------------------------------------------- 110 Programmers Guide to the E Editor Toolkit. Version 2.0 ERESCONFIGDLGPROC _________________ ------------------------------- (CONFIGUATION DIALOG PROCEDURE) Purpose Allow edit window options to be configured from dialog box. Prototype: ERESCONFIGDLGPROC ____________________ Parameters HWND (HWND) _____ The handle to the dialog box. MESSAGE (USHORT) ________ Window message. LPARM1 (MPARAM) _______ Message parameter one. LPARM2 (MPARAM) _______ Message parameter two. Returns VOID Remarks This dialog allows configuration of edit window options. These options include setting margins, autosave level, tabs, colors, and paths. This dialog can be called using the WinDlgBox() function. For example: WinDlgBox(Parent, Owner, DlgProc, Resource, Dlgid, CreatParam); o Parent - Window handle of the parent of the dialog o Owner - Window handle of the owner of the dialog o DlgProc - Window procedure of the dialog (ERESConfigDlgProc) o Resource - Where the dialog resource is located (ERES) ----------------------------------------------------------------------------- ERES.DLL - Exported Dialog Box Procedures 111 o Dlgid - Dialog id (DLG_CONFIG) o CreateParam - Dialog creation parameter. Must be set to(&GlobData->eres). ----------------------------------------------------------------------------- 112 Programmers Guide to the E Editor Toolkit. Version 2.0 ENTRYBOXDLGPROC _______________ ---------------------------- (ENTRY DIALOG BOX PROCEDURE) Purpose General purpose entry dialog box. Prototype: ENTRYBOXDLGPROC __________________ Parameters HWND (HWND) _____ The handle to the dialog box. MESSAGE (USHORT) ________ Window message. LPARM1 (MPARAM) _______ Message parameter one. LPARM2 (MPARAM) _______ Message parameter two. Returns VOID Remarks This dialog can be called using the WinDlgBox() function. For example: WinDlgBox(Parent, Owner, DlgProc, Resource, Dlgid, CreatParam); o Parent - Window handle of the parent of the dialog o Owner - Window handle of the owner of the dialog o DlgProc - Window procedure of the dialog (EntryBoxDlgProc) o Resource - Where the dialog resource is located (ERES) o Dlgid - Dialog id (IDD_ENTRYBOX) o CreateParam - Dialog creation parameter. Must be set to(PENTRYBOXINFO). ----------------------------------------------------------------------------- ERES.DLL - Exported Dialog Box Procedures 113 Check eres.h for a desription of the structure ENTRYBOXINFO. A pointer to this structure must be allocated and passed into the dialog procedure via this parameter. ----------------------------------------------------------------------------- 114 Programmers Guide to the E Editor Toolkit. Version 2.0 LISTBOXDLGPROC ______________ --------------------------- (LIST BOX DIALOG PROCEDURE) Purpose General purpose list dialog procedure. Prototype: LISTBOXDLGPROC _________________ Parameters HWND (HWND) _____ The handle to the dialog box. MESSAGE (USHORT) ________ Window message. LPARM1 (MPARAM) _______ Message parameter one. LPARM2 (MPARAM) _______ Message parameter two. Returns VOID Remarks This dialog can be called using the WinDlgBox() function. For example: WinDlgBox(Parent, Owner, DlgProc, Resource, Dlgid, CreatParam); o Parent - Window handle of the parent of the dialog o Owner - Window handle of the owner of the dialog o DlgProc - Window procedure of the dialog (ListBoxDlgProc) o Resource - Where the dialog resource is located (ERES) o Dlgid - Dialog id (ID_LISTBOX) o CreateParam - Dialog creation parameter. Must be set to(PLISTBOXINFO). ----------------------------------------------------------------------------- ERES.DLL - Exported Dialog Box Procedures 115 Check eres.h for a description of the LISTBOXINFO structure. A pointer to this structure must be allocated and passed into the dialog procedure via this parameter. ----------------------------------------------------------------------------- 116 Programmers Guide to the E Editor Toolkit. Version 2.0 QUITBOXDLGPROC ______________ --------------------------- (QUIT BOX DIALOG PROCEDURE) Purpose Sample Quit box dialog which handles EPM_EDIT_ASKTOxxx messages. Prototype: QUITBOXDLGPROC _________________ Parameters HWND (HWND) _____ The handle to the dialog box. MESSAGE (USHORT) ________ Window message. LPARM1 (MPARAM) _______ Message parameter one. LPARM2 (MPARAM) _______ Message parameter two. Returns VOID Remarks This dialog informs the user that a file has been modified. It includes an entry field to specify what name the modifications should be saved as, and the pushbuttons: Save , Discard, Cancel, and Help. This dialog can be called using the WinDlgBox() function. For example: WinDlgBox(Parent, Owner, DlgProc, Resource, Dlgid, CreatParam); o Parent - Window handle of the parent of the dialog o Owner - Window handle of the owner of the dialog o DlgProc - Window procedure of the dialog (QuitBoxDlgProc) ----------------------------------------------------------------------------- ERES.DLL - Exported Dialog Box Procedures 117 o Resource - Where the dialog resource is located (ERES) o Dlgid - Dialog id (IDD_QUITBOX) o CreateParam - Dialog creation parameter. Must be set to(PQUITBOXINFO). See eres.h for a description of the QUITBOXINFO structure. A pointer to this structure must be allocated and passed into the dialog via this parameter. Returns This dialog returns one of the following codes. o ERES_SAVE - Save was selected. File name is stored in QUITBOXINFO->filename o ERES_CANCEL - Cancel was selected. o ERES_DISCARD - Discard was selected. ----------------------------------------------------------------------------- 118 Programmers Guide to the E Editor Toolkit. Version 2.0 ----------------------------------------------------------------------------- ERES.DLL - Exported Dialog Box Procedures 119 ----------------------------------------------------------------------------- 120 Programmers Guide to the E Editor Toolkit. Version 2.0 EXAMPLE E TOOLKIT APPLICATION _____________________________ The following sample source code demonstrates how an application can use various features of the E Toolkit. The source files included are: o Edllsamp.c - creates a sample edit window using E.DLL o edllsamp.e - macros defining the edit windows profile o eressamp.c - dialog resource management func- tions o sampdlg.c - sample dll which demonstrates two types of PM dialogs. o sampdlg.e - macros demonstrating how to invoke the sampdlg.c dialogs. ----------------------------------------------------------------------------- Example E Toolkit Application 121 ----------------------------------------------------------------------------- 122 Programmers Guide to the E Editor Toolkit. Version 2.0 APPENDIX ________ APPENDIX A - ____________ --------------------------------------------------------- DESCRIPTION OF THE EDITOR INFORMATION STRUCTURE. (EDITORINFO) ___________________________ .------------------------------------------------------------------------. | Editor Information Structure defined in 'C' | |------------------------------------------------------------------------| | typedef struct EDIT_INFO_TYPE { | | HAB hab; /* application anchor block */| | HWND hwndparent; /* handle to parent of edit window */| | HWND hwndowner; /* handle to owner of edit window */| | PRECTL rect; /* positioning of edit window */| | PSZ filename; /* file to be edited (with wildcard) */| | HPOINTER hEditPtr; /* handle to editor pointer icon. */| | HPOINTER hMarkPtr; /* handle to mark pointer icon. */| | VOID FAR *hEditorIcon; /* editor ICON. */| | ULONG editorstyle; /* internal editor options */| | ULONG pmstyle; /* PM standard window styles (FCF_xxxx) */| | USHORT font; /* TRUE = LARGE FONT, FALSE = SMALL FONT*/| | PSZ exfile; /* pre-compiled macro code file (xxx.EX) */| | PSZ *topmkr; /* top and bottom of file marker */| | PSZ *botmkr; /* */| | SHORT editid; /* unique window id specified for window | | PSZ exsearchpath; /* environment varible-search for .ex files| | SHORT reserved0; /* for future use. */| | } EDITORINFO; | | | `------------------------------------------------------------------------' hab Application Anchor Block. To obtain the appli- cations anchor block use the WinInitialize function. (example: hab = WinInitialize(NULL); ) ----------------------------------------------------------------------------- Appendix 123 hwndparent Window handle of the edit window parent. Effects the positioning of the edit window. In EPM, for example, the parent to the edit window is the desk top window (HWND_DESKTOP). This is why the edit windows created by EPM are free to roam the entire desk top. hwndowner Window handle of the edit window owner. Determines which window receives messages from the edit window. For example, if a command is send to the edit window (via the EPM_EDIT_COMMAND message), and the command generates some type of return code. The return code is put into message form (via the EPM_EDIT_RETCODE message), and passed to the edit window owner. rect Pointer to a PM rectangle structure. Deter- mines the positioning of the edit window. The '.xLeft' and '.yBottom' fields set the lower lefthand corner of the edit window. The '.xRight' and '.yTop' fields set the width and height of the edit window. Since this is a pointer to a rec- tangle structure, pass the address of a RECTL in the following manner: epm.rect = ▭ filename Pointer to a Asciiz string that contains a fully qualified path. If 'filename' is NULL then a blank file will be edited. The blank file will be named '.Unnamed file'. 'filename' can contain wildcards. For example, if '*.dat' were specified, all the files with the extension '.dat' will be placed in the newly created edit window. hEditPtr Handle to a pointer icon that will become active when the mouse pointer is over the client area of the edit window. Use WinQueryPointer(HWND_DESKTOP); to use current mouse pointer. hMarkPtr Handle to a pointer that will be displayed when editor is marking text. ----------------------------------------------------------------------------- 124 Programmers Guide to the E Editor Toolkit. Version 2.0 hEditIcon Handle to a icon that will be displayed when the edit window is minimized. editorstyle Internal Editor style flags. Logical 'OR' these flags together to form desired editor configuration. o EDIT_STYLE_BROWSE - browse file (view file only) o EDIT_STYLE_ACTIVEFOCUS - when edit window becomes active it will take focus. o EDIT_STYLE_STATUSLINE - Create edit window with status line o EDIT_STYLE_MESSAGELINE - Create edut window with message line pmstyle Standard PM window FCF_xxx styles. For example, if you want to create a edit window with a Title Bar, Vertical Scroll Bar, and Size Border, you would use the following flags: FCF_TITLEBAR | FCF_SIZEBORDER | FCF_VERTSCROLL nt Flag that specifies the size font to use in the edit window. If font is TRUE, the largest possible system AVIO font will be used. If font is FALSE, the smallest possible system AVIO font will be used. exfile Pointer to a asciiz string containing the name of a .EX file. A .EX file contains compiled macro code. The file must be created using ETPM.EXE. If this parameter is NULL, "EPM.EX" is used. topmkr Pointer to a asciiz string containing the text that will be used to denote the top of file. ----------------------------------------------------------------------------- Appendix 125 botmkr Pointer to a asciiz string containing the text that will be used to denote the bottom of file. editid A unique editor id number that is used to identify edit windows created by a particular appli- cation. exsearchpath A pointer to a string that contains the name of an environment variable. The internal toolkit will use the paths associated with this environment variable to search for .ex files speci- fied during the life of an edit window. If this field is NULL, EPMPATH is searched by default. reserved0 Reserved for future enhancements. ----------------------------------------------------------------------------- 126 Programmers Guide to the E Editor Toolkit. Version 2.0 APPENDIX A1 - _____________ --------------- FIELD CONSTANTS Used by EtkSetFileField(...), EtkQueryFileField, and EtkQueryFileFieldString. ATTRIBUTE_SUPPORT_LEVEL - 0 = No Attributes supported AUTOSAVE_FIELD - File Modifies Before Autosaving CODEPAGE_FIELD - Code page COL_FIELD - Column of Cursor. CURSORX_FIELD - X Cursor Position in pels. CURSORYG_FIELD - CURSORY_FIELD - Y Cursor Position in pels. CURSOR_COLUMN - column of the cursor CURSOR_OFFSET - DRAGCOLOR_FIELD - drag shadow DRAGSTYLE_FIELD - drag type (linbe, block, character) EA_AREA_FIELD - pointer to extended attribute area FILENAME_FIELD - file name FONTHEIGHT_FIELD - average font width FONTWIDTH_FIELD - average font height FONT_FIELD - internal font identifier string KEYSET_FIELD - Key set name LAST_FIELD - Number of last line in file. (absolute position) LINEG_FIELD - LINE_FIELD - Number of line where cursor is located. (absolute position) LOCKHANDLE_FIELD - TRUE = File is locked MARGINS_FIELD - Margin String. ( Left Right Paragraph ) MARKCOLOR_FIELD - Color of selected text MODIFY_FIELD - number of file modifications MOUSEX_FIELD - x position of mouse MOUSEY_FIELD - y position of mouse READONLY_FIELD - TRUE = BROWSE MODE SCROLLX_FIELD - x scroll increment SCROLLY_FIELD - y scroll increment TABS_FIELD - Tab rack. TEXTCOLOR_FIELD - forground and background text color TITLETEXT_FIELD - text to be placed on title bar USERSTRING_FIELD - string to be used by user VISIBLE_FIELD - file visible flag (FALSE=NOT in ring) WINDOWHEIGHTG_FIELD - WINDOWHEIGHT_FIELD - height of window in pels WINDOWWIDTHG_FIELD - WINDOWWIDTH_FIELD - width of window in pels WINDOWX_FIELD - starting x position of window WINDOWY_FIELD - starting x position of window ----------------------------------------------------------------------------- Appendix 127 APPENDIX B - ____________ ---------------- EDITOR COMMANDS. See EPM Users guide for a list of editor Command. (EPM SCRIPT) ----------------------------------------------------------------------------- 128 Programmers Guide to the E Editor Toolkit. Version 2.0 APPENDIX C - ____________ ------------------- EDITOR RETURN CODES ----------------------------------------------------------------------------- Appendix 129 .----------------------------------------------------------. | Descriptor Constant | Return Code Value | |----------------------------------------------------------| | SEE_MESSAGE | 0 | |----------------------------------------------------------| | FILE_NOT_FOUND_RC | -2 | |----------------------------------------------------------| | PATH_NOT_FOUND_RC | -3 | |----------------------------------------------------------| | TOO_MANY_OPEN_FILES_RC | -4 | |----------------------------------------------------------| | ACCESS_DENIED_RC | -5 | |----------------------------------------------------------| | MEMORY_CONTROL_BLOCKS_RC | -7 | |----------------------------------------------------------| | INSUFFICIENT_MEMORY_RC | -8 | |----------------------------------------------------------| | INVALID_DRIVE_RC | -15 | |----------------------------------------------------------| | NO_MORE_FILES_RC | -18 | |----------------------------------------------------------| | NUMERIC_OVERFLOW_RC | -254 | |----------------------------------------------------------| | INVALID_NUMBER_ARGUMENT_RC | -255 | |----------------------------------------------------------| | RECURSION_TOO_DEEP_RC | -256 | |----------------------------------------------------------| | INVALID_NUMBER_OF_PARAMETERS_RC | -257 | |----------------------------------------------------------| | OUT_OF_STRING_SPACE_RC | -258 | |----------------------------------------------------------| | EXPRESSION_STACK_OVERFLOW_RC | -259 | |----------------------------------------------------------| | INVALID_FILEID_RC | -260 | |----------------------------------------------------------| | ILLEGAL_OPCODE_RC | -261 | |----------------------------------------------------------| | TOO_MANY_WINDOWS_RC | -262 | |----------------------------------------------------------| | INVALID_ARGUMENT_RC | -263 | |----------------------------------------------------------| | LOOP_STACK_OVERFLOW_RC | -264 | |----------------------------------------------------------| | DIVIDE_BY_ZERO_RC | -265 | |----------------------------------------------------------| | UNABLE_TO_SHRINK_RC | -266 | |----------------------------------------------------------| | INVALID_CALL_BY_REFERENCE_RC | -267 | |----------------------------------------------------------| | PROCEDURE_NEEDS_MORE_ARGUMENTS_ | -268 | |----------------------------------------------------------| | BREAK_KEY_PRESSED_RC | -269 | |----------------------------------------------------------| | NOT_ENOUGH_MEMORY_RC | -270 | ----------------------------------------------------------------------------- 130 Programmers Guide to the E Editor Toolkit. Version 2.0 +.---------------------------------------------------------+ ----------------------------------------------------------------------------- Appendix 131 +----------------------------------------------------------+ | ERROR_IN_MARGIN_SETTINGS_RC | -271 | |----------------------------------------------------------| | ERROR_IN_TAB_SETTINGS_RC | -272 | |----------------------------------------------------------| | STRING_NOT_FOUND_RC | -273 | |----------------------------------------------------------| | UNKNOWN_COMMAND_RC | -274 | |----------------------------------------------------------| | MISSING_FILENAME_RC | -275 | |----------------------------------------------------------| | LINE_TOO_LONG_TO_JOIN_RC | -276 | |----------------------------------------------------------| | TOO_MANY_FILES_RC | -277 | |----------------------------------------------------------| | LINES_TRUNCATED_RC | -278 | |----------------------------------------------------------| | TEXT_ALREADY_MARKED_RC | -279 | |----------------------------------------------------------| | TEXT_NOT_MARKED_RC | -280 | |----------------------------------------------------------| | SOURCE_DEST_CONFLICT_RC | -281 | |----------------------------------------------------------| | NEW_FILE_RC | -282 | |----------------------------------------------------------| | LINE_MARK_REQUIRED_RC | -283 | |----------------------------------------------------------| | ERROR_OPENING_FILE_RC | -284 | |----------------------------------------------------------| | ERROR_WRITING_FILE_RC | -285 | |----------------------------------------------------------| | ERROR_READING_FILE_RC | -286 | |----------------------------------------------------------| | INSUFFICIENT_DISK_SPACE_RC | -287 | |----------------------------------------------------------| | BLOCK_MARK_REQUIRED_RC | -288 | |----------------------------------------------------------| | TOO_MANY_RINGS_RC | -289 | |----------------------------------------------------------| | INCORRECT_VERSION_RC | -290 | |----------------------------------------------------------| | NO_MAIN_ENTRY_POINT_RC | -291 | |----------------------------------------------------------| | ERROR_CLOSING_FILE_RC | -292 | |----------------------------------------------------------| | CMDLINE_TOO_LONG_RC | -300 | |----------------------------------------------------------| | CANT_UNLINK_MOD_IN_USE_RC | -301 | |----------------------------------------------------------| | CANT_UNLINK_KEY_MOD_RC | -302 | |----------------------------------------------------------| | INTERNAL_INVALID_MOD_NBR_RC | -303 | |----------------------------------------------------------| | LINK_MODULE_ERROR_RC | -304 | ----------------------------------------------------------------------------- 132 Programmers Guide to the E Editor Toolkit. Version 2.0 +----------------------------------------------------------+ +----------------------------------------------------------+ | MAIN_NOT_FOUND_RC | -305 | |----------------------------------------------------------| | INIT_NOT_FOUND_RC | -306 | |----------------------------------------------------------| | LOADFILE_FINDFILE_RC | -307 | |----------------------------------------------------------| | LOADFILE_MAKEFILE_RC | -308 | |----------------------------------------------------------| | LOADFILE_ALREADYLINKED_RC | -309 | |----------------------------------------------------------| | UNLINK_UNKNOWN_MODULE_RC | -310 | |----------------------------------------------------------| | UNLINK_BAD_MODULE_FN_RC | -311 | |----------------------------------------------------------| | CALL_DUPLICATED_PROC_RC | -312 | |----------------------------------------------------------| | CALL_UNKNOWN_PROC_RC | -313 | |----------------------------------------------------------| | GREP_MEMORY_ERROR | -314 | |----------------------------------------------------------| | GREP_MISSING_BRACKET | -315 | |----------------------------------------------------------| | GREP_BAD_RANGE | -316 | |----------------------------------------------------------| | GREP_EMPTY_RANGE | -317 | |----------------------------------------------------------| | GREP_REGULAR_EXPRESSION_LONG | -318 | |----------------------------------------------------------| | DYNALINK_INCORRECT_PARAMETERS | -319 | |----------------------------------------------------------| | CANNOT_FIND_KEYSET | -321 | |----------------------------------------------------------| | BAD_LIBRARY_OR_PROC | -322 | |----------------------------------------------------------| | INVALID_LINE_NUMBER | -323 | |----------------------------------------------------------| | KBDSETSTATUS_FAILED | -324 | |----------------------------------------------------------| | BUFFER_CREATE_SIZE | -325 | |----------------------------------------------------------| | BAD_PROCEDURE | -326 | `----------------------------------------------------------' ----------------------------------------------------------------------------- Appendix 133 APPENDIX E - ____________ ----------------------------------------------------- DESCRIPTION OF THE GLOBAL DATA STRUCTURE. (GLOBDATA) _____________________ +------------------------------------------------------------------------+ | Global Data Structure defined in 'C' | |------------------------------------------------------------------------| | typedef struct { | | HAB hAB; | | EPMRES eres; | | HMODULE eresModule; | | HMQ hmq; | | HDC hDCApp; | | PFNWP DefFrameProc; | | PSZ ShrMsgBuff; | | RECTL rc; | | USHORT stagcount; | | CHAR LastCmdLine[256]; | | CHAR EPMClass[32]; | | CHAR AllowMultProcesses; | | HWND hwndHelpInstance; | | HELPINIT hmiHelpData; | | CHAR IniApplicationName[20]; | | PSZ ExSearchPath; | | BOOL CountOnlyVisibleWindows; | | USHORT ApplicationID; | | CHAR ApplicationName[20]; | | ULONG EditWindowListStyle; | | } GLOBDATA; | | | +------------------------------------------------------------------------+ hAB The Application Anchor Block. To obtain the applications anchor block use the WinInitialize function. (example: hab = WinInitialize(NULL); ) eres Structure shared between applications and ERES.DLL. The pointer to this structure is passed into ERES.DLL where it is used internally. (See Appendix G for a description of this structure) eresModule Module handle of ERES.DLL. Optained with the DosLoadModule function. ----------------------------------------------------------------------------- 134 Programmers Guide to the E Editor Toolkit. Version 2.0 hmq The handle to the applications message queue. hDCApp The handle to the applications window device context. DefFrameProc Used internally. ShrMsgBuff The pointer to the applications shared message buffer. rc Used in positioning editwindows. stagcount Stagger window count. LastCmdLine The last command line used to open an edit window. EPMClass Edit window class name. Used to identify edit windows. AllowMultProcesses Flag to allow multiple processes hwndHelpInstance Window handle of the a help instance of the information presentation facility hmiHelpData Hook for the information presentation facility. IniApplicationName Name of the ini file to save and retrieve internal data from. ----------------------------------------------------------------------------- Appendix 135 ExSearchPath Ex file search path. CountOnlyVisibleWindows When set this flag insures that ERESCountEwindows returns only the number of visible edit windows. ApplicationID Unique window id specified for editwindows. ApplicationName Name of application. EditWindowListStyle Edit window list dialog style flag. The following flags can be used to position the edit window list dialog. o EWindow_List_Window_Middle - display in the middle of the active window. o EWindow_List_Window_Corner - display in the lower right corner of the active window. ----------------------------------------------------------------------------- 136 Programmers Guide to the E Editor Toolkit. Version 2.0 APPENDIX F - ____________ ------------------------------------------------ DESCRIPTION OF THE ERES DATA STRUCTURE. (EPMRES) _____________________ .------------------------------------------------------------------------. | Eres Data Structure defined in 'C' | |------------------------------------------------------------------------| | typedef struct EPMRES_TYPE { | | HAB hAB; | | HWND hwndAppFrame; | | HWND hwndAppClient; | | HWND hwndActiveEdit; | | HWND hwndActiveDlgBox; | | HWND hwndSearchReplaceBox; | | CHAR exfilename[MAXFILENAME]; | | LISTDLG cmd; | | LISTDLG msgbox; | | LISTDLG open1; | | BOOL skipopen1; | | CHAR saveretpath[MAXFILENAME]; | | PVOID dlgin; | | PVOID internal; | | } EPMRES; | .------------------------------------------------------------------------. hAB The Application Anchor Block. To obtain the applications anchor block use the WinInitialize function. (example: hab = WinInitialize(NULL); ) hwndAppFrame The applications frame window handle. hwndAppClient The applications client window handle. hwndActiveEdit The window handle of the active edit window. hwndActiveDlgBox The window handle of the active dialog box. ----------------------------------------------------------------------------- Appendix 137 hwndSearchReplaceBox The window handle of the Search Replace dialog box. exfilename String containing the name of the main ex file. cmd Structure used to store entries in the command dialog box. msgbox Structure used to store entries in the Message box dialog. open1 Structure containing previous entries in the open dialog box. skipopen1 When set skips the open1 dialog box and presents the list dialog box. saveretpath The name of the file containing retrieve list data. dlgin Pointer to dialog input information. internal Used internally in ERES.DLL. ----------------------------------------------------------------------------- 138 Programmers Guide to the E Editor Toolkit. Version 2.0 APPENDIX G - ____________ ------------------------------------------------------- DESCRIPTION THE MESSAGES HANDLED BY ERESCOMMONWNDPROC() _____________________ The Following message are handled by ERESCommonWndProc(): o WM_COMMAND o EPM_EDIT_NEWFILE o EPM_EDIT_HELPNOTIFY o EPM_EDIT_RETCODE o EPM_EDIT_DESTROYNOTIFY o EPM_POPCMDLINE o EPM_POPMSGBOX o EPM_POPOPENDLG o EPM_POPCHANGEDLG o EPM_POPCONFIGDLG o EPM_POPHELPBROWSER o EPM_POPHELPMGRPANEL o EPM_OPEN_EDITWINDOW o EPM_SAVE_LISTS o EPM_RETRIEVE_LISTS o EPM_EDIT_ACTIVEHWND WM_COMMAND Process a message from the system menu bar. Message parameter one is the id of the item selected. EPM_EDIT_NEWFILE An existing edit window is requesting to open up a new edit window. ERESOpenEditWindow is called to handle it. EPM_EDIT_HELPNOTIFY This message is in response to a WM_HELP message that was received by an edit window. It is handled by either creating a help manager panel, or create a file with the help brower file. EPM_EDIT_RETCODE Used internally. ----------------------------------------------------------------------------- Appendix 139 EPM_EDIT_DESTROYNOTIFY This message notifies EPM that a edit window has been closed. If it was the last edit window and the search replace dialog exists, destroy that dialog. EPM_POPCMDLINE This message is handled by poping the command line dialog box. EPM_POPMSGBOX This message is handled by poping the message dialog box. EPM_POPOPENDLG This message is handled by poping the open1 dialog box. EPM_POPCHANGEDLG This message is handled by poping the find/change dialog box. EPM_POPCONFIGDLG This message is handled by poping the configuration dialog box. EPM_POPHELPBROWSER This message is handled by poping an edit window containing the help browser file. EPM_POPHELPMGRPANEL This message pops a help manager panel. EPM_OPEN_EDITWINDOW Used internally by EPM EPM_SAVE_LISTS Calls ERESSaveLists() EPM_RETRIEVELIST Calls ERESRetrieveList() ----------------------------------------------------------------------------- 140 Programmers Guide to the E Editor Toolkit. Version 2.0 EPM_EDIT_ACTIVEHWND Used internally. ----------------------------------------------------------------------------- Appendix 141