Clipboard

The clipboard is a shared storage area that can be used to transfer data within an application or between multiple applications. Content placed on the clipboard can be copied (or "pasted") into another section of an application or into a completely different application.

The following application demonstrates the use of the clipboard. It is signed to allow it to access the system clipboard; untrusted Pivot applications can only perform copy and paste with a local clipboard whose content is not shared with other applications.

The application source code consists of two files: a main BXML file that declares the structure of the user interface along with some simple event handlers, and a JavaScript file that defines two functions: copy() and paste(). These functions are invoked by the button press listeners attached to the UI elements declared in the BXML file. The BXML source code for the example is shown below:

            
            <Window title="Clipboard" maximized="true"
                xmlns:bxml="http://pivot.apache.org/bxml"
                xmlns="org.apache.pivot.wtk">
                <bxml:script src="clipboard.js"/>

                <windowStateListeners>
                    function windowOpened(window) {
                        sourceImageButtonGroup.setSelection(sourceImageButton1);
                        sourceImageButton1.requestFocus();
                    }
                </windowStateListeners>

                <TablePane styles="{horizontalSpacing:4, verticalSpacing:4}">
                    <columns>
                        <TablePane.Column width="1*"/>
                        <TablePane.Column width="1*"/>
                    </columns>

                    <TablePane.Row height="1*">
                        <Border styles="{padding:2}">
                            <CardPane bxml:id="sourceImageCardPane" styles="{padding:4}">
                                <ImageView image="/org/apache/pivot/tutorials/IMG_0725_2.jpg"/>
                                <ImageView image="/org/apache/pivot/tutorials/IMG_0735_2.jpg"/>
                                <ImageView image="/org/apache/pivot/tutorials/IMG_0767_2.jpg"/>
                            </CardPane>
                        </Border>
                        <Border styles="{padding:2}">
                            <CardPane selectedIndex="0" styles="{padding:4}">
                                <ImageView bxml:id="destinationImageView"/>
                            </CardPane>
                        </Border>
                    </TablePane.Row>

                    <TablePane.Row height="-1">
                        <BoxPane orientation="vertical" styles="{fill:true}">
                            <BoxPane bxml:id="sourceImageButtonBoxPane"
                                styles="{horizontalAlignment:'center', verticalAlignment:'center'}">
                                <bxml:define>
                                    <ButtonGroup bxml:id="sourceImageButtonGroup">
                                        <buttonGroupListeners>
                                            function selectionChanged(buttonGroup, previousSelection) {
                                                var selection = buttonGroup.getSelection();

                                                if (selection != null) {
                                                    var index = sourceImageButtonBoxPane.indexOf(selection);
                                                    sourceImageCardPane.setSelectedIndex(index);
                                                }
                                            }
                                        </buttonGroupListeners>
                                    </ButtonGroup>
                                </bxml:define>

                                <PushButton bxml:id="sourceImageButton1"
                                    buttonData="IMG_0725_2.jpg" toggleButton="true"
                                    buttonGroup="$sourceImageButtonGroup"/>
                                <PushButton bxml:id="sourceImageButton2"
                                    buttonData="IMG_0735_2.jpg" toggleButton="true"
                                    buttonGroup="$sourceImageButtonGroup"/>
                                <PushButton bxml:id="sourceImageButton3"
                                    buttonData="IMG_0767_2.jpg" toggleButton="true"
                                    buttonGroup="$sourceImageButtonGroup"/>
                            </BoxPane>

                            <BoxPane styles="{horizontalAlignment:'center'}">
                                <PushButton bxml:id="copyButton" buttonData="Copy"
                                    ButtonPressListener.buttonPressed="copy()"/>
                            </BoxPane>
                        </BoxPane>

                        <BoxPane styles="{horizontalAlignment:'center', verticalAlignment:'center'}">
                            <PushButton bxml:id="pasteButton" buttonData="Paste"
                                ButtonPressListener.buttonPressed="paste()"/>
                        </BoxPane>
                    </TablePane.Row>
                </TablePane>
            </Window>
            
        

Like most Pivot tutorial examples, it defines a single top-level, maximized, undecorated Window instance that contains the rest of the UI. The source images are contained in a set of ImageView components stored in a CardPane, and a set of toggle-style PushButtons is used to navigate between them. Another ImageView is used to display the image content pasted from the clipboard.

The file defines several event handlers:

  • A window state listener that initializes the selection of the card pane when the window is opened:

                        
                        <windowStateListeners>
                            function windowOpened(window) {
                                sourceImageButtonGroup.setSelection(sourceImageButton1);
                                sourceImageButton1.requestFocus();
                            }
                        </windowStateListeners>
                        
                    
  • A button group listener that changes the card pane's selection in response to a button group selection change:

                        
                        <buttonGroupListeners>
                            function selectionChanged(buttonGroup, previousSelection) {
                                var selection = buttonGroup.getSelection();
    
                                if (selection != null) {
                                    var index = sourceImageButtonBoxPane.indexOf(selection);
                                    sourceImageCardPane.setSelectedIndex(index);
                                }
                            }
                        </buttonGroupListeners>
                        
                    
  • A button press listener that calls the copy() function when the "Copy" button is pressed:

                        
                        <PushButton bxml:id="copyButton" buttonData="Copy"
                            ButtonPressListener.buttonPressed="copy()"/>
                        
                    
  • A button press listener that calls the paste() function when the "Paste" button is pressed:

                        
                        <PushButton bxml:id="pasteButton" buttonData="Paste"
                            ButtonPressListener.buttonPressed="paste()"/>
                        
                    

Since all of the application's logic is implemented in script, there is no Java source file for this example. The contents of "clipboard.js" are shown below:

            
            importPackage(org.apache.pivot.wtk);

            function copy() {
                // Copy the selected image to the clipboard
                var selectedSourceIndex = sourceImageCardPane.getSelectedIndex();
                var sourceImageView = sourceImageCardPane.get(selectedSourceIndex);
                var sourceImage = sourceImageView.getImage();

                var content = new LocalManifest();
                content.putImage(sourceImage);

                Clipboard.setContent(content);
            }

            function paste() {
                // Paste any available image from the clipboard
                var content = Clipboard.getContent();

                if (content != null) {
                    var image = content.getImage();

                    if (image != null) {
                        destinationImageView.setImage(image);
                    }
                }
            
        

These two functions perform the actual copying and pasting of the image data. The copy() function gets a reference to the actual image displayed by the selected card (an instance of org.apache.pivot.wtk.media.Image) and sets it as the "image" property of a LocalManifest instance. LocalManifest is a concrete implementation of the abstract Manifest class that is used to represent the source data in a clipboard transaction. In contrast, a RemoteManifest represents data obtained from the clipboard. Local manifests are created by an application, whereas remote manifests are created by the system.

A manifest encapsulates the content that may be placed on the clipboard by a Pivot application. It can represent the data in a variety of "flavors": as text, as an image, as a list of files, as a URL, or as a custom data format. An application may provide one or more flavors depending on the nature of the data. An application that is interested in consuming the data can then choose the most appropriate format based on the available flavors.

Once the manifest has been created and populated, it is placed on the clipboard via the Clipboard.setContent() method. It is now available for other applications to consume.

The paste() method performs the opposite transaction. It retrieves the current clipboard contents and checks for the presence of an image flavor. If available, it extracts the image content and sets it as the source of the "destinationImageView" component.

Next: Drag and Drop