Volume Number:		4
Issue Number:		5
Column Tag:		Hyperhat™

PopUpMenus in HyperTalk

By Joseph Bergin, Professor, Marist College, NY

When Hypercard first appeared it wasn’t possible to include user defined menus in your stacks. While waiting for my Hypercard developers kit to arrive from APDA I decided to experiment and to see what could be done without resorting to XFCN’s and XCMD’s. The result of my early trials is shown in Figure 1. It looks similar to a menu bar except that I placed it on the top of a “card” instead of the top of the window. Actually what you see is a collection of invisible labeled buttons drawn across the top of a card and not an actual menu bar.

In Smalltalk a popup menu is a menu selection device which appears (pops up) when you click the mouse button on certain screen areas. These areas do not need to be anywhere special, and they do not need to be labeled. You select an option by clicking (not releasing) on one of the choices. For example the main control window pops up when you click on the background outside of any window. Another difference between Apple’s pull down menus and Smalltalk’s popups is the fact that popups may stay on the desktop while you work until you actually dismiss them, usually by taking some menu choice. This is similar to Apple’s new tear off menus that made their appearance in Hypercard.

Fig 1.

When you click on one of these buttons a “Popup Menu” appears. If we click on the “Apple” we get Figure 2. This popup is actually a field. Clicking on the Apple only made it appear. As you can see it has four choices presented to the user. If the user clicks on one of these the corresponding action will be taken and the popup will disappear. If you don’t take an action the popup will just sit there while you do other things. The popup will also disappear if you move the browser (cursor) into the window and then move it out again without clicking. This just “dismisses” the popup.

Fig. 2 The HyperCard PopUpMenu

The purpose of popup menus is to provide for those situations in which you want to provide a lot of options for your user but you don’t want to clutter up the cards and/or backgrounds with a lot of buttons which add visual “noise” to the interface. The options may be clustered together in groups and each group may be provided with a single button to call up a popup with the associated choices. There are a number of other solutions to this problem but if used wisely popup menus can be a valuable addition to your Hypercard toolkit.

Actually, what I learned about HyperTalk along the way to creating these popups was as valuable as the popups themselves. In order to make the creation of popups easier I decided to automate the process. This made it unnecessary for me to remember all of the steps that were needed in creation of a popup and its associated button, field, and scripts. The solution was to create a command which creates new popups, but it does so by having a script that writes scripts.

In the Unix world a program which writes other programs is a fairly standard item (YACC and LEX for example) but they seem to be less used in other environments. They are an important development tool, however, and quite easy to do in Hypercard.

The necessary scripts

Before we get into the operation of the ScriptWriter we should look first at the scripts that are needed for the popups to operate correctly.

Suppose that we want to have a popup called “Apple” and we want it to look like the first example in this article. We will need a background button called “Apple” which, when clicked shows a background field called “Apple.” The script to do this is simply

on mouseUp
 show bkgnd field Apple -- at the clickLoc
 -- remove the dashes above for a 
   --nice effect
end mouseUp

which belongs in the script of the “apple” button.

Next we need the background field called by the same name, “Apple.” It has a script to hide itself (target) and one to select and execute the required user choice, which here is done on mouseUp. It also has a special action command (“apple1”, “apple2”, etc.) for each visible line of the field. You may have more action commands than visible lines if you like but they won’t be usable. You can also add new action commands at any time by editing the script, and increasing the number of visible lines in the field and all will be well. Note though that the lockText property of the field will have to be set to true so that Hypercard will be able to recognize a click in the field. The required scripts for this field are:

on mouseLeave
  hide the target
end mouseLeave

on mouseUp
  selectChoice
end mouseUp

on apple1
  open MacWrite
end apple1

on apple2
  open MacPaint
end apple2

on apple3
  open MacProject
end apple3

on apple4
  doMenu “Quit Hypercard”
end apple4

Recall that the second choice on the “Apple menu” was to open Mac Paint. This will happen when we execute the command apple2. The command selectChoice decides that the mouseup happened on line 2 of the popup and dispatched the command apple2.

