Xmfract General Information

This is xmfract, an X11R5/Motif version of a popular fractal generation
program named "FRACTINT". It is a graphic user interface program quite
different from that program.

The first section of this file is comprised of excerpts from the help
documentation for the original FRACTINT. The next section describes
features particular to xmfract.

This documentation assumes that the user has read "Fractal Creations
Second Edition", by Tim Wegner and Bert Tyler, published (1993) by
Wait Group Press, 200 Tamal Plaza, Corte Madera, CA 94925. If you
have not read this most excellent book, please do so. The book will
give you many insights into the creation and inner workings of fractals
and is the official user's guide to FRACTINT, the original DOS program
that this version of xmfract is based upon.

Xmfract plots and manipulates images of "objects" -- actually, sets of
mathematical points -- that have fractal dimension. See the above named
book for some historical and mathematical background on fractal geometry,
a discipline named and popularized by mathematician Benoit Mandelbrot.
For now, these sets of points have three important properties:

1) They are generated by relatively simple calculations repeated over and
over, feeding the results of each step back into the next -- something
computers can do very rapidly.

2) They are, quite literally, infinitely complex: they reveal more and
more detail without limit as you plot smaller and smaller areas. Xmfract
lets you "zoom in" by positioning a small box and hitting <d> to redraw
the boxed area at full-screen size; its maximum linear "magnification"
is over a trillionfold.

3) They can be astonishingly beautiful, especially using color displays.
You may also "animate" the images by quickly shifting color assignments.

