API Overview

This API Overview highlights some of the the Zaplib Standard Library. Our API Reference is is more comprehensive but isn't as user friendly.

Universal Interfaces

Some Rust functions, particularly around IO, don't work in WebAssembly out-of-the-box. Zaplib provides a number of cross-platform, "universal" interfaces that work both natively and in WebAssembly.

Rust	Universal
`println!`	`log!`	Logs to the console (with line number).
`thread`	`universal_thread`	`spawn` (without `JoinHandle`) `sleep` We recommend using a thread pool, e.g. the rayon's `ThreadPoolBuilder`.
`Instant`	`UniversalInstant`	`elapsed, now, duration_since, checked_add, checked_sub, +, -, +=, -=`
`File`	`UniversalFile`	`open` (on WebAssembly this blocks until the whole file is loaded in memory) `open_url` (non-standard; load an absolute URL) `clone` (cheap; clones just a handle to the data; doesn't preserve cursor) `std::io::Read` `std::io::Seek` `ReadSeek` (non-standard; convenient trait for `Read + Seek`)
non-standard	`universal_http_stream`	`request` (returns data as it comes in; useful for large files) `std::io::Read`
non-standard	`universal_rand`	`random_128`

`Cx` & Events

Cx object. This is a global "context" object, that gets passed around practically everywhere.

Construction Event

When the app is constructed, a Construct event is fired. It is fired exactly once, and before any other calls to handle or draw. The event contains no further information.

Calling cx.start_timer creates a new Timer object. When the timer fires, a TimerEvent event is dispatched. Use timer.is_timer to check if that event belongs to a particular timer. Use cx.stop_timer to stop it.

Signals

Signals are user-defined events that can be used for anything you want. Create a new Signal object by calling cx.new_signal. Then send it with a StatusId using cx.send_signal (same thread) or Cx::post_signal (any thread). This will trigger a SignalEvent on the main thread (handle and draw are always called on the main Rust thread).

Note that the Signals API is a bit complicated currently; we aim to improve this so you can send any user-defined events.

WebSockets

cx.websocket_send sends a message on a WebSocket. If no WebSocket yet exists for the given URL, a new one is opened. When receiving a message on a WebSocket, a WebSocketMessageEvent is fired.

Focus

If the browser tab or native window gets or loses focus, then AppFocus or AppFocusLost are fired, respectively.

User files

To create a drop target for the entire window / browser tab, we have to create a Window with create_add_drop_target_for_app_open_files. Then, when dropping a file, an AppOpenFilesEvent event will fire.

There are also events for when a file drag is started, updated, or cancelled.

Profiling

Basic profiling using the console can be done using cx.profile_start and cx.profile_end.

Missing compatibility

Some standard library APIs don't work in all contexts. APIs that are currently unsupported in a context are annotated with a tracking ticket ID.

API	Rust main thread	Rust child thread	JS main thread	JS WebWorker
Logging (`log!`)	✅	✅	✅	✅
Spawning threads (`universal_thread`)	✅	✅	#72	#72
Current time (`UniversalInstant`)	✅	✅	✅	✅
Reading local files (`UniversalFile`)	✅	✅	#72 #66	#72
Writing local files	#73	#73	#73 #66	#73
HTTP requests (`UniversalFile`/`universal_http_stream`)	✅	✅	#66	✅
Random (`universal_rand`)	✅	✅	✅	✅
Websockets (`cx.websocket_send`)	✅	#71	#71	#71
Timers (`cx.start_timer`)	✅	#71	#71	#71
Posting signals (`Cx::post_signal`)	✅	✅	#72	#72
Profiling (`cx.profile_start`)	✅	#71	#71	#71
Blocking Rust threading primitives (`Mutex`)	✅	✅	#66	✅

Zaplib docs