Help directory added

parent be87de01
<HEAD><TITLE>bigFORTH Documentation</TITLE></HEAD>
<H1>bigFORTH Documentation</H1>
<H2>Bernd Paysan <A HREF="">
<P><I>This manual describes bigFORTH and MINOS</I>
<H2><A NAME="toc1">1.</A> <A HREF="minos.html">MINOS</A></H2>
<H2><A NAME="toc2">2.</A> <A HREF="theseus.html">Theseus</A></H2>
<ADDRESS><hr size=5>
<A HREF="">Bernd Paysan</A>,
17may1998, 17may1998<BR>

515 Bytes

<HEAD><TITLE>Minos Documentation</TITLE></HEAD>
<IMG SRC="previous.jpg" ALT="Previous" Border=2>
<A HREF="minos-2.html"><IMG SRC="next.jpg" ALT="Next"></A>
<A HREF="minos.html#toc1"><IMG SRC="toc.jpg" ALT="Table of Contents"></A>
<H1><A NAME="s1">1. Introduction</H1>
<H2>What's MINOS?</H2>
<P>MINOS is the answer to the question ``Is there something like
Visual BASIC (Microsoft) or Delphi (Inprise) in Forth?'' - and the
answer is ``yes''.</P>
<P>Basically, these GUI RADs contain two components: a library with a
wide variety of elements for a graphical user interface; e.g. windows,
buttons, edit-controls, drawing areas, etc.; and an editor to combine
the elements with the mouse by drag&amp;drop or click&amp;point
actions. Missing code then is inserted to add actions when buttons are
<P>Typical applications are often related to data base
access. Therefore, many of these systems already contain a data base
engine or at least a standardized interface to a data base, such as
<P>Another aspect are complex components. With some of these toolkits,
you can create a web browser with some mouse clicks and a few
keystrokes. However, these components hide their details, a shrink
wrapped web browser application is not necessarily worse.</P>
<P>The interactivity of these tools usually is not very high. You
create your form, write your actions as code and compile it more
(Delphi) or less (Visual Age for C++) fast. Trying it usually isn't
possible before the compiler run.</P>
<H2>Why Visual?</H2>
<P>It isn't really necessary to brush graphical user interfaces
together, as it isn't to edit texts WYSIWYG. Many typesetting
functions are more semantically than visual, e.g. a text is a headline
or emphasized instead of written in bold 18 point Garamond or 11 point
Roman italics. All this is true for user interfaces, to some extend
much more. It's not the programmer that decides which font and size to
use for the UI - that's up to the user. As is color of buttons and
<P>Also to layout individual widgets, more abstraction than defining
position, width and height makes sense. Typically buttons are arranged
horizontally or vertically, perhaps with a bit distance between
them. The size of buttons must follow the containing strings, and
should conform to aesthetics (e.g. each button in a row has the same
<P>Such an abstract model, related to TeX's boxes&amp;glues, programs
quite good even without a visual editor. The programmer isn't
responsible for ``typesetting'' the buttons and boxes. This approach
is quite usual in Unix. Motif and Tcl/Tk use neighborhood relations,
Interviews uses boxes&amp;glues. I decided for boxes&amp;glues, since it's a
fast and intuitive solution, although it needs more objects to get the
same result.</P>
<P>These concepts contradict somehow with a graphical editing process,
since the editors I know don't provide abstract concepts (``place left
of an object'' or ``place in a row''), but positions.</P>
<H2>Visual Forth?</H2>
<P>One point makes me think: the packets that allow real visual form
programming have many years of programming invested in. Microsoft,
Borland, and IBM may hire hundreds of programmers just for one such
project. This man-power isn't available for any Forth project. But
<LI> Forth claims that good programmers can work much more
efficient with Forth
<LI> A team of 300 (wo)men blocks itself. If the boss partitions the
work, the programmers need to document functions, and to read
documents from other programmer related to other functions and must
understand them, or ask questions to figure things out. Everybody
knows that documenting takes much longer than writing the code, and
explaining is even worse. Thus at a certain project complexity level,
no time is left for the programming task; all time is used to specify
planned functions and read the specification from other
programmers. Or the programmers just chat before the door holes of the
much too small and noisy cubicles.
<LI> A good programmer reportedly works 20 times as fast as a bad,
even though he can't type in more key strokes per time. The resulting
program is either up to 20 times shorter or has 20 times less bugs (or
both) - with more functionality at the same time. Teamwork however
prevents good programmers from work, since they are frustrated by bad
programmers surrounding them, from their inability to produce required
information in time; and the bad programmers are frustrated by the
good ones, which makes them even worse.
<LI> Therefore, even in large projects, the real work is (or should
be) done by a small ``core team''. Then the Dilbert rule applies: what
can be done with two people, can be done with one at half of the
Furthermore, bigFORTH-DOS already contains a ``Text-GUI'', without
graphical editor, but with an abstract boxes&amp;glue concept, which, as
claimed above, hinders the use of such an editor.</P>
<P>Finally I wanted to get rid of DOS, and port bigFORTH to a real
operating system (Linux). In contrast to Windows and OS/2, user
interface and screen access are separated there. Drawing on the screen
uses the X Window System (short X), the actual user interface is
implemented in a library. This is the reason, why there is no common
interface, but a lot of different libraries, such as Athena Widgets,
Motif, Tcl/Tk, xforms, Qt, gtk, and others. The ``look and feel'' from
Motif-like buttons is quite common, even Windows and MacOS resemble
<P>All these libraries have disadvantages. The Athena Widgets are
hopelessly outdated. Motif is commercial, even if a free clone
(Lesstif) is in creation. It's slow and a memory hog. Tcl/Tk consumes
less memory, but it's <EM>even</EM> slower. How do you explain your
users that drawing a window takes seconds, while Quake renders
animated 3D-graphic on the same machine? Qt is fast, but it's written
in C++ and doesn't have a foreign language interface now. gtk, the
GIMP toolkit, has more foreign language interfaces, and it's free, but
it wasn't available until recently.</P>
<P>Therefore I decided to port the widget classes from bigFORTH-DOS
to X, and write an editor for it. Such classes written in Forth
naturally fit in an development environment and are - from the Forth
point of view - easier to maintain. There are not such many widget
libraries in C, because it's a task written in an afternoon, but
because the available didn't fit the requests, and a modification
looked desperate.</P>
<H2>The Name - Why MINOS?</H2>
<P>``Visual XXX'' is an all day's name, and it's too much of a
microsoftism for me. ``Forth'' is a no-word, especially since the
future market consists of one billion Chinese, and for them four is a
number of unluck (because ``se'' (four) sounds much like ``se''
(death)). However, even Borland doesn't call their system ``Visual
TurboPascal'', but ``Delphi''.</P>
<P>Greek is good, anyway, since this library relates to the
boxes&amp;glues model of TeX, which is pronounced Greek, too. Compared
with Motif, the library is quite copact (MINimal), and since it's
mainly for Linux, the phonetic distance is small... I pronounce it
Greek: ``meenoz''.</P>
<H2>Port to Windows</H2>
<P>I ported MINOS to Windows 95/NT, on the demand of some potential
users. It doesn't run near as stable as under Linux/X, since there are
a hideous number of subtle bugs in Windows, and I don't have the time
to work around all of them. Drawing polygons doesn't work as well as
on X, and all the bugs that are in the memory drawing device can drive
me nuts. The Windows port of MINOS looks more like the ``modern
Forth'' Claus Vogt portrayed in <A
HREF="news:de.comp.lang.forth">de.comp.lang.forth</A>: it shows random
general protection faults. Well, just like any other Windows
<IMG SRC="previous.jpg" ALT="Previous" Border=2>
<A HREF="minos-2.html"><IMG SRC="next.jpg" ALT="Next"></A>
<A HREF="minos.html#toc1"><IMG SRC="toc.jpg" ALT="Table of Contents"></A>
<ADDRESS><hr size=5>
<A HREF="">Bernd Paysan</A>,
09feb1999, 09feb1999<BR>
<HEAD><TITLE>Widget Classes</TITLE></HEAD>
<A HREF="minos-1.html"><IMG SRC="previous.jpg" ALT="Previous"></A>
<A HREF="minos-3.html"><IMG SRC="next.jpg" ALT="Next"></A>
<A HREF="minos.html#toc2"><IMG SRC="toc.jpg" ALT="Table of Contents"></A>
<H1><A NAME="s2">2. Widget Classes</A></H1>
<P>The primary classes of MINOS are gadgets (widgets and displays),
actors, and resources (xresource and font).</P>
<P>Resources just provide system-specific data like window handles,
display pointers, font informations, etc., they are critical for
system-specific parts of display implementations.</P>
<P>Widgets are the central objects represented on screen. Widgets draw
through displays, such as windows, viewports, etc. Since many displays
can be embedded into a bigger window, they also have all widget
functionality. Widgets are composed in boxes (horizontal and
vertical), and automatically layouted. Boxes certainly are widgets
themselves, and some of the more complicated widgets such as sliders
or textboxes are derived from boxes to layout the inner parts easily.</P>
<P>Actors are bound to associated actions when operating a widget
(i.e. clicking on it, pointing on it, or entering text). Actors
provide the way to script actions.</P>
<H2><A NAME="ss2.1">2.1 Actors</A></H2>
<DD><P>All Actors have the following methods in common:
<LI><B>called</B> This variable points to the object that is being called
<LI><B>caller</B> This variable points to the object that is
calling (the widget).
<LI><B>set</B> ( -- ) sets the flag
<LI><B>reset</B> ( -- ) resets the flag
<LI><B>toggle</B> ( -- ) toggles the flag
<LI><B>fetch</B> ( -- x1 .. xn ) queries the value(s)
<LI><B>store</B> ( x1 .. xn -- ) changes the value(s)
<LI><B>click</B> ( x y b n -- ) performs the action for a click
<LI><B>key</B> ( key sh -- ) performs the action for a keystroke
<LI><B>enter</B> ( -- ) performs the action for entering the widget
<LI><B>leave</B> ( -- ) performs the action for leaving the widget
<LI><B>assign</B> ( x1 .. xn -- ) initially assigns the state
<LI><B>set-called</B> ( o -- ) sets the called object
The stack effect you see below is the stack effect of the init method.</P>
<DD><DL><DT><B>KEY-ACTOR</B> This is an actor for keyboard macros. It
inserts keystrokes into the called widget.
<DT><B>TOOLTIP</B> ( actor tip -- ) A tooltip is a nested actor; it shows
the widget tip some time after entering with the mouse, and forwards the other
messages to actor
<DT><B>EDIT-ACTION</B> ( o xt -- ) This actor handles text input field key
events, and does all the editing stuff. After each keystroke and each click,
it calls xt ( -- ).
<DD><DL><DT><B>NUMBER-ACTION</B> ( o xt -- ) Same as EDIT-ACTION, but filters
out digits only
</DL></DL><DD><DL><DT><B>SCALE-VAR</B> ( o pos max -- ) Scaler actor,
keeps position and maximum value in own variables.
<DD><DL><DT><B>SCALE-DO</B> ( o pos max xt -- ) Same as SCALE-VAR, but executes
xt ( pos -- ) on changes
<DT><B>SLIDER-VAR</B> ( o pos max step -- ) Slider actor, keeps position,
step, and maximum value in own variables
<DD><DL><DT><B>SLIDER-DO</B> ( o pos max step xt -- ) Same as SLIDER-VAR,
but executes xt ( -- ) on changes
</DL></DL><DT><B>SIMPLE</B> ( o xt -- ) xt is executed at every store (no
state maintained)
<DD><DL><DT><B>DRAG</B> ( o xt -- ) Calls toggle on each click event
<DT><B>REP</B> ( o xt -- ) Calls toggle repeatedly while the user holds down
the mouse button
</DL><DT><B>TOGGLE-STATE</B> ( o xtstore xtfetch -- ) allows generic fetch
and store functions
<DD><DL><DT><B>SCALE-ACT</B> ( o do-store do-fetch max -- ) Generic slider
actor (maximum slider position provided)
<DD><DL><DT><B>SLIDER-ACT</B> ( o do-store do-fetch max -- ) Generic scaler
actor (maximum scaler position provided)
</DL></DL><DT><B>TOGGLE-VAR</B> ( o addr xt -- ) keeps the flag in addr,
and executes xt on changes
<DD><B>TOGGLE-NUM</B> ( o n addr xt -- ) is responsible for state n in addr
(sets addr to n when set), and executes xt on changes
<DT><B>TOGGLE</B> ( o state xtset xtreset -- ) models a flag with
initial state and two functions for each state
<H2><A NAME="ss2.2">2.2 Resources</A></H2>
<H2><A NAME="ss2.3">2.3 Widgets</A></H2>
<H2><A NAME="ss2.4">2.4 Boxes</A></H2>
COMBINED 44 E4 40139938
VBOX 44 E4 4013B15C
SLIDERVIEW 4C E8 40146360
VSLIDER 44 E8 401423B4
VSCALER 50 EC 401434F4
VSLIDER0 44 E8 40142B74
VRBOX 44 E4 40140E74
VTBOX 44 E4 4013C59C
VRTBOX 44 E4 4014163C
VATBOX 44 E4 4013CB70
VARTBOX 44 E4 40141760
VASBOX 4C E8 40147340
VRESIZE 44 E4 40146FF0
MODAL 48 E4 401418AC
VARBOX 44 E4 40141058
HBOX 44 E4 4013A84C
INFO-MENU 54 E4 4014CA70
HSLIDER 44 E8 40141D94
HSCALER 50 EC 40142E98
HSLIDER0 44 E8 4014292C
HRBOX 44 E4 401411B8
HTBOX 44 E4 4013C0E8
HRTBOX 44 E4 401413F8
HATBOX 44 E4 4013CA50
HARTBOX 44 E4 4014151C
HABOX 44 E4 4013BFC8
HASBOX 4C E8 40147558
HRESIZE 44 E4 40147138
HARBOX 44 E4 401412D8
TEXTFIELD 48 E4 40140A08
(NIL 24 C8 40137B80
GLUE 34 C8 401379F8
GLCANVAS 58 CC 4014B670
RULE 38 C8 40138458
CANVAS 78 118 40138FCC
MFILL 38 C8 40138A48
MSKIP 38 C8 40138908
SSKIP 40 C8 40146178
VRULE 38 C8 40138734
HRULE 38 C8 40138618
VGLUE 34 C8 40138308
HGLUE 34 C8 401381EC
TOPGLUE 34 C8 4013E908
ICON 28 C8 401377E4
<H2><A NAME="ss2.5">2.5 Displays</A></H2>
DISPLAYS 90 178 4012FC60
WINDOW A4 194 40148B18
MENU-WINDOW A4 194 4014D09C
FRAME A8 1A4 4014A698
MENU-FRAME A8 1A4 4014C0D0
WINDOW-STUB A4 194 4014A2C0
(NILSCREEN 90 178 40137D00
BACKING A8 17C 40131DD0
VIEWPORT E0 190 40143EB4
SCRVIEWPORT E0 190 40123590
HVIEWPORT E8 190 40145F14
VVIEWPORT E8 190 40145CC4
BEAMER B8 180 401330F8
<A HREF="minos-1.html"><IMG SRC="previous.jpg" ALT="Previous"></A>
<A HREF="minos-3.html"><IMG SRC="next.jpg" ALT="Next"></A>
<A HREF="minos.html#toc2"><IMG SRC="toc.jpg" ALT="Table of Contents"></A>
<ADDRESS><hr size=5>
<A HREF="">Bernd Paysan</A>,
09feb1999, 21jul1999<BR>
\ No newline at end of file
This diff is collapsed.
<HEAD><TITLE>Minos Documentation</TITLE></HEAD>
<H1>Minos Documentation</H1>
<CENTER><IMG SRC="minos-logo.jpg"></CENTER>
<H2>Bernd Paysan <A HREF="">
<P><I>This manual describes the GUI library MINOS</I>
<H2><A NAME="toc1">1.</A> <A HREF="minos-1.html">Introduction</A></H2>
<H2><A NAME="toc2">2.</A> <A HREF="minos-2.html">Widget Classes</A></H2>
<H2><A NAME="toc3">3.</A> <A HREF="minos-3.html">Support Classes</A></H2>
<LI><A HREF="minos-3.html#ss3.1">3.1 3D Turtle Graphics</A>
<LI><A HREF="minos-3.html#ss3.2">3.2 SQL Interface</A>
<ADDRESS><hr size=5>
<A HREF="">Bernd Paysan</A>,
09feb1999, 09feb1999<BR>

218 Bytes

<HEAD><TITLE>Theseus Documentation: Introduction</TITLE></HEAD>
<IMG SRC="previous.jpg" ALT="Previous" Border=2>
<A HREF="theseus-2.html"><IMG SRC="next.jpg" ALT="Next"></A>
<A HREF="theseus.html#toc1"><IMG SRC="toc.jpg" ALT="Table of Contents"></A>
<H2><A NAME="s1">1. Introduction</A></H2>
<P><B>Theseus</B> is designed to create <B>MINOS</B> dialogs. Each
dialog is derived form a window class. You can create dialogs by
composing boxes (layout managers) and widgets together, glue actions
to the widgets, add variables and methods to the derived window
classes, and so on.</P>
<P>This is the help system, called ``Ariadne'', since it is the red
line that leads you through the labyrinth of MINOS. This chapter will
give some informations about the philosophy behind MINOS and Theseus,
so you understand what you are doing.</P>
<P>MINOS has four sets of classes:
<LI><B>Widgets:</B> ``window gadgets'', these are the basic objects
like buttons, labels, icons and text fields.
<LI><B>Displays:</B> these widgets are the drawing area of other
widgets. They know how to draw to X or to the parent display. It's
also possible to create new displays that e.g. draw into an OpenGL
widget or send drawing events over the network, to copy drawing
messages to more than one parent display and so on.
<LI><B>Boxes:</B> or layout managers. Although each object in MINOS
has coordinates and size, it's formating is done by a surrounding
layout manager. These either form horizontal boxes, and align their
contents from left to right, or vertical boxes, and align their
contents from top to bottom. Each widget has a horizontal and a
vertical glue, these glue values are used to compute a nice look of
the widgets.
<LI><B>Actions:</B> these are the objects that link data and widgets
together. An action knows in which state it is, and what to do when
the state changes. There are several types of actions, for simpe
buttons, toggle buttons, text fields, and sliders.
<P>Each dialog is hierarchically composed out of widgets, boxes, and
displays (e.g. viewports). Each active object, thus each button,
toggle button, slider, and text field has an associated action, a
name, and other attributes.</P>
<P>The next chapter will describe how to use Theseus, and which
classes and messages are available.</P>
<P>I hope you will find this program somehow useful and I would
appreciate any suggestions and comments.</P>
<P><A HREF="">Bernd Paysan
<IMG SRC="previous.jpg" ALT="Previous" Border=2>
<A HREF="theseus-2.html"><IMG SRC="next.jpg" ALT="Next"></A>
<A HREF="theseus.html#toc1"><IMG SRC="toc.jpg" ALT="Table of Contents"></A>
<ADDRESS><hr size=5>
<A HREF="">Bernd Paysan</A>,
1997-09-14, 1998-01-25<BR>
<HEAD><TITLE>Theseus Manual: Onscreen Fundamentals</TITLE></HEAD>
<A HREF="theseus-1.html"><IMG SRC="previous.jpg" ALT="Previous"></A>
<A HREF="theseus-3.html"><IMG SRC="next.jpg" ALT="Next"></A>
<A HREF="theseus.html#toc2"><IMG SRC="toc.jpg" ALT="Table of Contents"></A>
<H1><A NAME="s2">2. Onscreen Fundamentals</A></H1>
<H2><A NAME="ss2.1">2.1 Menu</A></H2>
<IMG SRC="menu.gif" ALT="Menu bar">
<P>The menu bar contains a file menu, an edit menu and a help menu.</P>
<H2><A NAME="ss2.2">2.2 Widget bar</A></H2>
<IMG SRC="widget.gif" ALT="Widget bar">
<P>The widget bar contains groups of widgets. To insert a widget into
a dialog, select the group and click on a button. The corresponding
widget is inserted in the current position (affected by the mode
<H2><A NAME="ss2.3">2.3 Editing modes</A></H2>
The editing modes are separated into four groups:
<table width=100%>
<tr><td><IMG SRC="modes.gif" ALT="Editing modes"></td>
<UL><LI>Click modes:
<UL><LI>Edit mode: clicking opens the inspector of that object, with
focus on the text/code/name field (left/middle/right mouse button).
<LI>Cut&amp;Paste mode: clicking left cuts the object to the cut stack,
clicking middle or right pastes from the cut stack.
<LI>Try mode: clicking makes the object react as in the dialog, but
without executing code.
<LI>Insert modes:
<UL><LI>Add object first in current box
<LI>Add object last in current box
<LI>Add object before current box
<LI>Add object after current box
<LI>Navigation, selects the active box. Note that there is an active
widget (which you can select with the mouse pointer).
<UL><LI>Move one box up in hierarchy
<LI>Move one box to the left/up
<LI>Move one box to the right/down
<LI>Move to the first child
<LI>Short cuts:
<UL><LI>Load dialog
<LI>Save dialog
<LI>Try dialog
<LI>Save as module
<H2><A NAME="ss2.4">2.4 Dialog editor</A></H2>
<IMG SRC="dialog.gif" ALT="Dialog editor">
<P>The dialog editor shows a navigation bar for each dialog to
edit. The dialog itself is resizable with the split bar below and on
the side, to see how it looks resized.</P>
<P>The navigation bar consists of an icon to open/hide the dialog, to
open/hide the declarations field, to open/hide the code field, to
select whether to show the dialog, a dialog menu, a dialog title and a
dialog name. It is important to give every dialog a name, since
dialogs without names can't be saved. The dialog name is the name of