Score

https://pub.dev/packages/super_clipboard
Admin
This repository contains documentation for the Score project, detailing various versions and related...
Tokens:18,773
Snippets:284
Trust Score:9.9
Update:3 months ago
Show doc for...
Tokens:
Raw
### Install Melos and Bootstrap Project

Source: https://pub.dev/packages/super_clipboard

Installs the Melos tool globally if not already present, clones the repository, and bootstraps the project dependencies.

```bash
flutter pub global activate melos # if you don't have melos already installed
git clone https://github.com/superlistapp/super_native_extensions.git
cd super_native_extensions
melos bootstrap

```

--------------------------------

### Flutter App Entry Point and Main UI Setup

Source: https://pub.dev/packages/super_clipboard/versions/0.9.0-dev.1/example

Sets up the main Flutter application, theme, and the home page. It also registers and unregisters paste event listeners.

```dart
import 'dart:ui' as ui;
import 'dart:typed_data';

import 'package:flutter/material.dart';
import 'package:flutter/rendering.dart';
import 'package:super_clipboard/super_clipboard.dart';
import 'package:flutter_layout_grid/flutter_layout_grid.dart';

import 'widget_for_reader.dart';

void main() async {
  runApp(const MyApp());
}

const _notAvailableMessage =
    'Clipboard is not available on this platform. Use ClipboardEvents API instead.';

class MyApp extends StatelessWidget {
  const MyApp({super.key});

  // This widget is the root of your application.
  @override
  Widget build(BuildContext context) {
    return MaterialApp(
      title: 'SuperClipboard Example',
      theme: ThemeData(
        snackBarTheme: const SnackBarThemeData(
          behavior: SnackBarBehavior.floating,
        ),
        outlinedButtonTheme: OutlinedButtonThemeData(
          style: OutlinedButton.styleFrom(
              padding: 
                  const EdgeInsets.symmetric(horizontal: 10, vertical: 16)),
        ),
        primarySwatch: Colors.blue,
        useMaterial3: false,
      ),
      home: const MyHomePage(title: 'SuperClipboard Example'),
    );
  }
}

class Expand extends SingleChildRenderObjectWidget {
  const Expand({super.key, required super.child});

  @override
  RenderObject createRenderObject(BuildContext context) => _RenderExpanded();
}

class _RenderExpanded extends RenderProxyBox {
  @override
  void layout(Constraints constraints, {bool parentUsesSize = false}) {
    final boxConstraints = constraints as BoxConstraints;
    super.layout(
        boxConstraints.tighten(
          width: boxConstraints.maxWidth,
          height: boxConstraints.maxHeight,
        ),
        parentUsesSize: parentUsesSize);
  }
}

class HomeLayout extends StatelessWidget {
  const HomeLayout({
    super.key,
    required this.mainContent,
    required this.buttons,
  });

  final List<Widget> mainContent;
  final List<Widget> buttons;

  @override
  Widget build(BuildContext context) {
    return LayoutBuilder(builder: (context, constraints) {
      if (constraints.maxWidth < 540) {
        return ListView(
          padding: const EdgeInsets.all(16),
          children: [
            LayoutGrid(
              autoPlacement: AutoPlacement.rowDense,
              columnSizes: [1.5.fr, 2.fr],
              rowSizes: const [auto, auto, auto, auto],
              gridFit: GridFit.expand,
              rowGap: 10,
              columnGap: 10,
              children: buttons.map((e) => Expand(child: e)).toList(),
            ),
            const SizedBox(height: 16),
            ...mainContent,
          ],
        );
      } else {
        return Row(
          crossAxisAlignment: CrossAxisAlignment.stretch,
          children: [
            SingleChildScrollView(
              child: Padding(
                padding: const EdgeInsets.all(16),
                child: IntrinsicWidth(
                  child: Column(
                    crossAxisAlignment: CrossAxisAlignment.stretch,
                    children: buttons
                        .intersperse(const SizedBox(height: 10))
                        .toList(growable: false),
                  ),
                ),
              ),
            ),
            VerticalDivider(
              color: Colors.blueGrey.shade100,
              thickness: 1,
              width: 1,
            ),
            Expanded(
              child: ListView(
                padding: const EdgeInsets.all(16),
                children: mainContent,
              ),
            )
          ],
        );
      }
    });
  }
}

class MyHomePage extends StatefulWidget {
  const MyHomePage({super.key, required this.title});

  final String title;

  @override
  State<MyHomePage> createState() => _MyHomePageState();
}

class _MyHomePageState extends State<MyHomePage>
    with SingleTickerProviderStateMixin {
  void showMessage(String message) {
    ScaffoldMessenger.of(context).showSnackBar(
      SnackBar(
        content: Text(message),
        duration: const Duration(milliseconds: 1500),
      ),
    );
  }

  @override
  void initState() {
    super.initState();
    ClipboardEvents.instance?.registerPasteEventListener(_onPasteEvent);
  }

  @override
  void dispose() {
    super.dispose();
    ClipboardEvents.instance?.unregisterPasteEventListener(_onPasteEvent);
  }

```

--------------------------------

### Install Rust on macOS/Linux

Source: https://pub.dev/packages/super_clipboard

Installs Rust using the official script for macOS and Linux systems. This is a prerequisite for compiling the Rust components of the super_clipboard package from source.

```bash
curl --proto '=https' --tlsv1.2 -sSf https://sh.rustup.rs | sh

```

--------------------------------

### Example Widget with Clipboard Operations

Source: https://pub.dev/packages/super_clipboard/versions/0.9.0-dev.3/example

This widget demonstrates various ways to interact with the system clipboard, including copying and pasting text, images, and custom data. It also shows how to handle cases where the clipboard might not be available.

