Tutorial Project 2: Building a Document, Part 1

This project has three parts. In the first part of this project, we will build a simple one page Document that we will call: graph. On this page, we will place a Graph2D object, and will create a simple TextBox that will allow the reader to enter an expression in variable x. The finished version of this project may be found in the project directory: graph. The Documents supplied with Mathwright32 Author are by default in subdirectories of the Program Files\Bluejay Lispware\Mathwright32 directory. You may find it in Windows Explorer by browsing to C:\Program Files\Bluejay Lispware\Mathwright32\microworlds\graph.

There will also be two Pushbuttons. One, called Graph Function will cause the graph of the function defined by the expression to be drawn. The other, called Clear will cause the window to be cleared.

In the second part, we will show an alternative way to implement the same idea without using pushbuttons. We do this by scripting a TextLine gadget and the Graph2D windows themselves!

For the third part, we show how a sprite may be used to trace along the graph, and report the points.

Part 1: A Simple Page

Step 1: Document Directory

Before you begin, be sure that the screen resolution is 800x600 or 1024x768. The Documents that you create may be displayed on reader machines or browsers in any resolution. You have no control over that. But if you create them in 800x600 or 1024x768 resolution, then they will display properly in 640x480, 800x600, or 1024x768 resolutions in the reader's machine or browser. This is especially important because, in the browsers, you may shrink or enlarge the page as you like to fit your web page. Along these lines, we remind you that if you use wallpaper bitmaps (and hotspots) then you may use either bitmaps, GIFs, or JPGs. And these should be 800x600, or 1024x768 pixels to match your screen resolution.

You set the screen resolution by right-clicking on the background screen to get the menu, and then selecting Properties. Under Settings, choose 800x600 or 1024x768 screen resolution. The colors should be High Color (16 Million or 2^24 Colors).

We begin by creating the "Document Directory". Every Document should be placed in its own directory. The reason for this is that Documents often have auxiliary files called resources, such as bitmap files and sound files. When a Document is placed on the server, all of its resources need to be packaged together so that MathwrightWeb knows where to find them.

When the Document is viewed by a reader in Applet mode, MathwrightWeb brings these resources to the user's web cache one at a time, as needed. Any particular resource is downloaded only once. The next time it is needed (If the reader returns to a page, say, or reopens the Document at a later time) the resource is simply loaded from the cache. If, however, for some reason, the resource is removed from the cache, then MathwrightWeb will go back to the server to get another copy of the resource.

Also, if the reader opts to make a "Disk Version" of a Document, then these resources come over the web much more quickly, because they are zipped up in a self-extracting archive. In that case, they are all placed in a subdirectory (named by the reader) of the Documents Folder, so that, again, they are bundled together for either MathwrightWeb or for Mathwright32 Reader to find.

If a number of Documents are placed in a common directory along with their resources, it may become a difficult matter later on to "untangle" these Documents and their resources from one another. For example, if you want to give a Document to a colleague, the cleanest way to do it is to have the Document, together with its resources isolated in a single directory. Otherwise, you will later have to remember what resources belong to the current Document. This will not be a trivial matter when Documents become sophisticated and utilize a variety of resources.

Therefore, the first step in creating the graph Document is to create a directory called graph that will hold it. We use lowercase for all file names and directories because some servers (notably Apache servers) are case sensitive, and may not find a file if the case is wrong. Of course, this is not an issue for Mathwright32 Author or Reader when they read Documents offline, but we follow the practice outlined above because most Documents will be served from web servers.

Another practice that we follow for reasons that will be clear when you read Project A on Packaging and Delivering your Document, is this: The name of the directory should be the same (lowercase) name as the name of your Document ( .lva file). We will create Documents in the C:\My Documents folder, because that is where Mathwright32 looks for them.

Thus, go to the Windows Explorer, select the C:\My Documents directory, then select File, New, Folder: and when asked for a name, type graph. This will create a directory: C:\My Documents\graph\ into which you will place the Document.

