Atari FTP/ATARI_FTP_0693.zip/ATARI_FTP_0693/Mint/toswin14.zoo/toswin.doc

Text File | 1992-10-27 | 16KB | 393 lines

TOSWIN: a background program accessory for MiNT
Written by Eric R. Smith ([e-mail])

This version of TOSWIN is copyright 1992 Eric R. Smith. All rights
reserved.

TOSWIN is a simple accessory that gives an easy way of running
TOS programs in the background of a GEM session. Selecting this accessory
pops up a window with a scrapbook icon and a menu bar. The menu bar
contains drop down menus; to open a window, select "Open Std Window"
or "Open Alt Window" from the "File" menu. This will pop up a file
selector box; use this box to select the program you want to run. Of
course, this should *not* be a GEM program; you already have a GEM program
running, or you wouldn't be able to get to the accessory. GEM will likely
become horribly confused if there are two programs making GEM calls
simultaneously.

Closing the TOSWIN window has the effect of closing the accessory, so
that all windows are hidden. They will all re-appear when "TOS programs"
is selected again from the DESK menu.

Closing any other window kills all the programs running in that window.
Be careful!

Note that TOSWIN may also be run as an ordinary program; to do this,
just change the extension from '.acc' to '.prg'.

MENUS

File:
    Open Std Window
    Opens a standard size (i.e. the same size as the line A variables)
    window.
    Open Alt Window
    Opens a different size window. The size defaults to 80x50, but
    this may be changed with the "Set Alt Window Size..." Global
    menu entry.
    Close
    Closes the topmost window.
    Load Config...
    Loads a configuration file previously saved by Save Config...
    TOSWIN looks for a config file called TOSWIN.CNF when starting
    up, and loads it automatically if found.
    Save Config...
    Save the current menu settings and position of the scrapbook icon
    in a file. The user is prompted for whether or not to save
    window positions.
    Set Menu Keys...
    Allows keyboard equivalents to be established for any menu entries.
    Any key (except spacebar) may be used as a menu equivalent, although
    obviously the use of standard ASCII codes would be undesirable :-(.

    Quit
    Exit TOSWIN after sending SIGHUP to all child processes.

Edit:
    Copy
    Copies the currently selected region in the top window to the
        scrapbook.
    Paste
    Pastes the contents of the scrapbook into the top window.
    Paste Options...
    Controls how data is copied and pasted; for example, whether end
    of line should be sent to applications as a carriage return,
    line feed, or combination.

Global:
    Align Windows
    If this is set, TOSWIN will adjust all windows so that the text
    inside them falls on a byte boundary. This should speed up
    the VDI output a bit, at least for fixed width fonts that are
    8 pixels wide.
    Application Menus
    If this option is set, and a window is opened for which an associated
    .MNU file is found, then the application's menu will be loaded and
    displayed in the status line of the window.
    Autoclose
    If this option is set, windows are automatically closed when no more
    processes can send data to them. Otherwise, the string <EXITED>
    is written to the window and it remains open until the user closes
    it manually.
    Flourishes
    If set, grow/shrink boxes appear for windows and dialog boxes.
    Point to type
        If set, input is sent to whatever window the mouse pointer is
    currently over (so you only have to point at a window to type
    into it). Otherwise, input always goes to the top window.
    Smooth Scrolling
    Causes the window contents to be updated more often (after every line)
    if set.
    Set Std Window Size...
    Sets the number of rows and columns for windows opened with the
    "Open Std Window" menu option, or which are run via TOSRUN.
    This option also changes the line A variables to reflect the
    new "standard" size. When specifying a window's rows and
    columns, you may also specify a "scrollback" size. This many rows
    of data are kept around even after they scroll off the top of
    the window, and may be accessed via the vertical scroll bar and
    scroll arrows (or via any keys assigned to the "Gadgets/Scroll Up"
    and "Gadgets/Scroll Down" menu items).
    Set Alt Window Size...
    Sets the number of rows and columns for windows opened with the
    "Open Alt Window"
    Set Default Font...
    Sets the default font for new windows. Any GDOS font may be used
    in a window (this assumes, of course, that you're running GDOS!).
    Even proportional fonts may be used, although they may produce
    strange looking results if used with certain programs :-).
    Set Default Gadgets...
    Sets the default gadgets for new windows. Windows may have no
    gadgets, a title bar (including closer and fuller), or a full
    complement of gadgets including sizer, sliders, arrow, and title
    bar. Windows may also have a menu bar; if a .MNU file is found
    that goes with the program being started in the window, it may
    be loaded and displayed. If no .MNU is found, no menu is displayed
    for this window.
    Environment...
    Instructs TOSWIN about how to set up the environment for new
    processes. The default setting (use ARGV, and set TERM, TERMCAP,
    LINES, and COLUMNS) is the one usually desired.
    Redraw Screen
    Sends a redraw message to all windows, and re-draws the menu
    bar as well.

The "Window" and "Gadgets" menus are only applicable to the topmost window,
and since the topmost window is the "TOSWIN" window when the menu is
active, they items in these menus cannot be accessed directly. Instead, you
must use the "Set Menu Keys" option to assign keyboard equivalents for
the menu items below:

Window:

    Bury Window
        If more than one TOSWIN window is open on screen, a new window
    (i.e. not the current top one) is brought to the top. Repeated
    application will cycle through all open windows.
    Iconify Window
    Make the window small and put it "out of the way". Iconified windows
    may be dragged around without making them bigger; they are
    expanded again by a single click.
    Send Character
    The next character typed will be sent to the application running
    in the top window, regardless of whether the key is a menu
        equivalent or not.
    Set Window Size...
    Change the number of rows and columns for the top window; this probably
    won't change the appearance on screen (unless the new size is
    radically smaller). It will, however, make more or less space available
    via the sliders. Changing the window size causes a SIGWINCH signal
    to be sent to the process group running in the window.
    Set Font...
    Change the font of the top window.
    Set Gadgets...
    Change the gadgets (slider, title, etc.) showing on the top
    window.

