2.13. Lua Scripting

DC.LogWrite(Message, MsgType, bForce, bLogFile)

Write a message to the log window.

Here is the description of each field:

• Message : The message text.
• MsgType : The message type: 0 - information, 1 - success, 2 - error.
• bForce : A boolean, when true, will show the log window if invisible.
• bLogFile : A boolean, when true, will write the message also in the log file.

iPanel = DC.CurrentPanel()

Get active panel: returns 0 if left panel is active or 1 if right.

DC.CurrentPanel(iPanel)

Set active panel: left panel if iPanel equal 0 or right if 1.

DC.ExecuteCommand(Command, Param1, Param2,...,ParamX)

This allows the script to invoke internal commands of DC.

The Command is holding the actual internal command name.

We may provide as many Param... as command may support.

SysUtils.Sleep(Milliseconds)

Suspends the execution of the script for the specified number of Milliseconds.
After the specified period has expired, script execution resumes.

SysUtils.GetTickCount()

Returns an increasing clock tick count. It is useful for time measurements, but no assumptions should be made as to the interval between the ticks.

bFlagExists = SysUtils.FileExists(FileName)

Check whether a particular file exists in the filesystem.

Returns in bFlagExists the value true if file with name FileName exists on the disk, or false otherwise.

bFlagExists = SysUtils.DirectoryExists(Directory)

Checks whether Directory exists in the filesystem and is actually a directory.

If this is the case, the function returns in bFlagExists the value true otherwise false is returned.

Attr = SysUtils.FileGetAttr(FileName)

Returns in Attr the attribute settings of file FileName.

See the detail explanations of the returned value here.

Handle, FindData = SysUtils.FindFirst(Path)

Looks for files that match the Path, generally with wildcards.

If no file is found, Handle will be nil.

When at least one item is found, the returned Handle may be used in subsequent SysUtils.FindNext to find other occurences of the same pattern.

The FindData table contains information about the file or directory found.

The field of the FindData table are:

• Name : The file name (without path).
• Attr : The file attributes of the file (see details here).
• Size : The size of the file in bytes.
• Time : The time stamp of the file (seconds since Jan 01 1970)

Result, FindData = SysUtils.FindNext(Handle)

Finds the next occurrence of a search sequence initiated by FindFirst by re-using the Handle returned previously.

Returned Result will be non-nil if a file or directory is found and will be nil otherwise.

The same notes mentioned for SysUtils.FindFirst applied here.

Remark: The last SysUtils.FindNext call must always be followed by a SysUtils.FindClose call with the same Handle. Failure to do so will result in memory leaks.

SysUtils.FindClose(Handle)

Ends a series of SysUtils.FindFirst/SysUtils.FindNext calls.

Frees any memory used by these calls.

It is absolutely necessary to do this call, or memory losses may occur.

bResult = SysUtils.CreateDirectory(Directory)

Create a chain of directories, Directory is the full path to directory.

Returns true if Directory already exist or was created successfully. If it failed to create any of the parts, false is returned.

bResult = SysUtils.CreateHardLink(Path, LinkName)

Create the hard link LinkName to file Path.

Returns true if successful, false otherwise.

bResult = SysUtils.CreateSymbolicLink(Path, LinkName)

Create the symbolic link LinkName to file or directory Path.

Returns true if successful, false otherwise.

sTarget = SysUtils.ReadSymbolicLink(LinkName, Recursive)

Read destination of the symbolic link LinkName.

If Recursive is true and the link points to a link then it's resolved recursively until a valid file name that is not a link is found.

Returns the path where the symbolic link LinkName is pointing to or an empty string when the link is invalid or the file it points to does not exist and Recursive is true.

sName = SysUtils.ExtractFileName(FileName)

Extract the filename part from a full path filename.

