home *** CD-ROM | disk | FTP | other *** search
/ SPACE 2 / SPACE - Library 2 - Volume 1.iso / telecom / 46 / pascal / pager.doc < prev    next >
Encoding:
Text File  |  1986-08-15  |  8.1 KB  |  167 lines
  1.      pager.pas is a simple application in OSS Personal Pascal for the Atari
  2. ST.  I wrote it on a monochrome 1040, but it should work on any system at
  3. any resolution.
  4.  
  5.      My intent was to experiment with the GEM interface from Pascal, and try
  6. to write some kind of "template" program I could use as a basis for more
  7. sophisticated programs later.
  8.  
  9.      Pager is a multiple window file viewer.  Files may be opened or closed,
  10. and viewing can scroll forward or backward.  Pager is organized around the
  11. simplest possible event driven loop:
  12.  
  13.      Initialize
  14.      While still running
  15.         get an event
  16.         deal with it
  17.      Clean up
  18.  
  19.      Pager will handle all of the events returned by Get_Event, although it
  20. ignores the right mouse button, only performs limited menu service, and only
  21. pays attention to the first cursor rectangle event.
  22.  
  23.      Pager also uses built in dialogs, as well as alert boxes, and responds
  24. to menu entries.  It also demonstrates XBIOS calls as well as timer events.
  25.  
  26.      It does not build it's own dialogs, and doesn't use mouse position
  27. information.
  28.  
  29.      Pager starts by offering the user an alert box which allows him to
  30. immediately abort the program.  If he chooses to continue, pager opens the
  31. first file, using the built in "Item Selector" dialog.
  32.  
  33.      In order to spread the overhead of reading files around, the entire
  34. file is not read in immediatly, but rather only enough to fill the default
  35. window, which is full screen size.
  36.  
  37.      Pager than enters it's procesing loop, which consists mostly of waiting
  38. for events to occur and then responding to them.
  39.  
  40.      An unusual event that pager responds to is a ten second interval.  If
  41. no activity has happened within the last ten seconds, pager will put an
  42. alert box up indicating how long it has been since pager has started.
  43.  
  44.      This alert is simply a demonstration of the interval timer, as well as
  45. using XBIOS calls to access supervisor memory.
  46.  
  47.      The events which pager responds to are message events, keyboard events,
  48. timer events, 'rectangle' events, and button pushed events.
  49.  
  50.      Since pager is a template,  I made up a silly use for the rectangle and
  51. button events.  The cursor takes one of four shapes, depending on the mouse
  52. being in or out of the front window, and the left mouse button being down or
  53. up.  In pager, these cursor shapes don't have any real meaning, they are
  54. just window dressing.
  55.  
  56.      Most keyboard events (key strokes) are ignored.  However, the HELP key
  57. causes a HELP alert box to be posted, which would contain something a litte
  58. more useful in a serious program, and the UNDO key causes the quit alert box
  59. to be posted.
  60.  
  61.      Most of the work occurs in message events, which fall into several
  62. catagories.  There are selection events, redraw events, top events, close
  63. events, fulled events, arrowed events, horizontal events, veritical events,
  64. size events, and move events.
  65.  
  66.      A selection event occurs when the mouse is clicked on a menu selection.
  67. Pager allows desk accessories to work and has four menu entries of its own.
  68. A menu event can be used to open a new file, to close an open file (and it's
  69. window,) to quit the program, or to get an "about pager" alert box.
  70.  
  71.      A close event occurs when the close box has been clicked, and causes
  72. pager to close the file, close the window, and free up any related storage.
  73.  
  74.      A full event occurs when the full box has been clicked.  Pager uses the
  75. full box as a toggle event.  If the window is already full, than it is
  76. resized to be the last size it was set to by other than a full.  If it's not
  77. full, then it's set to cover the entire screen.
  78.  
  79.      Since windows start out as full screen size, pager starts with the
  80. assumption that the first 'small' size for a window should be 1/4 the screen
  81. size, located in the upper left hand quarter of the window.
  82.  
  83.      Size events simply cause the window to grow or shrink, in response to
  84. clicking the size box and dragging.  Pager allows the window to assume any
  85. size.
  86.  
  87.      Move events simply cause the window to be displaced, in response to
  88. clicking the title bar and dragging.  Pager will allow the window to be
  89. placed anywhere GEM will put it.
  90.  
  91.      Arrow events occur from clicking in the elevator bar, or on the arrows
  92. at the ends of the elevator bar.  Pager responds to arrow clicks by moving
  93. the page up or down one line, or by moving the display left or right one
  94. character.  Pager responds to elevator bar clicks by moving the page up,
  95. down, left or right one window full, as appropriate.
  96.  
  97.      Because files are only read as needed, the code for keeping track of
  98. the position in the file is a fairly crude, although it appears to be bug
  99. free.
  100.  
  101.      However, the code for calculating the position and size of the elevator
  102. cars is slightly buggy, suffering from some calculation round off errors
  103. which cause the cars to sometimes do nonintuitive things.
  104.  
  105.      Also, until the file has been entirely input, it is not possible to
  106. know the full size of the file, so a heuristic is used for the vertical
  107. elevator.  One full window size is added to the currently known size of the
  108. file when calculating the postion and offset of the elevator, so there will
  109. always be room to click on either side of the bar until the entire file has
  110. been read.  Once the entire file is read, the actual file size is used.
  111.  
  112.      Horizontal and Vertical events occur when the elevator car has been
  113. clicked and drug to a new location.  In this event, Pager calculates the
  114. correct viewing offset according to the new positions of the elevator cars
  115. and redisplays accordingly.
  116.  
  117.      There is room for much improvement in this area, since "scrolling"
  118. consists of erasing and redrawing the entire window, rather than moving the
  119. still visible part and adding new data.
  120.  
  121.      The most interesting event Pager has to deal with is the Redraw event,
  122. which occurs when a portion of a window which was previously invisible
  123. becomes visible.
  124.  
  125.      As you are probably aware, GEM keeps lists of 'visible' rectangles
  126. which make up each of the windows.  The most efficent way to update a window
  127. would be to only redraw the portions which weren't visible before, but which
  128. are now.
  129.  
  130.      Unfortunately, what Pager does is to go through the list of visible
  131. rectangles, setting the clipping region to the part just made visible and
  132. redrawing the entire window.  This is the second area where there is much
  133. room for improvement.
  134.  
  135.      Pager tries to be relitively bug free and robust, and seems to succede
  136. moderately well, (except for the elevator calculations mentioned before.)
  137. However, one are where I systematically did an unsafe bit of coding was in
  138. obtaining memory.  None of the places where new is called to obtain more
  139. memory, is there a check for failure.  This will probably lead to
  140. unpleasentness eventually, and I will probably fix it one of these days.
  141.  
  142.      In writing pager, I discovered that the built in read procedure will
  143. not read character data from other than a text type.  Since I was
  144. considering using random file access to facilitate memory management, I
  145. wrote a "Get_string" routine, which will allow me to expand to random access
  146. if I need it.
  147.  
  148.      Overall,  I have been very impressed with Personal Pascal.  I have
  149. managed to fairly sophisticated programming using only it, it's manual, and
  150. the ABACUS "Internals" manual.  It is reasonably bug free;  I only found two
  151. problems with it while writing pager.  It is reasonably easy to learn; I've
  152. only had it for two weeks, and pager is only about six hours work.
  153. (Although I have had a lot of pascal experience before.)  It runs reasonably
  154. quickly; pager only takes about fifty seconds to compile and link using a
  155. ram disk on my 1040ST.  The support from OSS is good. and the price is
  156. right.
  157.  
  158.      I've also been very impressed with the 1040ST.  I've got a MacUgly
  159. (used to have a girl's name) sitting on my desk at work, complete with full
  160. blown Aztec C, and I still haven't managed to get anything as complete at
  161. pager working using it's interface.  (I also have a lot of C experience,
  162. since hacking Unix kernels is my living.)
  163.  
  164.      All in all, I'm glad I've got the beasty.
  165.  
  166. Marty
  167.