The small scripts appleN can contain anything that you like. They can show or hide fields or buttons. They can paint. They can do menu commands or open files or stacks. They should be kept short, though, perhaps by defining new commands that they call.

After the field was created and the scripts put into it the lockText was set to false so that its contents could be edited. Then a line was entered into the field for each possible choice, indicating what the choice is. Then the lockText was set to true.

The script for selectChoice is either in the stack script or, perhaps, in the script of the Home Card. This command is called when the user mouses down in a popup. It first computes the line number on which the user clicked the mouse and then executes a command whose name is the same as the name of the field which took the click with the line number appended to it. Thus, if the user clicked on line 3 (selection 3) of a popup whose field was called Apple, this script would execute command apple3, which was shown above.

on selectChoice --used by popups
  put the short name of the target into theName
  get the rect of the target  --field clicked in
  put   item 2 of it into top --top of the rect
  get the textHeight of the  target
  put it into size --how big each line is
  put ((item 2 of the clickLoc) - top + size) ¬  
     div size into lineNumber  
  send ( theName&linenumber) to target
  -- executes the required command
end selectChoice

How to create popups

Since there is so much to do and type for popups it would be nice to automate their creation. The following shows how. It assumes that you want your popup buttons and fields that define the popup to be part of the background, and that if you create a new card from the background you will want the popup to look and behave the same in the new card. None of these assumptions are required and you might experiment to discover the effect of doing it differently. That would require modifying the script for the command “newPopup” which is described next.

To create a new popup called Apple, with four options, in a stack that contains all of these scripts you just type

newPopup Apple,4  

into the message window and the button and field will be created and the required scripts will be put into them. You will then need to resize and place the field in the card, type your menu options into it, lock its text, and edit the action commands to give the effect that you want. The action command skeletons

on Apple1

end Apple1

etc. will be created for you however.

The script that does all this work is shown below. It uses three other commands which are shown later. First, newPopup, which has two parameters, theName and theNumber, locks the screen to speed things up, says that we want to do this stuff to the background, and remembers the current tool so that it can be restored to the user at the end. Next it calls the first auxiliary command to create the button which will bring up the popup. Then the next command creates the popup itself, and the last command in the group adds a script segment to the background so that new Card operations will perform as suggested above. Finally the user’s state is restored and the screen unlocked. [I have done some modifications to the script which will allow a windoid type menu that can be draged around. The original script is intact; there are comments how to modify it. The modifications are in italics. -HyperEd]

on newPopup theName,theNumber
  ---- add next line for watch cursor HyperEd
  -- set cursor to 4
  ----
  
  set lockScreen to true
  set editBkgnd to true
  put the tool into oldTool
  
  
  doNewButton theName
  
  ---- add this line HyperEd
  -- doNewBtnClose theName
  ----
  
  doNewField theName, theNumber
  
  set editBkgnd to false
  
  fixBkgnd theName
  
  choose oldTool
  set lockscreen to false
  
  ---- Return to normal cursor HyperEd
  -- set cursor to 1
  ----
  
end newPopup

[The next section puts in the button for the close box. HyperEd]

--on doNewBtnClose theName    -- This whole procedure HyperEd
-- set editBkgnd to true
doMenu “New Button”
set name of bkgnd button “New Button” to “close”
set style of bkgnd button close to checkbox
set autoHilite of bkgnd button close to true
set showname of bkgnd button close to false
set rect of bkgnd button close to 206,73,226,90
put “on mouseup” into newScript
put “hide bkgnd field” && theName into line 2 of newScript
put “hide bkgnd btn close” into line 3 of newScript
put “set hilite of me to false” into line 4 of newScript
put “set hilite of bkgnd btn” && theName && “to false” ¬
into line 5 of newScript
put “end mouseUp” into line 6 of newScript
set script of bkgnd button close to newScript
--end doNewBtnClose

