A Generic Application

By Jörg Langowski, EMBL, c/o I.L.L, Grenoble, Cedex, France, MacTutor Editorial Board

The Edit window

The Hanoi towers were fun to play with. Today, we'll start doing something 'serious' and develop a template application in NEON, which will eventually develop into the skeleton of a terminal program. In this issue, we'll first set up the object definitions and the appropriate methods that are necessary to handle TextEdit records.

'Application templates' in NEON

The word 'application template' has a somewhat different meaning under NEON than, let's say, in assembly language or C, since NEON provides you with a lot of the event handling support that has to be taken care of explicitly otherwise. In principle, one could setup an application shell - e.g. a window that supports text editing and has the basic File and Edit menus and the appropriate event handlers - in NEON from scratch. One would start by defining windows, controls and menus using only toolbox definitions and the basic Object class to build on. But this would mean reinventing the wheel and not taking advantage of the features that are already built into NEON. If any of these standard definitions will ever have to be changed, one can even do that because their source code is part of the NEON system.

So for the time being we will use the classes that are already provided by the NEON system. This way the main 'event loop' becomes very simple; the NEON manual suggests to handle almost all the important events by just saying

begin   key  key: xywindow again 

with an arbitrary window xywindow, or even

begin 
 key key: [ frontwindow ] again 

where frontwindow generates the address of the frontmost window object (by calling FrontWindow from the toolbox).

This will be the complete event loop, the reason being that key waits for a keystroke, which is the thing that will in most cases have to be processed separately by your application. While waiting, key automatically tracks all mouse events and associated window activate and update events. The routines that handle these events are defined separately by the actions: method for windows and controls, and in the menu definition file for menus.

Events other than keystrokes detected by key will be sent to the appropriate (window, control, menu) objects, and theses objects will take care of handling them as the action words have been set up accordingly. [Important note: as far as I have found out on my review NEON 1.0 version, even Control- keystrokes will not cause key to exit but will be sent to the menu bar].

Fig. 1 gives an illustration of the action of key.

This is the structure that most NEON programs should make use of since different window and control objects can be defined in a very straightforward way, very independent of one another.

This is also how we are going to proceed to develop a simple NEON application: a TextEdit window that can be grown and dragged, which will accept text from the keyboard and whose text may be copied, cut and pasted through an Edit menu. A File menu will have Quit as its only option.

There is one problem, however, with using key as defined in NEON when one calls the TextEdit routines. The convention is that you call TEIdle in the main event loop as often as possible so that the blinking caret is updated. key does not do this, so when manipulating a TextEdit record in the window one has to write a loop that is cycled often enough and does not stop at key waiting for a keystroke.I'll come back to this issue after having described the class definitions.

The editwindow class

We will first define the main object in our application, which is a window that contains a vertical scroll bar and has a TE record associated with it. Other than in MacForth, there is no predefined space in a window record to hold a pointer of a TE record, nor are there predefined routines that will do the editing on such a window. This is good and bad; bad since it requires work on the part of the programmer and good because we can define the object exactly the way we want it to be and know the structure of the methods that we associated with it.

Refer to Listing 1 for our program example. An editwindow is defined as an object of the superclass ctlwindow, and you will have to load ctl, ctlwind and vscroll into the NEON system before loading this definition. Associated with this window are the instance variables text, TEscrollbar and position. text is a TErecord object, and we'll get to its definition soon. TEscrollbar is a variable that holds the address of a vscroll object (for reasons that are explained in detail in the NEON manual, a control cannot be an instance variable itself).

position will be used to keep track of the current position within the text. The reason why this has to be done is that after a call to TEcaltext (recalculate line positions after resizing the destRect), the start position of the text put into the destination rectangle is reset to the beginning of the text. However, the value of the vertical scroll bar will not have been reset, and it will show a position somewhere within the edited text while what is actually displayed is the very beginning.

So there remain two possibilities: after recalculating the text, one can either reset the control to zero or scroll the newly aligned text back to the position given by the scroll bar. We choose the latter alternative here.

In our example, the scroll bar will not reflect the relative position in the text, but rather the absolute position counted in pixels from the beginning (mainly because of my laziness to write a separate scaling routine). The scroll bar range will be 0 to 2000, and the up/down arrows will change the control by 10 on every click, while page up/page down will change it by 100.

When the editwindow object is created, a vertical scroll bar is generated on the heap and its address put into the instance variable. The text edit record has to be initialized separately using the teinit: method

