Documentation for RPM's Object Viewer, version 0.92 1993 August 21



What is it?



The Object Viewer is a Newton application intended mainly for programmers. It

displays the contents of objects in Newton's memory, and provides several ways

to jump from one object to another.  It is a floating window which is half the

height of the screen, and can therefore be used to examine the activities of

other Newton programs while they are running.



Basic Instructions

==================



- Main list shows up to ten items; each is a frame slot or array element. Tap

on an item to jump to that object.  For binary objects, the display shows 80

bytes of data in hex and ASCII format.



- Top two lines of display show the path taken to get to the current object, the

object's class, memory address, and size (slots/elements/bytes).



- Use the scroll arrows to view more slots, elements, or bytes of the current

object.  If you scroll continuously by holding the pen on the scroll arrow, it

scrolls by larger and larger amounts.



- Tap the Undo button to go back to the object you were looking at before the

recentmost jump.



- Tap the Recent button in the Viewer window to see a list of the ten

most-recently-viewed objects; then tap on one to jump to that object.



- The Home button jumps to the rootView object (the object that is displayed

when the Viewer is opened).



- The Update button updates the display to reflect changes (if any) in the

currently-viewed object.



- The Viewer is nondestructive -- it does not allow you to change any objects in

memory.  In normal operation it will not cause any objects to change except

objects which belong to it, and a few system objects like the undo list.



- The Info icon in the lower left jumps to an object that contains information

about the ObjViewer program (author, copyright, etc.)



Notes, features, oddities, etc:

===============================



- The second line (info line) shows: The object's class, a "@" for modifiable

objects or a "!" for non-modifiable objects, the object's virtual memory

address, and the object's size (bytes, slots, or elements).  For frames, the

info line also indicates the position of the view within the frame, for example

"8/27 slots" to indicate that there are 27 slots and the display currently

starts with slot number 8.



- The title line (the boldface line at the top) shows the "path" that was used to

get to the current object.  For example, after jumping to slot "_Parent", then to

slot "AvailablePrinters", then to array element 1, then to slot "imagingName", 

the title line might say:

              ...ent.AvailablePrinters[1].imagingName

the beginning of the path is cut off because the most recent information is at

the end, and this is usually the most useful.



- When you jump to an object, the name of the slot or element that you chose

gets added to the end of the title line.  However, if your jump takes you to

an object you've visited recently, the title line will display the path that

was used the first time that object was visited.



- If you hold the pen on a scroll arrow for continuous scrolling, it will

scroll in increasingly large jumps.  This allows you to quickly go to a

desired point in a really large binary object.  Of course, it may skip over

the point you're trying to get to; when this happens you have to stop

scrolling for a moment, then start again (it will restart at the original

slow rate).



- If you re-visit an object that you have visited recently, the Object Viewer

shows it at the same scroll position that it had when you left it.



- Most of the data in the notepad, datebook, and names file are not in the

dynamic object memory, and cannot be displayed using the Viewer.  This

information is stored in soups, which are seperate from the object memory and

are compressed.



- ObjViewer trivia #1:  When you tap the "?" icon, it shows a little online

help.  What it's actually doing is visiting an object within its own _proto

frame (this is mainly done to avoid making extra copies of the text into in the

formContext frame, which is what would happen if conventional online help

methods were used.)



- ObjViewer trivia #2:  When you tap the "Recent" button, it shows you the

contents of the "recentList" object in ObjViewer's formContext frame, but

with path titles for labels.  This object does not itself end up in the

recent list, unless you select an item from the recent list and then hit

Undo (to return to the recent list).  When you do this, the recent list is

shown in its "raw" representation, and it is added to the recent list. The

title will be something like "ObjViewer.recentList(@12:34pm)" indicating

that you are visiting an ObjViewer recent list that existed at some time in

the past (the current recent list is now different).  You can visit this

recentList later and use it to get to items that have already disappeared

