Bottom     Contents

StrongED

Mode files 1

Introduction 1

Finding the mode files 1

Creating a new mode 1

Editing an existing mode 1

StrongMode 2

Mode file parsing 2

Forcing parsing 2

Mode file structure 2

Options 3

ModeType 3

HelpPath 3

PrintHead PrintFoot 3

Bitmap 4

ID 4

ID_Middle 4

ID_FirstChar 4

ID_LastChar 4

FoldParm1 FoldParm2 4

Search 5

Special search expressions 5

_Indent 5

_MarkWord 5

_MoveWord 5

_DeleteWord 5

_SpellIgnore 5

_ParPrefix 5

ModeWhen matches 5

_Dumptest 5

_Newstest 5

_HTML 5

_Perl 6

Replace 6

SyntaxOptions 6

SingleQuote 6

DoubleQuote 6

QuoteQuote 6

SplitString 6

QuoteChar 6

HexPrefix 6

BinPrefix 6

SyntaxComment 7

Type 7

StartWith 7

EndWith 7

SyntaxWords 7

CaseType 8

Case 8

NoCase 8

WhereType 8

StartOfLine 8

StartSpace 8

EndType 8

EndAlways 8

EndNonID 8

EndOfID 8

EndOfLine 9

EndOfExpr name 9

Assembler EndTypes 9

EndAsm 9

EndSTM 9

EndBL 10

KeyList 10

Key definitions 10

Key sequences 10

Keypresses 10

Keynames 11

General KeyLists 11

Mode 11

Global 11

CopyCursor 11

Dialogue Keylists 11

Validation Strings 11

Dialogue functions 12

Errors 12

Interactive 12

SearchReplace 12

LoF_dbox 12

WhatNext 12

SaveBox 12

Print 12

ListOfFound

ListOfWinds

Throwback 12

ClickList 13

Mouse ClickLists 13

Default mouse clicks 13

Named ClickLists 13

Functions 14

Function 14

Icon 15

Menu 15

Help 15

Click 16

Key 16

Example 16

Shortcuts 17

Shortcut 17

Replacement 17

WriteProtect 18

Application Modes 19

Directory structure 19

!Boot 19

!Help 19

!Run 19

!Sprites[22] 20

Choices 20

ModeFile 20

Resources 20

Messages 20

Sprites[22] 20

ModeWhen 20

File structure 20

Mode section 20

Load definition 21

Loadtype 21

! 21

- 21

> 21

Filetypes 21

* 21

~ 21

Filepaths 21

* 21

** 21

Match 21

Examples 22

Appendix A

Keynames 24

Appendix B

Help tokens 24

Mode files

Introduction

The way a user sees StrongED is defined by its modes. The foundation for these is the BaseMode, on which other modes are built. The possibilities available to the writer, or modifier, of a mode are very large indeed, and cannot be described simply.

A mode is principally defined by a plain-text mode file and its associated options stored in StrongED's 'Options' data file. More complex modes are defined by a set of files stored in an application directory as an application mode. Within this the mode file is called 'ModeFile'!

A single, plain-text, 'ModeWhen' file defines which mode is used for a particular file, chosen by filetype, name, position or content.

This document only deals with how mode files are constructed and edited. There are many references to features of StrongED for which no further explanation is given here. These are indicated by a 'œ'.

With all respect to the author, modes files do have the appearance of having been designed ad hoc as the program had more features added over the years of development. This means that the way they are written is not very consistent.

StrongED is so flexible that in many cases there will be more than one way of achieving the same result.

Finding the mode files

Click <shift-select> on the iconbar icon to open the directory containing the configuration files in '!StrEd_cfg' or click <shift-adjust> to open the '!StrongED. Defaults' directory. In either case, open the 'Modes' directory to view the mode definitions. Open an application mode with double-click <shift-select> to view its 'ModeFile'

Creating a new mode

To create a new mode, click <select> on the iconbar icon to create a new file. After writing the mode, save it into a 'Modes' directory with a suitable name. The new mode will only become available after StrongED has been quit and reloaded.

Editing an existing mode

A simple way to edit an existing mode file is to open a document using that mode, then click on the last item on the main menu, which is the name of the mode. This loads the mode file without opening directories.

Alternatively, open the 'Modes' menu and choose a mode while holding <shift>.

The BaseMode file can also be loaded by clicking <ctrl-adjust> on the iconbar icon.

