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
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.
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".
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.
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.
| Property | Description | Type |
|---|---|---|
| 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 |
| Action | Description | ||||||||||||
|---|---|---|---|---|---|---|---|---|---|---|---|---|---|
| "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.
This action has no return value. | ||||||||||||
| "editors.add" | Add one or more editors (files/tabs) to HexEd.it.
| ||||||||||||
| "editor.activate" | Activate a specific editor.
This action has no return value. | ||||||||||||
| "editor.setCursor" | Move the cursor to a specific offset.
This action has no return value. | ||||||||||||
| "editor.getScrollOffset" | Returns of the offset of top/left byte in the editor viewport.
| ||||||||||||
| "editor.scrollTo" | Scrolls to the given offset
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.
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.
| Type | Description | Type |
|---|---|---|
| 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 |
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.eventType | Description | |||||||||
|---|---|---|---|---|---|---|---|---|---|---|
| "cursorChange" | The position of the cursor in the file changed.
| |||||||||
| "dataChange" | Data have been changed either by user input, or by some other type of interaction.
| |||||||||
| "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.
| |||||||||
| "historyChange" | If the user clicks the undo or redo button, this event is triggered. This event has no additional "data". | |||||||||
| "scroll" | Triggered if the scroll position changed, either programmatically or by using the scrollbar.
| |||||||||
| "selectionChange" | If the user changes the selection, this event is triggered. It's not triggered for inital selections based on Motorola S-Record or Intel HEX ranges. This event has no additional "data". | |||||||||
| "sizeChange" (deprecated) | This event is called on insert/delete actions. Right now it's also called if the size does not change on insertion in overwrite mode. In a later release, this event will be replaced by a new one, which handles overwriting correct.
|
| payload.code | Description |
|---|---|
| "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. |