Win32Forth

Getting Started

Win32Forth is intended to be run on a computer running a Windows operating system. Here’s all you need to do to get started (if the following procedure does not work for you, please drop us a note at win32forth@yahoogroups.com):

Download a copy of Win32Forth from www.win32forth.org (as of August 30^th 2004, the latest version is w32f60911.exe). There are other older versions available. More recent development versions are also available from the developer’s CVS source code control system, but you’ll have to dig a little deeper and work a little harder to gain access and get that setup and working (details are available in the links section of the Win32Forth Yahoo group and you are very welcome to access it when you get to the point that it makes sense), so for now, just start with the downloadable installation package.

Install Win32Forth by running w32f60911.exe. It will install the program with full source code and some sample programs.

Open Windows Explorer and navigate to the Win32Forth installation path (C:\Program Files\win32forth by default).

Explore the directory structure and become familiar with the contents of the various directories. There’s lots to learn about here.

Locate and double click on Win32for.EXE. This will open the Win32Forth development environment. Read the startup text which provides details about Win32Forth and your particular system and configuration.

Explore Win32Forth’s menus. They will probably seem pretty familiar to most Windows users. Pay particular attention to the Help menu. It contains links to lots of information that’s been installed on your machine and on the internet. Try as many of them as you want and remember all the resources that are available when you get stuck.

From the File menu, select the “Edit Forth File” choice. It should open a “file open” dialog. Navigate to the Win32Forth\demos folder and double click on the HELLO.F source file. This should open the SciEdit editor and display the hello.f source code file.

Explore SciEdit’s menus. They will probably also seem pretty familiar to most Windows users especially if you’re familiar with source code editors.

From the Win32Forth menu, select the “Compile” choice. This should FLOAD HELLO.F in the Win32Forth IDE. Switch back to the Win32Forth IDE window and type DEMO. Note that Win32Forth is largely un-aware of letter capitalization, so you can type “demo” if you wish. This should open a new application window with a Title of “Hello World” and in the body of the window you should see the program counting and displaying the number of times the window has been re-painted. Notice there is not a new item in the task bar corresponding to this window. Note also that the window is movable and sizable and has minimize, maximize and close buttons in the upper right hand corner. There is also a system menu in the title bar just to the left of “Hello World”. Play with the various things that can be done to the window and when you’ve seen enough, close it. Feel free to switch back to the SciEdit editor and study the code, make changes and re-compile and try your changes. When you’ve tired of this, close SciEdit, and return to Win32Forth.

From the File menu, select the “Edit Forth File” choice again. It should open a “file open” dialog. Navigate to the Win32Forth\demos folder again, and this time, double click on the WINHELLO.F source file. This should open the SciEdit editor and display the winhello.f source code file. Take a look at this file and you’ll see Win32Forth’s Object Oriented coding approach to creating a Windows program.

From the SciEdit Editor’s Win32Forth menu, select the “Compile” choice. This should FLOAD WINHELLO.F in the Win32Forth IDE. Switch back to Win32Forth and type DEMO. You may be lazy like I am and notice that the up and down arrow keys will recall previously executed commands in a manor similar to the DOSKEY function in DOS.

The demo program should open a new application window with a Title of “Hello World” and in the body of the window you should see “Hello World” again and the program counting and displaying the number of times the window has been re-painted. Note that despite the new colors and a new item in the task bar corresponding to this new window, the window is movable and sizable and has minimize, maximize and close buttons in the upper right hand corner just like the previous program. There is also a system menu in the title bar just to the left of “Hello World”. Play with the various things that can be done to the window and when you’ve seen enough, close it by switching back to Win32Forth and typing undemo. You could have closed the program in several other ways. How many can you find?

Close SciEdit, and Win32Forth and return to the Windows Explorer window. Locate forthform.exe and double click it. This will open a graphical development window in which you can design your own application window with various graphical controls. This program will generate the Win32Forth source code required to create your own program, but without all the hassle of having to type it out yourself.

Explore ForthForm’s menus. They will probably seem pretty familiar to most programmers who are accustomed to such tools, but should not be too difficult for any user to understand. There is a nice help file accessible from the help menu.

From the Form menu, click “New”. This should open a new window with Form1 in its title bar. You’ll notice that it has the same standard window functionality as our “Hello World” examples.

From the Form menu, click “Test”. This should open a new window just like the original with Form1 in its title bar. You’ll notice that it also has the same standard window functionality as our “Hello World” examples. If you had added other controls to you form, they would now act like they will when you compile the program.

If you happen to have multiple monitors like I do, you can drag these windows it to any available screen – they are not stuck inside the parent form. Pretty neat!

There are lots more things to explore in Win32Forth, we’ve just scratched the surface, but this was only “Getting Started with Win32Forth” after all. When you get tired of browsing all the links in help, the source for SciEdit and ForthForm are included - so you can see how they were made and make them better.

Don’t forget to join us in the Win32Forth Yahoo discussion group and share some of the cool things you make.

Having installed Win32Forth, and gotten to this point, you are probably starting to become familiar with the hyper-text editor/browser (and now also debugger) integrated into Win32Forth.

Typographic conventions