StrongMode

StrongED is distributed with a mode called StrongModeœ which is designed to aid the editing of mode files. Once a mode file is loaded, it can be edited in 'StrongMode' by choosing it from the 'Mode>Change mode' submenu.

Mode file parsing

When StrongED is run, it parses mode files in both 'Mode' directories and constructs its menu of available modes. It must find a BaseMode or it gets into bad trouble later.

Note that a mode in '!StrEd_cfg' takes precedence over one with the same name in '!StrongED.Defaults'

If an error occurs in a mode file it may bring up a parsing error window showing the file name, line number and error type, and it will also load the file.

Fig 1 - Parsing Error

However, not all errors are helpfully trapped. Some error reports are obscure and other errors may just crash StrongED. One error, at least, prints a message in the top- left corner of the screen.

Forcing parsing

If a mode file is edited and saved after StrongED has run, it will not be parsed again unless the 'Reload all modefiles ...' option in 'Global Choices - Edit' is selected. In that case all mode files are parsed. This can cause delays if there are a large number of documents open, so its is best to modify mode files with a just a test file loaded.

Mode file structure

A mode file is divided into a list of options and a number of named sections, some of which are only used in the BaseMode. None of them are obligatory in other mode files, which default to the the BaseMode definitions.

A section comprises:

By convention, the title and end are not indented and the definitions are.

Here are some rules, which show little consistency unfortunately:

Named search and replace expressionsœ are used widely in mode files, but their syntax is not covered here.

Likewise, StrongED functionsœ are used in several places, but there are too many to cover here.

Options

The options are usually placed at the beginning of the file, conventionally in the following order. Whitespace characters, space or tab, separate the option name from its definition.

ModeType

This is undocumented, but is used to indicate special handling for the Dumpœ and TaskWindowœ modes only.

ModeType	TaskWindow

HelpPath

A comma-separated list of StrongHelpœ manuals. This is the order that manuals will be searched to lookupœ a word using <f1> etc.

HelpPath	Basic,Assembly,

A final comma indicates that any other available manuals will also be searched after those in the list. The the default is to search all available manuals.

PrintHead
PrintFoot

A pair of strings that are printed at the head and foot of each page of a printout of a document, if this feature is enabled in 'Mode Choices - Misc', or the 'Print' dialogue box.

These may include the escape sequences described in the Shortcuts section, and system variables, perhaps set up by StrongEDœ.

PrintHead	<tmp$leaf>
PrintFoot	<tmp$page>

I am not sure that this (still) works.

Bitmap

The name of the bitmapœ sprite file to use for the character shapes displayed in this mode.

Bitmap	System

ID

Three sets of characters defining what is considered to be an identity (ID) in the mode. An ID is used to identify 'words' in the document and colourœ them, perhaps with reference to the 'SyntaxWords' sections.

A set of characters is defined in the same way as in a search expression, except that it does not have enclosing single quotation marks.

ID_Middle

A word is only identified if it consists exclusively of these characters, except:

ID_FirstChar

If defined, the first character is restricted to one of these characters.

ID_LastChar

If defined, the last character may also be one of these characters.

In 'BASIC' mode an ID is a variable name:

ID_FirstChar	A-Za-z_`
ID_Middle	A-Za-z_`0-9"
ID_LastChar	$%

FoldParm1
FoldParm2

Two fold parameters used to control how parts of a document are hidden by foldingœ.

FoldParm1 ("REM{","REM}",StartOfLine,Case)
FoldParm2 (foldstart,foldend,StartOfLine,Case)

In this example foldstart and foldend are search expressions; see below.

Search

One of these sections will contain definitions of named search expressions. A definition comprises a unique name followed by whitespace and then the expression.

Named search expressions will usually be used elsewhere in the mode file, eg in Functions, FoldParms, SyntaxWords and ClickLists. They may possibly be defined for the user to enter into advanced searchesœ.

Search
 foldstart	"DEF"
 foldend	"ENDPROC" | ("="*>) {NL}+
End

It is often convenient to place a Search section close to the place where its named expressions are used.

Special search expressions

There are a number of special named search expressions that are required by internal routines, rather than used in a mode file. Most of the examples below are based on the default values in BaseMode.

_Indent

Defines the default for the characters at the start of a line that may be used as an automatic indent in the function NewLine.

_Indent	{" "|"\t"}

_MarkWord