The filename consists of all characters after the last directory separator character ("/" or "\") or drive letter.

sPath = SysUtils.ExtractFilePath(FileName)

Extract the path from a filename (including drive letter).

The path consists of all characters before the last directory separator character ("/" or "\"), including the directory separator itself.

sDir = SysUtils.ExtractFileDir(FileName)

Extract only the directory part of FileName, including a drive letter.

The directory name has NO ending directory separator, in difference with SysUtils.ExtractFilePath.

sDrive = SysUtils.ExtractFileDrive(FileName)

Extract the drive part from a filename.

Note that some operating systems do not support drive letters.

sExt = SysUtils.ExtractFileExt(FileName)

Return the extension from a filename (all characters after the last "." (dot), including the "." character).

sName = SysUtils.GetAbsolutePath(FileName, BaseDirectory)

Returns the absolute (full) path to the file:

• FileName : The filename with a relative path.
• BaseDirectory : The directory that was used as the base directory for FileName.

sName = SysUtils.GetRelativePath(FileName, BaseDirectory)

Returns the filename relative to the specified directory:

• FileName : The full (absolute) filename.
• BaseDirectory : The directory that will be used as the base directory FileName.

If FileName and BaseDirectory contain the same value, the function will return an empty string ("").

bResult = SysUtils.MatchesMask(FileName, Mask, MaskOptions)

Returns true if FileName matches the passed mask Mask.

MaskOptions (optional parameter, 0 by default) is set as the sum of the following values:

bResult = SysUtils.MatchesMaskList(FileName, MaskList, Separator, MaskOptions)

Returns true if FileName matches at least one of passed masks MaskList separated by Separator (";" by default).

Separator and MaskOptions (see above) are optional parameters.

SysUtils.PathDelim

Allows a script to get from DC the system path delimiter.

In Unix/Linux system will be a " / " and in Windows will be " \ "

Clipbrd.Clear()

Clear the content of the clipboard.

StringVar = Clipbrd.GetAsText()

Get the current text content of the clipboard to assigned it to StringVar.

Clipbrd.SetAsText(StringVar)

Store in the clipboard the text content of StringVar.

Clipbrd.SetAsHtml(Html)

Adds html-formatted text Html to the clipboard (CF_HTML clipboard format).

This contents will be inserted in applications which support this clipboard format, like MS Word, LO Writer, etc.

It's correct to store data with both Clipbrd.SetAsText and Clipbrd.SetAsHtml. When we'll paste, the application will use the best one that it supports.

For example we may have this:

• Clipbrd.SetAsText("Welcome to Double Commander!")
• Clipbrd.SetAsHtml("Welcome to <B>Double Commander</b>!")

If we switch to Notepad attempting to paste something, it will paste in plain text the message we copied with Clipbrd.SetAsText. But if we switch to Microsoft Word and paste something, it will paste the second one, the one with Double Commander in bold since the Microsoft Word recognize and support that clipboard content type.

ButPressed = Dialogs.MessageBox(Message, Title, ButFlags)

Will diplay a message box prompting a user to click a button which will be returned by the function.

Here is the description of each field:

• Message : The message inside the box.
• Title : The text displayed as the title of the box.
• ButFlags : OR'ed value of constants to determine the buttons that will be displayed, the style of window and default button selected for the answer. See the following table the buttons displayed, style of window or default button.
• ButPressed : Returned value indicating the button user pressed (see this table).

bAck, sAnswer = Dialogs.InputQuery(Title, Msg, bMask, sDefault)

Will display a requester box where user may enter a string value.

Here is the description of each field:

• Title : The text displayed as the title of the box.
• Msg : The message inside the box.
• bMask : A boolean, when true, will display "stars" to hide characters.
• sDefault : The default suggested text that user may type over if necessary.
• bAck : Returned boolean indicating if user effectively enter something or not.
• sAnswer : Returned string when user entered something and then clicked ok.

sAnswer = Dialogs.InputListBox(Title, Msg, Items, sDefault)

Displays a dialog box to allow the user to choose from a list of items.

Here is the description of each field:

• Title : The text displayed as the title of the dialog.
• Msg : The message inside the dialog.
• Items : A Lua table, each element of the table must be a string.
• sDefault : The default selected item in the list.
• sAnswer : Returned the selected item as a string or nil if the dialog is dismissed.

Result = LazUtf8.Pos(SearchText, SourceText, Offset)

Search for substring in a string, starting at a certain position. The search is case sensitive.

Returns the position of the first occurrence of the substring SearchText in the string SourceText, starting the search at position Offset (default 1).

If SearchText does not occur in SourceText after the given Offset, zero is returned.

Result = LazUtf8.Copy(Source, Index, Count)

Copy part of a string.

Copy returns a string which is a copy if the Count characters in Source, starting at position Index.

If Count is larger than the length of the string Source, the result is truncated. If Index is larger than the length of the string Source, then an empty string is returned.

Result = LazUtf8.Length(String)

Returns the number of UTF-8 characters in the string.

Result = LazUtf8.UpperCase(String)

Receives a string and returns a copy of this string with all lowercase letters changed to uppercase.

Result = LazUtf8.LowerCase(String)

Receives a string and returns a copy of this string with all uppercase letters changed to lowercase.

Result = LazUtf8.ConvertEncoding(String, FromEnc, ToEnc)

Convert String encoding from FromEnc to ToEnc.

List of supported encoding values:

• Default system encoding (depends on user locale): "default".
• Default ANSI (Windows) encoding (depends on user locale): "ansi".
• Default OEM (DOS) encoding (depends on user locale): "oem".
• Unicode: "utf8", "utf8bom", "ucs2le", "ucs2be".
• ANSI (Windows): "cp1250", "cp1251", "cp1252", "cp1253", "cp1254", "cp1255", "cp1256", "cp1257", "cp1258".
• OEM (DOS): "cp437", "cp850", "cp852", "cp866", "cp874", "cp932", "cp936", "cp949", "cp950".
• ISO 8859: "iso88591", "iso88592", "iso885915".
• Other: "macintosh", "koi8".

• "default" - cp1251
• "ansi" - cp1251
• "oem" - cp866

• "default" - utf8
• "ansi" - cp1251
• "oem" - cp866

ResultCode = os.execute(Command)

Will execute Command as it would be typed on the command-line and return the result code of the operation.

The Command could either be:

• A terminal commmand like os.execute("dir > all.txt")
• An executable like os.execute("C:\\Windows\\System32\\calc.exe")
• An executable with parameters:
  os.execute("C:\\Utils\\fsum.exe -md5 test.bin > md5.txt")

TempFileName = os.tmpname()

Will return a filename to use as a temporary filename.

bResult, ErrorStr, ErrorNum = os.remove(FileName)

Will delete the file or the directory with the name FileName.

If it works, function returns true.

If it fails, function returns three things:

1. nil to indicate it failed
2. ErrorStr for the error message description
3. ErrorNum for the error code number

bResult, ErrorStr, ErrorNum = os.rename(OldName, NewName)

Will rename the file OldName with the new name NewName.

If it works, function returns true.

If it fails, function returns three things:

1. nil to indicate it failed
2. ErrorStr for the error message description
3. ErrorNum for the error code number

Value = os.getenv(VariableName)

Will return the Value of the variable VariableName passed in parameter.
If no variable of that name exists, it will return nil.