Charges
-=-=-=-

© 1992-2003  Richard G. Hallas
˜˜˜˜˜˜˜˜˜˜˜˜˜˜˜˜˜˜˜˜˜˜˜˜˜˜˜˜˜˜˜˜˜˜˜˜˜˜˜˜˜˜˜˜˜˜˜˜˜˜˜˜
####################################################
#####                                          #####
###      Wimp Messages used by Charges v. 2      ###
#####                                          #####
####################################################

Version 2 of Charges can be controlled remotely by
other multitasking applications. All you have to do
is send a message to Charges giving it a job title,
and it will start or stop timing the job. Everything
is dealt with intelligently: i.e. it will create job
files automatically, it won't try to 'stop' a job
which doesn't exist or has been terminated by the
user, and it will suspend a current job if it gets
asked to create a new one.

Currently, this feature is supported by the Sibelius
music processing system. If you plan to incorporate
support for Charges in another program you are free
to do so, but please notify me about it so that I
can ensure you have the latest version of Charges. I
would also appreciate seeing a copy of the software
which plans to make use of Charges (partly so I can
satisfy myself that everything works correctly and
as originally intended). You can contact me at the
following address:

  Richard Hallas,
  31 Skelton Crescent,
  Crosland Moor,
  Huddersfield,
  West Yorkshire,
  HD4 5PN, UK
  Tel. (01484) 460280
  Fax  (01484) 654186
  Email: Richard@Hallas.net


Instructions for communicating with Charges
===========================================

Please read the following text carefully if you
intend to provide Charges support in your program.
The procedure is very straightforward, but there are
a few conventions which you must follow.

Charges uses one wimp message, which is from a block
officially allocated to me by Acorn, so there should
be no conflict with other applications. The format
is as follows:

Message_ChargesControl (&825C5):
~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
This message details which job is in progress, and
whether Charges should start or stop the clock.

The message should contain the standard message
header as detailed in the PRM, and continue at
Block+20 with the following:

Offset: Length (bytes):    Contents:
~~~~~~~ ~~~~~~~~~~~~~~~    ~~~~~~~~~
+20     1                  1 to start the clock
                           or 0 to stop the clock
+21     11 (maximum)       Job name (actually a
                           filename) terminated by
                           a control code.
                           Therefore the maximum
                           acceptable size for this
                           entry is 10 chars+CHR$ #.
                           (NB terminator is usually
                           ASCII 13 or ASCII 0, but
                           can be any value below
                           32.)

Note that the job name is actually the LEAF-name of
the file; you should NOT include the full path.

Therefore, including the header, the message has a
maximum length of 32 bytes.

IMPORTANT: If your document's filename begins with
a '!' character, this should be OMITTED from the
messages you send to Charges. There are two reasons
for this:

  (1) It allows the user to have two separate files
      which Charges will treat as the same job.
      This can be useful at times; for example, you
      might have a Sibelius file called "Score" and
      a title page associated with it (Impression
      document, perhaps) with a filename "!Score".
      Charges would see both of these as the same
      job, and time them together appropriately.

  (2) Filenames starting with "!" would appear
      ahead of others in Charges "Jobs" menu, which
      is not particularly desirable.

NB You should only strip off the first '!' if there
is more than one.

The message should be BROADCAST. This saves the
hassle of trying to find out (a) whether Charges is
running and (b) what its task handle is. As the
message number is an official Acorn allocation,
there shouldn't be any conflict with other
applications. Charges will NOT acknowledge the
message in any way, as it is not up to you to
decide what to do about the job timing. All you
must do is start and stop jobs; Charges will do
everything else. Always send the messages; even if
Charges is not loaded.

When sending this message, you MUST specify a job
name, and it MUST consist of characters which form
a valid filename. If not, Charges will ignore the
message.

The implication of this is that it is not possible
to monitor time spent on an untitled document. The
user can do this manually, if required, but the
advisable procedure is for the user to copy a
template file under an appropriate name before
loading it into the editor, or open up a new
document and save it under an appropriate name
immediately, before starting work on it. This is
good practise anyway, as it avoids lost work and
sets things up properly; but if you plan to
support Charges, you should put words to this
effect in your documentation, or devise some sort
of system yourself which requires the user to give
every document/file a title before work on it can
commence.

A suggested course of action is to have a document
preference which concerns using Charges for timing.
This should default to OFF, but if the user turns
it on and the document has not been saved, then you
should prompt the user for a document name, with a
message along the lines of "In order to charge for
this document you must give it a name. Please enter
a filename below", followed by a writable icon, an
OK icon and a Cancel icon (which, if pressed, must
deselect the charging choice, of course). The name
which the user supplies (actually a leafname rather
than a full filename) should then be used for the
document in the window title bar and in messages to
Charges, and should be presented instead of the
default name in the 'Save as' window.

