Archive Magazine 1995/ARCHIVE95.iso/discs/shareware/share_40/star/!Star/!Help

Text File | 1990-09-21 | 14KB | 357 lines

STAR - A configurable iconbar menu system

VERSION 0.0 Mon,17 Sep 1990

INTRODUCTION
  Star is a configurable wimp interface to non wimp programs such as
operating system commands and other programs. Star peforms no useful
functions itself, but allows files of additonal commands to be loaded. These
commands appear as menu items on the star menu. Star can pass file names to
the commands or programs.

 For example you can use star to

  Set the current directory
  Set filetypes
  Run the C compiler
  Load a BASIC program into the BASIC editor
  Translate BASIC to and from text
  Print text files

  Star allows you to write simple programs to perform useful tasks, but
still access them easily from the desktop.

RUNNING STAR
  Star is a standard RISC_OS application, and is run by double clicking on
its icon. Star needs version 3.5 or later of the shared C library and looks
for this in the system:modules directory as usual.
 The star icon then installs itself on the iconbar. Its only functions are
to provide access to a menu tree, and to provide somewhere to drag files.
When you drag files to the star icon it just remembers their names. The
number of files that it has seen is recorded under the icon, a maximum of 16
are allowed. The file names are remembered in order of arrival. If you drag
a group of files their order may be unpredictable. The file names are
forgotten after any menu selection. If you want to clear the files you have
dragged you can click on the Info selection in the star submenu.
 The only items on the menu tree that are provided by star itself come from
the star submenu. They are :-

                 Info     -    Info on star
                 Load     -    Load the named files as star menu items.
                 Unload   -    Remove previously loaded items
                 Error    -    Display star's last error message.
                 Quit     -    Quit star

  Star may also load one or more files of star menu items when it starts up.
These are named as command line arguments. You can change the files that it
loads at startup by editing star's !Run file.
  Star has one more possible command line argument, a single minus sign,
separated from the other arguments by spaces. If this is present the star
icon installs on the right hand side of the iconbar. This is against RISC_OS
practice, but leaves more room for menu selection. It must be the first
argument in the list.

e.g. If the last line of !Run is

   Run <Star$Dir>.!RunImage - <Star$Dir>.StarText.MyFile

Star will install on the right hand side, and load the file MyFile of menu
items.

  One of star's capabilities is to start up an editor and load a file into
it. It does this by looking at the Alias$@RunType_FFF system variable,
however if an editor is already loaded it is preferable to load the file
directly into the editor rather than starting up a new copy. To do this star
needs to know the name of your favorite editor as given in the task display
window. I use my own wonderful editor Ed (Archive shareware disk 31), but
you can use another RISC_OS editor such as Edit. You need only change the
system variable Star$Ed to the desired name, by replacing the line in !Run
with e.g. set Star$Ed Edit. Star will only recognise this editor if it was
loaded after star.
  Star needs a directory to hold temporary files, this is set in !Run to
RAM:$ if you do not have some RAMFS configured you can change this.
    E.g.
                   Set Star$Scrap system:$

Note - any menu items outside the star subdirectory are loaded from star
menu item files. The startup file provided is configured for my system, some
items are unlikely to run on your system without alteration. To get the best
out of star you will need to adjust some of the menu items, delete those you
don't want and write some of your own. If you create a lot of menu items you
may want to keep some in separate files and load them when needed.

STAR MENU ITEM FILES (Starfiles)
 Starfiles have file type FFF (Text). They consist of a sequence of lines
that are recognised by their first character (or their second if the first
is a '|' ). Spaces ARE significant in star files, a line beginning with a
space will be ignored.

A comment line is started with a semicolon. The rest of the line is ignored.
In the explanations below I will put comments beside the line they refer to.
You CANNOT do this in a real star file. Comments can only be whole lines.

A leaf menu item is named by a line starting by a colon. Immediately
following the colon is the name that will appear on the menu. This name
should not contain the five symbols ~>,!" . It should not be too long as
this will make the menu wide. The lines that follow this line up to the next
line starting with {} or : are the instructions that are executed when this
menu item is selected.

