Autorun "content plugin" 1.5.0
==============================

This is simple "content" plugin for manage some actions while starting Total Commander. At first this is was the personal project, that was made for merge different autorun tasks into single interface. Now it's developing mainly for making portable version simple. It's cover the most of startup requirements. For more advanced or specific actions is more reasonable run the script or create plugin in traditional language. 

This plugin is a simple command processor that executes commands from text configuration file. All commands executes in the separate thread and should not freeze TC in case of problem in one of commands. It's possible to use variables and simple If..Else condition.

Installation
------------
Before installing plugin recommend to rename autorun.example.cfg file into autorun.cfg, and edit it if needed. Installation of plugin is usual for content plugins. Next, in order to load plugin at Total Commander start, you should create the fictitious color scheme:

 On the "Color" page press "Define colors by file type..." button. 
 In the "Define colors by file type" dialog set cursor in any place in the list, and press "Add..." button. 
 Press "Define..." button. 
 In the "Define selection" dialog move to "Plugins" tab.
 Select in "Plugin" dropdown list "autorun".
 Select in "Property" dropdown list "Autorun" (there will not be more properties).
 Select in "OP" dropdown list "=" and set in following field any integer, for example 1. 
 Press "Save" button, give the template some name , for example "Autorun".
 Next, repeatedly press OK  button in all dialogs until options dialog will be closed.
 Restart TC.

If you have many color schemes, it's recommended to move Autorun scheme to the top of list, else it can not run sometimes.

Plugin can be renamed, in this case change the name of configuration file correspondingly.

History
-------
1.5.0 - Added %AUTORUN_ISADMIN% constant
1.4.9.6 beta - CommandExec rewritten
1.4.9.5 beta - fixed closing routines
1.4.9.4 beta - added /W for ShellExec
1.4.9.3 beta - added /TT for ShellExec
1.4.9.2 beta - added /T for ShellExec, added AutorunBlockUnload command, fixed versioninfo
1.4.9.1 beta - added variables (Set), conditional expression, LoadFont, messages translation
1.4.7 - added IniDelete command
1.4.6 - fixed lockup on empty lines in configuration file
1.4.5 - small fix in expand variables function, removed limitation of using mixed quotes
1.4.4 - fixed installation via TC Plugin Manager, added version info
1.4.3 - fixed bug when environment variable become empty in append mode, if it's initial length was big enough
1.4.2 - added /AD parameter for SetEnv command (read the note)
1.4.1 - fixed TC crash when calling cm_UnloadPlugins
1.4 - changed handling of optional parameters/switches, added ability for loading libraries, added plugins, added IniWrite
1.3 - added showing parameters for ShellExecute command, value of Autorun field can be compared to anything
1.2 - first public version, script-like configuration file instead .ini
1.1 - added environment variables support and some other improvements
1.0 - first version, three commans, keep config in .ini file

Plans
-----
At first this is was the personal project, that was made for myself. I think it cover the most of startup requirements. For more advanced or specific actions is more reasonable run the script or create plugin in traditional language. 
Bug reports are welcome. Suggestions too, but they can be added in "core" only if they are universal enough. 
NO visual configurators are planned at all.

Variables
---------
Plugin operate with two kinds of variables - internal and environment. The only difference - internal variables are visible only in plugin, where environment variables are available for Total Commander and programs called from TC.
In common, variable is alphanumeric string, enclosed with "%" signs. Internal variables are defined with Set command, environment variables -  with SetEnv.

Also, autorun have few predefined variables (constants):
%AUTORUN_OSARCH% - architecrure of OS where TC is running. This can be either 32 or 64.
%AUTORUN_OSVERSION% - version of OS where TC is running. This can be one of:

WIN_UNKNOWN, WIN_95, WIN_98, WIN_ME, WIN_NT, WIN_2000, WIN_XP, WIN_2003, WIN_VISTA, WIN_2008, WIN_7, WIN_2008R2