Next we need to examine the three auxiliary commands that newPopup used. The doNewButton command is the easiest and it illustrates the technique of scripts which write scripts. The first line of it just creates a new button. It doesn’t say background button, but it will be because of the fact that it is called after setting edit bkgnd to true. The next five commands just set some properties of the new button to something convenient. Note that the New Button menu command should set the new button’s name to New Button. If it doesn’t, you will need a script called newButton which just sets the name of “the target” to “New Button”. We will need to do a similar thing for new fields also.

on doNewButton theName
  -- set editBkgnd to true
  doMenu “New Button”
  set name of bkgnd button “New Button” to theName
  
  ---- change next line to shadow HyperEd
  set style of bkgnd button theName to transparent
  ----
  
  ---- change next line to false HyperEd
  set autoHilite of bkgnd button theName to true
  ----
  
  set showname of bkgnd button theName to true
  set rect of bkgnd button theName to 206,70,306,92
  put “on mouseup” into newScript
  put “show bkgnd field” && theName into line 2 of newScript
  
  ---- add these three lines HyperEd
  -- put “show bkgnd btn close” into line 3 of newScript
  -- put “set hilite of bkgnd btn” && theName && “to true”¬
  -- into line 4 of newScript
  ----
  
  put “end mouseUp” into line 5 of newScript
  
  --- This Section added take away “--” HyperEd
  -- put “on mousestilldown” into line 8 of newScript
  -- put “set lockscreen to true” into line 9 of newScript
  -- put “if the visible of bkgnd field” && theName && “is true then” 
¬
  -- into line 10 of newScript
  -- put “set the loc of me to the mouseloc” into line 11 of newScript
  -- put “set the loc of bkgnd btn close to  the mouseh -36, the mousev” 
¬
  -- into line 12 of newScript
  -- put “set the loc of bkgnd field” && theName && “to the mouseh, the 
mousev+93”¬
  -- into line 13 of newScript
  -- put “end if” into line 14 of newScript
  -- put “set lockscreen to false” into line 15 of newScript
  -- put “end mousestilldown” into line 16 of newScript
  ---- End Section HyperEd
  
  set script of bkgnd button theName to newScript
  
  ---- added HyperEd
  -- set hilite of bkgnd btn theName to true
  ----
  
end doNewButton

[These sections ad the script neccessary to move the DragMenu. HyperEd]

The next four commands write a script into the new button. Suppose that the user had originally typed newPopup Apple, 4 into the message window. Then theName is Apple, and theNumber will be 4. After we execute the first of these script writing commands the local variable newScript has a value:

newScript=
 on mouseUp
Then after the second we will have:
newScript=
 on mouseUp
   show bkgnd field Apple

Note that && concatenates strings but leaves appropriate spaces between words. We could easily modify this to show the bkgnd field at the location of the users click. we would just insert

&&  “at the clickLoc”

after the word theName in the second put command. After the next command our script is:

newScript=
 on mouseUp
    show bkgnd field Apple
 end mouseUp

The fourth command copies this to the script of our new button, whose name by now is “Apple” which is the value stored in theName.

The next auxiliary script, doNewField, is a bit more elaborate but not much harder. It needs to know both the name and the number of action commands as these will be written into the script of the field. Again we simply create the field with the doMenu command and then set some of its properties to useful values. The next seven commands then write the mouseUp command for the field. It is left in local variable newScript, as before. After further augmentation we will put it into the script of the field. That will come at the end, just before we end this method.

on doNewField theName, theNumber
  --set editBkgnd to true
  doMenu “New Field”
  set name of bkgnd field “New Field” to theName
  set showlines of bkgnd field theName to true
  
  set style of bkgnd field theName to shadow
  
  
  set textFont of bkgnd field theName to Chicago
  set textSize of bkgnd field theName to 12
  
  ---- This line added HyperEd
  -- set the rect of bkgnd field theName to 206,93,306,256
  ----
  
  ---- Remove the next four lines HyperEd
  put “on mouseleave” into newScript             --
  put “hide the target” into line 2 of newScript --
  put “end mouseleave” into line 3 of newScript  --
  put “ “ into line 4 of newScript               --
  ----
  
  put “on mouseUp” into line 5 of newScript
  put “selectChoice” into line 6 of newScript
  put “end mouseUp” into line 7 of newScript
  
  repeat with x = 1 to theNumber
    put “ “ into line (8 + (x-1) * 4) of newscript
    put “on” && theName&x into  line (9 + (x-1) * 4) of newScript
    put “ “ into line  (10 + (x-1) * 4) of newScript
    put “end” && theName&x into line  (11 + (x-1) * 4) of newScript
  end repeat
  
  set script of bkgnd field theName to newScript
