StackMorph Tutorial


	links to this page:

StackMorph Tutorial

Last updated at 2:33 am UTC on 9 December 2011

This tutorial is for Squeak version 3.6 (90% of this tutorial, is based on a tutorial by Ted Kaehler, which was from the original demo by Scott Wallace. Scott wrote the code in class StackMorph.)

Updated! for Squeak 4.2. Added some new content and formatted the example to make it a little more readable. I'm not the original author ?, just added to it. – Stephen Smith

The Stack and Card model used by HyperCard is flexible and compelling. A user sees one Card at a time. It is a composite of Card-specific data and objects, over a background. The background gives the Card its "look". There can be multiple backgrounds in a Stack. Cards of different backgrounds can be intermixed and appear in any order.

In Squeak's version of a Stack, we have some additional features:

When many cards use a background field to display text, there is only one set of bulky display objects. Each Card only has the actual text data. This is much more compact than making a new page in a BookMorph for each card.
Each Card is an instance of a Player class. For each named field, there is an instance variable in the card object. The Text objects that hold the data on a card are accessible as regular Smalltalk objects.
Any Card may have objects that are specific to that Card. Any object that has a visible presence in Squeak may be placed on a Card. This gives tremendous variety.

Get the Stack Flap

You may already have the "Stack Tools" flap at the bottom of your screen. If not, click in the empty space to the right to get a World menu. Choose "flaps...". If the menu has check boxes, turn on "Stack Tools". If not, choose "show shared flaps". Then get the menu again and turn on the "Stack Tools".

Create a Stack

Open the "Stack Tools" flap. On the far left is a blank stack. Drag it out onto the screen. This new stack has one card, which has nothing in it. One thing I found confusing was how to resize the stack. To resize the stack, use the card's yellow halo not stack's yellow halo. I don't know why the stack's yellow halo doesn't work for this.

Note: In 4.2 the stack's yellow halo works as expected. You can still use the card's yellow halo - either seems to produce the same result (i.e. resizing the stack).

The Stack Controls

Across the top of the Stack are a set of control buttons. Here is what they do:

-	Delete this Card.
<<	Turn to the first Card of the Stack.
<	Turn to the previous Card.
•	Bring up a menu of commands. It is called the Stack Menu.
§	Show designation button. (Will be discussed below)
>	Turn to the next Card.
>>	Turn to the last Card.
+	Add a new card (it will have the current background).
Diamond	Show fewer controls. Press it again to see all of the controls again

The entire set of controls can also be hidden. Choose "hide page controls" from the Stack Menu.

From the Stack Tools flap, pull out the Stack Help object and place it on your World (i.e. current project desktop). Read through the Stack Help for an overview of how to use the stack and then return to this tutorial.

Let's Build a Personal Database

Add a Field and make it part of the background
- Let's make a field for a person's name. In the Stack Tools flap, there is an object labelled "Simple Text". Drag it out to your stack.
- Change the name of this object to "Name Field", by bringing up the object's halo and selecting the words 'Simple Text' under the object. Type in 'Name Field' and then hit carriage return.
- Use the yellow resize halo to enlarge the field to the right; make it long enough that it can hold 25 or 30 characters. (The simple text field defaults to growing downwards, so it is necessary to widen the field with the yellow halo).
- Type in the name of a person.

Add a Label Beside the Field
- Drag another "Simple Text" object out of the Stack Tools Flap. Use the yellow halo to enlarge the Label (enough for about 10 characters).
- Type the word "Name:" in this simple text field.

Now We Talk About "Designations"
- Select the Stack menu ( • ) and then select "explain designations". A rectangular object will appear with a green, orange and red background.
- Move the object to an empty spot in the world. The descriptions on this object summarize the designation information that you read in the Stack Help file.
- On the Stack menu, select "show designations". The 2 fields we placed on the stack will contain a red border around them (hold down the mouse button to keep the borders visible). This indicates they are only on this card.

Place the 2 Fields Onto the Background
- The "Name Field" is going to have unique data for each card. It is therefore going to be designated with an orange border when we are through.
- The Label field is going to say the exact same thing (Name:) on each card, so it is going to be designated with a green border.
- Select the "Name Field" and then select its red menu halo. From the menu select the "stacks and cards..." item and then select "background field, individual values". You have just added the 'Name Field' to the background.
- Select "show designations" from the Stack menu, and you will see an orange border around the field, indicating its data will be unique on each card.
- Select the Label field called "Name:" and select its red menu halo. From the menu select the "stacks and cards..." item and then select "Background field, shared value".
- Select "show designations" from the Stack menu, and you will see a green border around the field, indicating its data will be the same for each card.

