home *** CD-ROM | disk | FTP | other *** search
/ OS/2 Shareware BBS: 10 Tools / 10-Tools.zip / pmos2002.zip / DEF / fieldedi.def < prev    next >
Text File  |  1997-11-03  |  8KB  |  131 lines
  1. DEFINITION MODULE FieldEditor;
  2.  
  3.         (********************************************************)
  4.         (*                                                      *)
  5.         (*              Screen editing utilities                *)
  6.         (*                                                      *)
  7.         (*  Programmer:         P. Moylan                       *)
  8.         (*  Last edited:        3 November 1997                 *)
  9.         (*  Status:             OK                              *)
  10.         (*                                                      *)
  11.         (********************************************************)
  12.  
  13. FROM SYSTEM IMPORT
  14.     (* type *)  ADDRESS;
  15.  
  16. FROM Windows IMPORT
  17.     (* type *)  Window;
  18.  
  19. (************************************************************************)
  20. (*                                                                      *)
  21. (*  The editor in this module is "generic" in a limited sense.  It      *)
  22. (*  performs screen editing of variables of arbitrary types, provided   *)
  23. (*  that those types have been declared by calls to DefineFieldType.    *)
  24. (*                                                                      *)
  25. (*  The caller is required, when calling DefineFieldType, to supply     *)
  26. (*  procedures which write and edit variables of that type.  Each of    *)
  27. (*  the user-supplied procedures has three parameters: a window, a      *)
  28. (*  pointer to the variable to be written or edited, and the number of  *)
  29. (*  character positions to use.  For field types where the number of    *)
  30. (*  character positions cannot be determined in advance, the caller is  *)
  31. (*  expected to supply 0 as the value of the third parameter, and the   *)
  32. (*  user-supplied procedures are expected to be able to work out the    *)
  33. (*  actual width required.  The user-supplied procedures are expected,  *)
  34. (*  in all cases, to leave the screen cursor at the character position  *)
  35. (*  just beyond the written form of the field.  They must be prepared   *)
  36. (*  to deal with NIL addresses.  The user-supplied editor must handle   *)
  37. (*  all keystrokes which belong to it, but leave intact (via            *)
  38. (*  Keyboard.Putback, for example) the keystroke which causes it to     *)
  39. (*  return.  Note that it will be very common for the editor to receive *)
  40. (*  a cursor movement key implying that the user does not want to       *)
  41. (*  modify this field but is simply skipping over it.  In such cases    *)
  42. (*  the editor still has the responsibility for showing the user where  *)
  43. (*  the cursor is, by using blinking, reverse video, etc.               *)
  44. (*                                                                      *)
  45. (*  Given all of these rules, and the fact that all the hard work is to *)
  46. (*  be done by user-supplied procedures, you might by now be wondering  *)
  47. (*  whether there is any point in having this module.  The main point   *)
  48. (*  is that the rules impose some uniform standards which make it       *)
  49. (*  easier to develop readable software for applications which need a   *)
  50. (*  lot of screen editing.  They also help, in some applications, to    *)
  51. (*  avoid duplication of effort.  These properties are used to          *)
  52. (*  advantage in modules ListEditor and ScreenEditor.                   *)
  53. (*                                                                      *)
  54. (*  As an added bonus, this module exports some pre-defined field types *)
  55. (*  for commonly encountered cases.  For those cases, the user does not *)
  56. (*  need to call DefineFieldType, and therefore does not need to supply *)
  57. (*  the procedures for writing and editing variables of those types.    *)
  58. (*                                                                      *)
  59. (************************************************************************)
  60.  
  61. TYPE
  62.     FieldType;          (* is private *)
  63.     WriteProc = PROCEDURE (Window, ADDRESS, CARDINAL);
  64.     EditProc = PROCEDURE (Window, VAR (*INOUT*) ADDRESS, CARDINAL);
  65.  
  66. (************************************************************************)
  67. (*                      THE PREDEFINED TYPES                            *)
  68. (************************************************************************)
  69.  
  70. VAR Byte, Cardinal, Real, String: FieldType;
  71.  
  72. (************************************************************************)
  73. (*                      DEFINING A NEW TYPE                             *)
  74. (************************************************************************)
  75.  
  76. PROCEDURE DefineFieldType (Writer: WriteProc;  Editor: EditProc): FieldType;
  77.  
  78.     (* Introduces a new field type into the system.  Writer is a        *)
  79.     (* user-supplied procedure to write a variable of the new type.     *)
  80.     (* Editor is the user-supplied procedure for editing a variable of  *)
  81.     (* that type.                                                       *)
  82.  
  83. PROCEDURE DiscardFieldType (type: FieldType);
  84.  
  85.     (* A notification from the user that this type will not be used     *)
  86.     (* again (unless it is redefined by another call to procedure       *)
  87.     (* DefineFieldType).  Use of this procedure is optional, but is     *)
  88.     (* recommended for the sake of "clean" memory management.           *)
  89.  
  90. (************************************************************************)
  91. (*                         COMPARING TYPES                              *)
  92. (************************************************************************)
  93.  
  94. PROCEDURE SameType (t1, t2: FieldType): BOOLEAN;
  95.  
  96.     (* Returns TRUE iff t1 = t2.        *)
  97.  
  98. (************************************************************************)
  99. (*                          SCREEN OUTPUT                               *)
  100. (************************************************************************)
  101.  
  102. PROCEDURE WriteField (w: Window;  address: ADDRESS;  type: FieldType;
  103.                                                         width: CARDINAL);
  104.  
  105.     (* Writes address^ on the screen at the current cursor position in  *)
  106.     (* window w.  The width parameter specifies how many character      *)
  107.     (* positions to use.  Use width=0 for variable-width fields for     *)
  108.     (* which the write procedure for that type must work out the width. *)
  109.  
  110. (************************************************************************)
  111. (*                           THE EDITOR                                 *)
  112. (************************************************************************)
  113.  
  114. PROCEDURE EditField (w: Window;  VAR (*INOUT*) address: ADDRESS;
  115.                                 type: FieldType;  width: CARDINAL);
  116.  
  117.     (* Edits the variable at the given address, and of the given type,  *)
  118.     (* at the current cursor position in window w.  The width parameter *)
  119.     (* specifies how many character positions are to be used on the     *)
  120.     (* screen.  Set width=0 for variable-width fields where the editor  *)
  121.     (* must determine the width.  We leave this procedure on seeing a   *)
  122.     (* keyboard character which does not belong to us.  The cursor is   *)
  123.     (* left just beyond the last character of the field as it is        *)
  124.     (* displayed.  The terminating keystroke is returned to the         *)
  125.     (* keyboard driver so that it can still be read by the caller.      *)
  126.     (* Note that the address is an inout parameter because there are    *)
  127.     (* cases where we allow the user to create and delete fields, i.e.  *)
  128.     (* address could be NIL on entry but not on exit, or vice versa.    *)
  129.  
  130. END FieldEditor.
  131.