home *** CD-ROM | disk | FTP | other *** search
/ OS/2 Shareware BBS: 10 Tools / 10-Tools.zip / pmos2002.zip / DEF / windows.def < prev   
Text File  |  1998-01-26  |  22KB  |  417 lines
  1. DEFINITION MODULE Windows;
  2.  
  3.         (****************************************************************)
  4.         (*                                                              *)
  5.         (*                  Text-mode screen windows.                   *)
  6.         (*                                                              *)
  7.         (*  Programmer:         P. Moylan                               *)
  8.         (*  Last edited:        26 January 1998                         *)
  9.         (*  Status:             Working                                 *)
  10.         (*                                                              *)
  11.         (****************************************************************)
  12.  
  13. (************************************************************************)
  14. (*                                                                      *)
  15. (* REMARK: There are two versions of the basic 'write' procedure.       *)
  16. (* Procedure WriteChar treats every character as a printable character, *)
  17. (* so it can write any character in the standard character set.  This   *)
  18. (* is the output procedure recommended for general use.  Control        *)
  19. (* operations are supplied by separate procedures such as WriteLn,      *)
  20. (* SetCursor, etc., so there is no need to resort to the BASIC          *)
  21. (* programmers' trick of writing long strings of obscure control codes. *)
  22. (* But for people who can't break this bad habit, procedure Write is    *)
  23. (* supplied; this treats character codes 0..31 as control codes.        *)
  24. (* Its main intended uses are to echo keyboard input, and to print a    *)
  25. (* file which contains embedded control characters; but it may be       *)
  26. (* used for other purposes if desired.                                  *)
  27. (*                                                                      *)
  28. (* Warning: I have not bothered to look after all the control codes,    *)
  29. (* just the ones I found a use for.  Most of them print as a            *)
  30. (* two-character sequence ^<letter>.                                    *)
  31. (*                                                                      *)
  32. (************************************************************************)
  33.  
  34. (************************************************************************)
  35. (*                                                                      *)
  36. (* NOTE ON CRITICAL SECTIONS: When using this module in a multitasking  *)
  37. (* environment, there are numerous critical sections because several    *)
  38. (* tasks may be using the same physical screen.  These sections are     *)
  39. (* protected by semaphores.  (For the case where we are not using the   *)
  40. (* multitasking kernel, there is a version of module Semaphores which   *)
  41. (* contains dummy procedures).  The general philosophy is to assume     *)
  42. (* that critical section protection is needed for inter-window          *)
  43. (* conflicts, but that no protection is needed for operations on a      *)
  44. (* single window because the most common situation is that each window  *)
  45. (* is used by only one task.  If there happen to be windows which are   *)
  46. (* shared by two or more tasks, the associated synchronization problems *)
  47. (* must be resolved by the caller; they are not resolved in module      *)
  48. (* Windows, on the grounds that the extra overhead is not justified     *)
  49. (* just to support a case which rarely happens in practice.             *)
  50. (*                                                                      *)
  51. (*                                                                      *)
  52. (*                      LATEST DEVELOPMENT                              *)
  53. (*                                                                      *)
  54. (* Because of the addition of the MouseControl module, it can happen in *)
  55. (* practice, so I've added partial protection.  The following           *)
  56. (* procedures are indivisible with respect to one another, as far as    *)
  57. (* shared uses of a window are concerned:                               *)
  58. (*      OpenWindow, CloseWindow, ShiftWindowRel, ScrollUp, ScrollDown,  *)
  59. (*      WriteChar, WriteLn, SetCursor, Hide, PutOnTop.                  *)
  60. (* Minor technicality: in some cases there is an implied PutOnTop, or   *)
  61. (* similar side-effect, and this is not always part of the indivisible  *)
  62. (* section.  I can't think of any case where this would matter to the   *)
  63. (* user.  I don't like making protected sections too large, since this  *)
  64. (* can degrade overall system responsiveness.                           *)
  65. (*                                                                      *)
  66. (* Note: procedures WriteString and Write, while not indivisible in     *)
  67. (* the above sense, are protected at the "write a character" level.     *)
  68. (*                                                                      *)
  69. (************************************************************************)
  70.  
  71. CONST
  72.     MaxRowNumber = 24;
  73.     MaxColumnNumber = 79;
  74.  
  75. TYPE
  76.     Window;     (* is private *)
  77.     Colour = (black, blue, green, cyan, red, magenta, brown, white,
  78.                 darkgrey, lightblue, lightgreen, lightcyan, lightred,
  79.                 lightmagenta, yellow, intensewhite);
  80.  
  81.     (* Note: Any of these colours may be used as a foreground colour,   *)
  82.     (* but in most applications only [black..white] are suitable as     *)
  83.     (* background colours.  The others may be used, but they can give   *)
  84.     (* strange effects such as a blinking display.  Use with care!      *)
  85.  
  86.     RowRange = [0..MaxRowNumber];
  87.     ColumnRange = [0..MaxColumnNumber];
  88.  
  89.     Rectangle = RECORD
  90.                     top, bottom: RowRange;
  91.                     left, right: ColumnRange;
  92.                 END (*RECORD*);
  93.  
  94.     FrameType = (noframe, simpleframe, doubleframe);
  95.     DividerType = (nodivider, simpledivider, doubledivider);
  96.  
  97.     DisplayPage = [0..3];
  98.  
  99. PROCEDURE OpenWindow (VAR (*OUT*) w: Window;
  100.                         ForegroundColour, BackgroundColour: Colour;
  101.                         firstline, lastline: RowRange;
  102.                         firstcol, lastcol: ColumnRange;
  103.                         FrameDesired: FrameType;
  104.                         DividerDesired: DividerType);
  105.  
  106.     (* Create a new window.  Note that row and column numbers start     *)
  107.     (* from 0.  NOTE: If the window has a box drawn around it (the case *)
  108.     (* FrameDesired <> noframe), this subtracts from the space          *)
  109.     (* available for text.                                              *)
  110.  
  111. PROCEDURE OpenWindowHidden (VAR (*OUT*) w: Window;
  112.                         ForegroundColour, BackgroundColour: Colour;
  113.                         firstline, lastline: RowRange;
  114.                         firstcol, lastcol: ColumnRange;
  115.                         FrameDesired: FrameType;
  116.                         DividerDesired: DividerType);
  117.  
  118.     (* Like OpenWindow, but the window does not appear on the screen    *)
  119.     (* until the first PutOnTop(w).                                     *)
  120.  
  121. PROCEDURE OpenSimpleWindow (VAR (*OUT*) w: Window;
  122.                         firstline, lastline: RowRange;
  123.                         firstcol, lastcol: ColumnRange);
  124.  
  125.     (* Identical to OpenWindow, except that you don't get any choice    *)
  126.     (* about the colours or frame.  The window is white-on-black with   *)
  127.     (* a simple frame and no dividers for the scrolling region.  This   *)
  128.     (* version of OpenWindow is useful for those with monochrome        *)
  129.     (* displays who don't want to be bothered with importing the types  *)
  130.     (* Colour, FrameType, and DividerType.                              *)
  131.  
  132. PROCEDURE ChangeScrollingRegion (w: Window; firstline, lastline: RowRange);
  133.  
  134.     (* Changes the scrolling region of window w to the new line         *)
  135.     (* boundaries given, and sets the cursor of this window to the      *)
  136.     (* start of the scrolling region.  Row numbers are window-relative; *)
  137.     (* that is, line 0 is the top line of the window (which is where    *)
  138.     (* the border is, unless you have no border).                       *)
  139.  
  140. PROCEDURE NewScrollingRegion (w: Window;  firstline, lastline: RowRange;
  141.                                 firstcolumn, lastcolumn: ColumnRange);
  142.  
  143.     (* Changes the scrolling region of w to be the specified rectangle, *)
  144.     (* but unlike ChangeScrollingRegion this procedure does not redraw  *)
  145.     (* the dividers.  Furthermore the old scrolling region set by       *)
  146.     (* ChangeScrollingRegion is remembered and may be restored by a     *)
  147.     (* call to ResetScrollingRegion.                                    *)
  148.  
  149. PROCEDURE ResetScrollingRegion (w: Window);
  150.  
  151.     (* Changes the scrolling region of w back to what it was the last   *)
  152.     (* time ChangeScrollingRegion was called.  If ChangeScrollingRegion *)
  153.     (* was never called, the scrolling region goes back to being the    *)
  154.     (* entire window minus the frame (if any).                          *)
  155.  
  156. PROCEDURE SetWrapOption (w: Window;  enabled: BOOLEAN);
  157.  
  158.     (* If the parameter is TRUE - this is the initial default - then    *)
  159.     (* subsequent text written to the window will wrap to the next      *)
  160.     (* line when it hits the right of the scrolling region.  Setting    *)
  161.     (* the parameter to FALSE disables this feature.                    *)
  162.  
  163. PROCEDURE ShiftWindowRel (w: Window;  rowchange, columnchange: INTEGER);
  164.  
  165.     (* Moves w on the screen.  The second and third arguments may be    *)
  166.     (* negative.  The amount of move may be reduced to prevent a move   *)
  167.     (* off the edge of the screen.                                      *)
  168.  
  169. PROCEDURE ShiftWindowAbs (w: Window;  top: RowRange;  left: ColumnRange);
  170.  
  171.     (* Like ShiftWindowRel, except that we directly specify the target  *)
  172.     (* position of the top left corner in screen coordinates.           *)
  173.  
  174. PROCEDURE CloseWindow (w: Window);
  175.  
  176.     (* Destroys the window.  Note that this could have side-effects     *)
  177.     (* if procedure InstallCloseHandler (see below) has been called.    *)
  178.  
  179. PROCEDURE Hide (w: Window);
  180.  
  181.     (* Makes this window invisible on the screen.  It is still possible *)
  182.     (* to write to the window, but the output will not appear until     *)
  183.     (* a PutOnTop(w) is executed.                                       *)
  184.  
  185. PROCEDURE PutOnPage (w: Window;  p: DisplayPage);
  186.  
  187.     (* Moves window w to another display page.  The default is to put   *)
  188.     (* every window on page 0 when it is first opened.  To override     *)
  189.     (* the default, call this procedure after opening the window.       *)
  190.  
  191. PROCEDURE PageOf (w: Window): DisplayPage;
  192.  
  193.     (* Returns the display page on which window w resides. *)
  194.  
  195. PROCEDURE PutOnTop (w: Window);
  196.  
  197.     (* Makes sure that window w is fully visible on the screen.  (This  *)
  198.     (* also cancels the effect of a Hide(w).)  Rarely needed, since     *)
  199.     (* many window operations automatically put their window on top.    *)
  200.  
  201. PROCEDURE IdentifyTopWindow (VAR (*OUT*) w: Window;  page: DisplayPage;
  202.                                 VAR (*INOUT*) row: RowRange;
  203.                                 VAR (*INOUT*) col: ColumnRange): BOOLEAN;
  204.  
  205.     (* On entry w is unspecified and (page,row,col) describes a         *)
  206.     (* position on the screen.  On exit w is equal to the top window    *)
  207.     (* containing this screen location, and (row,col) have been altered *)
  208.     (* to be window-relative coordinates.  Exception: if there is no    *)
  209.     (* visible window containing the given point, the function result   *)
  210.     (* is FALSE, the returned w is meaningless, and row and col are     *)
  211.     (* unchanged.                                                       *)
  212.  
  213. PROCEDURE RefreshDisplay;
  214.  
  215.     (* Rewrites every open window.  Should not normally be needed, but  *)
  216.     (* available for use in cases the display is corrupted by, for      *)
  217.     (* example, software which bypasses this module and writes directly *)
  218.     (* to the screen.                                                   *)
  219.  
  220. PROCEDURE SetActivePage (page: DisplayPage);
  221.  
  222.     (* Changes the active display page.  Not needed unless you are      *)
  223.     (* switching among multiple pages.                                  *)
  224.  
  225. PROCEDURE CurrentPage(): DisplayPage;
  226.  
  227.     (* Returns the currently active display page. *)
  228.  
  229. TYPE PageChangeHandler = PROCEDURE (DisplayPage);
  230.  
  231. PROCEDURE RequestPageChangeNotification (Proc: PageChangeHandler);
  232.  
  233.     (* Sets up Proc as a procedure to be called on a page change.       *)
  234.  
  235. TYPE CloseHandlerProc = PROCEDURE (Window, DisplayPage);
  236.  
  237. PROCEDURE InstallCloseHandler (w: Window;  P: CloseHandlerProc);
  238.  
  239.     (* Sets up P as a procedure to be called when the window is closed. *)
  240.     (* It is legal to define multiple handlers for the same window.     *)
  241.  
  242. PROCEDURE WindowLocation (w: Window): Rectangle;
  243.  
  244.     (* Returns the current location of w on the screen. *)
  245.  
  246. PROCEDURE SetCursor (w: Window; row: RowRange; column: ColumnRange);
  247.  
  248.     (* Sets the cursor for window w to the given row and column.  The   *)
  249.     (* coordinates are window-relative; that is, they start at (0,0) at *)
  250.     (* the top left of the window.                                      *)
  251.  
  252. PROCEDURE SaveCursor (w: Window; VAR (*OUT*) row, column: CARDINAL);
  253.  
  254.     (* Returns the current cursor position.  The coordinates are        *)
  255.     (* window-relative; that is, they start at (0,0) at the top left of *)
  256.     (* the window.                                                      *)
  257.  
  258. PROCEDURE CursorLeft (w: Window);
  259.  
  260.     (* Moves the window cursor one position left.  If it falls off the  *)
  261.     (* left edge of the window, it moves to the right edge in the same  *)
  262.     (* row.                                                             *)
  263.  
  264. PROCEDURE CursorRight (w: Window);
  265.  
  266.     (* Moves the window cursor one position right.  If it falls off the *)
  267.     (* right edge of the window, it moves to the left edge in the same  *)
  268.     (* row.                                                             *)
  269.  
  270. PROCEDURE CursorUp (w: Window);
  271.  
  272.     (* Moves the window cursor one position up.  If it falls off the    *)
  273.     (* top edge of the window, it moves to the bottom edge in the same  *)
  274.     (* column.                                                          *)
  275.  
  276. PROCEDURE CursorDown (w: Window);
  277.  
  278.     (* Moves the window cursor one position down.  If it falls off the  *)
  279.     (* bottom edge of the window, it moves to the top edge in the same  *)
  280.     (* column.                                                          *)
  281.  
  282. PROCEDURE ScrollUp (w: Window);
  283.  
  284.     (* Scrolls the scrolling region of window w up by one row, filling  *)
  285.     (* the vacated row with spaces.                                     *)
  286.  
  287. PROCEDURE ScrollDown (w: Window);
  288.  
  289.     (* Scrolls the scrolling region of window w down by one row,        *)
  290.     (* filling the vacated row with spaces.                             *)
  291.  
  292. PROCEDURE WriteLn (w: Window);
  293.  
  294.     (* Go to next line in window, scrolling if necessary.  N.B. The     *)
  295.     (* window does not scroll if you are not in the scrolling region    *)
  296.     (* at the time of the WriteLn.                                      *)
  297.  
  298. PROCEDURE WriteChar (w: Window; ch: CHAR);
  299.  
  300.     (* Write one character.  Control characters are not given special   *)
  301.     (* treatment; they produce something visible just like any other    *)
  302.     (* character.  Wraps to the next line before writing if the write   *)
  303.     (* would put us on or beyond the right border of w.                 *)
  304.  
  305. PROCEDURE Write (w: Window; ch: CHAR);
  306.  
  307.     (* Like WriteChar, but codes in the range 0..31 are treated as      *)
  308.     (* control characters.  This procedure is not recommended for       *)
  309.     (* general use, as it leads to obscure programs.  (Instead, do the  *)
  310.     (* control operations by direct calls to the cursor control         *)
  311.     (* procedures which are also supplied in this module).  It is       *)
  312.     (* supplied mainly to help those who are used to the conventions of *)
  313.     (* the "standard" Modula-2 I/O modules such as InOut.               *)
  314.  
  315. PROCEDURE WriteString (w: Window; text: ARRAY OF CHAR);
  316.  
  317.     (* Write a string of characters, stopping at the first NUL          *)
  318.     (* character or the end of the array, whichever comes first.        *)
  319.  
  320. PROCEDURE ReadBack (w: Window;  r: RowRange;  c: ColumnRange): CHAR;
  321.  
  322.     (* Returns the character which currently occupies relative location *)
  323.     (* (r,c) on the display of window w.                                *)
  324.  
  325. PROCEDURE ReadChar (w: Window;  VAR (*OUT*) ch: CHAR);
  326.  
  327.     (* Read one character, and echo it. *)
  328.  
  329. PROCEDURE LookaheadChar (w: Window): CHAR;
  330.  
  331.     (* Reads a character without consuming it.  That is, the character  *)
  332.     (* remains available to be read by ReadChar.  This allows the       *)
  333.     (* caller to check whether the character is really wanted.          *)
  334.  
  335. PROCEDURE ReadCharWithoutEcho (w: Window;  VAR (*OUT*) ch: CHAR);
  336.  
  337.     (* Read one character, but don't echo it.  However, a blinking      *)
  338.     (* cursor is still displayed to prompt for the character.  (If you  *)
  339.     (* don't want the blinking cursor, use procedure GetKey).           *)
  340.  
  341. PROCEDURE GetKey (w: Window): CHAR;
  342.  
  343.     (* Read one character, without any prompt to the user.  The reason  *)
  344.     (* for specifying a window parameter is to ensure that keyboard     *)
  345.     (* input comes to us only when this window has input focus.         *)
  346.     (* (If you want the input regardless of input focus, use procedure  *)
  347.     (* Keyboard.InKey).                                                 *)
  348.  
  349. PROCEDURE PressAnyKey (w: Window);
  350.  
  351.     (* Types a "Press any key to continue" message.     *)
  352.  
  353. PROCEDURE ReadString (w: Window;  VAR (*OUT*) result: ARRAY OF CHAR);
  354.  
  355.     (* Reads a character string, terminated by carriage return.         *)
  356.  
  357. PROCEDURE EditString (w: Window;  VAR (*INOUT*) result: ARRAY OF CHAR;
  358.                                                 fieldsize: CARDINAL);
  359.  
  360.     (* Reads a character string, where a default result is supplied by  *)
  361.     (* the caller.  The final result is the state of the string at the  *)
  362.     (* time where the keyboard user types a carriage return or Esc, or  *)
  363.     (* uses a cursor movement key to move out of the displayed field.   *)
  364.     (* The terminating character remains available, via Keyboard.InKey, *)
  365.     (* to the caller.  At most fieldsize characters of the string can   *)
  366.     (* be edited, and perhaps fewer if the result array is smaller or   *)
  367.     (* if there is insufficient space in the window.                    *)
  368.  
  369. PROCEDURE EditAborted (): BOOLEAN;
  370.  
  371.     (* Checks the next keyboard input.  Returns TRUE for Escape, FALSE  *)
  372.     (* for anything else.  Escape or Carriage Return are consumed, any  *)
  373.     (* other character is returned to the Keyboard module.              *)
  374.  
  375. PROCEDURE SetColours (w: Window; row: RowRange; col: ColumnRange;
  376.                         nchar: CARDINAL;  foreground, background: Colour);
  377.  
  378.     (* Sets a field of nchar characters, starting at (row,col), to      *)
  379.     (* the specified foreground and background colours.  The location   *)
  380.     (* is given in window-relative coordinates, not absolute screen     *)
  381.     (* positions.  NOTE: Do not assume that this procedure can wrap     *)
  382.     (* around to a new line.  It normally cannot.                       *)
  383.  
  384. PROCEDURE ColourSwap (w: Window; row: RowRange; col: ColumnRange;
  385.                                                         nchar: CARDINAL);
  386.  
  387.     (* Sets a field of nchar characters, starting at (row,col), to      *)
  388.     (* "reverse video" by swapping the foreground and background        *)
  389.     (* colours.  Notice that the process is reversible: you get back to *)
  390.     (* "normal video" by calling this procedure again.  The location is *)
  391.     (* given in window-relative coordinates, not absolute screen        *)
  392.     (* positions.  NOTE: Do not assume that this procedure can wrap     *)
  393.     (* around to a new line.  It normally cannot.                       *)
  394.  
  395. PROCEDURE Blink (w: Window; r: RowRange; c: ColumnRange; nchar: CARDINAL);
  396.  
  397.     (* Toggles the blinking status - that is, turns blinking on if it   *)
  398.     (* was off, and vice versa - for nchar characters, starting at      *)
  399.     (* relative location (r,c) in window w.                             *)
  400.     (* NOTE: This procedure will not wrap around to a new row.          *)
  401.  
  402. PROCEDURE EraseLine (w: Window; option: CARDINAL);
  403.  
  404.     (* Erases some or all of the current line (but never the border).   *)
  405.     (* The erased characters are replaced by space characters.  The     *)
  406.     (* window cursor is moved to the location of the first erased       *)
  407.     (* character.  If w is not the currently active window, the changes *)
  408.     (* will not be visible until w is on top again.  The options are:   *)
  409.     (*          0       the whole of the line, except for the border    *)
  410.     (*          1       from the current cursor position onwards        *)
  411.     (*          2       from the start to just before the cursor        *)
  412.     (* If we are inside a scrolling region, then only that part of the  *)
  413.     (* line inside the scrolling region is affected.                    *)
  414.  
  415. END Windows.
  416. 
  417.