Create 2 More "orange" Data Items as Background Fields
- Create a simple text object for the person's phone number.
- Create a scrolling text object to jot down notes about the person. Go through the above same process to place these fields on the background as "orange" data items.

Make 2 Label Fields for Phone Number and Notes
- Make these "green" shared items on the Background because they will be the same on each card.

Add Your Data (i.e. make some new cards)
- Press the "+" button to make a new card. This card has "blankText" in each field until you replace it.
- Put some data into the fields of this card. When entering data into the Note field, you have to accept the entry, (Cmd S) before you leave the card or else the data will be lost.
- Use ">" to move between the Cards.

Sort Your Data
- Press the Stack menu button ( • ) and select "sort cards by..."
- A dialog will pop up showing the Field names to be sorted on (Note - you may have to save your image first to see the correct names - select the World menu and then save)
- If you named your "orange" Fields as described earlier (e.g. Name Field, Phone Field, Notes Field) you should see items in the sort list like this:
  - nameField
  - phoneField
  - notesField

Search Your Data
- What's the point of having a database if you can't search it? Searching is very simple fortunately.
- To search for anything (Name, Phone, text within the Notes) simply action-click (for me it's right-click on my mouse) inside a card to bring up the StackMorph object's menu and select the "book..." item then select "search for text".
- Enter the text you want to search for and select "Accept" and voila! you will be taken to the first card that has that instance of text in it.

Options - Enhance Your Database

Adding Contact Photos
- You can open a jpg file from the File List tool by selecting the file and clicking the open button. This places a Sketch object on your project desktop that you can then drag and drop onto your stack.
- You can call up a set of halos on the image and resize it to fit on the stack. The image is saved on the card, not the background.
- Select the § to see the red border designation around the image, indicating it is unique to the card.
- Now you have the ability to put a picture of each person on his or her card.

Improve the Form Usability
- You might want to try using "Text (border)" from the Text category of the Objects flap for your data fields to make them visibly different from your labels.
- Try changing the text color properties of your labels to make them stand out (Hint - use the red halo menu and select "text properties...")
- Add a reminder label to the Notes Field to remind the user to use (Cmd S) to save their content.
- Add previous card and next card buttons from the Stack Tools flap (I know, they're in the menu already, but you can make these bigger, with different colors, and place them strategically). Don't forget to add them to the background so that they are "green" designated (Hint - use the red halo menu, "stacks and cards..." then "put onto Background").
- You can even add a clock object from the Supplies flap so you can keep track of your phone call.
- As an exercise, see if you can prevent a user from editing a label (by default, labels can be edited just like your data fields can)

Change the Background Color
- Get the Halo for the Card. Press the red menu icon.
- Choose "fill style" and "gradient fill".
- Experiment to get the colors you want.

When you're done it should look something like this:

More to come...

Q. Where is my data saved?
- A. TBD

Q. What happens if I accidentally delete my StackMorph object?
- A. Can't be good but ...

Q. How do I transfer my newly created Personal Database to another Squeak image?
- A. TBD

Older stuff...

Initially these will be notes on what I have learned from experimenting with creating a stack using StackMorph.

The "show designations" button on the Controls menu at the top of the stack will show whether a morph on the stack is 1) on the background and shared by each card (green), 2) on the card instance specific (red), or 3) a data item on the background (orange), by drawing a rectangle of the corresponding color around each morph.
Dragging a text morph onto a stackMorph makes it an instance specific (red designation) morph on that card.
To place a text morph on the background as a shared item (green designation), place a morph on the stack, select the red menu halo and from the stacks and cards menu, select put on background option. The morph will now show up on every card.

Question: How does one make a textMorph a data item on the background (orange designation) using direct manipulation?

Answer: I found my answer in the stack help file on the Stack Tools flap (which I didn't know existed before). If the image does not have a Stack Tools flap, open the World menu and select flaps. Another menu appears which lists all the flaps available, with selection buttons next to each; select the Stack Tools flap and the flap magically appears. Then you can drag out the Stack Help morph.

You first have to place a morph which supports text on the background by using the stack/cards menu and select "place onto background".

Then to have the data morph be seen on every card, with each card having its own value, use the stack/cards menu and select "start holding separate data for each instance". Now you can add different text data on each card.

If you use a Scrolling Text morph, the border will turn red when you enter text; be sure to type Cmd-s to save the text in the Scrolling Text morph before you go to another card or else your text will be erased. –Dave Raftery