Behavior of the Edit Window

The function of the edit window is very largely determined by the draw: method. This method will be called automatically whenever an update event for that window occurs, e.g. after dragging or resizing.

In our case, the view and destination rectangles of the TE record will always be equal to the content region of the window minus the rectangle containing the vertical scroll bar. draw: first calculates the new scroll bar and puts it in the right position into the window (which might have been resized). Then the window itself is drawn by calling the draw: method of the superclass. For displaying the text, the new view and destination rectangles are then calculated by the getcont: method, the text is recalculated and scrolled into the position given by the value of the scroll bar.

Thereafter the window contents are updated by setting the whole of the content region invalid and doing a TEupdate between calls to BeginUpdate and EndUpdate.

A redefinition of the draw: method of a window is one way to define its update behavior. The other possibility, also given in the NEON manual, is by putting the cfa of a colon definition into the draw vector using the actions: method. After playing around with this feature for a while and getting bombed down quite a few times, I looked into the source code of draw: to see what had gone wrong.

The logic behind NEONs built-in draw: method is the following: First, the window is redrawn doing the appropriate updating between calls to BeginUpdate and EndUpdate. The last statement in the method definition is exec: draw. This jumps to the user-defined action vector, then exits the method. The code that you put into your action vector would then consist of updating code sandwiched between BeginUpdate and EndUpdate. Of course, if you make the mistake to send draw: to your window from within this code, you will get an infinite recursion which you probably never wanted in the first place.... therefore the bomb.

The updating that we do here manipulates the windows own TextEdit record. Since we prefer to hide this from the outside world as much as possible, we redefine draw: within the window rather than by changing the action vector.

Editing - the TErecord class

The actual text editing methods such as cut, copy, paste, handling of mouse clicks and scrolling are just passed through by the edit window to its own TE record, where they have been defined. This leads to the definition of the TErecord class.

A NEON TErecord object constitutes the interface to the Toolbox's TextEdit record (whose structure has been explained in several different columns in MacTutor, includingh this one). Just to refresh your mind, this data structure contains a handle to the text to be displayed, which is stored separately, and information which is necessary to display the text. The TErecord definition provides you with methods to access most of the fields in the TextEdit record, change them and do editing operations on the text.

Most of the methods in the TErecord are simple calls of the corresponding toolbox routines with the handle of the TE record as the top of stack parameter. In some cases, since stack items are always 32-bit parameters in NEON, it was necessary to use pack and unpack. For instance, NEON gets the coordinates of rect objects as separate 32-bit numbers on the stack, with the order being { left top right bottom }. The methods in our example that extract the coordinates of the view and destination rectangles out of the TextEdit record will of course leave them on the stack in this format, so they may be passed along to other rect objects.

A new TextEdit record is assigned to a TErecord object by sending a new: message to it, parameters on the stack being a zero (to hold the TEnew function result) and pointers to the destination and viev rectangles. Note that you will have to call this method from outside using absolute addresses for the rect objects, just as the NEON manual tells you.

The handle to the TextEdit record returned by TENew is stored in the instance variable TEhandle, the other instance variable is chars, which is used as an internal handle to the text being edited.

Menu definitions

There will be - in addition to the apple menu - two menus in our mini-application, File and TEmenu. Menus are set up in NEON in a way very different from MacForth, in that the menu text is contained in a separate text file and read in during setup of your application. This is very similar to the resource file concept but not quite the same. Differences are:

- the word that is executed upon selection of a menu item is given in the menu text file;

- control key handling is automatic and does not need do be taken into account by the application explicitly. All one has to do is to specify the control key in the menu definition text, and the menu item will be selected when this key is pressed.

One consequence of the inclusion of a menu item's action word in the menu text file is that this word has to be known to the NEON system when the application is loaded. This means that when you install an application in the way the NEON manual describes, you cannot use any of the words of the NEON kernel as menu action words. After installing the NEON kernel, these words cannot be found in the dictionary anymore, so the menu could not be loaded. So if you want to use e.g. bye as one of the selections in a menu, you would have to write a small 'interface' such as

: ciao bye ;

in your application. ciao would be known even to an installed NEON system, whereas bye would not.

The texts used for the menus here are given in listing 2.

Action words for controls and windows

