The following is a list of functions for communicating with the 010 Editor program when writing a Template or Script.

void AddBookmark(
    int64 pos,
    string name,
    string typename,
    int64 arraySize=-1,
    int forecolor=cNone,
    int backcolor=0xffffc4,
    int moveWithCursor=false )
Creates a bookmark in the file on which the current Script or Template is being executed (not the actual Script or Template). See Using Bookmarks for information on bookmarks and see Running Templates and Scripts for information on controlling on which file a Script or Template is run.

pos indicates the local address where the bookmark will be generated and name gives the name of the bookmark (this name can be empty). typename is a string giving the type of the bookmark to generate and this must be one of the built-in types or a user-defined type. If the type is user-defined and the AddBookmark function is run from a Template, that type must be defined in the current Template. If the type is user-defined and the AddBookmark function is run from a Script, that type must be defined in a Template that has already been run on the file (not in the current Script). Specify an array of variables using the arraySize argument or set arraySize to -1 to just generate a single variable. The text color of the bookmark can be indicated using the forecolor argument and the background color can be specified with the backcolor argument. If the moveWithCursor argument is true, the bookmark will reposition itself to the cursor as the cursor moves around the file.

For example, after loading a ZIP file in 010 Editor (which will cause the 'ZIP.bt' Template to be run on the file), create a new Script and run the following command on the file:

     AddBookmark( GetCursorPos(), "endmarker", 
         "ZIPENDLOCATOR", -1, cRed );

Here the type "ZIPENDLOCATOR" type is defined in the 'ZIP.bt' file, not in the Script. The functions GetNumBookmarks, GetBookmarkPos and GetBookmarkName can be used to query existing bookmarks and the RemoveBookmark function can be used to erase bookmarks.

int64 AddressFileToLocal( int64 fileAddress )
Given fileAddress, an address of a byte in a file, this function converts the address into local coordinates and returns the result. The local coordinate system is a method of referencing bytes in a file where 0 is the first byte and FileSize()-1 is the last byte. Usually the file and local coordinate systems are the same unless editing a process or a file with a custom starting address. To convert from a local coordinate to a file coordinate use the AddressLocalToFile function. This function is equivalent to ProcessHeapToLocalAddress when editing a process.

int64 AddressLocalToFile( int64 localAddress )
Almost all functions in scripts and templates use the local coordinate system, where 0 is the first byte in the file and FileSize()-1 is the last byte. This differs from the file coordinate system which uses the addresses as displayed in the Hex Editor. Given a localAddress, this function converts the address of the byte from local coordinates to file coordinates and returns the result. See AddressFileToLocal for the inverse operation and for more information. This function is equivalent to ProcessLocalToHeapAddress when editing a process.

void Assert( int value, const char msg[] = "" )
Stops execution of the script or template if the value is equal to zero. If execution is stopped, the text message msg will be displayed in the Output tab of the Output Window (note that this is an optional argument). Because conditional statements evaluate to 1 or 0 in C/C++, comparisons can be used in asserts. For example:

     Assert( numRecords > 10, 
       "numRecords should be more than 10." ); 

void ClearClipboard()
Removes any data that is on the currently active clipboard. See the SetClipboardIndex function to control which clipboard is active.

void CopyBytesToClipboard( uchar buffer[], int size, int charset=CHARSET_ANSI, int bigendian=false )
Copies size bytes from the array buffer and places them on the currently active clipboard. If the data being copied represents a string, use the charset parameter to indicate which character set the string uses (see the ConvertString function for a list of character sets). If copying Unicode data the bigendian parameter indicates if the data is in big or little endian format, otherwise this parameter is ignored. See the SetClipboardIndex function to control which clipboard is currently active.

void CopyStringToClipboard( const char str[], int charset=CHARSET_ANSI )
Sets the currently active clipboard to contain the string passed in the str argument. The charset parameter tells the clipboard what character encoding is used for the string (e.g. ANSI, UTF-8, etc.) and the list of possible character sets is available in the ConvertString function. If copying hex bytes to the clipboard see the CopyBytesToClipboard function and the active clipboard can be set using the SetClipboardIndex function.

void CopyToClipboard()
Copies the currently selected bytes to the active clipboard. See SetSelection to change the selection or SetClipboardIndex to set the active clipboard.

void CutToClipboard()
Copies the currently selected bytes to the active clipboard and deletes them from the file. See SetSelection to change the selection or SetClipboardIndex to set the active clipboard.

int DeleteFile( char filename[] )
Deletes the file given by filename from disk. Note that the file should not be open in the editor or the delete will fail. Returns a value less than zero on failure.

void DisableUndo()
Turns off undo support for a file. This function will speed up a script when writing a large number of changes to a file. Undo is automatically turned on after the script is finished. Note that undo is automatically disabled for files created with FileNew. See EnableUndo below.

void DisplayFormatBinary()
void DisplayFormatDecimal()
void DisplayFormatHex()
void DisplayFormatOctal()
Sets the display format of variables in the Inspector to binary, decimal, hexadecimal, or octal. Any variables declared after this function is called will be displayed in the selected format. Note that the format can also be set for one variable using the syntax <format=hex|decimal|octal|binary> after a declaration or typedef (see Declaring Template Variables for more information). The GetDisplayFormat and SetDisplayFormat functions provide an alternate method of setting the display format.

void EnableUndo()
Turns back on Undo support for a file after calling DisableUndo. Undo is automatically turned on after the script is finished.

int Exec( const char program[], const char arguments[], int wait=false )
int Exec( const char program[], const char arguments[], int wait, int &errorCode )
Executes an external application using the given program and arguments. Returns 0 if successful or a negative number if an error occurred. If the wait argument is true, this function waits for the external application to finish processing before it returns. If wait is true and the errorCode parameter is given, the error code from the executed program will be stored in the errorCode variable. Note that starting in 010 Editor version 3.1, this function can no longer be called in a Template because of security issues.

void Exit( int errorcode )
Ends execution of the current script or template and displays the errorcode in the Output tab of the Output panel. Note that usually the keyword return can be used to accomplish the same task unless execution is inside of a custom function.

This function is special in that it can be used to return an ERRORLEVEL code to a batch file (see Command Line Parameters for more information). The last errorcode that was passed to an Exit function, either from a script or a template, will be returned as the global ERRORLEVEL when 010 Editor exits.

void ExpandAll()
Recursively opens all tree nodes in the Template Results panel. Variables that have the attribute '<open=suppress>' set will not be opened. See Template Results for more information.

void ExportCSV( const char filename[] )
Writes the contents of the Template Results panel to a file in a comma-delimited format which can be opened in other programs such as Excel. The file is saved to the given filename and the ExpandAll function can be called first to ensure all variables are included in the export. Alternately, the FPrintf function can be used to output individual variables.

void ExportXML( const char filename[] )
Similar to ExportCSV except the contents of the Template Results panel are written to a file in XML format. The file to write is given by the filename parameter. Call the ExpandAll function first to ensure all variables are included in the XML file.

void FileClose()
Closes the current file. No file will be active after this function is called and use the FileSelect function to activate another file. This function can also be used to close an open process or drive. Note that the user will not be asked to save changes if the file is modified.

int FileCount()
Returns the number of existing file handles. See FileSelect to set the current file.

int FileExists( const char filename[] )
Returns true if the given file name exists on disk, or false if it does not.

int FileNew( char editAs[]="", int makeActive=true )
Creates a new file in the editor and returns the index of the created file (see GetFileNum). If the editAs parameter is not empty, the created file will be assigned that Edit As the same as using the SetFileInterface function (for example, "Hex", "Text", or "Unicode"). If no editAs is given, the default Edit As is used from the Editor Options dialog.