```dart
  @override
  Widget build(BuildContext context) {
    return Scaffold(
      appBar: AppBar(
        title: Text(widget.title),
      ),
      body: HomeLayout(
        mainContent: contentWidgets
            .intersperse(const SizedBox(height: 10))
            .toList(growable: false),
        buttons: [
          OutlinedButton(
            onPressed: copyText,
            child: const Text('Copy Text'),
          ),
          OutlinedButton(
              onPressed: copyTextLazy, child: const Text('Copy Text - Lazy')),
          OutlinedButton(onPressed: copyImage, child: const Text('Copy Image')),
          OutlinedButton(
              onPressed: copyImageLazy, child: const Text('Copy Image - Lazy')),
          OutlinedButton(onPressed: copyCustomData, child: const Text('Copy Customെടു')),
          OutlinedButton(
              onPressed: copyCustomDataLazy,
              child: const Text('Copy Custom - Lazy')),
          OutlinedButton(onPressed: copyUri, child: const Text('Copy URI')),
          OutlinedButton(
              onPressed: () async {
                final clipboard = SystemClipboard.instance;
                if (clipboard != null) {
                  final reader = await clipboard.read();
                  _paste(reader);
                } else {
                  showMessage(_notAvailableMessage);
                }
              },
              style: OutlinedButton.styleFrom(
                backgroundColor: Colors.blue.shade600,
                foregroundColor: Colors.white,
              ),
              child: const Text('Paste')),
        ],
      ),
    );
  }
}
```

--------------------------------

### MyApp Widget Setup

Source: https://pub.dev/packages/super_clipboard/versions/0.9.0-dev.6/example

Configures the root widget of the application, setting up the MaterialApp with a custom theme, including SnackBar and OutlinedButton themes. It defines the basic structure for the application's UI.

```dart
class MyApp extends StatelessWidget {
  const MyApp({super.key});

  // This widget is the root of your application.
  @override
  Widget build(BuildContext context) {
    return MaterialApp(
      title: 'SuperClipboard Example',
      theme: ThemeData(
        snackBarTheme: const SnackBarThemeData(
          behavior: SnackBarBehavior.floating,
        ),
        outlinedButtonTheme: OutlinedButtonThemeData(
          style: OutlinedButton.styleFrom(
              padding:
                  const EdgeInsets.symmetric(horizontal: 10, vertical: 16)),
        ),
        primarySwatch: Colors.blue,
        useMaterial3: false,
      ),
      home: const MyHomePage(title: 'SuperClipboard Example'),
    );
  }
}
```

--------------------------------

### Import super_clipboard in Dart

Source: https://pub.dev/packages/super_clipboard/versions/0.9.0/install

Import the super_clipboard package into your Dart files to start using its functionalities.

```dart
import 'package:super_clipboard/super_clipboard.dart';
```

--------------------------------

### Update Rust Installation

Source: https://pub.dev/packages/super_clipboard

Updates an existing Rust installation to the latest version. This ensures compatibility and access to the newest features required by the super_clipboard package.

```bash
rustup update

```

--------------------------------

### Initialize and Run Flutter App

Source: https://pub.dev/packages/super_clipboard/versions/0.9.0-dev.6/example

Sets up the main entry point for the Flutter application and initializes the MyApp widget. This is standard Flutter boilerplate.

```dart
void main() async {
  runApp(const MyApp());
}
```

--------------------------------

### Flutter App Initialization with Super Clipboard

Source: https://pub.dev/packages/super_clipboard/example

Sets up the main application widget and initializes clipboard event listeners. Ensure ClipboardEvents.instance is available on the platform.

```dart
import 'dart:ui' as ui;
import 'dart:typed_data';

import 'package:flutter/material.dart';
import 'package:flutter/rendering.dart';
import 'package:super_clipboard/super_clipboard.dart';
import 'package:flutter_layout_grid/flutter_layout_grid.dart';

import 'widget_for_reader.dart';

void main() async {
  runApp(const MyApp());
}

const _notAvailableMessage =
    'Clipboard is not available on this platform. Use ClipboardEvents API instead.';

class MyApp extends StatelessWidget {
  const MyApp({super.key});

  // This widget is the root of your application.
  @override
  Widget build(BuildContext context) {
    return MaterialApp(
      title: 'SuperClipboard Example',
      theme: ThemeData(
        snackBarTheme: const SnackBarThemeData(
          behavior: SnackBarBehavior.floating,
        ),
        outlinedButtonTheme: OutlinedButtonThemeData(
          style: OutlinedButton.styleFrom(
              padding:
                  const EdgeInsets.symmetric(horizontal: 10, vertical: 16)),
        ),
        primarySwatch: Colors.blue,
        useMaterial3: false,
      ),
      home: const MyHomePage(title: 'SuperClipboard Example'),
    );
  }
}

class Expand extends SingleChildRenderObjectWidget {
  const Expand({super.key, required super.child});

  @override
  RenderObject createRenderObject(BuildContext context) => _RenderExpanded();
}

class _RenderExpanded extends RenderProxyBox {
  @override
  void layout(Constraints constraints, {bool parentUsesSize = false}) {
    final boxConstraints = constraints as BoxConstraints;
    super.layout(
        boxConstraints.tighten(
          width: boxConstraints.maxWidth,
          height: boxConstraints.maxHeight,
        ),
        parentUsesSize: parentUsesSize);
  }
}

class HomeLayout extends StatelessWidget {
  const HomeLayout({
    super.key,
    required this.mainContent,
    required this.buttons,
  });

  final List<Widget> mainContent;
  final List<Widget> buttons;

  @override
  Widget build(BuildContext context) {
    return LayoutBuilder(builder: (context, constraints) {
      if (constraints.maxWidth < 540) {
        return ListView(
          padding: const EdgeInsets.all(16),
          children: [
            LayoutGrid(
              autoPlacement: AutoPlacement.rowDense,
              columnSizes: [1.5.fr, 2.fr],
              rowSizes: const [auto, auto, auto, auto],
              gridFit: GridFit.expand,
              rowGap: 10,
              columnGap: 10,
              children: buttons.map((e) => Expand(child: e)).toList(),
            ),
            const SizedBox(height: 16),
            ...mainContent,
          ],
        );
      } else {
        return Row(
          crossAxisAlignment: CrossAxisAlignment.stretch,
          children: [
            SingleChildScrollView(
              child: Padding(
                padding: const EdgeInsets.all(16),
                child: IntrinsicWidth(
                  child: Column(
                    crossAxisAlignment: CrossAxisAlignment.stretch,
                    children:
                        buttons.intersperse(const SizedBox(height: 10)).toList(growable: false),
                  ),
                ),
              ),
            ),
            VerticalDivider(
              color: Colors.blueGrey.shade100,
              thickness: 1,
              width: 1,
            ),
            Expanded(
              child: ListView(
                padding: const EdgeInsets.all(16),
                children: mainContent,
              ),
            )
          ],
        );
      }
    });
  }
}

class MyHomePage extends StatefulWidget {
  const MyHomePage({super.key, required this.title});

  final String title;

  @override
  State<MyHomePage> createState() => _MyHomePageState();
}

class _MyHomePageState extends State<MyHomePage>
    with SingleTickerProviderStateMixin {
  void showMessage(String message) {
    ScaffoldMessenger.of(context).showSnackBar(
      SnackBar(
        content: Text(message),
        duration: const Duration(milliseconds: 1500),
      ),
    );
  }

  @override
  void initState() {
    super.initState();
    ClipboardEvents.instance?.registerPasteEventListener(_onPasteEvent);
  }

  @override
  void dispose() {
    super.dispose();
    ClipboardEvents.instance?.unregisterPasteEventListener(_onPasteEvent);
  }

```

