First Steps into visualFORTH

A Pulldown Menu will show up with a left mouse click on „Form“ (just below the vF sign).

A click on "Open" opens a Window with the „Projects" folder.
Saving our visualFORTH-Files inside this „Projects“ folder enables the use of the One-Click-EXE-File-Function.

Double-click on "Projects" shows the files stored there, including "OneTest.ff", the example we start with.

Double-click on "OneTest.ff" opens our first example.

A click onto the little blue runner starts our example program.

A click on "Button1", and voila, we hear our famous Forth-Beep!

Now we look how this happend:

With a click on the red cross we close compiled Form1 to see our Form1 as a template again.

A right mouse click on "Button1", and a menu window pops up.

Click on "Properties", and we get the "Properties+" Form.

Looking at the “Properties+” Form, we see the “Beep” inserted at "Function:" - that is it!

We just discovered the Function-Secret!

It is not only possible to insert a defined word there, we also can define a new word.
Let's overwrite the word “Beep” with a new word “Test”.
To apply the new word – you guessed meanwhile – we click on “Apply”!

Now we like to define what our new word “Test” shall do:
A Click on “Ed” , and a new window pops up, our edit-window “Edit Function”.

“Function:” is already named "Test", because we defined it before.

With “Beep” a Button-click on the compiled Form resulted in a beep, now we like to get more. To achieve this, we type the words we like into the lower Text-box, one after the other, same order as they shall be executed.

I like this example:

Beep 300 ms Beep 100 ms Beep

A click on “Apply” saves these words, a click on the little blue runner , a click on “Button1”, and we hear our Beep ... Beep ... Beep.

That's simple, isn't it?

Of course we are able to connect to more complex programs.

Again we need our “Edit Function” window. If it's gone, a click on “Ed” will bring it back.

Let's say we developed a program for which we need a GUI to operate it.

Let's say we named this program "MyProgram.f".

All we have to do: type

needs MyProgram.f

into the upper text-box, the “Requirements:” text-box.

Of course we can define Constants, Values, Variables and Word-Definitions (as usual starting with a colon and ending with a semicolon) by typing into the “Requirements:” text-box, as far as it does not exceed 127 Bytes (including crlf for each new line).

Seldom more than 127 Bytes are needed.

My first program with visualFORTH was RPN-Calc.ff, a little Integer “Calculator” with Reverse Polish Notation (as used in Forth), and there was enough space for all functions, but I modularized everything and made names as short as possible. You find my example RPN-Calc.ff inside our “Projects” folder.

To end visualFORTH, a click on "Exit VisualFORTH" under "Form"-Menu, or <Alt>+F4 closes visualFORTH, reminding to save our work, if not yet done.



A new Start!

This exercise here shows how to program an operating panel / Graphical User Interface (GUI) from scratch.

With a double-click we open the folder
"visualFORTH" and a double-click on "visualFORTH.exe" starts visualFORTH.

A click on menu "Form" and "New" opens a new Form.

To place a Button into our new Form we click onto the Button-Symbol at the right part of our menu bar.

All we need is a short click, (we do not have a "Drag-and-Drop"-System here) and the "PushButton"-Symbol shows embossed that we clicked on it.

Now we position the mouse cursor inside the Form we opened onto the place where we like to have the PushButton. A left mouse click, and there is our first Pushbutton!

Now a right mouse click onto the PushButton-Symbol inside this Form, and the well known Popup-Menu with "Properties" shows up. A left mouse click on"Properties", and again we get the "Properties+" window.

The "Properties+" window contains our PushButtons position and dimensions which may be changed by typing in the new number(s) and click on “Apply”, the PushButton changes correspondingly.
No number shall exceed 1024.

There are more possibilities, more about it later.
For testing purposes we may insert our famous “Beep”, and if we like to use this function locally only, we remove the little hook shown at “Options”, “Global”: with a left mouse click.

A click on "Apply" accepts our function, we recognize that "Ed" is enabled now.

Again a click on "Ed" opens the Editing-window.
To proceed follow the description above.

With "Close active Form", "Form"-Menu, we are told to save our new Design.

Important: save your File into folder "Projects", to enable the One-Click-EXE-File generation.
A double click on "Projects" opens this folder and we save our first project with a click on “Save” after a name has been typed at “File Name:”.


One-Click-EXE-File


We are only one click away from Form to EXE-File!

First we should check the Form we made with a click on Run for Test. This Test is important to guarantee that the EXE-File will work.


Clicking the Symbol between "Test" and "Help" will start the making of the EXE-File.

Some seconds, and it is done. We will find the EXE-File inside the visualFORTH folder.

How does it work?
First a .ftk (Forth TurnKey) file is generated. All additional needed words for Turnkey have been added to the .frm-file. If there are Bitmaps used, these will be inserted afterwards into the EXE-file.

If you fload this .ftk-file with Win32Forth it also will make an EXE-File. This possibility is important to look for bugs in case it does not work (normally it should work unless you did not test it with “Run” before).
If there are problems, a .frm-file should be created with click on , and this .frm-file should be floaded with Win32Forth for debugging.


Button-Arrays


There is a special option you may like: generating an array of Pushbuttons or Bitmaps or any other control, up to 256, up to 32 in a row or in a column. Open Textbox64.ff or LED-Matrix-16x16.ff to see how it looks.