If this function is run from a script and the makeActive parameter is true, the created file becomes the current file. If this function is run from a template or the makeActive parameter is false, the current file does not change (use the FPrintf function to write data to the returned file handle). Note that when new files are created, the undo buffer is turned off by default, but will be turned on as soon as the script finishes.

int FileOpen( const char filename[], int runTemplate=false, char editAs[]="", int openDuplicate=false )
Opens the file specified by the UTF-8 encoded string filename into the editor. If runTemplate is true and a Template is associated with that file (see Template Options), the Template will be run on the file. The opened file will be assigned the Edit As editAs (for example, "Hex", "Text", or "Unicode") and if editAs is an empty string, FileOpen will automatically choose an Edit As. If openDuplicate is true and the file to be opened is already open in the editor, a duplicate copy of the file will be created but if openDuplicate is false, no action will be taken. This function returns the file index of the opened file if the file could be loaded (see GetFileNum), the file index of the already opened file if openDuplicate is false and the file is already open, or a negative number if the file could not be opened (no error message is displayed if the file could not be found). FileOpen is usually called in a Script but can be called in a Template if that Template is given special permission to read other files (see Permissions).

To open a logical drive use the OpenLogicalDrive function or call 'FileOpen( "Drive X:" );' where X is a letter. To open a physical drive use the OpenPhysicalDrive function or call 'FileOpen( "Physical Drive n:" );' where n is a number. Processes can be opened using the OpenProcessById or OpenProcessByName functions.

int FileSave()
int FileSave( const char filename[] )
int FileSave( const wchar_t filename[] )
Saves the current file to the given file name. The file name can be either a UTF-8 string or a wide string. If FileSave is called with no parameters, the file is saved to the current file name. See GetFileName or GetFileNameW to retrieve the name of the current file. Returns a value less than zero on error. Note that when using backslashes in Windows path names, two backslashes must be used in string constants. For example:

      FileSave( "C:\\temp\\data.log" ); 

int FileSaveRange( const char filename[], int64 start, int64 size )
int FileSaveRange( const wchar_t filename[], int64 start, int64 size )
Similar to the FileSave function except that only part of the file is written to disk. size bytes starting from the local address start are written to the given filename and filename can be given in UTF-8 or Unicode format. Note that filename must specify a different file than the current file name. Returns a negative value on error.

void FileSelect( int index )
Only one file can be active at a time and all of the Read/Write operations occur on that file. Use FileSelect to select a different file to be the current file. The files are numbered from 0 up to FileCount()-1. See GetFileNum to get the index of the current file.

int FindOpenFile( const char path[] )
int FindOpenFileW( const wchar_t path[] )
Searches through the list of all open files to see if the file indicated by path is currently open. If the file is open, the index of the file is returned which can be used with the FileSelect function. If the file cannot be found, -1 is returned. The FindOpenFileW operates similarly to the FindOpenFile function but takes as input a Unicode file name.

char[] GetArg( int index )
wchar_t[] GetArgW( int index )
Returns an argument passed to a script or a template from the command line. The GetArg function returns an ASCII string and the GetArgW function returns a wide string. The index parameter must be a number between 0 and GetNumArgs()-1. If index is an invalid number an empty string is returned. See the GetNumArgs function or the -script or -template parameter for more information on passing command line arguments.

int GetBackColor()
Returns the currently active background color for template variables. See SetBackColor for more information. When the current color was set using the SetStyle function then the background color associated with the style is returned, similar to the function GetStyleBackColor.

int GetBookmarkArraySize( int index )
If the bookmark specified by index is an array this function returns the number of elements in the array, otherwise this function returns -1. index should be greater or equal to zero and less than the value returned by GetNumBookmarks. See AddBookmark for more information.

int GetBookmarkBackColor( int index )
This function returns an integer representing the background color of the bookmark specified by index. index should be zero or greater and less than the number of bookmarks (see GetNumBookmarks). More information about creating bookmarks can be found in the AddBookmark help topic.

int GetBookmarkForeColor( int index )
Returns an integer representing the foreground (text) color of the bookmark indicated by the index parameter. A return value of cNone means that the foreground color is not changed. index should be greater or equal to zero and less that the total number of bookmarks. See GetNumBookmarks to retrieve the number of bookmarks and AddBookmark for more information on adding bookmarks.

int GetBookmarkMoveWithCursor( int index )
This function returns true if the bookmark specified by index is set to move around the file as the cursor/caret moves (a floating bookmark). False is returned if this is not a floating bookmark. Bookmarks can be created to move with the cursor using the AddBookmark function. Note that index should be greater or equal to zero and less that the value returned by GetNumBookmarks.

string GetBookmarkName( int index )
Returns a string which contains the name of a bookmark. index controls which bookmark name is returned and the value of index should be greater or equal to zero, and less than the number of bookmarks (see GetNumBookmarks). See AddBookmark for information on creating bookmarks.

int64 GetBookmarkPos( int index )
Returns the starting address of a bookmark and the bookmark returned is specified using the index argument. index should be greater or equal to zero, and less than the number of bookmarks (see GetNumBookmarks). See AddBookmark for information on creating bookmarks.

string GetBookmarkType( int index )
This function returns a string representing the type of data stored by the given bookmark (for example, "char" or "int"). The index parameter must be greater or equal to zero and less than the value returned by GetNumBookmarks. See the AddBookmark function for information about creating bookmarks.

int GetBytesPerLine()
Returns the number of bytes displayed per line in the current Hex Editor Window. This value is by default 16, but may change depending upon the current settings in the View Menu.

int GetClipboardBytes( uchar buffer[], int maxBytes )
Reads data from the currently active clipboard into the given buffer. At most maxBytes bytes will be read from the clipboard and the buffer array must be large enough to hold maxBytes bytes. The return value is the number of bytes written into the buffer, or 0 if no bytes could be read. Also see the GetClipboardString for reading strings from the clipboard and the active clipboard can be set using the SetClipboardIndex function.

int GetClipboardIndex()
Returns the index of the currently active clipboard. A return value of 0 means the standard system clipboard is chosen and a value of 1 to 9 inclusive means a custom clipboard is chosen. All clipboard operations including CopyToClipboard, CutToClipboard, PasteFromClipboard, CopyBytesToClipboard, CopyStringToClipboard, GetClipboardBytes, GetClipboardString, and ClearClipboard operate on the currently selected clipboard. Use the SetClipboardIndex function to select a different clipboard and see Using the Clipboard for more information on using multiple clipboards. The currently active clipboard is indicated in the Status Bar.

string GetClipboardString()
If the active clipboard currently contains a string, this string will be returned by the GetClipboardString function. If the data on the clipboard cannot be converted to a string, an empty string will be returned. If the clipboard contains hex data that may include null characters, use the GetClipboardBytes function instead. The active clipboard can be set using the SetClipboardIndex function.

string GetCurrentTime( char format[] = "hh:mm:ss" )
Returns a string representing the current time in the format "hh:mm:ss" by default (note this is using the 24-hour clock). For information on different formats that can be used see the GetCurrentDateTime function and to use the current application time format see the GetDefaultTimeFormat function.

string GetCurrentDate( char format[] = "MM/dd/yyyy" )
Returns a string representing the current date in the format "MM/dd/yyyy" by default. For information on different formats that can be used see the GetCurrentDateTime function and to use the current application date format see GetDefaultDateFormat.

string GetCurrentDateTime( char format[] = "MM/dd/yyyy hh:mm:ss" )
Returns a string representing the current date and time in the format "MM/dd/yyyy hh:mm:ss" by default (note this is using the 24-hour clock). When specifying a custom format, the following characters can be used:

