Clipboard extensions
Functional Specification

Document status

Contents

1. Document Status
2. History
3. Overview
4. User interface
5. Programmer interface
   1. Current interface
6. Data formats
7. External dependencies
8. Testing scheme
   1. Acceptance test
   2. Test strategy
9. Non-compliance
10. Outstanding issues

History

Revision		Author	Changes
Draft	13 Jan 1999	JF	Private draft - sent to MB for comment
2	15 Jan 1999	JF	Added list of applications currently (alledged to be) supporting the global clipboard model. Added comment about Messenger bug.
3	15 Jan 1999	JF	Added note about ARPlayer supporting clipboard. On comments from MB, added Clipboard module proposal. Added documentation of current message system for completeness.
4	17 Jan 1999	JF	Addition of a Vantage, Impression and Ovation Pro to the 'supporting' list. Added comments from MB about suggested methods of implementing Clipboard module (message interface, or complete transparent replacement). Added 'auto-conversion' notes to the 'outstanding issues' section.
5	11 Jan 2000	JF	Updated for release to developers. Support module proposal dropped.

Overview

The Clipboard Protocol has been in public existance for about 6 years, and yet users are still unaware that RISC OS has it and cite it as a failing of the system. A more 'visible' use of this protocol would bring it to the front and be a plus point on a list of new features.

It is proposed that a simple 'Clipboard viewer' application, capable of a simple operations on the clipboard would be the first step toward more public awareness and developer take up of the protocol.

Clipboard takeup

• DataPower
• Zap
• StrongEd
• Messenger (mail reader) [1.40 onward, but 1.40 broken]
• Pluto (mail reader)
• IRClient (IRC client)
• JFShared DispLib applications (about 10 applications which should be able to support it or already do); details on request
• WritableUtils module (copies text from writable icons)
• IcnClipBrd (similar to above) [Unconfirmed]
• Clip (application to 'hold' clipboard on application quit)
• Clipboard (application to save clipboard)
• Schema2 (spreadsheet)
• Impression series
• Techwriter/Easiwriter (work processors)
• AdvanceDB (Database)
• ARPlayer
• Impression family (DTP)
• Ovation Pro (DTP)
• Cerilica Vantage (graphic design)
• NCDraw [Unconfirmed]
• NCPaint [Unconfirmed]
• vim (vi like editor)
• Swipe (copy icon and window title text)
• DigitalCD [Unconfirmed]
• NoPaint [Unconfirmed]

The current clipboard interface is too bulky for small applications to use, unless they already provide a means of saving files using the standard data transfer methods. It is felt that an easier to use programmer interface to the clipboard would make inter-application data transfer much simpler.

It is proposed that a SWI be used to provide a simpler means of using the clipboard, as a supplement to the current SWI interface. This will be used in a similar manner to the interaction of the DDEUtils module and Throwback messages.

User interface

The 'ClipView' application should provide :

• iconic representation of the current clipboard for types which are not understood by the viewer itself
• A physical representation of the data for types which are understood
• A 'statistics' display showing who owns the current clipboard, and how large it is
• A means of saving the clipboard and possibly adding an entry to the clipboard (note that the present protocol supports only a single entry, but it may be possible to extend the application to cater for more 'virtual' clipboards which can be switched between depending on the data type requested).

The Clipboard module (prior Acorn development) would provide a 'holding area' for applications that have exited. Alternatively, I have produced an application that performs the same job. This requires an extension to the Clipboard protocol which very few applications currently support.

Programmer interface

Current interface

Message_ClaimEntity (Message 15)

Claim a user controlled entity

Message block
	Offset	Contents
	+ 0	Message size (24)
	+ 4	Sender task handle
	+ 8	My reference number
	+ 12	Your reference number
	+ 16	Message_ClaimEntity (15)
	+ 20	Flags : Bit Meaning if set 0 and 1 Caret or selection being claimed 2 Clipboard being claimed
Use
	Applications who have performed a 'cut' or 'copy' operation should broadcast this message to notify tasks of that the clipboard has been claimed. Any other application holding the clipboard should release any memory and mark internally that the clipboard is not held.

Message_DataRequest (Message 16)

Request data from clipboard

Message block
	Offset	Contents
	+ 0	Message size
	+ 4	Sender task handle
	+ 8	My reference number
	+ 12	Your reference number
	+ 16	Message_DataRequest (16)
	+ 20	Window handle
	+ 24	Internal handle - something to recognise the paste by
	+ 28	x co-ordinate, or internal data
	+ 32	y co-ordinate, or internal data
	+ 36	Flags : Bit Meaning if set 2 Clipboard being requested
	+ 40	Word list of filetypes in order of preference, terminated by -1
Use
	Applications wishing to paste the clipboard should broadcast this message and await either a bounce, or a reply of DataSave. Applications receiving this message and holding the clipboard should respond by copying the data from bytes 20 to 35 to a DataSave message and replying. Applications should supply data in the first format requested in the type list that they can support, or in their internal format if not. The filetype field on DataSave should be set to the type of data to be transfered.

Message_ReleaseEntity (Message 19)

Application with clipboard is quitting, someone else should take over

Message block
	Offset	Contents
	+ 0	Message size (24)
	+ 4	Sender task handle
	+ 8	My reference number
	+ 12	Your reference number
	+ 16	Message_ReleaseEntity (19)
	+ 20	Flags : Bit Meaning if set 2 Clipboard being released
Use
	Applications that are quitting and have the clipboard claimed should broadcast this message. A 'holding' application will respond with a paste request which should be honoured before the application exits.

Data formats

No additional data formats are required by this specification.

External dependencies

The Choices module may be required for storage of the configuration.

Testing scheme

Acceptance test

Test strategy

Non-compliance

This section has not been written.

Outstanding issues

There are no outstanding issues.