Defines what will be marked as a word on <double-click-select>.

It may also be used in some functions and in ClickLists.

_MarkWord	{AlphaNum|"_"}+|{Punct}+|{' \t'}+

_MoveWord

Defines what is a word to the left or right in the functions WordLeft and WordRight.

_MoveWord	{AlphaNum|"_"}+|{Punct}+

_DeleteWord

Defines what is a word to the left or right in the functions DeleteWordLeft and DeleteWordRight.

_DeleteWord	_MoveWord

_SpellIgnore

Defines words that will be ignored by the function SpellCheck. This does not apply to check-as-you-type

uchar	'A-Za-z_0-9./~+\-:;,?%@&#='
http	"http://"|"ftp://"|"mailto:"|"telnet://"|"stronghelp:"{uchar}+
www	"www."{uchar}+
epart	{'A-Za-z0-9_\-'}+
email	epart{'.'epart}"@"epart
_SpellIgnore	email|http|www|({Upper}+ ~?)

_ParPrefix

Defines what is considered as the indent of a paragraph for the HardWrap routine and the function Reformat.

_ParPrefix	{'>|*' [' ']} {' '}

ModeWhen matches

BaseMode has a number of special named search expressions that are used in the default ModeWhen file.

_Dumptest

Use Dumpmode if, after skipping the first 4 chars, there are no more than 4 "normal" characters, followed by a ctrl char.

_dump0	'\x09\x0a\x0d\x20-\x7e\x80-\xff'
_dumptest	{.}4:4 {_dump0}0:4 ~_dump0 any

_Newstest

Use newsmode if there is a line starting with "From:"

_newstest	** ( < "From:")

_HTML

Use HTML if an <html> tag is found at the start of the file

_html		"<html>"

_Perl

Use Perl if #!Perl is found at the start of the file

_perl		"#!" * "perl"

Replace

One of these sections will contain definitions of named replace expressions. A definition comprises a unique name followed by whitespace and then the expression.

These will be used less frequently than searches, and mainly as parameters in StrongED functions.

Search
 _wrap	~NL Any @1 {" "} NL ~ NL|"\t"|" "
End
Replace
 _rwrap	@01 " "
End

This pair is used to implement the menu choice 'Wrap' in BaseMode.

StrongED has no special named replace expressions.

SyntaxOptions

This is a set of 7 options which are used to define how text may be colouredœ. Whitespace characters, space or tab, separate the option name from its definition.

SingleQuote

yes | no

Is a set of characters enclosed in single quotation marks to be coloured as a string?

DoubleQuote

yes | no

Is a set of characters enclosed in double quotation marks to be coloured as a string?

QuoteQuote

yes | no

Is a pair of double quotation marks inside a string to be coloured as part of the string? I am not sure this has any effect.

SplitString

yes | no

Is a string which goes onto a new line to be coloured as continuous? I am not sure that this works.

QuoteChar

A single character that can be used to prefix quotations. I do not think the author is sure what this is for.

HexPrefix

A string of characters that is used to prefix hexadecimal numbers. Usually just one character.

BinPrefix

A string of characters that is used to prefix binary numbers. Usually just one character.

SyntaxOptions
 SingleQuote	no
 DoubleQuote	yes
 HexPrefix	&
 BinPrefix	%
End

SyntaxComment

1 | 2

Two types of comment may be defined for a mode. They are both coloured the same, and take precedence over any other colours. Each is defined by three options.

If only one type of comment is defined it does not need a numeric parameter.

Type

One of:

StartWith

A string that identifies the start of a comment.

EndWith

A string that identifies the end of a comment. A multiline comment must have this.

A possible bug means that it is probably wise to give a OneLine comment a default EndWith string of NL.

SyntaxComment 1
 Type	OneLine
 StartWith	REM
 EndWith	NL
End
SyntaxComment 2
 Type	OneLine
 StartWith	; 
# note trailing space
 EndWith	:
End

SyntaxWords

Group1 - Group8 CaseType WhereType EndType

Eight groups of reserved words can be defined and each may have a separate colour. The words themselves are entered on as many definition lines as required, separated by whitespace. If actual spaces are required, double quotation marks are used.

The power of this section comes from the parameters following the title, which specify how words are accepted for colouring. They may be in any order.

CaseType

- optional. Defines how the case of a word affects when it will be accepted. The default is that words are not case sensitive.

Case

A word is accepted exactly as it is entered.

