=============================================================================
Launcher - Yet Another RISC OS Application Launcher              Version 1.20

(C) Stephen Fryatt, 2003-2021                                 12 January 2021
=============================================================================

  This file is also contained within the Launcher application.  It can be
  accessed from the 'Help' entry in the Filer menu and from the 'Help' entry
  in Launcher's main menu.

License
-------

  Launcher is licensed under the EUPL, Version 1.2 only (the "Licence"); you
  may not use this work except in compliance with the Licence.

  You may obtain a copy of the Licence at
  http://joinup.ec.europa.eu/software/page/eupl

  Unless required by applicable law or agreed to in writing, software
  distributed under the Licence is distributed on an "AS IS" basis, WITHOUT
  WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.

  See the Licence for the specific language governing permissions and
  limitations under the Licence.

  The source for Launcher can be found on GitHub, at
  https://github.com/steve-fryatt/launcher



Introduction & Installation
---------------------------

  Launcher is yet another application launcher for RISC OS, which sits to the
  side of the desktop and allows applications to be started from a palette of
  shortcuts.  It can slide out of sight when not in use, and can be quickly
  brought back into view with a click of the mouse.

  Despite being in use on my desktop since 2003, it took sixteen years and
  many nudges from people who saw it on my machine at RISC OS shows and WROCC
  meetings to make it out into the wild.


  Installation
  ------------

  Launcher is designed to work with RISC OS 4 or later; it can be used on
  RISC OS 3, but a copy of the Nested Wimp must be installed.  It is
  26/32-bit neutral, and should therefore run on all hardware systems as long
  as the 32-bit Shared C Library is installed.  If required, this can be
  found in the System Resources on RISC OS Open Ltd's website at
  https://www.riscosopen.org/content/downloads/common.

  To install, copy the !Launcher application from the archive into a suitable
  place on your hard disc.  It can be run from a floppy disc, but this is not
  recommended.  Once installed, double-click on the !Launcher application in
  the Filer window to load it on to the desktop.

  If Launcher is to be used on a regular basis, it may be desirable to have
  it run automatically when the system starts.  The easiest way to achieve
  this is to add it to the list of applications in Configure.  Start
  Configure by double-clicking on !Boot (or selecting 'Configure...' from the
  Task Manager's iconbar menu on recent versions of RISC OS), then select
  'Boot' and finally 'Run'.  Drag the !Launcher application from your hard
  disc into the list of applications.



Using Launcher
--------------

  To use Launcher, run it in the usual way by double-clicking on its icon
  within a Filer window (or ensure that it runs at start up, as described in
  the previous section).  It will install itself on the desktop, initially
  placing a bar down the left-hand side of the screen -- although this is
  configurable.

  To access the shortcuts, click on the bar and the panel will expand on to
  the screen; click again on the bar to shrink it back again.  A Select-click
  on a shortcut will launch the associated application and shrink the panel
  back, while clicking with Adjust will leave the panel open on screen for
  another shortcut to be selected.

  The panel can also be configured to open when the mouse passes over it and
  remains in place for a minimum time, which saves a click to open it up.
  See the chapter on configuration for more details.


  Adding, Editing and Deleting panels
  -----------------------------------

  The initial panel can be configured and more panels can be added through
  the menu.  To add a panel, click Menu over an existing one and select 'New
  panel...'; to edit one, select 'Panel -- Edit...' instead.  In both cases,
  the Edit panel dialogue will open.

  The 'Name' of a panel is simply used to identify it when there is more than
  one on screen.  It is initially set to "Default" for the first panel, but
  can be changed to any name.  Names can contain lower and upper case
  letters, digits and a dash (hyphen); they must all be unique.

  The 'Position' section controls the location of the panel.  It can be moved
  to another side of the desktop by changing the 'Location' field -- panels
  can be located on any side of the desktop.

  If there is more than one panel on the same side of the screen, then the
  'Width' values are used to adjust the relative sizes: the total values for
  all of the panels on the side are summed, and then each bar takes on the
  proportion given by its own value.  If two bars had widths of "50" and
  "100", then the second would be twice as wide as the first.

  The order in which the bars appear is set by their 'Order' fields.  Again,
  these are relative values, with the panels being arranged in ascending
  numeric order; the values do not need to be consecutive: they could be "1",
  "2", "3" or "10", "20", "30"... or even "10", "50", "500".

  The 'Layout' section controls the arrangement of buttons within the panel.
  Buttons are arranged on a grid, with dimensions as set in the
  configuration; the 'Button width' and 'Button height' fields specify the
  number of grid squares that buttons will occupy.  Since the button layout
  is arranged along the length of the side of the screen, the width and
  height will swap around if a panel is moved from the top or bottom of the
  screen to the left or right.

  The 'Grid depth' sets the minimum number of grid rows which will be
  displayed when a panel opens.  If buttons end up outside of this area,
  either by being placed there or because the layout has been reflowed, the
  number of rows will be increased automatically.

  To delete a panel, click Menu over it and select 'Panel -- Delete' -- this
  will delete all of the shortcuts within it.  It is not possible to delete
  the last panel remaining on the screen.

  After making changes to the panel arrangement, it is necessary to select
  'Save layout' from the panel menu to retain it for future sessions.


  Adding shortcuts
  ----------------

  New shortcuts can be added by clicking Menu over an empty part of the panel
  and selecting 'New button...'.  This will open the Edit button dialogue,
  allowing a new shortcut button to be created.

  If the shortcut is to be used to launch an application, the easiest thing
  to do is to drag the application's icon from a Filer window into the
  dialogue.  This will complete the 'Name', 'Sprite' and 'Target' fields
  based on the application's details, and set a sensbile default for the load
  action.

  If not, or if the details need to be changed from the defaults offered,
  then the 'Name' of the button is a unique identifier, which will often be
  the name of the application or script to be run by the shortcut.  If
  <name>Show name in button</name> is ticked, the name will appear below the
  sprite in the button.  The 'Sprite' field holds the name of the sprite, and
  should be a sprite which is held in the Wimp Sprite Pool (such as one
  belonging to an application which has been seen by the Filer).

  The position of the button is set by the 'In direction of sidebar' and
  'Away from sidebar' fields: these specify the grid square occupied by the
  button which is nearest the top (for vertical bars) or left (for horizontal
  bars), and closest to the sidebar.  The coordinates start at (0,0),
  increasing as they move down (for vertical bars) or right (for horizontal
  bars), and as they move away from the sidebar towards the edge of the
  screen.

  | (i) Note that buttons are reflowed in the panel if they overlap or fall
  |     outside the visible area in the axis of the screen edge.  This means
  |     that buttons may not appear in the locations requested, and since
  |     buttons can push other buttons, this could affect a number of objects
  |     in a panel.  Buttons may reflow if a change of screen mode results in
  |     a panel being too small to display the buttons that it contains.

  Finally, the 'Action' section defines what happens when the button is
  clicked.  The 'Location' is the full path to an object to be launched,
  opened or run when the button is pressed: often an application folder,
  maybe an Obey file within it, or perhaps a folder or file.

  The three radio icons below determine what Launcher should attempt to do
  with the object when it starts up.  For an application, 'Boot target on
  startup' is equivalent to opening the Filer window containing it, and would
  ensure that things like filetypes are set up correctly. 'Load icon sprites
  on startup' will merge any application sprites held in a standard !Sprites
  file within an application into the Wimp Sprite Pool. 'Do nothing' will
  perform no action, and is suitable for applications, directories and files.

  To store the new shortcut, click on 'OK'; to abandon the changes, click
  'Cancel'.  New shortcuts will not be saved for future sessions unless 'Save
  layout' is selected from the main menu after the changes have been made.


  Editing shortcuts
  -----------------

  To edit an existing shortcut, click Menu over the button and select 'Button
  -- Edit...'.  This opens the Edit button dialogue, as described in the
  previous section, to allow changes to be made.  Buttons can be moved around
  the panel by changing their 'X position' and 'Y position' values.

  | (i) If the Edit button dialogue is opened for a button which has been
  |     reflowed, a warning is shown at the bottom of the window, since the
  |     'Position' fields will show the intended position and NOT the
  |     reflowed one.

  To delete a shortcut from the panel, click Menu over it and select 'Button
  -- Delete'.

  As with new shortcuts, any edits or deletions to shortcuts will not be
  saved for future sessions unless 'Save layout' is selected from the main
  menu after the changes have been made.



Configuration
-------------

  Selecting 'Choices...' from the main menu allows the default behaviour of
  Launcher to be changed.

  The 'Grid dimensions' section controls the dimensions of the grid in the
  launch panel.  The number of columns can be set using 'Display columns',
  remembering that each button occupies 2 grid squares by 2 grid squares.
  The number of rows on the grid is determined by the size of the screen mode
  that is currently in use.

  The size of a grid square can be set using 'Grid size', using OS Units and
  again remembering that a button occupies two grid cells in each direction.
  The spacing between cells in the grid, which sets any spacing between
  buttons, is set in the 'Grid spacing' field -- the size of cells includes
  the spacing that crosses between their pairs of grid squares.

  The thickness of the sidebar used to open and close panels can be
  configured with 'Sidebar size'.  The value is also in OS Units, and can be
  reduced from the default for a more minimalistic look.

  'Open on mouse-over' controls whether the panels will open when the mouse
  moves over them.  When off, which is its default state, a panel will open
  when the mouse is clicked on its bar.  If turned on, a panel will open when
  the mouse passes over it, and will close again when the pointer moves away
  again.  There is a delay between the mouse entering the panel and the panel
  opening, which is set by 'Open delay'; the value is in hundredths of a
  second.

  If 'Confirm deletions' is ticked, Launcher will confirm any attempt to
  delete a button from the grid.

  Clicking on 'Apply' will store the settings in the window for the current
  session (using Adjust will leave the dialogue box open), whilst clicking
  'Save' will also save any changes to disc for future use.  Clicking Select
  on 'Cancel' will close the dialogue and discard the changes, whilst using
  Adjust will reset any values which have been changed.



Version History
---------------

  This is a complete list of all the changes made to the publicly released
  versions of Launcher.


  0.50 (23 April 2019)
  --------------------

  First public release.


  0.51 (17 May 2019)
  ------------------

  Update to first publicly released version.

  * Add !Boot file to ensure that Help works correctly (ticket #679).
  * Correctly redraw edit dialogue when contents change (ticket #680).


  1.00 (25 May 2020)
  ------------------

  Second public release.

  * Prevent multiple copies of Launcher from starting by mistake
    (ticket #683).
  * Allow multiple bars on different edges of the desktop (tickets #678, #681
    and #682).
  * Bump icons added to the 'X position' and 'Y position' fields in the Edit
    button dialogue.
  * Enable buttons to reflow within a panel when they fall outside of the
    available area.
  * Warn of unsaved changes to the panel or button layout on exit
    (ticket #665).
  * Allow iconsprites to be merged instead of a full application boot
    (ticket #688).


  1.10 (26 July 2020)
  -------------------

  Third public release.

  * Add support for automatically opening panels when the mouse moves over
    them (ticket #707).
  * Improve the launching of objects, passing items to *StartDesktopTask,
    *Filer_Run or *Filer_OpenDir as appropriate (ticket 706).
  * Find the most appropriate sprite possible when adding a button using
    drag-and-drop.
  * Use ResConf-style system variables to identify resources.


  1.20 (12 January 2021)
  ----------------------

  Fourth public release.

  * Update the licence from EUPL v1.1 to EUPL v1.2.
  * Add configuration for sidebar width (ticket #729).
  * Allow button sizes to be configured on a panel-by-panel basis.
  * Allow button names to be included in the button (ticket #728).



Updates and Contacting Me
-------------------------

  If you have any comments about Launcher, or would like to report any bugs
  that you find, you can email me at the address below.

  Updates to Launcher and more programs for RISC OS computers can be found
  on my website at http://www.stevefryatt.org.uk/risc-os/launcher

  Stephen Fryatt
  email: info@stevefryatt.org.uk