--------------------------------

### Handle Clipboard Paste Event

Source: https://pub.dev/packages/super_clipboard/versions/0.9.0-dev.1/example

Processes a clipboard paste event by getting the clipboard reader and then parsing its items into reader information. This is typically called when the user pastes content.

```dart
void _onPasteEvent(ClipboardReadEvent event) async {
    _paste(await event.getClipboardReader());
  }
```

--------------------------------

### Build Method with Clipboard Actions

Source: https://pub.dev/packages/super_clipboard/versions/0.9.0-dev.1/example

This method builds the UI for the home page, including buttons to trigger various clipboard operations such as copying text, images, custom data, and URIs, as well as pasting content. It demonstrates how to integrate with the SystemClipboard instance.

```dart
  @override
  Widget build(BuildContext context) {
    return Scaffold(
      appBar: AppBar(
        title: Text(widget.title),
      ),
      body: HomeLayout(
        mainContent: contentWidgets
            .intersperse(const SizedBox(height: 10))
            .toList(growable: false),
        buttons: [
          OutlinedButton(
            onPressed: copyText,
            child: const Text('Copy Text'),
          ),
          OutlinedButton(
              onPressed: copyTextLazy, child: const Text('Copy Text - Lazy')),
          OutlinedButton(onPressed: copyImage, child: const Text('Copy Image')),
          OutlinedButton(
              onPressed: copyImageLazy, child: const Text('Copy Image - Lazy')),
          OutlinedButton(
              onPressed: copyCustomData, child: const Text('Copy Custom')),
          OutlinedButton(
              onPressed: copyCustomDataLazy,
              child: const Text('Copy Custom - Lazy')),
          OutlinedButton(onPressed: copyUri, child: const Text('Copy URI')),
          OutlinedButton(
              onPressed: () async {
                final clipboard = SystemClipboard.instance;
                if (clipboard != null) {
                  final reader = await clipboard.read();
                  _paste(reader);
                } else {
                  showMessage(_notAvailableMessage);
                }
              },
              style: OutlinedButton.styleFrom(
                backgroundColor: Colors.blue.shade600,
                foregroundColor: Colors.white,
              ),
              child: const Text('Paste')),
        ],
      ),
    );
  }
}
```

--------------------------------

### Flutter App Initialization with Super Clipboard

Source: https://pub.dev/packages/super_clipboard/versions/0.9.0/example

Sets up the main Flutter application and registers paste event listeners. Ensures the clipboard is accessible and handles platform availability.