Here is how to do it:
If you like to use an array, the best thing to do this is to do it as the first thing after opening a new form.
A right mouse click pops up the menu, a left mouse click on “Group Action” brings up the Properties+, Action window. There you select the number of rows and columns you like to have, then select the Pushbutton (or another control) and position it with a left mouse click into the form, to be the left top of the later array. All controls are then piled up there in a stack pile. Then draw a frame of the size and in the position of the array to be done by pushing the left mouse button and holding it down while dragging. Release the mouse button when done – if the drawn frame is not correct, you can start a new one, until it is correct.

Then click on “To Box” , and the array starts and finishes forming.

There are additional possibilities:
After stacking the controls into the form you can add additions to the control (Pushbutton) on top, you can add functions, a Bitmap, Variables, etc., see our example LedBox.ff. With the left mouse click on “To Box” these additions will be transferred onto all controls of this pile.

With clicking on “To Box” the drawn frame defines the size and position of the emerging array.

But you can define the size of each button by setting Width and Height of the top of pile control, drawing the frame and on “Action” click on Arrange “Horizontally” or “Vertically” instead of clicking “To Box”. This will arrange all controls with counting horizontally or vertically, respectively. In this case the size of the top on pile control defines the size of all controls of this array, the frame only has to cover the pile.

The distance of the controls is set by “Spacing” , for the LED-array we used a spacing of zero, the default setting is two.

To delete a group or a pile of controls, draw a frame with the controls to delete inside, get the popup menu with a right mouse click into the form outside the frame, a click on “Delete Controls” will delete the controls inside the frame.

If you start an array later, save your work first with “Save all modified”.



Bitmaps


There are two controls using a Bitmap, “Bitmap Button” and “Static Bitmap”. In Properties+, Bitmap: you can select a Bitmap with click on Bitmapselect . In case of a Bitmap Array each control will get the same Bitmap when done properly. Setting another Bitmap controlled by program is really easy, and the new Bitmap-Handle is defined automatically when this Bitmap - ending with .bmp - is written as a word into Properties+ "Form" "Add Words" "This Form needs:" - of course you can put in more than one, separated by blanks.

Let's assume you like to use a Bitmap named “MyPicture.bmp”, then the handle “MyPicture” is generated as follows:

z” MyPicture.bmp” LoadBitmap value MyPicture

That's it! And visualFORTH does it for you automatically!
To ease Bitmap setting a selection tool is established automatically for all Bitmap controls.
Let's assume you have some Bitmap controls in use, so to transfer this new Bitmap to control 3, do it as follows:

MyPicture 3 Bitmap!

“MyPicture” is the handle which was generated automatically, “3” is the number of the Bitmap control, and Bitmap! does the work.

To look for the number of the Bitmap control, use the “List Controls” listing function.

Bitmaps are automatically inserted into the EXE-file you get (see above “One-Click-EXE-File”).



Start-/Stop-Function


Everything is possible with Forth, that's why we can start or stop our Form really simple using the Forth Console (open with "Tools", "Forth Console" or <Ctrl>+F) after compiling with "Test active Form".
It is really totally simple:

Start <Enter>

to start, and

Stop <Enter>

to stop the Form. Cool, isn't it?
Of course our Form may be started or stopped by program, as usual with Forth

Question: what if several Forms are compiled?

Don't worry. Start and Stop always open and close the last compiled Form. If you like to open or close a Form compiled before, simply use the filename of this Form as prefix. Example: if the name of this file is Form1.ff, then you can start this Form1 with Form1-Start and stop with Form1-Stop. This is the simplest way you can imagine, isn't it?
The same method works of course in case you compiled only one Form, so you always can use this method when starting and stopping a Form by program.




Zooming-Function


Everything is possible with Forth, that's why we can generate a zoomable Form.
To make this possible, at "Options" "Set Preferences" we set a little hook at "Zooming" in "Compiler Settings".
This is a Compiler Setting, because the Zooming option makes files larger. "Zooming" has to be enabled before clicking on "Test active Form" and before starting a One-Click-EXE.

After starting the Form you can type the Zoomfactor into Forth Console:

75 %Zoom <Enter>

Cool, isn't it? Of course you can zoom to 150% with 150 %Zoom or with any other number.
If you choose a number too big, the form may disappear, but it comes back again with 100 %Zoom!
After compiling the form with Zooming it is possible to change the size by program, as usual with Forth.




Listing Functions


There are three listing functions to help with program development:
With menu “Control” you may select “List Controls” or “List Functions”, and copy these to the console or to the clipboard.
A right mouse click on a form pops up a menu, and a left mouse click on “View/Edit Source” shows the automatically generated source code for this form. It is possible to edit this code and save it as a separate Forth-file without affecting the form.


Final Remarks


There still may be bugs in visualFORTH (remember, this is the Alpha-Version), so I strongly advise to save your work every now and then, and, very important, save it before starting a special action like making an array, deleting a group of elements, or generating an EXE-File.

Normally an error will be shown on the console, and a click on console and hitting the Enter key will be enough to proceed without further problems, but sometimes visualFORTH disappears. Because of this accidental problem I recommend to save your work regularly and before special actions. We are working hard to reduce the possibility of unwanted interruption.


There you find: the original ForthForm-Notes

Enjoy Testing!
Questions? Ask visualFORTH@yahoogroups.de !
Join our visualFORTH group at http://de.groups.yahoo.com/group/visualFORTH/ !

Mai 4th, 2010 - Version 0.01.14