home *** CD-ROM | disk | FTP | other *** search
/ Power-Programmierung / CD2.mdf / c / library / windows / validedt / validedt.doc < prev    next >
Encoding:
Text File  |  1991-11-24  |  9.5 KB  |  256 lines
  1.                        ValidEdit (tm)
  2.     Self-Validating Edit Controls for Microsoft Windows
  3.                               
  4.                   Rolling Thunder Computing
  5.                      20 Hilltop Terrace
  6.                     Woburn MA 01801 USA
  7.                        (617) 938-4326
  8.                               
  9.  
  10. I.  Introduction
  11.  
  12.      ValidEdit is a custom control for use with Microsoft
  13. Windows.  It is a superclass of the EDIT class that can be
  14. set to accept or reject different types of keystrokes, for
  15. example, accepting numbers but rejecting letters. It
  16. improves your user interface by allowing the user of your
  17. programs to type into an edit control only input that is
  18. valid according to rules you specify.
  19.  
  20. II.  Business
  21.  
  22.      ValidEdit is a copyrighted software product of Rolling
  23. Thunder Computing.  It is not in the public domain.  You are
  24. permitted to evaluate this unregistered copy for 30 days, to
  25. copy it freely for backup purposes, and to distribute it
  26. freely to other users for them to evaluate.  If you decide
  27. to continue using it after the 30-day evaluation period is
  28. up, you may obtain a registered copy without the initial
  29. dialog box, with free upgrades for one year, compatible with
  30. Microsoft and Borland dialog box editors, and with no end-
  31. user royalties, by mailing the enclosed license form with
  32. US$ 50 (MA residents add 5% sales tax) to: Rolling Thunder
  33. Computing, 20 Hilltop Terrace, Woburn MA 01801.  Shipping is
  34. free in the United States and Canada, other countries write
  35. for current rates.  Specify 3-1/2 inch or 5-1/4 inch
  36. diskettes.  Your feedback is encouraged to Rolling Thunder
  37. Computing at the above address, or on Compuserve to David
  38. S. Platt, #73540,3430.
  39.  
  40. III.  Files
  41.  
  42.      ValidEdit comes with the following files:
  43.  
  44. VALIDEDT.DLL   A Windows 3.0 DLL containing the code for
  45. processing input to a ValidEdit box.  This file should be
  46. placed in your path, so Windows can locate it.
  47.  
  48. VALIDEDT.DOC   This document.
  49.  
  50. VALIDEDT.H     A header file to be included in any C or .RC
  51. files that need to use ValidEdit controls.  This file should
  52. be placed in your standard headers directory.
  53.  
  54. VALIDEDT.LIC   A license application for registering your
  55. copy of ValidEdit.
  56.  
  57.  
  58.  
  59. IV.  Using a ValidEdit Box
  60.  
  61.      ValidEdit is implemented as a Dynamic Link library.
  62. Your program may either load it explicitly with
  63. LoadLibrary(), or Windows will load it automatically when
  64. you first create a ValidEdit box.  The former method is
  65. faster from the user's point of view, the latter method uses
  66. less memory.
  67.  
  68.      A ValidEdit box is created in the same manner as any
  69. other edit control box.  You will generally want to put it
  70. in a dialog box template in your application's .RC file,
  71. such as:
  72.  
  73. #include <validedt.h>
  74.  
  75. SELECTPAGEBOX DIALOG PRELOAD MOVEABLE DISCARDABLE 22, 17, 140, 80
  76. CAPTION "PAGE SELECTION"
  77. STYLE WS_BORDER | WS_CAPTION | WS_DLGFRAME | DS_SYSMODAL
  78. BEGIN
  79.     CONTROL     "", IDD_PAGENAME, VALIDEDIT_CLASS, WS_BORDER | WS_CHILD | WS_VISIBLE, 45, 30, 50, 15
  80.     DEFPUSHBUTTON "OK"         IDOK, 25, 50, 32, 14, WS_GROUP
  81.     PUSHBUTTON "CANCEL"         IDCANCEL, 83, 50, 32, 14, WS_GROUP
  82. END
  83.  
  84.  
  85. If you do it this way, you will need to set the validation
  86. parameters (see next section) explicitly in the dialog box
  87. procedure, as there is currently no way of setting the
  88. ExStyle parameters directly from a dialog box template. 
  89.  
  90.      If you would rather create the ValidEdit box manually,
  91. we suggest you use CreateWindowEx, which will allow you to
  92. set the validation parameters (see next section) at creation
  93. time, such as:
  94.  
  95. #include <validedt.h>
  96.  
  97. hValidEdit = CreateWindowEx ( IVE_ALPHA, VALIDEDIT_CLASS,
  98.     name, style, x, y, width, height, hParent, hMenu,
  99.     hInstance, lpCreateStruc) ;
  100.  
  101.  
  102. V. Setting Validation Rule Parameters
  103.  
  104.      A ValidEdit box accepts or rejects characters according
  105. to rules that the user gives it.  The rules are specified by
  106. setting various bits in the ValidEdit box's ExStyle DWORD.
  107. You must specify some rule; the default ExStyle is 0, which
  108. means no characters will be accepted.  When the ValidEdit
  109. box rejects a character, it sends a message to its parent,
  110. informing the parent which character it has rejected (see
  111. next section for details on messages).  The ValidEdit box
  112. checks its ExStyle anew every time it receives a character,
  113. so you can change validation rules without having to destroy
  114. and recreate the ValidEdit box.  You set the flags by using
  115. SetWindowLong, thus:
  116.  
  117. SetWindowLong (hValidEdit, GWL_EXSTYLE, IVE_ALPHA | IVE_OCTALDIGIT) ;
  118.  
  119. Styles may be combined as desired without causing trouble,
  120. however, not all combinations make sense. The order in which
  121. a ValidEdit box applies its validation rules is:
  122.  
  123. 1.  Check for explicit exclusion (IVE_EXCLUDETHISLIST) of
  124. characters.  If the newly-entered character is a member of
  125. this list, it is immediately rejected, no matter what other
  126. specified rules it might satisfy.  In this way, you can, for
  127. example, accept all hex digits but 'B'.  (WARNING: explicit
  128. exclusion and inclusion are case sensitive, so if you want
  129. to eliminate the hex value 0xB, you must explicitly exclude
  130. both 'B' and 'b'.)
  131.  
  132. 2.  Check for a second decimal point.  If IVE_ONEDECPOINT is
  133. a specified style, the character is next checked to see if
  134. it is a decimal point, and, if so, whether the ValidEdit box
  135. already contains one.  If it is and it does, the second
  136. decimal point is rejected.
  137.  
  138. 3.  After the first two tests specified above, all of the
  139. other rules are checked in an order which is not
  140. guaranteed.  The first successful match of a character with
  141. a specified rule terminates the checking and causes the
  142. character to be accepted.  Thus, if you specify both
  143. IVE_OCTALDIGIT and IVE_HEXDIGIT, values 8-F are guaranteed
  144. to be accepted all the time, so you might as well not bother
  145. with IVE_OCTALDIGIT. 
  146.  
  147. NOTE:  To conform to expected edit box behavior, the
  148. backspace character (CTRL-H, 0x08) and the delete character
  149. (0x7F) are always accepted unless explicitly excluded.
  150.  
  151. The valid styles are:
  152.  
  153. IVE_HEXDIGIT:  Hexadecimal digits, 0-9 and A-F, case
  154. insensitive.
  155.  
  156. IVE_OCTALDIGIT: Octal digits, 0-7
  157.  
  158. IVE_DECIMALDIGIT: Decimal digits, 0-9
  159.  
  160. IVE_ALPHA: Alphabetic characters, A-Z, case insensitive
  161.  
  162. IVE_ANYPUNCT:  Punctuation characters, anything that
  163. satisfies the ANSI C macro ISPUNCT ().
  164.  
  165. IVE_ONEDECPOINT:  A maximum of one decimal point.  Second
  166. decimal points are rejected.  Useful for floating-point
  167. numbers.
  168.  
  169. IVE_WHITESPACE:  Whitespace characters, anything that
  170. satisfies the ANSI C macro ISSPACE ().
  171.  
  172. IVE_ANYCNTRL: Characters entered with the CTRL key down,
  173. anything that satisfies the ANSI C macro ISCNTRL ().
  174.  
  175. IVE_INCLUDETHISLIST:  Any character that is a member of a
  176. string specified by the programmer.  This string is
  177. specified by means of the WM_SETINCLUDESTRING message
  178. described in the next section.  Checking of this string IS
  179. CASE SENSITIVE.  
  180.  
  181. IVE_EXCLUDETHISLIST:  Any character that is NOT a member of
  182. a string specified by the programmer.  This string is
  183. specified by means of the WM_SETEXCLUDESTRING message
  184. described in the next section. Checking of this string IS
  185. CASE SENSITIVE.  This rule is always evaluated first, and takes
  186. precedence over all the others, even explicit inclusion using
  187. IVE_INCLUDETHISLIST.
  188.  
  189. IVE_ALPHANUMERIC:  Convenient combination of IVE_ALPHA and
  190. IVE_DECIMALDIGIT described above.  All decimal digits 0-9
  191. and all letters A-Z, case insensitive.
  192.  
  193. IVE_FLOATINGPOINT: Convenient combination of
  194. IVE_DECIMALDIGIT and IVE_ONEDECPOINT described above.
  195. Useful for entering floating-point numbers.
  196.  
  197.  
  198.  
  199.  
  200. V.  Messages
  201.  
  202.      A ValidEdit control uses three custom messages in
  203. addition to all the normal messages supported by a stnadard
  204. edit control.  These messages are defined in VALIDEDT.H.
  205. They are:
  206.  
  207. IEVM_INVALIDCHAR
  208.  
  209. This message is sent to you by your ValidEdit box when it
  210. rejects a character.  The user has entered a character which
  211. does not conform to the validation rules specified in the
  212. ValidEdit box.
  213.  
  214. wParam: child window ID of ValidEdit box
  215. lParam: LOWORD is child window handle of ValidEdit box
  216.     HIWORD is rejected character
  217.  
  218. IEVM_SETINCLUDESTRING
  219. IEVM_SETEXCLUDESTRING
  220.  
  221. These two messages are sent by the programmer to the
  222. ValidEdit box, generally at initialization time.  They set
  223. the strings containing the characters which the ValidEdit
  224. box will explicitly include or exclude, respectively.  You
  225. may combine the two together, and also combine them with
  226. other validation rules, making (for example) a ValidEdit box
  227. that accepts all hex digits except 9, and also accepts the
  228. characters '$' and '*'.
  229.  
  230. wParam: not used
  231. lParam: LPSTR, pointing to the string containing the
  232. characters to include or exclude. This string is copied into
  233. the edit control's own data area, so it need not be
  234. maintained by the calling function after successfully
  235. returning.
  236.  
  237. returns:  The length of the include/exclude string if
  238. successful, otherwise NULL.
  239.  
  240. NOTE:  The IVE_INCLUDETHISLIST and IVE_EXCLUDETHISLIST flags
  241. must be set in the ValidEdit box's ExStyle DWORD for
  242. inclusion or exclusion to occur.   Sending the message and
  243. setting the strings is necessary, but not sufficient.  If
  244. you want to temporarily disable inclusion and/or exclusion,
  245. you can simply turn the appropriate style bits off.  This
  246. will not affect the storage of the inclusion/exclusion
  247. lists, which will function correctly as previously set when
  248. you turn the style bits back on.
  249.                               
  250.  
  251.  
  252.  
  253.  
  254. Trademarks of various software products are properties of
  255. their owners.
  256.