There are some typographic conventions used for Forth code. Firstly, this font is used for forth words; DUP SWAP ROT . And because Forth words are delimited by white space (tab, carriage return and line feed (CRLF), and blank) words line COMPILE, and COMPILE can be difficult to distinguish when there's punctuation immediately following. So all Forth words have a space before any punctuation, as in the word DUP . The full-stop has been moved away from the word. Win32Forth is, in the main, case insensitive; but it's traditional to show then in UPPERCASE rather than lowercase .

WinEd

Run WINED.EXE. WinEd is an editor written in Forth (source provided in the file WinEd.F) and integrated with Win32Forth. You will see a fairly normal looking toolbar at the top of the program window (below the menus). The toolbar provides shortcuts to often used operations like; Open, Save, Cut, Copy, Paste, Search and HyperText. If you hold your mouse cursor over one of those buttons, you will see a "tooltip" popup in a second or so, telling you what the button does.

Win32For

Run WIN32FOR.EXE. You can edit, print or load a file using the Win32Forth File menu. The Display menu allows you to easily display various types of information. The Help menu contains entries to various pieces of information including a reference to F1 which you used to get to this help file. There is also an About menu item you may have looked at, it tells a little bit about Win32Forth and the people that have worked on it.

Forth is really a command line oriented interactive environment. Even though it is nice to have menus, most of what you will do while programming an application requires typing. If you don't like typing, then maybe you are in the wrong line of work (or hobby). If you are a reader, and not an explorer, then you may have trouble with Win32Forth, since there is very limited documentation currently (although it's getting better). Having said that, lets try some of the more common utility words to help you get a feel for what using Win32Forth is like.

Click in the Win32Forth console window. Remember, you can always click back in the editor window, if you need to scroll to see more of this file. then click back in the console window, to continue typing into Forth.

Some Useful Exploring Words

WORDS displays all or a set of words from the Forth dictionary. Since Win32Forth has over 4000 functions and over 9000 constants available, you can't hope to remember the names and functions of all of them, so WORDS allows you to select a set of those words by specifying one or two substrings (partial words) following the WORDS command on the Forth command line. You don't have to worry about upper or lower case, Win32Forth is case InSeNsItIvE (but not for calling Windows procedures). Go to the Forth console window and type;

Forth will display a list of all the words in all vocabularies that contain the substring "!". The word CONSTANTS is very similar to WORDS , except it displays Windows constants that contain one or both of the following substrings. For example, if you type;

This will prove very valuable when you find yourself trying to remember how to spell the name of a needed windows constant.

Now back to WORDS . If you typed the WORDS statement as shown above, you will see the words BEEP! and +! listed in the FORTH vocabulary. Go to the Forth window and type;

You will see that BEEP! is a : (colon) definition and +! is a CODE word that gets disassembled.

WORDS shows the vocabulary where a word is located, and you must make sure the correct vocabulary is selected before using SEE to decompile it. The word that displays the current vocabulary search order is ORDER , type;

A list of the vocabularies in the search order is displayed. The Context list is the list of vocabularies that is searched, and the Current vocabulary is the vocabulary where new definitions are compiled. So for example, if you were to type;

You would see a list of words displayed, including the word .CODE (pronounced dot code) in the HIDDEN vocabulary. To see .CODE , you would type;

To select the hidden vocabulary and then decompile the word .CODE . If you then type ORDER , you will see that the top (left most) entry of the vocabulary search order is HIDDEN .

You should have seen all of the windows message constants listed. These are all of the messages windows can send to an application. Don't worry, most of these are handled automatically, you only need to handle the ones your application needs to handle in a special way. All of the standard windows constants are kept in the WINCON vocabulary.

VOCS will display some statistics on all of the vocabularies in Win32Forth. There are 12 vocabularies. The VOCS display includes information about the number of hash threads for each vocabulary, the number of words in the vocabulary, and the average hash bucket thread depth for the vocabulary. Win32Forth uses a hashed dictionary, with a variable number of hash buckets for each vocabulary defined. As you can probably guess, since most vocabularies have seven threads, seven threads is the default number of threads for a vocabulary you create. The more threads a vocabulary has, the faster it is to search that vocabulary (up to a point). But as you can see some vocabularies (like HIDDEN and ASM-HIDDEN) have a large average thread depth. This is done because those vocabularies are not searched very often.

It is useful to note that all vocabulary threads are kept in the SYSTEM dictionary, so when you create a TURNKEYed application, the vocabularies are thrown away.

You can also View the source for any word in the dictionary, with the word V or VIEW , used as;

If you type the above into the Forth console window, Win32Forth will tell WinEd to display the source for DUP . The editor will dutifully open the file FKERNEL.F and display the desired line. When viewing a word, The editor uses BROWSE mode (BLUE left border in the editor) to prevent you from accidentally changing a source file. Notice the BLUE words "Browse Mode" in the toolbar to the right of the toolbar buttons. V and VIEW search all vocabularies for the requested word, so the vocabulary search order is not important unless you have defined a particular word more than once. Return here as described in the note above.

The forth word EDIT is like V and VIEW except that WinEd is told to enter EDIT mode (CYAN left border) instead of BROWSE mode on the requested word. Notice the words "Edit Mode" to the right of the toolbar buttons for an unmodified file, and "* MODIFIED *" in RED to the right of the toolbar buttons for a file you have changes.