e.g.

:RootDir    ;start a menu item called RootDir
*Dir $      ;this is what it does


A submenu is named by a line starting with { followed immediately by the
name that appears on the menu. Items in the submenu then appear as above
until a line starting with } closes the submenu. Submenus can be nested. The
same restrictions apply to submenu names as to item names.

e.g.

{Files      ;start a submenu called Files
:Cat        ;first item in submenu
*Cat
{Dog        ;start a sub-submenu called Dog
:Bark       ;first item in sub-submenu
  .
  .
}
:TopCat     ;Third item in submenu
*Dir $
}

Clicking on a submenu name has the same effect as clicking on the first item
in the submenu. This can be a useful short cut, but you should be careful
which items you chose for the top of submenus. Normally star files to be
loaded should only have a small number of entries in the root level menu, to
avoid this becoming overcrowded.

Most of the remaining line types have string arguments. All these arguments
may be substituted and can be translated.
 Sustitution replaces a percent sign and some following characters by a new
string as follows

     %%         %
     %0 ... %9  1st filename ... tenth filename
     %!         All the filenames followed by spaces
     %?         nth filename (see below)
     %"string"  star prompts for input displaying string
                the input string is the replacement
E.g.

*Filer_Opendir %1       ;Opens the second filename given ( it had better have                         been a directory)

*emacs  %!              ;loads the emacs editor and loads all the files named

The filenames used in substitution may be modified by < and > signs inserted
between the % and 0..9,? or ! . > takes the leafname and < the directory.

e.g. If the first file is $.a.b.c

     %>0   gives  c
     %<0   gives  $.a.b
     %<<0  gives  $.a
     %<>0  gives  b
     %>>0  fails

A %0..%9 or %? operation will fail if the requested filename was not given.
When star fails a line the rest of lines are abandoned. The iconbar text is
set to !? and an error message is placed in the system variable Star$Error.
You can inspect this from the Error item in the star submenu.


 Translated lines are preceeded by
             |     . . .    GS_trans the argument
             !     . . .    GS_trans <>'s only.
 GS_trans replaces |M by the <ctrl>M character, <name> by the system
variable name, <99> by character 99 etc. GS_trans is performed after
substitution.

e.g.

*Filer_Opendir <Star$Dir>         ;Would fail

|*Filer_Opendir <Star$Dir>        ;Opens the star application directory.

Note many star commands perform their own GS_Trans.

e.g.

*Echo "|GHello world|M"   ;beeps and prints out

|*Echo "|GHello world|M"   ;fails due to unknown characters in string

