home *** CD-ROM | disk | FTP | other *** search
/ MacFormat 1995 August / macformat-027.iso / mac / Portables / Newton / Dev / ObjView092Src folder / ObjViewer 0.92 README < prev    next >
Encoding:
Text File  |  1993-08-22  |  14.9 KB  |  310 lines  |  [TEXT/R*ch]
  1. Documentation for RPM's Object Viewer, version 0.92 1993 August 21
  2.  
  3. What is it?
  4.  
  5. The Object Viewer is a Newton application intended mainly for programmers. It
  6. displays the contents of objects in Newton's memory, and provides several ways
  7. to jump from one object to another.  It is a floating window which is half the
  8. height of the screen, and can therefore be used to examine the activities of
  9. other Newton programs while they are running.
  10.  
  11. Basic Instructions
  12. ==================
  13.  
  14. - Main list shows up to ten items; each is a frame slot or array element. Tap
  15. on an item to jump to that object.  For binary objects, the display shows 80
  16. bytes of data in hex and ASCII format.
  17.  
  18. - Top two lines of display show the path taken to get to the current object, the
  19. object's class, memory address, and size (slots/elements/bytes).
  20.  
  21. - Use the scroll arrows to view more slots, elements, or bytes of the current
  22. object.  If you scroll continuously by holding the pen on the scroll arrow, it
  23. scrolls by larger and larger amounts.
  24.  
  25. - Tap the Undo button to go back to the object you were looking at before the
  26. recentmost jump.
  27.  
  28. - Tap the Recent button in the Viewer window to see a list of the ten
  29. most-recently-viewed objects; then tap on one to jump to that object.
  30.  
  31. - The Home button jumps to the rootView object (the object that is displayed
  32. when the Viewer is opened).
  33.  
  34. - The Update button updates the display to reflect changes (if any) in the
  35. currently-viewed object.
  36.  
  37. - The Viewer is nondestructive -- it does not allow you to change any objects in
  38. memory.  In normal operation it will not cause any objects to change except
  39. objects which belong to it, and a few system objects like the undo list.
  40.  
  41. - The Info icon in the lower left jumps to an object that contains information
  42. about the ObjViewer program (author, copyright, etc.)
  43.  
  44. Notes, features, oddities, etc:
  45. ===============================
  46.  
  47. - The second line (info line) shows: The object's class, a "@" for modifiable
  48. objects or a "!" for non-modifiable objects, the object's virtual memory
  49. address, and the object's size (bytes, slots, or elements).  For frames, the
  50. info line also indicates the position of the view within the frame, for example
  51. "8/27 slots" to indicate that there are 27 slots and the display currently
  52. starts with slot number 8.
  53.  
  54. - The title line (the boldface line at the top) shows the "path" that was used to
  55. get to the current object.  For example, after jumping to slot "_Parent", then to
  56. slot "AvailablePrinters", then to array element 1, then to slot "imagingName", 
  57. the title line might say:
  58.               ...ent.AvailablePrinters[1].imagingName
  59. the beginning of the path is cut off because the most recent information is at
  60. the end, and this is usually the most useful.
  61.  
  62. - When you jump to an object, the name of the slot or element that you chose
  63. gets added to the end of the title line.  However, if your jump takes you to
  64. an object you've visited recently, the title line will display the path that
  65. was used the first time that object was visited.
  66.  
  67. - If you hold the pen on a scroll arrow for continuous scrolling, it will
  68. scroll in increasingly large jumps.  This allows you to quickly go to a
  69. desired point in a really large binary object.  Of course, it may skip over
  70. the point you're trying to get to; when this happens you have to stop
  71. scrolling for a moment, then start again (it will restart at the original
  72. slow rate).
  73.  
  74. - If you re-visit an object that you have visited recently, the Object Viewer
  75. shows it at the same scroll position that it had when you left it.
  76.  
  77. - Most of the data in the notepad, datebook, and names file are not in the
  78. dynamic object memory, and cannot be displayed using the Viewer.  This
  79. information is stored in soups, which are seperate from the object memory and
  80. are compressed.
  81.  
  82. - ObjViewer trivia #1:  When you tap the "?" icon, it shows a little online
  83. help.  What it's actually doing is visiting an object within its own _proto
  84. frame (this is mainly done to avoid making extra copies of the text into in the
  85. formContext frame, which is what would happen if conventional online help
  86. methods were used.)
  87.  
  88. - ObjViewer trivia #2:  When you tap the "Recent" button, it shows you the
  89. contents of the "recentList" object in ObjViewer's formContext frame, but
  90. with path titles for labels.  This object does not itself end up in the
  91. recent list, unless you select an item from the recent list and then hit
  92. Undo (to return to the recent list).  When you do this, the recent list is
  93. shown in its "raw" representation, and it is added to the recent list. The
  94. title will be something like "ObjViewer.recentList(@12:34pm)" indicating
  95. that you are visiting an ObjViewer recent list that existed at some time in
  96. the past (the current recent list is now different).  You can visit this
  97. recentList later and use it to get to items that have already disappeared
  98. off the current recentList (but if you really feel you have to do this, let
  99. me know and I'll just make the recentList longer!).
  100.  
  101. - The hex displays look somewhat ragged, due to the use of a proportional
  102. font (Simple 9 a.k.a. Geneva 9).  There are no monospace fonts on the
  103. Newton and I do not wish to plot characters one at a time for proper
  104. spacing.  Maybe eventually I'll figure out how to get my own font onto the
  105. Newton.
  106.  
  107. A Guided Tour
  108. =============
  109.  
  110. This section leads you through a sample Viewer session, showing how it is
  111. useful for Newton developers.  It also serves as a partial introduction to the
  112. organization and function of the more important system objects.  If you've
  113. already done some Newton programming then you probably won't learn anything
  114. new from this section.
  115.  
  116. We will use the Calculator as an example "target program".  If the Viewer is
  117. open, close it; then open the Calculator and re-open the Viewer (this puts the
  118. Viewer in front).  Relocate them so you can use both easily (I find that
  119. Calculator lower-right and Viewer upper-left works pretty well.)  To drag the
  120. Viewer, grab it by the gray border or anywhere in the top two lines of text.
  121.  
  122. At the top of the Viewer window is a line that says "GetRoot()".  This line is
  123. referred to as the CURRENT PATH.  It displays the canonical name of the object
  124. currently being viewed, which is the "System Root View" -- the View which
  125. contains everything on the screen.  Programs get this object by calling the
  126. builtin function GetRoot().
  127.  
  128. The second line says something like "Frame@04406781;0/118 slots"; the numbers
  129. will differ on your Newton.  This is the INFO LINE, and it tells you several
  130. important things about the current object; for now we'll just note that the
  131. current object is a frame and has 118 slots.
  132.  
  133. Below the info line are ten lines of labels followed by various kinds of
  134. information.  This is the CONTENT SECTION.  Since we are viewing a frame, each
  135. line corresponds to a slot of the frame.  The first ten slots are currently
  136. visible.  Each line contains the name of the slot followed by a colon ":" and
  137. a brief description of what the slot contains.
  138.  
  139. For example, look at the line that says "calculator: {..12..}" (perhaps with
  140. a different number between the ....'s).  This indicates that the current
  141. object has a slot called "calculator" and that its value is a frame with 12
  142. slots.  (The number of slots will be more if you have performed some
  143. operations on the calculator.)
  144.  
  145. Select this object by tapping on its line.  The Viewer now changes its display
  146. to show that object.  The current path changes to "GetRoot().calculator", the
  147. numbers in the info line change, and the entire content section changes to
  148. show 10 slots from the calculator frame.
  149.  
  150. Find the content line which says "paper: [..30..]".  This is an array with 30
  151. elements.  Select it.
  152.  
  153. Now the display shows the calculator.paper array.  The info line has changed
  154. to "Array@0440A851; 30 elements", indicating that the current object is an
  155. Array and that it has 30 elements.  Unless you have done a lot of
  156. operations on the Calculator since opening it, the content section will
  157. show ten lines of "$" symbols.
  158.  
  159. Scroll to the end of the paper array by clocking the down arrow three times.
  160. Each time you tap the arrow, the display moves down eight lines (showing
  161. eight new lines and two old lines).
  162.  
  163. Now use the Calculator a bit; add a few numbers together.  When a few numbers
  164. have scrolled up the calculator's window, tap the "update" button in the Viewer.
  165. The content section will change to reflect changes in the calculator.paper array.
  166. As you can see, this array contains strings representing the current contents of
  167. the calculator's "paper tape".  The Calculator supports scrolling, and it keeps
  168. the last 30 items in this array.  (Note that the Calculator won't scroll right
  169. now because the Viewer is in front, and it gets all of the scroll commands).
  170.  
  171. Tap on one of the strings. The path will be "GetRoot().calculator.paper[27]"
  172. (with a different number, perhaps).  The content section shows the string's
  173. text followed by the string's representation in memory.  Since the Newton
  174. is a Unicode machine, every character takes two bytes (and in this display,
  175. each byte is shown as two hex digits).  Characters in the ASCII character
  176. set have the same codes as in ASCII, but there is an extra "0" byte in the
  177. high half of each word.
  178.  
  179. At this point, we're at a "dead end" -- we're looking at an object that has no
  180. slots or elements to select.  The most convenient thing to do this point is to
  181. hit the Undo button, which will take you back to calculator.paper.  Then hit
  182. Undo again to get to GetRoot().calculator.
  183.  
  184. At this point Undo won't take you any further (try it).  It happens that at this
  185. point we can select the slot called "_Parent" to get back to the GetRoot()
  186. object.  Because the calculator is a child view of the root view, it has a
  187. _Parent slot which points back to the root view.  Try it now if you like.
  188.  
  189. Another way to get back to the root view is to use the Recent button.  Try it
  190. now.  The Viewer will show a list of the objects you've visited so far.  It will
  191. look something like this:
  192.      Last 4 objects viewed:
  193.      ___________________________________
  194.      GetRoot()
  195.      GetRoot().calculator.paper[28]
  196.      GetRoot().calculator.paper
  197.      GetRoot().calculator
  198. If you have looked at other objects, they too will appear in the list, and if you
  199. have re-visited old objects the order will be different.
  200.  
  201. The last item in the list is the current object, and the second-to-last item is
  202. the previous object.  Before that the order will vary depending on when you last
  203. visited particular objects.  For now, just select "GetRoot().calculator".
  204.  
  205. Now look at a floating-point number: find the "value" slot and select it.
  206. The display will now show the value on the Calculator's display and its
  207. representation in memory. Reals in the Newton are stored in 64-bit IEEE
  208. format.
  209.  
  210. If you enter a different number in the Calculator's display, then tap Update,
  211. the display will not change.  The reason is that the Calculator creates a new
  212. object for the "value" slot each time the value changes.  The ObjViewer still
  213. has a pointer to the old object, so when you tap update the display doesn't
  214. change.  To see the new value, return to GetRoot().calculator (by tapping
  215. Undo) and look at the "value" slot.
  216.  
  217. If you change the calculator's value several times, and re-visit the value
  218. slot each time, several copies of the value slot get placed in the Viewer's
  219. recent list.  The reason is that each value is a distinct object of type
  220. "Real" in the Newton's memory, and the Viewer is holding them in memory by
  221. keeping them in its recent-list.  This doesn't fill up memory because when
  222. the recent list gets full, the oldest object gets removed from the list. 
  223. When the old "calculator.value" objects get removed in this way, they no
  224. longer have anything pointing to them and the Newton OS deletes them from
  225. memory.
  226.  
  227. Go back to GetRoot().calculator and find the "base" slot.  Its entry says
  228. "base: SELF {..20..}".  This slot points to GetRoot().calculator itself
  229. (try it -- when you tap it the view doesn't change).  It is common for
  230. Newton frames to contain a pointer to themselves; ObjViewer identifies them
  231. as such.
  232.  
  233. Here are some examples of other types of objects that you might find
  234. interesting:
  235.  
  236. A sound:
  237.      GetRoot()._proto._proto.scrollUpSound
  238. The "samplingRate" slot indicates that the sound is to be played at
  239. 11,013.22 samples per second.  The "samples" slot contains the actual
  240. digitized sound samples.  (The display is particularly ragged because of
  241. the large number of E and F digits in the hex; see my note in the previous
  242. section).
  243.  
  244. A font:
  245.      GetRoot()._Parent.fonts._proto.geneva
  246. Newton uses TrueType fonts for on-screen rendering.  The "plainData" slot
  247. contains the TrueType font data, but although its class is "sfnt" it does not
  248. appear to be the same as a Macintosh "sfnt" resource or a Windows TrueType
  249. font.  (This might be related to Unicode.)
  250.  
  251. An icon:
  252.      GetRoot().trash._proto.icon
  253. The "bits" slot points to the image, and the "mask" slot points to the mask
  254. (analagous to an icon mask on the Macintosh).
  255.  
  256. A NewtonScript code block:
  257.      GetRoot()._proto.viewSetupChildrenScript
  258. This is an example of a non-generic frame: a frame whose class is not "Frame".
  259. There is a slot called "instructions" which is a non-generic binary object; it
  260. contains 79 bytes of "P-code".  There is a "literals" slot, a non-generic
  261. array, containing 25 literals (constants used by the code).  There is also a
  262. list of arguments and local variables in the "argFrame" slot (in this example
  263. there are no arguments or locals; the three slots _nextArgFrame, _Parent, and
  264. _implementor are always present).
  265.  
  266. A C function reference:
  267.      GetRoot()._proto._proto.SyncScroll
  268. The "funcPtr" slot is the memory address of the C++ code for the "SyncScroll"
  269. function.  "numArgs" indicates that the function takes 3 arguments.
  270.  
  271. The Viewer itself:
  272.      GetRoot().extrasDrawer.viewChildren[21]
  273. The number "21" in this path will depend on ObjViewer's position in the
  274. Extras drawer.  You know you've found the right one if the "app" slot is
  275. 'ViewerRPMSym.  The "theForm" frame contains the template for the application
  276. (including all the code); it and all of its slots are non-modifiable.  The
  277. "formContext" frame contains the variables.
  278.  
  279. Newton team members' names:
  280.      GetRoot().theGang._proto.authors
  281. This array contains the text displayed by the Assist "About Newton" Easter egg.
  282.  
  283. Revision History
  284. ================
  285.  
  286. Version 0.92, 1992 Aug 21 (posted to BCS)
  287.  
  288. - Fix bug: Undo just after opening Object Viewer would show a NIL object
  289. with no title.
  290.  
  291. - Fix bug: Recent would say "Last 10 objects viewed:" even when there were
  292. less than 10 items in the list.
  293.  
  294. - Fix bug: Undo just after selecting an item from the Recent list would
  295. show an old recent list with an incorrect title.  Made it into a feature by
  296. passing an appropriate title to the Undo system.
  297.  
  298. - When viewing a real, it now shows the real's value along with its hex.
  299.  
  300. - Scrolling: add "acceleration" feature.
  301.  
  302. - It no longer takes time to update the view if you scroll up when already at
  303. the top, or down when already at the bottom.
  304.  
  305. - Add fields to "?" button's display, and point it at the _proto entry to
  306. avoid copying text in memory.
  307.  
  308.  
  309. Version 0.9, 1992 Aug 20 (First beta-test version)
  310.