From 55d97c1ad150863f153caad6ba81a7f31ab1941e Mon Sep 17 00:00:00 2001 From: Mike Morris Date: Tue, 8 Dec 2015 14:13:03 -0800 Subject: [PATCH] [node] document EventEmitter interface [skip ci] --- platform/node/README.md | 60 +++++++++++++++++++++++++++++++++++------ 1 file changed, 52 insertions(+), 8 deletions(-) diff --git a/platform/node/README.md b/platform/node/README.md index 028da8dfb..3c935b9b3 100644 --- a/platform/node/README.md +++ b/platform/node/README.md @@ -17,7 +17,13 @@ Just run: npm install mapbox-gl-native ``` -Other platforms will fall back to a source compile with `make node`. To compile this module, make sure all submodules are initialized with `git submodule update --init` and install the [external dependencies required to build from source](https://github.com/mapbox/mapbox-gl-native/blob/master/INSTALL.md#depends). +Other platforms will fall back to a source compile with `make node`. To compile this module, make sure all submodules are initialized with `git submodule update --init` and install the [external dependencies required to build from source](https://github.com/mapbox/mapbox-gl-native/blob/node-v2.1.0/INSTALL.md#2-installing-dependencies). + +## Testing + +``` +npm test +``` ## Rendering a map tile @@ -45,12 +51,6 @@ The first argument passed to `map.render` is an options object, all keys are opt When you are finished using a map object, you can call `map.release()` to dispose the internal map resources manually. This is not necessary, but can be helpful to optimize resource usage (memory, file sockets) on a more granualar level than v8's garbage collector. -## Testing - -``` -npm test -``` - ## Implementing a file source When creating a `Map`, you must pass an options object (with a required `request` method and optional 'ratio' number) as the first parameter. @@ -149,6 +149,51 @@ var map = new mbgl.Map({ Mapbox GL uses two types of protocols: `asset://` for files that should be loaded from some local static system, and `http://` (and `https://`), which should be loaded from the internet. However, stylesheets are free to use other protocols too, if your implementation of `request` supports these; e.g. you could use `s3://` to indicate that files are supposed to be loaded from S3. +## Listening for log events + +The module imported with `require('mapbox-gl-native')` inherits from [`EventEmitter`](https://nodejs.org/api/events.html), and the `NodeLogObserver` will push log events to this. Log messages can have [`class`](https://github.com/mapbox/mapbox-gl-native/blob/node-v2.1.0/include/mbgl/platform/event.hpp#L43-L60), [`severity`](https://github.com/mapbox/mapbox-gl-native/blob/node-v2.1.0/include/mbgl/platform/event.hpp#L17-L23), `code` ([HTTP status codes](http://www.w3.org/Protocols/rfc2616/rfc2616-sec10.html)), and `text` parameters. + +``` +MBGL_DEFINE_ENUM_CLASS(EventClass, Event, { + { Event::General, "General" }, + { Event::Setup, "Setup" }, + { Event::Shader, "Shader" }, + { Event::ParseStyle, "ParseStyle" }, + { Event::ParseTile, "ParseTile" }, + { Event::Render, "Render" }, + { Event::Style, "Style" }, + { Event::Database, "Database" }, + { Event::HttpRequest, "HttpRequest" }, + { Event::Sprite, "Sprite" }, + { Event::Image, "Image" }, + { Event::OpenGL, "OpenGL" }, + { Event::JNI, "JNI" }, + { Event::Android, "Android" }, + { Event::Crash, "Crash" }, + { Event(-1), "Unknown" }, +}); +``` + +``` +MBGL_DEFINE_ENUM_CLASS(EventSeverityClass, EventSeverity, { + { EventSeverity::Debug, "DEBUG" }, + { EventSeverity::Info, "INFO" }, + { EventSeverity::Warning, "WARNING" }, + { EventSeverity::Error, "ERROR" }, + { EventSeverity(-1), "UNKNOWN" }, +}); +``` + +```js +var mbgl = require('mapbox-gl-native'); +mbgl.on('message', function(msg) { + t.ok(msg, 'emits error'); + t.equal(msg.class, 'Style'); + t.equal(msg.severity, 'ERROR'); + t.ok(msg.text.match(/Failed to load/), 'error text matches'); +}); +``` + ## Mapbox API Access tokens To use styles that rely on Mapbox vector tiles, you must pass an [API access token](https://www.mapbox.com/developers/api/#access-tokens) in your `request` implementation with requests to `mapbox://` protocols. @@ -200,4 +245,3 @@ map.render({}, function(err, image) { }); ``` -