Content plugins developer guide overview

From TotalcmdWiki
Revision as of 14:54, 15 April 2017 by Lefteous (talk | contribs) (Table reformatted)
Jump to navigation Jump to search

This help file is about writing content plugins for Total Commander. Content plugins are used for several purposes: For showing custom columns in the file lists, for searching, and in the multi-rename tool.

The minimum functions needed for a Content plugin are:

ContentGetSupportedField Gets the names of the supported fields
ContentGetValue Gets a value for the selected field



The following are optional functions:

ContentGetDetectString Allows TC to determine which file types are supported by the plugin, without loading the plugin.
ContentSetDefaultParams Informs the plugin about settings like plugin interface version and ini file location.
ContentStopGetValue Informs the plugin that it should abort a lengthy ContentGetValue operation.
ContentGetDefaultSortOrder Choose a default sort order (ascending or descending) for a column.
ContentPluginUnloading Called when your plugin is unloaded.
ContentGetSupportedFieldFlags Called to get special flags, e.g. whether a field can be changed with ContentSetValue
ContentSetValue Used to change a field, e.g. set a file date
ContentEditValue Used to open a field-specific value editor in the change attributes dialog
ContentCompareFiles Used in "Synchronize dirs" to compare two files by a custom method

How it works:

When installing the plugin, Total Commander calls ContentGetDetectString (if implemented) to find out what file types are supported by the plugin. The content string may be modified manually by the user to include/exclude certain file types. It's recommended not to use detect strings which check the file by contents, because ContentGetDetectString cannot be called delayed, so it would slow down file list display quite a lot.

When Total Commander needs information about a specific file, it first parses the detect string to determine whether the plugin needs to be called for that file or not. If yes, it then calls ContentGetSupportedField in a loop, to enumerate all available fields. This info is then cached, so TC doesn't have to call the function for each file separately. If a language file with the same name as the plugin but with extension .lng is present, Total Commander will automatically translate the returned field names. To request the contents of a field for a specific file, the function ContentGetValue will be called.

Notes:

  1. It's quite important to create a good detection string, especially if calling of your plugin is slow! If you cannot make a good detection string, then make sure that your plugin doesn't have any static objects defined as global variables! These would be loaded with the DLL! Only create such objects in the called functions, where needed!
  2. If the parsing of a file is very slow compared to the extraction of a field, it may be reasonable to cache all fields for a given file until the next file name is requested. This would make it faster to request multiple fields from the same file. Such a cache could be implemented with two fields, a name field storing the last name for which the cached information was stored, and a structure containing the extracted information. Please note that if your plugin returns ft_delayed, you have to take measures so the cache is protected from multiple simultaneous calls to ContentGetValue. This can be done using a semaphore.
  3. ContentSetValue should only be implemented where it makes sense! For example, a plugin which shows the file's size in various forms does not need to offer this function, because it makes no sense to change a file's size via the attributes dialog.