CLIPBOARD system handle

A handle to the system clipboard widget. The CLIPBOARD handle allows you to implement interactions that allow the user to transfer data between ABL field-level widgets, or between ABL field-level widgets and the widgets of other applications running on the system. ABL can interpret the data read from or written to the system clipboard widget as a single item or as a group of multiple items. These data transfers are typically invoked as cut, copy, and paste operations.

Syntax

CLIPBOARD [ :attribute ]

attribute

An attribute of the clipboard widget.

Attributes

Examples

The following code fragment implements cut, copy, and paste operations for the EM_Cut, EM_Copy, and EM_Paste items on the EditMenu menu. It uses the FOCUS handle to reference the widget that has the current input focus.

Note that the fragment tests the widget type of the FOCUS widget in two instances: once when EditMenu is opened during the MENU-DROP event to determine what clipboard operations are valid for the widget, and once again when a clipboard operation is chosen from the menu to determine how the operation is executed for the widget. During the MENU-DROP event, if a particular operation is valid for the FOCUS widget the menu item for that operation is enabled. Otherwise, it is disabled.

During the CHOOSE event for a n enabled menu item, the fragment executes the corresponding clipboard operation in a way that accounts for the unique features of the FOCUS widget. For example, the copy operation (EM_Copy) copies the selected text from an editor widget, copies the label text from a radio set item, and copies a composed true or false message for a toggle box. Your own implementation of these operations for the same widgets can be quite different.

For a complete description of this example, see the chapter on the system clipboard in OpenEdge Development: Programming Interfaces.

DEFINE VARIABLE lStat AS LOGICAL NO-UNDO.
. . .
ON MENU-DROP OF MENU EditMenu DO:
  IF FOCUS:TYPE = "EDITOR" THEN DO:
    MENU-ITEM EM_Cut:SENSITIVE IN MENU EditMenu =
      IF LENGTH(FOCUS:SELECTION-TEXT) > 0 THEN TRUE ELSE FALSE.
    MENU-ITEM Em_Copy:SENSITIVE IN MENU EditMenu =
      IF LENGTH(FOCUS:SELECTION-TEXT) > 0 THEN TRUE ELSE FALSE.
    MENU-ITEM EM_Paste:SENSITIVE IN MENU EditMenu =
      IF CLIPBOARD:NUM-FORMATS > 0 THEN TRUE ELSE FALSE.
  END.
  ELSE IF FOCUS:TYPE = "RADIO-SET" OR 
          FOCUS:TYPE = "SELECTION-LIST" OR
          FOCUS:TYPE = "SLIDER" OR
          FOCUS:TYPE = "TOGGLE-BOX" THEN DO:
    MENU-ITEM EM_Cut:SENSITIVE IN MENU EditMenu = FALSE.
    MENU-ITEM Em_Copy:SENSITIVE IN MENU EditMenu = TRUE.
    MENU-ITEM Em_Paste:SENSITIVE IN MENU EditMenu = FALSE.
  END.
  ELSE IF FOCUS:TYPE = "FILL-IN" THEN DO:
    MENU-ITEM EM_Cut:SENSITIVE IN MENU EditMenu =
      IF LENGTH(FOCUS:SCREEN-VALUE) > 0 THEN TRUE ELSE FALSE.
    MENU-ITEM Em_Copy:SENSITIVE IN MENU EditMenu =
      IF LENGTH(FOCUS:SCREEN-VALUE) > 0 THEN TRUE ELSE FALSE.
    MENU-ITEM EM_Paste:SENSITIVE IN MENU EDitMenu =
      IF CLIPBOARD:NUM-FORMATS > 0 THEN TRUE ELSE FALSE.
  END.
  ELSE DO:
    MENU-ITEM EM_Cut:SENSITIVE IN MENU EditMenu = FALSE.
    MENU-ITEM EM_Copy:SENSITIVE IN MENU EditMenu = FALSE.
    MENU-ITEM EM_Paste:SENSITIVE IN MENU EditMenu = FALSE.
  END.