Step 2: Adding the "handcursor.cur" resource

If you browse in Windows Explorer to the home directory: Program Files/Bluejay Lispware/Mathwright32 Author you will find a little file called: handcursor.cur Whenever you create a new Document, copy this file and paste it into your new directory. While it is not needed for offline reading in Mathwright32, it is a necessary resource for MathwrightWeb. Thus, highlight it, and select: Edit, Copy. Then browse to your new directory, and select Edit, Paste. Another resource that, in the future, you may want to bring to your new folder is algebra.lsp. We will not do that now.

Step 3: Creating the Document

Next, let's open Mathwright32 to create the graph Document. There are several ways to open Mathwright32 as we saw above. You may click on the Mathwright Author 32 icon above in the MWAuthor32 button on the Start Menu that was set up with the system, or you may go to Windows Explorer and click on mwauthor.exe in the Program Files/Bluejay Lispware/Mathwright32 Author subdirectory, or you may select Run..., then enter C:/Program Files/Bluejay Lispware/Mathwright32 Author\mwauthor.exe.

Any of these will open a blank copy of the program. Now, once the program is open, select WorkBook, New Microworld from the menu. The screen will turn white, and the page caption will change to: Untitled0: Page 1 of 1 This means that you have created a new Document. It has the temporary name: Untitled0.lva.

Mathwright32 Author wakes up in Reader Mode. You may change to Design mode if you like by selecting "Go to Design mode" in the WorkBook menu above. The advantage of being in Design mode is that certain objects that you create, such as push buttons and text fields, will be moveable and resizeable in this mode, and will not be activated when the mouse clicks on them. In Design mode, you may copy and paste objects or whole pages, may insert or delete pages, and so on.

On the other hand, Reader mode is where you give objects their specific properties, create and run scripts, and save the Document to disk.

Step 4: Setting the Page color

Now, let's set the page color for the Document. The "default" page color for a book is white. Each new page that you place in a Document will have this default color. When you set the page color for the Document, you change the default background color to a new color. That changes the color of the current page, and of each new page that will be added subsequently.

Select Page, Page Background color... A dialog box will appear with a selection of colors to choose from. Select the light grey in the sixth row, sixth column, as marked below:

The screen should change to light grey. This light grey will be the default background color for all new pages. You may still change the background color for any particular page by selecting: Page, Page Background Color... on any page.

The next step is to go to Design Mode and create an object so that we can save this Microworld. There are 13 types of Objects (or Gadgets) that you may create in Design Mode. These are: Button Gadgets, CheckBox Gadgets, CommandField Objects, Data Table Objects, Graph2D Gadgets, Graph3D Objects, HotSpot Gadgets, Label Objects, MathEdit Objects, Horizontal Slider Gadgets, Vertical Slider Gadgets, TextBox Objects, and TextField (or TextLine) Gadgets. To create any of these, you must place Mathwright in Design mode. This is done by the menu selection: WorkBook, Go to Design mode.

Mathwright always opens up in Reader mode. Next, select the Type of Object to create from the Objects menu.

Step 5: Creating a Graph2D gadget

We are nearly ready to draw a Graph2D gadget on the screen. This is where the graphs will be drawn. The procedure that we will use applies to all Display Objects and Gadgets. Read and follow the procedure outlined below to build a Graph2D gadget with the name: graph. Use the illustrations below as a guide.

Before drawing the Graph2D Window:

After drawing the Graph2D Window (in Design Mode):

After drawing the Graph2D Window (in Reader Mode):

How to create Display Objects and Gadgets from the Object Menu

Usually, the first thing that authors do after they have decided what the dynamics of reader interaction on a page should be, is to place appropriate display objects and gadgets on that page. The simplest way to do that is to use the Mathwright32 Objects menu in Design mode. Later, we'll discuss how individual objects, or whole pages may be copied and pasted, but for now, we'll discuss this simplest way to build objects from scratch.

