

                            Graphic Task Windows
                            ====================


Documentation for !GraphTask application version 4.04 19-Jan-2021,
for RISC OS 3.5 or later.

Issue: 4.04 19-Jan-2021, replaces:      0.10 13-Aug-1990
                                        1.00 23-Aug-1990
                                        2.00 31-Dec-1990
                                        3.00 20-Jun-1991
                                        3.10 14-Dec-1992
                                        3.11 09-Aug-1994
                                        3.12 15-Aug-1998
                                        3.53 15-Aug-1998
                                        3.54 04-Mar-2001
                                        3.60 24-Aug-2001
                                        4.00 28-Aug-2001
                                        4.01 01-Oct-2001
                                        4.02 30-Dec-2005
                                        4.03 05-Feb-2009

Author: David J Ruck

Copyright  DEEJ Technology PLC 1990-2021

 

Overview
========

The Graphic TaskWindow provides an extension to the RISC OS taskwindow
concept by allowing the full use graphics, whilst preserving the ability to
run true RISC OS tasks at the same time.

Taskwindows are usually managed by a text editor programs such as !Edit,
which don't know how to handle graphics or even text positioning codes.
!GraphTask knows how to handle all graphics, screen modes and palettes and
display them all in a window on the desktop.

!Graphtask is aimed at the enthusiast programmer who is able to write small
non wimp programs, and would like them to run in a window on the desktop,
but does not have the time or the expertise to tackle the complicated and
long winded RISC OS windowing operating systems calls.

!Graphtask is very useful for someone who has written or bought a large
collection of pre-RISC OS or BBC (Model A, B, Master, Compact or Electron)
programs which it is not possible to upgrade to RISC OS versions.

A Graphic Taskwindow will allow most non-desktop programs to be run in a
fully re-sizeable window on the desktop, without stopping the operations of
other  RISC OS tasks.

"Program" is used throughout this document to mean the program running
within a Graphic Task window. "Task" refers to a standard windowing program
running on the RISC OS desktop.

Features
--------

Currently some non desktop programs can be made to multitask using the New
Taskwindow option from the !Edit create menu (or by the TaskWindow option on
the RISC OS 3 Task Manger menu), but this has the disadvantage that the
programs must only output pure text.

This means that not only pure graphics programs will not work, but also any
program which relies on printing at different locations on the screen.
!GraphTask extends the text only Taskwindow concept by providing the
following enhancements:


Multi-tasking           The program running in a Graphic Taskwindow does not
                        need to contain any Wimp_Poll calls to multitask, it
                        is automatically run for a small amount of time
                        between the operation of other fully RISC OS tasks.
                        This is transparent to the user and program, except
                        that the program appears to run more slowly.

Multi-windows           Any number of Graphic Taskwindows may be active at
                        once, but this is limited in practice by how much
                        memory is used by each task and the memory used by
                        the screen for each task. 

The screen              A Graphic Taskwindow provides the program with an
                        environment similar to what it would have running
                        outside the desktop, whilst running in its own
                        window and without affecting other desktop programs.
                        This allows programs to change the screen mode and
                        the colour palette as normal, but for the changes to
                        only affect the contents of its window. The mode and
                        colours used are approximated as closely as possible
                        in the current desktop mode.

Cursors                 A text cursor and text editing cursor are provided,
                        to show where typed characters will appear and to
                        allow the copying of text from other parts of the
                        screen, in the same way as the cursors outside the
                        desktop. This enables easier editing than is
                        available  using the taskinput feature of an !EDIT
                        taskwindow.

Scaling                 A taskwindow can be resized and the scroll bars
                        moved in the normal RISC OS manner without affecting
                        the display of the program in the window.
                        Additionally it may be scaled down to give more room
                        on the desktop whilst keeping all of the programs
                        screen visible (albeit smaller), or scaled up to
                        examine small detail, again this does not affect the
                        program.

The mouse               Some non-desktop programs use the mouse in their
                        operation, to allow these to be used correctly the
                        position of the mouse pointer they read is adjusted
                        so that it is relative to their screen, rather than
                        the desktop screen. This takes into account the
                        position of the window in which the program is
                        running, whether all of it is visible due to use of
                        the scroll bars, and also if the scaling has been
                        selected.


Programs compatible with Graphic Taskwindows
--------------------------------------------
Most BASIC and machine code programs can be used in a Graphic Taskwindow as
long as they;

               Are not RISC OS windowing programs.

               Do not directly access the screen.

               Do not try to re-configure the machine.

               Do not claim operating system vectors or use interrupt code.

               Do not try to leave the desktop,
                (!65Host or old PC emulators).