NoCase

This is a possible parameter, but I think its effect is faulty, and it is not needed anyway.

WhereType

- optional. Defines where in the text a word will be accepted. The default is that a word is accepted anywhere.

StartOfLine

A word is only accepted if it is at the start of a line.

StartSpace

A word is only accepted if it is at the start of a line except for whitespace.

EndType

- must appear. Defines how a word is accepted and coloured among the rest of the text, once it has been found.

EndAlways

A word is accepted exactly as it is entered wherever it is in the text. Thus 'to' will be coloured even when it is in "tonight" or "bottom".

SyntaxWords Group1 EndAlways Case
 LOCAL RETURN ENDPROC END ERROR CLOSE
 CASE OF WHEN OTHERWISE ENDCASE
 FOR TO STEP NEXT IF THEN ELSE ENDIF
 REPEAT UNTIL WHILE ENDWHILE
End

These words are tokenised in BASIC wherever they appear in uppercase.

EndNonID

A word is accepted if the next character is not one of those defined in the 'ID_Middle' set. Thus 'to' will be coloured in "to " or "to," but not "top".

SyntaxWords Group2 EndNonID
 OPT EQUS EQUD EQUW EQUB DCB DCW DCD
 LSR LSL ASR ASL ROR ROL RRX
End

These 'words' cannot be limited by case but they should not be coloured if they appear in the middle of other text.

EndOfID

A word is accepted exactly as it is entered wherever it is, and colouring continues with the following characters as long as they are defined in the 'ID_Middle' set. Thus 'to' will be coloured in "to." but "top." and "together " will also be coloured.

SyntaxWords Group3 EndOfID Case
 PROC FN SYS OSCLI CALL USR
 OPENIN OPENOUT OPENUP LIBRARY OVERLAY
End

These words will colour the following text, highlighting the whole structure name.

EndOfLine

A word is accepted exactly as it is entered wherever it is, and colouring continues until the end of the line. Thus 'to' will also colour "together we can make it.".

SyntaxWords Group4 StartSpace EndOfLine
 DEF
End

This word will highlight the whole line it starts, making it stand out.

EndOfExpr name

Name is a named search expression that must be defined in a Search section earlier in the mode file. A word is accepted exactly as it is entered and if it is followed by a match to the expression both the word and the match are coloured. Thus if the search expression is the set 'mnop' then 'to' will colour "tom", "ton", "too" and "top" but not "tot" or "torn".

Search
 _hash	{" "}"#"
End
SyntaxWords Group5 EndOfExpr _hash Case
 CLOSE INPUT PRINT EOF PTR EXT BGET GET$
End

These word can/will be followed by "#", but there can be spaces between. The expression allows for any number of spaces.

Assembler EndTypes

There are three special EndTypes for use with assembler code:

EndAsm

A word is accepted if the following characters match an optional assembler conditionœ and optional suffixœ.

SyntaxWords Group 6 EndAsm
 ADD ADC SUB SBC RSB RSC
 BIC TST ORR TEQ CMP CMN
 STR LDR MOV MVN ADR
End

EndSTM

A word is accepted if the following characters match an optional condition and/or stacktypeœ. This should only contain "LDM STM".

SyntaxWords Group 7 EndSTM
 LDM STM
End

EndBL

A word is accepted if the following characters match an optional L and/or condition. This should only contain "B".

SyntaxWords Group 8 EndBL
 B
End

KeyList

Type

Nearly all keypresses can be defined by tying them to a list of StrongED functions in a KeyList.

Type specifies when the keylist is active. BaseMode uses several KeyLists, but all other modes can only define keys in the 'Mode', or default, KeyList.

Key definitions

A key definition is very flexible. At its simplest it is a keyname separated by whitespace from a function which will be executed when the key is pressed.

F8	Undo

There can be multiple functions separated by whitespace.

cs-X	CB_Copy BlockDelete

Functions can also be tied to multiple and repeated key sequences, and limited to the marked block.

c-W,c-H	SplitViewHor
cs-F1 2	ClearMark(1)
c-KpMin B	AddFold

Key sequences

The syntax for a key sequence is:

keypress {,keypress} [1|2|3] [B]

That is, one or more keypresses separated by commas, optionally followed by a number from 1 to 3 specifying how many times they must be repeated, and finally an optional "B" to limit the action to a marked block. Elements are separated by whitespace.

Keypresses