END. /* ON MENU-DROP IN EditMenu */

ON CHOOSE OF MENU-ITEM EM_Cut IN MENU EditMenu DO:
  IF FOCUS:TYPE = "EDITOR" THEN DO:
    IF FOCUS:SELECTION-START <> FOCUS:SELECTION-END THEN ASSIGN
      CLIPBOARD:VALUE = FOCUS:SELECTION-TEXT
      lStat           = FOCUS:REPLACE-SELECTION-TEXT("").
    ELSE ASSIGN
      CLIPBOARD:VALUE    = FOCUS:SCREEN-VALUE
      FOCUS:SCREEN-VALUE = "".
  END.
  ELSE ASSIGN /* For FILL-IN */
    CLIPBOARD:VALUE    = FOCUS:SCREEN-VALUE
    FOCUS:SCREEN-VALUE = "".
END. /* ON CHOOSE OF MENU-ITEM EM_Cut */

ON CHOOSE OF MENU-ITEM EM_Copy IN MENU EditMenu DO:
  IF FOCUS:TYPE = "EDITOR" THEN
    IF FOCUS:SELECTION-START <> FOCUS:SELECTION-END THEN
      CLIPBOARD:VALUE = FOCUS:SELECTION-TEXT.
    ELSE 
      CLIPBOARD:VALUE = FOCUS:SCREEN-VALUE.
    ELSE IF FOCUS:TYPE = "RADIO-SET" THEN
      CLIPBOARD:VALUE = ENTRY(LOOKUP(FOCUS:SCREEN-VALUE, 
        FOCUS:RADIO-BUTTONS) - 1, FOCUS:RADIO-BUTTONS).
    ELSE IF FOCUS:TYPE = "TOGGLE-BOX" THEN
      IF FOCUS:SCREEN-VALUE = "yes" THEN
        CLIPBOARD:VALUE = FOCUS:LABEL + " selected.".
      ELSE
        CLIPBOARD:VALUE = FOCUS:LABEL + " not selected.".
    ELSE /* For FILL-IN */
       CLIPBOARD:VALUE = FOCUS:SCREEN-VALUE.
END. /* ON CHOOSE OF MENU-ITEM EM_Copy */

ON CHOOSE OF MENU-ITEM EM_Paste IN MENU EditMenu DO:
  IF FOCUS:TYPE = "EDITOR" THEN DO:
    IF FOCUS:SELECTION-START <> FOCUS:SELECTION-END THEN
      lStat = FOCUS:REPLACE-SELECTION-TEXT(CLIPBOARD:VALUE).
    ELSE 
      aResult = FOCUS:INSERT-STRING(CLIPBOARD:VALUE).
  END.
  ELSE /* For FILL-IN */
    FOCUS:SCREEN-VALUE = CLIPBOARD:VALUE.
END. /* ON CHOOSE OF MENU-ITEM EM_Paste */
. . .

The following r-clpmul.p procedure demonstrates interaction with the clipboard using multiple items. The procedure copies out four rows of five numbers to the clipboard. It first displays the clipboard data as a single item, and then as a list of multiple items.

As a further demonstration of how the CLIPBOARD handle works with multiple items, try the following experiment:

1. Run the procedure, and at the pause, paste the result into an edit tool in your window system, such as Notepad in Windows.
2. You may have to select and copy text in the edit tool to activate the system clipboard before running the procedure.
3. Modify the text in the edit tool, leaving at least one tab or newline character, and copy it back to the clipboard from the edit tool.
4. Respond to the pause in the procedure to see how the modified clipboard data is displayed.

r-clpmul.p

DEFINE VARIABLE ClipBuffer AS CHARACTER NO-UNDO
  VIEW-AS EDITOR SIZE 60 BY 5.
DEFINE VARIABLE ClipItem   AS CHARACTER NO-UNDO.
DEFINE VARIABLE ix         AS INTEGER   NO-UNDO.