```dart
import 'dart:ui' as ui;
import 'dart:typed_data';

import 'package:flutter/material.dart';
import 'package:flutter/rendering.dart';
import 'package:super_clipboard/super_clipboard.dart';
import 'package:flutter_layout_grid/flutter_layout_grid.dart';

import 'widget_for_reader.dart';

void main() async {
  runApp(const MyApp());
}

const _notAvailableMessage =
    'Clipboard is not available on this platform. Use ClipboardEvents API instead.';

class MyApp extends StatelessWidget {
  const MyApp({super.key});

  // This widget is the root of your application.
  @override
  Widget build(BuildContext context) {
    return MaterialApp(
      title: 'SuperClipboard Example',
      theme: ThemeData(
        snackBarTheme: const SnackBarThemeData(
          behavior: SnackBarBehavior.floating,
        ),
        outlinedButtonTheme: OutlinedButtonThemeData(
          style: OutlinedButton.styleFrom(
              padding:
                  const EdgeInsets.symmetric(horizontal: 10, vertical: 16)),
        ),
        primarySwatch: Colors.blue,
        useMaterial3: false,
      ),
      home: const MyHomePage(title: 'SuperClipboard Example'),
    );
  }
}

class Expand extends SingleChildRenderObjectWidget {
  const Expand({super.key, required super.child});

  @override
  RenderObject createRenderObject(BuildContext context) => _RenderExpanded();
}

class _RenderExpanded extends RenderProxyBox {
  @override
  void layout(Constraints constraints, {bool parentUsesSize = false}) {
    final boxConstraints = constraints as BoxConstraints;
    super.layout(
        boxConstraints.tighten(
          width: boxConstraints.maxWidth,
          height: boxConstraints.maxHeight,
        ),
        parentUsesSize: parentUsesSize);
  }
}

class HomeLayout extends StatelessWidget {
  const HomeLayout({
    super.key,
    required this.mainContent,
    required this.buttons,
  });

  final List<Widget> mainContent;
  final List<Widget> buttons;

  @override
  Widget build(BuildContext context) {
    return LayoutBuilder(builder: (context, constraints) {
      if (constraints.maxWidth < 540) {
        return ListView(
          padding: const EdgeInsets.all(16),
          children: [
            LayoutGrid(
              autoPlacement: AutoPlacement.rowDense,
              columnSizes: [1.5.fr, 2.fr],
              rowSizes: const [auto, auto, auto, auto],
              gridFit: GridFit.expand,
              rowGap: 10,
              columnGap: 10,
              children: buttons.map((e) => Expand(child: e)).toList(),
            ),
            const SizedBox(height: 16),
            ...mainContent,
          ],
        );
      } else {
        return Row(
          crossAxisAlignment: CrossAxisAlignment.stretch,
          children: [
            SingleChildScrollView(
              child: Padding(
                padding: const EdgeInsets.all(16),
                child: IntrinsicWidth(
                  child: Column(
                    crossAxisAlignment: CrossAxisAlignment.stretch,
                    children: buttons
                        .intersperse(const SizedBox(height: 10))
                        .toList(growable: false),
                  ),
                ),
              ),
            ),
            VerticalDivider(
              color: Colors.blueGrey.shade100,
              thickness: 1,
              width: 1,
            ),
            Expanded(
              child: ListView(
                padding: const EdgeInsets.all(16),
                children: mainContent,
              ),
            )
          ],
        );
      }
    });
  }
}

class MyHomePage extends StatefulWidget {
  const MyHomePage({super.key, required this.title});

  final String title;

  @override
  State<MyHomePage> createState() => _MyHomePageState();
}

class _MyHomePageState extends State<MyHomePage>
    with SingleTickerProviderStateMixin {
  void showMessage(String message) {
    ScaffoldMessenger.of(context).showSnackBar(
      SnackBar(
        content: Text(message),
        duration: const Duration(milliseconds: 1500),
      ),
    );
  }

  @override
  void initState() {
    super.initState();
    ClipboardEvents.instance?.registerPasteEventListener(_onPasteEvent);
  }

  @override
  void dispose() {
    super.dispose();
    ClipboardEvents.instance?.unregisterPasteEventListener(_onPasteEvent);
  }

```

--------------------------------

### Reading from Clipboard

Source: https://pub.dev/packages/super_clipboard

Demonstrates how to read various data formats (HTML, plain text, images) from the system clipboard. It also shows how to check for format availability and handle binary data as streams.

```APIDOC
## Reading from Clipboard

### Description
Reads data from the system clipboard. Supports various formats including HTML, plain text, and binary formats like PNG. Checks for format availability before reading.

### Method
`SystemClipboard.instance.read()`

### Parameters
None

### Response
Returns a `ClipboardReader` object which can be used to read data.

#### `ClipboardReader.canProvide(format)`
- **format** (String) - The format to check for (e.g., `Formats.htmlText`, `Formats.plainText`, `Formats.png`).
- Returns `true` if the format is available, `false` otherwise.

#### `ClipboardReader.readValue(format)`
- **format** (String) - The format to read.
- Returns the value of the requested format.

#### `ClipboardReader.getFile(format, callback)`
- **format** (String) - The format to read (typically binary formats like `Formats.png`).
- **callback** (Function) - A callback function that receives a `File` object.
  - The `File` object has a `getStream()` method to access the binary data.

### Example
```dart
import 'package:super_clipboard/super_clipboard.dart';

final clipboard = SystemClipboard.instance;
if (clipboard == null) {
    return; // Clipboard API is not supported on this platform.
}
final reader = await clipboard.read();

if (reader.canProvide(Formats.htmlText)) {
    final html = await reader.readValue(Formats.htmlText);
    // .. do something with the HTML text
}

if (reader.canProvide(Formats.plainText)) {
    final text = await reader.readValue(Formats.plainText);
    // Do something with the plain text
}

if (reader.canProvide(Formats.png)) {
    reader.getFile(Formats.png, (file) {
        // Do something with the PNG image
        final stream = file.getStream();
    });
}
```
```

--------------------------------

### Writing to Clipboard

Source: https://pub.dev/packages/super_clipboard

Illustrates how to write data to the system clipboard. Supports adding data directly or using lazy callbacks for on-demand data provision. Covers common formats and considerations for multiple items.

```APIDOC
## Writing to Clipboard

### Description
Writes data to the system clipboard. Data can be provided directly or lazily. Supports various formats and offers considerations for writing multiple items.

### Method
`SystemClipboard.instance.write(List<DataWriterItem>)`

### Parameters
- **items** (List<DataWriterItem>) - A list of `DataWriterItem` objects to write to the clipboard.

#### `DataWriterItem.add(format, value)`
- **format** (String) - The format of the data (e.g., `Formats.htmlText`, `Formats.plainText`, `Formats.png`).
- **value** - The data to be written.

#### `DataWriterItem.addLazy(format, callback)`
- **format** (String) - The format of the data.
- **callback** (Function) - A function that returns the data when requested. Should execute quickly.

### Request Example (Direct Data)
```dart
import 'package:super_clipboard/super_clipboard.dart';