end doNewField

The only new feature here is the repeat command which writes the action command skeletons onto the end of newScript. Note that at this point newScript has seven lines. Each time that the loop body is executed we put four more lines into the script. The first line is blank. The next will say, for our example,

on Apple1 
or “Apple2...” 

depending on the value of x which will vary between 1 and theNumber. This numeric value is appended to theName. The third line is blank again and the fourth gives the end line for the script. Finally we stuff newScript into the field script and quit.

Both of the above scripts were simple in that we were starting fresh with a new object and were writing complete scripts. The last script in this group writes a script segment into the newCard method of the background script for the current background. It assumes that if the background has such a method then it contains a line somewhere with nothing on it but the comment:

 --here--

The modification will be done just above this line. If your background script doesn’t have a newCard method at all then all is well and this script will create one with the required comment line.

on fixBkgnd theName
  get script of bkgnd
  put it into bgscript
  put the number of lines of it into numLines
  put “no” into found
  repeat with x = 1 to numLines
    get line x of bgscript
    if  it  contains  “--here--”  then
    put “yes” into found
    put x into where
    exit repeat
    -- got it
    end if
    end repeat
    get the number of this background
    put it into bknum
    if found = “no” then
    put return & “on newCard “ && return   ¬
 after last line of bgscript
    put return after last line of bgscript
    put “set lockScreen to true” & return ¬
 after last line of bgscript
    put “push card” & return after last line ¬
 of bgscript
    put “go to recent card” & return after ¬
 last line  of bgscript
    put “get bkgnd field” && theName & return ¬ 
 after last line of bgscript
    put “pop card” & return after last line of ¬ 
 bgscript
    put “put it into bkgnd field” &&  theName & ¬
 return after last line of bgscript
    put “--here--” & return after last line ¬ 
 of bgscript
    put “set lockScreen to false” & return ¬
 after last line of bgscript
    put “end newCard” & return ¬
 after last line of bgscript
 else
    put “push card” & return before ¬
 line where of bgscript
    put “go to recent card” & return before ¬
 line where +1 of bgscript
    put “get bkgnd field” && theName & return ¬
 before line where +2 of bgscript
    put “pop card” & return before ¬
 line where +3 of bgscript
    put “put it into bkgnd field” && theName ¬
 & return before line where +4  of bgscript
  end if
  set script of  background bknum to bgscript
end fixBkgnd

The first few lines of this script search for the magic comment --here-- in the script. If it is not found a newCard method with all the required parts is written into the background script copy which is now stored in the local variable bgscript. Not much new here, except that we are appending to an existing script which explains why we include the “returns” at the beginning of various put commands. If the comment was found on line “where” then the required script is inserted just before it. The key part of the script that we write into the variable bgscript, for later stuffing into the background script itself, is just a way to copy the contents of the popup field from the original card into the field for the new card. This will make the popup menu have the same choices as the original card had. We must first go back to the original card, copy the field contents, go back to the new card and then put the contents into the old bkgnd field but from the new card. This requires writing a sequence push-go-get-pop-put into the background script each time we create a new popup, so that the field will get copied each time we create a new card. Simple. Except that the line counting gets a little tricky in modifying the script as we are repeatedly modifying it and changing linecounts.

Anyway, in spite of the complication of the scripts, the use is quite simple. Just type newPopup “someName”, “someNumber” into the message window and a new popup will appear in your stack as if by magic.

You can also refine your popups nicely by modifying the scripts slightly. For example, you might want to have a popup which has different choices in it at different times, or shows the choices in different ways. Here is a script (from the Home Card or the stack script) which puts a check mark at the beginning of a line of a popup. Just remember that lines count between actual “returns” in Hypercard. Auto wrap lines don’t count. Call this from your action command scripts