Control and Window action words are put into the respective objects by executing the actions: method. For a vertical scroll bar, 5 parameters are expected which are the handlers for the up, down, page up, page down and thumb regions of the bar, and for the window we need 4 cfas of the close, activate, update and content-click handlers.

These words are defined in the example, and their action vectors are initialized by two words initctl and initwind, which are called from the application's main body.

Main event loop

start.edit is the event loop. We emulate what is done by key automatically and write an endless loop in which:

- TEIdle is called periodically so that the caret is blinking normally,

- the cursor is adjusted to show an I-beam in the content area minus scroll bar of the window and the northwest arrow otherwise,

- events are tracked by next: fevent and keys are transferred to the editing window. Other events will be taken care of automatically by the NEON system. (Only key down events return from next: fevent with a true result).

Starting up the application

main starts up the application. The NEON window is closed, the menus, editing window and controls set up, some initial text put into the TErecord and the editing loop started. We will continue this example in the next issue to see how text is transferred to/from the scrap and how the serial port can be interfaced to this editing window.

Closing Remark - making a stand-alone application (?????)

I tried to make a stand-alone application from this program by applying the strategy that is proposed in the NEON manual, executing

finalsave TE.DEMO main ciao

and then clicking the TE.DEMO icon from the desktop. This did not give successful results, no matter what I tried I got a #2 bomb. This seems to happen at the point where new: [ obj: TEscrollbar ] is called from the method initscroll: in editwindow. This works perfectly when NEON is called up in the normal way and the example loaded thereafter. Trying to do this in a stand-alone NEON application gives the bomb.

I have not figured out more about this error message, except that I sometimes (in a seemingly irreproducible way) get the same error message when trying to built the grdemo example on the NEON source disk. When this column is in print, I will probably have an answer from Kriya systems that solves my problems.

Stay tuned till next time. MacForth purists don't cancel your subscriptions yet, you won't be forgotten.

Listing 1: Text Edit example 
\ application template example for MT V2#3 
\ (c) J. Langowski 1985 for MacTutor 

:class TErecord <super object
    handle TEhandle
    handle chars
    
    :M new:      call TEnew  put: TEhandle ;M
    :M release:  
 get: TEhandle call TEDispose  release: TEhandle ;M
    :M setdest:  
 pack ptr: TEhandle 4+ ! pack ptr: TEhandle !  ;M
    :M getdest:  ptr: TEhandle @ unpack 
 ptr: TEhandle 4+ @ unpack ;M
    :M setview:  pack ptr: TEhandle 12 + ! 
 pack ptr: TEhandle 8+ !  ;M
    :M getview:  ptr: TEhandle 8+ @ unpack 
 ptr: TEhandle 12 + @ unpack ;M
    
    :M getheight: ptr: TEhandle 24 + w@ ;M
    :M setheight: ptr: TEhandle 24 + w! ;M
    :M getfont: ptr: TEhandle 74 + w@ ;M
    :M setfont: ptr: TEhandle 74 + w! ;M
    :M getface: ptr: TEhandle 76 + w@ ;M
    :M setface: ptr: TEhandle 76 + w! ;M
    :M getmode: ptr: TEhandle 78 + w@ ;M
    :M setmode: ptr: TEhandle 78 + w! ;M
    :M getsize: ptr: TEhandle 80 + w@ ;M
    :M setsize: ptr: TEhandle 80 + w! ;M
    :M setcr:   ptr: TEhandle 72 + w! ;M
    :M recalc: get: TEhandle  call TEcaltext ;M
    :M update: getdest: self put: temprect
 abs: temprect  get: TEhandle  call TEupdate ;M
    :M key:    get: TEhandle  call TEkey ;M
    :M cut:    get: TEhandle  call TEcut ;M
    :M copy:   get: TEhandle  call TEcopy ;M
    :M paste:  get: TEhandle  call TEpaste ;M
    :M delete: get: TEhandle  call TEdelete ;M
    :M insert: get: TEhandle  call TEinsert ;M
    :M idle:   get: TEhandle  call TEidle ;M
    :M just:   get: TEhandle  call TEsetjust ;M
    :M click:  get: TEhandle  call TEclick ;M
    :M act:    get: TEhandle  call TEactivate ;M
    :M deact:  get: TEhandle  call TEdeactivate ;M
    :M scroll: pack get: TEhandle  call TEscroll ;M
    :M setbase: ptr: TEhandle 26 + w! ;M
    :M gettext: 0 get: TEhandle call TEgettext 
                put: chars  ptr: chars  ;M
    :M settext: swap +base swap get: TEhandle  
 call TEsettext ;M