• h - hour without leading zero
• hh - hour with leading zero
• m - minute without leading zero
• mm - minute with leading zero
• s - second without leading zero
• ss - second with leading zero
• z - millisecond without leading zero
• zzz - millisecond with leading zero
• AP - either AM or PM
• ap - either am or pm
• d - day without leading zero
• dd - day with leading zero
• ddd - short day (e.g. 'Mon')
• dddd - long day (e.g. 'Monday')
• M - month without leading zero
• MM - month with leading zero
• MMM - short month (e.g. 'Jan')
• MMMM - long month (e.g. 'January')
• yy - 2-digit year
• yyyy - 4-digit year

The function GetDefaultDateTimeFormat can also be used to get the current application date/time format. Functions such as StringToTimeT or StringToOleTime can be used to convert the resulting string to a date format.

int64 GetCursorPos()
Returns the address of the cursor/caret in the file in local coordinates.

string GetDefaultDateFormat()
Returns the default date format for the application as set in the Inspector Options dialog. This date format is used in the Inspector and the Template Results.

string GetDefaultDateTimeFormat()
Returns a string containing the default date format followed a single space followed by the default time format. Both date and time formats can be set using the Inspector Options dialog.

string GetDefaultTimeFormat()
Returns the default time format set in the Inspector Options dialog. This time format is used in the Inspector and the Template Results.

int GetDisplayFormat()
Returns an integer representing the current display format. The display format controls how a numeric variable is displayed in the Template Results or Inspector. One of the following constants will be returned:

• DISPLAY_FORMAT_DECIMAL
• DISPLAY_FORMAT_HEX
• DISPLAY_FORMAT_OCTAL
• DISPLAY_FORMAT_BINARY

The display format should usually be set through the functions DisplayFormatBinary, DisplayFormatDecimal, DisplayFormatHex, or DisplayFormatOctal and see those functions for more information on controlling the display format. The SetDisplayFormat function provides an alternate method of changing the format.

char[] GetEnv( const char str[] )
Attempts to locate the system environment variable indicated by str. If the environment variable is found, the value of the environment variable is returned as a UTF-8 string and if it could not be found an empty string is returned.

int GetFileAttributesUnix()
Returns the file attributes of a file on a Unix or Macintosh operating system as a bit flag. The resulting value has nine different flags: read, write and execute for each of the areas user, group, and other. The following constants can be used for testing the bits:

• FILEATTR_READ_USER
• FILEATTR_WRITE_USER
• FILEATTR_EXE_USER
• FILEATTR_READ_GROUP
• FILEATTR_WRITE_GROUP
• FILEATTR_EXE_GROUP
• FILEATTR_READ_OTHER
• FILEATTR_WRITE_OTHER
• FILEATTR_EXE_OTHER

If the file is not a valid file or the file is not in a Unix or Macintosh operating system, the constant FILEATTR_INVALID is returned. For example:

      int flags = GetFileAttributesUnix();
      if( (flags != FILEATTR_INVALID) && !(flags & FILEATTR_READ_USER) )
          Printf( "File is read only.\n" ); 

See the SetFileAttributesUnix function to modify the attributes.

int GetFileAttributesWin()
Returns the file attributes of a file on a Windows operating system as a bit flag. The resulting constants can be used for testing the bits:

• FILEATTR_ARCHIVE
• FILEATTR_HIDDEN
• FILEATTR_READONLY
• FILEATTR_SYSTEM

If the file is not a valid file or the file is not in a Windows operating system, the constant FILEATTR_INVALID is returned. For example:

      int flags = GetFileAttributesWin();
      if( (flags != FILEATTR_INVALID) && (flags & FILEATTR_READONLY) )
          Printf( "File is read only.\n" ); 

See the SetFileAttributesWin function to modify the attributes.

int GetFileCharSet()
Returns an integer representing the character set of the current file. The list of possible character sets is available in the ConvertString function. Use the SetFileCharSet function to change the character set for the current file.

char[] GetFileInterface()
Returns a string representing the Edit As of the current file. The current Edit As is listed in the status bar (for example: "Hex", "Text", or "Unicode"). See the SetFileInterface function to change the Edit As of the current file.

char[] GetFileName()
Returns a string representing the file name of the current file including the path. The string is returned in UTF-8 format.

wchar_t[] GetFileNameW()
Returns a wide string which contains the file name of the current file including the path.

int GetFileNum()
Each open file is assigned a index from 0 up to FileCount()-1. This function returns the index of the current file. Returns -1 if called in a Script which does not have a file target. Use the FileSelect function to make another file the active file.

int GetForeColor()
Returns the currently active foreground (text) color for template variables. See SetForeColor for more information. If the current color has been set using the SetStyle function then the foreground color associated with the style is returned, similar to the function GetStyleForeColor.

int GetKeepFileTime()
Returns true if keep file time is enabled for the current file. If keep file time is turned on for a file and the file is saved, the modified file time as stored on a hard drive will not be changed. See SetKeepFileTime to change the keep file time status for the current file.

int GetMouseWheelScrollSpeed()
Returns the number of lines that are scrolled every time a mouse scroll wheel is clicked ahead or back. The scroll speed can be controlled with the Editor Options dialog or with the SetMouseWheelScrollSpeed function.

int GetNumArgs()
Returns the number of arguments that were passed to this script or template from the command line. The individual arguments can be accessed using the GetArg and GetArgW functions. For more information on how to pass arguments see the -script and -template command line parameters.

int GetNumBookmarks()
Returns the number of bookmarks set for the file that the current Script or Template is being run on (see Running Templates and Scripts for more information on choosing which file to run a Template or Script on). See the AddBookmark function for information on creating bookmarks.

int GetReadOnly()
Returns true if the file is marked as read-only, or false if the file can be modified.

char[] GetScriptName()
wchar_t[] GetScriptNameW()
These functions return the name of the script that is currently being executed. This name is calculated by taking the full file name of the script and removing the path information. For example, if the script being run was 'H:\Scripts\Test.1sc', these functions would return 'Test.1sc'. GetScriptName returns a UTF-8 string and GetScriptNameW returns a Unicode string.

char[] GetScriptFileName()
wchar_t[] GetScriptFileNameW()
When a script is being executed, these functions return the full file name of the script being run. GetScriptFileName returns a UTF-8 string and GetScriptFileNameW returns a Unicode string.

int64 GetSelSize()
Returns the number of bytes that have been selected. Returns 0 if no selection is made.

int64 GetSelStart()
Returns the start address of the selection in local coordinates. Use GetSelSize to determine if a selection has been made.

int64 GetStartingAddress()
Returns the starting address of the file in file coordinates. This is the address of the first byte in the file as displayed in the Hex Editor. Usually the starting address is 0 unless a custom starting address has been assigned to the file. Use SetStartingAddress to modify the starting address.

int GetStyle()
Returns the currently active style for template variables as set by the SetStyle function. If a style has been set then one of the constants listed in the Template Styles section is returned. If no style has been set then -1 is returned. See SetStyle for more information.

int GetStyleBackColor( int style )
Returns the background color that is currently associated with the given style constant. A list of available template style constants is given in the Template Styles section. If a background color is associated with the style then the color is returned in the format 0xBBGGRR. If no background color is associated with the style then -1 is returned. Colors can be assigned to styles using the Theme/Color Options dialog.

int GetStyleForeColor( int style )
Returns the foreground (text) color that is associated with the given style constant. See the Template Styles section for a list of style constants. This function return a color in the format 0xBBGGRR if a foreground color is assigned, or -1 if no foreground is assigned. See the Theme/Color Options dialog to view and change colors for styles.

