home *** CD-ROM | disk | FTP | other *** search
/ The Datafile PD-CD 3 / PDCD_3.iso / pocketbk / developmen / frame / FRAMELIB.TXT < prev    next >
Text File  |  1993-01-17  |  16KB  |  374 lines
  1. APPLICATION FRAMEWORK FOR PSION SERIES 3                  By John Hind
  2. ----------------------------------------------------------------------
  3. A Dynamic Link Library that supports message-based, event-driven
  4. application programming in OPL on the PSION Series 3 pocket computer.
  5. The library includes support for time-based applications that cannot
  6. otherwise be done without machine code. Full documentation, source
  7. code and a test application is included.
  8. ----------------------------------------------------------------------
  9. FEATURE LIST
  10.  
  11. * Automatic handling of all Series3 operating system messages.
  12.  
  13. * Automatic vectoring of hotkey and menu options to application code.
  14.  
  15. * Simple file handling procedures automatically work from system level
  16.  
  17. * Non-blocking keyboard handling with all key combinations available.
  18.  
  19. * Support for "lazy" screen updating for better responsiveness.
  20.  
  21. * Non-blocking seconds timer with elapsed seconds count.
  22.  
  23. * Non-blocking minutes counter synchronised to real-time clock and
  24.   with elapsed minutes count.
  25.  
  26. * Message masking for simple mode handling.
  27.  
  28. * Automatic error handling mechanisms.
  29.  
  30. * Application exit interlock works from all exit methods.
  31.  
  32. * Dynamic Link Library may be shared amongst multiple applications.
  33.  
  34. * Includes fix for bug in the MENU command documented by PSION.
  35.  
  36. ----------------------------------------------------------------------
  37. OVERVIEW
  38.  
  39. The library provides a main routine which runs, after initialisation,
  40. until the application terminates. This routine invokes callback
  41. routines supplied by the application programmer when system, keyboard
  42. or timer messages occur. The library also supplies a number of
  43. utility routines that can be called from the callback routines.
  44.  
  45. ----------------------------------------------------------------------
  46. FIRST LOOK
  47.  
  48. The distribution archive contains the following files:
  49.  
  50. FRAMELIB.OPO   - Translated framework module.
  51. FRAMELIB.OPL   - Commented framework source code.
  52. FTEST.OPL      - Source code for example & test program.
  53. FRAMELIB.TXT   - This file.
  54.  
  55. To run the example program, first copy FRAMELIB.OPO into an \OPO
  56. directory on your S3. Then copy FTEST.OPL into the \OPL directory,
  57. open it and translate. On completion, install using PSION-I at
  58. the system screen.
  59.  
  60. Note that the sample application uses the OPL files in the OPL
  61. directory an a convenient example. It will not actually open or modify
  62. any files.
  63.  
  64. The test application simply displays messages and parameters as events
  65. occur. Use the [Menu] key to see the available facilities. Try
  66. pressing keys, switching the S3 on and off, opening new files at the
  67. system level etc.
  68.  
  69. Examine the FTEST.OPL application in conjunction with this file to
  70. understand how an application is put together.
  71.  
  72. FRAME.OPL is provided for advanced users only and you would not
  73. normally need to understand this code to put an application together.
  74.  
  75. ----------------------------------------------------------------------
  76. MESSAGES
  77.  
  78. When running, the "fRun:" procedure generates MESSAGES in response to
  79. events from the SERIES 3 operating system. These are in three
  80. categories: KEYBOARD,TIMER and SYSTEM (see below).
  81.  
  82. Each message has a number, which determines which Callback Routine
  83. gets invoked when that event occurs. When the callback routine is
  84. invoked an integer parameter and a string parameter are set (the
  85. parameters are actually the global variables "fParm%" and "fParm$").
  86. The callback routine uses these parameters to decide what to do.
  87.  
  88. Sixteen of the messages are "maskable" - unless these are enabled, the
  89. callback routine will not be invoked. The message mask is set when
  90. "fRun:" is first started and can be changed subsequently by returning
  91. a message from a callback routine. The mask is a bit-map with one bit
  92. set for each message to be enabled. This mask can be assembled by
  93. adding together the values given in the MESSAGE TABLE below.
  94.  
  95. The message handler callbacks return a message number when complete.
  96. This will normally be either an error message (negative) or 0 (null
  97. message) or 100 (exit message). However, the routine can return any
  98. message, including user-defined ones. Care must be taken to avoid
  99. infinite loops such as would happen if a callback routine returned its
  100. own message number.
  101.  
  102. ----------------------------------------------------------------------
  103. KEYBOARD MESSAGES
  104.  
  105. There are five keyboard messages:
  106.  
  107. #4 is invoked when the user presses a hot-key (PSION key with a letter
  108. EG PSION-S). This message is rarely un-masked as there is a special
  109. mechanism for handling individual hot-keys. A special callback can be
  110. provided for each hot-key used in the application. Hotkeys are enabled
  111. and disabled by including or excluding the letter in the hotkey mask.
  112. This mask is set from a parameter when "fRun:" is started and can
  113. subsequently be changed by a callback routine returning either message
  114. #130 or #131. If you use this mechanism, do NOT enable message #4 as
  115. the special callbacks will then not be invoked.
  116.  
  117. #5 is invoked when the user makes a keystroke which generates a
  118. printable character such as "a", "A" or "*". This includes SPACE, but
  119. excludes ENTER and DELETE.
  120.  
  121. #6 is invoked when the user presses one of the "Special" keys such as
  122. "up arrow" "ESC" "ENTER" etc. (see SPECIAL KEY TABLE below).
  123.  
  124. #9 is invoked when the "MENU" key is pressed. The associated callback
  125. would normally bring up a menu system and then return either message
  126. #0 or #4. In the latter case, the parameters would be set by the
  127. callback to the hotkey of the selected option. The framework will then
  128. use the hotkey callback to activate the option as if the hotkey had
  129. been pressed.
  130.  
  131. #10 is invoked when the "HELP" key is pressed.
  132.  
  133. For all keyboard messages there is a special additional parameter in
  134. the global variable "fKmod%". This gives the modifier status at the
  135. time the key was pressed as per the OPL KMOD function. This is
  136. particularly useful for detecting shifted special keystrokes.
  137.  
  138. ----------------------------------------------------------------------
  139. TIMER MESSAGES
  140.  
  141. There are two timers: one generates a message every minute and the
  142. other every second. Only one timer may be active at any time.
  143.  
  144. The timers are started and stopped by masking and unmasking their
  145. respective messages in the usual way. They are synchronised with the
  146. Series-3 clock (i.e. the minute timer message happens just after the
  147. minutes have changed on the clock).
  148.  
  149. The timers continue to run even if the application is in the
  150. background, however they stop when the SERIES-3 switches off. The
  151. message parameter shows how many units of time have been missed when
  152. the SERIES-3 was off, or was tied up with other things. For
  153. stopwatches and similar applications, the parameter should be added to
  154. an accumulator each time the message callback is invoked. This is
  155. important, because the system does not guarantee that the message will
  156. happen every unit of time. Also, the callback may be called with
  157. parameter equal to zero when the timer is synchronising and the
  158. callback must cope with this.
  159.  
  160. ----------------------------------------------------------------------
  161. SYSTEM MESSAGES
  162.  
  163. Messages #1 to #3 are system messages invoked when the operating
  164. system changes the state of the application. Normally they can be left
  165. masked as all normal house keeping is done by the framework.
  166.  
  167. Message #11 is the "Nothing better to do" message. It is invoked when
  168. there is a gap in the stream of other messages just before the
  169. framework suspends the application to await the next message. Un-mask
  170. this to perform low-priority or background processing such as "lazy"
  171. screen updating.
  172.  
  173. Messages #100 and above are not handled by the normal callback
  174. mechanism but may be returned by callback routines to cause the
  175. framework to take appropriate actions.
  176.  
  177. For file-based applications, the "aOpen%:", "aCreate%" and "aClose%"
  178. callbacks must be provided. The framework handles externally driven
  179. file handling using these routines. For application driven file
  180. handling DO NOT call these callbacks directl