<document title="Launcher">
<define name="version" value="">
<define name="date" value="" length=30 align="right">




<literal mode="Text">
=============================================================================
Launcher - Yet Another RISC OS Application Launcher              Version $$version$$

(C) Stephen Fryatt, 2003-2021                  $$date$$
=============================================================================
</literal>





<literal mode="HTML">
<html>
<head>
<title>Launcher</title>
</head>

<body>
<h1 align="center">Launcher</h1>
<p align="center"><b>Yet Another RISC&nbsp;OS Application Launcher</b> - &copy; Stephen Fryatt, 2003-2020<br>
Version $$version$$ ($$date$$)</p>

</literal>





<chapter title="License" file="License">

<cite>Launcher</cite> is licensed under the EUPL, Version&nbsp;1.2 only (the &ldquo;Licence&rdquo;); you may not use this work except in compliance with the Licence.

You may obtain a copy of the Licence at <link ref="#url http://joinup.ec.europa.eu/software/page/eupl">http://joinup.ec.europa.eu/software/page/eupl</link>

Unless required by applicable law or agreed to in writing, software distributed under the Licence is distributed on an &ldquo;<strong>as is</strong>&rdquo; basis, <strong>without warranties or conditions of any kind</strong>, either express or implied.

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

The source for <cite>Launcher</cite> can be found on GitHub, at <link ref="#url https://github.com/steve-fryatt/launcher">https://github.com/steve-fryatt/launcher</link>

</chapter>




<chapter title="Introduction &amp; Installation" file="Introduction">

<cite>Launcher</cite> is yet another application launcher for RISC&nbsp;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&nbsp;OS shows and WROCC meetings to make it out into the wild.

<subhead title="Installation">

<cite>Launcher</cite> is designed to work with RISC&nbsp;OS&nbsp;4 or later; it can be used on RISC&nbsp;OS&nbsp;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&nbsp;OS Open Ltd&rsquo;s website at <link ref="https://www.riscosopen.org/content/downloads/common">https://www.riscosopen.org/content/downloads/common</link>.

To install, copy the <file>!Launcher</file> 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 <file>!Launcher</file> application in the Filer window to load it on to the desktop.

If <cite>Launcher</cite> 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 <cite>Configure</cite>. Start <cite>Configure</cite> by double-clicking on <file>!Boot</file> (or selecting <menu>Configure...</menu> from the Task Manager&rsquo;s iconbar menu on recent versions of RISC&nbsp;OS), then select <icon>Boot</icon> and finally <icon>Run</icon>. Drag the <file>!Launcher</file> application from your hard disc into the list of applications.

</chapter>




<chapter title="Using Launcher" file="Use">

To use <cite>Launcher</cite>, 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 &ndash; 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 <mouse>select</mouse>-click on a shortcut will launch the associated application and shrink the panel back, while clicking with <mouse>adjust</mouse> 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 <link ref="Configuration">configuration</link> for more details.

<subhead title="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 <mouse>menu</mouse> over an existing one and select <menu>New panel...</menu>; to edit one, select <menu>Panel &msep; Edit...</menu> instead. In both cases, the <window>Edit panel</window> dialogue will open.

The <icon>Name</icon> of a panel is simply used to identify it when there is more than one on screen. It is initially set to <entry>Default</entry> 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 <icon>Position</icon> section controls the location of the panel. It can be moved to another side of the desktop by changing the <icon>Location</icon> field &ndash; 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 <icon>Width</icon> 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 <entry>50</entry> and <entry>100</entry>, then the second would be twice as wide as the first.

The order in which the bars appear is set by their <icon>Order</icon> 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 <entry>1</entry>, <entry>2</entry>, <entry>3</entry> or <entry>10</entry>, <entry>20</entry>, <entry>30</entry>... or even <entry>10</entry>, <entry>50</entry>, <entry>500</entry>.

The <icon>Layout</icon> section controls the arrangement of buttons within the panel. Buttons are arranged on a grid, with dimensions as set in the <link ref="Configuration">configuration</link>; the <icon>Button width</icon> and <icon>Button height</icon> 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 <icon>Grid depth</icon> 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 <mouse>menu</mouse> over it and select <menu>Panel &msep; Delete</menu> &ndash; 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 <menu>Save layout</menu> from the panel menu to retain it for future sessions.

