home *** CD-ROM | disk | FTP | other *** search
/ Simtel MSDOS 1992 June / SIMTEL_0692.cdr / msdos / desqview / api_exam.arc / ASSEMBLY.DOC < prev    next >
Text File  |  1988-10-01  |  10KB  |  243 lines
  1.                       API Details
  2.  
  3. In order for you to get a feel for the power built-in to each and every
  4. DESQview, we've included a short description about each API command.
  5.  
  6. The DESQview 2.0 API is an objected-oriented interface. The data structures
  7. DESQview uses to represent windows, mailboxes, etc. are called "objects".
  8. A call to the API involves "sending a message" to an object, indicating
  9. which of several operations you want performed on that data structure.
  10. This is referred to as the "send interface". Almost the entire API
  11. consists of sending one of 25 messages to one of 7 different object types.
  12.  
  13. The DESQview 2.0 API also has a non-object-oriented interface called
  14. the "direct call interface". This is the small subset of API functions
  15. that are not, by nature, object oriented or that are convenient alternatives
  16. to the send interface.
  17.  
  18. The DESQview 2.0 API has a concise way of encoding a complete description
  19. of a window so that a single call to the API can create the window,
  20. fill it with the desired information, size and position it on the
  21. display, and define fields that interact with the user. All this is
  22. done using "Window Streams".
  23.  
  24. So that you can interrogate a window for its current contents, position,
  25. etc., the DESQview 2.0 API also has "Query Streams". In fact, any
  26. window parameter that can be set by a Window Stream can be read by
  27. a Query Stream.
  28.  
  29. DESQview calls the portion of itself that interfaces with the user
  30. the "Window Manager". Each time a user presses the DESQ key (normally
  31. the Alt key) and makes a menu selection, it is the Window Manager
  32. that opens, switches, rearranges and closes windows, transfers data,
  33. displays help, or quits DESQview. In order for an application to have
  34. the same power as the user, the DESQview 2.0 API has "Manager Streams".
  35. Manager Streams enable an application to interact with the Window
  36. Manager.
  37.  
  38. Using Manager Streams an application can, for example, ask the Window
  39. Manager to make one of its windows the topmost window in the system,
  40. disallow any resizing of  the window by the user, and even notify
  41. the application if the user tries to close the window. Using Manager
  42. Streams an application can disallow use of the DESQview menu and DESQview
  43. submenus.
  44.  
  45. But, there's still even more to the DESQview 2.0 API. DESQview provides
  46. a comprehensive set of functions for simplifying the job of interfacing
  47. with the user. Instead of dealing with user input a single character
  48. at a time, your application can present entire menus, dialogue boxes,
  49. help screens to DESQview and get back the resulting user input. Common
  50. functions such as cursor control, insertion and deletion of characters,
  51. tracking the mouse, and selection from option lists are performed
  52. by DESQview. DESQview performs these functions under control of a
  53. data structure called the "Field Table".
  54.  
  55. Information about a window's size, position, contents and Field Table
  56. can be combined together into "Panels". Panels can be stored on disk
  57. or in memory for later display. Panels can be constructed manually
  58. or via the DESQview API Panel Design Tool.
  59.  
  60.  
  61. DESQview 2.0 API Commands:
  62.  
  63. Send Interface Commands
  64.  
  65. WINDOW Objects
  66.  
  67. ADDTO     write characters &attributes to a window
  68. AT        position the logical cursor
  69. EOF       return TRUE if cursor is past end window
  70. ERASE     clear a window
  71. FREE      close and free a window or a task
  72. HANDLE    return handle of current task's window
  73. LEN       return # characters/line in logical window
  74. NEW       create a new window or task
  75. OPEN      fill a window with a given character
  76. READ      read the next logical line from a window
  77. READN     read the next n characters/attributes
  78. REDRAW    redraw a window
  79. SIZEOF    return total # characters/logical window
  80. SUBFROM   write attributes to a window
  81. WRITE     write characters and/or command streams
  82.  
  83.  
  84. KEYBOARD Objects
  85.  
  86. ADDTO     set keyboard control flags
  87. CLOSE     close a keyboard object
  88. ERASE     discard all input queued to Keyboard
  89. FREE      free a Keyboard object
  90. HANDLE    return handle of task's default keybd
  91. NEW       create a new Keyboard object
  92. OPEN      attach a Keyboard to a window
  93. READ      get the next input from the Keyboard
  94. SETESC    intercept keystrokes to input fields
  95. SIZEOF    return #  of input buffers queued
  96. STATUS    get the scan code for the last key read
  97. SUBFROM   clear keyboard control flags
  98. WRITE     add input buffer to Keyboard queue
  99.  
  100.  
  101. MAILBOX Objects
  102.  
  103. ADDR      return tender of the last message READ
  104. ADDTO     send a message and status by value
  105. CLOSE     close a Mailbox
  106. ERASE     discard all queued messages
  107. FREE      frees a Mailbox
  108. HANDLE    return handle of task's default mailbox
  109. LOCK      request exclusive access to a resource
  110. NEW       create a new Mailbox
  111. OPEN      open a Mailbox for input
  112. READ      get the next message from the queue
  113. SETNAME   assign a name to a Mailbox
  114. SIZEOF    return the #  of messages in the queue
  115. STATUS    return status of the last message READ
  116. SUBFROM   send a message &status by reference
  117. WRITE     send a message by value with status=0
  118.  
  119.  
  120. OBJECTQ Objects
  121.  
  122. CLOSE     Close an Objectq
  123. ERASE     remove all objects from the queue
  124. HANDLE    return the handle of a task's Objectq
  125. OPEN      open the Objectq
  126. READ      wait for input from any open object
  127. SIZEOF    return the number of objects queued
  128. STATUS    return whether or not  Objectq is open
  129. SUBFROM   remove specific object from queue
  130. WRITE     add an object to the Objectq
  131.  
  132.  
  133. PANEL Objects
  134.  
  135. APPLY     display a particular panel
  136. CLOSE     close a panel object
  137. DIR       return a pointer to the panel directory
  138. FREE      free a panel object
  139. NEW       create a panel object
  140. OPEN      associate panel object with a panel file
  141. SIZEOF    return the # of panels in a panel file
  142. STATUS    verify success of an OPEN or APPLY
  143.  
  144.  
  145. POINTER Objects
  146.  
  147. ADDTO     set pointer control flags
  148. CLOSE     stop taking pointer input
  149. ERASE     discard all pointer messages
  150. FREE      free a Pointer object
  151. GETSCALE  return the current scaling factors
  152. NEW       create a new Pointer object
  153. OPEN      start taking Pointer input for window
  154. READ      wait for the next pointer message
  155. SETSCALE  set the current scaling factors
  156. SIZEOF    return the number of messages queued
  157. STATUS    return the status of the last message
  158. SUBFROM   reset pointer control flags
  159. WRITE     move the pointer to a specified position
  160.  
  161.  
  162. TIMER Objects
  163.  
  164. ADDTO     start a timer for a specified interval
  165. CLOSE     close a Timer object
  166. ERASE     cancel the current timer interval
  167. FREE      free a Timer object
  168. LEN       return time remaining before expiration
  169. NEW       create a new Timer object
  170. OPEN      open a Timer object
  171. READ      wait for the current timer to expire
  172. SIZEOF    return elapsed time since timer started
  173. STATUS    return the status of the Timer object
  174. WRITE     start a timer to end at a specified time
  175.  
  176.  
  177. Direct Call Interface Commands
  178.  
  179. APILEVEL  define minimum API level required
  180. APPNUM    get the current application's number
  181. BEGINC    begin critical region
  182. CSTYLE    use C language style control codes
  183. DBGPOKE   poke debug information onto display
  184. DISPEROR  display an error message window
  185. DVPRESENT determine if DESQview is present
  186. ENDC      end critical region
  187. FINDMAIL  find a mailbox by name
  188. FREEBIT   undefine second-level interrupt handler
  189. GETBIT    define a second-level interrupt handler
  190. GETBUF    get address of a Logical Window Buffer
  191. GETMEM    allocate buffer from System Memory
  192. ISOBJ     determine if a handle is valid
  193. JUSTIFY   turn off/on automatic justification
  194. KMOUSE    control the keyboard mouse
  195. LOCATE    find window at given screen location
  196. NEWPROC   start a new process
  197. OSTACK    switch to task's internal stack
  198. PAUSE     relinquish control to other tasks
  199. PGMINT    interrupt another task
  200. POSTTASK  awaken task by posting its Objectq
  201. POSWIN    position a window on the display
  202. PRINTC    display a character in a window
  203. PUSHKEY   push key into keyboard input stream
  204. PUTMEM    free a buffer allocated by GETMEM
  205. SETBIT    schedule a second-level interrupt handler
  206. SHADOW    get window buffer and start shadowing
  207. SOUND     make a sound
  208. START     start a task that was previously stopped
  209. STOP      stop a task until START is called
  210. UPDATE    update a portion of a window
  211. USTACK    switch off task's internal stack
  212.  
  213.  
  214. Window Stream Commands
  215.  
  216. 00 to 9F  print strings (attributes,characters,blanks) to window
  217. A0 to CF  change size/ position of a window
  218. D0 to DF  set options for appearance of window:
  219.           frames, color, show/hide window, display of control characters
  220. E0 to EF  perform immediate actions:
  221.           clearing, scrolling, recoloring, redrawing window;
  222.           create new windows &repeat command sequences
  223. F0 to FF  define, read, write fields within window.
  224.  
  225.  
  226. Query Stream Commands
  227.  
  228. same as Window Stream commands
  229.  
  230.  
  231. Manager Streams
  232.  
  233. 00 to 3F  Allows specific DESQview commands:
  234.           move & resize window, scroll data, hide, rearrange program,
  235.           suspend application, display DESQview menu
  236. 40 to 71  notify application on specific DESQview commands.
  237. 84 to 8B  specify environment of window:
  238.           suspend application when it is in background,
  239.           set application's asynchronous notification.
  240. AE to BF  enable/disable DESQview extensions.
  241. C0 to FF  reorder, hide, unhide, suspend resume
  242.           applications.
  243.