ImportClipboard

Description

Inserts data into a DataWindow control, DataStore object, or graph control from tab-separated, comma-separated, or XML data on the clipboard.

For DataWindow and DataStore syntax, see the ImportClipboard method for DataWindows in the section called “ImportClipboard” in DataWindow Reference.

Applies to

Graph controls in windows and user objects. Does not apply to graphs within DataWindow objects, because their data comes directly from the DataWindow.

Syntax

graphname.ImportClipboard ( { importtype} {, startrow {, endrow {, startcolumn } } } )

Argument

Description

importtype

(optional)

An enumerated value of the SaveAsType DataWindow constant. Valid type arguments for ImportClipboard are:

Text!

CSV!

XML!

If you want to generate an XML trace file, the XML! argument is required.

graphname

The name of the graph control to which you want to copy data from the clipboard.

startrow

(optional)

The number of the first detail row in the clipboard that you want to copy. The default is 1.

For default XML import, if startrow is supplied, the first N (startrow -1) elements are skipped, where N is the DataWindow row size.

For template XML import, if startrow is supplied, the first (startrow -1) occurrences of the repetitive row mapping defined in the template are skipped.

endrow

(optional)

The number of the last detail row in the clipboard that you want to copy. The default is the rest of the rows.

For default XML import, if endrow is supplied, import stops when N * endrow elements have been imported, where N is the DataWindow row size.

For template XML import, if endrow is supplied, import stops after endrow occurrences of the repetitive row mapping defined in the template have been imported.

startcolumn (optional)

The number of the first column in the clipboard that you want to copy. The default is 1.

For default XML import, if startcolumn is supplied, import skips the first (startcolumn - 1) elements in each row.

This argument has no effect on template XML import.


Return value

Returns the number of rows that were imported if it succeeds and one of the following negative integers if an error occurs:

-1 -- No rows or startrow value supplied is greater than the number of rows in the string

-2 -- Input data does not match number of columns or required column type

-3 -- Invalid argument

-4 -- Invalid input

-11 -- XML Parsing Error; XML parser libraries not found, or XML not well formed

-12 -- XML Template does not exist or does not match the DataWindow

If any argument's value is null, ImportClipboard returns null. If the optional importtype argument is specified and is not a valid type, ImportClipboard returns -3.

Usage

The clipboard data must be formatted in tab-separated or comma-separated columns or in XML. The datatypes and order of the DataWindow object's columns must match the data on the clipboard.

For graphs, ImportClipboard uses only three columns and ignores other columns. Each row of data must contain three pieces of information. The information depends on the type of graph:

  • For all graph types except scatter, the first column to be imported is the series name, the second column contains the category, and the third column contains the data.

  • For scatter graphs, the first column to be imported is the series name, the second column is the data's x value, and the third column is the y value.

If a series or category already exists in the graph, the data is assigned to it. Otherwise, the series and categories are added to the graph.

You can add data to more than one series by specifying different series names in the first column.

Examples

If the clipboard contains the data shown below and the graph does not have any data yet, then the next statement produces a graph with two series and three categories. The clipboard data is:

Sales 94Jan3000
Sales 94Mar2200
Sales 94May2500
Sales 95Jan4000
Sales 95Mar3200
Sales 95May3500

This statement copies all the data in the clipboard, as shown above, to gr_employee:

gr_employee.ImportClipboard()

This statement copies the data from the clipboard starting with row 2 column 3 and copying to row 30 column 5 to the graph gr_employee:

gr_employee.ImportClipboard(2, 30, 3)

See also

ImportFile

ImportString