Overview
Examples
Screenshots
Comparisons
Applications
Download
Documentation
Tutorials
Bazaar
Status & Roadmap
FAQ
Authors & License
Forums
Funding Ultimate++
Search on this site













SourceForge.net Logo

TheIDE Macros

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.

 

Last edit by klugier on 10/09/2016. Do you want to contribute?. T++