%AUTORUN_DESKTOPWIDTH% - desktop width.
%AUTORUN_DESKTOPHEIGHT% - desktop height.
%AUTORUN_DESKTOPDEPTH% - desktop depth.
%AUTORUN_TCHANDLE% - Total Commander's window handle (for using in scripts).
%AUTORUN_ISADMIN% - return 1 is TC executed under admin, 0 otherwise

Redefine the predefined constants are not allowed.

Conditional
-----------
Here is one and only conditional statement:

If <expression 1> <operator> <expression 2> Then
  ...
ElseIf <expression 3> <operator> <expression 4> Then
  ...
Else
  ...
EndIf

Simple conditional statement. For numeric comparison operator can be one of: ==, !=, >, <, >=, <=. For string comparison only == and != allowed, comparison is case insensitive. Variables are always expanding in the expressions. If both expressions are numeric, then numeric comparison used. 

Note the spaces between keywords, expressions and operator, all they are mandatory. Also, numeric expressions are not calculated here, use Set command for that.

Commands
--------
AutorunBlockUnload <True/False> - command blocking the plugin unloading (with cm_UnloadPlugins) till the TC closing. Useful when using ShellExec with /T. When command is not using, blocking disabled.

Set [/C] | [/EV] [/EE] <var name> <var text>
Sets internal variable. All internal variables are text, but can be treated as numeric in comparison.
[/C] - treat var text as numeric and calculate the expression. Four aritmetic operations and parenthesis are supported, variables (environment too) are always expanding.
[/EV] - enbables using environment variable in text.  
[/EE] - enbables using escape characters in text.

Note: when using /C parameter, any non-numeric string lead to zero, /EV /EE parameters are not taking in account.

SendCommand <command>
Sends to TC it's internal command. Can be literal (values retrieving from TOTALCMD.INC) or numeric.