final clipboard = SystemClipboard.instance;
if (clipboard == null) {
    return; // Clipboard API is not supported on this platform.
}
final item = DataWriterItem();
item.add(Formats.htmlText('<b>HTML text</b>'));
item.add(Formats.plainText('plain text'));
item.add(Formats.png(imageData)); // imageData should be Uint8List
await clipboard.write([item]);
```

### Request Example (Lazy Data)
```dart
import 'package:super_clipboard/super_clipboard.dart';

final clipboard = SystemClipboard.instance;
if (clipboard == null) {
    return; // Clipboard API is not supported on this platform.
}
final item = DataWriterItem();
item.add(Formats.htmlText.lazy(() => '<b>HTML text</b>'));
item.add(Formats.plainText.lazy(() => 'plain text'));
item.add(Formats.png.lazy(() => imageData)); // imageData should be Uint8List
await clipboard.write([item]);
```

### Considerations
- **Image Format**: PNG is the preferred format for images.
- **Multiple Items**: Platform support for multiple clipboard items varies. On Windows, only `Formats.fileUri` is supported for additional items. On Linux, `Formats.uri` and `Formats.fileUri` are supported for additional items.
```

--------------------------------

### Reading from Clipboard

Source: https://pub.dev/packages/super_clipboard/versions/0.9.1

Demonstrates how to read data from the system clipboard. It checks for the availability of the clipboard, reads available formats (HTML, plain text, PNG), and provides methods to access the data as strings or streams.

```APIDOC
## Reading from Clipboard

### Description
Reads data from the system clipboard, supporting various formats like HTML, plain text, and images (PNG).

### Method
`SystemClipboard.instance.read()`

### Parameters
None

### Response
Returns a `ClipboardReader` object which can be used to check for and retrieve data in different formats.

#### Success Response
- `ClipboardReader` object

### Request Example
```dart
import 'package:super_clipboard/super_clipboard.dart';

final clipboard = SystemClipboard.instance;
if (clipboard == null) {
    return; // Clipboard API is not supported on this platform.
}
final reader = await clipboard.read();

if (reader.canProvide(Formats.htmlText)) {
    final html = await reader.readValue(Formats.htmlText);
    // .. do something with the HTML text
}

if (reader.canProvide(Formats.plainText)) {
    final text = await reader.readValue(Formats.plainText);
    // Do something with the plain text
}

/// Binary formats need to be read as streams
if (reader.canProvide(Formats.png)) {
    reader.getFile(Formats.png, (file) {
        // Do something with the PNG image
        final stream = file.getStream();
    });
}
```
```

--------------------------------

### Writing to Clipboard

Source: https://pub.dev/packages/super_clipboard/versions/0.9.0-dev.6

Illustrates how to write data to the system clipboard. Supports adding various data types, including HTML, plain text, and images, either directly or lazily.

```APIDOC
## Writing to Clipboard

### Description
Writes data to the system clipboard. Data can be provided directly or lazily, and supports multiple items with platform-specific limitations.

### Method
`SystemClipboard.instance.write(List<DataWriterItem>)`

### Usage (Direct Data)
```dart
import 'package:super_clipboard/super_clipboard.dart';

final clipboard = SystemClipboard.instance;
if (clipboard == null) {
    return; // Clipboard API is not supported on this platform.
}
final item = DataWriterItem();
item.add(Formats.htmlText('<b>HTML text</b>'));
item.add(Formats.plainText('plain text'));
item.add(Formats.png(imageData));
await clipboard.write([item]);
```

### Usage (Lazy Data)
```dart
import 'package:super_clipboard/super_clipboard.dart';

final item = DataWriterItem();
item.add(Formats.htmlText.lazy(() => '<b>HTML text</b>'));
item.add(Formats.plainText.lazy(() => 'plain text'));
item.add(Formats.png.lazy(() => imageData));
await clipboard.write([item]);
```

### Considerations for Lazy Data
Ensure lazy callbacks provide data without unnecessary delay, as they might be called on the main thread. Avoid long-running operations within lazy callbacks. Use `DataWriterItem.addVirtualFile` for copying or dragging files not readily available.

### Image Format
PNG is the preferred format for images. Platforms like Windows will convert PNGs to DIB/DIBv5 formats natively.

### Multi-Item Support
While the API supports multiple items, platform support varies. Windows and Linux have specific format limitations for additional items (e.g., `Formats.fileUri`, `Formats.uri`).
```

--------------------------------

### Build Method with Clipboard Operations

Source: https://pub.dev/packages/super_clipboard/versions/0.9.0-dev.2/example

This method builds the UI for the home page, including buttons for various clipboard operations such as copying and pasting text, images, and custom data. It also includes a button to paste content from the clipboard.

```dart
  @override
  Widget build(BuildContext context) {
    return Scaffold(
      appBar: AppBar(
        title: Text(widget.title),
      ),
      body: HomeLayout(
        mainContent: contentWidgets
            .intersperse(const SizedBox(height: 10))
            .toList(growable: false),
        buttons: [
          OutlinedButton(
            onPressed: copyText,
            child: const Text('Copy Text'),
          ),
          OutlinedButton(
              onPressed: copyTextLazy, child: const Text('Copy Text - Lazy')),
          OutlinedButton(onPressed: copyImage, child: const Text('Copy Image')),
          OutlinedButton(
              onPressed: copyImageLazy, child: const Text('Copy Image - Lazy')),
          OutlinedButton(
              onPressed: copyCustomData, child: const Text('Copy Customെടു')),
          OutlinedButton(
              onPressed: copyCustomDataLazy,
              child: const Text('Copy Custom - Lazy')),
          OutlinedButton(onPressed: copyUri, child: const Text('Copy URI')),
          OutlinedButton(
              onPressed: () async {
                final clipboard = SystemClipboard.instance;
                if (clipboard != null) {
                  final reader = await clipboard.read();
                  _paste(reader);
                } else {
                  showMessage(_notAvailableMessage);
                }
              },
              style: OutlinedButton.styleFrom(
                backgroundColor: Colors.blue.shade600,
                foregroundColor: Colors.white,
              ),
              child: const Text('Pasteെടു')),
        ],
      ),
    );
  }
}
```

