diff options
| -rw-r--r-- | doc/info/mds.texinfo | 167 | ||||
| -rw-r--r-- | doc/protocols | 105 |
2 files changed, 167 insertions, 105 deletions
diff --git a/doc/info/mds.texinfo b/doc/info/mds.texinfo index f94e6a8..f8f3ba9 100644 --- a/doc/info/mds.texinfo +++ b/doc/info/mds.texinfo @@ -1722,6 +1722,7 @@ simple, reference implementation of a, status icon tray. * Infrastructure Protocols:: Infrastructure protocols. * Virtual Terminal Protocols:: Virtual terminal protocols. * Keyboard Protocols:: Keyboard protocols. +* Clipboard Protocols:: Clipboard protocols. * Miscellaneous Protocols:: Miscellaneous protocols. @end menu @@ -2629,6 +2630,172 @@ Recommended. +@node Clipboard Protocols +@section Clipboard Protocols + +@menu +* clipboard:: Read or manipulate a clipboard. +* clipboard-info:: Clipboard event announcements. +@end menu + + + +@node clipboard +@subsection clipboard + +@table @asis +@item Identifying header: +@command{Command: clipboard} + +@item Action: +Read or manipulate a clipboard. + +@item Required header: @code{Level} +The clipboard level, an [1, 3] integer: +@table @code +@item 1 +Text copied/pasted using the keyboard or a menu item. +(This level is called `primary'.) +@item 2 +Text copied/pasted using the rat. +(This level is called `secondary'.) +@item 3 +Data to begin with a line describing the data type. +(This level is called `tertiary'.) +@end table + +@item Required header: @code{Action} +What to do with the clipboard: + add) Write the message to the clipboard + read) Read the clipboard + clear) Clear all entries on the selected level on the clipboard + set-size) Shrink/grow the clipstack + get-size) Read the size of the clipstack + In the reply, the server will send: + Size: <configured maximum size of the clipstack> + Used: <number of elements currently in the clipstack> + +@item Conditionally required header: @code{Length} +Length of the message. +Required if @code{Action: add} is included in the headers. + +@item Conditionally required header: @code{Size} +The maximum number of elements in the clipstack. +Required if @code{Action: set-size} is included in the headers. + +@item Conditionally required header: @code{Client ID} +Your ID, provided by the @code{ID assignment} header +in response to a @code{Command: assign-id} header. +Required if @code{Action: read} or @code{Action: read} is +included in the headers, or if @code{Action: add} is +included in the headers and if the header @code{Time to live} +is included and has a value starting with @code{until-death}. + +@item Conditionally optional header: @code{Index} +The index of the item in the clipstack, starting at 0. +Available and optional if the @code{Action: read} is +included in the headers. + +@item Conditionally optional header: @code{Time to live} +The number of seconds the entry should be available before +it is removed by the server, or: +@table @code +@item until-death +Remove entry when the client closes. +@item until-death # +Remove entry when the client closes, +or @code{#} seconds have elapsed. +@item forever: +Never remove it. (This is the default.) +@end table +The server will always remove the entry when either: +@enumerate 1 +@item +it is at the bottom of the clipstack and a new +entry is added to the clipstack, or +@item +@code{Action: clear} is issued for the clipstack. +@end enumerate +The entry will also be removed, unless +@code{Time to live: forever} is used, if the server +crashes or is re-executed. + +It is up to the implementation to choose when the +removal actually takes place. For example, the reference +implementation will pop entries that have timed out when +a new entry is added, the reading on the clipstack is +requested or the server is reexecuted, but another +implement may choose to pop entires asynchronously using +another thread or an alarm an pop when @code{SIGARLM} is +received. + +Available and optional if the @code{Action: add} is +included in the headers. + +@item Message: +The content to add to the clipboard. + +@item Purpose: +Enable the user to duplicate content from one process +into another process without requiring those processes +to be aware of eathother to any extent. + +@item Compulsivity: +Optional. + +@item Reference implementation: +@command{mds-clipboard} +@end table + + + +@node clipboard-info +@subsection clipboard-info + +@table @asis +@item Identifying header: +@command{Command: clipboard-info} + +@item Action: +The clipboard server sends out some information about +what it is doing, such as automatically removing entires. + +@item Included header: @code{Event} +@table @code +@item pop +The value of the header @code{Event} is @code{pop} +when an item in the clipstack has been removed. +If the value header--value-pair is used the following +headers will also be included in the message: +@table @code +@item Level +The clipboard level that has been affected. +@item Popped +The index of the item in the clipstack that has been removed. +@item Size +Configured maximum size of the clipstack. +@item Used +Number of elements currently in the clipstack. +@end table +@item crash +The value of the header @code{Event} is @code{crash} when +the clipboard has been reset because of a software crash. +@end table + +@item Purpose: +Enable clients to get notification about changes +to the clipboard, that cannot trivially derived +from @command{Command: clipboard} + +@item Compulsivity: +Optional add-on to the clipboard's functionallity. + +@item Reference implementation: +@command{mds-clipboard} +@end table + + + @node Miscellaneous Protocols @section Miscellaneous Protocols diff --git a/doc/protocols b/doc/protocols index cbfca47..52c61bf 100644 --- a/doc/protocols +++ b/doc/protocols @@ -1,110 +1,5 @@ --------------------------------------------------------------------- -Command: clipboard - Read or manipulate a clipboard - -Required header: Level - The clipboard level, an [1, 3] integer: - 1 "primary". Text copied/pasted using - the keyboard or a menu item - 2 "secondary". Text copied/pasted using the rat - 3 "tertiary". Non-text, it is customary for this - data to begin with a line describing - the data type. - -Required header: Action - What to do with the clipboard: - add) Write the message to the clipboard - read) Read the clipboard - clear) Clear all entries on the selected level on the clipboard - set-size) Shrink/grow the clipstack - get-size) Read the size of the clipstack - In the reply, the server will send: - Size: <configured maximum size of the clipstack> - Used: <number of elements currently in the clipstack> - -Conditionally required header: Length - Required if: `Action: add` - Length of the message - -Conditionally required header: Size - Required if: `Action: set-size` - The maximum number of elements in the clipstack - -Conditionally required header: Client ID - Your ID, provided by `ID assignment` - in response to `Command: assign-id`. - Required if: `Action: add` and a header starting with - `Time to live: until-death` - Required if: `Action: read` - Required if: `Action: get-size` - -Conditionally optional header: Index - Available and optional if: `Action: read` - The index of the item in the clipstack, starting at 0 - -Conditionally optional header: Time to live - Available and optional if: `Action: add` - The number of seconds the entry should be available - before it is removed by the server, or: - until-death: remove entry when the client closes - until-death #: remove entry when the client closes, - or # seconds have elapsed - forever: never remove it (default) - The server will always remove the entry when: - 1) it is at the bottom of the clipstack and a new - entry is added to the clipstack - 2) `Action: clear` is issued for the clipstack - The entry will also be removed, unless - `Time to live: forever`, if the server crashes or is - reexecuted. - It is up to the implementation to choose when - the removal actually takes place. For example, - the reference implementation will pop entries - that have timed out when a new entry is added, - the reading on the clipstack is requested or the - server is reexecuted, but another implement may - choose to pop entires asynchronously using another - thread or an alarm an pop when when SIGARLM is - received. - -Message: The content to add to the clipboard - -Purpose: Enable the user to duplicate content from one process - into another process without requiring those processes - to be aware of eathother to any extent - -Compulsivity: optional - -Reference implementation: mds-clipboard - ---------------------------------------------------------------------- - -Command: clipboard-info - The clipboard server sends out some information about - what it is doing, such as automatically removing entires - -Included header: Event - pop) An item in the clipstack has been removed - Included headers: - Level: The clipboard level that has been affected - Popped: The index of the item in the clipstack - that has been removed - Size: Configured maximum size of the clipstack - Used: Number of elements currently in the clipstack - crash) The clipboard has been reset because of a software crash - -Purpose: Enable clients to get notification about changes - to the clipboard, that cannot trivially derived - from `Command: clipboard` - -Compulsivity: optional, optional add-on to the - clipboard's functionallity - -Reference implementation: mds-clipboard - ---------------------------------------------------------------------- - Command: add-tray-icon Add a status icons to the status icon tray The client should keep in mind that there can be any number of |