;class

: calc.scroll.length { l t r b -- }  l t  b t - ;

:class editwindow <super ctlwind
    TErecord text
    var TEscrollbar
    int position

    :M teinit: new:    text ;M
    :M settext: settext: text ;M
    :M terec:  addr:   text ;M
    :M key:    key:    text ;M 
    :M idle:   idle:   text ;M
    :M act:    act:    text ;M
    :M deact:  deact:  text ;M
    :M click:  click:  text ;M
    :M cut:    cut:    text ;M
    :M copy:   copy:   text ;M
    :M paste:  paste:  text ;M
    :M getcont: getrect: self swap 15 - swap ;M
    :M draw: getvrect: self calc.scroll.length
       16 swap size: [ obj: TEscrollbar ]
             moveto: [ obj: TEscrollbar ] draw: super 
 getcont: self setdest: text  
 getcont: self setview: text recalc: text  
 0 get: [ obj: TEscrollbar ] -1 * scroll: text
        getrect: self put: temprect 
 abs: temprect call invalrect
        (abs) call beginupdate  update: text 
 (abs) call endupdate ;M
    :M release: release: text dispose: TEscrollbar ;M
    :M setcr:  setcr:  text ;M
    :M showscr: show: [ obj: TEscrollbar ] ;M
    :M classinit: heap> Vscroll put: TEscrollbar ;M
    :M initscroll: getvrect: self calc.scroll.length 
       addr: self new: [ obj: TEscrollbar ] ;M
    :M scroll: 
 dup +: position 0 swap -1 * scroll: text ;M
    :M adjust: get: [ obj: TEscrollbar ] 
 get: position - scroll: self ;M
    :M getscr: obj: TEscrollbar ;M
;class  

rect edw
rect edest  rect eview
50 50 400 250 put: edw
5 5 380 240 put: edest  get: edest put: eview

editwindow mytext

: myact act: mytext ;
: mydeact release: mytext bye ;
: mycont 
  where: fevent g->l false makeint click: mytext  ;
: initwind <[ 4 ]> 'cfas mydeact myact null mycont
  actions: mytext ;

: inup get: [ getscr: mytext ]  
  10 - put: [ getscr: mytext ] adjust: mytext ;
: indn get: [ getscr: mytext ]  
  10 + put: [ getscr: mytext ] adjust: mytext ;
: pgup get: [ getscr: mytext ] 
  100 - put: [ getscr: mytext ] adjust: mytext ;
: pgdn get: [ getscr: mytext ] 
  100 + put: [ getscr: mytext ] adjust: mytext ;
: thmb adjust: mytext ;
: initctl <[ 5 ]> 'cfas inup indn pgup pgdn thmb 
           actions: [ getscr: mytext ] ;

: adjust.cursor word0 where: themouse pack 
  getcont: mytext put: temprect abs: temprect 
  call ptinrect word0 
  if ibeamcurs else call initcursor then ;
             
: start.edit begin idle: mytext  adjust.cursor
                   next: fevent 
                   if drop 255 and makeint  key: mytext then 
                 again ;

: cut cut: mytext ;
: copy copy: mytext ;
: paste paste: mytext ;

: ciao bye ;
  
3 menu TEmenu 
1 menu filmen
 
: main  close: fwind " TEmenu.txt" getmtxt 
    edw " Test Edit Window" docwind true true 
                                           new: mytext  initwind  
    call teinit  0 abs: edest abs: eview  teinit: mytext
    32 32 500 300 true setgrow: mytext
    10 10 500 300 true setdrag: mytext
    0 setcr: mytext  initscroll: mytext  initctl
    " Text Edit Window, example MacTutor V2#3 
        (c) 1985 J. Langowski"   settext: mytext
    0 2000 putrange: [ getscr: mytext ]
    select: mytext  set: mytext  start.edit
;
Listing 2: Menu texts used by the example

Put these menus into the file "TEmenu.txt".

APPLEMEN  1
  "$14" 
    "About Neon™..." about
    "(___________"  null
    "RES"  DRVR   \  get desk accy names
    "\\\"  
FILMEN  256
  "File"
     "Quit"   ciao
     "\\\"
TEMENU 261
  "TEMenu"
     "Cut/D" cut
     "Copy/F" copy
     "Paste/G" paste
     "\\\"
xxx