--------------------------------

### Build Method with Clipboard Operations

Source: https://pub.dev/packages/super_clipboard/versions/0.9.0/example

This widget builds the UI for the home page, including buttons to trigger various clipboard operations like copying text, images, custom data, and URIs, as well as pasting content.

```dart
  @override
  Widget build(BuildContext context) {
    return Scaffold(
      appBar: AppBar(
        title: Text(widget.title),
      ),
      body: HomeLayout(
        mainContent: contentWidgets
            .intersperse(const SizedBox(height: 10))
            .toList(growable: false),
        buttons: [
          OutlinedButton(
            onPressed: copyText,
            child: const Text('Copy Text'),
          ),
          OutlinedButton(
              onPressed: copyTextLazy, child: const Text('Copy Text - Lazy')),
          OutlinedButton(onPressed: copyImage, child: const Text('Copy Image')),
          OutlinedButton(
              onPressed: copyImageLazy, child: const Text('Copy Image - Lazy')),
          OutlinedButton(onPressed: copyCustomData, child: const Text('Copy Custom')),
          OutlinedButton(
              onPressed: copyCustomDataLazy,
              child: const Text('Copy Custom - Lazy')),
          OutlinedButton(onPressed: copyUri, child: const Text('Copy URI')),
          OutlinedButton(
              onPressed: () async {
                final clipboard = SystemClipboard.instance;
                if (clipboard != null) {
                  final reader = await clipboard.read();
                  _paste(reader);
                } else {
                  showMessage(_notAvailableMessage);
                }
              },
              style: OutlinedButton.styleFrom(
                backgroundColor: Colors.blue.shade600,
                foregroundColor: Colors.white,
              ),
              child: const Text('Paste')),
        ],
      ),
    );
  }
}
```

--------------------------------

### super_clipboard pubspec.yaml Entry

Source: https://pub.dev/packages/super_clipboard/versions/0.9.0/install

This is how the super_clipboard dependency will appear in your pubspec.yaml file after running the add command.

```yaml
dependencies:
  super_clipboard: ^0.9.0
```

--------------------------------

### Copy Plain Text and HTML to Clipboard

Source: https://pub.dev/packages/super_clipboard/versions/0.9.0-dev.1/example

Copies both plain text and HTML formatted text to the system clipboard. Ensure the SystemClipboard instance is available before attempting to write.

```dart
void copyText() async {
    final clipboard = SystemClipboard.instance;
    if (clipboard != null) {
      final item = DataWriterItem();
      item.add(Formats.htmlText('<b>This is a <em>HTML</en> value</b>.'));
      item.add(Formats.plainText('This is a plaintext value.'));
      await clipboard.write([item]);
    } else {
      showMessage(_notAvailableMessage);
    }
  }
```

--------------------------------

### Responsive Home Layout

Source: https://pub.dev/packages/super_clipboard/versions/0.9.0-dev.6/example

Manages the layout of the home page, adapting to different screen widths. On smaller screens, it uses a ListView with a grid for buttons; on larger screens, it uses a Row with a sidebar for buttons and a main content area.

```dart
class HomeLayout extends StatelessWidget {
  const HomeLayout({
    super.key,
    required this.mainContent,
    required this.buttons,
  });

  final List<Widget> mainContent;
  final List<Widget> buttons;

  @override
  Widget build(BuildContext context) {
    return LayoutBuilder(builder: (context, constraints) {
      if (constraints.maxWidth < 540) {
        return ListView(
          padding: const EdgeInsets.all(16),
          children: [
            LayoutGrid(
              autoPlacement: AutoPlacement.rowDense,
              columnSizes: [1.5.fr, 2.fr],
              rowSizes: const [auto, auto, auto, auto],
              gridFit: GridFit.expand,
              rowGap: 10,
              columnGap: 10,
              children: buttons.map((e) => Expand(child: e)).toList(),
            ),
            const SizedBox(height: 16),
            ...mainContent,
          ],
        );
      } else {
        return Row(
          crossAxisAlignment: CrossAxisAlignment.stretch,
          children: [
            SingleChildScrollView(
              child: Padding(
                padding: const EdgeInsets.all(16),
                child: IntrinsicWidth(
                  child: Column(
                    crossAxisAlignment: CrossAxisAlignment.stretch,
                    children: buttons
                        .intersperse(const SizedBox(height: 10))
                        .toList(growable: false),
                  ),
                ),
              ),
            ),
            VerticalDivider(
              color: Colors.blueGrey.shade100,
              thickness: 1,
              width: 1,
            ),
            Expanded(
              child: ListView(
                padding: const EdgeInsets.all(16),
                children: mainContent,
              ),
            )
          ],
        );
      }
    });
  }
}
```

--------------------------------

### Add super_clipboard to Dart Project

Source: https://pub.dev/packages/super_clipboard/versions/0.9.0-dev.1/install

Use this command to add the super_clipboard package as a dependency in your Dart project.

```bash
$ dart pub add super_clipboard
```

--------------------------------

### Create PNG Image Data for Clipboard

Source: https://pub.dev/packages/super_clipboard/example

This function generates a PNG image with a specified color and dimensions, returning it as a Uint8List. It's useful for preparing image data to be copied to the clipboard.

