Saving and opening drawings
A drawing is a document: its details (an ID, a name, its authors, when it was made, last opened and last changed), its size, the user's layers, drawings from other sources and a thumbnail. Undo history isn't kept.
const document = await canvas.createDocument(); // a DrawingDocument: images are PNG blobs
await canvas.openDocument(document); // false if it can't be opened
const json = JSON.stringify(await canvas.exportDocument()); // a DocumentFile: images are PNG data URLs
await canvas.importDocument(JSON.parse(json)); // false if the document isn't valid
- Document files match the document schema (
document-1.1.0.json,@typePaintCanvas/Document).documentToFileanddocumentFromFile(@lvl99dotcom/paintcanvas/lib/document) turn documents into files and back; files from before versioned schemas (format: "paintcanvas-document") are read too, with new details. canvas.documentInfohas the drawing's details.canvas.renameDocument(name)renames it, andcanvas.newDocument(name?)starts a new drawing with one empty layer.documentInfo.updatedAtis when the drawing was last changed: its layers' pixels or settings, their order, adding or deleting layers, the canvas size, or its name. Nothing is marked while the user draws: once a change is made, the canvas waits until the drawing has gone unchanged for 100 ms (MODIFIED_DEBOUNCE_MS, each change restarts the wait), then setsupdatedAtto that moment and dispatchesmodified(DOCUMENT_MODIFIED_EVENT).createDocument(),LayerAutosaveandRemoteDocumentAutosavemark a waiting change first (canvas.flushModified()), so none is missed.canvas.destroy()stops the wait. Selecting a layer, opening or restoring a drawing, other people's drawings, and being added as an author don't change it. A new drawing starts with itsdateCreated, and so does one opened from before documents had it.- The user (the
presetAuthoroption) starts a drawing's authors, and whoever saves it later (withcreateDocument) is added. - The thumbnail is the drawing as shown, at most
THUMBNAIL_SIZE(200) pixels on its longest side. Leave it out withcreateDocument({ thumbnail: false }).
Keeping the drawing in the browser
To keep the user's layers through a page reload, give the layout a store name. The layers are kept in the browser's IndexedDB under that name:
<paint-canvas store="my-drawing"></paint-canvas>
Or give the engine a store yourself:
import IndexedDbLayerStore from "@lvl99dotcom/paintcanvas/lib/storage";
canvas.useLayerStore(new IndexedDbLayerStore("my-drawing"));
// or: new PaintCanvas({ layerStore: new IndexedDbLayerStore("my-drawing") })
- The saved drawing is restored when the page opens: its details, the canvas size, each layer's settings and pixels, and the selected layer. Undo history isn't kept.
- Changes are saved soon after they're made (once drawing pauses), and straight away when the page is hidden or closed. Only layers whose pixels changed are saved again.
- Only one window draws on a drawing at a time. Another window or tab opening the same name is blocked by a message, "You are already drawing in another window", with a button to draw there instead (the first window is then blocked). When the first window closes, the other takes the drawing over the next time it's shown.
- If the saved drawing can't be loaded (e.g. it was saved by another version), saving stops so it isn't overwritten, and
pc-toasttells the user.canvas.autosave.store.clear()deletes it. - To start again with an empty drawing, use
canvas.newDocument(). The saved drawing follows.
canvas.autosave (a LayerAutosave) has the state (starting, elsewhere, ready or stopped) and dispatches change and error. To keep layers somewhere else (e.g. your server), pass your own store with the same methods as LayerStoreLike: load, save and clear. The test helpers include MemoryLayerStore (@lvl99dotcom/paintcanvas/testing/layerStore) and fake Web Locks (@lvl99dotcom/paintcanvas/testing/locks).
Keeping the drawing somewhere else
Besides the browser, the whole drawing can be kept in a remote store, e.g. the user's account online. Saving there takes longer, so it happens less often: every 5 minutes (REMOTE_SAVE_INTERVAL_MS) while there are changes, or when asked. In idle mode, it saves once the drawing has gone unchanged for a minute (idleMs, default REMOTE_IDLE_MS), and when the page is hidden or the window loses focus. Only changes to the drawing count (the canvas's modified event).
canvas.useRemoteDocumentStore(myAccountStore, { intervalMs: 10 * 60 * 1000 });
canvas.useRemoteDocumentStore(myAccountStore, { mode: "idle" });
// or: new PaintCanvas({ remoteDocumentStore: myAccountStore })
await canvas.remoteAutosave?.save(); // save now, e.g. from a "Save" button
-
A remote store has the
DocumentStoreLikemethods:save(document, onProgress)(the whole document, with its PNG blobs and thumbnail; callonProgresswith how much is done, 0 to 1, if known) andload(id). Its optionallabelnames it for the user, e.g. "Bluesky". -
canvas.remoteAutosave(aRemoteDocumentAutosave) hassaving,progress,lastSaved,hasChangesanderror, and dispatcheschangeanderror. A failed save is tried again next time. -
While it saves,
<pc-stats>shows "Saving to …" with a progress bar on the right, and says so if saving failed. -
To open a document from the store, use
canvas.openDocument(await myAccountStore.load(id)). -
IndexedDbDocumentStore(@lvl99dotcom/paintcanvas/lib/documentStore, optional) is a document store in the browser's IndexedDB, under a name. Besidessaveandload,list()gives each saved document's details, size and thumbnail (aDocumentSummary, most recently opened first) without loading its layers,remove(id)deletes one, andmarkOpened(id)marks one opened now without changing itsupdatedAt.import IndexedDbDocumentStore from "@lvl99dotcom/paintcanvas/lib/documentStore";const store = new IndexedDbDocumentStore("ada.example");await store.save(await canvas.createDocument());const [latest] = await store.list();await canvas.openDocument((await store.load(latest.id))!);await store.markOpened(latest.id); -
MemoryDocumentStore(@lvl99dotcom/paintcanvas/testing/documentStore) keeps documents in memory, optionally taking its time, for tests and trying it out. The demo uses it with?remotein its address.