Black Box 4

home *** CD-ROM | disk | FTP | other *** search

/ Black Box 4 / BlackBox.cdr / w3_prog / wedl200.arj / WEDL.DOC < prev next >

Wrap

Text File | 1991-05-01 | 149KB | 3,921 lines

+----------------------------------------------+ | | | | | (tm) | | W E D L | | | | Windows(tm) Enhanced Dialog Library | | | | | | Programmer's Manual | | | | | | Copyright (c) 1991-1992, Nemisoft, Inc. | | | | All Rights Reserved | | | | | | Version 2.00 | | | | May 1, 1992 | | | | | | Developed by Mike Smedley | | | | _______ | | ____|__ | (R) | | --| | |------------------- | | | ____|__ | Association of | | | | |_| Shareware | | |__| o | Professionals | | -----| | |--------------------- | | |___|___| MEMBER | | | | | | | +----------------------------------------------+ 1 SOFTWARE LICENSE WEDL is a shareware product. This allows you to try the software before you buy it. If after evaluating WEDL, you decide to continue using it, you are required to register the software by remitting the registration fee of $55 (plus shipping and handling) to Nemisoft, Inc. See the ORDER.DOC file for information on registering WEDL. This evaluation version of WEDL may be distributed, only in its entirety, for others to evaluate. None of the evaluation files may be modified or deleted. The evaluation version of the WEDL dynamic-link library (WEDL2E.DLL) cannot be distributed with any applications built using it. This requires registration of the software. Anyone distributing this evaluation version of WEDL for any kind of remuneration must first contact Nemisoft for authorization. This authorization will be automatically granted to distributors recognized by the Association of Shareware Professionals (ASP) as adhering to its guidelines for shareware distributors, and such distributors may begin offering WEDL immediately (However, Nemisoft must still be advised so that the distributor can be kept up-to-date with the latest version of WEDL.). DISCLAIMER Nemisoft has used their best efforts in producing this software and documentation. These efforts include the research, development, and testing of this software. Nemisoft makes no warranty of any kind, expressed or implied, with regards to the software or documentation. Neither Nemisoft nor the author, Mike Smedley, shall be liable in any event for incidental or consequential damages in connection with, or arising out of, the furnishing, performance, or use of this software package. All pricing subject to change without notice. TRADEMARKS BIX is a registered trademark of General Videotex Corp. Borland is a registered trademark of Borland International, Inc. CompuServe is a registered trademark of CompuServe, Inc. IBM is a registered trademark of International Business Machines Corp. Microsoft is a registered trademark of the Microsoft Corporation. MS-DOS is a registered trademark of the Microsoft Corporation. Turbo Pascal is a registered trademark of Borland International, Inc. WEDL is a trademark of Nemisoft, Inc. Windows is a trademark of the Microsoft Corporation. 2 TABLE OF CONTENTS Acknowledgements.....................................................6 Introduction.........................................................7 Welcome to WEDL!.................................................8 WEDL Features....................................................8 System Requirements..............................................9 ASP Ombudsman Statement..........................................10 Technical Support................................................10 Archive Contents.................................................10 How to Use this Manual...........................................11 Programming Guide....................................................12 Terminology......................................................13 Naming Conventions...............................................14 How WEDL Fields Work.............................................14 Creating the Dialog Box..........................................15 Defining the Form................................................15 Defining Fields..................................................16 Defining Buttons.................................................17 Generic Control Definitions......................................18 Defining Key Status Messages.....................................18 Creating Enable-Links............................................18 Using Context-Sensitive Help.....................................19 How Field Validation Works.......................................19 Writing Field Validation Functions...............................20 Writing the Error Handler........................................21 Terminating the Form.............................................22 Compiling and Linking............................................22 Executing the Program............................................23 Rebuilding the Library...........................................23 Debugging Checklist..............................................24 Function Reference...................................................25 button_define....................................................26 button_get_check.................................................27 button_get_from_ctrl_id..........................................27 button_get_from_group............................................28 button_get_from_hwnd.............................................28 button_get_hwnd..................................................29 button_has_changed...............................................29 button_lock......................................................29 button_set_check.................................................30 button_unlock....................................................30 char_is_printable................................................30 char_to_lower....................................................31 char_to_upper....................................................31 field_data_to_log................................................31 field_define.....................................................32 field_get_character..............................................37 field_get_from_ctrl_id...........................................37 field_get_from_hwnd..............................................37 field_get_hwnd...................................................38 3 field_get_pos_info...............................................38 field_get_position...............................................38 field_get_text...................................................39 field_has_changed................................................39 field_lock.......................................................40 field_log_to_data................................................40 field_log_to_phys................................................41 field_phys_to_log................................................41 field_set_text...................................................41 field_unlock.....................................................42 form_begin.......................................................42 form_cancel......................................................44 form_end.........................................................45 form_exists......................................................45 form_get_from_hdlg...............................................45 form_get_hdlg....................................................45 form_has_changed.................................................46 form_in_error_cond...............................................46 form_is_cancelled................................................46 form_load........................................................47 form_lock........................................................47 form_ok..........................................................48 form_save........................................................48 form_set_enable_link.............................................49 form_set_help....................................................49 form_unlock......................................................50 form_validate....................................................50 generic_define...................................................51 keystat_define...................................................51 str_delete_char..................................................52 str_insert_char..................................................52 str_is_blank.....................................................53 str_is_value_zero................................................53 str_trim_spaces..................................................53 Data Type Reference..................................................54 BUTTON...........................................................55 FIELD............................................................56 FIELD_POS........................................................57 FORM.............................................................58 HBUTTON..........................................................62 HFIELD...........................................................62 HFORM............................................................62 LPBUTTON.........................................................62 LPFIELD..........................................................62 LPFIELD_POS......................................................62 LPFORM...........................................................63 PBUTTON..........................................................63 PERRFUNC.........................................................63 PFIELD...........................................................63 PFIELD_POS.......................................................63 PFORM............................................................64 PVALFUNC.........................................................64 Appendix A: Picture String Characters...............................65 4 Appendix B: Field Editing Keys......................................68 Appendix C: Type Equivalency Table..................................70 5 Acknowledgments This manual was written using Microsoft Word for Windows. This manual was printed on a Hewlett-Packard LaserJet IIP. The software was written using SemWare's superb QEdit text editor. The resources for the demo program were created using Borland's Resource Workshop. All software and documentation was developed by Mike Smedley. Many thanks to Dieter Menne for exceptional beta testing. 6 Introduction 7 Welcome to WEDL! Welcome to WEDL, the Windows Enhanced Dialog Library. WEDL (pronounced "weddle") is a collection of C functions for Microsoft Windows programmers that makes dialog data entry dramatically easier for both the programmer and the user. WEDL Features Enhanced Edit Controls: * Formatted Data Entry. Define field templates using picture strings. * Internal Field Validation. (eg. Field Cannot Be Blank, Field Cannot Be Zero, etc.) * External Field Validation. (Programmer-defined validation functions) * Automatic Updating of Variables. Supports most standard data types. * True numeric data entry. Supports decimal points, commas, and justification. * Context-Sensitive Help. Each field can have its own unique help context. * 3-Level Undo. * Drag and Drop. Can accept drag and drop file names from File Manager. * Overtype Mode. (In addition to the Insert mode standard in edit controls) * Case Conversion. Support conversions include UPPER, lower, and Proper. * Combo Box Support. The edit controls in combo boxes are supported. * Additional Editing Keys. (See Appendix B) Enhanced Buttons: * Automatic Updating of Variables. Set variable value based on button's check state. 8 * Context-Sensitive Help. Each button can have its own unique help context. Enable-Links: * Provide for automatic enabling/disabling of controls based upon the condition of a field or button. For example, you may want the "OK" button disabled when a given field is blank. Or you may want a field disabled when a check box is not checked. Context-Sensitive Help: * Any dialog box control can have its own help context so when the user presses the F1 key, the Windows Help application will be run and help information for the current control will be displayed. * Form's default help context. (For when the current control doesn't have a help context) Compatibility: WEDL is compatible with (but not limited to) the following: * Microsoft Windows 3.0 (real, standard, and enhanced modes) * Microsoft Windows 3.1 (standard and enhanced modes) * All C and C++ compilers that can produce Microsoft Windows programs. * Turbo Pascal for Windows. * Borland's BWCC custom control library. * Borland's Object Windows Library (OWL). * All resource editors. * Most CASE tools that support the creation of resource files. * All foreign languages supported by the Windows language driver whose characters are part of the 8-bit ANSI character set. The 16-bit Unicode(tm) character set is not supported at this time. System Requirements Microsoft Windows version 3.0 or 3.1. (real, standard, or enhanced mode) MS-DOS version 3.1 or greater. Microsoft Windows Software Development Kit (SDK) or compatible tools. Any C or C++ compiler capable of producing Microsoft Windows programs, 9 or Turbo Pascal for Windows. Other language compilers may or may not be compatible. ASP Ombudsman Statement The author of WEDL, Mike Smedley, is a member of the Association of Shareware Professionals (ASP). ASP wants to make sure that the shareware principle works for you. If you are unable to resolve a shareware- related problem with an ASP member by contacting the member directly, ASP may be able to help. The ASP Ombudsman can help you resolve a dispute or problem with an ASP member, but does not provide technical support for members' products. Please write to the ASP Ombudsman at 545 Grover Road, Muskegon, MI 49442 or send a CompuServe message via CompuServe Mail to ASP Ombudsman 70007,3536. Technical Support Technical support can be obtained by contacting Nemisoft via one of the following methods: Electronic Mail: CompuServe: 71331,2244 BIX: m.smedley FAX: (904) 739-1303 Postal Mail: Nemisoft, Inc. P.O. Box 550774 Jacksonville, FL 32255 U.S.A. Archive Contents Documentation ------------- ORDER.DOC Information on registering WEDL (including upgrades). READ.ME Last-minute updates and other important information WEDL.DOC Programmer's Manual Demonstration Programs ---------------------- DEMO.BMP Bitmap used for background DEMO.C C source code file DEMO.DEF Module definition file DEMO.EXE Executable file DEMO.H C header file DEMO.ICO Application icon DEMO.RC Resource file DEMOBWCC.EXE Executable file which uses Borland's BWCC.DLL DEMOBWCC.RC Resource file for use with Borland's BWCC.DLL DEMOBWCE.MAK Make file for use with Borland's BWCC.DLL 10 DEMOE.MAK Make file for use with Microsoft C or Borland C++ DEMOHELP.H Header file containing program help definitions DEMOHELP.HLP Compiled help file DEMOHELP.HPJ Project file for the demonstration program's help file DEMOHELP.RTF Source text for demonstration program's help file DEMOTPW.PAS Turbo Pascal for Windows source code file DEMOTPW.RES Resource file for DEMOTPW.PAS Interface Files --------------- WEDL.H C header file WEDLE.PAS Turbo Pascal for Windows library interface unit Library Files ------------- WEDL2E.DLL WEDL dynamic-link library (Evaluation version) WEDL2E.LIB WEDL import library (Evaluation version) How to Use this Manual The WEDL Programmer's Manual consists of these main sections: Section Description ------- ----------- Introduction Describes features, system requirements, technical support, etc. Programming Guide Describes terminology, naming conventions, where/how to call WEDL functions, how to compile with several popular compilers, how to rebuild the library, and common programming errors. Function Reference Alphabetical function reference. Data Type Reference Alphabetical data type reference. Appendixes Tables containing supporting information. The source code files for the example programs will be of invaluable assistance while learning to use WEDL. This manual teaches the basics, but to see how WEDL really works, you'll need to review the demonstration source code files thoroughly. The function and data type references are formatted similar to the Microsoft Windows SDK references. The source code examples and data types are given in the C language format. Appendix C contains a translation table for Turbo Pascal programmers. 11 Programming Guide 12 Terminology There are several terms that are used throughout this manual that are important to understand. You should learn these terms so you understand what they mean when you encounter them. These terms include: Term Definition ---- ---------- Form A window containing one or more controls defined by WEDL functions. Field An edit control defined by the WEDL field_define function. Button A radio button, push button, or check box control defined by the WEDL button_define function. Picture String A string of characters passed to the field_define function which defines the field size, the allowable characters for each position in the field, and the placement of formatting characters. Formatting Characters Characters embedded within a field that assist the user in entering the correct data. The positions of the formatting characters within the field are defined in the picture string. Validation Characters Characters within the picture string which define the allowable characters for each position in the field. Validation Function A function written by the programmer to validate the information in a field. Error Handler A function written by the programmer to handle any field errors detected either internally by WEDL or via a validation function. Enable-Link A link between a field or button and another control in the dialog box which automatically enables or disables the control depending upon a given condition. Physical Contents The actual contents of a field. Logical Contents The contents of a field excluding the embedded formatting characters. Physical Position The actual position of the caret in a field. 13 Logical Position The position the caret would be in a field if it contained no embedded formatting characters. Naming Conventions Function Naming WEDL's functions are named in an object-oriented manner. The first part of the function name is the prefix which identifies the type of object the function operates on. The second part of the function name identifies the action to perform on the object. The following is a list of prefixes used by WEDL functions: Prefix Meaning ------ ------- button_ Function operates on a button. char_ Function operates on a character. field_ Function operates on a field. form_ Function operates on a form. generic_ Function is generic - it operates on a any control. keystat_ Function operates on a key status message. str_ Function operates on a character string. Data Type and Variable Naming Data type and variable naming in WEDL is fairly consistent. The prefix 'h' is used for data types and variables corresponding to handles. The prefix 'p' is used for data types and variables corresponding to pointers (not specifying near or far). The prefix 'lp' is used for data types and variables corresponding to far pointers. How WEDL Works WEDL provides extensive dialog management from the time a dialog box is opened until it is closed. During dialog box initialization, the form is defined. The contents of variables are copied to fields for editing. If necessary, data type conversions will be performed automatically. Additionally, any specified formatting characters will be embedded in the fields. Radio buttons and check boxes are initialized to their defined states. Context-sensitive help and enable-links are also defined during form definition. 14 After the dialog box is initialized and the form is defined, the user is allowed to perform editing. When the user is in a WEDL-defined field, every keystroke is monitored by WEDL for validity. The user is not able to move the caret to, or edit, the embedded formatting characters. If the user tries to leave a field that has a validation function attached to it, the validation function will be called. The validation function validates the field and returns an error code. If the field is in error, the error handling function is called. The error handler is used to display an error message and reposition the caret to the position of the error. If the field has an enable-link attaching it to another control, the control will be automatically enabled or disabled depending upon the condition of the field. Radio buttons and check boxes behave as normal. If the button has an enable-link attaching it to another control, the control will be automatically enabled or disabled depending upon the condition of the button. When the user selects "OK" or "Cancel", the form is terminated. If "OK" was selected, the variables associated with the defined fields and buttons will be updated, with data type conversions being performed on-the-fly. All memory allocated by WEDL is released and the dialog box is terminated. Creating the Dialog Box When creating a dialog box to be used with WEDL, very few special considerations are needed. You just use your favorite resource editor to create the dialog box and place the controls within it. Any resource editor will work as will many CASE tools. For edit controls, it is suggested that they have the WS_TABSTOP, WS_BORDER, WS_CHILD, ES_LEFT, and ES_AUTOHSCROLL styles. For edit controls that belong to a combo box, use CBS_AUTOHSCROLL instead of ES_AUTOHSCROLL. For radio buttons and check boxes, you should specify the BS_AUTORADIOBUTTON or BS_AUTOCHECKBOX styles respectively. If the check box is a 3-state check box, use BS_AUTO3STATE. If you desire to have an automatically-updated Insert, CapsLock, or NumLock key status message in your dialog box, place a static text control for each message where you want the message to appear in the dialog box. The static text control must be wide enough to display the entire status message. When assigning IDs to the controls in the dialog box, avoid using values 27701 - 27739. These values are reserved by WEDL. Defining the Form The definition of a form is performed during dialog box initialization, usually after the dialog box is created and before the dialog box is displayed. In most cases, if your development system allows access to it, you will define the form in your dialog procedure during processing 15 of the WM_INITDIALOG message. The functions form_begin and form_end are required for form definition. In between these function calls is where you define individual controls (fields, buttons, etc.), context-sensitive help, status messages, and enable-links. Not all controls within a dialog box need to be defined; only those needing the features offered by WEDL should be defined. The form_begin function is used to mark the beginning of a form definition, specify form features, and specify an error handling function. It is very important that you save the return value (the form's handle) in a static or global variable. The following is an example of a C call to form_begin: hform = form_begin( hDlg, FMF_OVERTYPE, perror_handler ); The form_end function marks the ending of a form. In addition, it performs other processing including allocation of the undo buffers, initialization of the enable-links, and subclassing of the defined controls. After form_end is called, it is not possible to define additional controls or enable-links. The following is an example of a C call to form_end: form_end( hform ); Defining Fields Fields are defined by calling the field_define function during dialog box initialization. The call to field_define must be made between the calls to form_begin and form_end. The purpose of defining a field is to: 1. Assign a picture string to the field. The picture string defines the size of the field, the allowable characters for each field position, and the placement of formatting characters in the field. See Appendix A for a list of characters that can be used in picture strings. 2. Optionally assign a variable to the field. The variable can be initialized or updated by the field. 3. Optionally specify various behavioral features of the field. Such features include numeric formatting, case conversion, space padding, and whether the field belongs to a combo box. See the description of the field_define function for a list of features that can be specified. 4. Optionally assign a validation function to the field. The validation function is written by you, the programmer, to validate the contents of the field. See the section on writing field validation functions below for more information. 5. Optionally assign a Windows Help context to the field. If the 16 user presses F1 in the field, a help screen will be displayed with information on that particular field. See the section on defining context-sensitive help for more information. The following is an example of a call to field_define: field_define( hform, IDD_ACCTNO, &acct_no, FDT_INTEGER, "###", FDF_NUMERIC | FDF_NOTZERO, pcheck_acct_num, BAD_ACCTNO, IDH_ACCTNO ); Defining Buttons A button is a control within your dialog box that typically has an on or off state. The control is usually a radio button, check box, or compatible button. To define a button, you must call the button_define function. The purpose of defining a button is to: 1. Optionally assign a variable to the button. The variable can be set to a value indicating whether the button has been checked or not checked. The variable can also be set to a value indicating which button in a group of buttons was checked. 2. Initialize the state of the button. The button can be initialized on, off, grayed (disabled), or can be set according to the value of the variable assigned to the button. 3. Optionally assign a Windows Help context to the button. If the user presses F1 while on the button, a help screen will be displayed with information on that particular button. See the section on defining context-sensitive help for more information. The following is an example of a call to button_define where the button is not part of a group: button_define( hform, IDD_SAVECHANGES, &bSaveChanges, 0, TRUE, FALSE, BTF_NONE, IDH_SAVECHANGES ); The following calls to button_define demonstrate the definition of a group of 3 related buttons: button_define( hform, IDD_XMODEM, &nProtocol, 1, IDD_XMODEM, 0, BTF_UPDATE, IDH_XMODEM ); button_define( hform, IDD_YMODEM, &nProtocol, 1, IDD_YMODEM, 0, BTF_UPDATE, IDH_YMODEM ); button_define( hform, IDD_ZMODEM, &nProtocol, 1, IDD_ZMODEM, 0, BTF_UPDATE, IDH_ZMODEM ); There's normally no need to call button_define to define a push button. Since a push button only has an instantaneous "on" state, assigning a variable to it would be useless. It is probably better to use the generic_define function for defining push buttons. Once exception is if you are defining the "OK" or "Cancel" push buttons. 17 The "OK" and "Cancel" push buttons are defined by default because WEDL needs to maintain them. They are defined by default to have control ID values of IDOK (1) and IDCANCEL (2), respectively. However, should you want to assign different control IDs or context-sensitive help to these buttons, you can call the button_define function with the BTF_IDOK or BTF_IDCANCEL features, respectively. Here's an example of defining the "OK" button to a different control ID and specifying context-sensitive help: button_define( hform, IDD_DONE, NULL, 0, 0, 0, BTF_IDOK, IDH_DONE ); Generic Control Definitions You are also able to define other controls, such as list boxes, push buttons, or custom controls. This makes it possible to assign context-sensitive help to them and to make sure that key status messages get updated properly. The generic control definition function, generic_define, should be called to define these controls. The following is an example of a call to generic_define: generic_define( hform, IDD_LISTBOX, IDH_LISTBOX ); Defining Key Status Messages In many circumstances, it is desirable to have a status message indicating whether the Insert, CapsLock, or NumLock key is toggled on or off. WEDL provides a simple method for creating these automatically- updated key status messages. All you have to do is create a static text control in your dialog box to be used for the displaying of the status message. Then call the keystat_define function to link the key to the status message. It is recommended that you call keystat_define during form initialization. The only drawbacks to these types of status messages are they cannot be updated while the input focus is set to a control not defined by WEDL. When the user moves to a control that has been defined by WEDL, the status message will be updated. The way to avoid this drawback is to define all controls within the dialog box. Creating Enable-Links It is often desirable to have one control in a dialog box automatically enabled or disabled based upon the state of a given field or button. WEDL's enable-links provide a simple method to accomplish this. To create the enable-link, you must call the form_set_enable_link function during form initialization. This function specifies the handle of the field or button being tested, the condition to test for (eg. whether or not the field is blank), and the control ID of the control being 18 affected. Using Context-Sensitive Help Context-sensitive help can be applied to any individual control defined by WEDL. WEDL uses the standard Windows Help application and F1 (Help) key in its implementation. First you must call the form_set_help function. This specifies the name of the Windows Help file to use and optionally specifies the default help context. In the field_define, button_define, and generic_define function calls, the last parameter, help_context, is used to specify the context ID of the Windows Help topic associated with the control. If the user presses F1 while in a control with a nonzero help_context, the Windows Help application will be executed. Then Windows Help will automatically load the help file specified in the form_set_help function and display the topic for the control's help_context. Or, if the control doesn't have a help_context, the default help context for the form will be used. To create a Windows Help file, you'll need a word processing program capable of producing Rich Text Format (.RTF) files and a help compiler. Consult the documentation for your help compiler for additional information on creating Windows Help files. How Field Validation Works WEDL's field validation features are very powerful and flexible. Fields can be validated by either an internal validation specified by a form or field feature (such as FDF_NOTBLANK, which means the field cannot be blank), or by an external validation function written by the programmer. By default, validation does not occur until the user selects "OK". However, you can force the validation to occur either when the user attempts to leave the field or even upon each keypress. This is accomplished by specifying form or field features such as FDF_VLEAVFLD, which means validation will be performed when the user tries to leave the field, or FDF_VKEYPRES, which means validation will be performed each keypress (the typed-in character is validated against its position in the picture string). When validation occurs, the field is first validated against the internal validations specified by the form or field features. If the field passes those, the external programmer-defined validation function (if one was specified) will be called. The validation function validates the field and optionally returns an error code. If an error condition was detected either internally or externally, the programmer-defined error handling function will be called. Inside the error handling function, you may call MessageBox or other functions notifying the user that an error has occurred. If you do not handle the error during the error handling function, WEDL will display a default 19 error message. After the error handling is finished, the caret is placed back on the field in error at the position of the error. Writing Field Validation Functions A field validation function is a function written by you, the programmer, to validate the information in one or more fields. The validation function is called when the user selects "OK" or when the form_validate function is called. It can also be called if a form has the FMF_VLEAVFLD feature or a field has the FDF_VLEAVFLD feature and the user attempts to leave the field. A validation function is assigned to a field by the field_define function. The validation function must be declared in this form: int FAR PASCAL ValFuncName( HFORM hform, HFIELD hfield, LPSTR lpBuf ); Since the validation function is a callback function, it must be declared FAR and have an entry in the EXPORTS section of your application's module definition file. The validation function is passed the form's handle, the handle of the field being validated, and a pointer to a temporary buffer containing a character string in logical field format. You use this character string to validate the field. If you need to convert the value to a numeric data type, you can use the field_log_to_data function to do so. The validation function can be used to validate data from multiple fields, or even multiple forms. When you are done validating the field's contents, you return either zero if the field contains no errors or the logical position of the error in the field + 1. The following is an example of a validation function that checks an account number and makes sure it is within 100 and 400: int FAR PASCAL CheckAcctNo( HFORM hform, HFIELD hfield, LPSTR lpBuf ) { int nAcctNo; field_log_to_data( hfield, lpBuf, &nAcctNo, FDT_INTEGER ); if( nAcctNo < 100 || nAcctNo > 400 ) return( 1 ); return( 0 ); } Use the validation function only for validating the field. Remember that the validation function is called during WM_KILLFOCUS / WM_SETFOCUS processing. Calling Windows functions that would interfere with this processing could crash your program. (Don't display a message box!) Modifying the contents of the temporary buffer will not change the contents of the field and is not recommended. 20 Writing the Error Handler The error handling function is where errors detected by your field's validation function are handled. An error handler can service a single or multiple forms. After your validation function returns an error code, WEDL calls the error handler. The error handler is passed the handle of the form in error, the handle of the field in error, the error value of the field in error, the logical position of the error, and the event code of the event which triggered the error. Using this information, you can sound a beep, display an error message, or perform other error handling processing related to the error. The error value is used to determine which error has occurred. It is either one of the error values you defined and specified in your calls to field_define, or a WEDL internal error value. If you're not fond of an error message WEDL gives for a certain internal error, you can intercept the error and display a message of your creation. The following WEDL internal errors can be intercepted: Error Value Meaning ----------- ------- ERV_BLANK Field is blank. ERV_INCOMPL Field is incomplete. ERV_INVCHAR Field has an invalid character. ERV_NOTEDIT User tried to edit a noneditable field. ERV_UNEDITED Field has not been edited. ERV_ZERO Field has a value of zero. The error event code can be used to determine which event was initially responsible for the error condition. This feature can be used to display a different error message depending upon which event caused the error. The event code can be one of the following values: Event Code Meaning ---------- ------- ERE_KEYPRESS A key was pressed. ERE_LEAVEFLD User attempted to leave the field. ERE_SELECTOK User attempted to select "OK" or the form_validate function was called. The following is an example error handler: BOOL FAR PASCAL ErrorHandler( HFORM hform, HFIELD hfield, int error_value, int error_position, 21 int error_event ) { HWND hDlg; hDlg = form_get_hdlg( hform ); switch( error_value ) { case BAD_ACCTNO: MessageBeep( 0 ); MessageBox( hDlg, "Bad account number!!", NULL, MB_OK ); break; case BAD_ZIPCODE: MessageBox( hDlg, "Invalid zip code!", NULL, MB_OK ); break; case ERV_BLANK: // internal WEDL error if( error_event == ERE_LEAVEFLD ) MessageBeep( 0 ); break; default: return( FALSE ); // error was not handled } return( TRUE ); // error was handled } After you have handled the error, your error handler returns TRUE if the error was handled; otherwise FALSE. WEDL will take care of positioning the caret to the position of the error. Terminating the Form A form can be terminated by one, and only one, of two methods: by saving the form ("OK") or by cancelling the form ("Cancel"). There are two WEDL functions that handle these conditions: form_ok and form_cancel, respectively. The form_ok function is called upon selection of the "OK" button (or equivalent) and the form_cancel function is called upon selection of the "Cancel" button. After calling form_ok or form_cancel, all of the form's data structures will no longer be valid. In most cases, if your development system allows access to it, you will terminate the form during the dialog procedure's WM_COMMAND message processing. Compiling and Linking Microsoft C/C++: cl -c -AS -Gsw -Ox -Zpe -W3 filename.c link /NOD filename, filename, filename, libw slibcew wedl2e,filename rc filename Borland C++ 3.0: 22 bcc -c -ms -w -WS -O -Z filename.c tlink /Twe /v /n /c c0ws filename, filename, filename, cws cs import mathws wedl2e, filename rc filename Borland C++ IDE, Turbo C++ for Windows: For Turbo C++ for Windows, use Resource Workshop to save the resource file in .RES format. Create a project file and add the following files: FILENAME.C FILENAME.DEF FILENAME.RC WEDL2E.LIB Compile and link the program via the menu by selecting Compile | Build all. Turbo Pascal for Windows IDE: When creating your resources, save them in .RES format so the command line resource compiler is not needed. Load the file into the editor. Select File | Build. QuickC for Windows: Create a project file and add the following files: FILENAME.C FILENAME.DEF FILENAME.RC WEDL2E.LIB Then compile and link the program via the menu by selecting Project | Build. Executing the Program When executing your program that uses WEDL, the only requirement is that the library file WEDL2E.DLL be in the current directory, the PATH, or the Windows system directory. Rebuilding the Library 23 To rebuild the WEDL library, you will need Microsoft C 6.0, Microsoft C/C++ 7.0, or Borland C++ 3.0. Other C or C++ compilers may work as well, but only these have been tested. You will also need the Microsoft Windows 3.1 Software Development Kit (SDK). There is an included make file which you should use when rebuilding the library (WEDL.MAK). This make file will work with Microsoft's NMAKE or Borland's MAKE programs. Debugging Checklist There are a few common programming errors when using the WEDL library. This checklist will help you spot them: 1. Character string variables must be large enough to hold the characters in the field + one additional character for the terminating '\0'; 2. The form handle must be declared global or static. 3. Invalid characters in the picture string will cause field_define to fail. 4. If a field is in update mode, the contents of the variables being updated must be initialized. 5. Do not call MessageBox or any other functions which would change the input focus during a validation function. 6. The data type specified in the data_type parameter of the field_define function must match the data type pointed to by the pdata parameter. 7. Combo box fields cannot have formatting characters in the picture string unless the field has the FDF_PHYSICAL feature and all strings in the combo box's list box are in physical field format. 8. Be careful not to specify field features (FDF_ prefix) when calling form_begin, or form features (FMF_ prefix) when calling field_define. 9. After calling form_ok or form_cancel, the form handle and the handles of all defined controls become invalid. Do not call any other WEDL functions which rely on the validity of these handles. You can call form_exists to check a form handle for validity. 24 Function Reference 25 button_define Syntax HBUTTON button_define(hform, ctrl_id, pdata, group_id, on_value, off_value, features, help_context) Defines a button. Parameter Type/Description --------- ---------------- hform HFORM The form's handle. ctrl_id int The dialog control ID of the button or check box control being defined. pdata LPINT Pointer to the integer variable that will be automatically initialized or updated by the button control. If NULL is given, the button will not manipulate any variables and the button's value will have to be retrieved manually. group_id int An identifier specifying the group the button belongs to. For example, if there was a group box containing 2 radio buttons, one for "Male" and the other for "Female", you'd define both of their buttons with the same pdata and group_id. If the button does not belong to a group, set group_id to 0. on_value int The value that will be stored at the integer pointed to by pdata if the button is checked. off_value int The value that will be stored at the integer variable pointed to by pdata if the button is not checked. If the button control belongs to a group (group_id is nonzero), the value given for off_value is ignored. features DWORD One or more button features combined with the bitwise OR operator. Can be one or more of the following: Value Meaning ----- ------- BTF_NONE No features specified. BTF_CHECKED Button will be initially checked. 26 BTF_GRAYED Button will be initially grayed if it is a 3-state button. BTF_UPDATE Button will be initialized according to the value of the integer pointed to by pdata. If the value is equal to the on_value, the button will be initially checked. Otherwise, the button will be initially unchecked. BTF_IDOK Button is the "OK" button. BTF_CANCEL Button is the "Cancel" button. help_context DWORD The help context identifier of the Windows Help topic associated with the button. If context-sensitive help is not being applied to the button, set help_context to 0. If context-sensitive help is being applied to the button, the form_set_help function must be called prior to the F1 key being pressed. Return Value The handle of the new button's record or NULL if an error occurred. An error can be caused by one of the following conditions: * Control ID is invalid. * The form_end function has already been called. * Memory allocation error. ------------------------------------------------------------------------ button_get_check Syntax int button_get_check(hbutton) Gets the check state of a button. Parameter Type/Description --------- ---------------- hbutton HBUTTON The button's handle. Return Value 0 if the button is not checked, 1 if the button is checked, or -1 if an error occurred. ------------------------------------------------------------------------ button_get_from_ctrl_id 27 Syntax HBUTTON button_get_from_ctrl_id(hform, ctrl_id) Gets the handle of a button using its dialog control ID as input. Parameter Type/Description --------- ---------------- hform HFORM The form's handle. ctrl_id int The dialog control ID of the control the button is associated with. Return Value The handle of the button associated with the input dialog control ID or NULL if an error occurred. ------------------------------------------------------------------------ button_get_from_group Syntax HBUTTON button_get_from_group(hform, group_id) Gets the handle of the checked button in a group of buttons. Parameter Type/Description --------- ---------------- hform HFORM The form's handle. group_id int The group ID of the group of buttons to test. Return Value The handle of the button that is checked or NULL if an error occurred. ------------------------------------------------------------------------ button_get_from_hwnd Syntax HBUTTON button_get_from_hwnd(hform, hWnd) Gets the handle of a button using the window handle of its control as input. Parameter Type/Description --------- ---------------- hform HFORM The form's handle. hWnd HWND The window handle of the control associated with the button. Return Value The handle of the button associated with the input window handle or NULL if an error occurred. ------------------------------------------------------------------------ 28 button_get_hwnd Syntax HWND button_get_hwnd(hbutton) Gets the window handle of a push button or check box. Parameter Type/Description --------- ---------------- hbutton HBUTTON The button's handle. Return Value The window handle of the button or NULL if an error occurred. ------------------------------------------------------------------------ button_has_changed Syntax BOOL button_has_changed(hbutton) Determines whether a button has been changed by the user. Parameter Type/Description --------- ---------------- hbutton HBUTTON The button's handle. Return Value TRUE if the user has changed the button; otherwise FALSE. ------------------------------------------------------------------------ button_lock Syntax LPBUTTON button_lock(hbutton) Locks a button's record in memory so it can be accessed. Parameter Type/Description --------- ---------------- hbutton HBUTTON The button's handle. Return Value A far pointer to the button's record or NULL if an error occurred. See the description for the BUTTON struct for details. Comments Once you have obtained a pointer to the button's record, you are able to read or change any of the record's elements. However, it is not recommended that you change the values of any of the elements. When you are done accessing the button's record, be sure to call button_unlock. 29 Calling this function locks the button's record in the .DLL's local heap. In addition, the .DLL's entire data segment is locked in the global heap. This is required to ensure the returned far pointer will remain valid until the call to button_unlock. For this reason, you should not keep the button locked any longer than absolutely necessary. ------------------------------------------------------------------------ button_set_check Syntax int button_set_check(hbutton, state) Sets the check state of a button. Parameter Type/Description --------- ---------------- hbutton HBUTTON The button's handle. state int The state to set the button control to. 0 = not checked, 1 = checked, 2 = grayed (3-state button only). Return Value Nonzero if an error occurred. ------------------------------------------------------------------------ button_unlock Syntax void button_unlock(hbutton) Unlocks a button's record in memory. Parameter Type/Description --------- ---------------- hbutton HBUTTON The button's handle. Return Value None. ------------------------------------------------------------------------ char_is_printable Syntax BOOL char_is_printable(ch) Determines whether a character is printable. This determination is made based upon Windows' current language driver settings. Parameter Type/Description --------- ---------------- ch int The character to test. 30 Return Value TRUE if the character is printable; otherwise FALSE. ------------------------------------------------------------------------ char_to_lower Syntax int char_to_lower(ch) Converts a character to lowercase. This conversion is made based upon Windows' current language driver settings. Parameter Type/Description --------- ---------------- ch int The character to convert. Return Value The converted character. ------------------------------------------------------------------------ char_to_upper Syntax int char_to_upper(ch) Converts a character to uppercase. This conversion is made based upon Windows' current language driver settings. Parameter Type/Description --------- ---------------- ch int The character to convert. Return Value The converted character. ------------------------------------------------------------------------ field_data_to_log Syntax int field_data_to_log(hfield, pbuf, pdata, data_type) Converts a value in a specified data type to a character string in logical field format. Parameter Type/Description --------- ---------------- hfield HFIELD The field's handle. pbuf LPSTR Pointer to the buffer to receive the converted value. pdata LPVOID Pointer to the data item to containing the data to convert. This parameter can point to one of the following types: char (string), int, unsigned, long, unsigned long, float, or double. The value 31 you give for the data_type parameter must correspond to the data pointed to by pdata. data_type int Specifies the data type pdata points to. See the description of the field_define function for a list of possible values. Return Value Nonzero if an error occurred. ------------------------------------------------------------------------ field_define Syntax HFIELD field_define(hform, ctrl_id, pdata, data_type, picture_string, features, pvalid_func, error_value, help_context) Defines a field. This function is called for each edit control in your dialog box you want to define. Parameter Type/Description --------- ---------------- hform HFORM The form's handle. ctrl_id int The dialog control ID of the edit control you want to define. pdata LPVOID Pointer to the data item you are going to initialize or update. This parameter can point to one of the following types: char (string), short, unsigned short, int, unsigned, long, unsigned long, float, or double. It can also be NULL if you do not want any data modified by the field. The value you give for the data_type parameter must correspond to the data pointed to by pdata. data_type int Specifies the data type pdata points to. Can be one of the following values: Value Meaning ----- ------- FDT_NULL The pdata parameter is NULL. FDT_STRING pdata points to a character string. The string must be terminated with a '\0' if you are updating existing data. FDT_SHORT pdata points to a 16-bit signed short integer. 32 FDT_USHORT pdata points to a 16-bit unsigned short integer. FDT_INTEGER pdata points to a signed integer. FDT_UNSIGNED pdata points to an unsigned integer. FDT_LONG pdata points to a 32-bit signed long integer. FDT_ULONG pdata points to an 32-bit unsigned long integer. FDT_FLOAT pdata points to a single- precision real number. FDT_DOUBLE pdata points to a double- precision real number. picture_string LPSTR The field's picture string. The picture string describes the allowable characters for each position in the field, the size of the field, and the positioning of the formatting characters. See Appendix A for a list of characters you can use in the picture string. features DWORD One or more features describing how the field should behave. You can combine features with the bitwise OR operator. Can be one or more of the following values: Value Meaning ----- ------- FDF_NONE No features defined. FDF_COMPLETE Field must be complete (no blanks allowed unless specified in the picture string). FDF_NOTBLANK Field cannot be blank. FDF_NOTZERO Field cannot be zero. FDF_NOTEDIT Field cannot be edited. Normally this feature is combined with FDF_UPDATE. FDF_MUSTEDIT Field must be edited. 33 FDF_UPDATE Update existing data. This initializes the edit control with the data pointed to by pdata. Not required if the form has the FMF_UPDATE feature specified. FDF_NOSELECT Field will not be automatically selected upon gaining focus. FDF_SPCFILL Space-fill field from the right. The data_type must be FDT_STRING. FDF_ZEROFILL Zero-fill numeric field from the left. FDF_NUMERIC or FDF_CALCNUM must also be specified. FDF_BLNKZERO Blank numeric field if equal to zero. FDF_NUMERIC or FDF_CALCNUM must also be specified. FDF_BLNKNEZ Blank not equal zero. If a numeric field is blank, it will not be forced to zero. FDF_NUMERIC or FDF_CALCNUM must also be specified. FDF_PHYSICAL The FDT_STRING variable pointed to by pdata will be read and written in physical field format (with embedded formatting characters). FDF_UPPER Characters enters into the field will be converted to uppercase. FDF_LOWER Characters entered into the field will be converted to lowercase. FDF_PROPER Characters entered into the field will be converted to uppercase or lowercase depending upon the previous character. The Shift key overrides automatic lowercase conversion. 34 FDF_NUMERIC Field is a standard numeric field. FDF_CALCNUM Field is a calculator-style numeric field. Digits to the left of the decimal are shifted to the left as digits are entered. FDF_VKEYPRES Each character entered into the field will be immediately validated against the corresponding validation character in the field's picture string. Not required if the form has the FMF_VKEYPRES feature specified. FDF_VLEAVFLD Validation of the field will occur when the user attempts to leave the field. Not required if the form has the FMF_VLEAVFLD feature specified. FDF_COMBO Field belongs to a combo box. Use caution when defining a combo box field with embedded formatting characters - strings in the combo box's list box must have the same format as the picture string. pvalid_func PVALFUNC The procedure-instance address of the field's validation function or NULL if there is no validation function. This cannot be the address of the validation function itself. A procedure- instance address must be created using MakeProcInstance and this is the value given here. See the following "Comments" section for details. error_value int This is the value that is passed to the dialog procedure when the validation function returns an error. If pvalid_func is NULL, the value given for error_value is ignored. help_context DWORD The help context identifier of the Windows Help topic associated with the 35 field. If context-sensitive help is not being applied to the field, set help_context to 0. If context-sensitive help is being applied to the field, the form_set_help function must be called prior to the F1 key being pressed. Return Value The handle of the new field's record or NULL if an error occurred. An error can be caused by one of the following conditions: Picture string is invalid or invalid for the specified field feature(s). Control ID is invalid. The form_end function has already been called. Memory allocation error. Comments The validation function must use the Pascal calling convention and must be declared FAR. The validation function must have the following form: Validation int FAR PASCAL ValidationFunc(HFORM hform, HFIELD hfield, Function LPSTR lpBuf) ValidationFunc represents the programmer-defined validation function's name. The name of the validation function must be listed in an EXPORTS statement in the program's module definition file. The validation function is used to validate a field. When the user tries to leave the field, ValidationFunc is called. The ValidationFunc then validates the field's logical contents and returns zero if no error was found or the logical position of the error + 1. Parameter Description --------- ----------- hform Handle of the form containing the field being validated. hfield Handle of the field being validated. lpBuf Pointer to the buffer containing the field's current logical contents. Return Value Zero if the field passed validation, or the logical position of the error in the field + 1. Comments Modifying the data pointed to by lpBuf will have no effect on the contents of the field. ------------------------------------------------------------------------ 36 field_get_character Syntax int field_get_character(hfield, position, physical) Gets a character from the contents of a field. Parameter Type/Description --------- ---------------- hfield HFIELD The field's handle. position int The logical or physical position from which the character will be retrieved. physical BOOL TRUE if position is a physical position. FALSE if position is a logical position. Return Value The specified character or -1 if an error occurred. ------------------------------------------------------------------------ field_get_from_ctrl_id Syntax HFIELD field_get_from_ctrl_id(hform, ctrl_id) Gets the handle for a field associated with a given dialog control ID. Parameter Type/Description --------- ---------------- hform HFORM The form's handle. ctrl_id int The dialog control ID of the field's edit control. Return Value The handle of the field associated with the input dialog control ID or NULL if an error occurred. ------------------------------------------------------------------------ field_get_from_hwnd Syntax HFIELD field_get_from_hwnd(hform, hWnd) Gets the handle for a field associated with a given edit control's window handle. Parameter Type/Description --------- ---------------- hform HFORM The form's handle. hWnd HWND The window handle of the field's edit 37 control. Return Value The handle of the field associated with the input window handle or NULL if an error occurred. ------------------------------------------------------------------------ field_get_hwnd Syntax HWND field_get_hwnd(hfield) Gets the window handle of a field's edit control. Parameter Type/Description --------- ---------------- hfield HFIELD The field's handle. Return Value The window handle of the field's edit control or NULL if an error occurred. ------------------------------------------------------------------------ field_get_pos_info Syntax int field_get_pos_info(hfield, logical_position, pfpos) Gets information related to a field's logical position. This information includes the physical position, selection, picture string position, validation character, validation character occurrence, and which side of the decimal point the position lies. Parameter Type/Description --------- ---------------- hfield HFIELD The field's handle. logical_position int The logical position to get information for. pfpos LPFIELD_POS A pointer to the FIELD_POS struct which will receive the information. See the description of the FIELD_POS structure for details. Return Value Nonzero if an error occurred. ------------------------------------------------------------------------ field_get_position Syntax int field_get_position(hfield, pfpos) Gets information related to the current position in a field. 38 This information includes the logical position, physical position, selection, picture string position, validation character, validation character occurrence, and which side of the decimal point the position lies. Parameter Type/Description --------- ---------------- hfield HFIELD The field's handle. pfpos LPFIELD_POS A pointer to the FIELD_POS struct which will receive the information. See the description of the FIELD_POS structure for details. Return Value Nonzero if an error occurred. Comments The field identified by hfield must have the focus when calling this function. ------------------------------------------------------------------------ field_get_text Syntax int field_get_text(hfield, pbuf, physical) Gets the contents of a field. Parameter Type/Description --------- ---------------- hfield HFIELD The field's handle. pbuf LPSTR Pointer to the buffer to receives the field's contents. physical BOOL TRUE specifies physical contents are to be copied to pbuf. FALSE specifies logical contents are to be copied. Return Value Nonzero if an error occurred. ------------------------------------------------------------------------ field_has_changed Syntax BOOL field_has_changed(hfield) Determines whether a field has been edited by the user. Parameter Type/Description --------- ---------------- hfield HFIELD The field's handle. Return Value TRUE if the user has edited the field; otherwise FALSE. 39 ------------------------------------------------------------------------ field_lock Syntax LPFIELD field_lock(hfield) Locks a field's record in memory so it can be accessed. Parameter Type/Description --------- ---------------- hfield HFIELD The field's handle. Return Value A far pointer to the field's record or NULL if an error occurred. See the description for the FIELD struct for details. Comments Once you have obtained a pointer to the field's record, you are able to read or change any of the record's elements. However, it is not recommended that you change the values of any of the elements. When you are done accessing the field's record, be sure to call field_unlock. Calling this function locks the field's record in the .DLL's local heap. In addition, the .DLL's entire data segment is locked in the global heap. This is required to ensure the returned far pointer will remain valid until the call to field_unlock. For this reason, you should not keep the field locked any longer than absolutely necessary. ------------------------------------------------------------------------ field_log_to_data Syntax int field_log_to_data(hfield, pbuf, pdata, data_type) Converts a character string in logical field format to a value in a specified data type. Parameter Type/Description --------- ---------------- hfield HFIELD The field's handle. pbuf LPSTR Pointer to the buffer containing the string to convert. pdata LPVOID Pointer to the data item to receive the converted value. This parameter can point to one of the following types: char (string), int, unsigned, long, unsigned long, float, or double. The value you give 40 for the data_type parameter must correspond to the data pointed to by pdata. data_type int Specifies the data type pdata points to. See the description of the field_define function for a list of possible values. Return Value Nonzero if an error occurred. ------------------------------------------------------------------------ field_log_to_phys Syntax int field_log_to_phys(hfield, pbuf) Converts a character string in logical field format to physical field format. Parameter Type/Description --------- ---------------- hfield HFIELD The field's handle. pbuf LPSTR Pointer to the buffer containing the string to convert. Return Value Nonzero if an error occurred. ------------------------------------------------------------------------ field_phys_to_log Syntax int field_phys_to_log(hfield, pbuf) Converts a character string in physical field format to logical field format. Parameter Type/Description --------- ---------------- hfield HFIELD The field's handle. pbuf LPSTR Pointer to the buffer containing the string to convert. Return Value Nonzero if an error occurred. ------------------------------------------------------------------------ field_set_text Syntax int field_set_text(hfield, pbuf, physical) Sets the contents of a field. 41 Parameter Type/Description --------- ---------------- hfield HFIELD The field's handle. pbuf LPSTR Pointer to the buffer containing the string to be used for the field's contents. physical BOOL TRUE if the string pointed to by pbuf is in physical field format. FALSE if the string is in logical field format. Return Value Nonzero if an error occurred. ------------------------------------------------------------------------ field_unlock Syntax void field_unlock(hfield) Unlocks a field's record in memory. Parameter Type/Description --------- ---------------- hfield HFIELD The field's handle. Return Value None. ------------------------------------------------------------------------ form_begin Syntax HFORM form_begin(hDlg, features, perror_func) Begins a form definition. Parameter Type/Description --------- ---------------- hDlg HWND The window handle of the dialog box. features DWORD One or more features describing how the form should behave. You can combine features with the bitwise OR operator. Can be one or more of the following values: Value Meaning ----- ------- FMF_NONE No features defined. FMF_OVERTYPE Sets the Insert mode off by default. Normally, Insert mode is on by default. 42 FMF_UPDATE Sets all fields and buttons in update mode. Has the same effect as giving all fields the FDF_UPDATE and all buttons the BTF_UPDATE features. FMF_VKEYPRES Specifies that for all fields, each character entered will be immediately validated against the corresponding validation character in the field's picture string. FMF_VLEAVFLD Specifies that for all fields, validation will occur when the user attempts to leave the field. FMF_NOSELECT Specifies that for all fields, the contents of the field will not be automatically selected upon gaining focus. perror_func PERRFUNC The procedure-instance address of the form's error hander function. This cannot be the address of the error handler function itself. A procedure-instance address must be created using MakeProcInstance and this is the value given here. See the following "Comments" section for details. You can specify NULL and WEDL will use default error handling. Return Value The new form's handle or NULL if an error occurred. This handle should be assigned to a static or global variable for use in future function calls. Comments The error handler function must use the Pascal calling convention and must be declared FAR. The error handler function must have the following form: Error BOOL FAR PASCAL ErrorHandler(HFORM hform, HFIELD hfield, Handler int error_value, int error_position, int error_event) ErrorHandler represents the error handler function's name. The name of the error handler function must be listed in an EXPORTS statement in the program's module definition file. The error handler is used to notify the user that an error has occurred and to perform other error processing. When a validation function returns an error, or if an internal WEDL error occurs, the error handler is called. 43 Parameter Description --------- ----------- hform The handle of the form which contains the field in error. hfield The handle of the field in error. error_value The error value of the field in error. error_position The logical position of the error + 1. error_event The event which caused the error. Can be one of the following values: Value Meaning ----- ------- ERE_KEYPRESS A key was pressed. ERE_LEAVEFLD User attempted to leave the field. ERE_SELECTOK User attempted to select "OK" or the form_validate function was called. Return Value TRUE if the error was handled by the error handler function; otherwise FALSE. ------------------------------------------------------------------------ form_cancel Syntax int form_cancel(hform) Terminates processing of the form. Form changes are not saved. All memory allocated by the form and the defined controls within it will be freed. Parameter Type/Description --------- ---------------- hform HFORM The form's handle. Return Value Nonzero if an error occurred. Comments This function is typically called after the user presses the "Cancel" button. After calling this function, all handles and pointers corresponding to the form and its defined controls will no longer be valid. ------------------------------------------------------------------------ 44 form_end Syntax int form_end(hform) Ends a form definition. Parameter Type/Description --------- ---------------- hform HFORM The form's handle. Return Value Nonzero if an error occurred. Comments This function must be called during the WM_INITDIALOG message processing in the dialog procedure. After calling this function, no more controls can be defined. ------------------------------------------------------------------------ form_exists Syntax BOOL form_exists(hform) Determines if a given form handle is valid. Parameter Type/Description --------- ---------------- hform HFORM The form handle to test. Return Value TRUE if the form handle is valid; otherwise FALSE. ------------------------------------------------------------------------ form_get_from_hdlg Syntax HFORM form_get_from_hdlg(hDlg) Gets the handle of a form associated with a given dialog box window handle. Parameter Type/Description --------- ---------------- hDlg HWND The window handle of the dialog box. Return Value The handle of the form associated with the input dialog box window handle or NULL if an error occurred. ------------------------------------------------------------------------ form_get_hdlg Syntax HWND form_get_hdlg(hform) 45 Gets the window handle of a form's dialog box. Parameter Type/Description --------- ---------------- hform HFORM The form's handle. Return Value The window handle of the form's dialog box or NULL if an error occurred. ------------------------------------------------------------------------ form_has_changed Syntax BOOL form_has_changed(hform) Determines whether any of the defined fields or buttons of a form have been changed by the user. Parameter Type/Description --------- ---------------- hform HFORM The form's handle. Return Value TRUE if one or more defined fields or buttons have been changed by the user; otherwise FALSE. ------------------------------------------------------------------------ form_in_error_cond Syntax BOOL form_in_error_cond(hform) Determines whether a form is in an error condition. Parameter Type/Description --------- ---------------- hform HFORM The form's handle. Return Value TRUE if the form is in an error condition; otherwise FALSE. Comments When a validation error has occurred, the form is in an error condition. Even if a field's error handler is active, messages are still sent to the dialog procedure. It is often desirable to check to see if the form is in an error condition before processing these messages. For example, if the form is in an error condition, you would not want to any IDOK processing to occur. Calling this function first can prevent this from happening. ------------------------------------------------------------------------ form_is_cancelled 46 Syntax BOOL form_is_cancelled(hform) Determines whether a form has been cancelled. Parameter Type/Description --------- ---------------- hform HFORM The form's handle. Return Value TRUE if the form has been cancelled; otherwise FALSE. Comments The form is cancelled when the user presses the Escape key or clicks on the "Cancel" button. Even if the form has been cancelled, messages are still sent to the dialog procedure. It is often desirable to check to see if the form has been cancelled before processing these messages. ------------------------------------------------------------------------ form_load Syntax int form_load(hform) Updates all defined fields and buttons to reflect the current values of their linked variables. Parameter Type/Description --------- ---------------- hform HFORM The form's handle. Return Value Nonzero if an error occurred. ------------------------------------------------------------------------ form_lock Syntax LPFORM form_lock(hform) Locks a form's record in memory so it can be accessed. Parameter Type/Description --------- ---------------- hform HFORM The form's handle. Return Value A far pointer to the form's record or NULL if an error occurred. See the description for the FORM struct for details. Comments Once you have obtained a pointer to the form's record, you are able to read or change any of the record's elements. However, it is not recommended that you change the values of any of the elements. When you are done accessing the form's record, be sure to 47 call form_unlock. Calling this function locks the form's record in the .DLL's local heap. In addition, the .DLL's entire data segment is locked in the global heap. This is required to ensure the returned far pointer will remain valid until the call to form_unlock. For this reason, you should not keep the form locked any longer than absolutely necessary. ------------------------------------------------------------------------ form_ok Syntax int form_ok(hform) Saves form changes and terminates the form. All memory allocated by the form and the defined controls within it will be freed. Parameter Type/Description --------- ---------------- hform HFORM The form's handle. Return Value Nonzero if an error occurred. Comments This function is typically called after the user presses the "OK" button. This function must be called prior to EndDialog, DestroyWindow, etc. Calling this function has the same effect as calling form_save then form_cancel. ------------------------------------------------------------------------ form_save Syntax int form_save(hform) Updates all linked variables linked to reflect the current values of their associated fields and buttons. Parameter Type/Description --------- ---------------- hform HFORM The form's handle. Return Value Nonzero if an error occurred. Comments This function does not validate any of the fields before copying their contents to their linked variables. It is recommended that you call form_validate prior to calling this function. ------------------------------------------------------------------------ 48 form_set_enable_link Syntax int form_set_enable_link(hform, hcontrol, condition, ctrl_id, enable) Creates an "enable-link" between a defined field or button and another control in the dialog box. This enable-link provides automatic enabling or disabling of a control based upon a condition of the field or button. Parameter Type/Description --------- ---------------- hform HFORM The form's handle. hcontrol HANDLE The handle of the field or button to be tested. You should cast the HFIELD or HBUTTON value to a HANDLE. condition DWORD The condition to test for. Can be one of the following values: Value Meaning ----- ------- ELC_BLANK Field is blank. ELC_ZERO Field contains a value of zero. ELC_EDITED Field has been edited by the user. ELC_CHECKED Button is checked. You cannot specify this value unless hcontrol is a button handle. ctrl_id int The control ID of the control to enable or disable based on the results of the test. enable BOOL TRUE if the control specified by ctrl_id is to be enabled. Return Value Nonzero if an error occurred. ------------------------------------------------------------------------ form_set_help Syntax int form_set_help(hform, help_file_name, help_context) Sets the file name of the Windows Help file to be used for context-sensitive help for individual controls in the dialog box. 49 Parameter Type/Description --------- ---------------- hform HFORM The form's handle. help_file_name LPSTR Pointer to the character string containing the Windows Help file name. The full drive:path specification can be included. help_context DWORD Default Windows Help context for the form. When the user presses F1 on a defined control that doesn't have a help context defined for it, this help context value will be used instead. If no default help context is to be defined, set this value to 0. Return Value Nonzero if an error occurred. ------------------------------------------------------------------------ form_unlock Syntax void form_unlock(hform) Unlocks a form's record in memory. Parameter Type/Description --------- ---------------- hform HFORM The form's handle. Return Value None. ------------------------------------------------------------------------ form_validate Syntax HFIELD form_validate(hform) Forces validation of all fields in a form. If a field fails validation, input focus will be set to the field in error. Parameter Type/Description --------- ---------------- hform HFORM The form's handle. Return Value The handle of the field that failed validation or NULL if all fields passed validation. A value of -1 will be returned in the event of an error. Comments The validation of fields is normally handled internally by WEDL; however, calling this function will force the 50 validation of all fields from within your program. ------------------------------------------------------------------------ generic_define Syntax HANDLE generic_define(hform, ctrl_id, help_context) Defines a control for use with WEDL. This allows the control to have context-sensitive help associated with it. Parameter Type/Description --------- ---------------- hform HFORM The form's handle. ctrl_id int The control ID of the control to define. help_context DWORD The help context identifier of the Windows Help topic associated with the control. If context-sensitive help is not being applied to the control, set help_context to 0. If context-sensitive help is being applied to the control, the form_set_help function must be called prior to the F1 key being pressed. Return Value The handle of the new control's record or NULL if an error occurred. ------------------------------------------------------------------------ keystat_define Syntax int keystat_define(hform, ctrl_id, which, onmsg, offmsg) Defines a static text control to be used as a status message for the Insert, CapsLock, or NumLock key. Parameter Type/Description --------- ---------------- hform HFORM The form's handle. ctrl_id int The dialog control ID of the static text control to be used for the status message. which int Identifier that specifies which status message is to be assigned to the control. Can be one of the following values: Value Meaning 51 ----- ------- KSM_INSERT Insert key status message. KSM_CAPSLOCK CapsLock key status message. KSM_NUMLOCK NumLock key status message. onmsg LPSTR The message to set the static text control to when the key identified by which is toggled on. offmsg LPSTR The message to set the static text control to when the key identified by which is toggled off. Return Value Nonzero if an error occurred. Comments The static text control used for the key status message will be updated automatically when the user toggles the key. However, if the key is toggled while the user is in a control that has not been defined, the message will not be updated until the user moves to a control that has been defined. ------------------------------------------------------------------------ str_delete_char Syntax int str_delete_char(pstr, ch) Deletes the first occurrence of a character from a string. Parameter Type/Description --------- ---------------- pstr LPSTR Pointer to the string to operate on. ch int The character to delete. Return Value Nonzero if the character was not found. ------------------------------------------------------------------------ str_insert_char Syntax void str_insert_char(pstr, ch, offs) Inserts a character into a string. Parameter Type/Description --------- ---------------- pstr LPSTR Pointer to the string to operate on. 52 ch int The character to insert. offs int The offset into the string where the character is to be inserted. Return Value None. ------------------------------------------------------------------------ str_is_blank Syntax BOOL str_is_blank(pstr) Determines whether a string is blank. Parameter Type/Description --------- ---------------- pstr LPSTR Pointer to the string to test. Return Value TRUE if the string is blank; otherwise FALSE. ------------------------------------------------------------------------ str_is_value_zero Syntax BOOL str_is_value_zero(pstr) Determines whether a string contains a numeric value of zero. Parameter Type/Description --------- ---------------- pstr LPSTR Pointer to the string to test. Return Value TRUE if the string contains a numeric value of zero; otherwise FALSE. ------------------------------------------------------------------------ str_trim_spaces Syntax void str_trim_spaces(pstr) Trims trailing spaces from a string. Parameter Type/Description --------- ---------------- pstr LPSTR Pointer to the string to operate on. Return Value None. 53 Data Type Reference 54 BUTTON Button Record The BUTTON structure contains information about a defined button. typedef struct { DWORD features; DWORD help_context; LPINT pdata; HWND hwnd; HBUTTON hbutton; HBUTTON hnext_button; int ctrl_id; int group_id; int off_value; int on_value; BOOL has_changed; } BUTTON; The BUTTON structure contains the following elements: Element Description ------- ----------- features Contains one or more button features combined with the bitwise OR operator. See the description of the button_define function for a list of possible values. help_context The help context identifier of the Windows Help topic associated with the button. pdata Pointer to the integer variable being updated or initialized by the button. hwnd Window handle of the button control. hbutton Handle of the BUTTON data structure. (Self-reference) hnext_button Handle of the next BUTTON data structure in the linked list of buttons. ctrl_id Dialog control ID of the button control associated with the button. group_id Group ID of the button. Other buttons with the same group ID belong to the same group as this button. 55 off_value The value that will be stored at the integer variable pointed to by pdata if the button is not checked. on_value The value that will be stored at the integer variable pointed to by pdata if the button is checked. has_changed Flag indicating whether the button has been changed by the user. Comments The values of these elements should not be directly changed. ------------------------------------------------------------------------ FIELD Field Record The FIELD structure contains information about a defined field. typedef struct { DWORD features; DWORD help_context; LPVOID pdata; LPSTR picture_string; PVALFUNC pvalid_func; HWND hcombo; HWND hwnd; HFIELD hfield; HFIELD hnext_field; int ctrl_id; int data_type; int decimal_position; int error_value; int logical_size; int physical_size; BOOL has_changed; } FIELD; The FIELD structure contains the following elements: Element Description ------- ----------- features Contains one or more field features combined with the bitwise OR operator. See the description of the field_define function for a list of possible values. help_context The help context identifier of the Windows Help topic associated with the field. 56 picture_string Pointer to the picture string associated with the field. pdata Pointer to the data item being updated or initialized by the field. See the description of the field_define function for a list of the data types that pdata can point to. pvalid_func Procedure-instance address of the field's validation function. hcombo Window handle of the combo box a field belongs to. hwnd Window handle of the field's edit control. hfield Handle of the FIELD data structure. (Self-reference) hnext_field Handle of the next FIELD data structure in the linked list of fields. ctrl_id Dialog control ID of the edit control associated with the field. data_type Specifies what pdata points to. See the description of the field_define function for a list of possible values. decimal_position Virtual logical position of the decimal point. error_value The error value used when the validation function returns an error. logical_size Logical size of the field. physical_size Physical size of the field. has_changed Flag indicating whether the field has been edited by the user. Comments The values of these elements should not be directly changed. ------------------------------------------------------------------------ FIELD_POS Field Position Information The FIELD_POS structure contains information about a position in a field. 57 typedef struct { LPSTR ppicture_str_pos; long selection; int logical_position; int physical_position; int val_char_occ; BOOL to_right_of_dec; char validation_char; } FIELD_POS; The FIELD_POS structure contains the following elements: Element Description ------- ----------- ppicture_str_pos Pointer to the position in the picture string that is associated with the position. selection The field's selection. The low-order word will always be equal to the high-order word. logical_position The field's logical position. physical_position The field's physical position. val_char_occ Validation character occurrence. When there is multiple occurrence validation characters (such as "A(25)") in a field, the values for ppicture_str_pos and validation_char will remain the same regardless of which occurrence the position is at. The val_char_occ identifies which occurrence the position is associated with. to_right_of_dec Flag indicating whether the position is on the right-hand side of the decimal. validation_char The validation character. See Appendix A for a list of possible values. ------------------------------------------------------------------------ FORM Form Record The FORM structure contains information about a form. typedef struct { DWORD features; PERRFUNC perror_func; 58 FARPROC pdialog_proc; DWORD help_context; LPSTR capslock_offmsg; LPSTR capslock_onmsg; LPSTR help_file_name; LPSTR insert_offmsg; LPSTR insert_onmsg; LPSTR numlock_offmsg; LPSTR numlock_onmsg; long undo_selection; HANDLE hhead_elink; HANDLE hproc_array; HANDLE hundo_buffer1; HANDLE hundo_buffer2; HWND hdlg; HFORM hform; HFORM hnext_form; HFIELD hcurr_field; HFIELD herror_field; HFIELD hhead_field; HBUTTON hhead_button; int cancel_id; int capslock_id; int error_event; int error_position; int error_value; int insert_id; int numlock_id; int num_controls; int ok_id; int undo_level; BOOL edit_key_pressed; BOOL help_invoked; BOOL insert_mode; BOOL in_error_handler; BOOL just_passed_dec; BOOL pressed_cancel; } FORM; The FORM structure contains the following elements: Element Description ------- ----------- features Contains one or more form features combined with the bitwise OR operator. See the description of the form_begin function for a list of possible values. perror_func The procedure-instance address of the error handler function. pdialog_proc Address of the dialog box's window procedure. 59 help_context The default Windows Help context for the form. capslock_offmsg Pointer to the character string containing the message indicating the CapsLock key is off. capslock_onmsg Pointer to the character string containing the message indicating the CapsLock key is on. help_file_name Pointer to the character string containing the help file name. insert_offmsg Pointer to the character string containing the message indicating the Insert key is off. insert_onmsg Pointer to the character string containing the message indicating the Insert key is on. numlock_offmsg Pointer to the character string containing the message indicating the NumLock key is off. numlock_onmsg Pointer to the character string containing the message indicating the NumLock key is on. undo_selection The selection that the field will be set to after an undo. hhead_elink Handle of the head node in the enable-link linked list. hproc_array Handle of the memory block which contains the window procedure array that holds the window procedure addresses for each defined control. hundo_buffer1 Handle of memory block containing the contents of undo buffer #1. hundo_buffer2 Handle of memory block containing the contents of undo buffer #2. hdlg The window handle of the dialog box associated with the form. hform Handle of the FORM data structure. (Self-reference) hnext_form Handle of the next FORM data structure in 60 the linked list of forms. hcurr_field Handle of the FIELD structure of the current field. herror_field Handle of the field in error, or NULL if there is no field in error. hhead_field Handle of the head FIELD structure in the linked list of fields. hhead_button Handle of the head BUTTON structure in the linked list of buttons. cancel_id Control ID of the "Cancel" button. capslock_id Control ID of the static text control used for the CapsLock key status message. error_event Event that caused the error. See WEDL.DEF for a list of possible values. error_position Logical position of the error in the field + 1. error_value Error value of the field in error, or 0 if there is no field in error. insert_id Control ID of the static text control used for the Insert key status message. numlock_id Control ID of the static text control used for the NumLock key status message. num_controls Number of defined controls in the form. ok_id Control ID of the "OK" button. undo_level Current undo level (0, 1, or 2). edit_key_pressed Flag indicating whether the last key pressed was an editing key or a character key. help_invoked Flag indicating whether the Windows Help application has been invoked from within any of the defined controls. insert_mode Flag indicating whether insert mode is on. in_error_handler Flag indicating that the error handler is processing. 61 just_passed_dec Flag indicating whether the last keystroke moved the caret from the position to the left of the decimal to the position to the right of the decimal. pressed_cancel Flag indicating whether the user pressed or clicked on the "Cancel" button. Comments The values of these elements should not be directly changed. ------------------------------------------------------------------------ HBUTTON Handle of a BUTTON Structure typedef HANDLE HBUTTON; ------------------------------------------------------------------------ HFIELD Handle of a FIELD Structure typedef HANDLE HFIELD; ------------------------------------------------------------------------ HFORM Handle of a FORM Structure typedef HANDLE HFORM; ------------------------------------------------------------------------ LPBUTTON Far Pointer to a BUTTON Structure typedef BUTTON FAR * LPBUTTON; ------------------------------------------------------------------------ LPFIELD Far Pointer to a FIELD Structure typedef FIELD FAR * LPFIELD; ------------------------------------------------------------------------ LPFIELD_POS 62 Far Pointer to a FIELD_POS Structure typedef FIELD_POS FAR * LPFIELD_POS; ------------------------------------------------------------------------ LPFORM Far Pointer to a FORM Structure typedef FORM FAR * LPFORM; ------------------------------------------------------------------------ PBUTTON Pointer to a BUTTON Structure typedef BUTTON * PBUTTON; ------------------------------------------------------------------------ PERRFUNC Pointer to an Error Handler Function This is a pointer which is used to hold the address of a form's error handler function. The address can either be the actual address or the procedure-instance address (created by MakeProcInstance). typedef BOOL (FAR PASCAL *PERRFUNC) (HFORM,HFIELD,int,int,int); ------------------------------------------------------------------------ PFIELD Pointer to a FIELD Structure typedef FIELD * PFIELD; ------------------------------------------------------------------------ PFIELD_POS Pointer to a FIELD_POS Structure typedef FIELD_POS * PFIELD_POS; ------------------------------------------------------------------------ 63 PFORM Pointer to a FORM Structure typedef FORM * PFORM; ------------------------------------------------------------------------ PVALFUNC Pointer to a Validation Function This is a pointer which is used to hold the address of a field's validation function. The address can either be the actual address or the procedure-instance address (created by MakeProcInstance). typedef int (FAR PASCAL *PVALFUNC) (HFORM,HFIELD,LPSTR); 64 Appendix A: Picture String Characters Character Meaning --------- ------- 9 Accept a numeric character (0 - 9). N Accept an integer numeric character (0 - 9, -, +). # Accept a real numeric character (0 - 9, -, +, ., E, e). A Accept an alphabetic character (A - Z, a - z). Foreign alphabetic characters are supported. X Accept an alphanumeric character (A - Z, a - z, 0 - 9). Foreign alphabetic characters are supported. Y Accept a yes/no character (Y, y, N, n). D Accept a date character (0 - 9, -, /). T Accept a telephone number character (0 - 9, (, ), -, +). F Accept a file name character (any character except \, :, *, ?, ;, ,, =, +, <, >, |, /, [, ], "). P Accept a pathspec character (any character except ;, ,, =, +, <, >, |, /, [, ], "). ? Accept any printable character. ! Accept any printable character. If the character is a lowercase letter, convert it to uppercase. Foreign alphabetic characters are supported. < ..... > Accept only one of the characters listed between the angle brackets. For example, "<0123>" will accept only 0, 1, 2, or 3. Also you can specify a range using two periods between the two range limiting characters. For example, "<0..3>" would be equivalent to "<0123>". Or you can get fancy, "<0..3>5<7..9>" would accept 0, 1, 2, 3, 5, 7, 8, or 9. Characters are converted to uppercase. For example, "<A..Z>" will accept any uppercase or lowercase letter. 65 > ..... < Accept any character except the ones listed between the angle brackets. Works similar to the "<.....>" characters. ( ..... ) Specifies multiple occurrences of one of the above validation characters. For example, "A(5)" is equivalent to "AAAAA". "<0123>(3)" is equivalent to "<0123><0123><0123>". The open parenthesis must immediately follow the validation character. '.....' Insert formatting characters into field. All characters between the single quotes are formatting characters. "....." Double quotes have the meaning as single quotes. Useful for when you need to insert formatting characters that include the single quote character. Note in the C programming language, backslashes preceding the double quote characters are required. / Date separator character. The character which is actually displayed is dependent upon Windows' language driver settings. For example, in the U.S. a '/' would be displayed. In Germany, a '.' would be displayed. . Special formatting character which specifies where the decimal point will be in a numeric field. You can only have one decimal point in a picture string. The field must have either the FDF_NUMERIC or FDF_CALCNUM feature defined. The decimal character which is actually displayed is dependent upon Windows' language driver settings. For example, in the U.S., a '.' would be displayed. In Germany, a ',' would be displayed. , Special formatting character which specifies where conditional commas will be located in a calculator-style numeric field. A comma will only be displayed if a digit exists to the left of it. The field must have the FDF_CALCNUM feature defined. The thousands separator character which is actually displayed is dependent upon Windows' language driver settings. For example, in the U.S., a ',' would be displayed. In Germany, a '.' would be displayed. space The space character can be used throughout the picture string to improve readability. Do not 66 put spaces between angle brackets or quotes unless you intend for them to be there. 67 Appendix B: Field Editing Keys Editing Key Action ----------- ------ Alt+Backspace 3-Level Undo. First press, it restorres the last editing operation. Second press, it restores the contents of the field upon gaining focus. Third press, it restores the initial contents of the field. Backspace Deletes the character to the left of the caret. If the field has a selection, the selection will be deleted. CapsLock Toggles Caps Lock mode. Ctrl+Backspace Deletes the word to the left of the caret. If the field has a selection, the selection will be deleted. Ctrl+Delete Deletes the word at the caret. If the field has a selection, the selection will be deleted. Ctrl+End Move the caret to the last position in the field. Ctrl+Insert Copy. Copies the field's selection to the clipboard. Ctrl+LeftArrow Moves the caret to the beginning of the previous word. Ctrl+RightArrow Moves the caret to the beginning of the next word. Ctrl+Shift+Delete Deletes all characters to the right of the caret. If the field has a selection, this is equivalent to Shift+Delete (Cut). Delete Deletes the character at the caret. If the field has a selection, the selection will be deleted. End Moves the caret to the position following the last character in the field. F1 Displays context-sensitive help for the field. Home Moves the to the first position in the field. Insert Toggles Insert mode. LeftArrow Moves the caret to the previous position. 68 NumLock Toggles Num Lock mode. Period (Decimal Point) Moves the caret to the opposite side of the decimal point in a numeric field. RightArrow Moves the caret to the next position. Shift+Delete Cut. Copies the field's selection to the clipboard, then deletes the selection. Shift+Insert Paste. Inserts the contents of the clipboard into the field at the caret position. 69 Appendix C: Type Equivalency Table This table provides a method of interpreting the C langauge data types described in this manual as their equivalent Turbo Pascal representations. C/C++ Turbo Pascal ----- ------------ BOOL Bool BUTTON BUTTON char Char double Double DWORD LongInt FARPROC TFarProc FIELD FIELD FIELD_POS FIELD_POS float Single FORM FORM HANDLE THandle HBUTTON HBUTTON HFIELD HFIELD HFORM HFORM HWND HWnd int Integer LONG LongInt long LongInt LPBUTTON LPBUTTON LPFIELD LPFIELD LPFIELD_POS LPFIELD_POS LPFORM LPFORM LPINT PInteger LPSTR PStr LPVOID LPVoid PBUTTON PBUTTON PERRFUNC PERRFUNC PFIELD PFIELD PFIELD_POS PFIELD_POS PFORM PFORM PVALFUNC PVALFUNC short Integer unsigned Word unsigned short Word unsigned long LongInt WORD Word 70