This page is part of the HexEd.it User Manual.

HexEd.it - the client-side JavaScript based hex editor, can be found at https://hexed.it

Application Programming Interface (API)

Introduction

HexEd.it provides an Window.postMessage() API which enables your website or web application to interact with it.

You can either communicate with HexEd.it directly, on low-level, by using Window.postMessage() and WindowEventHandlers.onmessage, or by using a wrapper, which provides an easier-to-use higher-level, Promise-based interface.

The API is free to use, there's no authentification required. But, please contact me, if you expect more than 1000 requests per day, to discuss an usage and billing plan, to be able to provide a smooth user experience, also in the future.

Table of content

Low-level API

The first parameter of Window.postMessage() specifies the message object as described here.

The second parameter specifies the target origin. To make sure, your data are not dispatched to the wrong website, this parameter should be set to "https://hexed.it".

Higher-level API

The higher-level API wraps Window.postMessage() and WindowEventHandlers.onmessage into an easy-to-use Promise-based interface, which rejects the Promise if an error is returned, and resolves the Promise with the payload returned in the "done" response. Beside that, the interface takes care of the messageId management.

After initializing the wrapper, three methods can be used: request(action, params), subscribe(eventType, callback) and unsubscribe(eventType, callback). For details, see the example code above in JSFiddle.

Currently, you'll have to copy the wrapper code into your project. This allows you to adjust the code to fit your requirements (e.g. if you want to use TypeScript or CoffeeScript instead of JavaScript). If you think it would be a good idea to have a library, which you can simply include into your project, feel free to contact me.

Request message object

PropertyDescriptionType
action

The action to be performed by HexEd.it.

See below for the available actions.

string
params

Depending on the requested action, different parameters are available.

See below for the available actions and their specific parameters.

object
messageId

An optional unique identifier for this specific message. The easiest way here, is to use a counter which you'll increase for each message sent.

If an errors occurs while executing a specific message, the messageId will be available in the error-response, to be able to associate it to the request.

Beside that, if this property is specified and the request has been processed successfully, a response message with action "done" is returned, which includes the messageId as well. If messageId is not specified, no "done" message is sent.

string | number | undefined

Available actions

ActionDescription
"launch"

By using "https://hexed.it#defer" instead of "https://hexed.it" for the IFrame-URL, you are able to defer the loading the of the editor, till you send this "launch" action.

This is useful, if you want to send other actions first, which affect the look and feel of the editor (e.g. if you want to hide components, or open a specific file).

This action has no parameters and no return value.

"ui.components"

This action allows you to configure the UI of HexEd.it. You should do that, in combination with the "https://hexed.it#defer" and before you call the "launch" action.

ParameterDescriptionType
visible

Allows you to show only specific UI components.

If the property is undefined, all UI components are shown, otherwise only the components which are specified in the array are visible.

('AppToolbar' | 'FileTabbar' | 'SidebarContainer' | 'AppStatusbar')[] | undefined

This action has no return value.

"editors.add"

Add one or more editors (files/tabs) to HexEd.it.

ParameterDescriptionType
files

An array of Blobs, Files or TypedArrays.

ATTENTION! Because of a bug in Google Chrome, you'll have to create a new File instance for every item in the event.target.files array, in the change event handler of <input type="file"> elements, otherwise the file content will not be transfered to HexEd.it. In the higher-level API this is already considered, see the source code on JSFiddle.net for a solution.

(File | Blob | Int8Array | Uint8Array | Uint8ClampedArray | Int16Array | Uint16Array | Int32Array | Uint32Array | Float32Array | Float64Array)[]
Return valueDescriptionType
editors

An array of internal identifiers for the editor instances of each item in the files parameter.

The item in the editors array is the counterpart of the item in the files parameter.

The identifiers can be used for further interactions with a specific editor.

number[] | undefined
"editor.activate"

Activate a specific editor.

ParameterDescriptionType
editor

The internal identifier of the editor instance which should be activated. It's returned by the "editors.add" action.

number

This action has no return value.

"editor.setCursor"

Move the cursor to a specific offset.

ParameterDescriptionType
id

The internal identifier of the editor instance. It's returned by the "editors.add" action.

number
offset

The file offset at which the cursor should be placed.

number

This action has no return value.

"editor.getScrollOffset"

Returns of the offset of top/left byte in the editor viewport.

ParameterDescriptionType
id

The internal identifier of the editor instance. It's returned by the "editors.add" action.

number
Return valueDescriptionType
scrollOffset

The offset of top/left byte in the editor viewport.

number
"editor.scrollTo"

Scrolls to the given offset

