Clipboard device

This is the user manual for the clipboard device of the Bedrock computer system.

This document is aimed at people who are learning about or writing programs for the Bedrock system. For people who are implementing the system from scratch, the clipboard device specification will provide more relevant information.

Overview

The clipboard device provides access to the shared system clipboard and to data dragged and dropped between programs.

Concepts

This device provides two clipboard interfaces, called the primary clipboard and the secondary clipboard. The first half of the device controls the primary clipboard, and the second half controls the secondary clipboard.

The primary clipboard provides access to the shared system clipboard, which is used for data that has been explicitly copied by the user. The secondary clipboard is instead used for data that has been implicitly copied, such as the contents of the text selection, or data that has been dragged and dropped between programs.

The item on a clipboard is called an entry. An entry can contain either text data, which must be a valid UTF-8 string, or binary data, which is unrestricted.

Each clipboard uses a read queue and a write queue to access entries. Writing to the read entry port will load the current entry into the read queue for reading, and writing to the write entry port will write the contents of the write queue as an entry to the clipboard. The value written to an entry port determines the type of entry that will be read or written, with a non-zero value indicating a text entry and a zero value indicating a binary entry.

Ports

Read entry

There are two read entry ports, one for each clipboard. Writing a byte to one of these ports will load the current clipboard entry into the read queue of that clipboard, first clearing the queue. Each clipboard entry can contain either binary or text data; writing a non-zero byte will load text data and writing a zero byte will load binary data.

Write entry

There are two write entry ports, one for each clipboard. Writing a byte to one of these ports will store the contents of the write queue as an entry on that clipboard, clearing the queue. Each clipboard entry can contain either binary or text data; writing a non-zero byte will store the data as text and writing a zero byte will store the data as binary.

Read queue

There are two read queue ports, one for each clipboard. Reading a byte from one of these ports will return the number of bytes waiting to be read in the read queue of that clipboard.

Write queue

There are two write queue ports, one for each clipboard. Reading a byte from one of these ports will return the number of bytes of space free in the write queue of that clipboard, and writing any value will clear the queue.

Head

There are two head port groups, one for each clipboard. Reading a byte from one of these ports will remove and return a byte from the front of the read queue of that clipboard, and writing a byte will push the byte onto the write queue.

Drag entry

Reading a byte from this port will return FF if the entry on the secondary clipboard is currently being dragged over the program window, or 00 otherwise.

Writing a non-zero byte to this port will hint that the entry on the secondary clipboard is being currently being dragged by this program, and writing a zero byte will cancel the drag.

Drop entry

Reading a byte from this port will return FF if the entry on the secondary clipboard was dropped on this program window since the port was last read.

Writing any value to this port will hint that the entry on the secondary clipboard was dropped by this program.

Wake behaviour

This device will wake the system device when an entry on the secondary clipboard is dropped onto this system, or when a drag is started or stopped.

Examples

Copying text to the clipboard

To copy text to the system clipboard, write each byte of the string to the primary head port and then write FF to the primary write entry port to store the entry:

*:selection JMS:copy-text HLT

@selection "Text selection."

@copy-text  ( string* -- )
  :A6 JMS:write-string
  :FF STD:A3 JMPr

@write-string  ( string* port -- )
  STA:~port JMP:~start &loop
    STD:[&port 00] INC* &start
    DUP* LDA DUP JCN:~loop
  POP POP* JMPr

Pasting text from the clipboard

To paste text from the system clipboard, load a text entry from the primary clipboard by writing FF to the primary read entry port, and then read bytes from the primary head port until the read queue is empty:

JMS:paste-text HLT

@paste-text  ( -- )
  :FF STD:A2
  &check-queue
  LDD:A4 DUP JCN:{ POP JMPr }
  &loop  ( queue )
    LDD:A6 STD:86 DEC DUP JCN:~loop
  POP JMP:~check-queue

Dragging a text selection

When the left mouse button is clicked, write the selection to the secondary clipboard, and then write FF to the drag entry port to hint that the text is being dragged. When the left mouse button is released, write FF to the drop entry port to hint that the entry was dropped:

@main
  PSH:[&prev 00] LDD:47            ( old new )
  AND:80 DUP STA:~prev             ( old new )
  DUP* NOT AND JCS:drop-selection  ( old new )
  SWP  NOT AND JCS:drag-selection  (         )
  *:0800 STD*:00 JMP:main          (         )

@selection "Text selection."

@drag-selection  ( string* -- )
  *:selection :AE JMS:write-string
  :FF STD:AB :FF STD:A8 JMPr

@drop-selection  ( -- )
  :FF STD:A9 JMPr

@write-string  ( string* port -- )
  STA:~port JMP:~start &loop
    STD:[&port 00] INC* &start
    DUP* LDA DUP JCN:~loop
  POP POP* JMPr