The syntax for a keypress is:

[c][s][-] keyname

That is, optionally one or both of the modifiers, <ctrl> (c) or <shift> (s) immediately followed by a "-", and a keyname. There are no spaces.

Although the <alt> (a) modifier can be used for ClickLists it cannot yet be used in KeyLists and Functions.

Earlier versions of StrongED used "^" and "‹", without a "-", for <ctrl> and <shift>, and these are still recognised.

Keynames

The keynames are:

The NumLock status is ignored

Keys with punctuation marks cannot be defined.

See Functions for an additional way to define keys.

General KeyLists

These keylist types operate while text is being edited.

Mode

This is the default when no type is specified. It used when entering text in a document window.

KeyList
	
End

Global

Always checked after the active KeyList. This also allows StrongED to take action when it does not have the input focus (caret), as long as keypresses are passed on by the application that does.

KeyList Global
	cs-F9	dbox_Chars
End

This definition allows the user to open the 'Chars' pop-up window at any time.

CopyCursor

Checked before the active KeyList when the copy cursor is invoked with <shift-Copy>. This is very unlikely to be used now.

Dialogue Keylists

These keylist types define the keypresses some dialogue boxes.

This area of StrongED is a bit untidy and not accurately documented in the StrongHelp manual. It all works in the standard BaseMode, but changes could produce some oddities.

Validation Strings

Icons that should have keypresses reflecting their text, eg c-C for 'case', would vary in different languages. To allow for this, they are defined as '&' commands in the validation strings of the icons rather than in the keylist; eg c-C for 'case' would be '&C'.

In the sections below, a capital letter in an icon name shows the control key defined in the UK Templates file, but overriding alternatives may be defined in the BaseMode file.

Dialogue functions

There are special functions for the dialogue keylists:

There do not appear to be any other useable functions.

Errors

When the BaseMode file is parsed there is an error if a key is defined for an icon that does not exist in a dialogue, and for functions that cannot be used. Other mistakes, such as using a the History function in a WhatNext keylist, are ignored and seem to have no detrimental effect.

Note too that there are acceptable icon names that have no actual effect and produce no errors. They are shown in brackets in the sections below.

Interactive

Interactive Search: 'Case', 'Old', 'Next', 'Prev', ['search'].

SearchReplace

Search/Replace: 'Advanced', 'Line', 'Case', 'Old', 'Scope', 'couNt, 'go', ['search', 'replace'].

LoF_dbox

List of Found dialogue box: 'Advanced', 'Line', 'Case', 'old', 'go', ['search'].

WhatNext

WhatNext?: 'Next', 'Replace', 'All', 'Undo', 'redo'.

SaveBox

Save text: 'Selection', 'Ascii' 'save', 'kill', ['name', 'type'].

Print

Print Text. This keylist is commented out in the BaseMode file of v4.60 and has no effect.

ListOfFound
ListOfWinds
Throwback

List of Found, List of Texts and Throwback windows can have keylists defined, but as there are no icons, they can have no effect. These may be relics of earlier versions of StrongED.

ClickList

Name

ClickLists are spooky! They originally defined actions to be taken when mouse buttons are clicked, but they now have a use that involves no clicking at all.

Name is either a specifier of a mouse button click or an identifying string.

Each line in a ClickList comprises a named search expression followed by a list of functions, separated by whitespace.

When a ClickList is invoked, each line is checked in turn. If the current 'word' in the document matches the search expression, its list of functions is executed, and the ClickList ends.

Mouse ClickLists

A ClickList written for a single click on <select> is named Select1. There are similar names for <adjust> and double clicks, and each may have <alt>, <ctrl> and <shift> modifier keys.

The name specification is:

[a][c][s][-] Select|Adjust 1|2

Silly example:

Search
 _stars	{"*"}+
End
ClickList as-Adjust2
 _stars	InsertStr("*")
End

A double-click <alt-shift-adjust> on one or more "*" will insert another "*" at the caret.

Default mouse clicks

Note that StrongED also takes action on clicks to mark blocks of text. A ClickList takes precedence over these so take care.

They were once defined in the KeyList but are now done internally, I think. Their effects are:

Named ClickLists

The name of a ClickList is passed as a string parameter to the ClickList() function to invoke it.

Search
 c_TRUE	"TRUE"
 c_FALSE	"FALSE"