```Dart
Future<Uint8List> createImageData(Color color) async {
  final recorder = ui.PictureRecorder();
  final Canvas canvas = Canvas(recorder);
  final Paint paint = Paint()..color = color;
  canvas.drawOval(const Rect.fromLTWH(0, 0, 200, 200), paint);
  final picture = recorder.endRecording();
  final image = await picture.toImage(200, 200);
  final data = await image.toByteData(format: ui.ImageByteFormat.png);
  return data!.buffer.asUint8List();
}
```

--------------------------------

### Copy URI to Clipboard

Source: https://pub.dev/packages/super_clipboard/versions/0.9.0-dev.1/example

Copies a URI along with an optional name to the system clipboard. This is useful for sharing web links or file paths.

```dart
void copyUri() async {
    final clipboard = SystemClipboard.instance;
    if (clipboard != null) {
      final item = DataWriterItem();
      item.add(Formats.uri(NamedUri(
          Uri.parse('https://github.com/superlistapp/super_native_extensions'),
          name: 'Super Native Extensions')));
      await clipboard.write([item]);
    } else {
      showMessage(_notAvailableMessage);
    }
  }
```

--------------------------------

### Copy Custom Data to Clipboard

Source: https://pub.dev/packages/super_clipboard/versions/0.9.0-dev.1/example

Copies custom binary data (Uint8List) to the system clipboard. This requires a custom format to be defined.

```dart
void copyCustomData() async {
    final clipboard = SystemClipboard.instance;
    if (clipboard != null) {
      final item = DataWriterItem();
      item.add(formatCustom(Uint8List.fromList([1, 2, 3, 4])));
      await clipboard.write([item]);
    } else {
      showMessage(_notAvailableMessage);
    }
  }
```

--------------------------------

### Copy Image to Clipboard

Source: https://pub.dev/packages/super_clipboard/versions/0.9.0-dev.1/example

Copies an image (represented as a Uint8List) to the system clipboard. A suggested file name can be provided.

```dart
void copyImage() async {
    final clipboard = SystemClipboard.instance;
    if (clipboard != null) {
      final image = await createImageData(Colors.red);
      final item = DataWriterItem(suggestedName: 'RedCircle.png');
      item.add(Formats.png(image));
      await clipboard.write([item]);
    } else {
      showMessage(_notAvailableMessage);
    }
  }
```

--------------------------------

### Flutter UI with Clipboard Actions

Source: https://pub.dev/packages/super_clipboard/versions/0.9.0-dev.6/example

This widget demonstrates various buttons to interact with the clipboard, including copying text, images, custom data, and URIs, as well as pasting content. It shows how to integrate clipboard operations into a Flutter UI.

```dart
Scaffold(
      appBar: AppBar(
        title: Text(widget.title),
      ),
      body: HomeLayout(
        mainContent: contentWidgets
            .intersperse(const SizedBox(height: 10))
            .toList(growable: false),
        buttons: [
          OutlinedButton(onPressed: copyText, child: const Text('Copy Text')),
          OutlinedButton(
              onPressed: copyTextLazy, child: const Text('Copy Text - Lazy')),
          OutlinedButton(onPressed: copyImage, child: const Text('Copy Image')),
          OutlinedButton(
              onPressed: copyImageLazy, child: const Text('Copy Image - Lazy')),
          OutlinedButton(
              onPressed: copyCustomData, child: const Text('Copy Custom')),
          OutlinedButton(
              onPressed: copyCustomDataLazy,
              child: const Text('Copy Custom - Lazy')),
          OutlinedButton(onPressed: copyUri, child: const Text('Copy URI')),
          OutlinedButton(
              onPressed: () async {
                final clipboard = SystemClipboard.instance;
                if (clipboard != null) {
                  final reader = await clipboard.read();
                  _paste(reader);
                } else {
                  showMessage(_notAvailableMessage);
                }
              },
              style: OutlinedButton.styleFrom(
                backgroundColor: Colors.blue.shade600,
                foregroundColor: Colors.white,
              ),
              child: const Text('Paste')),
        ],
      ),
    )
```

--------------------------------

### Add super_clipboard Dependency

Source: https://pub.dev/packages/super_clipboard/versions/0.9.0/install

Use this command to add the super_clipboard package to your Flutter project. This command automatically updates your pubspec.yaml file.

```bash
flutter pub add super_clipboard
```

--------------------------------

### MIT License for super_clipboard

Source: https://pub.dev/packages/super_clipboard/license

This is the MIT license text for the super_clipboard package. It grants broad permissions for use, modification, and distribution.

```text
Copyright (c) 2022 Superlist, Matej Knopp and the contributors

MIT LICENSE

Permission is hereby granted, free of charge, to any person obtaining a copy
of this software and associated documentation files (the "Software"), to deal
in the Software without restriction, including without limitation the rights
to use, copy, modify, merge, publish, distribute, sublicense, and/or sell copies
of the Software, and to permit persons to whom the Software is furnished to do
so, subject to the following conditions:

The above copyright notice and this permission notice shall be included in all
copies or substantial portions of the Software.

THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY, FITNESS
FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE AUTHORS
OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER LIABILITY,
WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM, OUT OF OR
IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE SOFTWARE.

```

--------------------------------

### Declare Content Provider for Android

Source: https://pub.dev/packages/super_clipboard

Declares a content provider in the AndroidManifest.xml file. This is required for writing images and custom data formats to the Android clipboard using super_clipboard.

```xml
<manifest>
    <application>
        ...
        <provider
            android:name="com.superlist.super_native_extensions.DataProvider"
            android:authorities="<your-package-name>.SuperClipboardDataProvider"
            android:exported="true"
            android:grantUriPermissions="true" >
        </provider>
        ...
    </application>
</manifest>

```

--------------------------------

### Write Data to Clipboard

Source: https://pub.dev/packages/super_clipboard/versions/0.9.0-dev.6