A line starting with ( starts a repeat block. The repeated commands are run
once for each file name given. The repeat ends at a line starting with ).
The repeat can be started at the nth file by following the ( immediately by
0-9. (0 is the same as (. The file name in the repeat is given by %? .

e.g.

(1         ;give information on all files except the first.
*info %?
)

() may not be nested.

A line begining with * sends its argument to the command line interpreter.
This is performed using wimp_starttask. If the command outputs to the screen
a wimp command window will be opened on the screen and you will have to
press a key or click the mouse before continuing.

A line starting with [ introduces a block that ends with a line starting
with ]. In between these lines may only start with * or with a matched pair
of (). [] may not be nested. The commands in a [] block are saved to a
temporary obey file. After the ] the file is obeyed. Any string following
the ] is added to the obey instrution.
  There are several differences between obeying commands individually and as
a file. If the individual commands produce screen output you will have to
close the command window after each command, whereas the file of commands
will all write to the same window. If a command in a file produces a RISC_OS
error (rather than a star error) the rest of the file will be abandoned,
whereas individual commands will only abandon that command.

E.g.

[          ;put information on all files into one command window.
(
*info %?
)
]

[
*dir $
*cat
] { > printer: }  redirect two commands to the printer.

A line starting with < gives a default file name, the < should be followed
immediately by a file number 0..9.

E.g

:SetDir
<0 $    ;If no files have been dragged set name 0 to $
*Dir %0

A line starting with # gives a set of acceptable filetypes for a file  The #
should be followed immediately by 0..9 ? or ! . The possible filetypes in
hex follow separated by spaces. Application directories have type 2000,
other directories have type 1000. Defaults provided by < lines have type
123456. If the filetype is not among those given the remaining commands are
abandoned.

E.g.

:SetDir
<0 $
#0 1000 2000 123456   ;Check if file is a directory
*Dir %0

A line starting with ? queries the user. The rest of the command line is
used as a prompt. If the user responds <cancel> the remaining commands are
abandoned.

E.g.

:Wipe
#0 1000 2000
*Filer_opendir %0
?Do you really want to wipe this directory?  ;Ask user
*Wipe ~C~VFR  %0.*

Lines starting with > open an editor and pass the rest of the command to it.
If the editor Star$Ed has been seen star sends it a DATALOAD message with
the rest of the command as file, otherwise it runs the rest of the command.

E.g.

> RAM:temp  ;load RAM:temp into an editor

Lines starting with + insert the rest of the line into the keyboard buffer.
For this to be of any use you need to know where the keypresses will be
sent. This shold be ok if you have just opened a file using > ,or you are
about to run a non-wimp application.

E.g.

:Goto 5
> %0        ;open file
|+<&85>5|M  ;put <F5> 5 <Return> into buffer
            ;If you are using Edit this goes to line 5
            ;Note GS_Trans is needed

:LoadProg #0 FFB         ;check basic filetype
|+LOAD "%0"|M
BASIC                    ;Load program into BASIC

KNOWN SHORTCOMINGS

  Star's error messages are a bit crypic. Although some checking of star
file syntax is done on loading they are supposed to be correct. It may be
difficult to distinguish between a bug in star, a bug in your star file, or
a RISC_OS error.
  It was difficult to know when to stop adding star commands. Star could be
given if-then-else and for loops etc. However if you need these it is
probably better to write a small Basic or C program and run it from star,
rather than use what is a rather awkward interpreted language. Also star has
already become rather larger than I would like it, although this is largely
due to the size of RISC_OSlib. I hope Acorn will get round to putting
RISC_OSlib in a shared module, preferably in ROM.

COMMAND SUMMARY

     First symbol  Qualifiers    Tail       Use
          :                      Name     Start menu item
          {                      Name     Start submenu
          }                               End submenu
          ;                      String   Comment
          (         0-9 or none           Repeat for each file after n
          )                               End repeat
          [                               Start Obey file
          ]                      String   End Obey file
          *                      String   Star command
          <         0-9          String   Default file name
          >                      String   Edit
          +                      String   Insert in keybord buffer
          ?                      String   Query with string prompt
          #         0-9 ? !      String   Check filetypes

  In string tails %Qualifier is substituted as follows
     Qualifier    Substitution
         0-9       Filename 0-9
          !        All filenames followed by spaces
          ?        Filename for repeat loop number
          "string" Prompt for input with string prompt
          %        %

Between the % and !?0-9 may go any number of < or >  characters
          <        Tail of filename
          >        Leafname

  The first symbols with string arguments may be preceeded by
          |         GStrans after substitution
          !         GStrans <>'s only after substitution

  Filetype strings contain a list of permissible hex filetypes separated by
spaces 1000 for directory, 2000 for application dir ,FFFFFFFF for untyped,
123456 for a < default substitution.

  Names may not contain the symbols ,~>!"

Inside [ ]  pairs the only permissible first characters are * ( ) . () must
both be inside. Neither () nor [] can be nested.


COMMENTS PLEASE

                 I would welcome bug reports, criticism (constructive or
otherwise), modifications or suggestions for modifications.

                  Chris Stretch
                                 Archive BBS No.62
                         CBTP13@JANET%UK.AC.ULSTER.UCVAX