/* Copy rows of integer items to the clipboard, display the clipboard value. */
ASSIGN
  CLIPBOARD:MULTIPLE      = TRUE
  CLIPBOARD:ITEMS-PER-ROW = 5.

REPEAT ix = 1 TO 20: 
  CLIPBOARD:VALUE = STRING(ix).
END.

ASSIGN
  CLIPBOARD:MULTIPLE = FALSE
  ClipBuffer         = CLIPBOARD:VALUE.

ENABLE ClipBuffer WITH FRAME A.
DISPLAY SPACE(1) ClipBuffer LABEL "Clipboard Data" WITH FRAME A.
PAUSE.

/* Display each item of the clipboard value. */
ASSIGN
  CLIPBOARD:MULTIPLE = TRUE
  ClipItem           = "".

REPEAT WHILE ClipItem <> ?:
  ClipItem = CLIPBOARD:VALUE.
  IF ClipItem <> ? THEN
    DISPLAY SPACE(1) ClipItem FORMAT "x(16)" LABEL "Clipboard Item" 
      WITH DOWN FRAME B.
END.

CLIPBOARD:MULTIPLE = FALSE.

Notes

• In character mode environments where there is no system clipboard, ABL supports CLIPBOARD handle operations within a single ABL application. You can cut and paste among fields in one ABL application, but not between one ABL application and another ABL or non-ABL application.
• In graphical window systems, ABL supports CLIPBOARD handle operations using the system clipboard. This allows data transfers among ABL and non-ABL applications as well as within a single ABL application.
• The AVAILABLE-FORMATS attribute returns a comma-delimited string containing the names of the available formats for the data stored in the clipboard. ABL currently supports two formats:
  • PRO_TEXT — Specifies the standard text format on your system (CF_TEXT in Windows).
  • PRO_MULTIPLE — Specifies that the data in the clipboard contains tab or newline characters, and thus can be read as multiple items.
• The ITEMS-PER-ROW attribute specifies how the AVM writes multiple items to the clipboard. Set the MULTIPLE attribute to TRUE before specifying ITEMS-PER-ROW. Then when you set ITEMS-PER-ROW to any integer value n greater than 1, the AVM terminates every nth value you assign to the VALUE attribute with a newline character and terminates all other values with a tab character. This formats the output in the clipboard into newline-terminated rows of n items separated by tabs. The default value for the ITEMS-PER-ROW attribute is 1.

  During a MULTIPLE write, you can set and reset ITEMS-PER-ROW at any time until you set the MULTIPLE attribute to FALSE. When you set the MULTIPLE attribute to FALSE, the AVM uses the current value of ITEMS-PER-ROW to format and flush the data to the clipboard, and resets the ITEMS-PER-ROW attribute to 1.

  The value of ITEMS-PER-ROW has no effect when reading data from the clipboard.

• The MULTIPLE attribute specifies whether the AVM reads data from, and writes data to, the clipboard as a single item or as multiple items.

  When you set MULTIPLE to FALSE, the AVM treats all data in the clipboard as a single item. Thus, any character string you assign to the VALUE attribute replaces all data in the clipboard, and whenever you read the VALUE attribute it returns all the data in the clipboard.

  When you set MULTIPLE to TRUE, the AVM treats the data in the clipboard as multiple items separated by tab or newline characters.

  When you set the MULTIPLE attribute to TRUE and write values to the clipboard (assign values to the VALUE attribute), the AVM stores the values in a buffer until you set MULTIPLE to FALSE. At this time the AVM assigns the values to the clipboard separated from each other by tab or newline characters according to the value of the ITEMS-PER-ROW attribute. Note that the clipboard data itself does not change until you set MULTIPLE to FALSE. When you do set MULTIPLE to FALSE, all data previously in the clipboard is replaced by the items you have written.

  When you set the MULTIPLE attribute to TRUE and read values from the clipboard (assign values from the VALUE attribute), each read returns the next item in the clipboard (starting with the first one). After all items have been read, the VALUE attribute returns the Unknown value (?). Setting the MULTIPLE attribute to FALSE and then to TRUE restarts the item pointer to read the first item of data in the clipboard.

  Until you (or another application) write data to the clipboard, changing the value of the MULTIPLE attribute itself has no effect on clipboard contents. It only affects the way you can access the clipboard for reading and writing.

  The default value for the MULTIPLE attribute is FALSE.