As far as making use of Charges is concerned, your
program must obviously be multitasking for messages
to work. If it takes over the whole screen (as does
Sibelius, for example), your task is very easy:
just send a start message when entering editing
mode from the desktop (assuming the file you are
working on has been saved previously), or when a
new change is made to a document which has just
been saved. Send a stop message when you return to
the desktop or save (or discard) the file.

For properly desktop compliant applications, the
procedure is almost as straightforward. You should
send a start message to Charges as soon as the file
being edited is marked as modified (i.e. when you
put an asterisk character ['*'] in the title bar),
assuming of course that the file has been saved
previously. Similarly, you should send a stop
message to Charges as soon as the file is saved
(when you remove the '*' from the window title) or
discarded.

There is an additional condition which should not
be forgotten: because RISC OS is multitasking, it
is theoretically possible (if rather unlikely) that
a user may want to work on two or more jobs at the
same time. In order for Charges to keep track of
this, you need to make one addition provision not
mentioned above. If input focus is regained by a
document which is UNSAVED, you should send Charges
a start message for that document. If the message
is unnecessary, it will be ignored. The reason for
this is that Charges may have gone off and set up a
new job for a different document, and when the user
comes back to your (unsaved) document, and hence
the input focus is regained, Charges' attention
needs to be drawn back to it. If you do not follow
this 'input focus' procedure, then when a user
returns to an unsaved job, Charges will not know
to start timing it again until the user resaves the
document and begins editing once again. This
circumstance is of most importance to desktop tasks
but still applies to single-document, full-screen
editors like Sibelius. Users can have as many jobs
on the go simultaneously as they wish, and so you
should send Charges a start message whenever your
document is 're-entered', by whatever means.

There is one further special case which you should
bear in mind, whether or not your application takes
over the full screen: if the user opens a new
document and saves it for the first time, or opens
an existing document and saves it under a new name,
you should send a stop message to Charges using the
previous name of the document (if it wasn't a
newly opened, untitled document) and remember to
send a start message to Charges with the new name
as soon as editing begins.

As a final point, the external activation of
Charges by other tasks can be turned off inside
Charges; but it may be useful to users to choose
whether or not individual documents are timed. It
may be helpful, therefore, to have a document-local
preference to determine whether or not any given
document should be timed. The preference should be
set to be OFF by default, if you intend to follow
the document-titling suggestion above; or to ON
otherwise, if you devise a different procedure.

To summarise:
-------------

(1)  When editing begins on a named document,
     broadcast a start message containing the name.

(2)  When an UNSAVED, named document regains input
     focus (or is re-entered for a full-screen
     editor), broadcast a start message containing
     the name.

(3)  When a named document is saved or discarded,
     broadcast a stop message containing the name.
     You should also do this if an unsaved document
     is closed but remains in memory. (Impression
     and ArtWorks allow this type of behaviour, for
     example.)

(4)  When an unnamed document is saved for the
     first time, you must remember to broadcast
     a start message containing its new name as
     soon as editing begins on it again.

(5)  When an existing document is saved under a new
     name, broadcast a stop message containing the
     old name of the document, and remember to
     broadcast a start message containing its new
     name as soon as editing begins on it again.

(6)  If the first character of your document's
     filename is an exclamation mark ('!'), strip
     this off before broadcasting the message.

(7)  If possible, provide a preference to determine
     whether Charges should be used to time any
     given document.

NOTE:
-=-=-

From version 2.51 onwards, Charges will broadcast a
Message_ChargesControl when it starts up and quits,
so that programs can keep track of it if they need
to do so.

Since Charges does not send the message under other
circumstances (i.e. your task will not receive it
during normal operation of Charges), there should
be no confusion between this startup and quit
message and the normal remote-control mechanism.
For starting and quitting, Charges broadcasts the
message; for operation of Charges' clock from with
another application, it is the other application
which broadcasts the message.

When broadcasting this message, Charges just uses
a one-word data block for the message. The full
message contains the standard message header as
detailed in the PRM, and continues at Block+20 with
the following:

Offset: Length (bytes):    Contents:
~~~~~~~ ~~~~~~~~~~~~~~~    ~~~~~~~~~
+20     4 (one word)       1 for "Charges is
                           starting up"

                           or

                           0 for "Charges is
                           quitting"