<subhead title="Adding shortcuts">

New shortcuts can be added by clicking <mouse>menu</mouse> over an empty part of the panel and selecting <menu>New button...</menu>. This will open the <window>Edit button</window> 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&rsquo;s icon from a Filer window into the dialogue. This will complete the <icon>Name</icon>, <icon>Sprite</icon> and <icon>Target</icon> 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 <icon>Name</icon> 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 <icon>Sprite</icon> 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 <icon>In direction of sidebar</icon> and <icon>Away from sidebar</icon> 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.

<box type="info">
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.
</box>

Finally, the <icon>Action</icon> section defines what happens when the button is clicked. The <icon>Location</icon> 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 <cite>Launcher</cite> should attempt to do with the object when it starts up. For an application, <icon>Boot target on startup</icon> is equivalent to opening the Filer window containing it, and would ensure that things like filetypes are set up correctly. <icon>Load icon sprites on startup</icon> will merge any application sprites held in a standard <file>!Sprites</file> file within an application into the Wimp Sprite Pool. <icon>Do nothing</icon> will perform no action, and is suitable for applications, directories and files.

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

<subhead title="Editing shortcuts">

To edit an existing shortcut, click <mouse>menu</mouse> over the button and select <menu>Button &msep; Edit...</menu>. This opens the <window>Edit button</window> dialogue, as described in the previous section, to allow changes to be made. Buttons can be moved around the panel by changing their <icon>X position</icon> and <icon>Y position</icon> values.

<box type="info">
If the <window>Edit button</window> dialogue is opened for a button which has been reflowed, a warning is shown at the bottom of the window, since the <icon>Position</icon> fields will show the intended position and <em>not</em> the reflowed one.
</box>

To delete a shortcut from the panel, click <mouse>menu</mouse> over it and select <menu>Button &msep; Delete</menu>.

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

</chapter>




<chapter title="Configuration" file="Configuration">

Selecting <menu>Choices...</menu> from the main menu allows the default behaviour of <cite>Launcher</cite> to be changed.

The <icon>Grid dimensions</icon> section controls the dimensions of the grid in the launch panel. The number of columns can be set using <icon>Display columns</icon>, 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 <icon>Grid size</icon>, using OS&nbsp;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 <icon>Grid spacing</icon> field &ndash; 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 <icon>Sidebar size</icon>. The value is also in OS&nbsp;Units, and can be reduced from the default for a more minimalistic look.

<icon>Open on mouse-over</icon> 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 <icon>Open delay</icon>; the value is in hundredths of a second.

If <icon>Confirm deletions</icon> is ticked, <cite>Launcher</cite> will confirm any attempt to delete a button from the grid.

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

</chapter>




<chapter title="Version History" file="History">

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

<subhead title="0.50 (23 April 2019)">

First public release.


<subhead title="0.51 (17 May 2019)">

Update to first publicly released version.

<list>
<li>Add <file>!Boot</file> file to ensure that Help works correctly (ticket&nbsp;#679).
<li>Correctly redraw edit dialogue when contents change (ticket&nbsp;#680).
</list>


<subhead title="1.00 (25 May 2020)">

Second public release.

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


<subhead title="1.10 (26 July 2020)">

Third public release.

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


<subhead title="1.20 (12 January 2021)">

Fourth public release.

<list>
<li>Update the licence from EUPL&nbsp;v1.1 to EUPL&nbsp;v1.2.
<li>Add configuration for sidebar width (ticket&nbsp;#729).
<li>Allow button sizes to be configured on a panel-by-panel basis.
<li>Allow button names to be included in the button (ticket&nbsp;#728).
</list>

</chapter>




<literal mode="Text">

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
</literal>




<literal mode="HTML">

<hr noshade>
<h2>Updates and Contacting Me</h2>

<p>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.</p>

<p>Updates to Launcher and more programs for RISC&nbsp;OS computers can be found on my website at <a href="http://www.stevefryatt.org.uk/risc-os/launcher">http://www.stevefryatt.org.uk/risc-os/launcher</a></p>

<p>Stephen Fryatt (email: <a href="mailto:info@stevefryatt.org.uk">info@stevefryatt.org.uk</a>)</p>
</body>
</html>
</literal>