off the current recentList (but if you really feel you have to do this, let

me know and I'll just make the recentList longer!).



- The hex displays look somewhat ragged, due to the use of a proportional

font (Simple 9 a.k.a. Geneva 9).  There are no monospace fonts on the

Newton and I do not wish to plot characters one at a time for proper

spacing.  Maybe eventually I'll figure out how to get my own font onto the

Newton.



A Guided Tour

=============



This section leads you through a sample Viewer session, showing how it is

useful for Newton developers.  It also serves as a partial introduction to the

organization and function of the more important system objects.  If you've

already done some Newton programming then you probably won't learn anything

new from this section.



We will use the Calculator as an example "target program".  If the Viewer is

open, close it; then open the Calculator and re-open the Viewer (this puts the

Viewer in front).  Relocate them so you can use both easily (I find that

Calculator lower-right and Viewer upper-left works pretty well.)  To drag the

Viewer, grab it by the gray border or anywhere in the top two lines of text.



At the top of the Viewer window is a line that says "GetRoot()".  This line is

referred to as the CURRENT PATH.  It displays the canonical name of the object

currently being viewed, which is the "System Root View" -- the View which

contains everything on the screen.  Programs get this object by calling the

builtin function GetRoot().



The second line says something like "Frame@04406781;0/118 slots"; the numbers

will differ on your Newton.  This is the INFO LINE, and it tells you several

important things about the current object; for now we'll just note that the

current object is a frame and has 118 slots.



Below the info line are ten lines of labels followed by various kinds of

information.  This is the CONTENT SECTION.  Since we are viewing a frame, each

line corresponds to a slot of the frame.  The first ten slots are currently

visible.  Each line contains the name of the slot followed by a colon ":" and

a brief description of what the slot contains.



For example, look at the line that says "calculator: {..12..}" (perhaps with

a different number between the ....'s).  This indicates that the current

object has a slot called "calculator" and that its value is a frame with 12

slots.  (The number of slots will be more if you have performed some

operations on the calculator.)



Select this object by tapping on its line.  The Viewer now changes its display

to show that object.  The current path changes to "GetRoot().calculator", the

numbers in the info line change, and the entire content section changes to

show 10 slots from the calculator frame.



Find the content line which says "paper: [..30..]".  This is an array with 30

elements.  Select it.



Now the display shows the calculator.paper array.  The info line has changed

to "Array@0440A851; 30 elements", indicating that the current object is an

Array and that it has 30 elements.  Unless you have done a lot of

operations on the Calculator since opening it, the content section will

show ten lines of "$" symbols.



Scroll to the end of the paper array by clocking the down arrow three times.

Each time you tap the arrow, the display moves down eight lines (showing

eight new lines and two old lines).



Now use the Calculator a bit; add a few numbers together.  When a few numbers

have scrolled up the calculator's window, tap the "update" button in the Viewer.

The content section will change to reflect changes in the calculator.paper array.

As you can see, this array contains strings representing the current contents of

the calculator's "paper tape".  The Calculator supports scrolling, and it keeps

the last 30 items in this array.  (Note that the Calculator won't scroll right

now because the Viewer is in front, and it gets all of the scroll commands).



Tap on one of the strings. The path will be "GetRoot().calculator.paper[27]"

(with a different number, perhaps).  The content section shows the string's

text followed by the string's representation in memory.  Since the Newton

is a Unicode machine, every character takes two bytes (and in this display,

each byte is shown as two hex digits).  Characters in the ASCII character

set have the same codes as in ASCII, but there is an extra "0" byte in the

high half of each word.



At this point, we're at a "dead end" -- we're looking at an object that has no

slots or elements to select.  The most convenient thing to do this point is to

hit the Undo button, which will take you back to calculator.paper.  Then hit

Undo again to get to GetRoot().calculator.



At this point Undo won't take you any further (try it).  It happens that at this

point we can select the slot called "_Parent" to get back to the GetRoot()

object.  Because the calculator is a child view of the root view, it has a

_Parent slot which points back to the root view.  Try it now if you like.



Another way to get back to the root view is to use the Recent button.  Try it

now.  The Viewer will show a list of the objects you've visited so far.  It will

look something like this:

     Last 4 objects viewed:

     ___________________________________

     GetRoot()

     GetRoot().calculator.paper[28]

     GetRoot().calculator.paper

     GetRoot().calculator

If you have looked at other objects, they too will appear in the list, and if you

have re-visited old objects the order will be different.



The last item in the list is the current object, and the second-to-last item is

the previous object.  Before that the order will vary depending on when you last

visited particular objects.  For now, just select "GetRoot().calculator".



Now look at a floating-point number: find the "value" slot and select it.

The display will now show the value on the Calculator's display and its

representation in memory. Reals in the Newton are stored in 64-bit IEEE

format.



If you enter a different number in the Calculator's display, then tap Update,

the display will not change.  The reason is that the Calculator creates a new

object for the "value" slot each time the value changes.  The ObjViewer still

has a pointer to the old object, so when you tap update the display doesn't

change.  To see the new value, return to GetRoot().calculator (by tapping

Undo) and look at the "value" slot.



If you change the calculator's value several times, and re-visit the value

slot each time, several copies of the value slot get placed in the Viewer's

recent list.  The reason is that each value is a distinct object of type

"Real" in the Newton's memory, and the Viewer is holding them in memory by

keeping them in its recent-list.  This doesn't fill up memory because when

the recent list gets full, the oldest object gets removed from the list. 

When the old "calculator.value" objects get removed in this way, they no

longer have anything pointing to them and the Newton OS deletes them from

memory.



Go back to GetRoot().calculator and find the "base" slot.  Its entry says

"base: SELF {..20..}".  This slot points to GetRoot().calculator itself

(try it -- when you tap it the view doesn't change).  It is common for

Newton frames to contain a pointer to themselves; ObjViewer identifies them

as such.



Here are some examples of other types of objects that you might find

interesting:



A sound:

     GetRoot()._proto._proto.scrollUpSound

The "samplingRate" slot indicates that the sound is to be played at

11,013.22 samples per second.  The "samples" slot contains the actual

digitized sound samples.  (The display is particularly ragged because of

the large number of E and F digits in the hex; see my note in the previous

section).



A font:

     GetRoot()._Parent.fonts._proto.geneva

Newton uses TrueType fonts for on-screen rendering.  The "plainData" slot

contains the TrueType font data, but although its class is "sfnt" it does not

appear to be the same as a Macintosh "sfnt" resource or a Windows TrueType

font.  (This might be related to Unicode.)



An icon:

     GetRoot().trash._proto.icon

The "bits" slot points to the image, and the "mask" slot points to the mask

(analagous to an icon mask on the Macintosh).



A NewtonScript code block:

     GetRoot()._proto.viewSetupChildrenScript

This is an example of a non-generic frame: a frame whose class is not "Frame".

There is a slot called "instructions" which is a non-generic binary object; it

contains 79 bytes of "P-code".  There is a "literals" slot, a non-generic

array, containing 25 literals (constants used by the code).  There is also a

list of arguments and local variables in the "argFrame" slot (in this example

there are no arguments or locals; the three slots _nextArgFrame, _Parent, and

_implementor are always present).



A C function reference:

     GetRoot()._proto._proto.SyncScroll

The "funcPtr" slot is the memory address of the C++ code for the "SyncScroll"

function.  "numArgs" indicates that the function takes 3 arguments.



The Viewer itself:

     GetRoot().extrasDrawer.viewChildren[21]

The number "21" in this path will depend on ObjViewer's position in the

Extras drawer.  You know you've found the right one if the "app" slot is

'ViewerRPMSym.  The "theForm" frame contains the template for the application

(including all the code); it and all of its slots are non-modifiable.  The

"formContext" frame contains the variables.



Newton team members' names:

     GetRoot().theGang._proto.authors

This array contains the text displayed by the Assist "About Newton" Easter egg.



Revision History

================



Version 0.92, 1992 Aug 21 (posted to BCS)



- Fix bug: Undo just after opening Object Viewer would show a NIL object

with no title.



- Fix bug: Recent would say "Last 10 objects viewed:" even when there were

less than 10 items in the list.



- Fix bug: Undo just after selecting an item from the Recent list would

show an old recent list with an incorrect title.  Made it into a feature by

passing an appropriate title to the Undo system.



- When viewing a real, it now shows the real's value along with its hex.



- Scrolling: add "acceleration" feature.



- It no longer takes time to update the view if you scroll up when already at

the top, or down when already at the bottom.



- Add fields to "?" button's display, and point it at the _proto entry to

avoid copying text in memory.





Version 0.9, 1992 Aug 20 (First beta-test version)