Gadgets:

    Toggle Full
    Has the same effect as clicking on the "full" box of a window.
    Move Window
    A pointing finger appears; move this to the location to which
    you want the window moved, and click the mouse.
    Scroll Up
    Has the same effect as the "up arrow" gadget of a window.
    Scroll Down
    Has the same effect as the "down arrow" gadget of a window.
    Scroll Left
    Has the same effect as the "left arrow" gadget of a window.
    Scroll Right
    Has the same effect as the "right arrow" gadget of a window.

WINDOWS

Text in a window may be selected by the usual operation of holding down
the mouse button and sweeping out a region. Single clicking on a window
will unselect any text previously selected. Selected text appears in
inverse video. A block of selected text may be dragged to another
(or the same) window; when this is done, the effect is as though
the user typed the selected text at the keyboard while the target window
was on top. Selected text may also be dragged to the clipboard icon to
paste it to the clipboard. Dragging the clipboard icon to a window pastes
the contents of the clipboard into the window.

Windows may be resized, moved, etc. with the normal window gadgets, or
with the mouse if the control key is held down. To resize a window without
a sizer box, hold down the control key and press the left mouse button
at the lower right hand corner of the window. To "full" the window do
the same thing at the upper right hand corner; and to move the window
hold down the control key and press the left mouse button anywhere else
in the window. Scrolling of a window without scroll bars may be done
via the Gadgets menu.

Closing a window sends a SIGHUP signal to the process group running in
the window. Pressing CTRL-C or CTRL-\ sends a SIGINT or SIGQUIT
signal to the process group in the current top window.

APPLICATION MENUS

When a new window is opened, TOSWIN looks for a file with the same path
and name as the program being executed, but with a .MNU extension instead
of the program's extension (e.g. if C:\MINT\TOP.TTP is being launched,
TOSWIN looks for C:\MINT\TOP.MNU). If found, this .MNU file is loaded and
the menu described therein is displayed whenever the given window is the
top one and the "Application Menus" option is set. This allows .TOS and
.TTP programs to have a simple menu driven interface provided for them
with little effort.

The format of the .MNU file is quite straightforward. Lines beginning
in the first column (i.e. no leading white space) are menu titles.
Lines beginning with white space represent menu entries. The first
word (sequence of non-white space characters, or characters between
double quote marks) is the menu entry itself. The second word represents
a string which will be sent to the application when this menu is
selected. The characters of the string are represented by the 4
hexadecimal digits which make up their VDI key codes, e.g. 6100
is the UNDO key. The final word in the line is a keyboard equivalent
for this menu item; 0000 means no equivalent is provided.

If the menu entry string begins with a minus sign '-', then it will
be disabled. If it consists of nothing but '-' characters, then it
will be expanded to stretch across the full length of the menu.

TERMINAL EMULATION

TOSWIN tries hard to make windows look like a regular ST console. For
example, the shift key status and scan codes are sent when keys are typed
in a window, and the "Standard" window size matches what the line A says
is the size of a window. All the VT52 escape codes are interpreted. One
oddity is that ESC-b and ESC-c (set foreground and background colors) use
VDI colors instead of line-A colors; but unlike MW, different colored
characters can appear on the screen together. Also, note that only 16 different
text colors are supported.

TOSWIN extensions to the ST's terminal emulation ( (MW) indicates that
the extension is shared by Allan Pratt's MW window manager as well ).

ESC Q        Quote next character; the next character is output
        without any control character interpretation taking
        place. (MW)
ESC R        Set window size; the next text should be an ASCII
        string representing (in decimal) the number of
        columns the window should have, followed by a comma
        and the number of rows the window should have, and
        terminated by a carriage return. For example, the
        command:
            Cconws("\033R132,50\r");
        will cause the window to be resized to 132 columns by
        50 rows. If either the columns or rows is missing (or
        zero) then it is left unchanged.
