Clipboard operations

Through a set of dedicated methods, HyperFormula supports clipboard operations, such as copying, cutting, and pasting. This lets you integrate the functionality of interacting with the clipboard.

The copied or cut data is stored as a memory reference, not directly in the system clipboard.

Copy

To copy the contents of a cell or range, use the copy() method. Pass arguments of type SimpleCellRange.

const hfInstance = HyperFormula.buildFromArray([
  ['1', '2'],
]);

// copy [ [ 2 ] ]
const clipboardContent = hfInstance.copy({
  start: { sheet: 0, col: 1, row: 0 },
  end: { sheet: 0, col: 1, row: 0 },
});

Cut

To cut the contents of a cell or range, use the cut() method. Pass arguments of type SimpleCellRange.

Tip

Any CRUD operation called after the cut() method aborts the cut operation.

const hfInstance = HyperFormula.buildFromArray([
  ['1', '2'],
]);

// returns the values that were cut: [ [ 1 ] ]
const clipboardContent = hfInstance.cut({
  start: { sheet: 0, col: 0, row: 0 },
  end: { sheet: 0, col: 0, row: 0 },
});

Paste

To paste the contents of a cell or range, use the paste() method.

paste() requires only one parameter: the top left corner of the target range.

const hfInstance = HyperFormula.buildFromArray([
  ['1', '2'],
]);

// [ [ 2 ] ] was copied
const clipboardContent = hfInstance.copy({
  start: { sheet: 0, col: 1, row: 0 },
  end: { sheet: 0, col: 1, row: 0 },
});

// returns a list of modified cells: their absolute addresses and new values
const changes = hfInstance.paste({ sheet: 0, col: 1, row: 0 });

If the clipboard is empty, the paste() method doesn’t do anything.

Copy and paste

When called after copy(), the paste() method:

• Pastes the copied data into the target range.
• Triggers a recalculation of all affected formulas.

Tip

If a formula =A1 is copied from cell B1 into B2, the B2 formula becomes =A2.

Cut and paste

When called after cut(), the paste() method:

• Moves the cut data into the target range, by calling the moveCells() method.
• Removes the cut data from the source range.
• Triggers a recalculation of all affected formulas.

Tip

If a formula =A1 is cut from cell B1 into B2, the B2 formula becomes =A1.

Pasting named expressions

If a copied or cut formula contains a named expression defined for a local scope, and the formula is pasted to a sheet that is out of scope for that expression, the expression’s scope changes to global.

If the copied or cut named expression’s scope is the same as the target’s, the expression’s local scope remains the same.

Clear the clipboard

To clear the clipboard, use the clearClipboard() method.

To check if the clipboard holds any data, use the isClipboardEmpty() method.

Data storage

The copied or cut data is stored as a memory reference, not directly in the system clipboard.

Depending on what was cut, the data is stored as:

• An array of arrays
• A number
• A string
• A boolean
• An empty value

Demo

Copy Paste Reset

Name	Surname	Both

Source code

/* start:skip-in-sandbox */
const NothingToPasteError = HyperFormula.NothingToPasteError;
/* end:skip-in-sandbox */
/**
 * Initial table data.
 */
const tableData = [
  ['Greg', 'Black', '=CONCATENATE(A1, " ",B1)'],
  ['Anne', 'Carpenter', '=CONCATENATE(A2, " ", B2)'],
  ['Chris', 'Aklips', '=CONCATENATE(A3, " ",B3)'],
];

// Create an empty HyperFormula instance.
const hf = HyperFormula.buildEmpty({
  licenseKey: 'gpl-v3',
});

// Add a new sheet and get its id.
const sheetName = hf.addSheet('main');
const sheetId = hf.getSheetId(sheetName);

/**
 * Reinitialize the HF data.
 */
function reinitializeData() {
  hf.setCellContents(
    {
      row: 0,
      col: 0,
      sheet: sheetId,
    },
    tableData,
  );
}

/**
 * Bind the events to the buttons.
 */
function bindEvents() {
  const copyButton = document.querySelector('.example #copy');
  const pasteButton = document.querySelector('.example #paste');
  const resetButton = document.querySelector('.example #reset');

  copyButton.addEventListener('click', () => {
    copy();
    updateCopyInfo('Second row copied');
  });
  pasteButton.addEventListener('click', () => {
    paste();
  });
  resetButton.addEventListener('click', () => {
    reinitializeData();
    updateCopyInfo('');
    renderTable();
  });
}

/**
 * Copy the second row.
 */
function copy() {
  return hf.copy({
    start: { sheet: 0, col: 0, row: 1 },
    end: { sheet: 0, col: 2, row: 1 },
  });
}

/**
 * Paste the HF clipboard into the first row.
 */
function paste() {
  try {
    hf.paste({ sheet: 0, col: 0, row: 0 });
    updateCopyInfo('Pasted into the first row');
    renderTable();
  } catch (error) {
    if (error instanceof NothingToPasteError) {
      updateCopyInfo('There is nothing to paste');
    } else {
      throw error;
    }
  }
}

const ANIMATION_ENABLED = true;

/**
 * Fill the HTML table with data.
 */
function renderTable() {
  const tbodyDOM = document.querySelector('.example tbody');
  const updatedCellClass = ANIMATION_ENABLED ? 'updated-cell' : '';
  const { height, width } = hf.getSheetDimensions(sheetId);
  let newTbodyHTML = '';

  for (let row = 0; row < height; row++) {
    for (let col = 0; col < width; col++) {
      const cellAddress = { sheet: sheetId, col, row };
      let cellValue = '';

      if (!hf.isCellEmpty(cellAddress)) {
        cellValue = hf.getCellValue(cellAddress);
      }

      newTbodyHTML += `<td class="${updatedCellClass}"><span>
      ${cellValue}
      </span></td>`;
    }

    newTbodyHTML += '</tr>';
  }

  tbodyDOM.innerHTML = newTbodyHTML;
}

/**
 * Update the information about the copy/paste action.
 *
 * @param {string} message Message to display.
 */
function updateCopyInfo(message) {
  const copyInfoDOM = document.querySelector('.example #copyInfo');

  copyInfoDOM.innerText = message;
}

// Fill the HyperFormula sheet with data.
reinitializeData();
// Bind the button events.
bindEvents();
// Render the table.
renderTable();