Commit 5e08cc7c authored by Neil Turton's avatar Neil Turton

Import from cleaned 360 CD

parents
| Copyright 1996 Acorn Computers Ltd
|
| Licensed under the Apache License, Version 2.0 (the "License");
| you may not use this file except in compliance with the License.
| You may obtain a copy of the License at
|
| http://www.apache.org/licenses/LICENSE-2.0
|
| Unless required by applicable law or agreed to in writing, software
| distributed under the License is distributed on an "AS IS" BASIS,
| WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
| See the License for the specific language governing permissions and
| limitations under the License.
|
Dir <Obey$Dir>
amu_machine -f MakeDecAOF decode
hdr/** gitlab-language=armasm linguist-language=armasm linguist-detectable=true
s/** gitlab-language=armasm linguist-language=armasm linguist-detectable=true
**/s/** gitlab-language=armasm linguist-language=armasm linguist-detectable=true
c/** gitlab-language=c linguist-language=c linguist-detectable=true
**/c/** gitlab-language=c linguist-language=c linguist-detectable=true
h/** gitlab-language=c linguist-language=c linguist-detectable=true
**/h/** gitlab-language=c linguist-language=c linguist-detectable=true
_swi & _swix
------------
These functions provide a generic method of calling RISC OS SWIs from C. They
are the preferred method of calling SWIs.
Two functions are provided _swi, for calling SWIs without setting the X bit
and _swix which sets the X bit before calling the SWI.
The definitions for these functions are
extern int _swi(int swi_no, unsigned int mask, ...);
extern int _swix(int swi_no, unsigned int mask, ...);
swi_no is the number of the SWI to be called. This should never have the X bit
set.
mask is a word containing an input and output register mask, a return register,
and a block parameter register.
The arrangement of mask is as follows:
Bits 0 - 9: Set if R(N) is passed to the SWI.
Bits 22 - 31: Set if R(31-N) is output from the SWI (ie bit 31
corresponds to R0, bit 22 corresponds to R9).
Bit 21: Set if the PC (including the flags) is to be output.
Bits 16 - 19: Register no. to be returned from a _swi call. This is only
applicable to _swi as _swix always returns either 0 or an error
pointer.
Bit 11: Set if a local block parameter is to be passed to the SWI
Bits 12 - 15: Register number for local block parameter if bit 11 set.
If a register is specified as a return register (bits 16-19) it must not also
be specified as an output register in the output register mask (bits 22-31).
If a register is specified as a local block parameter register it must not also
be specified as an input register in the input register mask (bits 0-9).
If the PC is specified as a return register (ie bits 16-19 = 15) or as an
output registers (bit 21 = 1) the value returned will contain the flags in bits
28 to 31 (28 = V, 29 = C, 30 = Z, 31 = N).
The remainder of the variadic arguments are as follows (in order):
The word value of each input register in order from 0 to 9 as specified by bits
0 to 9 of the mask.
The address of a word to be written for each output register in order from
0 to 9 as specified by bits 31 downto 22 of the mask.
The address of a word to be written with the PC value on exit from the SWI if
bit 21 of the register mask is set.
If bit 11 is set the remainder of the arguments are placed in order in a
parameter block and the address of the parameter block is passed to the SWI in
the register specified by bits 12-15.
The functions are declared in the header swis.h along with some macros for
constructing masks and a complete list of system SWI definitions.
The macros are as follows:
_IN(n) - Specifies that R(n) is used on input
_OUT(n) - Specifies that R(n) is output
_BLOCK(n) - Specifies that R(n) is a block parameter
_RETURN(n) - Specifies that R(n) is returned from _swi.
The values of the macros should be ORed together to produce the value for the
mask.
The following constants are defined
_FLAGS - the register containing the flags (currently 15)
_C - mask for the C bit in _FLAGS
_Z - mask for the Z bit in _FLAGS
_N - mask for the N bit in _FLAGS
Please use these constants as they may change on ARM 600.
Example calls:
_swi(OS_NewLine, 0); /* Must specify 0 register mask */
_swi(OS_Write0, _IN(0), "Hello, World");
task_handle = _swi(Wimp_Initialise, _IN(0)|_IN(1)|_IN(2)|_RETURN(1),
300, *(int *)"TASK", "Test");
e = _swix(Wimp_LoadTemplate, _IN(1)|_IN(2)|_IN(3)|_IN(4)|_IN(5)|_IN(6)|_OUT(2)|_OUT(6),
template_buffer, workspace, workspace_end, -1, "MyWind", next,
&workspace_end, &next);
e = _swix(Wimp_SetExtent, _IN(0)|_BLOCK(1), w, minx, miny, maxx, maxy);
Control Files
=============
Author: William Stoye
History:
0.01
0.02
0.03 - 19-June-89 - remarks about help, and icons.
0.04 - 04-July-89 - ctl_make becomes ctl_init()
0.05 - 11-July-89 - more updates
0.06 - 12-July-89 - more updates
02-Jan-90 - I realise now that there are various shortcomings,
this thing has lain fallow for some time.
Key-bindings must be specific to specific contexts,
as different windows might have different ones.
Interactive help on menu entries (perhaps via Messages
file) should be supported. Should better use of
DecodeArgs be made? None of these issues have yet been
investigated.
0.10 - 31-Jan-90 RMokady - Major changes to syntax !
* actions use OS_ReadArgs.
* Nested action blocks.
- Added interactive help support.
- Changed key bindings.
0.11 - 08-Feb-90 RMokady - Some more changes to syntax.
* added external menus.
* added colourmenu menu.
* added action on non leaf entries.
* added noreopen option for dbox.
* added submenu -1 support.
- added section about built in actions.
- added onclick section.
To do:
------
Escape sequences in quoted strings.
Help actions.
Better key names.
The 'ctl' module is a set of library facilities, written in C, allowing a
program to put a great deal of user event decoding into a resource file.
This file controls the mapping of menu, dialogue box and key events into
textually named actions, which are then executed by the program. It makes
programs easier to construct, and means that the result is customisable (to
some extent) by the user.
This is always called Control, and is a resource file within an application
directory.
File Syntax
-----------
# starts a comment line. Blank lines are ignored.
Each line is split into symbols, separated by spaces.
A symbol is any character sequence in matching quote marks, OR any
alphanumeric char sequence (underscore is also allowed, and the first
character may not be a number).
Escape sequences within quoted symbols are currently not supported.
Examples: hello
delete_file
"Hello there"
Symbol comparison is case-sensitive. Conventionally all keywords within a
Control file are entirely in lower case.
In the ensuring descriptions, items in angle brackets (unless otherwise
stated) are all symbols.
Actions and Action sequences
----------------------------
An action is a symbol.
Anything after the action on the same line is treated as arguments to the
action, arguments can be continued on the next line if the NL is immediately
preceded by \, otherwise a NL character is treated as space.
The symbol is the name of an operation that the application supports,
the actual set of operations available is defined by the application.
An action block is a sequence of one or more actions grouped inside
matching '{' , '}'. Action blocks can appear anywhere a single action can
appear. Action blocks can be nested. The closing '}' should be on a separate
line, otherwise it will be taken to be part of the argument list for the
preceding action.
so an action block should look something like:
... {
action1 args
action2 args
action3 args
} ...
You can have other symbols on the line following the '}' as it is not
an action.
Actions return an integer return code which is then passed on to the next
action executed.
Built in actions.
-----------------
The following built-in actions are always available:
error <error message> -- Produce the specified error message,
in the standard Wimp error message
window.
oscli .... -- The argument is passed to the OS_CLI.
OR * ...
showdbox <dbox name> -- Cancel the current menu and show
this dialogue box as a menu. (I.E. clicks
outside it close it).
quit -- Quit the application (I.E. calls exit(0)).
process -- See hot keys section below.
if <expr> -- Tests the return code returned from the last
action, if it is equal to <expr> the following
action or action block is executed, if not
the action or action block is skipped.
else -- Can only come after an if action, if the if
test failed the action or action block following
this action will be executed, if not it will be
skipped.
<Number> -- A number on its own simply sets the return code
to its value.
For example:
5 an_action
will pass a return code of 5 into an_action.
A control object header
-----------------------
Syntax: ctl <logical control object name>
This starts entries in a named control object.
A menu header
-------------
Syntax: menu <menu name> <menu title> <menu body>
OR menu <menu name> <menu title> colourmenu
OR menu <menu name> external
Used to start the declaration of a menu.
The first form defines a simple menu:
<menu title> is the text used for the menu title, if it is a valid
message token from the Messages file, the message text is used,
otherwise the actual text is used.
<menu body> is the menu body in the syntax used for menu_new, again this is
first matched against message tokens in the Messages file.
Note:
The menu body text should not include the ! and > symbols,
as submenus, and greying of menu entries is handled by the
ctl module (see below).
The second form is like the first form, but the menu body is a colour
selection menu (like the one used by edit to set the text colours).
The third form defines a menu who's title and body are specified by the
application at run time. Range checking on entry and submenu numbers is only
done when the application attaches the wimp menu structure at run time.
A Menu help token /action
--------------------------
Syntax: help token <token>
OR help action <action> (or action block) <-- NOT YET IMPLEMENTED
The first form gives a token for the interactive help messages to be used
with this menu the entry number (starting with 1) will be appended to the
token before it is searched for in the Messages file.
The second form gives the action sequence to be performed when help is
requested, the result code passed to the first (or only) action is the menu
entry number.
A menu open action
------------------
Syntax: onopen <action> (or action block)
This describes the actions to be performed when the menu is opened.
A menu reopen action
--------------------
Syntax: onreopen <action> (or action block)
This describes the actions to be performed when the menu is reopened,
as a result of the user using the ADJUST button.
A menu entry
------------
Syntax: entry <entry number> action (or action block)
This describes the actions to be performed when the user clicks
on the entry.
Entry numbers are checked against the number of entries in the menu,
and errors are generated if you try to specify an out of range entry number.
Entries on the menu which don't have actions defined for them, are greyed
out (unless they have submenus attached to them, see below).
An entry number of -1 means 'default' , if actions are specified for entry
-1 , entries with no actions will not be greyed out, but the actions
specified for entry -1 will be used for them.
The return code passed to the first action is the entry number on which
the user clicked.
A submenu
----------
Syntax: submenu <entry number> menu <submenu name>
OR submenu <entry number> dbox <dbox name>
OR submenu <entry number> warning action (or action block)
OR submenu <entry number> menu <submenu name> action (or action block)
OR submenu <entry number> dbox <dbox name> action (or action block)
The first form indicates a non-leaf menu entry. The submenu name must refer
to a previously defined menu, and matches the menu name given in the menu
header.
The second form indicates a non-leaf menu leading to a dbox. The dbox name
must refer to a previously defined dbox, and matches the dbox name given in
the dbox header.
The third form indicates a non-leaf menu entry which leads to some actions
this is different from entry n action ... because a right arrow will be
displayed in this position on the parent menu.
The fourth form is like the first form but allows you to specify the actions
to be performed if the user clicks on the menu entry leading to the submenu.
The fifth form is like the second form but allows you to specify the actions
to be performed if the user clicks on the menu entry leading to the dbox.
You can not have both
entry n action ...
and submenu n ...
for the same menu.
If you use -1 as the entry number, all entries without specific actions / or
submenus will lead to the submenu / dbox specified.
The end of a menu
-----------------
Syntax: endmenu
This should appear at the end of a menu description. Menu descriptions
cannot be nested.
A dialogue box header
---------------------
Syntax: dbox <dbox name>
Used to start the declaration of a dbox.
A dialogue box template name.
-----------------------------
Syntax template <template name>
The correspondingly named template
(typically in the resource file Templates) will be used to describe the
visual appearance of the dialogue box. The template directive must appear
before any icon actions in the dbox description.
A dialogue box help token /action
---------------------------------
Syntax: help token <token>
OR help action <action> (or action block) <-- NOT YET IMPLEMENTED
The first form gives a token for the interactive help messages to be used
with this dbox the icon number (starting with 0) will be appended to the
token before it is searched for in the Messages file. Unless the pointer is
not over an icon in which case the unmodified token will be used.
The second form gives the action sequence to be performed when help
is requested, the result code passed to the first (or only) action
is the icon number (or -1 if not over an icon).
A dialogue box open action
--------------------------
Syntax: onopen <action sequence>
This describes the actions to be obeyed every time a dialogue box is opened
(and just before it is first displayed).
A dialogue box reopen action
----------------------------
Syntax: onreopen <action sequence>
This describes the actions to be obeyed every time a dialogue box is
reopened (as a result of the user clicking ADJUST on an icon).
Dialogue boxes with noreopen.
-----------------------------
Syntax: noreopen
This prevents the dbox from being reopened by a right click.
If the user right clicks in the dbox the menu tree from which the dbox is
hanging will remain open, but the dbox will be closed.
You can not have both onreopen and noreopen in the same dbox description.
A dialogue box close action
---------------------------
Syntax: onclose <action sequence>
This describes the actions to be obeyed every time a dialogue box is closed.
A dialogue box icon action
--------------------------
Syntax: icon <icon number> <action sequence>
This describes the action to be taken when a hit occurs on the specified
icon.
Icons which don't have an action defined for them will be greyed out, unless
their button type is 'Never'.
An icon number of -1 means 'Default', if actions are specified for icon -1,
icons without actions will not be greyed out, but the actions specified for
icon -1 will be used for them.
The return code passed to the first action is the icon number.
The end of a dbox
-----------------
Syntax: enddbox
This should appear at the end of a dbox description. Dialogue box
descriptions cannot be nested.
Keystrokes
----------
Syntax: onkey keycode <action> (or action block)
OR: onkey [S][C] <keyname> <action> (or action block)
OR: onkey <Default> <action> (or action block)
with the first form the keycode (as returned by the W)mp is given)
with the second form, the key name is given, key names are:
For any normal key the symbol on the key (i.e. a for unshifted a or A for
shift+a). For special keys <keyname> (i.e. <f5> or <Print> with the angle
brackets as part of the name). The key name can be preceded by C to specify
Control+key or by S to specify Shift+key. S and C can be combined, so SC<f1>
is Shift+Control+<f1>.
Example:
onkey Sa action
onkey A action
onkey 65 action
are all equivalent.
Note: To specify Uppercase s or Uppercase c use Ss & Sc as S or C will
result in a syntax error. to specify # use S3 as # will begin a comment.
The key name <Default> is used to mean any other key.
The result code passed to the first action on the list is the key code.
The action process passes the key to the wimp, so
onkey <Default> process
will result in all undefined key presses being passed to the wimp.
The onclick action.
-------------------
Syntax: onclick action (or action block)
This specifies the actions to be executed when the user clicks on an icon in
the window to which the ctl is attached. The main use of this is for ctls
attached to the iconbar.
The return code passed to the first action on executed is the mouse button
state as returned from the wimp in the wimp_EBUT event.
The end of a 'ctl'
------------------
Syntax: endctl
Apache License
Version 2.0, January 2004
http://www.apache.org/licenses/
TERMS AND CONDITIONS FOR USE, REPRODUCTION, AND DISTRIBUTION
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