◄Using Section►  ◄Function Group►  ◄Message Group►    ◄Up► ◄Next► ◄Previous►
────────────────────────────────────────────────────────────────────────────
 
                            About the Clipboard
 
This topic describes how to use the clipboard to transfer data between
applications. You should also be familiar with the following topics:
 
    ◄Bitmaps►
    ◄Metafiles►
    ◄Atom tables►
    ◄Messages and message queues►
    ◄Memory manager►
 
The clipboard is a set of functions that can be used by Presentation Manager
applications for exchanging data. In particular, the clipboard provides
support for the generalized cut, copy, and paste user-interface common to
Presentation Manager applications. The clipboard supports data formats
common to most applications, as well as allowing individual applications to
define new formats for special purposes.
 
The data on the clipboard is maintained in memory only. Clipboard data is
lost when the computer is turned off.
 
Data exchange on the clipboard is controlled by the user. An application
should not perform any clipboard operations unless the user explicitly
initiates them. Other MS OS/2 features, such as pipes, queues, and shared
memory should be used when data exchange is needed without the knowledge of
the user. For example, an application that continuously passes remotely
collected data to a data-analysis application should not use the clipboard.
Such an application should use the other interprocess data communication
capabilities of MS OS/2 instead.
 
Cutting, Copying, and Pasting Data
 
All Presentation Manager programs should support the cut, copy, and paste
data exchange in a single application and between applications. These are
all user-initiated operations. Typically, a user selects data in an
application, called the "current selection." The application should provide
visual feedback, such as inverting the data display, to indicate the current
selection. The user can then initiate a cut, copy, or paste operation on the
current selection.
 
The standard cut, copy, and paste operations are summarized in the following
list:
 
Operation  Description
────────────────────────────────────────────────────────────────────────────
Cut        Copies the current selection to the clipboard and deletes the
           current selection from the application document. The previous
           contents of the clipboard are destroyed.
 
Copy       Copies the current selection to the clipboard. The current
           selection remains unchanged. The previous contents of the
           clipboard are destroyed.
 
Paste      Deletes the current selection and replaces it with the contents
           of the clipboard. The contents of the clipboard are not changed.
 
Clear      Deletes the current selection without putting the data on the
           clipboard. The contents of the clipboard are not changed.
 
Clipboard-Data Formats
 
The clipboard accepts data in several formats. MS OS/2 supports three
standard formats: text, bitmap, and metafile. Applications can use these
predefined formats or create their own formats.
 
Typically, all formats on the clipboard are simply different representations
of the most recent selection on the clipboard. For example, a word processor
that supports multiple fonts might write a selection to the clipboard in
three formats: straight text, rich text, and metafile. Another application
(pasting from the clipboard) could then choose the format most applicable to
its own capabilities. All of these formats refer to the same data.
 
Shared Memory and the Clipboard
 
Because data on the clipboard can be accessed by different applications, it
is important that it be stored in shared memory. The clipboard uses two
types of memory: selectors for shareable segments (allocated by the
DosAllocSeg function), and Presentation Manager objects such as bitmaps and
metafiles. Clipboard functions use two flag values, CFI_SELECTOR and
CFI_HANDLE, to distinguish each memory type.
 
When an application writes either a bitmap or a metafile to the clipboard,
it passes a bitmap or metafile handle to the clipboard. The clipboard
functions make the object "shareable." The application cannot access the
object once it closes the clipboard. Once an object is passed to the
clipboard, it can no longer be used in the application. Likewise, when an
application requests a bitmap or metafile from the clipboard, it receives a
handle to a bitmap or metafile object that is good only until the
application closes the clipboard. Typically, the application either uses the
object immediately before closing the clipboard, or it copies the object to
local memory for future use, then closes the clipboard.
 
To give a selector to the clipboard, an application must put data into a
segment allocated by using the DosAllocSeg function with the SEG_GIVEABLE
attribute. Once an application passes the selector for that segment to the
clipboard and closes the clipboard, the clipboard owns the segment. The
application cannot access the shared segment. When an application requests a
selector from the clipboard, the clipboard gives the segment to the
application. An application must use the selector before closing the
clipboard or it must copy the data from the shared segment to a local
segment before closing the clipboard.
 
An application must use a shared segment when writing text to the clipboard.
An application must also use shared segments for any application-defined
clipboard formats. In this case, it is important to specify the CFI_SELECTOR
flag when sending data to the clipboard.
 
 
                                      ♦