ConEmu
Windows Terminal

ConEmu GuiMacro

GUI macros are the set of functions allowing to control ConEmu window and its consoles.

GuiMacro may be triggered from many places, for example from command line or keypress.

Contents

How GuiMacro may be executed

1. ConEmu hotkeys ‘Macro 01’ … ‘Macro 32’

Just set up ‘Macro 01’ … ‘Macro 32’ on ‘Keys’ page of ‘Settings’ dialog.

2. ConEmuC -GuiMacro switch

NB. This does not work in WSL!

If you may call ConEmuC.exe (command line, batch file, etc.) then you may use ConEmuC -GuiMacro switch. The format is flexible, few examples below.

"%ConEmuBaseDir%\ConEmuC.exe" /GUIMACRO WindowMinimize
ConEmuC -GuiMacro palette 1 "<Solarized>" -guimacro WindowMaximize
ConEmuC -guimacro status 1 test
ConEmuC -Guimacro Flash(1,3,5) ; MsgBox("Notification text")
ConEmuC -GuiMacro:0 print: C:\Program Files (x86)\Adobe\Reader 10.0\Reader\AcroRd32

3. [From shortcut (ConEmu and ConEmu64)]

ConEmu.exe -Detached -GuiMacro "Create(0,1); Context; print(\"echo \\\"Hello world\\\"\");"

4. ANSI OSC code

The following is only a demo, if you need to check ‘IsConEmu’ it is better to call "ConEmuC -IsConEmu" and check %errorlevel%.

rem We need real ESC code (symbol with ASCII \x1B) in cmd scripts
call SetEscChar.cmd
echo %ESC%]9;6;"IsConEmu"%ESC%\
if "%ConEmuMacroResult%"=="Yes" echo ConEmu found!

5. Via Far Manager plugin

NB. Far Manager 1.7x, 2.0, 3.0 are supported.

F11 -> ConEmu -> Execute ConEmu macro

6. Via Far Manager macros, Far3-lua

Plugin.SyncCall("4b675d80-1d4a-4ea9-8436-fdc23f2fc14b","IsConEmu()")

7. Far3-pre-lua (callplugin is alias of Plugin.Call)

Plugin.Call("4b675d80-1d4a-4ea9-8436-fdc23f2fc14b","IsConEmu()")

8. Far2

callplugin(0x43454D55,"IsConEmu()")

Syntax

ConEmu GuiMacro parser is flexible and support different styles.

Styles of arguments specification

  • surrounded by brackets:
Function(Arguments)
  • delimited by space:
Function Arguments
  • delimited by colon (and space optionally):
Function: Arguments

Note Using colon-style you may easily pass one-string-argument. Other methods may require quotating, backslash-escaping or verbatim strings.

print: C:\Program Files (x86)\Adobe\Reader 10.0\Reader\AcroRd32
  or
print("C:\\Program Files (x86)\\Adobe\Reader 10.0\\Reader\\AcroRd32")
  or
print(@"C:\Program Files (x86)\Adobe\Reader 10.0\Reader\AcroRd32")

Specifying more that a one argument

  • delimited by commas:
Function(Arg1,Arg2,Arg3)
  • delimited by spaces:
Function Arg1 Arg2 Arg3

Executing several functions at once

  • delimited by semicolons:
print("abc"); keys("^_"); print("def")
  • delimited by -GuiMacro when called from your shell prompt:
ConEmuC -GuiMacro print abc -GuiMacro keys "^_" -GuiMacro print def

Numerical arguments

  • decimal form with leading optional ‘+’ or ‘-’:
FontSetSize(1,-1)
  • hexadecimal form with ‘0x’ or ‘0X’ prefix:
MsgBox("Text","Title",0x132)

String arguments

It is recommended to put string arguments in doublequotes, but in fact that is not required for ‘one-word’ arguments.

C-style strings

Backslashes and doublequotes must be escaped with backslashes.

Special symbols can be specified using escaped form:

\\  --> \
\"  --> "
\r  --> Carriage return (ASCII 13)
\n  --> New line (ASCII 10)
\t  --> Horizontal tab (ASCII 9)
\b  --> Backspace (ASCII 8)
\e  --> Escape (ASCII 27)
\a  --> Alert (ASCII 7)

And hexadecimal form \xNNNN (up to 4 digits) may be used to specify exact unicode character:

\x1B   --> same as \e (ASCII 27)
\x044F --> russian ‘я’ letter

Example:

print("\eCD /d \"C:\\Users\"\n")

Verbatim strings

No ‘escaped’ symbols, with the only exception of doublequote - they must be doubled.

print(@"CD /d ""C:\Users""")

Far plugin notes

When you run some GuiMacro’s from Far Manager macro and the string has backslashes ("C:\\Users\\...") you need to use verbatim strings or double-double them because ConEmu GuiMacro parser always parse escaped symbols itself. The GuiMacro may be called from many places (from command line for example) and parser is the one for all inputs.

Plugin.SyncCall("4b675d80-1d4a-4ea9-8436-fdc23f2fc14b","shell(\"new_console\",@\""..win.GetEnv("FARHOME").."\\far.exe\")")

Command line (ConEmuC and ConEmuC64)

It doesn’t matter ConEmuC.exe or ConEmuC64.exe you are using.

Syntax:

ConEmuC [/SILENT] /GuiMacro[:PID|HWND][:T<tab>][:S<split>] <GuiMacro command>
  or
ConEmuC [-Silent] -GuiMacro[:PID|HWND][:T<tab>][:S<split>] <GuiMacro command>
SILENT Suppress output of GuiMacro result (OK, FAILED, etc.)
PID ‘Process ID’, decimal number
0 Special value means ‘Use active tab/split of the first found ConEmu window
ConEmu GUI PID ConEmu.exe or ConEmu64.exe, macro will be executed in the active tab/split
Console server PID ConEmuC.exe or ConEmuC64.exe started with /ROOT argument
HWND Window descriptor, hexadecimal number with x prefix
ConEmu GUI HWND Main ConEmu window, macro will be executed in the active tab/split
Console server HWND The hidden real console window
T<tab> Changes affected RealConsole, ‘tab’, decimal 1-based tab index
S<split> Changes affected RealConsole, ‘split’, decimal 1-based pane index of selected/active group of panes

When GUI macro executed, ConEmuC.exe set errorlevel to 0 and write result to ‘StdOut’.

When you execute macro without PID or HWND,

ConEmuC -GuiMacro print abc

your macro will be executed in the current console (tab/split), if it was started in ConEmu. On the other hand, if you try to call that outside of ConEmu, execution will fails with ‘%errorlevel% == 134’, because your console (where you are trying to execute macro) is not a ConEmu console.

So, if you need to execute macro from any external application (Visual Studio, Sublime text, even from Win+R) you may specify exact instance with PID or HWND.

  • PID must be decimal number.
  • HWND must be specified as hexadecimal number (window descriptor) with ‘x’ prefix.

Exact values you may see in the ConEmu status bar, in the Windows Task Manager, or find yourself using Windows API.

Few examples:

ConEmuC -GuiMacro:0 print: C:\Program Files (x86)\Adobe\Reader 10.0\Reader\AcroRd32
  or
ConEmuC -GuiMacro:8204 print "This is sample text"
  or
ConEmuC -GuiMacro:x140F32 WindowMinimize

Run from shortcut (ConEmu and ConEmu64)

If you need to run some GuiMacro(s) after ConEmu starts user may use -GuiMacro switch with ConEmu.exe or ConEmu64.exe. Only one -GuiMacro switch may be specified, but you may delimit functions with semicolon. Also, double quotes and backslashes must be properly escaped within string arguments.

The following example will start ConEmu window without tabs, show ‘Create new console’ dialog and prints into the created console echo "Hello world".

ConEmu.exe -Detached -GuiMacro "Create(0,1); Context; print(\"echo \\\"Hello world\\\"\");"

Far Manager plugin

You may run GuiMacro from Far Plugin (ConEmu.dll / ConEmu64.dll) from:

  • Using menu command: F11 -> ConEmu -> Execute ConEmu macro
  • Using Far Manager macro language, Far v3.x Lua:
Plugin.SyncCall("4b675d80-1d4a-4ea9-8436-fdc23f2fc14b","IsConEmu()")
  • Far v3.x pre Lua:
Plugin.Call("4b675d80-1d4a-4ea9-8436-fdc23f2fc14b","IsConEmu()")
  • Far v2.x:
callplugin(0x43454D55,"IsConEmu()")

When you call plugin menu, result is show in the dialog field.

When you use Far Manager macro, the result is placed to the