ESC S        Set title bar; text up to the next carriage return
        is placed in the window's title bar. (MW)
ESC T        Send TERMCAP string. A TERMCAP description for the
        window is sent just as though the user had typed it.
        The string begins with TERMCAP= and ends with a
        carriage return.
ESC a        Delete the character at the current cursor position. (MW)
ESC h        Enter insert mode. (MW)
ESC i        Leave insert mode. (MW)
ESC t <C>    Set cursor flash timer. The next character, <C>, is
        the number of 50 ms intervals that should pass before
        the cursor flashes, plus 32. (That is, an interval of
        n * 50 is represented by (' '+n).) If the interval is
        0 (i.e. the character <C> is a space) then the cursor
        does not flash.
ESC y <C>    Set text effects. The low 5 bits of the next character
        (<C>) are used to determine which text effects should
        be turned on:
        0x0001: Bold text
        0x0002: Dim text
        0x0004: Slanted text
        0x0008: Underlined text
        0x0010: Reverse video
ESC z <C>    Clear text effects. The low 5 bits of the next character
        are used to determine which effects should be turned off.
        See the description of ESC y for more details.


ENVIRONMENT

TOSWIN will put several variables into the environment of the top level
process in a new window, including:

LINES=        POSIX's way of telling how many lines and columns a
COLUMNS=    window has

TERMCAP=    A complete termcap style description of the terminal
        capabilities.
TERM=tw52    Goes with the TERMCAP= above.

The Atari standard ARGV= argument passing mechanism is also used by
TOSWIN, so ARGV= and arguments are put into the environment.

Besides the environment variables, TOSWIN also uses the TIOCSWINSZ
Fcntl option on the pseudo-terminal associated with a window. Whenever
a window's size is changed, a new TIOCSWINSZ call is made and also
a SIGWINCH signal is sent to the process group running in the window.
tcsh, for example, notices this and updates its environment variables
accordingly.


BUGS

Things to do/known bugs:

(1) Italic text isn't always redrawn correctly (it can be chopped
    off on the left by the cursor).
(2) TOSWIN doesn't know that bold text can be wider than normal
    text, and so again redraws get messed up (this mostly happens
    with proportional text).
(3) The "Copy" and "Paste" menu items should be disabled when
    there is no data available on the clipboard.
(4) TOSWIN chokes on 0 width characters in proportional fonts. (Well, OK,
    it doesn't choke on them -- but the screen display can get quite messed
    up if 0 width characters are showing!).
(5) There should be a program to make .MNU files.
(6) More flexible .MNU files would be nice (e.g. the entries in
    the "Toggles" menu for top should actually toggle in appearance,
    and ways should be provided to check or disable application
    menus.


APPENDIX: Launching programs in a TOSWIN window

Here's a short sample application that can be used to launch
programs in a TOSWIN window, using the pipe that TOSWIN
opens (u:\pipe\tosrun).

/*
 * runtos: a small program that will launch a TOS or TTP program
 * in a TOSWIN window.
 * To compile:
 *     gcc -O -mshort -o runtos.prg runtos.c -lgem16
 * To run:
 *     runtos someprog.tos arg1 arg2 arg3
 * OR
 *     Using the desktop, do an "Install Application" on runtos.prg.
 *     For "document type", use .TOS. Now, double clicking on a TOS
 *     program will automatically start it up in a TOSWIN window.
 *     (unfortunately, it will also cause all TOSWIN windows to be
 *     hidden -- you'll have to select "TOS programs" from the DESK
 *     menu to get them back again).
 * BUGS
 *     See above. Also, it would be nice to have a "runttp.prg"
 *     that would prompt for .TTP arguments. This is left as an
 *     exercise for the interested reader.
 *
 * "runtos" was written by Eric R. Smith and is hereby placed in
 * the public domain.
 */

#include <minimal.h>

long _stksize = 2*1024;

int
main(int argc, char **argv)
{
/* BUG: shouldn't have a fixed size buffer */
    static char buf[1024];
    char *where = buf;
    int i, fd;
    long r;

    if (!argv[1]) return 2;

/* first, put the path */
    *where++ = Dgetdrv() + 'A';
    *where++ = ':';
    Dgetpath(where, 0);
    if (!*where) *where = '\\';
    strcat(where, " ");

/* next, put the program */
    strcat(where, argv[1]);

/* finally, put the arguments */
    for (i = 2; argv[i]; i++) {
        strcat(where, " ");
        strcat(where, argv[i]);
    }

    fd = Fopen("U:\\PIPE\\TOSRUN", 2);
    if (fd < 0) return 1;

    r = strlen(buf) + 1;

    if (Fwrite(fd, r, buf) != r)
        return 1;

    return 0;
}