ShellExec [/EV] [/SW_HIDE|/SW_SHOWNORMAL|/SW_MINIMIZE|/SW_MAXIMIZE] [/T|/TT] [/W[:####]] <filename> [<parameters> [<working dir>]]
Executes the file. If no params are set, but you need to set working directory, use empty string (two consecutive quotes). Any environment variable can be used in any path.
Optional parameters:
[/EV] - enbables using environment variables also in parameters.
[/SW_HIDE] - hidden
[/SW_SHOWNORMAL] - normal (by default), also using when no explicit SW_* parameter set
[/SW_MINIMIZE] - minimized
[/SW_MAXIMIZE] - maximized to all screen
[/T] - terminate program when plugin unloading (also look AutorunBlockUnload command)
[/TT] - terminate program tree when plugin unloading
[/W] - trying to close process window before program terminating. Default closing timeout 1000 ms. After parameter can be optional value that sets timeout, ex: /W:5000. This parameter can be used only with /T or /TT paramaters.

CommandExec [/CD[:T|S|TS]] <command/path1> [<path2>]
Execute user command em_*** or set paths in the panels.
[/CD] - first and optional secons paramaters - paths for setting in panels.  After parameter can be optional flags how to set paths: T - open in new tab, S - make first path as source, second as target, else left and right panels  accordingly, ST - combination of parameters.

SetEnv [/A] [/EV] [/EE] <var name> <var text>
Sets environment variable for current process. 
Optional parameters:
[/A] - appends a text to exising variable text (replacing instead).
[/AD] - the same as /A, but allow duplicating (look note)
[/EV] - enbables using environment variable in text.
[/EE] - enbables using escape characters in text.

Note: by default, when using parameter /A, plugin is checking if text at the end of variable's text the same as text being added, and not adding it repeatedly. This allow to avoid the case when text is repeatedly adding when you restart TC or unload plugin by cm_UnloadPlugins. If you still need to add text without this check use /AD.

Usage example: place "noclose.pif" in TC folder and add this path to the PATH variable for current process, after that Shift+Enter command will work correctly without placing this file to windows directory (portable mode).

Sleep <delay>
Delay before executing next command in milliseconds.

IniDelete <ini name> <section> [<key>]
Deleting key or section from given configuration file.
If <key> is omitted, the whole section will be deleted. Use carefully!

IniRead <var name> <ini name> <section> <key> [<default value>]
Read the value from given configuration file. 
First parameter should be name of variable. If variable not exists, it will be created. Default value is the value that will be returned in case of function failure (error with file, missed key etc.)

IniWrite [/EV] <ini name> <section> <key> [<value>]
Writing value into given configuration file.
Optional parameters:
[/EV] - enbables using environment variable in value.
This command is partucularly useful in portable compilations for fixing paths for some programs that are not smart enough to run in any place.

Language <ID>
Load custom language for messages from autorun.lng file. If this command absent the default language (English) will be used.

LoadFont [/N] <font name>
Command that loading selecting font. By default this font will be available in Total Commander process only and will be unloaded when TC is closed.
[/N] - allow other applications using this font. Note, that font still become unavailable when TC is closed.

LoadLibrary [/U] <dll name> [<function>]
Command that loading a dynamic library (paths can be relative to plugin path). Also can execute parameterless function.
Optional parameters:
[/U] - dll will be unloaded immediately after loading and executing function (if this set).

This command also loading plugins, read more about in corresponding section.

Note: code that executing while library initialization, running in the main thread, so when using blocking functions (like MessageBox), the Total Commander loading will be suspended. In order to avoid this, don't use those functions in the initializing code, or use explicit function call.

Notes
-----
If space used in command parameter, take it into quotes - double or single. In this case quotes of another type can be used in text. If you need to use in text quotes of both types, the quote of type that opens parameter should be doubled in the text. Example: "this ""text"" is quoted"
Line that begin with # treating as comment. Empty lines are ignoring.
Optional named parameters should start with "/" and should be placed before mandatory parameters.

Plugins
-------
If needed to use own commands with parameters, it's possible to use plugins. They are loading with LoadLibrary command.

One example plugin already included in the distributive, it intended to moving the "Options" button in the copy/move dialogs of Total Commander (since it's new position starting from TC 7.50 don't liked by many people). After loading plugin with LoadLibrary the new command become enabled:

MoveOptionsButton <MOVE_LEGACY|MOVE_RIGHT>
It's parameter can be one of:
[MOVE_LEGACY] - moving button to position as in versions prior 7.5
[MOVE_RIGHT] - moving button to right side of dialog
The command can be executed only once, following calls are ignoring. Plugin works correctly only for TC version 7.55 and up.
 
For developers
--------------
When loading library with LoadLibrary, Autorun is trying to find Autorun_PluginInit function, if this is found, calling it and retreive list of names of user commands, supported by plugin. List should be separated by pipe char "|". Also, function get the AutorunInfo type structure with some useful information, that can be used in plugin (so far only TC window handle).

Delphi interface:

type
  PAutorunInfo = ^TAutorunInfo;
  TAutorunInfo = record
    nSize: integer;  // struct size
    hWnd: HWND;      // window handle of current TC copy
  end;

procedure Autorun_PluginInit(Info: PAutorunInfo; FuncList: PAnsiChar; MaxListSize: integer); stdcall;

If not set "unload" parameter and list of command names is not empty, those names are adding in the list of supported commands and they are can be used in following execution. For that in the plugin should be Autorun_ExecFunc function:
 
type 
  TAnsiCharArray = array of PAnsiChar;
  PAnsiCharArray = ^TAnsiCharArray;

function Autorun_ExecFunc(FuncName: PAnsiChar; Param: PAnsiCharArray; ParamCount: integer): integer; stdcall;

Function return one of following values:
  AU_OK = 0;
  AU_NOSUCHFUNC = 1;

C++ interface:

  struct AutorunInfo
  {
    int nSize;    // struct size
    HWND hWnd;    // window handle of current TC copy
  };

void __stdcall Autorun_PluginInit(const AutorunInfo* Info, char* FuncList, int MaxListSize); 
int __stdcall Autorun_ExecFunc(const char* FuncName, const char** Param, int ParamCount);

Copyright (c) 2010-2011 Dmitry Yudin