Eight bit BBC computer programs which require !65Host will not work, but
65Tube can be used to run Basic or 6502 assembler programs in a Graphic
Taskwindow. 65Tube can be entered by typing *EmulateTube from within a
taskwindow.

Programs which try to redefine the cursor keys or action (OS_Byte 4 / *FX4)
will run but not always function correctly e.g. Arm Basic Editor. Programs
which use multiple screen buffers to improve graphics updating will run, but
will not always give the correct display in the Graphic Taskwindow.



Using !GraphTask
================

To start !GraphTask double click on the !GraphTask icon in a filer window,
it will then install itself on the icon bar.


New Graphic Taskwindow
----------------------
A new Graphic Taskwindow can be created in four ways; the first two are by
clicking on its icon or selecting New Task from the iconbar menu.

This will create a new taskwindow with no task running except a command line
interpreter. The amount of memory initially given to the task will be that
specified in the next slot of the Taskmanager display. To alter the amount
of memory when the task has been started use the *WimpSlot command.

The third way to create a new Graphic Taskwindow is to drag a file or an
application directory (of a non desktop application) onto the !GraphTask
icon. The program will then automatically load and run in a new taskwindow.
If shift is held when dragging the file name will be inserted at the cursor
allowing further parameters to be added.

Another way is to start !GraphTask from the Taskmanager menu or an obey
file, with the names of programs which will automatically start up in their
own task windows.

        e.g. Run !GraphTask Program1 Program2...


Errors when starting.   Each new Graphic Taskwindow will require memory for
                        both the program and the screen it uses within its
                        window. Graphic Taskwindows usually start in MODE 12
                        (the program's mode, not the mode the desktop is
                        currently in), if not enough memory is available
                        MODE 0 will be tried, if there is still not enough
                        memory an error will be reported, and no taskwindow
                        will be created.

Dragging files
--------------
Dragging a file over to a Graphic Taskwindow will have the same effect as
typing in its full pathname and pressing RETURN - useful for programs which
ask for filename, or starting new programs in an existing taskwindow.

The filename is normally inserted with a newline at the end, but if shift
is held a space is appeneded instead. This is useful for executing commands
which take more than one filename as parameters.


Graphic Taskwindow Menu
-----------------------
Pressing the mouse menu button in a Graphic Taskwindow will call up the
menu, its entries are as follows;

Menu Button             When the mouse buttons select and adjust are pressed
                        over a Graphic Taskwindow the program being run can
                        read this, together with  the position of the mouse,
                        taking into account the windows position and scaling
                        so it is relative to the programs screen.

                        When the menu button is pressed the window menu will
                        appear, so to enable the program to detect a menu
                        button destined for it, hold the menu button down
                        over the Menu Button entry. The menu will disappear
                        and the program will see that the menu button has
                        been activated.

Kill                    Kill will not close the window, but the program
                        running in it will be killed and memory used by it
                        freed, the program cannot be restarted.

Reconnect               After killing reconnect will allow another program
                        to run in the same window, memory is claimed from
                        the Taskmanagers next slot.

Suspend                 This temporarily stops the program from running,
                        without freeing any memory used by it. This is
                        useful to use with the Save screen facility
                        described below.

Resume                  This enables the program to continue after a
                        suspend, it is transparent to the program running.

Save screen             This brings up a standard RISC OS saver dialog box
                        to save a copy of the programs screen. A full size
                        screen is saved as a sprite file irrespective of how
                        much of the screen is visible in the window or its
                        scaling.

Magnify                 A magnifier box as used in !Paint and !Draw is
                        displayed allowing the screen within the window to
                        be scaled down, to create more room on the desktop
                        whilst still showing the whole screen, or scaled up
                        to examine detail or read small text.



Technical details
=================

Multi-tasking           Multi-tasking is achieved by using a the taskwindow
                        module. This allows non wimp programs to be started
                        as RISC OS tasks, the module waits for Null events to
                        be delivered to each task. It then runs the program
                        for a small amount of time before interrupting it and
                        passing control back to other taskwindow tasks, or
                        normal RISC OS tasks via the standard Wimp_Poll SWI.
                        This results in the program running slower than it
                        would outside the desktop, but it is not necessary to
                        rewrite the program to run in a desktop compatible
                        way.

