share

tape
@profile(t1);
import share from "share";
import ui from "ui";
import widgets from "widgets";
import io from "io";

fn send_photo() {
    share.file("photos/holiday.jpg", "Holiday photo") or {
        io.println("can't share here: {err}");
    };
}

component App {
    view {
        ui.Column { padding: 12;
            widgets.Button { label: "Share"; enabled: share.available(); on_click: send_photo; grow: 0; }
        }
    }
}

pub fn main() -> i32 {
    ui.run(App {}, 480, 320, "Photos") or { return 1; };
    return 0;
}

share.file(path, title) shows the system’s share sheet for one file, anchored to your ui window, so the user can hand it to mail, a chat app, AirDrop or whatever else the system offers. It returns as soon as the sheet is shown; it does not wait for the user’s choice. You are not told what the user picked, or whether they closed the sheet: Windows does not report a dismissed sheet, so there is no Cancelled.

FunctionDoes
share.available() -> boolWhether this platform has a share sheet (Windows 10 and later, macOS)
share.file(path: []const u8, title: []const u8) -> void or ShareErrorShows the sheet for the file at path
share.files(paths: []const []const u8, title: []const u8) -> void or ShareErrorShows one sheet for all the files at paths
share.MAX_FILESThe most files one sheet takes: 100

Call file from the ui loop (a handler, a timer) while ui.run has its window open: the sheet belongs to that window. A relative path is taken from the current directory. title heads the sheet on Windows; "" uses the file’s name. macOS shows no heading.

To share several files at once, pass them to files: one sheet offers them together (Mail attaches them all). file(path, title) is files with one path. Every path is checked before anything is shown, so a missing one shows no sheet at all. With several files a title of "" becomes “3 files”.

tape
fn send_trip() {
    let picked: [3][]const u8 = ["trip/1.jpg", "trip/2.jpg", "trip/notes.txt"];
    share.files(picked[0..3], "Trip") or {
        io.println("can't share them: {err}");
    };
}

Where available() is false, offer something else, such as opening the file’s folder.

Errors

ShareError:

VariantWhen
UnsupportedThis system has no share sheet (Linux, Uusi)
NotFoundThere is no file at path, or at one of paths (nothing there, or a folder)
FailedNo paths, more than MAX_FILES (100), the system refused, or ui.run has no window open

Platforms

  • Windows: the share sheet of Windows 10 and 11 (DataTransferManager) over your window, with the files and the title. The files are handed over read-only.
  • macOS: the sharing service picker (NSSharingServicePicker) with the files, at the middle of your window.
  • Linux: no share sheet. The desktop portal has none, and no desktop offers one of its own, so available() is false and file and files return Unsupported.

The library is shell100 (.dll, .dylib, .so), next to tape; tape build copies it beside your program.

Last modified: