plugins.wlx
Interface WLXPluginInterface

All Known Implementing Classes:

SwingWLXPlugin, SWTWLXPlugin, WLXPluginAdapter

public interface WLXPluginInterface

This is the interface for Total Commander WLX plugins.

Author:

Ken Händel

Field Summary

static int	LC_COPY listSendCommand: Copy current selection to the clipboard.
static int	LC_NEWPARAMS listSendCommand: New parameters passed to plugin, see LCP_* constants.
static int	LC_SELECT_ALL listSendCommand: Select the whole contents.
static int	LC_SETPERCENT listSendCommand: Go to new position in document (in percent).
static int	LCP_ANSI listSendCommand: Ansi charset is checked.
static int	LCP_ASCII listSendCommand: Ascii(DOS) charset is checked.
static int	LCP_CENTER listSendCommand: the image needs to be centered.
static int	LCP_FITLARGERONLY listSendCommand: in addition to LCP_FITTOWINDOW.
static int	LCP_FITTOWINDOW listSendCommand: Images: Fit image to window is checked.
static int	LCP_FORCESHOW listSendCommand: force show lister window.
static int	LCP_VARIABLE listSendCommand: Variable width charset is checked.
static int	LCP_WRAPTEXT listSendCommand: Text: Word wrap mode is checked.
static int	LCS_BACKWARDS listSearchText: Search backwards towards the beginning of the file.
static int	LCS_FINDFIRST listSearchText: String to be searched.
static int	LCS_MATCHCASE listSearchText: Search from the beginning of the first displayed line (not set: find next).
static int	LCS_WHOLEWORDS listSearchText: The search string is to be treated case-sensitively.
static int	LISTPLUGIN_ERROR something is wrong.
static int	LISTPLUGIN_OK everything is ok.

Method Summary

void	listCloseWindow(int listWin) ListCloseWindow is called when a user closes lister, or loads a different file.
void	listDefaultGetParams(DefaultParam dps) ListSetDefaultParams is called immediately after loading the DLL, before ListLoad.
java.lang.String	listGetDetectString(int maxLen) ListGetDetectString is called when the plugin is loaded for the first time.
java.lang.Object	listGetPreviewBitmap(java.lang.String fileToLoad, int width, int height, java.lang.String contentBuf, int contentBufLen, java.lang.StringBuffer filename) ListGetPreviewBitmap is called to retrieve a bitmap for the thumbnails view.
int	listLoad(int parentWin, java.lang.String input, int showFlags) ListLoad is called when a user opens lister with F3 or the Quick View Panel with Ctrl+Q, and when the definition string either doesn't exist, or its evaluation returns true.
int	listLoadNext(int parentWin, int listWin, java.lang.String fileToLoad, int showFlags) New in Total Commander 7: ListLoadNext is called when a user switches to the next or previous file in lister with 'n' or 'p' keys, or goes to the next/previous file in the Quick View Panel, and when the definition string either doesn't exist, or its evaluation returns true.
int	listNotificationReceived(int listWin, int message, int wParam, int lParam) ListNotificationReceived is called when the parent window receives a notification message from the child window: WM_COMMAND, WM_NOTIFY, WM_MEASUREITEM or WM_DRAWITEM.
int	listPrint(int listWin, java.lang.String fileToPrint, java.lang.String defPrinter, int printFlags, java.awt.Rectangle margins) ListPrint is called when the user chooses the print function.
int	listSearchDialog(int listWin, int findNext) ListSearchDialog is called when the user tries to find text in the plugin.
int	listSearchText(int handle, java.lang.String searchString, int searchParameter) ListListSearchText is called when the user tries to find text in the plugin.
int	listSendCommand(int listWin, int command, int parameter) ListSendCommand is called when the user changes some options in Lister's menu.

Field Detail

LISTPLUGIN_OK

static final int LISTPLUGIN_OK

everything is ok.

See Also:

Constant Field Values

LISTPLUGIN_ERROR

static final int LISTPLUGIN_ERROR

something is wrong.

See Also:

Constant Field Values

LCS_FINDFIRST

static final int LCS_FINDFIRST

listSearchText: String to be searched.

See Also:

Constant Field Values

LCS_MATCHCASE

static final int LCS_MATCHCASE

listSearchText: Search from the beginning of the first displayed line (not set: find next).

See Also:

Constant Field Values

LCS_WHOLEWORDS

static final int LCS_WHOLEWORDS

listSearchText: The search string is to be treated case-sensitively.

See Also:

Constant Field Values

LCS_BACKWARDS

static final int LCS_BACKWARDS

listSearchText: Search backwards towards the beginning of the file.

See Also:

Constant Field Values

LC_COPY

static final int LC_COPY

listSendCommand: Copy current selection to the clipboard.

See Also:

Constant Field Values

LC_NEWPARAMS

static final int LC_NEWPARAMS

listSendCommand: New parameters passed to plugin, see LCP_* constants.

See Also:

Constant Field Values

LC_SELECT_ALL

static final int LC_SELECT_ALL

listSendCommand: Select the whole contents.

See Also:

Constant Field Values

LC_SETPERCENT

static final int LC_SETPERCENT

listSendCommand: Go to new position in document (in percent).

See Also:

Constant Field Values

LCP_WRAPTEXT

static final int LCP_WRAPTEXT

listSendCommand: Text: Word wrap mode is checked.

See Also:

Constant Field Values

LCP_FITTOWINDOW

static final int LCP_FITTOWINDOW

listSendCommand: Images: Fit image to window is checked.

See Also:

Constant Field Values

LCP_ANSI

static final int LCP_ANSI

listSendCommand: Ansi charset is checked.

See Also:

Constant Field Values

LCP_ASCII

static final int LCP_ASCII

listSendCommand: Ascii(DOS) charset is checked.

See Also:

Constant Field Values

LCP_VARIABLE

static final int LCP_VARIABLE

listSendCommand: Variable width charset is checked.

See Also:

Constant Field Values

LCP_FORCESHOW

static final int LCP_FORCESHOW

listSendCommand: force show lister window.

See Also:

Constant Field Values

LCP_FITLARGERONLY

static final int LCP_FITLARGERONLY

listSendCommand: in addition to LCP_FITTOWINDOW.

See Also:

Constant Field Values

LCP_CENTER

static final int LCP_CENTER

listSendCommand: the image needs to be centered.

See Also:

Constant Field Values

Method Detail

listLoad

int listLoad(int parentWin,
             java.lang.String input,
             int showFlags)

ListLoad is called when a user opens lister with F3 or the Quick View Panel with Ctrl+Q, and when the definition string either doesn't exist, or its evaluation returns true.
Please note that multiple Lister windows can be open at the same time! Therefore you cannot save settings in global variables. You can call RegisterClass with the parameter cbWndExtra to reserve extra space for your data, which you can then access via GetWindowLong(). Or use an internal list, and store the list parameter via SetWindowLong(hwnd,GWL_ID,...). Lister will subclass your window to catch some hotkeys like 'n' or 'p'.
When lister is activated, it will set the focus to your window. If your window contains child windows, then make sure that you set the focus to the correct child when your main window receives the focus!
If lcp_forceshow is defined, you may try to load the file even if the plugin wasn't made for it. Example: A plugin with line numbers may only show the file as such when the user explicitly chooses 'Image/Multimedia' from the menu. Lister plugins which only create thumbnail images do not need to implement this function.

Parameters:

parentWin - This is lister's window. Create your plugin window as a child of this window.

input - The name of the file which has to be loaded.

showFlags - A combination of the following flags:

• lcp_wraptext Text: Word wrap mode is checked
• lcp_fittowindow Images: Fit image to window is checked
• lcp_ansi Ansi charset is checked
• lcp_ascii Ascii(DOS) charset is checked
• lcp_variable Variable width charset is checked
• lcp_forceshow User chose 'Image/Multimedia' from the menu. See remarks.

You may ignore these parameters if they don't apply to your document type.

Returns:

Return a handle to your window if load succeeds, NULL otherwise. If NULL is returned, Lister will try the next plugin.

listCloseWindow

void listCloseWindow(int listWin)

ListCloseWindow is called when a user closes lister, or loads a different file. If ListCloseWindow isn't present, DestroyWindow() is called.
You can use this function to close open files, free buffers etc.

Parameters:

listWin - This is the window handle which needs to be destroyed.

listGetDetectString

java.lang.String listGetDetectString(int maxLen)

ListGetDetectString is called when the plugin is loaded for the first time. It should return a parse function which allows Lister to find out whether your plugin can probably handle the file or not. You can use this as a first test - more thorough tests may be performed in ListLoad(). It's very important to define a good test string, especially when there are dozens of plugins loaded! The test string allows lister to load only those plugins relevant for that specific file type.
The syntax of the detection string is as follows. There are operands, operators and functions. Operands:

• EXT The extension of the file to be loaded (always uppercase).
• SIZE The size of the file to be loaded.
• FORCE 1 if the user chose 'Image/Multimedia' from the menu, 0 otherwise.
• MULTIMEDIA This detect string is special: It is always TRUE (also in older TC versions). If it is present in the string, this plugin overrides internal multimedia viewers in TC. If not, the internal viewers are used. Check the example below!
• [5] The fifth byte in the file to be loaded. The first 8192 bytes can be checked for a match.
• 12345 The number 12345
• "TEST" The string "TEST"

Operators

• & AND. The left AND the right expression must be true (!=0).
• | OR: Either the left OR the right expression needs to be true (!=0).
• = EQUAL: The left and right expression need to be equal.
• != UNEQUAL: The left and right expression must not be equal.
• < SMALLER: The left expression is smaller than the right expression. Comparing a number and a string returns false (0). Booleans are stored as 0 (false) and 1 (true).
• > LARGER: The left expression is larger than the right expression.

Functions

• () Braces: The expression inside the braces is evaluated as a whole.
• !() NOT: The expression inside the braces will be inverted. Note that the braces are necessary!
• FIND() The text inside the braces is searched in the first 8192 bytes of the file. Returns 1 for success and 0 for failure.
• FINDI() The text inside the braces is searched in the first 8192 bytes of the file. Upper/lowercase is ignored.

Internal handling of variables
Varialbes can store numbers and strings. Operators can compare numbers with numbers and strings with strings, but not numbers with strings. Exception: A single char can also be compared with a number. Its value is its ANSI character code (e.g. "A"=65). Boolean values of comparisons are stored as 1 (true) and 0 (false).
Examples:

• EXT="WAV" | EXT="AVI" The file may be a Wave or AVI file.
• EXT="WAV" & [0]="R" & [1]="I" & [2]="F" & [3]="F" & FIND("WAVEfmt")
• Also checks for Wave header "RIFF" and string "WAVEfmt"
• EXT="WAV" & (SIZE<1000000 | FORCE) Load wave files smaller than 1000000 bytes at startup/file change, and all wave files if the user explictly chooses 'Image/Multimedia' from the menu.
• ([0]="P" & [1]="K" & [2]=3 & [3]=4) | ([0]="P" & [1]="K" & [2]=7 & [3]=8) Checks for the ZIP header PK#3#4 or PK#7#8 (the latter is used for multi-volume zip files).
• EXT="TXT" & !(FINDI("<HEAD>") | FINDI("<BODY>")) This plugin handles text files which aren't HTML files. A first detection is done with the <HEAD> and <BODY> tags. If these are not found, a more thorough check may be done in the plugin itself.
• MULTIMEDIA & (EXT="WAV" | EXT="MP3") Replace the internal player for WAV and MP3 files (which normally uses Windows Media Player as a plugin). Requires TC 6.0 or later!

Operator precedence:

• The strongest operators are =, != < and >, then comes &, and finally |. What does this mean? Example:
• expr1="a" & expr2 | expr3<5 & expr4!=b will be evaluated as ((expr1="a") & expr2) | ((expr3<5) & (expr4!="b")) If in doubt, simply use braces to make the evaluation order clear.

Parameters:

maxLen - Maximum length, in bytes, of the detection string (currently 2k).

Returns:

Return the detection string here. See remarks for the syntax.

listSearchText

int listSearchText(int handle,
                   java.lang.String searchString,
                   int searchParameter)

ListListSearchText is called when the user tries to find text in the plugin. Don't implement this function if your plugin doesn't contain any text, or doesn't support text searches!
The plugin needs to highlight/select the found text by itself.

Parameters:

handle - Handle to your list window created with ListLoad

searchString - String to be searched.

searchParameter - A combination of the following search flags: LCS_FINDFIRST, LCS_MATCHCASE, LCS_WHOLEWORDS, LCS_BACKWARDS

Returns:

LISTPLUGIN_OK - found, LISTPLUGIN_ERROR - not found

listSendCommand

int listSendCommand(int listWin,
                    int command,
                    int parameter)

ListSendCommand is called when the user changes some options in Lister's menu.

Parameters:

listWin - hande to your list window created with ListLoad

command - One of the following commands: LC_COPY, LC_NEWPARAMS, LC_SELECT_ALL, LC_SETPERCENT

parameter - Used for lc_newparams. May be a combination of: LCP_FITTOWINDOW, LCP_ANSI, LCP_ASCII, LCP_VARIABLE, LCP_WRAPTEXT, LCP_FORCESHOW

Returns:

Return either LISTPLUGIN_OK or LISTPLUGIN_ERROR.

listPrint

int listPrint(int listWin,
              java.lang.String fileToPrint,
              java.lang.String defPrinter,
              int printFlags,
              java.awt.Rectangle margins)

ListPrint is called when the user chooses the print function.
You need to show a print dialog, in which the user can choose what to print, and select a different printer. See the sample plugin on how to do this!

Parameters:

listWin - Hande to your list window created with ListLoad

fileToPrint - The full name of the file which needs to be printed. This is the same file as loaded with ListLoad.

defPrinter - Name of the printer currently chosen in Total Commander. May be NULL (use default printer).

printFlags - Currently not used (set to 0). May be used in a later version.

margins - The left, top, right and bottom margins of the print area, in MM_LOMETRIC measurement units (1/10 mm). May be ignored.

Returns:

Return either LISTPLUGIN_OK or LISTPLUGIN_ERROR.

listNotificationReceived

int listNotificationReceived(int listWin,
                             int message,
                             int wParam,
                             int lParam)

ListNotificationReceived is called when the parent window receives a notification message from the child window: WM_COMMAND, WM_NOTIFY, WM_MEASUREITEM or WM_DRAWITEM.
Do not implement this function if you don't use any owner-drawn controls and don't require any notification messages! Possible applications: Owner-drawn Listview control, reacting to scroll messages, etc.

Parameters:

listWin - Hande to your list window created with ListLoad

message - The received message, one of the following: WM_COMMAND, WM_NOTIFY, WM_MEASUREITEM or WM_DRAWITEM. (from winuser.h)

wParam - The WPARAM parameter of the message.

lParam - The LPARAM parameter of the message.

Returns:

Return the value described for that message in the Windows API help.

listGetPreviewBitmap

java.lang.Object listGetPreviewBitmap(java.lang.String fileToLoad,
                                      int width,
                                      int height,
                                      java.lang.String contentBuf,
                                      int contentBufLen,
                                      java.lang.StringBuffer filename)

ListGetPreviewBitmap is called to retrieve a bitmap for the thumbnails view. Please only implement and export this function if it makes sense to show preview pictures for the supported file types! This function is new in version 1.4. It requires Total Commander >=6.5, but is ignored by older versions.

1. This function is only called in Total Commander 6.5 and later. The plugin version will be >= 1.4.
2. The bitmap handle goes into possession of Total Commander, which will delete it after using it. The plugin must not delete the bitmap handle!
3. Make sure you scale your image correctly to the desired maximum width+height! Do not fill the rest of the bitmap - instead, create a bitmap which is SMALLER than requested! This way, Total Commander can center your image and fill the rest with the default background color.

Parameters:

fileToLoad - The name of the file for which to load the preview bitmap.

width - Requested maximum width of the bitmap.

height - Requested maximum height of the bitmap

contentBuf - The first 8 kBytes (8k) of the file. Often this is enough data to show a reasonable preview, e.g. the first few lines of a text file.

contentBufLen - The length of the data passed in contentbuf. Please note that contentbuf is not a 0 terminated string, it may contains 0 bytes in the middle! It's just the 1:1 contents of the first 8k of the file.

filename - Here you need to return the bitmap handle. Three forms are supported:

1. filename.append ("253|shell32.dll"); // load bitmap from a resource (EXE/DLL), referenced by a resource id
2. filename.append ("G:\\Totalcmd\\plugins\\java\\Drives\\test.bmp"); // load bitmap from bmp file (absolute path name)
3. filename.append ("%CWD%\\test.bmp"); // load bitmap from bmp file in the plugin directory

Returns:

Return a device-dependent bitmap created with e.g. CreateCompatibleBitmap.

listDefaultGetParams

void listDefaultGetParams(DefaultParam dps)

ListSetDefaultParams is called immediately after loading the DLL, before ListLoad. This function is new in version 1.2. It requires Total Commander >=5.51, but is ignored by older versions.
This function is only called in Total Commander 5.51 and later. The plugin version will be >= 1.2.

Parameters:

dps - This structure of type ListDefaultParamStruct currently contains the version number of the plugin interface, and the suggested location for the settings file (ini file). It is recommended to store any plugin-specific information either directly in that file, or in that directory under a different name. Make sure to use a unique header when storing data in this file, because it is shared by other file system plugins! If your plugin needs more than 1kbyte of data, you should use your own ini file because ini files are limited to 64k.

listLoadNext

int listLoadNext(int parentWin,
                 int listWin,
                 java.lang.String fileToLoad,
                 int showFlags)

New in Total Commander 7: ListLoadNext is called when a user switches to the next or previous file in lister with 'n' or 'p' keys, or goes to the next/previous file in the Quick View Panel, and when the definition string either doesn't exist, or its evaluation returns true.

Parameters:

parentWin - This is lister's window. Your plugin window needs to be a child of this window

listWin - The plugin window returned by ListLoad

fileToLoad - The name of the file which has to be loaded.

showFlags - A combination of the following flags:

• lcp_wraptext Text: Word wrap mode is checked
• lcp_fittowindow Images: Fit image to window is checked
• lcp_fitlargeronly Fit image to window only if larger than the window. Always set together with lcp_fittowindow.
• lcp_center Center image in viewer window
• lcp_ansi Ansi charset is checked
• lcp_ascii Ascii(DOS) charset is checked
• lcp_variable Variable width charset is checked
• lcp_forceshow User chose 'Image/Multimedia' from the menu. See remarks.

You may ignore these parameters if they don't apply to your document type.

Returns:

LISTPLUGIN_OK if load succeeds, LISTPLUGIN_ERROR otherwise. If LISTPLUGIN_ERROR is returned, Lister will try to load the file with the normal ListLoad function (also with other plugins).
Remarks:
Please note that multiple Lister windows can be open at the same time! Therefore you cannot save settings in global variables. You can call RegisterClass with the parameter CBWNDEXTRA to reserve extra space for your data, which you can then access via GetWindowLong(). Or use an internal list, and store the list parameter via SetWindowLong(hwnd,GWL_ID,...). Lister will subclass your window to catch some hotkeys like 'n' or 'p'. When lister is activated, it will set the focus to your window. If your window contains child windows, then make sure that you set the focus to the correct child when your main window receives the focus!
If LCP_FORCESHOW is defined, you may try to load the file even if the plugin wasn't made for it.
Example: A plugin with line numbers may only show the file as such when the user explicitly chooses 'Image/Multimedia' from the menu.
Lister plugins which only create thumbnail images do not need to implement this function. If you do not implement ListLoadNext but only ListLoad, then the plugin will be unloaded and loaded again when switching through files, which results in flickering.

listSearchDialog

int listSearchDialog(int listWin,
                     int findNext)

ListSearchDialog is called when the user tries to find text in the plugin. Only implement this function if your plugin requires a plugin-specific search dialog! For searching text, please implement ListSearchText instead!

Parameters:

listWin - Hande to your list window created with ListLoad

findNext - 0: FindFirst was chosen by the user
1: FindNext was chosen from the menu

Returns:

LISTPLUGIN_OK if you implement this function, or LISTPLUGIN_ERROR if Total Commander should show its own text search dialog and call ListSearchText later. This allows a plugin to support both its own search method via ListSearchDialog, and the standard search method via ListSearchText! Do NOT return LISTPLUGIN_ERROR if the search fails!
Remarks:
The plugin needs to show the search dialog and highlight/select the found text by itself. Requires Total Commander 7 or later.