New interface documentation for TC7 plugins

[tbeu]

Would be fine if the WCX header could contain all exported function declarations as the the other plugin headers already do.

[Alextp]

TC 7.0 pb4: Lister API not updated?

[ghisler(Author)]

I have just uploaded the new lister help, see the first message of this thread!

[Alextp]

Listplug.pas doesn't compile. You missed "uses windows" line:

unit listplug; { Contents of file listplug.pas }

interface

uses Windows;

[now]

How is ContentGetSupportedFieldFlags supposed to work exactly? It seems that it is called for one more entry than the number of fields that I have defined. Also, what value should I return for a field that I know can’t be changed, for example, a field that depends on a dll being loaded that failed being loaded at startup, but isn’t critical to any of the other fields? I figured a value of 0 would work, but that prevents any of the fields from working.

[ghisler(Author)]

When ContentGetSupportedFieldFlags is called with FieldIndex set to -1 (minus one), Total Commander wants to know whether ANY of the fields supports one of the available options. So if for example the fields with index 0 and 1 support the option contflags_substsize, and the fields 2 and 3 support the option contflags_passthrough_size_float, then you need to return the sum (logial "OR") of both of these flags when FieldIndex is -1.

In C code, this would look like this:

switch (FieldIndex) {
case -1:
return contflags_substsize | contflags_passthrough_size_float;
case 0:
case 1:
return contflags_substsize;
case 2:
case 3:
return contflags_passthrough_size_float;
}

Also, what value should I return for a field that I know can’t be changed, for example, a field that depends on a dll being loaded that failed being loaded at startup, but isn’t critical to any of the other fields?

You can of course just return a combination of ALL available options for -1, but then TC would call ContentGetSupportedFieldFlags for every single field (which it doesn't do if ContentGetSupportedFieldFlags for -1 returns 0).

[now]

Say that I have two fields, “Encoding” and “Line Endings”.

The “Encoding” field can be changed if the dll “iconv.dll” can be LoadLibrary()ied. If that dll can’t be loaded, the “Encoding” field isn’t modifiable. How do I state that?

The “Line Endings” field can always be changed, however.

Currently I have (something like)

switch (FieldIndex) {
case -1:
return contflags_edit | contflags_substmask;
case 0:
return (iconv_loaded ? contflags_edit | contflags_substattributestr : ?);
case 1:
return contflags_edit | contflags_substattributestr;
}

(I use substmask as I’m trying to be generic here, in case other fields with other substs are added later.)

So what should I put in place of the ? in the ternary expression?

One thing that perhaps should be noted in the documentation is when exactly ContentGetSupportedFieldFlags gets called. I figured that it got called when the plug-in was loaded, but it turns out that it gets called with an index of -1 when you click the “Change plugin attributes” checkbox in the attribute dialog and then once for each field’s index when you enter the dropdown menu for selecting a plug-in’s fields to modify.

[ghisler(Author)]

I wouldn't rely on when exactly the function gets called. Other programs may also implement this function, so it's better to implement it in a way which will work independent from when it is called.

So if iconv.dll cannot be loaded and you are sure that it cannot be loaded during the entire lifetime of the plugin, do what you do above and return

return (iconv_loaded ? contflags_edit | contflags_substattributestr : contflags_substattributestr);

If it is possible that the DLL gets loaded at a later time, then always return
return (contflags_edit | contflags_substattributestr);

Then when the user clicks on the edit button, show an error message that the iconv.dll couldn't be loaded, so it's not currently possible to use the edit function.

This has the additional advantage that LoadLibrary only needs to be called when the user clicks the Edit button.

[now]

OK. About holding off on LoadLibrary, yes, that’s actually a good solution. It can then also be unloaded when editing is done.

Thanks!

[Sektor]

Me jus' wanna say dat Total Commander is THE GREATEST file manager! Me hope there will be no any other FM than TC! :) Thanks a lot, Mr. Ghisler!

[kenchis]

Dear Mr. Ghisler,

While updating my java plugin API,
I found out, that the Overview page of the WLX help file is not fully updated:
WLX help (v1.:
ListSearchDialog and ListLoadNext are not mentioned by "how it works"-section.
Additionally the optional functions section is empty.

[kenchis]

In WFX plugin help file FsGetPreviewBitmap:

Code: Select all

Important notes:
...
[b]3.[/b] nothing here?
4. ...

In WFX plugin help file FsContentGetSupportedFields:
You can remove the remarks, since ft_fulltext is unsupported by WFX plugins.

In WFX plugin help file FsContentGetValue:
see above
Additionally remove parameter ft_fulltext

In WFX plugin help file FsContentPluginUnloading:

Code: Select all

[b]T[/b]here are no parameters.

T is bold?

In WFX plugin help file fsContentGetSupportedFieldFlags;
The following flags are not explained here (only in the WDX help file),
is this correct?
CONTFLAGS_PASSTHROUGH_SIZE_FLOAT, CONTFLAGS_FIELDEDIT

In WFX plugin help file: fsContentGetDefaultView:
Parameter description for maxlen is missing.

In WFX plugin help file:
These content plugin functions are not part of the file system plugin API, is this correct? (contentSendStateInformation, contentEditValue)

[kenchis]

WDX plugin help:

The following is missing in the header files (*.h,*.pas):
ft_setsuccess Change was successful

This constant is described in ContentSetValue

[ND]

In the WCX Guide, for structures [face=Courier]tHeaderData[/face] and [face=Courier]tHeaderDataEx[/face] the members [face=Courier]Flags[/face] , [face=Courier]UnpVer[/face] , and [face=Courier]Method[/face] , are not documented.
Some googling gave me the idea that they might be related with [face=Courier]unrar.dll[/face] same as [face=Courier]HostOS[/face] , so they should be ignored and set to zero. Please confirm/deny.

P.S. I'm using Doxygen for source-code documentation, and as a first step in writing my compressor I have created an unofficial HtmlHelp conversion of WCX Writer's Guide.

[ghisler(Author)]

Yes, that's correct. I used the unrar.dll interface to make it easier for people to adapt to the TC interface.These fields are not used, it doesn't matter to what you set them. It's better to set all unused fields to 0, though.