There are 13 types of Objects and Gadgets that you can draw on the screen in Design mode, as you can see from the menu:

These are: Button Gadgets, CheckBox Gadgets, CommandField Objects, Data Table Objects, Graph2D Gadgets, Graph3D Objects, HotSpot Gadgets, Label Objects, MathEdit Objects, Horizontal Slider Gadgets, Vertical Slider Gadgets, TextBox Objects, and TextField (or TextLine) Gadgets.

To create any of these, you must place Mathwright in Design mode. This is done by the menu selection: WorkBook, Go to Design mode.

Mathwright always opens up in Reader mode. Next, select the Type of Object to create from the Objects menu.

Step 5 Continued: Draw the Graph2D gadget

Now, once you have selected Graph2D Gadget, the cursor will change to a "pointing finger ". This indicates that you are expected to draw the outline of the object on the screen. Do this in 4 steps:

Usually, a "ghost rectangle" will be traced as you move the mouse to help you see what you have at any moment, but if you are drawing on the surface of another window, you will not see a ghost rectangle. Once you have drawn the rectangle, you will be asked for a name.

Naming Display Objects and Gadgets

Once you draw the rectangle, you will be asked to name the object (unless it is a HotSpot or a Label). In this case, the name will be graph. Each Display object or Gadget must have a name. The name you supply will be used whenever Scripts refer to the object to get or set information in them. Therefore the names you supply for different objects of the same type on a page should be distinct.

Names will be interpreted as MathScript Strings, and so should conform to the rules for creating strings. They may contain lower-case letters, spaces and underscores, and they are case-sensitive. Objects on separate pages may have the same name. Also, it is important to refer to objects in Scripts and Commands with exactly the same spelling and case with which the object was named. Any object may be renamed in Design mode by accessing the Rename option on its menu.

When you have typed a name, a captioned window representing the object will appear. The caption will show the name and the type of the object, and the window will show its background color. In Reader mode, you will see the actual object, and be able to set its attributes.

Redrawing Objects in Design mode

When objects are first created, they pop to the top of the screen (above other objects). In Design mode, the placeholder windows for objects are really not part of the page. They are independent windows, and they may occasionally "disappear" from site or be minimized to the Task Bar. Once in Reader mode, they become permanent and static parts of the page. If they should disappear in Design mode, just click on the page background to bring them all back. You may also select Redraw Objects on the WorkBook Menu to bring them back. Or, of course, you may go to Reader mode to see them.

No Overlapping of Objects

It is an error in Mathwright Documents to attempt to stack objects, one above the other. In general, objects should not overlap at all on a page. While captioned objects may be moved around, and temporarily overlap, the page should not be designed so that they will overlap when that page is entered.

Saving Changes

As you make changes, we recommend that you save those changes frequently. The procedure for doing that follows. You will not be allowed to save a book with an empty page, so you will have to wait until you have added an object, as we just did, to save the book.

Get into Reader mode, and Select WorkBook, Save As...

And type in the Dialog Box C:\My Documents\graph\graph or, select the C:\My Documents\graph directory, then type graph in the dialog box as below. Save the Document. It is saved as graph.lva.

As you develop your book, frequently follow a procedure similar to the one used above for saving the book for the first time. And every now and then, back up your work by copying the directory to disk, or at least to a different directory. Nothing is more frustrating than losing a day's (or a week's) work in the ether after a system or program crash.

Simply select WorkBook, Save, and the changes will be saved to the file: graph.lva, which is the Document File that you would open in Mathwright32 Author or Reader. It is good practice to do this from time to time, and of course, for projects in which you have invested a fair amount of time, you should save a "backup" copy of your .lva file to some other place, such as a floppy disk, or another directory occasionally.

Screen Design and Scripting