End
ClickList Toggle
 c_TRUE	ToggleStr("FALSE")
 c_FALSE	ToggleStr("TRUE")
End
KeyList
 s-Home	ClickList("Toggle")
End

This example is in the standard BaseMode and toggles "TRUE" and "FALSE" in a document using <shift-Home>.

Functions

The Functions section is used to add smart icons to the toolbarœ at the top of a document window, and/or add an items to the 'Mode' submenu, and possibly define shortcut keypresses for these. Although a Function could add keypresses alone, this is better done in the KeyList.

It comprises any number of Function groups and subgroups, which are terminated by blank lines. Note that this means that the closing 'End' must be preceded by a blank line.

Take careful note that "Function", with an uppercase "F", refers here to a subsection of a Functions section and not to a StrongED function that will part of the action taken.

Function

A Function starts with a group and may have a number of dependent subgroups. Sensibly, a group contains one or both of Icon and Menu definitions and a Select (Click) definition. It may also have Key and Help definitions.

An Icon group can have subgroups for other Click definitions and associated Key definitions. Note that a Key definitions in a sub-groups must precede the Click definition.

It is wise to make this structure clear with comments, because group and subgroups can be confused:

Functions
# this is the start of a full Function
 
# this is a group
 Icon	icon name
 Help	help text or token
 Menu	menu text
 Key	shortcut keypress
 Select	function list

# this is a subgroup
 Key	another keypress
 Adjust	another function list
 
# and another subgroup
 ^Select	another function list
 
# this is the end of the Function
 
# this is an icon only Function
 Icon	icon name
 Help	help text or token
 Key	shortcut keypress
 Select	function list
 
 Key	another keypress
 Adjust	another function list
 
# end of icon Function
 
# this is a menu only Function
 Menu	menu text
 Help	help text or token
 Select	function list
 
# end of menu Function
End

Icon

An Icon definition is the name of a sprite, which should be 30 by 30 pixels in square-pixel modes.

The sprite will be looked for in an application mode's 'Sprites[22]' file, then the '!StrongED.Resources.Sprites[22]' file and lastly in the Wimp sprite pool. If the sprite is not found a blank icon is shown.

The plan is that icons common to all modes are in StrongED, and a mode that has its own icons is an application. The opportunity exists to use Wimp's sprites if suitable ones exist, eg the tick for Choices.[1]

Menu

A menu text cannot be internationalized using a message token; see below.

Help

A Help definition is one of:

If a Function has both Icon and Menu definitions, the same Help is shown for each, which can be confusing. A further problem is that menu Help cannot be a token. This arises from the way that StrongED builds menus from its own format in the 'Messages' file.

For simplicity, it is recommended that a group is always just for an icon or a menu. See example below for more.

Click

A Click is either Select or Adjust, and may be preceded by the modifiers ^ and ‹ for <ctrl> and <shift> but not "c-" or "s-" (yet).

[^][] Select|Adjust

A Click definition is a list of StrongED functions, as with a KeyList.

An Icon group can have several Click definitions, in its subgroups, which determine the actions taken when the the smart icon is clicked on by the user in different ways.

A Menu group can only have one Click definition, which had best be Select, although any other one has the same effect.

Key

A Key definition follows the same rules as a key sequence in a KeyList.

Example

This is a set of Functions I wrote for BASIC to split comma-separated lists, and colon-separated statements, onto separate lines, to make the contents clearer for editing. They need to be joined again before saving, of course.

The lists are recognized only in the appropriate structures and each item must be preceded by spaces.

I have used Adjust for the the Click in the second menu Function just to make the association with the Icon Function; it has no other significance.

Could there be a neater way to achieve the same?