ParameterDescriptionType
id

The internal identifier of the editor instance. It's returned by the "editors.add" action.

number
offset

The file offset to which should be scrolled.

number

This action has no return value.

"subscribe" / "unsubscribe"

Subscribe or unsubscribe to an editor event.

Event subscriptions always refer to the whole application, not to a specific editor (tab/file). Each event message contains a editor property, which allow you to identify the source of the specific event.

A list of event names and their additional payload can be found here.

ParameterDescriptionType
eventType

The name of a single event which should be subscribed/unsubscribed.

string

This action has no return value.

You have a special use-case where these actions are not enough? No, problem! Contact me and I'll implement it!
Basically, every action in the editor could be triggered by the Window.postMessage() API - the only limiting factor is my spare time.

Responses

TypeDescriptionType
type

There are 3 types of responses:

"done" indicates, that the request was successfully processed. "done" is only returned, if your request contains a messageId.

"error" is returned, if an error occured while processing your request (e.g. because of an invalid request parameter). See the the list of errors below for possible error responses.

"event" is returned, if you've subscribed to an editor event. See the the list of events below for possible event responses.

"done" | "error" | "event"
payload

Depending on the response type, different payloads are possible.

On type "done", the payload contains the result of the action, or undefined if the action has no result.

On type "error", payload contains an error code and an human-readable error message. See the the list of errors below for possible error responses.

On type "event", the payload contains information about the event. See the the list of events below for possible event responses.

object | undefined
messageId

If a messageId has been specified in the request, the same messageId is returned in the response for "done" and "error" actions.

For response type "event", no messageId is sent, because events are not directly related to specific requests.

string | number | undefined

Events

You are able to subscribe for different events. Event subscriptions always refer to the whole application, not to a specific editor (tab/file). Beside the eventType property, each event message also contains a editor property in the payload, which allow you to identify the source of the specific event.

If the event provides additional data, these are available in payload.data. If no additional data are available, the payload.data property does not exist.

payload.eventTypeDescription
"cursorChange"

The position of the cursor in the file changed.

Data propertyDescriptionType
newOffsetThe offset of the byte, to which the cursor moved.number
prevOffsetThe previous offset of the byte, from which the cursor moved.number
"dataChange"

Data have been changed either by user input, or by some other type of interaction.

Data propertyDescriptionType
offsetThe start offset of the change.number
lengthThe length of the range which has been changed.number
"destroy"

A specific editor has been destroyed and is no longer available.

This event has no additional "data".

"error"

If the editor component is not able to read the file, this event is triggered.

Data propertyDescriptionType
errorNameThe identifier of the error, or a specific error message."FILE_NOT_FOUND" | "FILE_NOT_READABLE" | "FILE_ABORT" | "FILE_SECURITY" | "FILE_ENCODING" | "FILE_IS_LOCKED" | "FILE_ACCESS_DENIED" | string
"historyChange"

The message

This event has no additional "data".

"scroll"

The message

Data propertyDescriptionType
source

The source which triggered the scrolling. Possible source values are:

"USER_INTERACTION", which is triggered if the user clicks somewhere in the scrollbar.

"POSITION_UPDATE", which is triggered if the cursor position has been changed programmatically.

"RESIZING", which is triggered if the scroll position has been changed because of a resizing of the editor.

"USER_INTERACTION" | "POSITION_UPDATE" | "RESIZING"
"selectionChange"

The message

This event has no additional "data".

"sizeChange"

The message

Data propertyDescriptionType
newSizeThe new size of the Blob.number

Errors

payload.codeDescription
"UNSUPPORTED_BROWSER"

While Window.postMessage() is available even in IE 8, Firefox 2 or Chrome 4, HexEd.it has higher requirements to the available functionality of the browser (see the User Manual home page for supported browsers). The editor does not check for specific browser versions, but checks if the required features are available in the browser - if they aren't this error is sent on startup.

To retrieve this error, you need to bind the WindowEventHandlers.onmessage listener, before you load HexEd.it.

payload.message will contain a list of features, which are not supported by the browser.

"ALREADY_LAUNCHED"

If you are calling the "launch" action, but the application has been already launched.

Eiher you havn't opened the HexEd.it by using the URL "https://hexed.it#defer", or you've already called the "launch" action.

"INVALID_MESSAGE_ID"The messageId parameter is neither undefined, nor of type number or string.
"INVALID_ACTION"The requested action does not exist.
"INVALID_PARAMETER"Either a mandatory parameter is missing, or the type or value of the parameter is invalid.
"UNKNOWN_EDITOR"The editor property in the request refers to an editor which does not exist.