on wantCheck  fieldName, lineNumber
  -- toggles a checkmark at the beginning of a  
  -- line of a bkgnd field
  get line linenumber of bkgnd field fieldName
  if char 1 of it <> “ ” then
    Put “ ” before it
  else
    delete first char of it
  end if
  put it into line linenumber of L
 bkgnd field fieldName
end wantCheck

Interface guidelines

Popup menus that look like ordinary menus but which behave differently will not be admired by your users. They will be expecting “Press-drag-release” to choose, and if they need to “click-move-click” instead it will only add to their frustration. The solution is to make them look different. That is to say, the buttons which summon the popups should not be arranged in the form of the first card shown in this article, all in a row across the top of the window. Words down the left might be OK. Icons instead of words would probably be acceptable. One of the best methods is to cover part of your background with a large invisible button which has an invisible name as well.

Stack instructions (perhaps summoned by a button press) could explain that options may be chosen by first “clicking near the upper left of the card.” If nothing else is in front of your invisible button (or even if it is painted over by card graphics) your popup will be appear. One of the stacks that I recently built is a multi window editor that is controlled by popups. The next figure is the screen you see when the stack is first opened.

This background of this card is covered by a large button. Any clicking on an area not covered by some other item will cause the popup shown to appear. In the next figure the user has dismissed the instructions and has just clicked on the background. The popup also draws itself at a fixed location, but it could be at the point of the mouse click (in HyperScript this is the ClickLoc).

This stack has another feature that you may choose to implement. One of the popups in it is controlled by clicking on the “filename” field in the upper right, rather than on a button. This field normally contains the name of the file being edited and islocked text, filled in by the scripts.

In operation a card will show the text to be edited. By creating new cards from this background you may have a multi window editor for text files. It is also useful as a note pad.

Be careful with popups that don’t disappear on mouseLeave. They should have at least one “Safe” option among the choices so that the user can make them them just disappear.

You might want to experiment with popups which disappear on mouseLeave as well as on down or up. A combination of Up and Leave is probably best. Note that if the popup disappears at mouseUp you can mouse down and then drag off the popup, and your initial mouseDown will be ignored. This lets your user avoid a choice. This is not possible with a choice at mouseDown.

What you get on this month’s disk

This article is packaged with two stacks. The first is a practice stack to help you learn about popups. It also contains all of the necessary scripts, especially newPopup. The other stack is the simple editor described above that uses popups for its commands. This stack has only one card in it, but by executing “new Card” from the Edit menu you will build yourself a multi window editor for text files. It is also a useful textfile viewer. For this stack to work correctly you will need to paste the newPopup and selectChoice scripts, as well as the auxiliary scripts, either into the Editor stack or into your Home Stack. The latter is preferred so that you can have popups available in all your stacks.

The following figures are screen shots from the popup stack which contains all of these scripts and a few more goodies.

The popup is called Howdy, and its purpose is to call up windows that teach you about popups and how to create them. The first figure in this article is a card from this stack.

When Howdy is clicked it brings up a popup with four choices. Each of these will bring up another window which has information about popups in it.

Line 1 and 2 have been clicked. The popup won’t scoot until the browser leaves it. Thus you may make several choices on the same menu. Did you ever want to do that in standard Mac menus?

The user has clicked in the two windows from before. The popup disappeared, but it was called back and the user clicked on the third line.

The user moved the browser from the popup and it went away. Clicking in the window showing will dispel it as well. Once you get used to fields as menus it is relatively simple to create hierarchical menus. What you need to do is have a script for one of your action commands call up another popup. It is easy to overdo this however, and your users won’t be too happy if every popup calls others. One of the most frustrating features of older computers (pre Macintosh) was having to wade through menu levels when you already knew what you wanted. Ah well, it’s nice that times have changed. Happy Computing.

[Figure 12 Shows the Windoid type DragMenu. The method of scripts making objects is very powerful. As you can see from my additions a different type of menu can be produced. Experiment and see what you can come up with. HyperEd]