Global Object Reference

The global object defines several functions that are directly accessible to the script.

Declaration

interface IGlobal {
    // Properties
    readonly ${apiVersion}: number;
    readonly ${activeDocument}: ${IDocument};
    readonly ${activeView}: ${IDocumentView};
    readonly ${wholeFile}: ${ISelection};
    readonly ${documents}: ${IDocument}[];
    readonly ${activeProcessWindow}: ${IProcessWindow};

    // Methods

    // Control Flow and Tracing Methods
    ${log}(message: any): void;
    ${alert}(message: any, params?: { title?: string; buttons?: ${AlertButtons}; icon?: ${AlertIcon} }): ${AlertResult};
    ${input}(message: string): string;
    ${async}(handler: () => void, ms: number, repetitive = false): number;
    ${cancelAsync}(handlerId: number): void;
    ${delay}(ms: number): Promise<void>;
    ${loadTextFile}(path: string): string;
    ${stopScript}(): void;

    // Pattern Object Creation Methods
    ${createPattern}(): ${IPattern};
    ${createPattern#createPattern1}(text: string, encoding?: ${Encodings}): void;
    ${createPattern#createPattern2}(data: number[], dataType = ${ValueType}.Byte, bigEndian = false): ${IPattern};
    ${createPattern#createPattern3}(data: Uint8Array | Uint16Array | Uint32Array): ${IPattern};

    // New Document Creation Methods
    ${newDocument}(format?: string): ${IDocument};

    // Document Opening Methods
    ${openFile}(path: string, mode = ${OpeningMode}.Normal, readOnly = false, format?: string): ${IDocument};
    ${openVolume}(path: string, friendlyName?: string, mode = ${OpenVolumeMode}.ReadOnly): ${IDocument};
    ${openDisk}(path: string, friendlyName?: string, readOnly = true): ${IDocument};
    ${openHexAsync}(path: string, format: ${HexFormat}, flags = ${InsertHexFlags}.None): ${IDocument};

    // Window Management Methods
    ${activate}(value: string | ${IWindow}): void;
    ${closeAll}(closeMode = ${CloseMode}.Prompt): boolean;

    // General Application Control Methods
    ${displaySettings}(page?: string, hideOtherPages = false): void;
    ${exportSettings}(path?: string): boolean;
    ${importSettings}(path?: string): boolean;
    ${restart}(message?: string): void;
    ${exportConfiguration}(path?: string): boolean;
    ${importConfiguration}(path?: string): boolean;
    ${resetConfiguration}(): void;

    // Find in Files Methods
    ${findInFilesAsync}(pattern: ${IPattern} | string,
        folders: null | string | string[],
        operation: ${FindInFilesOperation},
        params?: { fileMask?: string; flags?: ${FindInFilesFlags}; subExpression?: number }): Promise<${FindInFilesResult}>;
    ${replaceInFilesAsync}(search: ${IPattern} | string,
        replace: ${IPattern},
        folders: null | string | string[],
        operation: ${ReplaceInFilesOperation},
        params?: { fileMask?: string; flags?: ${FindInFilesFlags}; subExpression?: number }): Promise<${FindInFilesResult}>;
    ${cancelFindInFilesOperation}(): void;

    // Process Methods
    ${findProcess}(processId: number): ${IProcess};
    ${findProcesses}(name: string): ${IProcess}[];
    ${openProcess}(process: number | ${IProcess}, withSnapshot = false): ${IProcessWindow};

    // Events
    ${activeDocumentChanged}(handler: (doc: ${IDocument}) => void): number;
    ${activeDocumentChanged}(eventId: number): void;
    ${activeViewChanged}(handler: (view: ${IDocumentView}) => void): number;
    ${activeViewChanged}(eventId: number): void;
}

// This interface is not available in managed environment

// This interface is not available in native environment

IGlobal Properties

apiVersion

readonly apiVersion: number;

// This property is not available in managed environment

// This property is not available in native environment

Returns the current API version. Equals 0x100 in Hex Editor Neo 7.01.

activeDocument

readonly activeDocument: ${IDocument};

// This property is not available in managed environment

// This property is not available in native environment

The reference to the active document's document object. If there is no active document, this property holds null.

activeView

readonly activeView: ${IDocumentView};

// This property is not available in managed environment

// This property is not available in native environment

The reference to the active editor window's document view object. If there is no active window, this property holds null.

wholeFile

readonly wholeFile: ${ISelection};

// This property is not available in managed environment

// This property is not available in native environment

Returns a special selection object that means “whole file”.

documents

readonly documents: ${IDocument}[];

// This property is not available in managed environment

// This property is not available in native environment

Returns an array of all opened documents in the editor.

activeProcessWindow

readonly activeProcessWindow: ${IProcessWindow};

// This property is not available in managed environment

// This property is not available in native environment

Returns a reference to an active process window or null if no such window exists.

IGlobal Methods

log

log(message: any): void;

// This method is not available in managed environment

// This method is not available in native environment

message: A message to display. Accepts value of any type and automatically converts it to string.

Prints the message to the Console. Does not halt script execution.

log("The value of the parameter v = " + v);

alert

alert(message: any, params?: { title?: string; buttons?: ${AlertButtons}; icon?: ${AlertIcon} }): ${AlertResult};

// This method is not available in managed environment

// This method is not available in native environment

message: A message to display. Accepts value of any type and automatically converts it to string.
params: Optional parameters include window title and combinations of buttons and icon to use. If title is omitted, default title is used. If buttons is omitted, a single OK button is displayed and if icon is omitted, no icon is displayed ina message box.

A button pressed by the user. Should be one of the values of AlertResult enumeration.

Display a message in a message box and return user's choice. Allows the script to customize the window title and buttons and icons used.

if (${AlertResult}.yes === alert("Do you want to execute the sequence of operations", { title: "Overwrite Prompt", buttons: ${AlertButtons}.YesNo, icon: ${AlertIcon}.Question))
{
    // ...
}

input

input(message: string): string;

// This method is not available in managed environment

// This method is not available in native environment

message: The message to be displayed to the user.

The string entered by the user.

Displays a message to the user and asks him to enter the line of text. The method then returns the text returned by the user. The call to this method results in a message box to be displayed.

var name = input("Enter your name:");
log("User name is " + name);

async

async(handler: () => void, ms: number, repetitive = false): number;

// This method is not available in managed environment

// This method is not available in native environment

handler: JavaScript function that takes no parameters and returns nothing. This function is invoked after ms milliseconds once or until cancelled, depending on the repetitive parameter.
ms: A number of milliseconds to wait until calling the passed function.
repetitive: An optional boolean that tells if async handler should be called once (repetitive is omitted or equals to false) or until cancelled (repetitive equals to true).

Returns an asynchronous function identifier. You may pass this identifier to cancelAsync method to cancel delayed function.

Schedules a passed Javascript function for delayed execution. A caller may optionally specify if the async function should be repetitive.

TypeScript lambda that is executed once after 1 second:

async(() => alert("Async handler executed"), 1000);

JavaScript function that is invoked every 2 seconds until cancelled after 20 seconds:

var h1 = async(function() { alert("Async handler executed"); }, 2000, true);
async(function() { cancelAsync(h1); }, 20000);

cancelAsync

cancelAsync(handlerId: number): void;

// This method is not available in managed environment

// This method is not available in native environment

handlerId: Async handler identifier to cancel.

Cancels pending async handler.

JavaScript function that is invoked every 2 seconds until cancelled after 20 seconds

var h1 = async(function() { alert("Async handler executed"); }, 2000, true);
async(function() { cancelAsync(h1); }, 20000);

delay

delay(ms: number): Promise<void>;

// This method is not available in managed environment

// This method is not available in native environment

ms: A number of milliseconds to wait until completing the returned promise object.

Returns a Promise object that gets completed in a given number of milliseconds.

Using await:

async function test() {
    // ...
    await delay(500);
    // ...
}

Using continuations:

delay(500).then(() => { ... });

loadTextFile

loadTextFile(path: string): string;

// This method is not available in managed environment

// This method is not available in native environment

path: Full path to a text file.

Loads contents of a text file into a string.

Load text file into string and print it:

log(loadTextFile("c:\\temp\\test.js"));

stopScript

stopScript(): void;

// This method is not available in managed environment

// This method is not available in native environment

Stops execution of a current script.

createPattern

createPattern(): ${IPattern};

// This method is not available in managed environment

// This method is not available in native environment

An empty pattern object.

Creates an empty pattern object.

// Replace all occurrences of a "test" pattern with an empty pattern
await activeView.replaceAllAsync(createPattern("test"), wholeFile, createPattern());

createPattern

createPattern(text: string, encoding?: ${Encodings}): void;

// This method is not available in managed environment

// This method is not available in native environment

text: Text string to be used as a pattern. encoding parameter specifies how Hex Editor Neo interprets this string.
encoding: Optional encoding to interpret the text string. Use Encodings.UTF16 to specify UTF-16 unicode string.

Create a pattern from a given text string. Optional encoding parameter specifies how the editor interprets the given string.

createPattern

createPattern(data: number[], dataType = ${ValueType}.Byte, bigEndian = false): ${IPattern};

// This method is not available in managed environment

// This method is not available in native environment

data: Pattern data values in a number array.
dataType: Optional value type. Tells the editor how to interpret values in a data array. Defaults to ValueType.Byte.
bigEndian: true to encode values from the data array as big-endian values, false otherwise. Defaults to false. Does not change data encoding if dataType equals ValueType.Byte.

A pattern object.

Create a pattern from a given number array. Optional dataType and bigEndian parameters change how the values in a data array are interpreted.

var pattern = createPattern([0x1234, 0x9876], ValueType.Word, true);

createPattern

createPattern(data: Uint8Array | Uint16Array | Uint32Array): ${IPattern};

// This method is not available in managed environment

// This method is not available in native environment

data: Pattern data in a given format.

A pattern object.

Create a pattern from a given data. Data is used as-is, without any conversion.

newDocument

newDocument(format?: string): ${IDocument};

// This method is not available in managed environment

// This method is not available in native environment

format

Optional format for the new document.

Format	Description
`"binary"`	Create standard empty document. This is the default format.
`"intel-hex"`	Create an encoded Intel Hex document.
`"motorola-hex"`	Create an encoded Motorola S-Records document.

A document object for the created document.

Create an empty document. Created document becomes an active document. A single view is also automatically created (it becomes an active view) and is opened in the editor.

var document = newDocument();
log("New document created.");

openFile

openFile(path: string, mode = ${OpeningMode}.Normal, readOnly = false, format?: string): ${IDocument};

// This method is not available in managed environment

// This method is not available in native environment

path

A full path to the file. File's extension is used to determine the type of the document to open.

mode

An optional opening mode.

readOnly

true to open a file in read-only mode, false otherwise. Defaults to false.

format

Optional format. If specified, forces the editor to try to open a file in a given format, overriding default behavior which analyzes the file's extension to determine format.

Format	Description
`"binary"`	Open as standard binary document.
`"intel-hex"`	Open as Intel Hex document.
`"motorola-hex"`	Open as Motorola S-Records document.

A document object.

Open a given file. If format is omitted, Hex Editor Neo analyzes file extension to determine the format of the file. .hex extension switches to the Intel Hex format and .s19, .s28 and .s37 extensions switch to the Motorola S-Records format.

Created document becomes an active document. A single view is also automatically created (it becomes an active view) and is opened in the editor.

var document = openFile("c:\\temp\\test.bin");

openVolume

openVolume(path: string, friendlyName?: string, mode = ${OpenVolumeMode}.ReadOnly): ${IDocument};

// This method is not available in managed environment

// This method is not available in native environment

path: Full path to the volume.
friendlyName: Optional volume “friendly name” to use in the editor.
mode: Volume opening mode. If omitted, defaults to OpenVolumeMode.ReadOnly.

A document object.

Open a given volume (logical disk) in the editor.

Created document becomes an active document. A single view is also automatically created (it becomes an active view) and is opened in the editor.

var document = openVolume("\\\\?\\Volume{7c1102f4-68e7-22e5-a511-80aa6f644963}\\", "Volume: C:\\", OpenVolumeMode.ReadOnly);

openDisk

openDisk(path: string, friendlyName?: string, readOnly = true): ${IDocument};

// This method is not available in managed environment

// This method is not available in native environment

path: Full path to the disk.
friendlyName: Optional disk “friendly name” to use in the editor.
readOnly: true to open the disk in read-only mode, false otherwise. If omitted, defaults to true.

A document object.

Open a given disk (physical disk) in the editor.

Created document becomes an active document. A single view is also automatically created (it becomes an active view) and is opened in the editor.

var document = openDisk("\\\\.\\PHYSICALDRIVE0", "First Physical Disk", true);

openHexAsync

openHexAsync(path: string, format: ${HexFormat}, flags = ${InsertHexFlags}.None): ${IDocument};

// This method is not available in managed environment

// This method is not available in native environment

path: Full path to the file. Specify null to take file contents from the Clipboard.
format: A format of the file you are opening.
flags: One or more of the flags that modify the behavior of this method.

A document object.

Open a given encoded hex file in the editor. format is used to specify the format of the hex file and flags modify the file decoding behavior.

Created document becomes an active document. A single view is also automatically created (it becomes an active view) and is opened in the editor.

var document = await openHexAsync(null, HexFormat.Intel, InsertHexFlags.IgnoreDataOffset);

activate

activate(value: string | ${IWindow}): void;

// This method is not available in managed environment

// This method is not available in native environment

value: A name of the window or a reference to a window object.

Activates a given window. This method takes a reference to the window to activate or a window name.

activate("New Document 1");
// activate the first view of the first document
activate(documents[0].views[0]);

closeAll

closeAll(closeMode = ${CloseMode}.Prompt): boolean;

// This method is not available in managed environment

// This method is not available in native environment

closeMode: An optional closing mode.

true if operation was successful, false otherwise.

Close all opened windows. The optional closeMode parameter is interpreted as follows:

Value	Description
Prompt	Ask the user what to do with unsaved changes to documents.
Save	Force save any unsaved changes.
Discard	Discard all unsaved changes.

displaySettings

displaySettings(page?: string, hideOtherPages = false): void;

// This method is not available in managed environment

// This method is not available in native environment

page: Optional (non-localized) name of the page to display.
hideOtherPages: true to hide all other pages besides page, false otherwise.

Display the application Settings Window, optionally highlighting a given settings page.

exportSettings

exportSettings(path?: string): boolean;

// This method is not available in managed environment

// This method is not available in native environment

path: Optional path of an external file where to write current application settings. If omitted, Hex Editor Neo asks the user to specify it.

true if the export was successful and false otherwise.

Exports all application settings to a given file. If a full path is not given, an Save File window opens so the user may select the location of the export file.

importSettings

importSettings(path?: string): boolean;

// This method is not available in managed environment

// This method is not available in native environment

path: Optional path of an external file where to read application settings. If omitted, Hex Editor Neo asks the user to specify it.

true if the import was successful and false otherwise.

Imports all application settings from a given file. If a full path is not given, an Open File window opens so the user may select the location of the file.

restart

restart(message?: string): void;

// This method is not available in managed environment

// This method is not available in native environment

message: Optional message to display to the user before restarting application.

Restart Hex Editor Neo. Optional message, if specified, is displayed to the user before proceeding with a restart.

exportConfiguration

exportConfiguration(path?: string): boolean;

// This method is not available in managed environment

// This method is not available in native environment

path: Optional path of an external file where to write current UI configuration. If omitted, Hex Editor Neo asks the user to specify it.

true if the export was successful and false otherwise.

Exports the current UI configuration (toolbars and tool window layout) to a given file. If a full path is not given, an Save File window opens so the user may select the location of the export file.

importConfiguration

importConfiguration(path?: string): boolean;

// This method is not available in managed environment

// This method is not available in native environment

path: Optional path of an external file where to read application UI configuration. If omitted, Hex Editor Neo asks the user to specify it.

true if the import was successful and false otherwise.

Imports UI configuration (toolbars and tool window layout) from a given file. If a full path is not given, an Open File window opens so the user may select the location of the file.

resetConfiguration

resetConfiguration(): void;

// This method is not available in managed environment

// This method is not available in native environment

Resets the UI configuration to default state.

findInFilesAsync

findInFilesAsync(pattern: ${IPattern} | string,
    folders: null | string | string[],
    operation: ${FindInFilesOperation},
    params?: { fileMask?: string; flags?: ${FindInFilesFlags}; subExpression?: number }): Promise<${FindInFilesResult}>;

// This method is not available in managed environment

// This method is not available in native environment

pattern: A pattern or regular expression string to search. Use the createPattern method to create a pattern object.
folders: One or more folder paths that serve as the starting point for a search operation. If params.flags include the FindInFilesFlags.IncludeSubFolders flag, sub-folders of a given folder(s) are also searched. If folders parameter is null, the operation is performed for opened documents only.
operation: A type of Find in Files operation to perform.
params: Optional operation parameters. fileMask, if omitted, defaults to "*". flags, if omitted, equals to FindInFilesFlags.None.

A Promise object that produces a result of operation (as FindInFilesResult object) when completed.

Start the Find in Files operation. folders parameter specifies the starting search location. pattern specifies the pattern to search. The behavior of this method changes depending on the type of this parameter:

Type	Description
IPattern	Standard matching mode is used. `params.flags` parameter may include the FindInFilesFlags.IgnoreCase flag to ignore patter case when matching.
`string`	Regular expression mode is used. `params.flags` parameter may include the FindInFilesFlags.IgnoreCase and FindInFilesFlags.RegularExpressionUnicode flags. Optional `params.subExpression`, if set, specifies the regular expression's sub-expression to use.

replaceInFilesAsync

replaceInFilesAsync(search: ${IPattern} | string,
    replace: ${IPattern},
    folders: null | string | string[],
    operation: ${ReplaceInFilesOperation},
    params?: { fileMask?: string; flags?: ${FindInFilesFlags}; subExpression?: number }): Promise<${FindInFilesResult}>;

// This method is not available in managed environment

// This method is not available in native environment

search: A pattern or regular expression string to search. Use the createPattern method to create a pattern object.
replace: A pattern for use for replacing. Use the createPattern method to create a pattern object.
folders: One or more folder paths that serve as the starting point for a search operation. If params.flags include the FindInFilesFlags.IncludeSubFolders flag, sub-folders of a given folder(s) are also searched. If folders parameter is null, the operation is performed for opened documents only.
operation: A type of Replace in Files operation to perform.
params: Optional operation parameters. fileMask, if omitted, defaults to "*". flags, if omitted, equals to FindInFilesFlags.None.

A Promise object that produces a result of operation (as FindInFilesResult object) when completed.

Start the Replace in Files operation. folders parameter specifies the starting search location. pattern specifies the pattern to search. The behavior of this method changes depending on the type of this parameter:

Type	Description
IPattern	Standard matching mode is used. `params.flags` parameter may include the FindInFilesFlags.IgnoreCase flag to ignore patter case when matching.
`string`	Regular expression mode is used. `params.flags` parameter may include the FindInFilesFlags.IgnoreCase and FindInFilesFlags.RegularExpressionUnicode flags. Optional `params.subExpression`, if set, specifies the regular expression's sub-expression to use.

cancelFindInFilesOperation

cancelFindInFilesOperation(): void;

// This method is not available in managed environment

// This method is not available in native environment

Cancel a currently running Find in Files operation.

findProcess

findProcess(processId: number): ${IProcess};

// This method is not available in managed environment

// This method is not available in native environment

processId: Process ID of a running process.

A reference to a running process or null if there is no such process

Locate the running process object using the provided process ID.

findProcesses

findProcesses(name: string): ${IProcess}[];

// This method is not available in managed environment

// This method is not available in native environment

name: A process name to match

An array of running process objects. If no match is found, the returned array is empty.

Find all instances of a running processes that match the provided name. Name matching is case insensitive.

openProcess

openProcess(process: number | ${IProcess}, withSnapshot = false): ${IProcessWindow};

// This method is not available in managed environment

// This method is not available in native environment

process: Process ID or a reference to a process object to open.
withSnapshot: Set to true to automatically create a process snapshot.

A reference to a created process window object.

Opens the given process and returns its process window object.

IGlobal Events

activeDocumentChanged

activeDocumentChanged(handler: (doc: ${IDocument}) => void): number;
activeDocumentChanged(eventId: number): void;

doc: A reference to a document object that becomes active. May be null.

This event is fired when the active document changes.

activeViewChanged

activeViewChanged(handler: (view: ${IDocumentView}) => void): number;
activeViewChanged(eventId: number): void;

view: A reference to a document view object that becomes active. May be null.

This event is fired when the active view changes.

AlertButtons AlertResult AlertIcon IDocument IDocumentView IPattern ISelection Encodings ValueType OpeningMode OpenVolumeMode HexFormat IWindow FindInFilesOperation ReplaceInFilesOperation FindInFilesFlags FindInFilesResult IProcess IProcessWindow