Search
#-Find CSV lists
 Schar	,(:='|"("|"DATA"|"READ"|"LOCAL"|"DIM"
 CSpace	Schar@1{" "}+ CNewL
Schar@1NL{" "}+End
Replace
#-Split CSV lists
 CSplit	@01NL"  "
#-Join CSV lists
 CJoin	@01" "
End
Functions
#-Split/Join CSV lists
 Icon		split
 Help		HBa_spl
 Key		cs-S
 Select	Replace (CSpace,CSplit)
 
 Key		cs-J
 Adjust	Replace (CNewL,CJoin)
 
 Menu		Split lists ^‹S
 Help		Split comma-separated lists
 Select	Replace (CSpace,CSplit)
 
 Menu		Join lists ^‹J
 Help		Join comma-separated lists
 Adjust	Replace (CNewL,CJoin)
 
End

Token in the 'Messages' file:

HBa_spl:\Ssplit comma-separated lists|M
\Ajoin comma-separated lists

Shortcuts

A shortcut is a way to type common strings using only a few keypresses.

A shortcut definition comprises a shortcut string followed by a replacement string, separated by whitespace.

Shortcut

A shortcut string is up to 7 plain, case-sensitive, typed characters.

Replacement

A replacement string can contain escape sequences:

If there are several \@ sequences, the caret is placed at the first, and moves to the next when <return> is pressed, as long as the caret remains in the replacement text.

A shortcut cannot be replaced if the typed text is already defined in a KeyList or Function, which would be unusual.

When typed, a shortcut must also be distinct from the surrounding text, which will usually be the case if it is separated by whitespace. Some experimenting may be needed, since the author is not very specific about this!

Shortcuts
 dp#	\nDEFPROC\@(\@)\n \@\nENDPROC\n
End

Typing 'dp#' expands to:

DEFPROC¦(¦)
 ¦
ENDPROC

The ¦ symbol is used to show the caret positions.

An option in 'Choices - Edit' controls whether shortcuts are expanded.

WriteProtect

This section is used to protect files from accidental modification.

If the name of a file is loaded into this mode matches one of these definitions, StrongED will behave as if the file were write protected, and displays a transient warning if you try to edit it.

To edit the file, untick 'Locked' in the 'Misc' menu. In this case only, you can lock the file again, otherwise the choice is greyed out.

The file matching syntax is the same as that in the ModeWhen file.

WriteProtect
 ;**.old.**
 fff;**.Clib.h.*
End

Application Modes

A mode defined in a single mode file can only draw on the Sprites and Messages resources that are part of the StrongED application, and the user choices are stored in the one 'Options' file shared by other modes.

This is not flexible when a mode is to add smart icons and menu items, with help messages that should be internationalized. An application mode is a way to include private resources within a mode.

Directory structure

!ModeName
	!Boot *
	!Help *
	!Run *
	!Sprites *
	!Sprites22 *
	Choices
	Documents
		Manual *
	ModeFile
	Resources
		Germany
			Messages +
		UK
			Messages +
	Sprites +
	Sprites22 +

The name of the mode is the name of the application, including the "!".

Files labelled "*" are cosmetic, and can be omitted without affecting the mode itself.

Files labelled "+" may not be required.

!Boot

There is no use for such an Obey file at the moment, but StrongED could easily be made to Filer_Boot all application modes on loading. One possibility would be to add a temporary manual to StrongHelp, but that is not supported.

!Help

This is the application help Text file that should give brief details about the mode, author, version number and where more information is stored.

!Run

This is an Obey file to open the application directory, and perhaps load a manual, when the user double-clicks on the application.

Filer_OpenDir	<Obey$Dir>
Filer_Run	<Obey$Dir>.Documents.Manual

'Manual' could be a StrongHelp manual.

!Sprites[22]

These files provide application sprites for the filer display.

Choices

This Data file will be generated by StrongED when the user saves from the 'Mode Choices' dialogue box.

ModeFile

This Text file is the mode file itself.

Resources

This directory holds the international resources. Each sub-directory is for one territory.

Messages

The mode file should make use of message tokens for HelpText definitions in the Functions section, rather than use plain text. This allows other language versions to be produced simply by writing a new 'Messages' Text file.

As noted under Functions, Menu definitions and help cannot use tokens at the moment, which is a pity.

Sprites[22]

These files provide the sprites for the smart icons.

ModeWhen

The 'ModeWhen' file defines which files will be loaded into StrongED when they are double-clicked in a filer window, and which mode should be used for the file when it is loaded.

It is not part of the mode definitions themselves, but it is integral to the use of modes, and will almost certainly contain a section for each mode installed.

As with the modes, the 'ModeWhen' file is found either in the '!StrED_cfg' or the '!StrongED.Defaults' directories. The one in '!StrED_cfg' takes precedence.

It can be loaded without opening a directory by clicking <ctrl-select> on the iconbar icon, and it is parsed whenever it is saved.

File structure

The 'ModeWhen' file consists of a number of mode sections containing load definitions. These are searched in the order they appear, which is an important consideration when a new section is to be added.

It is possible to have multiple sections for a mode, giving different precedence to different files.

If a mode is not installed, its corresponding sections are ignored.

The text in the mode sections is not case-sensitive.

Single line comments can be included anywhere and start with a "#" at the left-hand margin. It is useful to have lots of comments.

Mode section

A mode section starts with the full name of a mode, including the '!' for application modes.

The name is followed by a number of lines with definitions for loading a file into that mode.

A mode section ends with a blank line.

# Obey section from default ModeWhen file
Obey
! feb,**
! fd7,**

# load all Obey and TaskObey files with <shift> double-click

The !Dump mode name, only, is followed by a comma and a mode parameter: 0, 1, 2, or 3 for Byte, Word, Ascii or Assembly displays.

Load definition

A load definition consists of an optional loadtype, a filetypes specification followed by a comma, a filepaths specification, and then an optional space, comma and a match expression:

[loadtype] filetypes , filepaths [ , match]

The commas may be replaced by colons.

Loadtype

No loadtype means that files that satisfy the rest of the definition are always loaded in this mode when double-clicked.

!

Only files that are double-clicked with <shift> are loaded.

-

Only files that are passed by the external edit protocol are loaded.

>

The file is loaded and then the contents are tested against the match expression before it is displayed.

Filetypes

The filetypes specification consists of one or more hexadecimal numbers, from 000 to FFF, separated by spaces.

*

Represents all filetypes. (This is also assumed if there are no filetype numbers.)

~

At the start of the list, excludes all those filetypes from the description.

Filepaths

The filepaths specification consists of one or more wildcarded filepaths separated by spaces. These are matched against the full pathname of the file to be loaded.

*

Represents anything but '.', the separator for directory names.

**

Represents anything at all.

( taskname)

At the start of a path this represents the task passing an external edit, and is used with the '-' loadtype. (?)

Match

A match expression is only used with the '>' loadtype.

It is the name of a search expression defined in the BaseMode file, which will be matched exactly to the start of the file, and up to 1 kbyte in.

Note that to search for something after the start of the file the match expresssion must start with '**'.

Examples

These examples are modified from the default ModeWhen file, with added comments.

# C programming
C
# load any Text file in a C or H directory
 fff,**.C.* **.H.*
# <shift>-load any file with a C or H extension
!*,**/C *,**/H

## the default file has these on separate lines

# edit News and Mail messages
!News
# load any Text file in an OLEfiles directory that starts with "mar" (Marcel)
 fff,**.OLEfiles.mar*
# load any Text file passed as an external edit by Pluto - this does not look quite right
 fff,(Pluto)**

# load any Text file if the content matches the _Newstest expression

>fff, ** ; _Newstest

##

# edit external files
External
# load any Text files passed by the external edit protocol
-fff,(*).**

##

# edit disassembled code
!Dump,3
# <shift>-load any Absolute or Module file
! ff8 ffa,**

## this could include ffc for Utility files

# edit binary files
!Dump,0

# load any file, except Absolute or Module, if the content matches the _Dumptest expression

> ~ ff8 ffa,** ; _Dumptest

##

Appendix A
Keynames

These are the keynames that are recognized for use in menu items:

F1 F2 F3 F4 F5 F6 F7 F8 F9 F10 F11 F12
Esc ESC Print PRINT Break BREAK Pause PAUSE
Tab TAB Return RETURN Enter ENTER Copy COPY
Insert INSERT Home HOME PageUp PAGE UP
Delete DELETE End END PageDown PAGE DOWN
Up UP Down DOWN Left LEFT Right RIGHT
Select SELECT Menu MENU Adjust ADJUST
Acorn ACORN

They can be preceded by a combination of the modifiers ^ ‹ for <ctrl> and ‹ <shift>

Appendix B
Help tokens

These are the HelpText shortcuts that can be used in Help definitons:

\S:Click SELECT to 
\R:Move the pointer right to 
\A:Click ADJUST to 
\T:This is the 
\G:This option is greyed out because 
\W:This window is 
\D:Drag SELECT to 
\d:Drag ADJUST to 

\w:window
\s:SELECT
\a:ADJUST

Note that all but the last three have trailing spaces when expanded.


[1]  There is a bug with version 4.60 and RISC OS 4.02 that means that this scheme does not work correctly. This may yet be fixed. A temporary solution is to include this line towards the bottom of StrongED's '!Run' file: IconSprites <StrongED$Dir>.Resources.Sprites



    Top