• The NUM-FORMATS attribute returns the number of formats available to read data from the clipboard. If no data is in the clipboard, the value is 0. If data is in the clipboard, the value is 1 (for PRO_TEXT) unless there are tab or newline characters in the data, in which case the value is 2 (for both PRO_TEXT and PRO_MULTIPLE).
• The VALUE attribute accesses the data in the clipboard. Reading the VALUE attribute has no effect on the clipboard contents. However, the exact value read or written depends on the setting of the MULTIPLE attribute.

  When the MULTIPLE attribute is FALSE, reading the VALUE attribute returns the current value in the clipboard as a single item. If there is no data in the clipboard, the VALUE attribute returns the Unknown value (?). Writing to the VALUE attribute immediately changes the current value in the clipboard to the value that is written.

  When the MULTIPLE attribute is TRUE, reading the VALUE attribute either references one of the multiple data items in the clipboard, or references the Unknown value (?) if all items have been read or there is no data in the clipboard. Writing to the VALUE attribute buffers each assignment and replaces the current data in the clipboard with the multiple values assigned when the MULTIPLE attribute is set to FALSE. See the previous description of the MULTIPLE attribute for more information.

  Note: Windows provides clipboard storage for a maximum of 64K of data.

  Assigning the Unknown value (?) to the VALUE attribute has no effect. To write a null item or clear the system clipboard when writing a single item, assign the null string ("") to the VALUE attribute.

• To cut or copy an ABL data item to the clipboard, set the CLIPBOARD:VALUE attribute to the value of the appropriate field or variable. A cut or copy operation replaces all data in the clipboard with the data from the specified ABL field or variable.
• To paste data from the clipboard to an ABL data item, assign the value of the CLIPBOARD:VALUE attribute to the appropriate the field or variable. If there is no data in the clipboard, a paste operation assigns the Unknown value (?) to the data item.
• To implement clipboard operations, use the FOCUS system handle, which identifies the ABL field-level widget that has the current input focus. Depending on the type of widget (for example, EDITOR or RADIO-ITEM) and its input state, you use one of several possible widget attributes as the source or destination for the data. For example, when working with selected text in an editor widget, use the SELECTION-TEXT attribute to cut or copy and the REPLACE-SELECTION-TEXT method to paste, but when working with the value of the entire editor field, use the SCREEN-VALUE attribute for all operations.
• Do not interrupt an ABL clipboard operation with input-blocking statements like UPDATE or WAIT-FOR. In general, make any ABL clipboard cut, copy, or paste operation with the CLIPBOARD handle a one-step operation. Any interruption gives the user an opportunity to access and modify the clipboard from outside ABL, in the middle of the ABL clipboard operation.
• Windows provides default clipboard operations through control keys, whether or not you implement them with the CLIPBOARD handle. These operations are available in editor and fill-in widgets, and are completely compatible with CLIPBOARD handle operations. They are single-item operations without any interaction with the MULTIPLE attribute. They also can occur in the middle of an ABL clipboard operation, if it is interrupted. (See the previous bullet on interrupting ABL clipboard operations.) The operations and control keys to activate them include:
  • Cut — CTRL+X and SHIFT+DEL
  • Copy — CTRL+C and CTRL+INS
  • Paste — CTRL+V and SHIFT+INS
• The TYPE attribute returns the widget type, PSEUDO-WIDGET.
• For more information on implementing clipboard operations with the CLIPBOARD handle, see OpenEdge Development: Programming Interfaces.

See also

FOCUS system handle