When you use Mathwright, you will be doing two fairly independent things. On the one hand, you will work on screen design and page layout. For this, you create the pages, and then place Display Objects, Wallpaper, Hotspots, and Gadgets on those pages. This will determine the style and the nature of the reader's interaction within the Document.

The other thing that you will do is create Scripts of various sorts for the Document Objects. For example, In the WorkBook Script, you will place the statements that initialize the Document, that is, that create the global Objects, Programs, and Commands that you want to be available. Often, this will happen by placing statements in the WorkBook script that load File Scripts.

File Scripts are places where useful programs and commands can be defined and stored for use by any books. A common example is a script the solves a differential equation, or one that moves a sprite as you move the cursor. Sometimes, special steps ought to be taken each time a Page is entered. In that case, those steps may be placed in a Page Script.

In addition to these, you will create Gadget Scripts that determine how Pushbuttons, Sliders, and CheckBoxes will behave when you click on them. Next, you may create scripts for Graph2D windows, and TextLines. Finally, you may create "Hotspot Scripts" for hotspots on any page that has wallpaper.

Some properties of Display Objects and Gadgets

In Design mode, all objects are resizeable. This means that you may use the mouse to move them or change their size or shape. Further, if you select the "Snap to Grid" option on the Page Menu:

the objects will be easy to align and size in a consistent way.

In Reader mode, all objects and gadgets are static. That means that they cannot be moved or resized in Reader mode.

Accessing Object Menus

Objects have menus that are always accessed in Reader mode by clicking on them with the right mouse button. In design mode, the objects are represented with their sizes and colors by generic rectangular windows. These windows have captions that tell the name and type of each object. To move an object in Design mode, click with the left mouse button on the caption of the object and drag it. The menus available in Design mode allow you to rename the object or to copy it. Names are case-sensitive, may consist of more than one word, and are unique for each object type on a page. Objects of different types may have the same name on a page, and of course, objects on different pages, even of the same type, may have the same name. An object that is copied may be pasted onto any page thereafter.

To resize an object in Design mode, click with the left mouse button at one of the sides or corners, then draw the side or corner to a new position, holding the left mouse button down. In Design mode, all of the Display Objects and Gadgets appear on the Mathwright32 screen with caption bars. In that mode, these captioned objects can be moved and resized whenever they appear on the screen.

Selecting Display Objects

In order to control the flow of traffic of information in an intuitive way we have implemented the notion of selection for all Display Objects except Labels. If several objects of the same type appear on a page, then a left-click (left mouse button) in the client area of any one of them selects it. There is no immediate visual indication that it is "selected". If the selected window is a graph2D gadget, then the next graphical output is automatically directed to it. If it is a textbox, then the next text output (through a print command, say) is directed to it.

Sometimes it is desirable to select a window under program control, by name. The Select Command, if it is given the name of a graph2D gadget or textbox (or any other object except Label) will do that. Many commands, such as "graph" or "curve" allow you to select the object simply by including the phrase: in "windowname" in the command statement. For example, if "Mywin" is a graph2D window, then: Graph sin in "Mywin" causes Mywin to be selected, and the graph to be drawn in it.

It is not possible to select a script window in this way.

Step 6: Adding a TextBox for input

Return to Design mode. The next step will be to add a TextBox Entry Field, so that the reader can type an expression in variable x, and that expression will be graphed when the button is pushed. Thus, follow the procedure outlined above to create a TextBox Object called "Input".

First, select Objects, TextBox Object..., and draw it as indicated below. When asked for a name, type: Input.

Accessing Object Menus

Each object on a page has its own settable and gettable properties. When those properties are accessed through scripts, the name of the object must be used. Those properties may be modified on the screen, also, and for that, one must access the menu of the object. These menus are always accessed with the right mouse button, in Reader mode. For Display Objects such as TextBoxes, there are generally three of the four options:

The Settings generally give properties of the object. They determine, for example, the font or text color of a TextBox, the type of coordinate system, pencolor and width of a Graph2D, and so on. Actions generally trigger changes appropriate to the type of object, such as editing and testing the script. Appearance allows you to make changes in the screen appearance of the object, such as border style, background color, etc. Finally, Utilities make high level language services directly available. They might cause a graph, curve, or surface to be drawn, or bring a sprite or wallpaper into the window for a Graph2D, for example.

From the menus in Design mode, objects may only be copied, renamed, or destroyed.

Accessing Gadget Scripts For Gadgets

Perhaps the most important menu option is obtained through the sequence: Actions, Edit Script. In this way, the Script Window for the Gadget is opened up. Then the script may be edited, compiled, executed, or debugged. Script windows may be accessed only in Reader mode.

Step 7: Changing the TextBox Settings and Appearance

You will notice that, as with the Graph2D window, you may move and resize the TextBox, once you have drawn it. We will now access the menu of the Text Field to give it an Ariel 16 pt. Font, a background color: yellow, and a text color: dark blue. We do this by switching to Reader mode, so that you see:

Next, access the Settings menu for the TextBox. As we said above, you get the menu for a TextBox by right-clicking anywhere on that TextBox. When you click the right mouse button, this menu appears: Select Settings, Text, Set Font...and the following Dialog Box appears:

Now, choose Arial, 12 pt., Regular. And press OK. Type some text. Next, select: Settings, Text, Text Color... and choose a dark blue text color.

Finally, select from the menu, Appearance, Background Color... and choose a yellow background color. Normally, input fields that accept simple one-line input from the reader will be TextLines, instead of TextBoxes. Textlines are scripted gadgets that accept only a single line of input. We use a TextBox here to demonstrate the variety of options, but will use a textline in the second part of this Project. A TextBox with multiple lines normally simply scrolls when the reader presses Enter. Command lines, however, attempt to execute the command on the line before scrolling.

Seeding Text Fields

It is usually a good idea to "seed" a text entry field with a default entry, so that when the page first opens, it will have some example text for the reader to see. Thus, if the reader presses the button without entering text, something will happen. To seed the field, go to Reader Mode. Click in the TextBox, and type: 3*sin(x) Remember to place the asterisk between 3 and sin. Multiplication in MathScript is always indicated by an asterisk. Your page should look like the one below.

Step 8: Make a Label with Instructions

We now create a Label just above the "Input" Field that will appear to be part of the background page. This will contain the text: Enter an expression in x. When we are finished, it will not be possible for the reader to change the text of this field.

For this, reenter Design mode, and select: Objects, Label Object. Draw the Label just above the Input TextBox. You will not be asked for a name, since labels are not selectable and are identified by the text they contain. Return to Reader mode. The screen should resemble:

Next, access the menu for the new Label. You will see one option available: Edit the Label. This option is only available in Mathwright32 Author. In Mathwright32 Reader and MathwrightWeb, Labels do not have menus. They really are a part of the background page. Select that, and the other menu options become available, and you may enter text in the Label now.

First, select Set Background Color... and choose the same light grey color you used for the page. The Label disappears! Actually, you see that there is a blinking caret where it was, so it is not really gone. It just blends with the background now.

Next, select Set Font... and change the Font to Arial, 12pt, Bold. Then click on the label and type the text:

Enter an expression in x:

Now, Save the Document. You should see something like:

Step 9: Creating the PushButtons and using "Snap to Grid" to line them up

Now we create the Pushbuttons: Graph Function and Clear below the Input TextBox. Return to Design mode. In order to line these buttons up properly, we will select the "Snap to Grid" option from the Page menu.

After that, to create Graph Function, access the Objects menu, as before, and select: Button Gadget.... Draw the button below the Input TextBox, and when asked for a name, type: Graph Function.

Next, make a copy of this PushButton by clicking on it with the right mouse button to access its menu, then selecting: Copy Object... If you paste the button into this page, it will automatically be given the name "New Button" because there is already a button named Graph Function on the page.

