Commit 36c0337f authored by Neil Turton's avatar Neil Turton
Browse files

Import from cleaned 360 CD

hdr/** gitlab-language=armasm linguist-language=armasm linguist-detectable=true
s/** gitlab-language=armasm linguist-language=armasm linguist-detectable=true
*,ffb gitlab-language=bbcbasic linguist-language=bbcbasic linguist-detectable=true
SWI TaskManager_TaskNameFromHandle (Task manager 0.47 and later)
r0 = Task Handle.
r0 -> Task name.
You should copy the name into your workspace if you want to keep it.
SWI TaskManager_EnumerateTasks (Task manager 0.51 and later)
r0 = 0 For first call or value from last call
r1 -> Word aligned Buffer
r2 = Buffer length
r0 = <0 If no more entries
else value to pass to next call
r1 -> First unused word in buffer
r2 = Number of unused bytes in buffer
[r1] - Filled with entries of the form:
[0] = Task handle.
[4] -> Task name (This should be copied away and not used in place)
[8] = Amount of memory (in K) used by the task.
[12] = Flags:
bit 0 1 - Module task
0 - Application task.
bit 1 1 - Slot bar can be dragged
0 - Slot bar cannot be dragged
bits 2-31 reserved and are currently 0.
> net#arf:$.a500.RiscOS+.doc.SaveDesk
Author: Neil Raine
Status: Draft proposal, not agreed yet
20-Sep-89 0.01 First draft.
20-Sep-89 0.02 TinyDirs section added.
20-Sep-89 0.03 Desktop_PreSavingDesktop stuff deleted.
*SetMemorySize -next <n>k added
Comment about *Desktop_SetPalette added.
Comment about printer drivers saving choices added.
20-Sep-89 0.04 /<Edit$Dir>.!Edit changed to /<Edit$Dir>
Comment about junking Filer=>Display=>Save added.
20-Sep-89 0.05 Section about "shared resources" replaces "!System"
21-Sep-89 0.06 Simplified according to WStoye's comments
26-Sep-89 0.07 Added stuff about !Alarm
Added 'Outline' section
Added 'Work done in Desktop module' section
29-Sep-89 0.08 Correct section about dbox
Enlarged section on Filer
4-Oct-89 0.09 Message_SavingDesktop changed to Message_SaveDesktop
Example code segment for C application added
6-Oct-89 0.10 Stuff about not acknowledging Message_SaveDesktop
19-Oct-89 0.11 Stuff about desktop auto-saving removed
Aside about save dbox not being a menu removed
"Work done in the Desktop module" section removed
GStark 27-Oct-89 0.12 Added Service_WimpSaveDesktop (in resident modules
27-Oct-89 0.13 Corrected Service_WimpSaveDesktop
31-Oct-89 0.14 Put auto-save icon into description of dbox
GStark 03-Jan-89 0.15 Changed Ram Disc and other slot size stuff to the new spec.
This document describes the Task Manager facility that allows a user to save
and restore the current state of his desktop, thus obviating the need for a
separate !SetDeskWorld utility.
The Task Manager menu provides an option to save the current state of the
desktop world into a Desktop file, which can be used to restart the desktop
in its original state.
There will also be facilities to save the Desktop file as a !Boot file (on
ADFS) or !ArmBoot file (on NetFS), whereby the necessary configuration
commands to get the system to reboot via this file are automatically carried
out by the Task Manager.
In general the boot file will not return the desktop to precisely the state
it was in, because:
(a) Applications which have not been specially written to deal with
desktop saving will not be restarted.
(b) Apart from Filer directory viewers, applications will not re-open
all the windows that were open when the desktop was saved. In
particular, this means that editors will not re-open the files that
were being edited.
Work done by Task Manager
Task Manager will have the following options:
Save state to a given file, without exitting
Exit to supervisor
Shutdown machine
The menu therefore contains:
New task => (writeable buffer)
Task display
*Commands (f12)
Desktop boot => (boot dbox)
Note that the menu option says "Desktop boot" rather than "Save desktop" in
order not to raise the user's expectations too high, since it will not in
general be possible to return to precisely the same state as the desktop was
The boot file save dbox would look like this:
<file icon>
[ !Boot ] [OK]
[ ] Auto boot
[ ] Auto save
If auto boot is enabled, then the effect of SHIFT being pressed on reset is
reversed: ie. if it is not pressed, the boot file will be executed, and if
it is pressed, the boot file will not be executed. The icon is initially
set up to reflect the current state of the auto-boot CMOS RAM bit.
The auto save icon is always turned off by default - if it is enabled when
the file is saved, the file will be marked as an auto-save file, so that
when the user selects Exit or Shutdown from the iconbar menu, the desktop
state will be automatically saved in that file.
The filename is initialised to "!Boot" or "!ArmBoot" when the Task Manager
starts up, depending on whether adfs or net is the configured filing system.
The user can change this if he wishes, and then click on OK or drag the
file into a directory viewer.
If directory name is net#<fsname>:&
*opt 4,2 executed on the appropriate fileserver
*configure filesystem net
*configure fs <fsname>
*configure boot/noboot
If directory name is <fs>::<discname>.$
*opt 4,2 executed on the appropriate disc
*configure filesystem <fs>
*configure boot/noboot
If <fs> is adfs
*configure drive <drive containing appropriate disc>
Filing systems other than the network are assumed to behave like adfs, ie.
the boot filename is "!Boot" and it must be created in "$".
Aside: It was felt that it would be too much of a shock for the user if
an error message was returned if the file was not saved in the
root directory, so instead it just doesn't do the filesystem
configuration etc.
The save protocol
Once the file to be saved is known, the save protocol can start:
* The Task Manager first opens the output file and makes a note of the
* The Task Manager then inserts a comment saying when the file was created,
so that when the user refers to the file (s)he will know how recent it is.
* The Task Manager then inserts four *commands:
1) WimpSlot -next <wimp slot 'next' size>K
2) ChangeDynamicArea -FontSize <font area size>K
3) ChangeDynamicArea -SpriteSize <system sprite area size>K
4) ChangeDynamicArea -RamFsSize <RAM disc size>K
These set the sizes of the 'Next' slot, the font and sprite area sizes, and
the RAM disc size, as would be expected. It is not sensible to set the RMA
size or the system stack in this way, as they are much more system-dependent
than those described above. The screen size cannot be set as it is always
reset to the size of the current screen mode by the Task Manager.
If there is not enough memory free to be allocated for a particular slot then,
instead of giving errors, the largest amount of memory which is free
will be allocated to the slot.
* If the user enabled 'auto-save' in the dbox, the Task Manager inserts
the following line at the top of the output file:
*Set SaveDesk$File <Desktop$File>
What this does is to ensure that when the file is used to restart the
desktop, the environment variable SaveDesk$File is set up to remember
the name of the file. This works because the Desktop module has also
been extended to set up Desktop$File to the name of the file passed to
When the user selects 'Exit' or 'Shutdown' from the task manager's menu,
it looks to see if the variable SaveDesk$File is set up - if it is, it
automatically saves the desktop state in this file before exitting.
* Rather than using broadcast messages, the Task Manager talks to all the
other tasks by using its list of task handles and names. This ensures
that the tasks are asked to restart in the same order as they were
originally started (which is not true for broadcasts).
* For each task in its list, the task manager sends a message called
+16 Message_SaveDesktop (10)
+20 (word) file handle of desktop file being written
+24 flag word:
bits 0..31 reserved (ignore them)
Note that this is a RISC OS rather than a C file handle, so fprintf()
cannot be used. The RISC OS SWIs OS_BPut or OS_GBPB should be used
* If the task understands the message, it then writes data directly
into the desktop file, using the file handle supplied.
The data is a sequence of *commands suitable for inclusion in a Desktop
file, each terminated by a linefeed character (&0A). When the file is
run to start the desktop, each command will be executed as a separate
Wimp task.
A typical example for a C application follows:
#include <os.h>
#include <swis.h>
os_error *save_desktop(int handle)
char *ptr;
for (ptr=getenv ("Edit$Dir"); *ptr; ptr++) {
os_error *error = os_swi2(OS_BPut, *ptr, handle);
if (error) return error;
return os_swi2(OS_BPut, 10, handle); /* line terminator */
* If the message is NOT acknowledged, the task manager goes on to the
next one in the list. This means that:
(a) Tasks which don't understand desktop saving will not be saved in
the desktop file, and the documentation should make it clear
that this will happen with old applications.
(b) If an application gets an error while writing to the file, it
should acknowledge the message and report the error. The Task
Manager will detect that the message has been acknowledged, and
will abort the save operation and remove the file.
* When all the tasks have been asked for their restart commands, the file
is closed, and if the output was a boot file, *Opt 4,2 is executed for
the appropriate disc drive / user id.
* If this was an auto-save operation, the exit / shutdown sequence will
start from there, with the PreQuit broadcast followed by the Quit
Work done by applications
Normal applications:
The typical restart command for an application is a GSTrans-ed form of
something like:
Note that since several copies of !Edit can be loaded at once, this
GSTrans-ing operation should be done as soon as the application is
loaded (and the result stored in a buffer), in case the value of
Edit$Dir changes subsequently.
Resident modules:
Resident module tasks do not require a restart command of that form,
since they are automatically started when the desktop is entered (by
means of the Service_StartWimp protocol). However, if the modules are
not stored in the ROM, they will probably be loaded by means of some
form of *RMEnsure command in a !foo application, so the !foo application
should be re-run instead.
There is a service call provided, though, for modules which need to save
some state to the file, e.g. ColourTrans saves its calibration. This is
as below:
Service_WimpSaveDesktop (&5C)
In R0 = flag word (as in Message_SaveDesktop)
R1 = &5C (reason code)
R2 = file handle of file to write *commands to
Out R0 -> Error, if necessary, else preserved
R1 = 0 for error (i.e. claim), else preserved
all other registers preserved
When a module receives this service code it should write out any *
commands, to the specified file handle, which should be performed by a
Desktop Boot file on entry to the Desktop.
If an error occurs (Disc full, Can't extend, or even a module specific
error like 'Can't save desktop now because...' then the service should
be claimed, and R0 should point to the error block.
This service call is performed before the task manager issues the Wimp
broadcast message Message_SaveDesktop.
Network logons must be regenerated, so that Filer windows referring to
network directories can be re-opened. The NetFiler module must keep
track of which username is in use on each fileserver, so that it knows
the required username to put in the *command. These commands would not
include the password - if the user id required a password, the Wimp's
command window would appear with the *Logon command in the title and the
prompt 'Password:' in the window. The current NetFiler would have to be
changed so that the window title displayed the fileserver and username,
so that the user knew which password to enter!
As long as the appropriate logons are executed, the current state of the
filer display can be saved by using the Filer's ability to generate
*Filer_OpenDir commands for the directories currently open (already used
in the Filer's Display => Save option).
The Filer must remember the full pathnames of any applications it sees
(eliminating duplicates), and issue a "Filer_Boot" command for each
application that contained a !Boot file (since these can set up aliases
and load in icons for data filetypes).
The Filer must issue a Message_FileStarted broadcast after it has
started all its children, which allows the TaskManager to 'renumber' the
Filer in its list, so that its desktop saving will be done AFTER that of
the individual filing systems. This is important so that the NetFiler
can issue its logon commands before any net directories are opened.
Shared resources:
Environment variables pointing to shared resources are set up when the
!Boot file of the relevant shared resource directory is run. This is
therefore dealt with by the Filer.
The Palette Utility is capable of saving the current palette in a file,
but this would not be suitable for saving its current state into the
saved desktop file. It would have to accept a new *command of the form:
*Desktop_SetPalette RRGGBB RRGGBB RRGGBB etc. (times 20)
where 'RRGGBB' is a sequence of 6 hex digits defining colour (0..15,
then the border colour and then the 3 mouse colours).
(The maximum length of a line in a Desktop file is 256 characters, and
at 158 characters, this line is OK).
Printer drivers:
Similarly the printer drivers can set their current state from the
'PrData' file stored within themselves, but strictly speaking ought to
save their state as a set of textual parameters on the command line,
which could be re-asserted when the command was executed. The problem
with simply saving the current state into the PrData file is that two
different desktop save files with different printer setups would produce
the same result if there was only one printer application, since both
would cause the same PrData file to be loaded. However, it may be
impractical to duplicate all the functionality of the modifiable parts
of the PrData file as *commands.
If the state must be saved in the PrData file, then at least the printer
drivers should behave like !Edit in that if you try to exit while you
have unsaved choices, a dialogue box is presented.
Applications such as !Alarm that live in DeskFS: cannot easily save data
into their application directory (unless the user copies the directory
onto a disc and runs it from there).
With the advent of desktop saving, it is probably better for
applications like !Alarm to save small bits of configuration status in
an environment variable, and then to output an appropriate *Set command
when the desktop save occurs.
The ROM version of !Alarm will detect which filing system it was run
from, and grey out the "Alarm=>Set" option if it detects that it has
been run from DeskFS. It can do this as follows:
handle% = OPENIN"Alarm:!Alarm" :REM open alarm file
SYS "OS_FSControl",21,handle% TO ,,fsword% :REM read FS info word
CLOSE #handle%
IF (fsword% AND &FF)=21 THEN <grey out "set alarm">
!Alarm should use an environment variable to store the user format
time string, eg.
*Set Alarm$DateFormat %w3 %zdy %m3 %z12:%mi %pm
Another environment variable is also required:
*Set Alarm$DateType Analogue
*Set Alarm$DateType HoursMins
*Set Alarm$DateType HoursMinsSecs
since Alarm$DateFormat is still used for the user date string even if
(eg) analogue is initially selected.
In this way all the data concerning the display options is held in the
desktop save file, rather than the application itself. CMOS RAM is not
used, since (a) there is not enough to store the user format string, and
(b) if the user format string is in a variable, then so should the
display type be.
However, the alarms are stored in the application directory, but are not
available if !Alarm is run from DeskFS.
It is not necessary to 'log on' to discs - the user will automatically
be prompted to insert the appropriate discs as required.
The TinyDirs module must return a *AddTinyDir command for each
directory currently held on the iconbar, in left-to-right order. When
re-executed, these commands would cause each new directory to be placed
to the right of the previous one.
The length of the bar is linear with the memory up to 512K. For the next
1024K the gradient is a half, the next 2048K a quarter and so on (for very
large values this approximates to a sum of logorithms)
- its fast BOTH ways (the inverse is required for dragging)
- linear for low memory sizes- easy to use
- total memory/ used/free etc. aren't much bigger
Title; "Blue" Switcher changes
Author; David De Vorchik
Distribution; Internal only
19-Jun-92 DDV Created
This document outlines the changes made to the Task Manager (Switcher) since
RISC OS 3.10, it covers bug fixes and some API changes.
Task Manager 3.17:
* Bug fix: Clicking on the about this OS dialogue no longer gives
an address exception on certain icons.
* No longer knows anything about the limits on various dynamic areas,
reads them back from the kernel.
Apache License
Version 2.0, January 2004
1. Definitions.
"License" shall mean the terms and conditions for use, reproduction,
and distribution as defined by Sections 1 through 9 of this document.
"Licensor" shall mean the copyright owner or entity authorized by
the copyright owner that is granting the License.
"Legal Entity" shall mean the union of the acting entity and all
other entities that control, are controlled by, or are under common
control with that entity. For the purposes of this definition,
"control" means (i) the power, direct or indirect, to cause the
direction or management of such entity, whether by contract or
otherwise, or (ii) ownership of fifty percent (50%) or more of the
outstanding shares, or (iii) beneficial ownership of such entity.
"You" (or "Your") shall mean an individual or Legal Entity
exercising permissions granted by this License.
"Source" form shall mean the preferred form for making modifications,
including but not limited to software source code, documentation
source, and configuration files.
"Object" form shall mean any form resulting from mechanical
transformation or translation of a Source form, including but
not limited to compiled object code, generated documentation,
and conversions to other media types.
"Work" shall mean the work of authorship, whether in Source or
Object form, made available under the License, as indicated by a
copyright notice that is included in or attached to the work
(an example is provided in the Appendix below).
"Derivative Works" shall mean any work, whether in Source or Object
form, that is based on (or derived from) the Work and for which the
editorial revisions, annotations, elaborations, or other modifications
represent, as a whole, an original work of authorship. For the purposes
of this License, Derivative Works shall not include works that remain
separable from, or merely link (or bind by name) to the interfaces of,
the Work and Derivative Works thereof.
"Contribution" shall mean any work of authorship, including
the original version of the Work and any modifications or additions
to that Work or Derivative Works thereof, that is intentionally
submitted to Licensor for inclusion in the Work by the copyright owner
or by an individual or Legal Entity authorized to submit on behalf of
the copyright owner. For the purposes of this definition, "submitted"
means any form of electronic, verbal, or written communication sent
to the Licensor or its representatives, including but not limited to
communication on electronic mailing lists, source code control systems,
and issue tracking systems that are managed by, or on behalf of, the
Licensor for the purpose of discussing and improving the Work, but
excluding communication that is conspicuously marked or otherwise
designated in writing by the copyright owner as "Not a Contribution."
"Contributor" shall mean Licensor and any individual or Legal Entity
on behalf of whom a Contribution has been received by Licensor and
subsequently incorporated within the Work.
2. Grant of Copyright License. Subject to the terms and conditions of
this License, each Contributor hereby grants to You a perpetual,
worldwide, non-exclusive, no-charge, royalty-free, irrevocable
copyright license to reproduce, prepare Derivative Works of,
publicly display, publicly perform, sublicense, and distribute the
Work and such Derivative Works in Source or Object form.
3. Grant of Patent License. Subject to the terms and conditions of
this License, each Contributor hereby grants to You a perpetual,
worldwide, non-exclusive, no-charge, royalty-free, irrevocable
(except as stated in this section) patent license to make, have made,
use, offer to sell, sell, import, and otherwise transfer the Work,
where such license applies only to those patent claims licensable
by such Contributor that are necessarily infringed by their
Contribution(s) alone or by combination of their Contribution(s)
with the Work to which such Contribution(s) was submitted. If You
institute patent litigation against any entity (including a
cross-claim or counterclaim in a lawsuit) alleging that the Work
or a Contribution incorporated within the Work constitutes direct
or contributory patent infringement, then any patent licenses
granted to You under this License for that Work shall terminate
as of the date such litigation is filed.
4. Redistribution. You may reproduce and distribute copies of the
Work or Derivative Works thereof in any medium, with or without
modifications, and in Source or Object form, provided that You
meet the following conditions:
(a) You must give any other recipients of the Work or
Derivative Works a copy of this License; and
(b) You must cause any modified files to carry prominent notices
stating that You changed the files; and
(c) You must retain, in the Source form of any Derivative Works
that You distribute, all copyright, patent, trademark, and
attribution notices from the Source form of the Work,
excluding those notices that do not pertain to any part of
the Derivative Works; and
(d) If the Work includes a "NOTICE" text file as part of its
distribution, then any Derivative Works that You distribute must
include a readable copy of the attribution notices contained
within such NOTICE file, excluding those notices that do not
pertain to any part of the Derivative Works, in at least one
of the following places: within a NOTICE text file distributed
as part of the Derivative Works; within the Source form or
documentation, if provided along with the Derivative Works; or,
within a display generated by the Derivative Works, if and
wherever such third-party notices normally appear. The contents
of the NOTICE file are for informational purposes only and
do not modify the License. You may add Your own attribution
notices within Derivative Works that You distribute, alongside
or as an addendum to the NOTICE text from the Work, provided
that such additional attribution notices cannot be construed
as modifying the License.
You may add Your own copyright statement to Your modifications and
may provide additional or different license terms and conditions
for use, reproduction, or distribution of Your modifications, or
for any such Derivative Works as a whole, provided Your use,
reproduction, and distribution of the Work otherwise complies with
the conditions stated in this License.
5. Submission of Contributions. Unless You explicitly state otherwise,
any Contribution intentionally submitted for inclusion in the Work
by You to the Licensor shall be under the terms and conditions of
this License, without any additional terms or conditions.
Notwithstanding the above, nothing herein shall supersede or modify
the terms of any separate license agreement you may have executed
with Licensor regarding such Contributions.
6. Trademarks. This License does not grant permission to use the trade
names, trademarks, service marks, or product names of the Licensor,
except as required for reasonable and customary use in describing the
origin of the Work and reproducing the content of the NOTICE file.
7. Disclaimer of Warranty. Unless required by applicable law or
agreed to in writing, Licensor provides the Work (and each
Contributor provides its Contributions) on an "AS IS" BASIS,
implied, including, without limitation, any warranties or conditions
PARTICULAR PURPOSE. You are solely responsible for determining the
appropriateness of using or redistributing the Work and assume any
risks associated with Your exercise of permissions under this License.
8. Limitation of Liability. In no event and under no legal theory,
whether in tort (including negligence), contract, or otherwise,
unless required by applicable law (such as deliberate and grossly
negligent acts) or agreed to in writing, shall any Contributor be
liable to You for damages, including any direct, indirect, special,
incidental, or consequential damages of any character arising as a
result of this License or out of the use or inability to use the
Work (including but not limited to damages for loss of goodwill,
work stoppage, computer failure or malfunction, o