Screen handling         The output from Graphic Taskwindow programs are
                        redirected to a sprite which can have MODE and
                        palette settings independent of the desktop. The
                        screen is plotted into a window using the
                        OS_SpriteOp and the Colour_Trans module to provide
                        scaling and achieve the closest result to the
                        appearance of the screen if it were running outside
                        the desktop.

                        Output is buffered to prevent excessive redraws of
                        the window, speeding up the processes. The larger
                        the area changed each time, however, the slower the
                        update becomes.  Scaling of 1:1 should be used for
                        the fastest update. Users writing programs
                        specifically for Graphic Taskwindows should try to
                        ensure the screen is updated in blocks, rather than
                        drawing at opposite ends of the screen alternatively.

Text cursors            Text cursor and cursor editing is provided within
                        !GraphTask as it is not automatic when re-directing
                        output to a sprite. Only normal *FX4,0 type control
                        is provided at present.

Mode changes            If at any time a mode for which there is not enough
                        free memory is selected by the program, MODE 0 will
                        be used as default.
                        
Mode 7                  Mode 7 is now supported giving a BBC B compatible
                        Teletext mode. The VDU emulation is not complete in
                        this mode the following features are not supported:-
                      
                        VDU 1,2,3 - sending characters to the printer
                        VDU 6,21  - enable and disable VDU streams
                        VDU 14,15 - page mode
                        VDU 23    - text window scrolling, clear block
                                    cursor movement, cursor on/off

Mouse position          While the pointer is over a Graphic Taskwindow and
                        during any mouse button changes, the !GraphTask and
                        and the GraphTask support module translate the mous
                        position so OS_Mouse calls by the program will be
                        relative to its screen, irrespective of the position
                        or scaling of the window.

Incompatibilities       The majority of graphics programs tested, which do
                        not try to access the screen or perform operations
                        which do not agree with the taskwindow module (OS
                        vector claims, interrupt handling), have been found
                        to work correctly in a Graphics Taskwindow.

                        All VDU commands work correctly, however there are a
                        few small incompatibilities relating to the values
                        returned by the basic functions (and hence OS
                        routines) MODE, POS & VPOS, referring to the desktop
                        screen, which can cause some programs problems.

ColourTrans             ColourTrans SWI's which rely on the current screen
                        mode and palette (such as ColourTrans_ReturnGCOL)
                        cannot be used from within Graphic Task Windows, as
                        the current screen mode and palette are taken to be
                        that of the desktop.

                        SWI's which allow a mode and palette to be specified
                        should be used,

                        e.g. ColourTrans_ReturnGCOLForMode.


Future enhancements
-------------------
Future enhancements may include:

               Enhanced cursor & function key emulation to allow all *FX4
                and *fx224-228 options without affecting desktop programs.
                This will allow the use of Arm Basic Editor

               Interception of OS routines behind BASIC's MODE, POS & VPOS
                to return values representative of the programs rather than
                the desktop screen.

               Support for multiple screen banks and *FX112/*FX113
                switching using multiple output sprites.

               Support for ColourTrans to enable the SWI's to work
                correctly with the mode and palette used in graphic
                taskwindow.             


GraphTask and RISC OS 3.5+
==========================

GraphTask will work correctly with the  RISC OS version 3.5+

Programs running in the graphic taskwindow should not attempt to change
screen mode using the new OS_ScreenMode SoftWare Interrupt as this will
cause the desktop to change mode with unpredictable results. Also graphic
task windows cannot handle screen modes with more than 8 bits per pixel.


Credits
=======

MODE 7 functionality is provided by the Teletext+ module which remains
the copyright of Colin Granville. Many thanks are due for allowing its use.


Chnages
=======

3.54 04-Mar-2001  Function key string entry supported for Print(F0),F1-F12
3.60 24-Aug-2001  Reliance on hacked taskwindow module removed, now using
                  GraphTask module to deliver correct mouse positions to
                  programs running in the graphic taskwindows.
4.00 28-Aug-2001  Mode 7 Telextext support added.
                  Faster cursor drawing routines.
4.01 01-Oct-2001  Fixed redraw problem with right hand column in mode 7
                  Window gains caret when files are dragged to it.
                  !Help updated to mention action of shift drag to window
4.02 30-Dec-2005  Added VDU4 text cursor control with VDU23,1,x| (x=0 off)
4.03 05-Feb-2009  Work around for RISC OS 6.14 bug which requires room
                  for true colour paletted 256 colour sprite
4.04 19-Jan-2021  Recompile to fix issues on Raspberry Pi 4B

End of !GraphTask.!Help