string GetTempDirectory()
Returns a string representing the current temporary directory set using the Directory Options dialog. The temp directory will contain a slash as the last character (e.g. "C:\temp\").

char[] GetTempFileName()
Returns the full path of a file that can be used as a temporary file. The file will be in the current temporary directory and will be guaranteed not to exist. The returned file name is in UTF-8 format.

char[] GetTemplateName()
wchar_t[] GetTemplateNameW()
These functions operate by taking the full template file name as returned from the functions GetTemplateFileName or GetTemplateFileNameW, removing the path information and returning the result. For example, if the current Template being run was 'H:\Templates\Test.bt', these functions would return 'Test.bt'. GetTemplateName returns a UTF-8 string and GetTemplateNameW returns a Unicode string.

char[] GetTemplateFileName()
wchar_t[] GetTemplateFileNameW()
When run in a Template, these functions return the full file name of the Template that is being run. When run in a Script, these functions return the full file name of the Template that has been associated with the target file, or an empty string if there is no associated Template. GetTemplateFileName returns a UTF-8 string and GetTemplateFileNameW returns a Unicode string.

int GetUnoptimizedArraysCollapsible()
Returns true if unoptimized arrays are displayed with a parent node that can be opened or closed in the Template Results. See Optimizing Arrays of Structs for more information. The value this function returns is initially determined by the Compiling Options dialog and is by default true. See the SetUnoptimizedArraysCollapsible function to change the value.

char[] GetWorkingDirectory()
wchar_t[] GetWorkingDirectoryW()
Returns the full path of the current working directory for the application. The last character of the directory will be a slash and the current working directory can be set using the SetWorkingDirectory and SetWorkingDirectoryW functions. GetWorkingDirectory returns UTF-8 string and GetWorkingDirectoryW returns a Unicode string.

void HighlightAllowInstanceSharing( int allowSharing )
Instance sharing is used for Syntax Highlighters to make loading of syntax highlighters faster and use less memory. When allowSharing is true then all files in 010 Editor that use this syntax highlighter share a single copy of the compiled template in memory. For example, if instance sharing is turned on for the CPP.bt template, then all files that use that template share a single copy of the template so it does not have to be recompiled every time a new C++ file is opened. Only enable instance sharing if a template calls the HighlightLineRealtime function and only creates local variables.

void HighlightApplyColor(
    int foreColors[],
    int backColors[],
    int start,
    int count,
    int foreColor,
    int backColor )
Given an array of foreground colors foreColors, this function sets count colors starting at position start to the color foreColor. count colors in the backColors array beginning at the start index are also set to the color backColor. If foreColor or backColor is -1 then those colors are not applied. This function is similar to HighlightApplyStyle which uses styles instead of colors.

void HighlightApplyStyle(
    int foreColors[],
    int backColors[],
    int start,
    int count,
    int styleIndex )
Sets count colors in the arrays foreColors and backColors to the style styleIndex, starting at index start. If the style has a foreground or background color of -1 (none) then those colors are not applied. See the HighlightFindStyle function to retrive a styleIndex. This function can be used in the HighlightLineRealtime function to apply styles.

TKeywordList HighlightBuildKeywordList(
    int options,
    string str1 [, string str2, ... ] )
This function builds a TKeywordList structure out of the options paramater and a list of one or more strings. Once the TKeywordList structure is built it can be used in the HighlightCheckKeywordRule or HighlightMatchKeyword functions to quickly check if text matches a number of different keywords. options is a bitmask of HIGHLIGHT_WHOLEWORD and/or HIGHLIGHT_IGNORECASE. If HIGHLIGHT_WHOLEWORD is enabled then partial words cannot match the keyword list and if HIGHLIGHT_IGNORECASE is enabled then the keywords are compared case insensitive.

virtual void HighlightBytesRealtime(
    int64 pos,
    uchar bytes[],
    int foreColors[],
    int backColors[],
    int count )
This is a special virtual function. When this function is implemented inside a Binary Template, the function will be called for hex files every time a block of data is to be displayed in the editor. The block of data starts at address pos and has count bytes which are stored in the array bytes. Any colors applied to the foreColors or backColors arrays will be used to color text in the hex editor. See the HighlightColorPattern function for a method of applying a repeating block of colors to an array of colors. Note that this function can cause performance issues in 010 Editor if the function is very slow and cancelling of execution while this function is running is disabled.

int HighlightCheckCommentRule(
    wchar_t text[],
    int count,
    wstring target,
    int &pos,
    int foreColors[],
    int backColors[],
    int styleIndex,
    int options=0 )
Applies a single-line comment rule to a line of text of size count. If the target string is found at position pos then the color styleIndex is applied to foreColors and backColors from pos to the end of the line. If the target matches then pos is set to count. See HighlightFindString for a list of possible values for the options parameter. Use the HighlightFindStyle function to locate a syntax style. If a match is found this function returns true, otherwise this function returns false.

int HighlightCheckKeywordRule(
    wchar_t text[],
    int count,
    TKeywordList &keywords,
    int &pos,
    int foreColors[],
    int backColors[],
    int styleIndex,
    int options=0 )
This function checks if a set of keywords matches the text array of size count starting at position pos. The keywords structure is created with the HighlightBuildKeywordList function. If any of the keywords match then the foreColors and backColors arrays are colored using the styleIndex color. See the HighlightFindStyle function to locate a style. If a match is found this function returns true and pos is updated to the next character past the found keyword, otherwise false is returned. See HighlightFindString for a list of possible values for the options parameter and note that to perform case-insenstive keyword matches the list must be built with the HIGHLIGHT_IGNORECASE option in HighlightBuildKeywordList.

int HighlightCheckMultiLineRule(
    wchar_t text[],
    int count,
    wstring startKeyword,
    wstring endKeyword,
    int &pos,
    int &rule,
    int ruleStart,
    int ruleTarget,
    int foreColors[],
    int backColors[],
    int styleIndex,
    int options=0 )
Similar to HighlightCheckSingleLineRule except that this function can be used to apply coloring that spans several lines such as a multi-line comment. Multi-line coloring is achieved through the rule parameter which is assumed to be saved in the flags paramater of the HighlightLineRealtime function. The text line of size count is investigated and the styleIndex color is applied to foreColors and backColors from the startKeyword to the endKeyword inclusive. This function has two different modes. If rule has the value ruleStart then we are not yet coloring according to this rule and startKeyword is checked at position pos. If startKeyword is found the coloring rule becomes active, rule is set to ruleTarget and coloring is applied until endKeyword is found or the end of the line is reached. If endKeyword is found then rule is set back to ruleStart and pos is updated to the first character past endKeyword otherwise pos is set to the end of the line. If HighlightCheckMultiLineRule is called and rule is equal to ruleTarget then we are currently coloring using this rule. Coloring is applied starting from pos until endKeyword is found or the end of the line is found similar to the above case. Using the rule parameter coloring can be applied to multiple lines but note multi-line functions should be called first in a loop to check if they are active before checking other rules. This function returns true if coloring was applied. See HighlightFindStyle function to locate style indices and see HighlightFindString for a list of possible values for the options parameter.

int HighlightCheckSingleLineRule(
    wchar_t text[],
    int count,
    wstring startKeyword,
    wstring endKeyword,
    int &pos,
    int foreColors[],
    int backColors[],
    int styleIndex,
    int options=0 )
Applies syntax highlighting to a single line of text of size count. The styleIndex color is applied to the array foreColors and backColors if the startKeyword string is found at position pos. If startKeyword is found, coloring is applied from pos to the end of the endKeyword if endKeyword is found or to the end of the line if endKeyword is not found. If startKeyword is found this function returns true and pos is updated to the next character past what was colored, otherwise false is returned. This function can be used to color a single line string if startKeyword is '"' and endKeyword is '"'. See the HighlightFindStyle function to locate style indices and see HighlightFindString for a list of possible values for the options parameter.

int HighlightCheckTagRule(
    wchar_t text[],
    int count,
    wstring startKeyword,
    wstring endKeyword,
    int &pos,
    int &rule,
    int ruleStart,
    int ruleTarget,
    int foreColors[],
    int backColors[],
    int styleIndex,
    int &foundName,
    int options=0 )
Used to apply coloring to tags in an XML or HTML file but could be used for a variety of other coloring as well. This function applies coloring to just startKeyword and endKeyword whereas HighlightCheckMultiLineRule colors everything in between as well. Multi-line coloring can be achieved through the rule parameter which is assumed to be saved in the flags parameter of the HighlightLineRealtime function. If rule has the value ruleStart the keyword startKeyword is checked at the pos location. If it is found then it is colored by applying styleIndex to the arrays foreColors and backColors, rule is set to ruleTarget, pos is moved to the first character after the keyword, and foundName is set to false. If rule has the value ruleTarget then the endKeyword is checked at the pos location. If it is found then coloring is applied using styleIndex, rule is set to ruleStart and pos is updated to the first character after the keyword. See the HighlightFindStyle function to locate style indices and see HighlightFindString for a list of possible values for the options parameter.

int HighlightCheckTagTokenRule(
    wchar_t text[],
    int count,
    int &pos,
    int foreColors[],
    int backColors[],
    int tagStyle,
    int nameStyle,
    int attributeStyle,
    int &foundName )
Used as a convenience function for coloring text inside a tag, such as used in XML or HTML. The next token is extracted from the text of size count similar to the HighlightGetNextToken function. The colors corresonding to the token in the foreColors and backColors arrays are then colored according to one of three possible styles. If the token starts with a letter and foundName is false then the token is colored according to the nameStyle and foundName is set to true. This allows the first name found inside a tag to be colored differently than the other names. If foundName is true and the token starts with a letter then the attributeStyle is used to color the next, otherwise the tagStyle is used to color the text. Use the HighlightFindStyle function to retrieve style indices. This function returns true if a token was found and pos is updated to the next character after the end of the token.

void HighlightColorPattern(
    int start,
    int end,
    int foreColors[],
    int backColors[],
    int count,
    int patternSize1, int foreColor1, int backColor1
    [, int patternSize2, int foreColor2, int backColor2, ...] )
Applies a repeating color pattern to a block of bytes. This function is useful to apply coloring to a hex file when using the HighlightBytesRealtime function. Given an array of colors foreColors and backColors of size count, a pattern is applied starting at the index start and ending at end. The pattern consists of patternSize1 bytes of color foreColor1 and backColor1, followed by patternSize2 bytes of color foreColor2 and backColor2, etc., and repeats until the end is reached. For example:

 void HighlightBytesRealtime( int64 pos, uchar bytes[], 
         int foreColors[], int backColors[], int count )
 {
     int start = 18, end = 1278;
     if( (pos < end) && (pos+count >= start) )
         HighlightColorPattern( start-pos, end-pos, 
             foreColors, backColors, count, 
             6,  -1, cDkBlue,
             12, -1, cDkAqua,
             64, -1, -1 );
 }

int HighlightFindString(
    wchar_t text[],
    int count,
    wstring target,
    int start,
    int &matchlen,
    int options=0 )
Attempts to locate the string target in the array text of size count characters. The search starts at index start. If a find occurrence is found the starting index is the return value of the function and the number of matching characters is returned in the matchlen variable. options may be a bitmask of the following constants:

• HIGHLIGHT_REGEX - searches with regular expressions
• HIGHLIGHT_IGNORECASE - perform a case-insensitive search
• HIGHLIGHT_CSTRING - when searching for quotes, do not allow \" or \' to end a string
• HIGHLIGHT_XMLSTRING - when searching for quotes, allow '>' to end a string (malformed XML)

Note that HIGHLIGHT_REGEX can currently only be combined with HIGHLIGHT_IGNORECASE.

int HighlightFindStyle(
    string styleName,
    int lightForeColor=-1,
    int lightBackColor=-1,
    int darkForeColor=-1,
    int darkBackColor=-1 )
Returns the index of the style with name styleName in the list of Syntax Styles as located in the Theme/Color Options dialog. This style index can be used with other functions such as HighlightGetStyleForeColor, HighlightGetStyleBackColor, HighlightApplyStyle, HighlightCheckCommentRule, etc. Versions of 010 Editor before version 15 used a different naming scheme for syntax styles, where 'code-' was prefixed to certain style names. This prefix was removed starting in version 15. This function supports both naming schemes; for example, searching for "code-comment" will find the style "comment" and searching for "code-data-type" will find the style "type". Also, newer styles use '.' between style names instead of '-' and both formats are supported so that searching for "tag-string" will find "tag.string".

If the styleName is not found then a new style is created with the colors lightForeColor and lightBackColor indicating the color when using a light theme, and darkForeColor and darkBackColor indicating the color for a dark theme. If darkForeColor and darkBackColor are both -1 then lightForeColor and lightBackColor are used for both light and dark colors. Colors should be given in the format 0xBBGGRR or -1 for no color.

int HighlightGetNextToken( wchar_t text[], int count, int start, int splitAlphaNum=1 )
This function is used to divide up a line of text into a series of tokens to check for syntax highlighting. Given a text array of size count, this function starts scanning at index start and returns the index of the first character that has a different character class than the character at start. The different character classes are letter, number, symbol, or whitespace. If splitAlphaNum is false then letters and numbers are considered the same character class. If the character class never changes then count is returned. Use this function to speed up the search for keywords in a line of text since keywords only need to be checked every time the character class changes.

int HighlightGetStyleForeColor( int styleIndex )
Returns the foreground (text) color for a styleIndex. The styleIndex parameter can be obtained using the HighlightFindStyle function. Colors are in the format 0xBBGGRR and the color -1 indicates no color (clear).

int HighlightGetStyleBackColor( int styleIndex )
Returns the background color for a styleIndex. The styleIndex parameter can be obtained using the HighlightFindStyle function. Colors are in the format 0xBBGGRR and the color -1 indicates no color (clear).

virtual void HighlightLineRealtime(
    int64 line,
    wchar_t text[],
    int foreColors[],
    int backColors[],
    int count,
    ushort &flags )
This is a special virtual function. When this function is implemented in a Binary Template then that Template is used for Syntax Highlighting a text file. This function is called every time a line of text needs to be colored in the editor. The line number (starting at 0) is given with the line parameter. The text of the line is converted to Unicode characters (wstring) and passed in the text parameter as count characters. The function is responsible for scanning the text and placing colors into the foreColors and backColors arrays. foreColors holds the foreground (text) color of each character and backColors holds the background color of each character.

Any method can be used to apply colors to the arrays but a number of functions are provided to make applying colors easier and these functions all start with 'Highlight'. Syntax Highlighters can use Syntax Styles as described in the Theme/Color Options dialog to apply colors. See the HighlightFindStyle function to locate styles and HighlightApplyStyle to apply the styles. Styles can also be applied using the HighlightCheckCommentRule, HighlightCheckKeywordRule, HighlightCheckMultiLineRule, HighlightCheckSingleLineRule, or HighlightCheckTagRule functions. These functions provide an easier way to apply different types of syntax highlighting rules to text.

The flags parameter is a special parameter that allows multi-line syntax highlighting to work. For the first line in the file the value of flags is zero. flags may be modified by the HighlightLineRealtime function and the value of flags at the end of the function is passed to the next line when HighlightLineRealtime is called. For example, using this variable it is possible to keep track if the highlighter is inside a multi-line comment. flags is a 16-bit value and a combination of numbers or flags can be stored in this variable using bitmasks.

Note that this function can cause performance issues in 010 Editor if the function is very slow and cancelling of execution while this function is running is disabled.

int HighlightMatchKeyword(
    TKeywordList &keywords,
    wchar_t text[],
    int count,
    int start,
    int options=0 )
Given a keywords structure as created by HighlightBuildKeywordList, this function returns true if any of the keywords match the text array of size count starting at position start. If a match is found the number of matching characters is returned, otherwise the function returns 0. options may be 0 or HIGHLIGHT_WHOLEWORD, in which case partial matches are not returned. Note that to perform case-insenstive keyword matches the list must be built with the HIGHLIGHT_IGNORECASE option in HighlightBuildKeywordList.

void HighlightMatchString(
    wchar_t text[],
    int count,
    wstring target,
    int start,
    int options=0 )
Given a line of text text of size count, this function checks if the string target exists at position start. If a match is found the number of matching characters is returned otherwise zero is returned. options can be a bitmask of either HIGHLIGHT_REGEX to perform regular expression searches and/or HIGHLIGHT_IGNORECASE to perform case-insensitive searches.

char[] InputDirectory( const char title[], const char defaultDir[]="" )
Allows the user to choose a directory using the standard system directory select dialog. The title string is displayed in the title bar of the dialog. The defaultDir parameter allows setting the initial directory when the dialog is first displayed and if this parameter is null, the last chosen directory will be used. The return value is the directory name in UTF-8 format including a trailing slash, or an empty string if the dialog was cancelled.

double InputFloat(
    const char title[],
    const char caption[],
    const char defaultValue[] )
Opens up a dialog with a single edit box. The title displays in the title bar of the dialog and the caption displays above the edit box. The defaultValue specifies the starting value in the edit box. This function returns the floating-point value of the number entered in the edit box. If an invalid number is entered or Cancel is pressed, the constant BAD_VALUE is returned.

int InputNumber(
    const char title[],
    const char caption[],
    const char defaultValue[] )
Similar to InputFloat except an integer is returned instead of a float value. If an invalid number is entered or Cancel is pressed, the constant BAD_VALUE is returned.

char[] InputOpenFileName(
    char title[],
    char filter[]="All files (*)",
    char filename[]="" )
Shows a standard file open dialog box with the caption title. The filter controls which file masks are available in the File Type drop-down list. Specify filters as an array of strings separated by the '|' character (the file masks should be inside brackets). The filename gives the default file name of the file to open and may just contain a directory to start the dialog in that directory. Only a single file may be selected with the file dialog box. The returned value is the full chosen file name in UTF-8 format, or an empty string if cancel was pressed.

TOpenFileNames InputOpenFileNames(
    char title[],
    char filter[]="All files (*)",
    char filename[]="" )
Similar to InputOpenFileName except that multiple files may be selected. The results are returned in a structure TOpenFileNames that contains a count variable indicating the number of opened files (zero if cancel was pressed), and an array of file variables which each have a UTF-8 filename variable indicating the selected file. For example:

     int i;
     TOpenFileNames f = InputOpenFileNames( 
         "Open File Test", 
         "C Files (*.c *.cpp)|All Files (*)" );
     for( i = 0; i < f.count; i++ )
         Printf( "%s\n", f.file[i].filename ); 

will print out all file names selected.

int InputRadioButtonBox(
    const char title[],
    const char caption[],
    int defaultIndex,
    const char str1[], const char str2[], const char str3[]="",
    const char str4[]="", const char str5[]="", const char str6[]="",
    const char str7[]="", const char str8[]="", const char str9[]="",
    const char str10[]="", const char str11[]="", const char str12[]="",
    const char str13[]="", const char str14[]="", const char str15[]="" )
Displays a dialog box containing a number of radio buttons which allows a user to pick one choice from a list of options. The title string is displayed in the title bar and the caption string is displayed above the first radio button. The list of options to be displayed is controlled using the str1 .. str15 parameters. Which radio button is chosen by default is controlled with the defaultIndex parameter (use a value of -1 to not use a default and note that 0 represents the first item). The return value of this function is the index of the chosen radio button (0 is the first item, 1 the next, etc), or -1 is returned if the dialog was cancelled.

char[] InputSaveFileName(
    char title[],
    char filter[]="All files (*)",
    char filename[]="",
    char extension[]="" )
Uses a standard file save dialog box to select a file name suitable to use when saving a file. The user will be asked to overwrite a file if it already exists on disk. The title, filter and filename arguments are similar to the InputOpenFileName function. If no extension is given for the file name, a period and the extension argument will automatically be appended to the file name. The return value is the full chosen file name in UTF-8 format, or an empty string if cancel was pressed.

char[] InputString(
    const char title[],
    const char caption[],
    const char defaultValue[] )
Similar to InputFloat except that the string value of the edit box is returned instead of a float value. If Cancel is pressed, an empty string is returned. The string is returned in UTF-8 format.

wstring InputWString(
    const char title[],
    const char caption[],
    const wstring defaultValue )
Displays a dialog for the user to enter a wide string (unicode string). See the InputFloat function for an explanation of the different arguments. If Cancel is pressed, an empty string is returned.

int InsertFile( const char filename[], int64 position )
Inserts all of the bytes in the file given by filename into the current file starting at local address position. A negative number is returned if the file cannot be inserted.

int IsEditorFocused()
Returns true if a Editor Window is currently focused. This function is useful if you want to build a script that controls the cursor/caret of the Editor Window and only want the caret to move when the window is focused.

int IsModified()
Returns true if any changes have been made to the file, or false otherwise.

int IsNoUIMode()
Returns true if 010 Editor is currently in -noui mode, or false otherwise. See Command Line Parameters for more information on -noui mode.

int IsUndoEnabled()
Returns true if undo is enabled for the current script. Undo can be turned on or off using the functions EnableUndo and DisableUndo.

int MessageBox( int mask, const char title[], const char format[] [, argument, ... ] )
Displays a message box to the user with a number of buttons to press. The buttons displayed depend upon an OR mask of four values. The Ok, Cancel, Yes, or No buttons can be displayed by using the constants idOk, idCancel, idYes, or idNo respectively (note that not all possible combinations are supported). The title is display in the title bar of the message box. The message to display is obtained using a syntax similar to printf (see Printf below). The return value is one of the constants idOk, idCancel, idYes, or idNo depending upon which button was pressed. For example, to display a message box with Yes and No buttons use:

  if( MessageBox( idYes | idNo, 
     "Script", 
     "Save changes to '%s'?", 
     GetFileName() ) 
       == idYes ) 
   . . . 

This function should not be used in read, name or comment attribute functions since these functions may be called many times a second. Use StatusMessage or Warning instead. Note that extended characters can be displayed in the message box by passing strings in UTF-8 format.

void OffsetClear()
Removes any offset or any size limit that has been set for the current template. This function is identical to calling OffsetSetLimitSize(0) and OffsetSetStart(0). See OffsetSetLimitSize and OffsetSetStart for more information.

int64 OffsetGetLimitSize()
Templates can be run on just a section of a file instead of the whole file. If a size limit is set for a file, then a template can only access data in the file from offset up to offset + size limit - 1. This function returns the current size limit for the file and a return value of 0 means that the template can access data from offset up to the end of the file. See OffsetSetStart to set the offset and OffsetSetLimitSize to set the size limit. More information is available in the Running Templates at an Offset help topic.

int64 OffsetGetStart()
Instead of running a template on a whole data file, a template may be run on just part of the file by specifying an offset and a size limit. Offsets may be set using the Run Template dialog as described in the Running Templates at an Offset help topic. This function returns the current offset for the file in local coordinates and a value of 0 indicates that no offset has been set. OffsetSetStart can be used to change the template offset.

void OffsetSetLimitSize( int64 sizelimit )
Sets the size limit of the current file to sizelimit. This allows a template to be run on only part of a data file instead of the whole data file. Setting sizelimit to a value less than or equal to 0 removes any size limit for the file. See the Running Templates at an Offset help topic for more information on the offset and size limit for templates. Use OffsetGetLimitSize to query the current size limit for the template.

void OffsetSetStart( int64 start )
An offset can be set for a template which allows the template to be run on just part of a data file instead of the whole file. Calling this function sets the template offset to start meaning the template can only access data in the data file starting at local address start. See the Running Templates at an Offset help topic for more information. OffsetSetLimitSize can be used to set a size limit on the data that can be accessed and OffsetGetStart can be used to query the current offset.

void OutputPaneClear()
The Output Pane refers to the area where text from the Printf function is displayed (located in the Output tab of the Output Window). When this function is called, all previous output in the Output Pane is cleared.

int OutputPaneSave( const char filename[] )
Saves all text in the Output tab of the Output Window to a file on disk. The filename argument gives the name of the target output file. This function returns 0 if the file was successfully written or a negative number if the file could not be written.

void OutputPaneCopy()
Copies the text in the Output tab of the Output Window to the operating system clipboard.

void PasteFromClipboard()
Inserts any bytes in the currently active clipboard into the file starting at the current cursor/caret position. If a selection has been made, the selected bytes will be deleted before the bytes are inserted. See the SetClipboardIndex function to control which clipboard is active.

int Printf( const char format[] [, argument, ... ] )
Similar to the standard C printf function. Accepts a format specifier and a series of arguments. The results of the Printf are displayed in the Output tab of the Output Window and the following codes can be used to specify different data types:

      Printf( "Num = %d, Float = %lf, Str = '%s'\n", 15, 5, "Test" ); 

The above statement would display "Num = 15, Float = 5.000000, Str = 'Test'". Extended characters can be printed in the Output Window by passing a string in UTF-8 format. Wide strings can be printed with Printf using the regular '%s' specifier because they will automatically be cast to a UTF-8 string. Previous to version 4.0 of 010 Editor, the Printf function did some interpretation of basic HTML tags but this has been removed in version 4.0. Consult documentation on the standard C printf function for more information on different specifiers that can be used. See SPrintf or Str to convert the output to a string instead of displaying the output in the Output Window.

The Output Window is automatically shown when Printf is called in a Script but is not automatically shown when Printf is called in a Template. This functionality can be controlled via the Compiling Options dialog.

int64 ProcessGetHeapLocalAddress( int index )
Each memory heap in a process is assigned a position in the current file. This function returns the starting local file address for the heap given by index. index must be between 0 and ProcessGetNumHeaps()-1. If the current file is not a process or if index does not refer to a valid heap, -1 is returned. See Editing Processes for more information on processes and heaps.

wchar_t[] ProcessGetHeapModule( int index )
Returns the name of the module to which the given memory heap belongs. The module name is returned as a wide string and index must be between 0 and ProcessGetNumHeaps()-1. If the current file is not a process or if index does not refer to a valid heap or if the given heap is not associated with a module, an empty string is returned. For more information on heaps and modules see Editing Processes.

int ProcessGetHeapSize( int index )
Returns the size in number of bytes for the heap given by index. index must be between 0 and ProcessGetNumHeaps()-1. If the current file is not a process or if index does not refer to a valid heap, -1 is returned.

int64 ProcessGetHeapStartAddress( int index )
Returns the starting address in memory for the heap given by index. index must be between 0 and ProcessGetNumHeaps()-1. If the current file is not a process or if index does not refer to a valid heap, -1 is returned.

int ProcessGetNumHeaps()
Returns the number of memory heaps for the current process. If the current file is not a process, 0 is returned. See Editing Processes for more information on processes and heaps.

int64 ProcessHeapToLocalAddress( int64 memoryAddress )
Each heap in a process has two addresses: a memory address where the data actually exists in computer memory and a local file address where the data is located when using scripts and templates. Given an address memoryAddress in system memory, this function returns the equivalent address in the local file. See Editing Processes for more information on processes and heaps.

int64 ProcessLocalToHeapAddress( int64 localAddress )
Each heap in a process has two addresses: a memory address where the data actually exists in computer memory and a local file address where the data is located when using scripts and templates. Given an address localAddress in the local file, this function returns the equivalent address in system memory. See Editing Processes for more information on processes and heaps.

void ProjectClose()
Closes the current project. This function can only be run in a script and note that since closing a project could cause the current script to be closed, the project is not closed until the script has finished execution.

void ProjectOpen( const char filename[] )
Loads the project specified by filename and filename should be in UTF-8 format. If the project has an associated workspace then all current files are closed and all the files in the workspace are opened. This function must be called in a script and since the current script could be closed in the process of opening the project, the project is not opened until the script has finished execution.

void RemoveBookmark( int index )
Removes a bookmark from the current file. The index argument specifies which bookmark to remove and its value should be greater or equal to zero, and less than the number of bookmarks (see GetNumBookmarks). For information on creating bookmarks see AddBookmark.

int RenameFile( const char originalname[], const char newname[] )
Renames a file on disk from originalname to newname. Note that the file should not be open in the editor when it is renamed. A negative number if returned if the rename fails.

void RequiresFile()
Scripts can either be run with a target file or without a target file (select "(none)" in the Run on File section when editing a Script to run it without a target file). If this function is called and the current script is being run without a target file, a runtime error will be displayed and the script will be stopped. This function should not be called in a Template because Templates must always have a target file.

void RequiresVersion( int majorVer, int minorVer=0, int revision=0 )
Indicates what version of 010 Editor is required to execute the current script or template. The execution of the script or template will stop if the current version of 010 Editor is less than the version number given by the majorVer, minorVer, and reversion parameters. For example, with 010 Editor version '3.0.2', the '3' is the major version, '0' is the minor version, and '2' is the revision number. Use this function to ensure that other people that are running your scripts or templates are using the proper version of 010 Editor.

void RunTemplate( const char filename[]="", int clearOutput=false )
This function can be called in a Script to execute a Template on the current file. The filename argument indicates which Template file to run and the filename can either be a full file path, or can be just the name of the file and 010 Editor will attempt to locate the Template using the same rules as locating Include files. For example, 'RunTemplate( "ZIP.bt" );' will attempt to locate the "ZIP.bt" file and execute it on the current file. filename can also be an empty string in which case the Template which is associated with the current file will be run (usually this is the last Template that was run on the file). If the Template cannot be located or if there is an error executing the Template, program execution will be stopped. If clearOutput is true, the Output tab of the Output Window will be cleared before the Template is started.

void SetBackColor( int color )
void SetColor( int forecolor, int backcolor )
void SetForeColor( int color )
These functions are used when writing a Template to apply color to different variables. All variables defined after calling one of these functions will be displayed in the given color. SetForeColor sets the foreground (text) color, and SetBackColor sets the background color. Use SetColor to set both the foreground and background color at the same time. A color is an integer made up of 3 hex bytes specifying the blue, green, and red components of the color. The following constants are defined and may be used when setting colors:

• cBlack - 0x000000
• cRed - 0x0000ff
• cDkRed - 0x000080
• cLtRed - 0x8080ff
• cGreen - 0x00ff00
• cDkGreen - 0x008000
• cLtGreen - 0x80ff80
• cBlue - 0xff0000
• cDkBlue - 0x800000
• cLtBlue - 0xff8080
• cPurple - 0xff00ff
• cDkPurple - 0x800080
• cLtPurple - 0xffe0ff
• cAqua - 0xffff00
• cDkAqua - 0x808000
• cLtAqua - 0xffffe0
• cYellow - 0x00ffff
• cDkYellow - 0x008080
• cLtYellow - 0x80ffff
• cDkGray - 0x404040
• cGray - 0x808080,
• cSilver - 0xc0c0c0,
• cLtGray - 0xe0e0e0
• cWhite - 0xffffff
• cNone - 0xffffffff

The cNone constant indicates that no color should be applied. When a dark Theme is used for the editor, any background colors are automatically darkened and see the ThemeAutoScaleColors function for more information. See GetBackColor and GetForeColor to get the value of the currently active color.

void SetBytesPerLine( int bytesPerLine )
When displaying a file in the Hex Editor, calling this function allows overriding the number of bytes per line of the editor. Usually the number of bytes per line comes from the current Edit As and is set using the 'View > Line Width' menu. Setting a bytesPerLine value of 0 uses the default value from the Edit As. If a value is set with this function and then a new value is chosen with the 'View > Line Width' menu, the value set with this function will be discarded. Currently the maximum bytes per line accepted is 1024.

int SetClipboardIndex( int index )
Sets which clipboard is the currently active clipboard. An index value of 0 indicates the normal system clipboard and a value of 1 through 9 indicates one of the custom clipboards. All clipboard functions including CopyToClipboard, PasteFromClipboard, etc. operate on the currently active clipboard. See the GetClipboardIndex function to retrieve which clipboard is active and see Using the Clipboard for more information on using multiple clipboards. Note that setting the clipboard index effects the whole application and the selected clipboard will remain active after the script has finished executing. See the Status Bar for a visual indication of which clipboard is active.

void SetCursorPos( int64 pos )
Sets the cursor/caret position in the current file to local address pos. A flashing caret will visually indicate the cursor position in the file.

void SetDisplayFormat( int format )
Sets the current variable display format to format and see GetDisplayFormat for a list of constants that can be passed to this function. The functions DisplayFormatBinary, DisplayFormatDecimal, DisplayFormatHex, DisplayFormatOctal should generally be used instead of this function. Any variable created after calling this function will be assigned the current variable display format, or the display format can be defined for a variable using the syntax <format=hex|decimal|octal|binary> while creating the variable.

int SetEnv( const char str[], const char value[] )
Attempts to set the system environment variable indicated by str to the given value (both str and value are UTF-8 strings). Note that the environment variable changes are only local to the 010 Editor process, so when 010 Editor is closed the changes will be lost. Returns 0 on success or a negative number on failure.

int SetFileAttributesUnix( int attributes )
Sets the file attributes of the current Unix or Macintosh file to attributes. The attributes are a bit flag composed of the constants listed in the GetFileAttributesUnix function. This function returns true if the file is on a Unix or Macintosh operating system and the attributes were set properly, or false otherwise. For example:

      int flags = GetFileAttributesUnix();
      if( flags != FILEATTR_INVALID )
          SetFileAttributesUnix( flags & ~(FILEATTR_READ_USER) ); 

int SetFileAttributesWin( int attributes )
Sets the file attributes of the current Windows file to the given attributes. The attributes are a bit flag made up of the constants in the GetFileAttributesWin function. This function returns true if the file is a valid Windows file and the attributes were set properly, or returns false otherwise. For example:

      int flags = GetFileAttributesWin();
      if( flags != FILEATTR_INVALID )
          SetFileAttributesWin( flags | FILEATTR_READONLY );

void SetFileCharSet( int charsetId )
Sets the character set for the current file to charsetId. charsetId is an integer constant representing a character set and the list of constants is available in the ConvertString function. Use GetFileCharSet to retrieve the character set used by the current file. Note that setting the character set only affects the current file and does not modify other files that use the same Edit As.

int SetFileInterface( const char name[] )
Sets the Edit As of the current file to the Edit As with the given name. The current Edit As of the file can be returned using the GetFileInterface function. The list of valid Edit As names is found in the 'View > Edit As' menu (for example: "Hex", "Text", or "Unicode"). This functions returns 0 if the change was successful or a negative number if the Edit As could not be found.

void SetKeepFileTime( int keeptime )
Sets the keep file time of the current file to keeptime. If keeptime is true and the file is saved, the file modified time on disk will not be changed. If keeptime is false and a file is saved then the file modified time will change. Most files have keep file time set to false. See GetKeepFileTime to query the current keep file time of the active file. Note that this function can only be called in a script.

void SetMouseWheelScrollSpeed( int speed )
Sets the number of lines that are scrolled each time a scroll wheel on a mouse is clicked forward or backward. The scroll speed is also listed in the Editor Options dialog and the scroll speed can be investigated with the GetMouseWheelScrollSpeed function.

int SetReadOnly( int readonly )
Sets the read-only status of the current file to true or false. A negative number is returned if the read-only status could not be changed.

void SetSelection( int64 start, int64 size )
Selects size bytes from the file starting at the local address start. The selected bytes will appear blue in the main window.

void SetStartingAddress( int64 address )
Sets the starting address of the file to address, which is given in file coordinates. The starting address is the address of the first byte in the file shown in the Hex Editor. The starting address is typically 0 unless a custom starting address was assigned to the file. See the GetStartingAddress function to query the current starting address.

void SetStyle( int style )
Sets both the current foreground and background color to the color indicated by the style constant. A list of available style constants is given in the Template Styles sections. Any variable created after calling SetStyle will have that foreground and background color applied. Calling this function removes any colors set by SetForeColor or SetBackColor. Styles can also be set using the <style=???> syntax. The sNone constant can be used when calling SetStyle to clear any styles (the colors are set to cNone). Use GetStyle to query the current set style or use GetStyleForeColor/GetStyleBackColor to retrieve the current colors for a certain style.

void SetUnoptimizedArraysCollapsible( int collapsible )
Sets whether unoptimized arrays can be opened or closed using a parent node in the Template Results. The value of collapsible should be either true or false and use GetUnoptimizedArraysCollapsible to query the initial value when the template is run. Starting in version 13, by default arrays are collapsible but this function can be used to turn off the collapsible node if that causes unexpected results in older templates. Consult the Optimizing Arrays of Structs help topic for more information.

int SetWorkingDirectory( const char dir[] )
int SetWorkingDirectoryW( const wchar_t dir[] )
Sets the current working directory of the application to the directory dir. The current working directory can be retrieved using the GetWorkingDirectory or GetWorkingDirectoryW functions. This functions returns 0 if the directory is valid and could be set, or a negative number if the directory is not valid.

void Sleep( int milliseconds )
Halts program execution for the given number of milliseconds. For example, 'Sleep(2000);' would cause a pause of two seconds. Note that for sleeps of more than 1000 milliseconds the screen is automatically repainted before the sleep occurs.

void StatusMessage( const char format[] [, argument, ... ] )
Similar to the Printf function except the resulting string is displayed in the Status Bar of the application as a normal status message. See also the Warning function.

void ThemeAutoScaleColors( int autoScale, float scaleFactor=0.5f )
Background colors in a Template can be specified with either the bgcolor special attribute or with the SetBackColor function. When the editor is using a dark Theme the background colors are multiplied by a scale factor which effectively darkens the colors to fit in with the dark theme. To turn off this scaling call the ThemeAutoScaleColors function with autoScale set to false. To adjust the scale factor set autoScale to true and set the scale factor using scaleFactor. Scale factors between 0 and 1.0 are accepted and 0.5 is the default. To check if the current theme is dark see the ThemeIsDark function.

int ThemeIsDark()
Returns true if the current Theme uses a dark color for the Editor background or returns false if the current Theme uses a light color for the Editor background. Note that colors applied using a Template automatically adjust their colors when being used on a dark theme and see the ThemeAutoScaleColors function to control this.

void Terminate( int force=true )
Exits out of the script and then shuts down 010 Editor. If force is true, all open files will be closed and any unsaved modifications will be lost. If force is false and files are modified, the user will be asked if they want to save the files and optionally given a chance to cancel the shut down procedure.

void Warning( const char format[] [, argument, ... ] )
Similar to the Printf function except the resulting string is displayed in the Status Bar of the application and is highlighted orange. This is useful to display an error that occurs in a Template. See also the StatusMessage function.