OK, select Rename... from the button menu and rename the "New Button" button to Clear. Go to Reader mode, take a look at it, and return to Design mode. Actually, we took this trip to notify MathScript that the name was indeed changed. Now on the Objects menu, select Paste Object... And the new button is pasted right on top of the original.

You may now move the Clear Button directly below the Graph Function button. Notice that the screen is "sticky" and the button is attracted always to the closest lattice point. In this way, you can put the two buttons in perfect alignment, one above the other. When you are finished, go to Reader mode and Save the Document. You should see something like:

At this point, we'll take care of the last piece of business for this page.

Creating Scripts

In order for the page to work, we have to write scripts for the pushbuttons. Thus, we should say a little bit about creating Scripts in Script Windows. There are just five types of scripts that authors may create. These are: Gadget Scripts, HotSpot Scripts, WorkBook Scripts, Page Scripts, and File Scripts. All scripts are created and edited in Reader mode.

How and where to create Scripts

Every script is created in a Script wndow in three steps. There are no exceptions. To create a script, you must:

Scripts are composed in Script Windows, or Sometimes called Listeners. All Gadgets have their private Script Windows. To edit a Gadget Script, you select: Actions, Edit Script from the Gadget menu. Once a script window is open, you may edit the script. To make the editing changes functional, you should press the Compile button, then Attach and Exit to attach it to the Gadget. If you do not attach it, your script is not saved, unless, of course, you saved it to disk from the File, Save Script As... menu. Often, you will open a Script Window to create a FIle Script, and you will not intend to attach it to the gadget. In this case, press Cancel when finished.

To compile the script, click the Compile button. If the compiler detects no errors, it will notify you with a Success! banner, otherwise, it will attempt to diagnose the error. If the compilation is successful, then you can save your changes as mentioned by pressing the Attach and Exit button, or by selecting File, Save Script As...

Step 10: Scripting the PushButtons

We begin by creating the script for PushButton Graph Function. To do this, we first have to get the pushbutton menu. Thus, click with the right mouse button anywhere on the pushbutton. The following menu should appear.

Select from it Actions, then Edit Script.

When you do this, the Script Window for Graph Function will appear. This is where you create the script. We shall not discuss details of MathScript syntax here. We will do that later in the tutorial. Type the following script in the window. Notice that each line ends with a semicolon.

make variable x;
let f(x) be value evaluate(text("Input"));
graph f;

The first line sets x to a variable. The second line defines the function f. And the third line causes it to be graphed. The script window should look like this (be sure to place "Input" in quotes, and to capitalize the I):

Next, we have to compile the script. For that, click the Compile button at the bottom of the window. The Success! banner should appear. Click Ok. Then click Attach and Exit. As explained above, this is where you accept the changes made to the script, and connect the new script to the button.

While the appearance of the screen doesn't change, the PushButton Graph Function now has the following functionality. When the button is pushed, the expression in TextBox "Input" is converted to function f and f is graphed. Since there is only one Graph2D window to graph it in, it is drawn in window graph. Later, we'll see how to select the window for the graph when there are more than one Graph2D windows. Try it.

This is a good time to Save the WorkBook. The last thing we want to do is attach the script for the Clear Button. Thus, click with the right mouse button anywhere on the Clear pushbutton. The menu should appear. Select from it Actions, then Edit Script. When you do this, the Script Window for Clear will appear. Now the script for Clear is the single command, followed by semicolon

clear;

Type that in the Script Window. Now, as before, click the Compile button at the bottom of the window. The Success! banner should appear. Click Ok. Then click Attach and Exit.

The graph WorkBook is complete. Save the Document by selecting WorkBook, Save, as before. Now enter Reader Mode and try it out. When you are satisfied, close Mathwright by selecting WorkBook, then Exit from the menu.

End of Part 1 of Project 2