Writes data to the system clipboard, supporting multiple formats like HTML, plain text, and PNG. Ensure the clipboard API is supported on the platform.

```dart
    import 'package:super_clipboard/super_clipboard.dart';

    // ...

    final clipboard = SystemClipboard.instance;
    if (clipboard == null) {
        return; // Clipboard API is not supported on this platform.
    }
    final item = DataWriterItem();
    item.add(Formats.htmlText('<b>HTML text</b>'));
    item.add(Formats.plainText('plain text'));
    item.add(Formats.png(imageData));
    await clipboard.write([item]);

```

--------------------------------

### MyHomePage State Management

Source: https://pub.dev/packages/super_clipboard/versions/0.9.0-dev.6/example

Manages the state for the home page, including displaying snack bar messages and registering/unregistering paste event listeners. It ensures proper cleanup of listeners when the widget is disposed.

```dart
class MyHomePage extends StatefulWidget {
  const MyHomePage({super.key, required this.title});

  final String title;

  @override
  State<MyHomePage> createState() => _MyHomePageState();
}

class _MyHomePageState extends State<MyHomePage>
    with SingleTickerProviderStateMixin {
  void showMessage(String message) {
    ScaffoldMessenger.of(context).showSnackBar(
      SnackBar(
        content: Text(message),
        duration: const Duration(milliseconds: 1500),
      ),
    );
  }

  @override
  void initState() {
    super.initState();
    ClipboardEvents.instance?.registerPasteEventListener(_onPasteEvent);
  }

  @override
  void dispose() {
    super.dispose();
    ClipboardEvents.instance?.unregisterPasteEventListener(_onPasteEvent);
  }
}
```

--------------------------------

### Read Data from Clipboard

Source: https://pub.dev/packages/super_clipboard/versions/0.9.0-dev.6

Reads data from the system clipboard, checking for supported formats like HTML, plain text, and PNG images. Requires checking for platform support of the clipboard API.

```dart
    import 'package:super_clipboard/super_clipboard.dart';

    // ...

    final clipboard = SystemClipboard.instance;
    if (clipboard == null) {
        return; // Clipboard API is not supported on this platform.
    }
    final reader = await clipboard.read();

    if (reader.canProvide(Formats.htmlText)) {
        final html = await reader.readValue(Formats.htmlText);
        // .. do something with the HTML text
    }

    if (reader.canProvide(Formats.plainText)) {
        final text = await reader.readValue(Formats.plainText);
        // Do something with the plain text
    }

    /// Binary formats need to be read as streams
    if (reader.canProvide(Formats.png)) {
        reader.getFile(Formats.png, (file) {
            // Do something with the PNG image
            final stream = file.getStream();
        });
    }

```

--------------------------------

### Registering Clipboard Event Listeners on Web

Source: https://pub.dev/packages/super_clipboard

This snippet demonstrates how to register listeners for paste and copy events using the ClipboardEvents API. It shows how to access clipboard data, including HTML and plain text, during a paste event and how to write data to the clipboard during a copy event. Note that clipboard events are only supported on web platforms.

```dart
   final events = ClipboardEvents.instance;
   if (events == null) {
     // Clipboard events are only supported on web.
     return;
   }

   events.registerPasteEventListener((event) async {
      // Requesting the clipboard reader will prevent the default paste action
      // such as inserting the text in editable element.
      final reader = await event.getClipboardReader();
      if (reader.canProvide(Formats.htmlText)) {
        final html = await event.clipboardReader.readValue(Formats.htmlText);
        // .. do something with the HTML text
      }
   });

   events.registerCopyEventListener((event) {
      // Calling the [write] method on event will prevent the default copy action
      // such as copying the selected text to clipboard.
      final item = DataWriterItem();
      item.add(Formats.htmlText('<b>HTML text</b>'));
      item.add(Formats.plainText('plain text'));
      await event.write([item]);
   });


```

--------------------------------

### Configure Android NDK Version

Source: https://pub.dev/packages/super_clipboard

Specifies the NDK version to be used in an Android Flutter project. This is crucial for the super_clipboard package's native Android functionality.

```gradle
android {
    // by default the project uses NDK version from flutter plugin.
    ndkVersion flutter.ndkVersion

```

--------------------------------

### Copy Lazy Custom Data to Clipboard

Source: https://pub.dev/packages/super_clipboard/versions/0.9.0-dev.1/example

Copies custom binary data to the clipboard with lazy generation. The data is created only when requested by the pasting application.

```dart
void copyCustomDataLazy() async {
    final clipboard = SystemClipboard.instance;
    if (clipboard != null) {
      final item = DataWriterItem();
      item.add(formatCustom.lazy(() async {
        showMessage('Lazy custom data requested.');
        return Uint8List.fromList([1, 2, 3, 4, 5, 6]);
      }));
      await clipboard.write([item]);
    } else {
      showMessage(_notAvailableMessage);
    }
  }
```

--------------------------------

### Write Data to Clipboard with Lazy Representations

Source: https://pub.dev/packages/super_clipboard/versions/0.9.0-dev.6

Writes data to the clipboard using lazy callbacks for on-demand data provision. Be mindful of potential main thread blocking if callbacks are slow.

```dart
    final item = DataWriterItem();
    item.add(Formats.htmlText.lazy(() => '<b>HTML text</b>'));
    item.add(Formats.plainText.lazy(() => 'plain text'));
    item.add(Formats.png.lazy(() => imageData));
    await clipboard.write([item]);

```

--------------------------------

### Set Minimum Android SDK Version

Source: https://pub.dev/packages/super_clipboard

Sets the minimum SDK version for an older Android Flutter project. A minimum of SDK 23 is recommended for compatibility with super_clipboard.

```gradle
android {
    defaultConfig {
        minSdkVersion 23

```
Tokens:
Raw