
----------------------------  !MidiMole (0.08)  ----------------------------

                         Copyright : Somascape 2000

                               Author : Lenny

----------------------------------------------------------------------------

0.0  Contents
     ========

     1.0  Overview
     1.1    System requirements
     1.2    Software status
     2.0  MIDI communications
     3.0  Iconbar
     4.0  The Panel window
     5.0  The Options window
     6.0  Contacting the author

----------------------------------------------------------------------------

1.0  Overview
     ========

This document describes the features and operation of the !MidiMole
application, for use on a computer running RISC OS.  It was previously
called !Monitor, though has been renamed so as to avoid confusion with
Cerelica's application with that name.

!MidiMole is a very simple utility that can capture and display incoming
MIDI data.  It has been written as a MIDISupport plugin, and allows a
maximum of 500 MIDI messages or (by default) 64k of data to be held in
memory (whichever limit is reached first).  The 64k limit can be increased
(see section 2.0).

On systems with the 'new boot' structure (or the !Choices pseudo app), the
Choices scheme will be used for user preferences.

Interactive Help is supported, so run !Help (or !BubbleHlp, etc) when
first trying out the program.

- - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - -

1.1  System requirements
     ===================

!MidiMole requires the presence of ESP's MIDI Support software, including
!MidiMan (its front end application).  For use with external MIDI devices,
you will also need a MIDI expansion card and its associated MIDISupport
driver.  On a 26-bit OS, version 0.30 or later of the MIDISupport module
is required, whereas on a 32-bit OS version 0.34 or later is required
(along with !MidiMan 0.32 or later).  Contact Liquid Silicon
(www.liquid-silicon.com) if you need to upgrade.

!MidiMole itself is 26/32-bit neutral, with no special SharedCLibrary
requirements as it has been linked with StubsG.  It runs on my StrongARM'd
RiscPC with RISC OS 4.02 through to RISC OS 4.37 (Select 3).  Although it
will run on any machine equipped with RISC OS 3.10 or later, the latest
(ie 32-bit) version of MIDI Support now requires RISC OS 3.50 or later.

- - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - -

1.2  Software status
     ===============

This software is not PD ...

 ... It is Freeware.

That is, I retain the copyright, though it may be freely distributed.

Please, refer to the file 'Licence' within the '<MidiMole$Dir>.Docs'
directory.

----------------------------------------------------------------------------

2.0  MIDI communications
     ===================

!MidiMole makes use of a software MIDI driver (named 'MidiMole') to
receive (but not send) MIDI commands.  This driver needs to be connected
into the MIDI Support system.  This is done using !MidiMan :

 * Whilst !MidiMole is running, open !MidiMan's Routing window and use the
   Source popup menu for the MidiMole driver and select the required
   source driver(s).

 * If you then use !MidiMan's Save Configuration facility, these
   'connections' will automatically be made whenever !MidiMole is
   subsequently run (provided that !MidiMan is running at the time).

Once 'connected', the setting of the Listen toggle in the Panel window
determines whether the MIDI input is actually monitored for the arrival of
MIDI data.  When ticked, arriving messages are captured and stored in
memory.

The program will beep upon receiving a MIDI message that would exceed
either limit of 500 messages or (by default) 64k of data.  The 64k limit
can be increased if need be, by editing the 'UserOpt.MsgDataL' parameter
in the Messages file.

----------------------------------------------------------------------------

3.0  Iconbar
     =======

* Click SELECT on the iconbar icon to Open/Surface the Panel window.

* Click ADJUST on the iconbar icon to Open/Close the Panel window.

  Use the CTRL key with SELECT/ADJUST to open/surface/close the Options
  window.

  Use the SHIFT key with SELECT/ADJUST to open/surface/close both windows.

* Click MENU on the iconbar icon to open the iconbar menu.

  This contains 4 items : Info, Help, Options... and Quit.

  Info and Quit do the usual, whereas Help runs this file, and Options...
  opens the User Options window.

----------------------------------------------------------------------------

4.0  The Panel window
     ================

All of the main functions of the program are accessed directly from this
window.  There is no menu for this window.

This window contains two sections, the upper one containing two framed
areas, whilst the lower section contains a pair of action buttons.

In the top section :

 * The top area indicates the number of messages currently in memory, and
   provides a switch enabling the reception of MIDI data to be toggled on
   and off (when Listen is ticked, any MIDI messages received by the
   MidiMole MIDI driver will be captured.  (See section 2.0, 'MIDI
   Communications'.)

 * The middle area provides information about a single message : its
   length, a textual description, and up to 10 bytes of the message.

   The textual description always refers to MIDI channels as 1-16, and to
   voice numbers as 1-128.

   In the case of System Exclusive messages that are longer than 10 bytes,
   the message can be scrolled through using the bump icons next to the
   bytes list.  The number immediately to the right shows the offset into
   the message (of the leftmost displayed byte).

   Note that holding down the SHIFT key whilst clicking on any of the bump
   icons (message selection and byte offset) will speed up the rate of
   change of the associated parameter.

In the bottom (action button) section :

 * Remove All : Removes all messages from memory.

 * Remove : Removes a single message from memory.

Closing the Panel window does not lose any data currently held in memory.

----------------------------------------------------------------------------

5.0  The Options window
     ==================

This window is accessed via the iconbar menu, and allows the user to
specify their preferred settings.  If these are saved, they will be used
as the default settings in subsequent sessions.

 * Open Panel upon start-up : If ticked, the Panel window will be opened
   upon running !MidiMole.

 * Listen, at start-up : This specifies the initial setting of the Listen
   switch in the Panel window.

 * Open Panel upon Rx : If ticked, the Panel window will be opened when a
   message is received via MIDI (this also requires that the Listen switch
   in the Panel window is ticked, and that appropriate MIDI 'connections'
   have been set up using !MidiMan).

The effect of the first two settings will not be apparent until the next
time !MidiMole is run (provided the options are saved, that is).

In the absence of a preferences file, !MidiMole will start up using its
internal defaults :

 * Open Panel upon start-up : Yes
 * Listen, at start-up      : No
 * Open Panel upon Rx       : Yes

----------------------------------------------------------------------------

6.0  Contacting the author
     =====================

For bug reports, suggestions, sighs of adulation, derisive comments or
submission of gratuities, please contact me (Lenny) :

  email: riscos@somascape.org   (Use the button in the Info window.)

----------------------------------------------------------------------------
