TheIDE Macros
Table of contents
1. Overview
2. TheIDE - API
2.1 Text editing methods
2.2 File methods
2.3 User interaction methods
2.4 Build and execute methods
2.5 Informative methods
1. Overview
TheIDE macros are written in Esc scripting language and placed in .usc files. .usc files can be either part of regular packages or are placed in Common or Local directory.
Macro definition in .usc file starts with header in following form:
macro Macro_menu:Macro_item Key
where Macro_menu and Macro_item are text literals (with C syntax) and Key is key description similar to those shown in menus. Macro_menu with : and Key can be omitted. Macro header is followed by Esc body.
Examples:
macro "Navigation":"Find next \"TopWindow\"" Ctrl+T {
.Find("TopWindow");
}
macro "Insert current date" {
s = [];
tm = GetSysTime();
s << to_string(tm.year) << "-" << to_string(tm.month) << "-" << to_string(tm.day);
.Insert(s);
}
Formally, from Esc perspective, macro is a "method" of editor - all editor commands are written in "method" notation (starting with dot).
Additionally, helper functions can be defined using the fn keyword:
fn Duplicate(str) {
return str + str;
}
Functions defined like this can be simply called in the code of macros as a global functions.
2. TheIDE - API
2.1 Text editing methods
Most of text editing methods are provided in two ("overloaded") forms - implicit that works with cursor and selection or explicit with given positions.
Method
|
Description
|
GetLength()
|
Length of text.
|
GetLineCount()
|
Number of lines in text.
|
GetLinePos(line)
|
Position (offset from the beginning of the file) of the first character of line.
|
GetLineLength(line)
|
Returns the number of characters in given line.
|
GetCursor()
|
Cursor offset.
|
GetLine(position)
|
Line for given position.
|
GetColumn(position)
|
Position in line for given position.
|
GetSelBegin()
|
Start of selection.
|
GetSelCount()
|
Number of characters in selection. If zero, GetSelBegin() is equal to GetCursor().
|
SetCursor(position)
|
Sets cursor to given position.
|
SetSelection(position, count)
|
Sets selection starting with position with count characters.
|
ClearSelection()
|
Cancels selection.
|
Get(position, count)
|
Returns array of count characters, starting at position.
|
Get(position)
|
Same as Get(position, 1).
|
Remove(position, count)
|
Removes count characters at position.
|
Remove(count)
|
Same as Remove(GetCursor(), count) - removes count characters at cursor position.
|
Remove()
|
Same as Remove(GetSelBegin(), GetSelCount()) - removes selection.
|
Insert(position, text)
|
Inserts array of characters text at the position.
|
Insert(text)
|
Same as Insert(GetCursor(), text) - inserts text at cursor position.
|
Find(text, down, whole_word, ignore_case, wildcards)
|
Finds text, using give options. Options can be omitted - in that case down is considered true and rest of options false. If text is found, function returns 1, otherwise 0.
|
Replace(text, replace_with, whole_word, ignore_case, widcards)
|
Block replace, using given options. Options ca be omitted - in that case they are considered false. Returns number of strings replaced.
|
MoveLeft(...)
MoveRight(...)
MoveWordLeft(...)
MoveWordRight(...)
MoveUp(...)
MoveDown(...)
MoveHome(...)
MoveEnd(...)
MovePageUp(...)
MovePageDown(...)
MoveTextBegin(...)
MoveTextEnd(...)
MoveLeft(sel)
MoveRight(sel)
MoveWordLeft(sel)
MoveWordRight(sel)
MoveUp(sel)
MoveDown(sel)
MoveHome(sel)
MoveEnd(sel)
MovePageUp(sel)
MovePageDown(sel)
MoveTextBegin(sel)
MoveTextEnd(sel)
|
Moves cursor in given direction. Variant with sel makes selection (like when corresponding movement while pressing Shift key) if sel is 1.
|
|
2.2 File methods
This section grouped methods that allows to manipulate TheIDE files.
Method
|
Description
|
FileName()
|
Returns the name of currently edited file.
|
EditFile(path)
EditFile(filename, pkg)
|
Opens the specified file in editor.
|
SaveCurrentFile()
|
Saves file in active tab.
|
CloseFile()
|
Closes active tab.
|
|
2.3 User interaction methods
From time to time, it is necessary to communicate some information from user to the macro or vice versa, which is exactly what these methods do.
Method
|
Description
|
Input(label, ...)
|
Simple input dialog. Provides as many input text fields as is number of parameters specifying labels for these fields. If user chooses Cancel, returns void, otherwise returns single string if there is just one edit field or array of strings for multiple edit fields.
|
ClearConsole()
|
Clear the output console.
|
Echo(...)
|
Prints all arguments to the output console, one per line.
|
|
2.4 Build and execute methods
The macros can be used to extend the capabilities of TheIDE. For that, there is a few methods that allow executing other programs and also to trigger building U++ packages.
Method
|
Description
|
Execute(cmdline)
|
Executes cmdline, capturing the output to the console.
|
Launch(cmdline)
|
Launches the application.
|
Build([flags[, outfile]])
|
Builds open main package. Optional parameters can be used to specify the flags (e.g. "GUI MT") and target path for the compiled executable.
|
BuildProject(uppfile, flags[, outfile])
|
Same as previous, but works with any package specified by passing path to it's .upp file as a first parameter.
|
|
2.5 Informative methods
The methods providing information about packages and build settings. If the optional parameter pkg is not specified, the currently selected package is used.
Method
|
Description
|
ActivePackage()
|
The name of package in which the currently edited file belongs to.
|
MainPackage()
|
The name of main package.
|
AllPackages()
|
Array of all used packages.
|
PackageDir([pkg])
|
The directory where the package resides.
|
PackageFiles([pkg])
|
List of all files in the package.
|
Assembly()
|
Name of the assembly.
|
Flags()
|
Array of currently set build flags.
|
BuildMethod()
|
Currently selected build method.
|
BuildMode()
|
Currently selected build mode (0 = Debug, 1 = Optimal, 2 = Speed, 3 = Size).
|
Target()
|
Returns current target name. To obtain this value project must be firstly build.
|
|
|