Fractint is an experiment in collaboration. Many volunteers have joined
Bert Tyler, the program's first author, in improving successive versions.
Through electronic mail messages, first on CompuServe's PICS forum and now
on GRAPHDEV, new versions are hacked out and debugged a little at a time.
Fractint was born fast, and none of us has seen any other fractal plotter
close to the present version for speed, versatility, and all-around
wonderfulness. (If you have, tell us so we can steal somebody else's ideas
instead of each other's.)

Hints:

In general, the most interesting areas are the "border" areas where the
colors are changing rapidly. Zoom in on them for the best results. The
first Mandelbrot-set (default) fractal image has a large, solid-colored
interior that is the slowest to display; there's nothing to be seen by
zooming there.

Plotting time is directly proportional to the number of pixels in the
window, and hence increases with the size of the window. You may want to
start in with the default 640 x 480 pixel window for quick progress
while zooming in, and switch to a larger window when things get interesting.
zooming in, and switch to a higher-resolution mode when things get
interesting. Or use the solid guessing mode and pre-empt with
a zoom before it finishes. Plotting time also varies with the maximum
iteration setting, the fractal type, and your choice of drawing mode.
Solid-guessing (the default) is fastest, but it can be wrong: perfectionists
will want to use dual-pass mode (its first-pass preview is handy if you
might zoom pre-emptively) or single-pass mode.

Ken Shirriff has ported FRACTINT to UNIX, using an interface almost
identical to the original FRACTINT. That version of the program is
named xfractint and has several advantages over this version, and may
be preferable for many users. Those differences include the ability to
use the disk video mode, and that the interface has the same
look-and-feel of the original FRACTINT, among many others.

Xmfract differs from FRACTINT and xfractint in many ways. The first and
most obvious of these is the graphic user interface. Many of the same
keystrokes will invoke familiar menus, and some other keystrokes are
changed or non-existent. Please browse each of the menus on the menu
bar to become familiar with their contents.

The letter to the right of the menu item indicates the letter which may
be typed to invoke that menu item. This is called a menu item accelerator.
The menu does not need to be displayed to invoke the item with the
accelerator letter.

Xmfract supports tear-off menus, if the user has not specifically
prevented it by an entry in the resource file. Menus may be "torn off",
or posted in windows of their own (seperate from the main window), by
selecting the dashed line at the top of the menu. To dismiss any torn-off
menu, press the 'Esc' key while the pointer is in the menu window.

Options may be specified on the command line or in a parameter file
(<filename>.par) or in a startup command file named "xmfract.ini".

If fractdir=<directory> (see below) is set on the command line or if
XMFRACTDIR is set in the environment, the "xmfract.ini" file may reside
in the directory pointed to by whichever of these methods has taken
precedence (again, see below). Otherwise, the "xmfract.ini" file must
reside in the directory from which you invoke xmfract for the program
to recognize it.

The help files must reside in a subdirectory of <fractdir>. If
helpdir=<directory> is set in the "xmfract.ini" file, the program
will look in <fractdir/<helpdir> for the help files. If it is not set,
the program expects the the help files to be in a subdirectory of
"fractdir" named "help" (<fractdir>/help).

Some new options may be of note - the author credits screen that pops
up when the program lifts off may enabled or disabled with the
command-line or startup-file option "creditscreen=". An xmfract.ini
entry of "creditscreen=no" will prevent the credits screen from
popping up when the program starts. Of course, the credits may be
viewed at any time by selecting "Display authors window" from the
"Authors" menu (or by hitting the "w" key) regardless of the
creditscreen option.

Another important option is "fractdir=". When this option is set,
it tells xmfract where to find all of the ancillary files. Note that
the operation of this variable is different than that of the same
variable in FRACTINT. If it is set in "xmfract.ini", it should be the
first line in the file. The directory may also be specified on the
command line or by setting an environment variable named "FRACTDIR"
to the desired directory. If this option is not set, xmfract assumes
that all of the ancillary files are in the current working directory.

The order in which this option is processed is:

  The environment is checked first. If FRACTDIR is set in the environment,
  fractdir is set to the named directory. If FRACTDIR is not set in the
  environment, fractdir is set to the current working directory.

  The command line is checked next. If fractdir= is specified,
  fractdir is set to the named directory, overriding any previous
  setting of the variable.

  The initialization file is checked next. If fractdir= is specified,
  fractdir is set to the named directory, overriding any previous
  setting of the variable.

Experienced xmfract users may want to set the "verbose=" option. This
option (sometimes in concert with the "overwrite=" option) when set
set to "verbose=yes" will prevent some of the more obvious dialogs
from being presented. For example, the program usually asks the user
to confirm creation of image or parameter files, or whether to resize
a window to fit an image to be read. These messages and some other
dialogs will not appear when this option is set to "yes".

Setting the "overwrite=" option to "overwrite=yes" will cause the
program to automatically overwrite existing files (such as parameter
files or images), without asking the user -- if the verbose option
is not set to "yes".

I recommend that you become familiar with the dialogs that appear
periodically during the course of this program before setting the
verbose option to "no" or the overwrite option to "yes". That will
prevent you from becoming confused by unexpected behavior from xmfract.

A new menu item has been added to allow the user to explicitly set
the size of the main window. The default size is 640 x 480 pixels,
and the maximum size is 2048 x 2048. Only the size of the menu bar is
taken into account when calculating the maximum size for a fully
visible image (the window manager decorations, such as borders,
etc., are not considered). That means that if you resize the window
to the maximum size for a fully visible image, the borders may be off
the screen, but the image canvas will be fully visible. In addition,
if the user elects to load a GIF image that was created in a size that
is different from the current window size, the user is given the option
to resize the window to fit the new image.

There is an option menu associated with the "Set window size" dialog.
Press the left mouse button when the pointer is in the button and an
option menu will appear that allows the user to select from several
preconfigured window sizes, including the maximum size for a fully
visible image. Pressing the "Default" pushbutton will set the window
to the pre-selected default size of 640 x 480 pixels. The normal
aspect ratio for the program (the ratio of width to height) is 4:3,
and the program figures out the aspect ratio of the root window on
your display and configures several preset values in that aspect
ratio as well. To resize the window to any of these values, select
the desired menu item.

There are a maximum of 10 parameters sets that are automatically logged
by the program. You may re-create a previously created image by using
the "Restore" menu.

The user may reset the color, clear the screen, or reset the fractal
parameters from a menu selection. One may also choose to reset all of
the above from the same menu.

To generate a fractal, select the fractal type by invoking the
"Fractals" menu (or hitting the "t" key). By default the basic
Mandelbrot type is selected. Parameters for the selected type will
be displayed. Change these if desired, then select "Create Image"
from the "Draw" menu (or hit the "d" key).

Other parameter selection is found under the "Options" menu. I have
attempted to make these selections appear (as much as possible) as they
appear in FRACTINT. Again, please read the above-mentioned book for
a MUCH more detailed explanation of these and other options, and peruse
the on-line help system for more information.

Motif user interface:

If, in any application, you need to click the mouse in a window before
typing any information in that window, then the focus policy is set to
"pointer". If, when the mouse pointer is moved into a window, you are
able to type into that window without having to click the mouse button
first, the focus policy is set to "explicit". Either method is perfectly
OK, and a matter of personal taste. We just need to know because it
effects that way that all applications running under that window
manager accept keyboard and mouse input.

If your focus policy is "pointer" then, in the following steps, activate
each window before following these steps by clicking the mouse in the
title bar of the window. If the focus policy is explicit, then just
move the mouse into the window to activate it.

Before we begin, edit ~/Xmfract (xmfract's X resource file) -- change the
line that reads:

Xmfract*highlightThickness: 0

to read:

Xmfract*highlightThickness: 3

(More on this resource at the end of the tutorial...)

Please start xmfract.

Press "x" (or use the menu to select Basic Options).

Notice that there is a color band around the "Done" button.

Also around the "Done" button, there is a 3D-looking box. Depending
on what colors you or your window manager have set for this application,
the box may appear to be recessed into the screen, or protruding out
from it.

Now press the "Tab" key. Notice that, now, the color band has moved to
the top button in the top left radio box.

Use the cursor arrow keys (Up/Down or Right/Left) to move this color
band to the other buttons in this radio box.

The color band represents the "active" widget.

While this color band surrounds a button or any other widget, any keyboard
key press (except Return or Enter) will affect only this widget.

Press "Tab" again.

Now, the color band surrounds the center radio box's top button, and the
cursor arrow keys activate (but do not actually change the settings of)
the buttons in this radio box.

Press Tab until the color band surrounds one of the scale (slider) widgets.

Depending on your keyboard and X server key mappings, the cursor arrow
buttons may or may not affect the activation or settings of these
types of widgets.

Press Tab until the color band surrounds one of the buttons at the bottom
of the dialog.

Now, the cursor arrow keys will select the activation of the buttons.

Notice that the 3D-looking box which surrounds the button will also
follow the color band.

The purpose of these steps is to illustrate how Motif combines widgets in
logical groups.

The cursor arrow keys affect the activation of widgets in one logical group.

Pressing the "Tab" key will select the next logical group (or an individual
widget, if it is not part of a logical group, like the sliding scales).

Depending on your keyboard and X server key mappings, the cursor arrow
buttons may or may not affect the activation or settings of these
types of widgets.

Notice that pressing the left mouse button down on any widget will cause
that widget to be activated (also changing the logical group, if applicable).

The 3D-looking box represents the default button. This is the widget that
will be activated when the Return or Enter key is pressed. This selection
is separate from the active widget. The default button does not have to
be the active widget for the Return or Enter key to activate it.

Using only the Tab key and the cursor (or keypad) arrow keys, move the
active widget color band around in this dialog to become familiar with
this sort of logical grouping.

Now, close the Basic Options dialog by pressing the "Done" or "Cancel"
button. Use any method you desire -- either press the left mouse button
down while the pointer is in the button, or use a combination of the
Tab and cursor arrow keys to activate the desired button, then press
Return or Enter.

Now select "Help Index" from the main menu bar "Help" menu.

Note that the textfield (the place where text may be entered -- the small
box in the center of the dialog) is automatically selected as the active
widget.

Leave this widget as the active widget (or activate it by using the Tab key).

Now press the cursor arrow keys. Notice that the selection in the list box
will change!

These text and list widgets are special cases. The cursor arrow (Up/Down)
keys will affect the selection index in the list, but any other keyboard
key pressed (again, except Return or Enter) will be displayed in the text
field.

Also note that the cursor arrow (Left/Right) keys will affect the
position of the "I" cursor in the text field, if the text field is active
and can be edited.

Activate (make the color band surround) the big list box. Now use the
(Left/Right) cursor arrow keys. Since this list is not editable, the
position of the "I" cursor will not change. Also, any other key press
will cause an error beep, because the program assumes you are trying
to edit this text, which is not editable.

Now activate the small text field again. Note that the cursor arrow
(Left/Right) keys will cause the position of the "I" cursor to change,
and any text that is typed will be inserted before the "I" cursor.

The left mouse button may also be used to set the position of the "I"
cursor, and double- and triple-clicks of the mouse will select (highlight)
a word or line, respectively.

Any text typed in the text field will replace any highlighted text.

List selection dialogs are also special in that double-clicking the left
mouse button down on any list item causes the program to assume that the
selected item is to be processed just as if you had selected the item
with the mouse (or typed that text in the text field) then pressed the
"OK" button.

Activate the big list selection box by using the Tab key or the mouse.

Now double-click the mouse on any desired topic from the list, and notice
that the associated help dialog is automatically displayed.

In the Help Index dialog, note that the buttons at the bottom of the dialog
form a logical group just as they did in the Basic Options dialog.

This concludes this tutorial. It is by no means complete or comprehensive.
For more information, please see any of the available documentation about
Motif at your site and/or on your particular hardware platform.

The highlight bar that surrounds the active widget may be customized
to any thickness or color that you desire. If the thickness is set to
zero, or if the color is set to the same color as the foreground color
of the application, the bar is invisible. Experiment with different
thickness settings to determine which is most pleasing to you.
Xmfract does not need to be re-compiled when any resource is changed.
You just need to quit the application and restart it for the new
resources to take effect.

Also, the length of time between clicks of the left mouse button that
tells the program that a double-click (or triple, or quadruple) may
also be set using your particular window manager's resources. For
more information on this, and on color and the hundreds of other
resource customization options available, please see the documentation
for Motif and/or your window manager that should be available through
the man pages on your system. If they are not, please contact your
system administrator to determine the location of documentation for
your site.