From c82275eb7d2fd034941677f94a8ae3d55fece5a0 Mon Sep 17 00:00:00 2001 From: =?UTF-8?q?Michal=20V=C3=A1rady?= Date: Tue, 19 Dec 2023 20:07:01 +0100 Subject: [PATCH 1/2] spl_gen.h, spl_com.h: translated --- src/plugins/shared/spl_com.h | 999 +++++++++++++++++------------------ src/plugins/shared/spl_gen.h | 253 ++++----- 2 files changed, 625 insertions(+), 627 deletions(-) diff --git a/src/plugins/shared/spl_com.h b/src/plugins/shared/spl_com.h index 2d4549d9c..02d78aa09 100644 --- a/src/plugins/shared/spl_com.h +++ b/src/plugins/shared/spl_com.h @@ -12,7 +12,7 @@ #pragma once #ifdef _MSC_VER -#pragma pack(push, enter_include_spl_com) // aby byly struktury nezavisle na nastavenem zarovnavani +#pragma pack(push, enter_include_spl_com) // so that the structures are independent of the alignment setting #pragma pack(4) #pragma warning(3 : 4706) // warning C4706: assignment within conditional expression #endif // _MSC_VER @@ -20,28 +20,28 @@ #pragma option -a4 #endif // __BORLANDC__ -// v pluginu je treba definovat promennou SalamanderVersion (int) a v SalamanderPluginEntry tuto -// promennou inicializovat: +// in the plugin, it is neccessary to define the variable SalamanderVersion (int) and initialize +// this variable in SalamanderPluginEntry: // SalamanderVersion = salamander->GetVersion(); -// globalni promenna s verzi Salamandera, ve kterem je tento plugin nacteny +// global variable with the version of Salamander in which this plugin is loaded extern int SalamanderVersion; // // **************************************************************************** // CSalamanderDirectoryAbstract // -// trida reprezentuje adresarovou strukturu - soubory a adresare na pozadovanych cestach, root cesta je "", -// oddelovace v ceste jsou backslashe ('\\') +// Class representing a directory structure - files and directories in the desired paths, root path is "", +// separators in the path are backslashes ('\\') // -// CQuadWord - 64-bitovy unsigned integer pro velikosti souboru -// triky: -// -rychlejsi predani vstupniho parametru typu CQuadWord: const CQuadWord & -// -priradit 64-bit integer: quadWord.Value = XXX; -// -pocitat pomer velikosti: quadWord1.GetDouble() / quadWord2.GetDouble() // ztrata presnosti pred delenim se projevi malo (max. 1e-15) -// -oriznout na DWORD: (DWORD)quadWord.Value -// -prevest (unsigned) __int64 na CQuadWord: CQuadWord().SetUI64(XXX) +// CQuadWord - 64-bit unsigned integer for file sizes +// tricks: +// -faster passing of an input parameter of type CQuadWord: const CQuadWord & +// -assign a 64-bit integer: quadWord.Value = XXX; +// -calculate the size ratio: quadWord1.GetDouble() / quadWord2.GetDouble() // the loss of precision before division will be small (max. 1e-15) +// -trim to DWORD: (DWORD)quadWord.Value +// -convert (unsigned) __int64 to CQuadWord: CQuadWord().SetUI64(XXX) struct CQuadWord { @@ -55,9 +55,9 @@ struct CQuadWord unsigned __int64 Value; }; - // POZOR: nesmi sem prijit operator prirazeni ani konstruktor pro jeden DWORD, - // jinak bude pouziti 8-bytovych cisel zcela nekontrolovatelne (C++ vse - // vzajemne prevede, coz nemusi byt vzdy prave ono) + // CAUTION: The assignment operator or constructor for a single DWORD must not be used here, + // otherwise the use of 8-bit numbers will be completely uncontrollable (C++ converts everything + // mutually, which may not always be correct) CQuadWord() {} CQuadWord(DWORD lo, DWORD hi) @@ -185,11 +185,11 @@ struct CQuadWord BOOL operator<=(const CQuadWord& qw) const { return Value <= qw.Value; } BOOL operator>=(const CQuadWord& qw) const { return Value >= qw.Value; } - // prevod na double (pozor na ztratu presnosti u velkych cisel - double ma jen 15 platnych cislic) + // Conversion to double (note the loss of precision for large numbers - double has only 15 valid digits) double GetDouble() const - { // MSVC neumi konverzi unsigned __int64 na double, takze si musime pomoct sami + { // MSVC does not know how to convert unsigned __int64 to double, so we have to help ourselves if (Value < CQuadWord(0, 0x80000000).Value) - return (double)(__int64)Value; // kladne cislo + return (double)(__int64)Value; // positive number else return 9223372036854775808.0 + (double)(__int64)(Value - CQuadWord(0, 0x80000000).Value); } @@ -197,82 +197,84 @@ struct CQuadWord #define QW_MAX CQuadWord(0xFFFFFFFF, 0xFFFFFFFF) -#define ICONOVERLAYINDEX_NOTUSED 15 // hodnota pro CFileData::IconOverlayIndex v pripade, ze ikona nema overlay +#define ICONOVERLAYINDEX_NOTUSED 15 // value for CFileData::IconOverlayIndex in case the icon has no overlay -// zaznam kazdeho souboru a adresare v Salamanderovi (zakladni data o souboru/adresari) -struct CFileData // nesmi sem prijit destruktor ! +// record of each file and directory in Salamander (basic data about the file/directory) +struct CFileData // destructor must not be here! { - char* Name; // naalokovane jmeno souboru (bez cesty), nutne alokovat na heapu - // Salamandera (viz CSalamanderGeneralAbstract::Alloc/Realloc/Free) - char* Ext; // ukazatel do Name za prvni tecku zprava (vcetne tecky na zacatku jmena, - // na Windows se chape jako pripona, narozdil od UNIXu) nebo na konec - // Name, pokud pripona neexistuje; je-li v konfiguraci nastaveno FALSE - // pro SALCFG_SORTBYEXTDIRSASFILES, je v Ext pro adresare ukazatel na konec - // Name (adresare nemaji pripony) - CQuadWord Size; // velikost souboru v bytech - DWORD Attr; // atributy souboru - ORovane konstanty FILE_ATTRIBUTE_XXX - FILETIME LastWrite; // cas posledniho zapisu do souboru (UTC-based time) - char* DosName; // naalokovane DOS 8.3 jmeno souboru, neni-li treba je NULL, nutne - // alokovat na heapu Salamandera (viz CSalamanderGeneralAbstract::Alloc/Realloc/Free) - DWORD_PTR PluginData; // pouziva plugin skrze CPluginDataInterfaceAbstract, Salamander ignoruje - unsigned NameLen : 9; // delka retezce Name (strlen(Name)) - POZOR: maximalni delka jmena je (MAX_PATH - 5) - unsigned Hidden : 1; // je hidden? (je-li 1, ikonka je pruhlednejsi o 50% - ghosted) - unsigned IsLink : 1; // je link? (je-li 1, ikonka ma overlay linku) - standardni plneni viz CSalamanderGeneralAbstract::IsFileLink(CFileData::Ext), pri zobrazeni ma prednost pred IsOffline, ale IconOverlayIndex ma prednost - unsigned IsOffline : 1; // je offline? (je-li 1, ikonka ma overlay offline - cerne hodiny), pri zobrazeni ma IsLink i IconOverlayIndex prednost - unsigned IconOverlayIndex : 4; // index icon-overlaye (pokud ikona nema zadny overlay, je zde hodnota ICONOVERLAYINDEX_NOTUSED), pri zobrazeni ma prednost pred IsLink a IsOffline - - // flagy pro interni pouziti v Salamanderovi: nuluji se pri pridani do CSalamanderDirectoryAbstract - unsigned Association : 1; // vyznam jen pro zobrazeni 'simple icons' - ikona asociovaneho souboru, jinak 0 - unsigned Selected : 1; // read-only flag oznaceni (0 - polozka neoznacena, 1 - polozka oznacena) - unsigned Shared : 1; // je adresar sdileny? u souboru se nepouziva - unsigned Archive : 1; // jedna se o archiv? pouziva se pro zobrazovani ikony archivu v panelu - unsigned SizeValid : 1; // je u adresare napocitana jeho velikost? - unsigned Dirty : 1; // je potreba tuto polozku prekreslit? (pouze docasna platnost; mezi nastavenim bitu a prekreslenim panelu nesmi byt pumpovana message queue, jinak muze dojit k prekresleni ikonky (icon reader) a tim resetu bitu! v dusledku se neprekresli polozka) - unsigned CutToClip : 1; // je CUT-nutej na clipboardu? (je-li 1, ikonka je pruhlednejsi o 50% - ghosted) - unsigned IconOverlayDone : 1; // jen pro potreby icon-reader-threadu: ziskavame nebo uz jsme ziskavali icon-overlay? (0 - ne, 1 - ano) + char* Name; // allocated file name (without path), must be allocated on the heap + // of the Salamander (see CSalamanderGeneralAbstract::Alloc/Realloc/Free) + char* Ext; // pointer to the Name after the first dot from the right (including the dot at the beginning of the name, + // on Windows it is understood as an extension, unlike UNIX) or at the end + // of Name if the extension does not exist; if FALSE is set in the configuration + // for SALCFG_SORTBYEXTDIRSASFILES, Ext for directories is a pointer to the end + // of Name (directories have no extensions) + CQuadWord Size; // file size in bytes + DWORD Attr; // file attributes - ORed constants FILE_ATTRIBUTE_XXX + FILETIME LastWrite; // time of the last write to the file (UTC-based time) + char* DosName; // allocated DOS 8.3 file name, if not needed, it is NULL, must be allocated on the heap + // of the Salamander (see CSalamanderGeneralAbstract::Alloc/Realloc/Free) + DWORD_PTR PluginData; // used by a plugin through CPluginDataInterfaceAbstract, Salamander ignores + unsigned NameLen : 9; // length of the Name string (strlen(Name)) - WARNING: the maximum length of the name is (MAX_PATH - 5) + unsigned Hidden : 1; // is hidden? (if 1, the icon is 50% transparent - ghosted) + unsigned IsLink : 1; // is links? (if 1, the icon has a link overlay) - standard filling see CSalamanderGeneralAbstract::IsFileLink(CFileData::Ext), has priority over IsOffline when displayed, but IconOverlayIndex has priority + unsigned IsOffline : 1; // is offline? (if 1, the icon has an offline overlay - black clock), when displayed, both IsLink and IconOverlayIndex have priority + unsigned IconOverlayIndex : 4; // index of the icon overlay (if the icon has no overlay, the value is ICONOVERLAYINDEX_NOTUSED), when displayed, it has priority over IsLink and IsOffline + + // flags for internal use in Salamander: reset when added to CSalamanderDirectoryAbstract + unsigned Association : 1; // makes sense only for displaying 'simple icons' - icon associated with the file, otherwise 0 + unsigned Selected : 1; // read-only flag of selection (0 - item not selected, 1 - item selected) + unsigned Shared : 1; // is the directory shared? not used for files + unsigned Archive : 1; // is it an archive? used to display the archive icon in the panel + unsigned SizeValid : 1; // is the size of the directory counted for the directory? + unsigned Dirty : 1; // is it necessary to redraw this item? (temporary validity; between setting the bit and redrawing the panel, the message queue must not be pumped, otherwise the icon (icon reader) may be redrawn and thus the bit reset! as a result, the item is not redrawn) + unsigned CutToClip : 1; // is it CUT to the clipboard? (if 1, the icon is 50% more transparent - ghosted) + unsigned IconOverlayDone : 1; // only for the needs of the icon reader thread: have we already obtained the icon overlay? (0 - no, 1 - yes) }; -// konstanty urcujici platnost dat, ktera jsou primo ulozena v CFileData (velikost, pripona, atd.) -// nebo se generuji z primo ulozenych dat automaticky (file-type se generuje z pripony); -// Name + NameLen jsou povinne (musi byt platne vzdy); platnost PluginData si ridi plugin sam -// (Salamander tento atribut ignoruje) -#define VALID_DATA_EXTENSION 0x0001 // pripona je ulozena v Ext (bez: vsechny Ext = konec Name) -#define VALID_DATA_DOSNAME 0x0002 // DOS name je ulozeno v DosName (bez: vsechny DosName = NULL) -#define VALID_DATA_SIZE 0x0004 // velikost v bytech je ulozena v Size (bez: vsechny Size = 0) -#define VALID_DATA_TYPE 0x0008 // file-type muze byt generovan z Ext (bez: negeneruje se) -#define VALID_DATA_DATE 0x0010 // datum modifikace (UTC-based) je ulozen v LastWrite (bez: vsechny datumy v LastWrite jsou 1.1.1602 v local time) -#define VALID_DATA_TIME 0x0020 // cas modifikace (UTC-based) je ulozen v LastWrite (bez: vsechny casy v LastWrite jsou 0:00:00 v local time) -#define VALID_DATA_ATTRIBUTES 0x0040 // atributy jsou ulozeny v Attr (ORovane Win32 API konstanty FILE_ATTRIBUTE_XXX) (bez: vsechny Attr = 0) -#define VALID_DATA_HIDDEN 0x0080 // "ghosted" priznak ikony je ulozen v Hidden (bez: vsechny Hidden = 0) -#define VALID_DATA_ISLINK 0x0100 // IsLink obsahuje 1 pokud jde o link, ikonka ma overlay linku (bez: vsechny IsLink = 0) -#define VALID_DATA_ISOFFLINE 0x0200 // IsOffline obsahuje 1 pokud jde o offline soubor/adresar, ikonka ma offline overlay (bez: vsechny IsOffline = 0) -#define VALID_DATA_PL_SIZE 0x0400 // ma smysl jen bez pouziti VALID_DATA_SIZE: plugin ma aspon pro nektere soubory/adresare ulozenou velikost v bytech (nekde v PluginData), pro ziskani teto velikosti Salamander vola CPluginDataInterfaceAbstract::GetByteSize() -#define VALID_DATA_PL_DATE 0x0800 // ma smysl jen bez pouziti VALID_DATA_DATE: plugin ma aspon pro nektere soubory/adresare ulozeny datum modifikace (nekde v PluginData), pro ziskani teto velikosti Salamander vola CPluginDataInterfaceAbstract::GetLastWriteDate() -#define VALID_DATA_PL_TIME 0x1000 // ma smysl jen bez pouziti VALID_DATA_TIME: plugin ma aspon pro nektere soubory/adresare ulozeny cas modifikace (nekde v PluginData), pro ziskani teto velikosti Salamander vola CPluginDataInterfaceAbstract::GetLastWriteTime() -#define VALID_DATA_ICONOVERLAY 0x2000 // IconOverlayIndex je index icon-overlaye (zadny overlay = hodnota ICONOVERLAYINDEX_NOTUSED) (bez: vsechny IconOverlayIndex = ICONOVERLAYINDEX_NOTUSED), zadani ikon viz CSalamanderGeneralAbstract::SetPluginIconOverlays - -#define VALID_DATA_NONE 0 // pomocna konstanta - platne je jen Name a NameLen +// constants determining the validity of data that is directly stored in CFileData (size, extension, etc.) +// or are generated from directly stored data automatically (file-type is generated from the extension); +// Name + NameLen are mandatory (must be valid at all times); the validity of PluginData is controlled by the plugin itself +// (Salamander ignores this attribute) +#define VALID_DATA_EXTENSION 0x0001 // extension is stored in Ext (if not set: all Ext = end of Name) +#define VALID_DATA_DOSNAME 0x0002 // DOS name is stored in DosName (if not set: all DosName = NULL) +#define VALID_DATA_SIZE 0x0004 // size in bytes is stored in Size (if not set: all Size = 0) +#define VALID_DATA_TYPE 0x0008 // file-type can be generated from Ext (if not set: not generated) +#define VALID_DATA_DATE 0x0010 // modification date (UTC-based) is stored in LastWrite (if not set: all dates in LastWrite are 1.1.1602 in local time) +#define VALID_DATA_TIME 0x0020 // modification time (UTC-based) is stored in LastWrite (if not set: all times in LastWrite are 0:00:00 in local time) +#define VALID_DATA_ATTRIBUTES 0x0040 // attributes are stored in Attr (ORed Win32 API constants FILE_ATTRIBUTE_XXX) (if not set: all Attr = 0) +#define VALID_DATA_HIDDEN 0x0080 // "ghosted" icon flag is stored in Hidden (if not set: all Hidden = 0) +#define VALID_DATA_ISLINK 0x0100 // IsLink contains 1 if it is a link, the icon has a link overlay (without: all IsLink = 0) +#define VALID_DATA_ISOFFLINE 0x0200 // IsOffline contains 1 if it is an offline file/directory, the icon has an offline overlay (without: all IsOffline = 0) +#define VALID_DATA_PL_SIZE 0x0400 // makes sense only without using VALID_DATA_SIZE: the plugin has the size of the file/directory stored in bytes (somewhere in PluginData), to get this size, Salamander calls CPluginDataInterfaceAbstract::GetByteSize() +#define VALID_DATA_PL_DATE 0x0800 // makes sense only without using VALID_DATA_DATE: the plugin has the modification date of the file/directory stored (somewhere in PluginData), to get this size, Salamander calls CPluginDataInterfaceAbstract::GetLastWriteDate() +#define VALID_DATA_PL_TIME 0x1000 // makes sense only without using VALID_DATA_TIME: the plugin has the modification time of the file/directory stored (somewhere in PluginData), to get this size, Salamander calls CPluginDataInterfaceAbstract::GetLastWriteTime() +#define VALID_DATA_ICONOVERLAY 0x2000 // IconOverlayIndex is the index of the icon overlay (no overlay = ICONOVERLAYINDEX_NOTUSED value) (if not used: all IconOverlayIndex = ICONOVERLAYINDEX_NOTUSED), icon assignment see CSalamanderGeneralAbstract::SetPluginIconOverlays + +#define VALID_DATA_NONE 0 // helper constant - valid for Name and NameLen only #ifdef INSIDE_SALAMANDER -// VALID_DATA_ALL a VALID_DATA_ALL_FS_ARC jsou jen pro interni pouziti v Salamanderovi (jadre), -// pluginy si naORuji jen konstanty odpovidajici pluginem dodavanym datum (zamezi se tak problemum -// pri zavedeni dalsich konstant a jim odpovidajicim datum) +// VALID_DATA_ALL and VALID_DATA_ALL_FS_ARC are only for internal use in Salamander (core), +// plugins only OR constants corresponding to the dates supplied by the plugins (this prevents +// problems when introducing additional constants and their corresponding dates) + #define VALID_DATA_ALL 0xFFFF -#define VALID_DATA_ALL_FS_ARC (0xFFFF & ~VALID_DATA_ICONOVERLAY) // pro FS a archivy: vse krome icon-overlays +#define VALID_DATA_ALL_FS_ARC (0xFFFF & ~VALID_DATA_ICONOVERLAY) // for FS and archives: everything except icon-overlays #endif // INSIDE_SALAMANDER -// Pokud je zapnuto skryvani hidden a system souboru a adresaru, nezobrazuji se v panelech polozky s -// Hidden==1 a Attr obsahujicim FILE_ATTRIBUTE_HIDDEN a/nebo FILE_ATTRIBUTE_SYSTEM. +// if hiding of hidden and system files and directories is turned on, items with Hidden==1 and Attr +// containing FILE_ATTRIBUTE_HIDDEN and/or FILE_ATTRIBUTE_SYSTEM are not displayed in the panels + +// constants of flags for CSalamangerDirectoryAbstract: +// names of files and directories (even in paths) are to be compared case-sensitive (without this flag, +// comparison is case-insensitive - standard behavior in Windows) -// konstanty priznaku pro CSalamanderDirectoryAbstract: -// jmena souboru a adresaru (i v cestach) se maji porovnavat case-sensitive (bez tohoto flagu je -// porovnavani case-insensitive - standardni chovani ve Windows) #define SALDIRFLAG_CASESENSITIVE 0x0001 -// jmena podadresaru v ramci kazdeho adresare se nebudou testovat na duplicitu (tento -// test je casove narocny a je nutny jen v archivech, pokud se pridavaji polozky nejen -// do rootu - aby fungovalo napr. pridani "file1" na "dir1" nasledovane pridanim -// "dir1" - "dir1" se prida prvni operaci (automaticky se prida neexistujici cesta), -// druha operace uz jen obnovi udaje o "dir1" (nesmi ho pridat znovu)) +// names of subdir in each directory are not tested for duplicity (this test is time-consuming and is +// necessary only in archives, if items are added not only to the root - to make it work, for example, +// adding "file1" to "dir1" followed by adding "dir1" - "dir1" is added by the first operation +// (the non-existent path is automatically added), the second operation only restores the data about "dir1" +// (it must not be added again) #define SALDIRFLAG_IGNOREDUPDIRS 0x0002 class CPluginDataInterfaceAbstract; @@ -280,75 +282,73 @@ class CPluginDataInterfaceAbstract; class CSalamanderDirectoryAbstract { public: - // vycisti cely objekt, pripravi ho pro dalsi pouziti; pokud 'pluginData' neni NULL, pouzije - // se pro soubory a adresare k uvolneni dat specifickych pluginu (CFileData::PluginData); - // nastavuje standardni hodnotu masky platnych dat (suma vsech VALID_DATA_XXX krome - // VALID_DATA_ICONOVERLAY) a priznaku objektu (viz metoda SetFlags) + // clear the entire object, prepare it for further use; if 'pluginData' is not NULL, it is used + // for files and directories to release data specific to plugins (CFileData::PluginData); + // sets the standard value of the mask of valid data (the sum of all VALID_DATA_XXX except + // VALID_DATA_ICONOVERLAY) and the flag of the object (see the SetFlags method) virtual void WINAPI Clear(CPluginDataInterfaceAbstract* pluginData) = 0; - // zadani masky platnych dat, podle ktere se urcuje, ktera data z CFileData jsou platna - // a ktera se maji pouze "nulovat" (viz komentar k VALID_DATA_XXX); maska 'validData' - // obsahuje ORovane hodnoty VALID_DATA_XXX; standardni hodnota masky je suma vsech - // VALID_DATA_XXX krome VALID_DATA_ICONOVERLAY; masku platnych dat je potreba nastavit - // pred volanim AddFile/AddDir + // set the mask of valid data, according to which it is determined which data from CFileData are valid + // and which should only be "zeroed" (see the comment for VALID_DATA_XXX); the mask 'validData' + // contains ORed values VALID_DATA_XXX; the standard value of the mask is the sum of all + // VALID_DATA_XXX except VALID_DATA_ICONOVERLAY; the mask of valid data must be set before calling + // AddFile/AddDir virtual void WINAPI SetValidData(DWORD validData) = 0; - // nastaveni priznaku pro tento objekt; 'flags' je kombinace ORovanych priznaku SALDIRFLAG_XXX, - // standardni hodnota priznaku objektu je nula pro archivatory (zadny priznak neni nastaven) - // a SALDIRFLAG_IGNOREDUPDIRS pro file-systemy (smi se pridavat jen do rootu, test na duplicitu - // adresaru je zbytecny) + // set the flag of the object; 'flags' is a combination of ORed flags SALDIRFLAG_XXX, the standard + // value of the object flag is zero for archivers (no flag is set) and SALDIRFLAG_IGNOREDUPDIRS + // for file systems (can only be added to the root, the test for duplicate directories is unnecessary) virtual void WINAPI SetFlags(DWORD flags) = 0; - // prida soubor na zadanou cestou (relativni k tomuto "salamander-adresari"), vraci uspech - // retezec path se pouziva jen uvnitr funkce, obsah struktury file se pouziva i mimo funkci - // (neuvolnovat pamet naalokovanou pro promenne uvnitr struktury) - // v pripade neuspechu, je treba obsah struktury file uvolnit; - // parametr 'pluginData' neni NULL jen pro archivy (FS pouzivaji jen prazdne 'path' (==NULL)); - // neni-li 'pluginData' NULL, pouziva se 'pluginData' pri zakladani novych adresaru (pokud - // 'path' neexistuje), viz CPluginDataInterfaceAbstract::GetFileDataForNewDir; - // kontrola unikatnosti jmena souboru na ceste 'path' se neprovadi + // add a file to the specified path (relative to this "salamander directory"), returns success + // the string 'path' is used only inside the function, the contents of the file structure are + // used outside the function as well (do not release the memory allocated for variables inside the structure) + // (if case of failure, the contents of the file structure must be released; + // the 'pluginData' parameter is not NULL only for archives (FS only use empty 'path' (==NULL)); + // if 'pluginData' is not NULL, it is used to create new directories (if 'path' does not exist), + // see CPluginDataInterfaceAbstract::GetFileDataForNewDir; + // the uniqueness of the file name on the path 'path' is not checked virtual BOOL WINAPI AddFile(const char* path, CFileData& file, CPluginDataInterfaceAbstract* pluginData) = 0; - // prida adresar na zadanou cestu (relativni k tomuto "salamander-adresari"), vraci uspech - // retezec path se pouziva jen uvnitr funkce, obsah struktury file se pouziva i mimo funkci - // (neuvolnovat pamet naalokovanou pro promenne uvnitr struktury) - // v pripade neuspechu, je treba obsah struktury file uvolnit; - // parametr 'pluginData' neni NULL jen pro archivy (FS pouzivaji jen prazdne 'path' (==NULL)); - // neni-li 'pluginData' NULL, pouziva se pri zakladani novych adresaru (pokud 'path' neexistuje), - // viz CPluginDataInterfaceAbstract::GetFileDataForNewDir; - // kontrola unikatnosti jmena adresare na ceste 'path' se provadi, dochazi-li k pridani - // jiz existujiciho adresare, dojde k uvolneni puvodnich dat (neni-li 'pluginData' NULL, vola - // se pro uvolneni dat i CPluginDataInterfaceAbstract::ReleasePluginData) a ulozeni dat z 'dir' - // (je nutne pro obnovu dat adresaru, ktere se vytvori automaticky pri neexistenci 'path'); - // specialita pro FS (nebo objekt alokovany pres CSalamanderGeneralAbstract::AllocSalamanderDirectory - // s 'isForFS'==TRUE): je-li dir.Name "..", je adresar pridan jako up-dir (muze byt jen jeden, - // zobrazuje se vzdy na zacatku listingu a ma specialni ikonu) + // add a directory to the specified path (relative to this "salamander directory"), returns success + // the string 'path' is used only inside the function, the contents of the file structure are + // used outside the function as well (do not release the memory allocated for variables inside the structure) + // (if case of failure, the contents of the file structure must be released; + // the 'pluginData' parameter is not NULL only for archives (FS only use empty 'path' (==NULL)); + // if 'pluginData' is not NULL, it is used to create new directories (if 'path' does not exist), + // see CPluginDataInterfaceAbstract::GetFileDataForNewDir; + // the uniqueness of the directory name on the path 'path' is checked, if a directory with the same + // name already exists, the original data are released (if 'pluginData' is not NULL, CPluginDataInterfaceAbstract::ReleasePluginData + // is called to release the data) and the data from 'dir' are saved (it is necessary to restore the data + // of the directory, which is automatically created when 'path' does not exist); + // speciality for FS (or an object allocated via CSalamanderGeneralAbstract::AllocSalamanderDirectory + // with 'isForFS'==TRUE): if dir.Name == "..", the directory is added as an up-dir (there can be only + // one, it is always displayed at the beginning of the listing and has a special icon) virtual BOOL WINAPI AddDir(const char* path, CFileData& dir, CPluginDataInterfaceAbstract* pluginData) = 0; - // vraci pocet souboru v objektu + // returns the number of files in the object virtual int WINAPI GetFilesCount() const = 0; - // vraci pocet adresaru v objektu + // returns the number of directories in the object virtual int WINAPI GetDirsCount() const = 0; - // vraci soubor z indexu 'index', vracena data lze pouzit jen pro cteni + // returns the files from the 'index' index, the returned data can only be used for reading virtual CFileData const* WINAPI GetFile(int index) const = 0; - // vraci adresar z indexu 'index', vracena data lze pouzit jen pro cteni + // returns the directory from the 'index' index, the returned data can only be used for reading virtual CFileData const* WINAPI GetDir(int index) const = 0; - // vraci objekt CSalamanderDirectory pro adresar z indexu 'index', vraceny objekt lze - // pouzit jen pro cteni (objekty pro prazdne adresare nejsou alokovany, vraci se jeden - // globalni prazdny objekt - zmena tohoto objektu by se projevila globalne) + // returns the object CSalamanderDirectory for the directory from the 'index' index, the returned object + // can only be used for reading (objects for empty directories are not allocated, one global empty object is returned + // - changing this object would be reflected globally) virtual CSalamanderDirectoryAbstract const* WINAPI GetSalDir(int index) const = 0; - // Pluginu umoznuje predem sdelit predpokladany pocet souboru a adresaru v tomto adresari. - // Salamander si upravi realokacni strategii tak, aby pridavani prvku prilis nebrzdilo. - // Ma smysl volat pro adresare obsahujici tisice souboru nebo adresaru. V pripade desitek - // tisic uz je zavolani teto metody temer nutnost, jinak realokace zaberou nekolik vterin. - // 'files' a 'dirs' tedy vyjadruji priblizny celkovy pocet souboru a adresaru. - // Pokud je nektera z hodnot -1, bude ji Salamander ignorovat. - // Metodu ma vyznam volat pouze pokud je adresar prazdny, tedy nebylo volano AddFile nebo AddDir. + // allows to inform the Plugin about expected number of files and directories in this directory beforehand. + // Salamander will adjust its reallocation strategy to avoid slowdowns when adding items. Makes sense only + // for directories containing thousands of files or directories. For tens of thousands of items it is + // almost a necessity, otherwise reallocations take several seconds. 'files' and 'dirs' express approximate + // total number of files and directories. If any of the values is -1, Salamander will ignore it. + // This method makes sense only if the directory is empty, i.e. AddFile or AddDir was not called. virtual void WINAPI SetApproximateCount(int files, int dirs) = 0; }; @@ -357,57 +357,54 @@ class CSalamanderDirectoryAbstract // SalEnumSelection a SalEnumSelection2 // -// konstanty vracene z SalEnumSelection a SalEnumSelection2 v parametru 'errorOccured' -#define SALENUM_SUCCESS 0 // chyba nenastala -#define SALENUM_ERROR 1 // nastala chyba a uzivatel si preje pokracovat v operaci (vynechaly se jen chybne soubory/adresare) -#define SALENUM_CANCEL 2 // nastala chyba a uzivatel si preje zrusit operaci - -// enumerator, vraci jmena souboru, konci vracenim NULL; -// 'enumFiles' == -1 -> reset enumerace (po tomto volani zacina enumerace opet od zacatku), vsechny -// dalsi parametry (az na 'param') jsou ignorovany, nema navratove hodnoty (dava -// vse na nulu) -// 'enumFiles' == 0 -> enumerace souboru a podadresaru jen z korene -// 'enumFiles' == 1 -> enumerace vsech souboru a podadresaru -// 'enumFiles' == 2 -> enumerace vsech podadresaru, soubory jen z korene; -// k chybe muze dojit jen pri 'enumFiles' == 1 nebo 'enumFiles' == 2 ('enumFiles' == 0 nekompletuje -// jmena a cesty); 'parent' je parent pripadnych messageboxu s chybami (NULL znamena nezobrazovat -// chyby); v 'isDir' (neni-li NULL) vraci TRUE pokud jde o adresar; v 'size' (neni-li NULL) vraci -// velikost souboru (u adresaru se vraci velikost jen pri 'enumFiles' == 0 - jinak je nulova); -// neni-li 'fileData' NULL, vraci se v nem ukazatel na strukturu CFileData vraceneho -// souboru/adresare (pokud enumerator vraci NULL, vraci se v 'fileData' take NULL); -// 'param' je parametr 'nextParam' predavany spolu s ukazatelem na funkci tohoto -// typu; v 'errorOccured' (neni-li NULL) se vraci SALENUM_ERROR, pokud se pri sestavovani vracenych -// jmen narazilo na prilis dlouhe jmeno a uzivatel se rozhodl preskocit jen chybne soubory/adresare, -// POZOR: chyba se netyka prave vraceneho jmena, to je OK; v 'errorOccured' (neni-li NULL) se vraci -// SALENUM_CANCEL pokud se pri chybe uzivatel rozhodl pro zruseni operace (cancel), zaroven -// enumerator vraci NULL (konci); v 'errorOccured' (neni-li NULL) se vraci SALENUM_SUCCESS pokud -// zadna chyba nenastala +// constants returned from SalEnumSelection a SalEnumSelection2 in the 'errorOccured' parameter +#define SALENUM_SUCCESS 0 // error did not occur +#define SALENUM_ERROR 1 // error occurred and the user wants to continue the operation (only incorrectly named files/directories were skipped) +#define SALENUM_CANCEL 2 // error occurred and the user wants to cancel the operation + +// enumerator, returns file names, ends with NULL; +// 'enumFiles' == -1 -> enumeration reset (after this call, the enumeration starts again from the beginning), +// all other parameters (except 'param') are ignored, no return values (everything is set to zero) +// 'enumFiles' == 0 -> enumeration of files and subdirectories only from the root +// 'enumFiles' == 1 -> enumeration of all files and subdirectories +// 'enumFiles' == 2 -> enumeration of all subdirectories, files only from the root; +// an error can occur only when 'enumFiles' == 1 or 'enumFiles' == 2 ('enumFiles' == 0 does not make +// names and paths complete); 'parent' is the parent of any error message boxes (NULL means not to show errors); +// 'isDir' (if not NULL) returns TRUE if it is a directory; 'size' (if not NULL) returns the size of the file +// (for directories it only returns the size when 'enumFiles' == 0 - otherwise it is zero); +// if 'fileData' is not NULL, it returns a pointer to the CFileData structure of the returned file/directory +// (if the enumerator returns NULL, NULL is also returned in 'fileData'); +// 'param' is the parameter 'nextParam' passed together with the pointer to the function of this type; +// 'errorOccured' (if not NULL) returns SALENUM_ERROR, if a very long name was encountered during the +// compilation of the returned names and the user decided to skip only the incorrect files/directories, +// CAUTION: the error does not apply to the name returned, it is OK; 'errorOccured' (if not NULL) returns +// SALENUM_CANCEL if the user decided to cancel the operation (cancel), at the same time the enumerator +// returns NULL (ends); 'errorOccured' (if not NULL) returns SALENUM_SUCCESS if no error occurred typedef const char*(WINAPI* SalEnumSelection)(HWND parent, int enumFiles, BOOL* isDir, CQuadWord* size, const CFileData** fileData, void* param, int* errorOccured); -// enumerator, vraci jmena souboru, konci vracenim NULL; -// 'enumFiles' == -1 -> reset enumerace (po tomto volani zacina enumerace opet od zacatku), vsechny -// dalsi parametry (az na 'param') jsou ignorovany, nema navratove hodnoty (dava -// vse na nulu) -// 'enumFiles' == 0 -> enumerace souboru a podadresaru jen z korene -// 'enumFiles' == 1 -> enumerace vsech souboru a podadresaru -// 'enumFiles' == 2 -> enumerace vsech podadresaru, soubory jen z korene; -// 'enumFiles' == 3 -> enumerace vsech souboru a podadresaru + symbolicke linky na soubory maji -// velikost ciloveho souboru (pri 'enumFiles' == 1 maji velikost linku, coz je snad -// vzdy nula); POZOR: 'enumFiles' musi zustat 3 pro vsechna volani enumeratoru; -// k chybe muze dojit jen pri 'enumFiles' == 1, 2 nebo 3 ('enumFiles' == 0 vubec -// nepracuje s diskem ani nekompletuje jmena a cesty); 'parent' je parent pripadnych messageboxu -// s chybami (NULL znamena nezobrazovat chyby); v 'dosName' (neni-li NULL) vraci DOSovy nazev -// (8.3; jen pokud existuje, jinak NULL); v 'isDir' (neni-li NULL) vraci TRUE pokud jde o adresar; -// v 'size' (neni-li NULL) vraci velikost souboru (u adresaru nulu); v 'attr' (neni-li NULL) -// vraci atributy souboru/adresare; v 'lastWrite' (neni-li NULL) vraci cas posledniho zapisu -// do souboru/adresare; 'param' je parametr 'nextParam' predavany spolu s ukazatelem na funkci -// tohoto typu; v 'errorOccured' (neni-li NULL) se vraci SALENUM_ERROR, pokud doslo behem cteni -// dat z disku k chybe nebo se pri sestavovani vracenych jmen narazilo na prilis dlouhe jmeno -// a uzivatel se rozhodl preskocit jen chybne soubory/adresare, POZOR: chyba se netyka prave -// vraceneho jmena, to je OK; v 'errorOccured' (neni-li NULL) se vraci SALENUM_CANCEL pokud se -// pri chybe uzivatel rozhodl pro zruseni operace (cancel), zaroven enumerator vraci NULL (konci); -// v 'errorOccured' (neni-li NULL) se vraci SALENUM_SUCCESS pokud zadna chyba nenastala +// enumerator, returns file names, ends with NULL; +// 'enumFiles' == -1 -> enumeration reset (after this call, the enumeration starts again from the beginning), +// all other parameters (except 'param') are ignored, no return values (everything is set to zero) +// 'enumFiles' == 0 -> enumeration of files and subdirectories only from the root +// 'enumFiles' == 1 -> enumeration of all files and subdirectories +// 'enumFiles' == 2 -> enumeration of all subdirectories, files only from the root; +// 'enumFiles' == 3 -> enumeration of all files and subdirectories, symbolic links to files have +// the size of the target file (for 'enumFiles' == 1 they have the size of the link, +// which is probably always zero); CAUTION: 'enumFiles' must remain 3 for all calls +// to the enumerator; +// an error can occur only when 'enumFiles' == 1, 2 or 3 ('enumFiles' == 0 does not work with the disk +// or complete names and paths); 'parent' is the parent of any error message boxes (NULL means not to show errors); +// 'dosName' (if not NULL) returns the DOS name (8.3; only if it exists, otherwise NULL); 'isDir' (if not NULL) +// returns TRUE if it is a directory; 'size' (if not NULL) returns the size of the file (for directories +// returns zero); 'attr' (if not NULL) returns the attributes of the file/directory; 'lastWrite' (if not NULL) +// returns the time of the last write to the file/directory; 'param' is the parameter 'nextParam' passed +// together with the pointer to the function of this type; 'errorOccured' (if not NULL) returns SALENUM_ERROR, +// if an error occurred while reading data from the disk or if a very long name was encountered during the +// compilation of the returned names and the user decided to skip only the incorrect files/directories, +// CAUTION: the error does not apply to the name returned, it is OK; 'errorOccured' (if not NULL) returns +// SALENUM_CANCEL if the user decided to cancel the operation (cancel), at the same time the enumerator +// returns NULL (ends); 'errorOccured' (if not NULL) returns SALENUM_SUCCESS if no error occurred typedef const char*(WINAPI* SalEnumSelection2)(HWND parent, int enumFiles, const char** dosName, BOOL* isDir, CQuadWord* size, DWORD* attr, FILETIME* lastWrite, void* param, int* errorOccured); @@ -416,8 +413,9 @@ typedef const char*(WINAPI* SalEnumSelection2)(HWND parent, int enumFiles, const // **************************************************************************** // CSalamanderViewAbstract // -// sada metod Salamandera pro praci se sloupci v panelu (vypinani/zapinani/pridavani/nastavovani) +// set of Salamander methods for working with columns in the panel (turning off/on/adding/setting) +// panel view modes // rezimy pohledu panelu #define VIEW_MODE_TREE 1 #define VIEW_MODE_BRIEF 2 @@ -426,164 +424,157 @@ typedef const char*(WINAPI* SalEnumSelection2)(HWND parent, int enumFiles, const #define VIEW_MODE_THUMBNAILS 5 #define VIEW_MODE_TILES 6 -#define TRANSFER_BUFFER_MAX 1024 // velikost bufferu pro prenos obsahu sloupcu z pluginu do Salamandera +#define TRANSFER_BUFFER_MAX 1024 // buffer size for transferring column contents from the plugin to Salamander #define COLUMN_NAME_MAX 30 #define COLUMN_DESCRIPTION_MAX 100 -// Identifikatory sloupcu. Sloupce vlozene pluginem maji nastaveno ID==COLUMN_ID_CUSTOM. -// Standardni sloupce Salamandera maji ostatni ID. -#define COLUMN_ID_CUSTOM 0 // sloupec je poskytovan pluginem - o ulozeni jeho dat se postara plugin -#define COLUMN_ID_NAME 1 // zarovnano vlevo, podporuje FixedWidth -// zarovnano vlevo, podporuje FixedWidth; samostatny sloupec "Ext", muze byt jen na indexu==1; -// pokud sloupec neexistuje a v datech panelu (viz CSalamanderDirectoryAbstract::SetValidData()) -// se nastavi VALID_DATA_EXTENSION, je sloupec "Ext" zobrazen ve sloupci "Name" +// Columns identifiers. Columns added by the plugin have ID==COLUMN_ID_CUSTOM. +// Salamander default columns have other IDs. +#define COLUMN_ID_CUSTOM 0 // the column is provided by the plugin - the plugin will take care of saving its data +#define COLUMN_ID_NAME 1 // aligned to the left, supports FixedWidth +// aligned to the left, supports FixedWidth; separate column "Ext" can only be at index==1; +// if the column does not exist and VALID_DATA_EXTENSION is set in the panel data (see CSalamanderDirectoryAbstract::SetValidData()), +// the column "Ext" is displayed in the column "Name" #define COLUMN_ID_EXTENSION 2 -#define COLUMN_ID_DOSNAME 3 // zarovnano vlevo -#define COLUMN_ID_SIZE 4 // zarovnano vpravo -#define COLUMN_ID_TYPE 5 // zarovnano vlevo, podporuje FixedWidth -#define COLUMN_ID_DATE 6 // zarovnano vpravo -#define COLUMN_ID_TIME 7 // zarovnano vpravo -#define COLUMN_ID_ATTRIBUTES 8 // zarovnano vpravo -#define COLUMN_ID_DESCRIPTION 9 // zarovnano vlevo, podporuje FixedWidth - -// Callback pro naplneni bufferu znakama, ktere se maji zobrazit v prislusnem sloupci. -// Z duvodu optimalizace funkce nedostava/nevraci promenne prostrednictvim parametru, -// ale prostrednictvim globalni promennych (CSalamanderViewAbstract::GetTransferVariables). +#define COLUMN_ID_DOSNAME 3 // aligned to the left +#define COLUMN_ID_SIZE 4 // aligned to the right +#define COLUMN_ID_TYPE 5 // aligned to the left, supports FixedWidth +#define COLUMN_ID_DATE 6 // aligned to the right +#define COLUMN_ID_TIME 7 // aligned to the right +#define COLUMN_ID_ATTRIBUTES 8 // aligned to the right +#define COLUMN_ID_DESCRIPTION 9 // aligned to the left, supports FixedWidth + +// Callback for filling the buffer with characters to be displayed in the corresponding column. +// For optimization reasons, the function does not receive/return variables via parameters, +// but via global variables (CSalamanderViewAbstract::GetTransferVariables). typedef void(WINAPI* FColumnGetText)(); -// Callback pro ziskani indexu jednoduchych ikon pro FS s vlastnimi ikonami (pitFromPlugin). -// Z duvodu optimalizace funkce nedostava/nevraci promenne prostrednictvim parametru, -// ale prostrednictvim globalni promennych (CSalamanderViewAbstract::GetTransferVariables). -// Z globalnich promennych callback vyuziva jen TransferFileData a TransferIsDir. +// Callback to get index of simple icons for FS with custom icons (pitFromPlugin). +// For optimization reasons, the function does not receive/return variables via parameters, +// but via global variables (CSalamanderViewAbstract::GetTransferVariables). +// Only TransferFileData and TransferIsDir are used from the global variables. typedef int(WINAPI* FGetPluginIconIndex)(); -// sloupec muze vzniknout dvema zpusoby: -// 1) Sloupec vytvoril Salamander na zaklade sablony aktualniho pohledu. -// V tomto pripade ukazatel 'GetText' (na plnici funkci) ukazuje do Salamandera -// a ziskava texty standardne z CFileData. -// Hodnota promenne 'ID' je ruzna od COLUMN_ID_CUSTOM. +// column can only be created by these two ways: +// 1) Salamander creates a column based on the template of the current view. +// In this case, the 'GetText' pointer (to the filler function) points to Salamander +// and gets the texts from CFileData. +// The value of the 'ID' variable is different from COLUMN_ID_CUSTOM. // -// 2) Sloupec pridal plugin na zaklade svych potreb. -// 'GetText' ukazuje do pluginu a 'ID' je rovno COLUMN_ID_CUSTOM. +// 2) The plugin added the column based on its needs. +// 'GetText' points to the plugin and 'ID' is equal to COLUMN_ID_CUSTOM. struct CColumn { - char Name[COLUMN_NAME_MAX]; // "Name", "Ext", "Size", ... nazev sloupce, pod - // kterym sloupec vystupuje v pohledu a v menu - // Nesmi obsahovat prazdny retezec. - // POZOR: Muze obsahovat (za prvnim null-terminatorem) - // i nazev sloupce "Ext" - toto nastava pokud neexistuje - // samostatny sloupec "Ext" a v datech panelu (viz - // CSalamanderDirectoryAbstract::SetValidData()) se - // nastavi VALID_DATA_EXTENSION. Pro spojeni dvou - // retezcu poslouzi CSalamanderGeneralAbstract::AddStrToStr(). - - char Description[COLUMN_DESCRIPTION_MAX]; // Tooltip v header line - // Nesmi obsahovat prazdny retezec. - // POZOR: Muze obsahovat (za prvnim null-terminatorem) - // i popis sloupce "Ext" - toto nastava pokud neexistuje - // samostatny sloupec "Ext" a v datech panelu (viz - // CSalamanderDirectoryAbstract::SetValidData()) se - // nastavi VALID_DATA_EXTENSION. Pro spojeni dvou - // retezcu poslouzi CSalamanderGeneralAbstract::AddStrToStr(). - - FColumnGetText GetText; // callback pro ziskani textu (popis u deklatace typu FColumnGetText) - - // FIXME_X64 - male pro ukazatel, neni nekdy potreba? - DWORD CustomData; // Neni pouzivana Salamanderem; plugin ji muze - // vyuzit pro rozliseni svych pridanych sloupcu. - - unsigned SupportSorting : 1; // je sloupec mozne radit? - - unsigned LeftAlignment : 1; // pro TRUE je sloupec zarovnavan vlevo; jinak vpravo - - unsigned ID : 4; // identifikator sloupce - // Pro standardni sloupce poskytovane Salamanderem - // obsahuje hodnoty ruzne od COLUMN_ID_CUSTOM. - // Pro sloupce pridane pluginem obsahuje vzdy - // hodnotu COLUMN_ID_CUSTOM. - - // Promenne Width a FixedWidth muzou byt zmeneny uzivatelem behem prace s panelem. - // Standardni sloupce poskytovane Salamanderem maji zajisteno ukladani/nacitani - // techto hodnot. - // Hodnoty techto promennych pro sloupce poskytovane pluginem je treba ulozit/nacist - // v ramci pluginu. - // Sloupce, jejichz sirku pocita Salamander na zaklade obsahu a uzivatel ji nemuze - // menit, nazyvame 'elasticke'. Sloupce, pro ktere muze uzivatel nastavit sirku nazyvame - // 'pevne'/'fixed'. - unsigned Width : 16; // Sirka sloupce v pripade, ze je v rezimu pevne (nastavitelne) sirky. - unsigned FixedWidth : 1; // Je sloupec v rezimu pevne (nastavitelne) sirky? - - // pracovni promenne (nikam se neukladaji a neni treba je inicializovat) - // jsou urcene pro interni potreby Salamandera a pluginy je ignoruji, - // protoze jejich obsah neni pri volani pluginu zaruceny - unsigned MinWidth : 16; // Minimalni sirka, na kterou muze byt sloupce smrsten. - // Je pocitana na zaklade nazvu sloupce a jeho raditelnosti - // tak, aby byla hlavicka sloupce vzdy viditelna + char Name[COLUMN_NAME_MAX]; // "Name", "Ext", "Size", ... name of column, under + // which the column appears in the view and in the menu + // Must not contain an empty string. + // CAUTION: It may contain (after the first null-terminator) + // also the name of the column "Ext" - this happens if there is no + // separate column "Ext" and in the data of the panel (see + // CSalamanderDirectoryAbstract::SetValidData()) VALID_DATA_EXTENSION is set. + // To join two strings, use CSalamanderGeneralAbstract::AddStrToStr(). + + char Description[COLUMN_DESCRIPTION_MAX]; // Tooltip in header line + // Must not contain an empty string. + // CAUTION: It may contain (after the first null-terminator) + // also the description of the column "Ext" - this happens if there is no + // separate column "Ext" and in the data of the panel (see + // CSalamanderDirectoryAbstract::SetValidData()) VALID_DATA_EXTENSION is set. + // To join two strings, use CSalamanderGeneralAbstract::AddStrToStr(). + + FColumnGetText GetText; // callback to get the text (description at the FColumnGetText type declaration) + + // FIXME_X64 - small for pointer, isn't it sometimes needed? + DWORD CustomData; // not used by Salamander; the plugin can use it to distinguish its added columns. + + unsigned SupportSorting : 1; // can the column be sorted? + + unsigned LeftAlignment : 1; // for TRUE, the column is aligned to the left; otherwise to the right + + unsigned ID : 4; // column identifier + // For standard columns provided by Salamander + // it contains values other than COLUMN_ID_CUSTOM. + // For columns added by the plugin, it always contains + // the value COLUMN_ID_CUSTOM. + // The variables Width and FixedWidth can be changed by the user during work with the panel. + // Standard columns provided by Salamander have the saving/loading of these values + // ensured. The values of these variables for columns provided by the plugin must be saved/loaded + // within the plugin. + // Columns whose width is calculated by Salamander based on the content and the user cannot + // change it are called 'elastic'. Columns for which the user can set the width are called + // 'fixed'. + unsigned Width : 16; // Column width in case of fixed (adjustable) width. + unsigned FixedWidth : 1; // Is the column in fixed (adjustable) width mode? + + // working variables (not saved anywhere and it is not necessary to initialize them) + // they are intended for internal needs of Salamander and plugins ignore them, + // because their content is not guaranteed when calling plugins + unsigned MinWidth : 16; // Minimal width to which the column can be narrowed. + // It is calculated based on the column name and its sortability + // so that the column header is always visible }; -// Plugin prostrednictvim tohoto rozhrani muze pri zmene cesty zmenit rezim -// zobrazeni v panelu. Veskera prace se sloupci se tyka jen vsech detailed rezimu -// (Detailed + Types + tri volitelne rezimy Alt+8/9/0). Pri zmene cesty dostane -// plugin standardni sadu sloupcu nagenerovanou na zaklade sablony aktualniho -// pohledu. Plugin muze tuto sadu modifikovat. Modifikace neni trvaleho razu -// a pri pristi zmene cesty obdrzi plugin opet standardni sadu sloupcu. Muze tak -// napriklad odstranit nektery ze std. sloupcu. Pred novym plnenim std. sloupci -// dostane plugin prilezitost ulozeni informaci o svych sloupcich (COLUMN_ID_CUSTOM). -// Muze tak ulozit jejich 'Width' a 'FixedWidth', ktere uzivatel mohl v panelu -// nastavit (viz ColumnFixedWidthShouldChange() a ColumnWidthWasChanged() v interfacu -// CPluginDataInterfaceAbstract). Pokud plugin zmeni rezim pohledu, zmena je trvala -// (napr. prepnuti na rezim Thumbnails zustane i po opusteni pluginove cesty). +// Plugin can change the mode of displaying the panel via this interface when the path changes. +// All work with columns concerns only all detailed modes (Detailed + Types + three optional modes Alt+8/9/0). +// When the path changes, the plugin gets the standard set of columns generated based on the template +// of the current view. The plugin can modify this set. The modification is not permanent and when the +// path changes again, the plugin gets the standard set of columns again. It can, for example, remove +// some of the std. columns. Before filling the std. columns again, the plugin gets the opportunity +// to save information about its columns (COLUMN_ID_CUSTOM). It can save their 'Width' and 'FixedWidth', +// which the user could set in the panel (see ColumnFixedWidthShouldChange() and ColumnWidthWasChanged() +// in the interface CPluginDataInterfaceAbstract). If the plugin changes the view mode, the change is permanent +// (e.g. switching to the Thumbnails mode remains even after leaving the plugin path). class CSalamanderViewAbstract { public: // -------------- panel ---------------- - // vraci rezim, ve kterem je zobrazen panel (tree/brief/detailed/icons/thumbnails/tiles) - // vraci jednu z hodnot VIEW_MODE_xxxx (rezim Detailed, Types a tri volitelne rezimy jsou - // vsechny VIEW_MODE_DETAILED) + // returns mode in which the panel is displayed (tree/brief/detailed/icons/thumbnails/tiles) + // returns one of the values VIEW_MODE_xxxx (mode Detailed, Types and three optional modes are + // all VIEW_MODE_DETAILED) virtual DWORD WINAPI GetViewMode() = 0; - // Nastavi rezim panelu na 'viewMode'. Pokud jde o nektery z detailed rezimu, muze - // odstranit nektere ze standardnich sloupcu (viz. 'validData'). Proto je vhodne tuto - // funkci volat jako prvni - pred ostatnimi funkcemi z toho ifacu, ktere modifikuji - // sloupce. + // set the panel mode to 'viewMode'. If it is one of the detailed modes, it can remove some of + // the standard columns (see 'validData'). Therefore, it is appropriate to call this function + // first - before other functions from this interface that modify columns. // - // 'viewMode' je jedna z hodnot VIEW_MODE_xxxx - // Rezim panelu nelze zmenit ani na Types ani na jeden ze tri volitelnych detailed rezimu - // (vsechny zastupuje konstanta VIEW_MODE_DETAILED pouzita pro Detailed rezim panelu). - // Ovsem pokud je zrovna jeden z techto ctyr rezimu v panelu zvoleny a 'viewMode' je - // VIEW_MODE_DETAILED, zustane tento rezim zvoleny (aneb neprepne se na Detailed rezim). - // Zmena rezimu panelu je trvala (pretrva i po opusteni pluginove cesty). + // 'viewMode' is one of the values VIEW_MODE_xxxx + // The panel mode cannot be changed to Types or one of the three optional detailed modes + // (all are represented by the constant VIEW_MODE_DETAILED used in the Detailed mode of the panel). + // However, if one of these four modes is currently selected in the panel and 'viewMode' is + // VIEW_MODE_DETAILED, this mode remains selected (or in other words, it does not switch to + // the Detailed mode). + // Changing the panel mode is permanent (it persists even after leaving the plugin path). // - // 'validData' informuje o tom, jaka data si plugin preje zobrazit v detailed rezimu, hodnota - // se ANDuje s maskou platnych dat zadanou pomoci CSalamanderDirectoryAbstract::SetValidData - // (nema smysl zobrazovat sloupce s "nulovanymi" hodnotami). + // 'validData' informs about what data the plugin wants to display in the detailed mode, the value + // is ANDed with the mask of valid data specified by CSalamanderDirectoryAbstract::SetValidData + // (it does not make sense to display columns with "zeroed" values). virtual void WINAPI SetViewMode(DWORD viewMode, DWORD validData) = 0; - // Vyzvedne ze Salamandera umisteni promennych, ktere nahrazuji parametry callbacku - // CColumn::GetText. Na strane Salamandera se jedna o globalni promenne. Plugin si - // ukazatele na ne ulozi do vlastnich globalnich promennych. + // Get locations of variables from Salamander that replace callback parameters + // CColumn::GetText. On the Salamander side, these are global variables. The plugin + // saves pointers to them in its own global variables. // - // promenne: - // transferFileData [IN] data, na jejichz zaklade se ma vykreslit polozka - // transferIsDir [IN] rovno 0, pokud jde o soubor (lezi v poli Files), - // rovno 1, pokud jde o adresar (lezi v poli Dirs), - // rovno 2, pokud jde o up-dir symbol - // transferBuffer [OUT] sem se nalejou data, maximalne TRANSFER_BUFFER_MAX znaku - // neni treba je terminovat nulou - // transferLen [OUT] pred navratem z callbacku se do teto promenne nastavi - // pocet naplnenych znaku bez terminatoru (terminator neni - // treba do bufferu zapisovat) - // transferRowData [IN/OUT] ukazuje na DWORD, ktery je vzdy pred kreslenim sloupcu - // pro kazdy radek nulovan; lze pouzit pro optimalizace - // Salamander ma vyhrazene bity 0x00000001 az 0x00000008. - // Ostatni bity jsou k dispozici pro plugin. - // transferPluginDataIface [IN] plugin-data-interface panelu, do ktereho se polozka - // vykresluje (patri k (*transferFileData)->PluginData) - // transferActCustomData [IN] CustomData sloupce, pro ktery se ziskava text (pro ktery - // se vola callback) + // variables: + // transferFileData [IN] data based on which the item is to be drawn + // transferIsDir [IN] equal to 0 if it is a file (it is in the array Files), + // equal to 1 if it is a directory (it is in the array Dirs), + // equal to 2 if it is an up-dir symbol + // transferBuffer [OUT] data are poured into this buffer, maximum TRANSFER_BUFFER_MAX characters + // it is not necessary to terminate them with a zero + // transferLen [OUT] before returning from the callback, the number of filled characters + // without a terminator is set in this variable (the terminator does not + // need to be written to the buffer) + // transferRowData [IN/OUT] points to DWORD, which is always zeroed before drawing columns + // for each row; can be used for optimizations + // Salamander has reserved bits 0x00000001 to 0x00000008. + // Other bits are available for the plugin. + // transferPluginDataIface [IN] plugin-data-interface of the panel to which the item is drawn + // (belongs to (*transferFileData)->PluginData) + // transferActCustomData [IN] CustomData of the column for which the text is obtained (for which + // the callback is called) virtual void WINAPI GetTransferVariables(const CFileData**& transferFileData, int*& transferIsDir, char*& transferBuffer, @@ -592,49 +583,47 @@ class CSalamanderViewAbstract CPluginDataInterfaceAbstract**& transferPluginDataIface, DWORD*& transferActCustomData) = 0; - // jen pro FS s vlastnimi ikonami (pitFromPlugin): - // Nastavi callback pro ziskani indexu jednoduchych ikon (viz - // CPluginDataInterfaceAbstract::GetSimplePluginIcons). Pokud tento callback - // plugin nenastavi, bude se vykreslovat vzdy jen ikona z indexu 0. - // Z globalnich promennych callback vyuziva jen TransferFileData a TransferIsDir. + // for FS with custom icons only (pitFromPlugin): + // Sets callback for getting index of simple icons (see CPluginDataInterfaceAbstract::GetSimplePluginIcons). + // If this callback is not set by the plugin, only icon from index 0 will be drawn. + // Only TransferFileData and TransferIsDir are used from the global variables. virtual void WINAPI SetPluginSimpleIconCallback(FGetPluginIconIndex callback) = 0; // ------------- columns --------------- - // vraci pocet sloupcu v panelu (vzdy minimalne jeden, protoze nazev bude vzdy zobrazen) + // returns the number of columns in the panel (always at least one, because the column "Name" is always displayed) virtual int WINAPI GetColumnsCount() = 0; - // vraci ukazatel na sloupec (pouze pro cteni) - // 'index' udava, ktery ze sloupcu bude vracen; pokud sloupec 'index' neexistuje, vraci NULL + // returns a pointer to the column (read-only) + // 'index' specifies which of the columns will be returned; if the column 'index' does not exist, NULL is returned virtual const CColumn* WINAPI GetColumn(int index) = 0; - // Vlozi sloupec na pozici 'index'. Na pozici 0 je vzdy umisten sloupec Name, - // pokud je zobrazen sloupec Ext, bude na pozici 1. Jinak lze sloupec umistit - // libovolne. Struktura 'column' bude prekopirovana do vnitrnich struktur - // Salamandera. Vraci TRUE pokud byl sloupec vlozen. + // returns column to the position 'index'. The column Name is always placed at position 0, + // if the column Ext is displayed, it will be at position 1. Otherwise, the column can be placed + // anywhere. The structure 'column' will be copied to the Salamander internal structures. + // Returns TRUE if the column was inserted. virtual BOOL WINAPI InsertColumn(int index, const CColumn* column) = 0; - // Vlozi standardni sloupec s ID 'id' na pozici 'index'. Na pozici 0 je vzdy - // umisten sloupec Name, pokud je vkladan sloupec Ext, musi to byt na pozici 1. - // Jinak lze sloupec umistit libovolne. 'id' je jedna z hodnot COLUMN_ID_xxxx, - // mimo COLUMN_ID_CUSTOM a COLUMN_ID_NAME. + // inserts the standard column with ID 'id' at position 'index'. The column Name is always placed + // at position 0, if the column Ext is inserted, it must be at position 1. Otherwise, the column + // can be placed anywhere. 'id' is one of the values COLUMN_ID_xxxx, except COLUMN_ID_CUSTOM and + // COLUMN_ID_NAME. virtual BOOL WINAPI InsertStandardColumn(int index, DWORD id) = 0; - // Nastavi nazev a popis sloupce (nesmi byt prazdne retezce ani NULL). Delky - // retezu se omezi na COLUMN_NAME_MAX a COLUMN_DESCRIPTION_MAX. Vraci uspech. - // POZOR: Jmeno a popis sloupce "Name" muzou obsahovat (vzdy za prvnim - // null-terminatorem) i jmeno a popis sloupce "Ext" - toto nastava pokud - // neexistuje samostatny sloupec "Ext" a v datech panelu (viz - // CSalamanderDirectoryAbstract::SetValidData()) se nastavi VALID_DATA_EXTENSION. - // V tomto pripade je potreba nastavovat dvojite retezce (s dvoumi - // null-terminatory) - viz CSalamanderGeneralAbstract::AddStrToStr(). + // sets the name and description of the column (cannot be empty strings or NULL). The length of + // the string is limited to COLUMN_NAME_MAX and COLUMN_DESCRIPTION_MAX. Returns success. + // CAUTION: The name and description of the column "Name" may contain (always after the first + // null-terminator) also the name and description of the column "Ext" - this happens if there is + // no separate column "Ext" and in the data of the panel (see CSalamanderDirectoryAbstract::SetValidData()) + // VALID_DATA_EXTENSION is set. In this case, it is necessary to set double strings (with two + // null-terminators) - see CSalamanderGeneralAbstract::AddStrToStr(). virtual BOOL WINAPI SetColumnName(int index, const char* name, const char* description) = 0; - // Odstrani sloupec na pozici 'index'. Lze odstranit jak sloupce pridane pluginem, - // tak standardni sloupce Salamandera. Nelze odstranit sloupec 'Name', ktery je vzdy - // na indexu 0. Pozor pri odstranovani sloupce 'Ext', pokud je v datech pluginu - // (viz CSalamanderDirectoryAbstract::SetValidData()) VALID_DATA_EXTENSION, musi - // se jmeno+popis sloupce 'Ext' objevit u sloupce 'Name'. + // removes column at position 'index'. It is possible to remove both columns added by the plugin + // and standard columns provided by Salamander. The column 'Name' cannot be removed, it is always + // at position 0. Be careful when removing the column 'Ext', if the plugin data (see + // CSalamanderDirectoryAbstract::SetValidData()) VALID_DATA_EXTENSION is set, the column 'Ext' + // must be displayed in the column 'Name'. virtual BOOL WINAPI DeleteColumn(int index) = 0; }; @@ -642,184 +631,184 @@ class CSalamanderViewAbstract // **************************************************************************** // CPluginDataInterfaceAbstract // -// sada metod pluginu, ktere potrebuje Salamander pro ziskani specifickych dat -// pluginu do pluginem pridanych sloupcu (pracuje s CFileData::PluginData) +// set of plugin methods which are needed by Salamander to get specific data of the plugin +// into the columns added by the plugin (works with CFileData::PluginData) class CPluginInterfaceAbstract; class CPluginDataInterfaceAbstract { #ifdef INSIDE_SALAMANDER -private: // ochrana proti nespravnemu primemu volani metod (viz CPluginDataInterfaceEncapsulation) +private: // protection against incorrect calling of methods (see CPluginDataInterfaceEncapsulation) friend class CPluginDataInterfaceEncapsulation; #else // INSIDE_SALAMANDER public: #endif // INSIDE_SALAMANDER - // vraci TRUE pokud se ma zavolat metoda ReleasePluginData pro vsechny soubory vazane - // k tomuto interfacu, jinak vraci FALSE + // returns TRUE if the method ReleasePluginData is about to be called for all files related + // to this interface, otherwise return FALSE virtual BOOL WINAPI CallReleaseForFiles() = 0; - // vraci TRUE pokud se ma zavolat metoda ReleasePluginData pro vsechny adresare vazane - // k tomuto interfacu, jinak vraci FALSE + // returns TRUE if the method ReleasePluginData is about to be called for all directories related + // to this interface, otherwise return FALSE virtual BOOL WINAPI CallReleaseForDirs() = 0; - // uvolni data specificka pluginu (CFileData::PluginData) pro 'file' (soubor nebo - // adresar - 'isDir' FALSE nebo TRUE; struktura vlozena do CSalamanderDirectoryAbstract - // pri listovani archivu nebo FS); vola se pro vsechny soubory, pokud CallReleaseForFiles - // vrati TRUE, a pro vsechny adresare, pokud CallReleaseForDirs vrati TRUE + // releeases data specific to the plugin (CFileData::PluginData) for 'file' (file or directory - + // 'isDir' FALSE or TRUE; structure inserted into CSalamanderDirectoryAbstract when listing archives + // or FS); called for all files if CallReleaseForFiles returns TRUE, and for all directories if + // CallReleaseForDirs returns TRUE virtual void WINAPI ReleasePluginData(CFileData& file, BOOL isDir) = 0; - // jen pro data archivu (pro FS se nedoplnuje up-dir symbol): - // pozmenuje navrhovany obsah up-dir symbolu (".." nahore v panelu); 'archivePath' - // je cesta v archivu, pro kterou je symbol urcen; v 'upDir' vstupuji navrzena - // data symbolu: jmeno ".." (nemenit), date&time archivu, zbytek nulovany; - // v 'upDir' vystupuji zmeny pluginu, predevsim by mel zmenit 'upDir.PluginData', - // ktery bude vyuzivan na up-dir symbolu pri ziskavani obsahu pridanych sloupcu; - // pro 'upDir' se nebude volat ReleasePluginData, jakekoliv potrebne uvolnovani - // je mozne provest vzdy pri dalsim volani GetFileDataForUpDir nebo pri uvolneni - // celeho interfacu (v jeho destruktoru - volan z - // CPluginInterfaceAbstract::ReleasePluginDataInterface) + // for archive data only (for FS, the up-dir symbol is not added): + // modified the suggested content of the up-dir symbol (".." at the top of the panel); 'archivePath' + // is the path in the archive for which the symbol is intended; the proposed data of the symbol + // are entered in 'upDir': the name ".." (do not change), date&time of the archive, the rest is + // zeroed; the changes of the plugin are entered in 'upDir', especially 'upDir.PluginData', which + // will be used for the up-dir symbol when getting the content of the added columns; + // for 'upDir', ReleasePluginData will not be called, any necessary release can be performed + // either when calling GetFileDataForUpDir again or when releasing the entire interface (in its + // destructor - called from CPluginInterfaceAbstract::ReleasePluginDataInterface) virtual void WINAPI GetFileDataForUpDir(const char* archivePath, CFileData& upDir) = 0; - // jen pro data archivu (FS pouziva jen root cestu v CSalamanderDirectoryAbstract): - // pri pridavani souboru/adresare do CSalamanderDirectoryAbstract se muze stat, ze - // zadana cesta neexistuje a je ji tedy potreba vytvorit, jednotlive adresare teto - // cesty se tvori automaticky a tato metoda umoznuje pluginu pridat sva specificka - // data (pro sve sloupce) k temto vytvarenym adresarum; 'dirName' je plna cesta - // pridavaneho adresare v archivu; v 'dir' vstupuji navrhovana data: jmeno adresare - // (alokovane na heapu Salamandera), date&time prevzaty od pridavaneho souboru/adresare, - // zbytek nulovany; v 'dir' vystupuji zmeny pluginu, predevsim by mel zmenit - // 'dir.PluginData'; vraci TRUE pokud se pridani dat pluginu povedlo, jinak FALSE; - // pokud vrati TRUE, bude 'dir' uvolnen klasickou cestou (Salamanderovska cast + - // ReleasePluginData) a to bud az pri kompletnim uvolneni listingu nebo jeste behem - // jeho tvorby v pripade, ze bude ten samy adresar pridan pomoci - // CSalamanderDirectoryAbstract::AddDir (premazani automatickeho vytvoreni pozdejsim - // normalnim pridanim); pokud vrati FALSE, bude z 'dir' uvolnena jen Salamanderovska cast + // for archive data only (FS uses only root path in CSalamanderDirectoryAbstract): + // when adding a file or directory to CsalamanderDirectoryAbstract, it may happen that the specified + // path does not exist and it is therefore necessary to create it, the individual directories of this + // path are created automatically and this method allows the plugin to add its specific data (for its + // columns) to these created directories; 'dirName' is the full path of the added directory in the + // archive; the proposed data of the directory are entered in 'dir': the name of the directory + // (allocated on the heap of Salamander), date&time taken from the added file/directory, the rest + // is zeroed; the changes of the plugin are entered in 'dir', especially 'dir.PluginData'; returns + // TRUE if adding the plugin data was successful, otherwise FALSE; if it returns TRUE, 'dir' will + // be released in the standard way (Salamander part + ReleasePluginData) and either when releasing + // the entire listing or still during its creation in case the same directory is added using + // CSalamanderDirectoryAbstract::AddDir (overwriting the automatic creation by later normal addition); + // if it returns FALSE, only the Salamander part of 'dir' will be released virtual BOOL WINAPI GetFileDataForNewDir(const char* dirName, CFileData& dir) = 0; - // jen pro FS s vlastnimi ikonami (pitFromPlugin): - // vraci image-list s jednoduchymi ikonami, behem kresleni polozek v panelu se - // pomoci call-backu ziskava icon-index do tohoto image-listu; vola se vzdy po - // ziskani noveho listingu (po volani CPluginFSInterfaceAbstract::ListCurrentPath), - // takze je mozne image-list predelavat pro kazdy novy listing; - // 'iconSize' urcuje pozadovanou velikost ikon a jde o jednu z hodnot SALICONSIZE_xxx - // destrukci image-listu si plugin zajisti pri dalsim volani GetSimplePluginIcons - // nebo pri uvolneni celeho interfacu (v jeho destruktoru - volan z + // for FS with custom icons only (pitFromPlugin): + // returns image-list with simple icons, during drawing items in the panel, the icon-index + // into this image-list is obtained using a call-back; it is called only after getting a new + // listing (after calling CPluginFSInterfaceAbstract::ListCurrentPath), so it is possible to + // modify the image-list for each new listing; + // 'iconSize' specifies the required size of the icons and is one of the values SALICONSIZE_xxx + // the plugin will take care of destroying the image-list when calling GetSimplePluginIcons again + // or when releasing the entire interface (in its destructor - called from // CPluginInterfaceAbstract::ReleasePluginDataInterface) - // pokud image-list nelze vytvorit, vraci NULL a aktualni plugin-icons-type - // degraduje na pitSimple + // if the image-list cannot be created, it returns NULL and the current plugin-icons-type + // degrades to pitSimple virtual HIMAGELIST WINAPI GetSimplePluginIcons(int iconSize) = 0; - // jen pro FS s vlastnimi ikonami (pitFromPlugin): - // vraci TRUE, pokud pro dany soubor/adresar ('isDir' FALSE/TRUE) 'file' - // ma byt pouzita jednoducha ikona; vraci FALSE, pokud se ma pro ziskani ikony volat - // z threadu pro nacitani ikon metoda GetPluginIcon (nacteni ikony "na pozadi"); - // zaroven v teto metode muze byt predpocitan icon-index pro jednoduchou ikonu - // (u ikon ctenych "na pozadi" se az do okamziku nacteni pouzivaji take jednoduche - // ikony) a ulozen do CFileData (nejspise do CFileData::PluginData); - // omezeni: z CSalamanderGeneralAbstract je mozne pouzivat jen metody, ktere lze - // volat z libovolneho threadu (metody nezavisle na stavu panelu) + // for FS with custom icons only (pitFromPlugin): + // returns TRUE, if a simple icon for the file/directory ('isDir' FALSE/TRUE) 'file' should be + // used; returns FALSE, if the icon should be obtained by calling the method GetPluginIcon + // from the thread for loading icons (loading icons "in the background"); + // at the same time, the icon-index for a simple icon (for icons loaded "in the background", + // simple icons are used until the icon is loaded) can be pre-calculated in this method + // and saved in CFileData (most likely in CFileData::PluginData); + // limitation: only methods that can be called from any thread (methods independent of the + // panel state) can be used from CSalamanderGeneralAbstract virtual BOOL WINAPI HasSimplePluginIcon(CFileData& file, BOOL isDir) = 0; - // jen pro FS s vlastnimi ikonami (pitFromPlugin): - // vraci ikonu pro soubor nebo adresar 'file' nebo NULL pokud ikona nelze ziskat; vraci-li - // v 'destroyIcon' TRUE, vola se pro uvolneni vracene ikony Win32 API funkce DestroyIcon; - // 'iconSize' urcuje velikost pozadovane ikony a jde o jednu z hodnot SALICONSIZE_xxx - // omezeni: jelikoz se vola z threadu pro nacitani ikon (neni to hlavni thread), lze z - // CSalamanderGeneralAbstract pouzivat jen metody, ktere lze volat z libovolneho threadu + // for FS with custom icons only (pitFromPlugin): + // returns icon for the file/directory or NULL if the icon cannot be obtained; if + // 'destroyIcon' is TRUE, the Win32 API function DestroyIcon is called to release the icon; + // 'iconSize' specifies the required size of the icon and is one of the values SALICONSIZE_xxx + // limitation: since it is called from the thread for loading icons (it is not the main thread), + // you can use only methods from CSalamanderGeneralAbstract that can be called from any thread virtual HICON WINAPI GetPluginIcon(const CFileData* file, int iconSize, BOOL& destroyIcon) = 0; - // jen pro FS s vlastnimi ikonami (pitFromPlugin): - // porovna 'file1' (muze jit o soubor i adresar) a 'file2' (muze jit o soubor i adresar), - // nesmi pro zadne dve polozky listingu vratit, ze jsou shodne (zajistuje jednoznacne - // prirazeni vlastni ikony k souboru/adresari); pokud nehrozi duplicitni jmena v listingu - // cesty (obvykly pripad), lze jednoduse implementovat jako: + // for FS with custom icons only (pitFromPlugin): + // compares 'file1' (can be a file or directory) and 'file2' (can be a file or directory), + // must not return that two listing items are the same (ensures unambiguous assignment of + // a custom icon to a file/directory); if there is no risk of duplicate names in the listing + // paths (usual case), it can be easily implemented as: // {return strcmp(file1->Name, file2->Name);} - // vraci cislo mensi nez nula pokud 'file1' < 'file2', nulu pokud 'file1' == 'file2' a - // cislo vetsi nez nula pokud 'file1' > 'file2'; - // omezeni: jelikoz se vola i z threadu pro nacitani ikon (nejen z hlavniho threadu), lze - // z CSalamanderGeneralAbstract pouzivat jen metody, ktere lze volat z libovolneho threadu + // returns a number less than zero if 'file1' < 'file2', zero if 'file1' == 'file2' and + // a number greater than zero if 'file1' > 'file2'; + // limitation: since it is called from the thread for loading icons (it is not the main thread), + // you can use only methods from CSalamanderGeneralAbstract that can be called from any thread virtual int WINAPI CompareFilesFromFS(const CFileData* file1, const CFileData* file2) = 0; - // slouzi k nastaveni parametru pohledu, tato metoda je zavolana vzdy pred zobrazenim noveho - // obsahu panelu (pri zmene cesty) a pri zmene aktualniho pohledu (i rucni zmena sirky - // sloupce); 'leftPanel' je TRUE pokud jde o levy panel (FALSE pokud jde o pravy panel); - // 'view' je interface pro modifikaci pohledu (nastaveni rezimu, prace se - // sloupci); jde-li o data archivu, obsahuje 'archivePath' soucasnou cestu v archivu, - // pro data FS je 'archivePath' NULL; jde-li o data archivu, je 'upperDir' ukazatel na - // nadrazeny adresar (je-li soucasna cesta root archivu, je 'upperDir' NULL), pro data - // FS je vzdy NULL; - // POZOR: behem volani teto metody nesmi dojit k prekresleni panelu (muze se zde zmenit - // velikost ikon, atd.), takze zadne messageloopy (zadne dialogy, atd.)! - // omezeni: z CSalamanderGeneralAbstract je mozne pouzivat jen metody, ktere lze - // volat z libovolneho threadu (metody nezavisle na stavu panelu) + // used to set the view parameter, this method is called before displaying new content + // of the panel (when changing the path) and when changing the current view (also when + // manually changing the width of the column); 'leftPanel' is TRUE if it is the left panel + // (FALSE if it is the right panel); 'view' is an interface for modifying the view + // (setting the mode, working with columns); if it is archive data, 'archivePath' contains + // the current path in the archive, for FS data it is NULL; if it is archive data, 'upperDir' + // is a pointer to the parent directory (if the current path is the root of the archive, + // 'upperDir' is NULL), for FS data it is always NULL; + // CAUTION: during the call to this method, the panel must not be repainted (the size of + // the icons, etc. may change here), so no message loops (no dialogs, etc.)! + // limitation: only methods that can be called from any thread (methods independent of the + // panel state) can be used from CSalamanderGeneralAbstract virtual void WINAPI SetupView(BOOL leftPanel, CSalamanderViewAbstract* view, const char* archivePath, const CFileData* upperDir) = 0; - // nastaveni nove hodnoty "column->FixedWidth" - uzivatel pouzil kontextove menu - // na pluginem pridanem sloupci v header-line > "Automatic Column Width"; plugin - // by si mel ulozit novou hodnotu column->FixedWidth ulozenou v 'newFixedWidth' - // (je to vzdy negace column->FixedWidth), aby pri nasledujicich volanich SetupView() mohl - // sloupec pridat uz se spravne nastavenou FixedWidth; zaroven pokud se zapina pevna - // sirka sloupce, mel by si plugin nastavit soucasnou hodnotu "column->Width" (aby - // se timto zapnutim pevne sirky nezmenila sirka sloupce) - idealni je zavolat - // "ColumnWidthWasChanged(leftPanel, column, column->Width)"; 'column' identifikuje - // sloupec, ktery se ma zmenit; 'leftPanel' je TRUE pokud jde o sloupec z leveho - // panelu (FALSE pokud jde o sloupec z praveho panelu) + // setting new value "column->FixedWidth" - the user used the context menu on the column + // added by the plugin in the header-line > "Automatic Column Width"; the plugin should + // save the new value of column->FixedWidth stored in 'newFixedWidth' (it is always the + // negation of column->FixedWidth), so that when calling SetupView() again, the column + // can be added with the correct FixedWidth; at the same time, if the fixed width of the + // column is turned on, the plugin should set the current value of "column->Width" (so + // that the width of the column does not change when turning on this fixed width) - the + // ideal is to call "ColumnWidthWasChanged(leftPanel, column, column->Width)"; 'column' + // identifies the column to be changed; 'leftPanel' is TRUE if it is a column from the + // left panel (FALSE if it is a column from the right panel) virtual void WINAPI ColumnFixedWidthShouldChange(BOOL leftPanel, const CColumn* column, int newFixedWidth) = 0; - // nastaveni nove hodnoty "column->Width" - uzivatel mysi zmenil sirku pluginem pridaneho - // sloupce v header-line; plugin by si mel ulozit novou hodnotu column->Width (je ulozena - // i v 'newWidth'), aby pri nasledujicich volanich SetupView() mohl sloupec pridat uz se - // spravne nastavenou Width; 'column' identifikuje sloupec, ktery se zmenil; 'leftPanel' - // je TRUE pokud jde o sloupec z leveho panelu (FALSE pokud jde o sloupec z praveho panelu) + // setting new value "column->Width" - the user changed the width of the column added + // by the plugin in the header-line by the mouse; the plugin should save the new value + // of column->Width stored in 'newWidth', so that when calling SetupView() again, the + // column can be added with the correct Width; 'column' identifies the column that has + // changed; 'leftPanel' is TRUE if it is a column from the left panel (FALSE if it is + // a column from the right panel) virtual void WINAPI ColumnWidthWasChanged(BOOL leftPanel, const CColumn* column, int newWidth) = 0; - // ziska obsah Information Line pro soubor/adresar ('isDir' TRUE/FALSE) 'file' - // nebo oznacene soubory a adresare ('file' je NULL a pocty oznacenych souboru/adresaru - // jsou v 'selectedFiles'/'selectedDirs') v panelu ('panel' je jeden z PANEL_XXX); - // vola se i pri prazdnem listingu (tyka se jen FS, u archivu nemuze nastat, 'file' je NULL, - // 'selectedFiles' a 'selectedDirs' jsou 0); je-li 'displaySize' TRUE, je znama velikost - // vsech oznacenych adresaru (viz CFileData::SizeValid; pokud neni nic oznaceneho, je zde - // TRUE); v 'selectedSize' je soucet cisel CFileData::Size oznacenych souboru a adresaru - // (pokud neni nic oznaceneho, je zde nula); 'buffer' je buffer pro vraceny text (velikost - // 1000 bytu); 'hotTexts' je pole (velikost 100 DWORDu), ve kterem se vraci informace o poloze - // hot-textu, vzdy spodni WORD obsahuje pozici hot-textu v 'buffer', horni WORD obsahuje - // delku hot-textu; v 'hotTextsCount' je velikost pole 'hotTexts' (100) a vraci se v nem pocet - // zapsanych hot-textu v poli 'hotTexts'; vraci TRUE pokud je 'buffer' + 'hotTexts' + - // 'hotTextsCount' nastaveno, vraci FALSE pokud se ma Information Line plnit standardnim - // zpusobem (jako na disku) + // gets the content of Information Line for the file/directory ('isDir' TRUE/FALSE) 'file' + // or the selected files and directories ('file' is NULL and the number of selected files + // and directories are in 'selectedFiles'/'selectedDirs') in the panel ('panel' is one of + // PANEL_XXX); it is also called when the listing is empty (it only applies to FS, it cannot + // occur for archives, 'file' is NULL, 'selectedFiles' and 'selectedDirs' are 0); if 'displaySize' + // is TRUE, the size of all selected directories is known (see CFileData::SizeValid; if nothing + // is selected, it is TRUE); the sum of the numbers CFileData::Size of the selected files and + // directories is in 'selectedSize' (if nothing is selected, it is zero); 'buffer' is a buffer + // for the returned text (size 1000 bytes); 'hotTexts' is an array (size 100 DWORDs), in which + // information about the position of the hot-text is returned, the lower WORD always contains + // the position of the hot-text in 'buffer', the upper WORD contains the length of the hot-text; + // 'hotTextsCount' is the size of the 'hotTexts' array (100) and returns the number of written + // hot-texts in the 'hotTexts' array; returns TRUE if 'buffer' + 'hotTexts' + 'hotTextsCount' + // is set, returns FALSE if the Information Line is to be filled in the standard way (as on disk) virtual BOOL WINAPI GetInfoLineContent(int panel, const CFileData* file, BOOL isDir, int selectedFiles, int selectedDirs, BOOL displaySize, const CQuadWord& selectedSize, char* buffer, DWORD* hotTexts, int& hotTextsCount) = 0; - // jen pro archivy: uzivatel ulozil soubory/adresare z archivu na clipboard, ted zavira - // archiv v panelu: pokud metoda vrati TRUE, tento objekt zustane otevreny (optimalizace - // pripadneho Paste z clipboardu - archiv uz je vylistovany), pokud metoda vrati FALSE, - // tento objekt se uvolni (pripadny Paste z clipboardu zpusobi listovani archivu, pak - // teprve dojde k vybaleni vybranych souboru/adresaru); POZNAMKA: pokud je po zivotnost - // objektu otevreny soubor archivu, metoda by mela vracet FALSE, jinak bude po celou - // dobu "pobytu" dat na clipboardu soubor archivu otevreny (nepujde smazat, atd.) + // for archives only: user stored files/directories from the archive to the clipboard, now + // the archive in the panel is being closed: if the method returns TRUE, the archive will + // remain open (optimization of possible Paste from the clipboard - the archive is already + // listed), if the method returns FALSE, the object will be released (possible Paste from + // the clipboard will cause listing of the archive, then the selected files/directories + // will be unpacked); NOTE: if the file of the archive is open during the lifetime of the + // object, the method should return FALSE, otherwise the file of the archive will remain + // open for the entire "stay" of the data on the clipboard (cannot be deleted, etc.) virtual BOOL WINAPI CanBeCopiedToClipboard() = 0; - // jen pri zadani VALID_DATA_PL_SIZE do CSalamanderDirectoryAbstract::SetValidData(): - // vraci TRUE pokud je velikost souboru/adresare ('isDir' TRUE/FALSE) 'file' znama, - // jinak vraci FALSE; velikost vraci v 'size' + // only when entering VALID_DATA_PL_SIZE into CSalamanderDirectoryAbstract::SetValidData(): + // returns TRUE if the size of the file/directory ('isDir' TRUE/FALSE) 'file' is known, + // otherwise returns FALSE; the size is returned in 'size' virtual BOOL WINAPI GetByteSize(const CFileData* file, BOOL isDir, CQuadWord* size) = 0; - // jen pri zadani VALID_DATA_PL_DATE do CSalamanderDirectoryAbstract::SetValidData(): - // vraci TRUE pokud je datum souboru/adresare ('isDir' TRUE/FALSE) 'file' znamy, - // jinak vraci FALSE; datum vraci v "datumove" casti struktury 'date' ("casova" cast - // by mela zustat netknuta) + // only when entering VALID_DATA_PL_DATE into CSalamanderDirectoryAbstract::SetValidData(): + // returns TRUE if the date of the file/directory ('isDir' TRUE/FALSE) 'file' is known, + // otherwise returns FALSE; the date is returned in 'date' part of the 'date' structure + // ("time" part of the structure should remain untouched) virtual BOOL WINAPI GetLastWriteDate(const CFileData* file, BOOL isDir, SYSTEMTIME* date) = 0; - // jen pri zadani VALID_DATA_PL_TIME do CSalamanderDirectoryAbstract::SetValidData(): - // vraci TRUE pokud je cas souboru/adresare ('isDir' TRUE/FALSE) 'file' znamy, - // jinak vraci FALSE; cas vraci v "casove" casti struktury 'time' ("datumova" cast - // by mela zustat netknuta) + // only when entering VALID_DATA_PL_TIME into CSalamanderDirectoryAbstract::SetValidData(): + // returns TRUE if the time of the file/directory ('isDir' TRUE/FALSE) 'file' is known, + // otherwise returns FALSE; the time is returned in 'time' part of the 'time' structure + // ("date" part of the structure should remain untouched) virtual BOOL WINAPI GetLastWriteTime(const CFileData* file, BOOL isDir, SYSTEMTIME* time) = 0; }; @@ -827,57 +816,57 @@ class CPluginDataInterfaceAbstract // **************************************************************************** // CSalamanderForOperationsAbstract // -// sada metod ze Salamandera pro podporu provadeni operaci, platnost interfacu je -// omezena na metodu, ktere je interface predan jako parametr; tedy lze volat pouze -// z tohoto threadu a v teto metode (objekt je na stacku, takze po navratu zanika) +// set of Salamander methods for supporting the execution of operations, the validity of the interface is +// limited to the method that is passed as a parameter; therefore, it can only be called from this thread +// and in this method (the object is on the stack, so it disappears after returning) class CSalamanderForOperationsAbstract { public: - // PROGRESS DIALOG: dialog obsahuje jeden/dva ('twoProgressBars' FALSE/TRUE) progress-metry - // otevre progress-dialog s titulkem 'title'; 'parent' je parent okno progress-dialogu (je-li - // NULL, pouzije se hlavni okno); pokud obsahuje jen jeden progress-metr, muze byt popsan - // jako "File" ('fileProgress' je TRUE) nebo "Total" ('fileProgress' je FALSE) + // PROGRESS DIALOG: the dialog contains one/two ('twoProgressBars' FALSE/TRUE) progress meters + // opens a progress dialog with the title 'title'; 'parent' is the parent window of the progress + // dialog (if NULL, the main window is used); if it contains only one progress meter, it can be + // described as "File" ('fileProgress' is TRUE) or "Total" ('fileProgress' is FALSE) // - // dialog nebezi ve vlastnim threadu; pro jeho fungovani (tlacitko Cancel + vnitrni timer) - // je treba obcas vyprazdni message queue; to zajistuji metody ProgressDialogAddText, - // ProgressAddSize a ProgressSetSize + // the dialog does not run in its own thread; for its functioning (Cancel button + internal timer) + // it is necessary to occasionally empty the message queue; this is ensured by the methods + // ProgressDialogAddText, ProgressAddSize and ProgressSetSize // - // protoze real-time zobrazovani textu a zmen v progress bare silne zdrzuje, maji - // metody ProgressDialogAddText, ProgressAddSize a ProgressSetSize parametr - // 'delayedPaint'; ten by mel byt TRUE pro vsechny rychle se menici texty a hodnoty; - // metody si pak ulozi texty a zobrazi je az po doruceni vnitrniho timeru dialogu; - // 'delayedPaint' nastavime na FALSE pro inicializacni/koncove texty typu "preparing data..." - // nebo "canceling operation...", po jejiz zobrazeni nedame dialogu prilezitost k distribuci - // zprav (timeru); pokud je u takove operace pravdepodobne, ze bude trvat dlouho, meli - // bychom behem teto doby dialog "obcerstvovat" volanim ProgressAddSize(CQuadWord(0, 0), TRUE) - // a podle jeji navratove hodnoty akci pripadne predcasne ukoncit + // because real-time display of text and changes in progress bars is very slow, the methods + // ProgressDialogAddText, ProgressAddSize and ProgressSetSize have the parameter 'delayedPaint'; + // it should be TRUE for all quickly changing texts and values; the methods then save the texts + // and display them only after the internal timer of the dialog is delivered; + // 'delayedPaint' should be set to FALSE for initialization/ending texts such as "preparing data..." + // or "canceling operation..."; after displaying them, we do not give the dialog a chance to + // distribute messages (timers); if such an operation is likely to take a long time, we should + // "refresh" the dialog during this time by calling ProgressAddSize(CQuadWord(0, 0), TRUE) and + // depending on its return value, possibly terminate the action prematurely virtual void WINAPI OpenProgressDialog(const char* title, BOOL twoProgressBars, HWND parent, BOOL fileProgress) = 0; - // vypise text 'txt' (i nekolik radku - provadi se rozpad na radky) do progress-dialogu + // prints the text 'txt' (even several lines - the text is broken down into lines) to the progress dialog virtual void WINAPI ProgressDialogAddText(const char* txt, BOOL delayedPaint) = 0; - // neni-li 'totalSize1' CQuadWord(-1, -1), nastavi 'totalSize1' jako 100 procent prvniho progress-metru, - // neni-li 'totalSize2' CQuadWord(-1, -1), nastavi 'totalSize2' jako 100 procent druheho progress-metru - // (pro progress-dialog s jednim progress-metrem je povinne 'totalSize2' CQuadWord(-1, -1)) + // if 'totalSize1' is not CQuadWord(-1, -1), sets 'totalSize1' as 100 percent of the first progress meter, + // if 'totalSize2' is not CQuadWord(-1, -1), sets 'totalSize2' as 100 percent of the second progress meter + // (for a progress dialog with one progress meter, 'totalSize2' CQuadWord(-1, -1) is mandatory) virtual void WINAPI ProgressSetTotalSize(const CQuadWord& totalSize1, const CQuadWord& totalSize2) = 0; - // neni-li 'size1' CQuadWord(-1, -1), nastavi velikost 'size1' (size1/total1*100 procent) na prvnim progress-metru, - // neni-li 'size2' CQuadWord(-1, -1), nastavi velikost 'size2' (size2/total2*100 procent) na druhem progress-metru - // (pro progress-dialog s jednim progress-metrem je povinne 'size2' CQuadWord(-1, -1)), vraci informaci jestli ma - // akce pokracovat (FALSE = konec) + // if 'size1' is not CQuadWord(-1, -1), sets the size 'size1' (size1/total1*100 percent) on the first progress meter, + // if 'size2' is not CQuadWord(-1, -1), sets the size 'size2' (size2/total2*100 percent) on the second progress meter + // (for a progress dialog with one progress meter, 'size2' CQuadWord(-1, -1) is mandatory), returns whether the action + // should continue (FALSE = end) virtual BOOL WINAPI ProgressSetSize(const CQuadWord& size1, const CQuadWord& size2, BOOL delayedPaint) = 0; - // prida (pripadne k oboum progress-metrum) velikost 'size' (size/total*100 procent progressu), - // vraci informaci jestli ma akce pokracovat (FALSE = konec) + // adds (possibly to both progress meters) the size 'size' (size/total*100 percent of the progress) + // returns an information whether the action should continue (FALSE = end) virtual BOOL WINAPI ProgressAddSize(int size, BOOL delayedPaint) = 0; - // enabluje/disabluje tlacitko Cancel + // enables/disables the Cancel button virtual void WINAPI ProgressEnableCancel(BOOL enable) = 0; - // vraci HWND dialogu progressu (hodi se pri vypisu chyb a dotazu pri otevrenem progress-dialogu) + // returns HWND of the progress dialog (useful when displaying errors and queries with an open progress dialog) virtual HWND WINAPI ProgressGetHWND() = 0; - // zavre progress-dialog + // closes the progress dialog virtual void WINAPI CloseProgressDialog() = 0; - // presune vsechny soubory ze 'source' adresare do 'target' adresare, - // navic premapovava predpony zobrazovanych jmen ('remapNameFrom' -> 'remapNameTo') - // vraci uspech operace + // moves all files from 'source' to 'target' directory, + // moreover, it remaps the prefixes of the displayed names ('remapNameFrom' -> 'remapNameTo') + // returns success of the operation virtual BOOL WINAPI MoveFiles(const char* source, const char* target, const char* remapNameFrom, const char* remapNameTo) = 0; }; diff --git a/src/plugins/shared/spl_gen.h b/src/plugins/shared/spl_gen.h index 28c8c00f6..a186612d3 100644 --- a/src/plugins/shared/spl_gen.h +++ b/src/plugins/shared/spl_gen.h @@ -12,7 +12,7 @@ #pragma once #ifdef _MSC_VER -#pragma pack(push, enter_include_spl_gen) // aby byly struktury nezavisle na nastavenem zarovnavani +#pragma pack(push, enter_include_spl_gen) // so that the structures are independent of the alignment setting #pragma pack(4) #endif // _MSC_VER #ifdef __BORLANDC__ @@ -26,9 +26,9 @@ class CPluginDataInterfaceAbstract; // **************************************************************************** // CSalamanderGeneralAbstract // -// obecne pouzitelne metody Salamandera (pro vsechny typy pluginu) +// generally usable methods of Salamander (for all types of plugins) -// typy message-boxu +// message-box types #define MSGBOX_INFO 0 #define MSGBOX_ERROR 1 #define MSGBOX_EX_ERROR 2 @@ -37,7 +37,7 @@ class CPluginDataInterfaceAbstract; #define MSGBOX_WARNING 5 #define MSGBOX_EX_WARNING 6 -// konstanty pro CSalamanderGeneralAbstract::SalMessageBoxEx +// CSlamanderGeneralAbstract::SalMessageBoxEx constants #define MSGBOXEX_OK 0x00000000 // MB_OK #define MSGBOXEX_OKCANCEL 0x00000001 // MB_OKCANCEL #define MSGBOXEX_ABORTRETRYIGNORE 0x00000002 // MB_ABORTRETRYIGNORE @@ -63,12 +63,13 @@ class CPluginDataInterfaceAbstract; #define MSGBOXEX_SETFOREGROUND 0x00010000 // MB_SETFOREGROUND (bit mask) // altap specific -#define MSGBOXEX_SILENT 0x10000000 // messagebox nevyda pri otevreni zadny zvuk (bit mask) -// v pripade MB_YESNO messageboxu povoli Escape (generuje IDNO); v MB_ABORTRETRYIGNORE messageboxu -// povoli Escape (generuje IDCANCEL) (bit mask) +#define MSGBOXEX_SILENT 0x10000000 // messsagebox won't play any sound when opened (bit mask) +// in case of MB_YESNO messagebox, it allows Escape (generates IDNO); in case of MB_ABORTRETRYIGNORE +// messagebox, it allows Escape (generates IDCANCEL) (bit mask) #define MSGBOXEX_ESCAPEENABLED 0x20000000 -#define MSGBOXEX_HINT 0x40000000 // pokud se pouziva CheckBoxText, bude v nem vyhledan oddelovac \t a zobrazen jako hint -// Vista: defaultni tlacitko bude mit stav "pozaduje elevaci" (zobrazi se elevated icon) +#define MSGBOXEX_HINT 0x40000000 // if the CheckBoxText is used, it will be searched for +// the \t separator and displayed as a hint +// Vista: the default button will have "requires elevation" state (elevated icon will be displayed) #define MSGBOXEX_SHIELDONDEFBTN 0x80000000 #define MSGBOXEX_TYPEMASK 0x0000000F // MB_TYPEMASK @@ -78,9 +79,9 @@ class CPluginDataInterfaceAbstract; #define MSGBOXEX_MISCMASK 0x0000C000 // MB_MISCMASK #define MSGBOXEX_EXMASK 0xF0000000 -// navratove hodnoty message boxu -#define DIALOG_FAIL 0x00000000 // dialog se nepodarilo otevrit -// jednotliva tlacitka +// message box return values +#define DIALOG_FAIL 0x00000000 // dialog could not be opened +// individual buttons #define DIALOG_OK 0x00000001 // IDOK #define DIALOG_CANCEL 0x00000002 // IDCANCEL #define DIALOG_ABORT 0x00000003 // IDABORT @@ -242,19 +243,19 @@ URLText */ -// identifikace panelu -#define PANEL_SOURCE 1 // zdrojovy panel (aktivni panel) -#define PANEL_TARGET 2 // cilovy panel (neaktivni panel) -#define PANEL_LEFT 3 // levy panel -#define PANEL_RIGHT 4 // pravy panel +// panel identification +#define PANEL_SOURCE 1 // source panel (active panel) +#define PANEL_TARGET 2 // target panel (inactive panel) +#define PANEL_LEFT 3 // left panel +#define PANEL_RIGHT 4 // right panel -// typy cest -#define PATH_TYPE_WINDOWS 1 // windowsova cesta ("c:\path" nebo UNC cesta) -#define PATH_TYPE_ARCHIVE 2 // cesta do archivu (archiv lezi na windowsove ceste) -#define PATH_TYPE_FS 3 // cesta na pluginovy file-system +// types of paths +#define PATH_TYPE_WINDOWS 1 // windows path ("c:\path" or UNC path) +#define PATH_TYPE_ARCHIVE 2 // a path to archive (archive is on windows path) +#define PATH_TYPE_FS 3 // a path to plugin file-system -// Z nasledujici skupiny flagu lze vybrat pouze jeden. -// Definuji sadu zobrazenych tlacitek v ruznych chybovych hlasenich. +// It is possible to choose one of the following flags +// They define a set of buttons displayed in various error messages. #define BUTTONS_OK 0x00000000 // OK #define BUTTONS_RETRYCANCEL 0x00000001 // Retry / Cancel #define BUTTONS_SKIPCANCEL 0x00000002 // Skip / Skip all / Cancel @@ -262,9 +263,9 @@ URLText #define BUTTONS_YESALLSKIPCANCEL 0x00000004 // Yes / All / Skip / Skip all / Cancel #define BUTTONS_YESNOCANCEL 0x00000005 // Yes / No / Cancel #define BUTTONS_YESALLCANCEL 0x00000006 // Yes / All / Cancel -#define BUTTONS_MASK 0x000000FF // interni maska, nepouzivat -// detekci zda kombinace ma tlacitko SKIP nebo YES nechavam zde ve forme inline, aby -// v pripade zavadeni novych kombinaci byla dobre na ocich a nezapomeli jsme ji doplnit +#define BUTTONS_MASK 0x000000FF // internal mask, do not use +// The detection if the combination contains SKIP or YES button is kept here in the inline form, +// so that in case of adding new combinations it is easy to see and not to forget to add it here inline BOOL ButtonsContainsSkip(DWORD btn) { return (btn & BUTTONS_MASK) == BUTTONS_SKIPCANCEL || @@ -278,148 +279,153 @@ inline BOOL ButtonsContainsYes(DWORD btn) (btn & BUTTONS_MASK) == BUTTONS_YESALLCANCEL; } -// chybove konstanty pro CSalamanderGeneralAbstract::SalGetFullName -#define GFN_SERVERNAMEMISSING 1 // v UNC ceste chybi server name -#define GFN_SHARENAMEMISSING 2 // v UNC ceste chybi share name -#define GFN_TOOLONGPATH 3 // operaci by vznikla prilis dlouha cesta -#define GFN_INVALIDDRIVE 4 // u normalni cesty (c:\) neni pismenko A-Z (ani a-z) -#define GFN_INCOMLETEFILENAME 5 // relativni cesta bez zadaneho 'curDir' -> neresitelne -#define GFN_EMPTYNAMENOTALLOWED 6 // prazdny retezec 'name' -#define GFN_PATHISINVALID 7 // nelze vyloucit "..", napr. "c:\.." +// error constants for CSalamanderGeneralAbstract::SalCheckPath +#define GFN_SERVERNAMEMISSING 1 // server name is missing in UNC path +#define GFN_SHARENAMEMISSING 2 // share name is missing in UNC path +#define GFN_TOOLONGPATH 3 // by using this operation, too long path would be created +#define GFN_INVALIDDRIVE 4 // there's no A-Z (or a-z) letter in the ordinary path (c:\) +#define GFN_INCOMLETEFILENAME 5 // a relative path without specified 'curDir' -> not solvable +#define GFN_EMPTYNAMENOTALLOWED 6 // empty 'name' string +#define GFN_PATHISINVALID 7 // ".." can't be excluded, e.g. "c:\.." -// chybovy kod pro stav, kdy uzivatel prerusi CSalamanderGeneralAbstract::SalCheckPath klavesou ESC +// error state for the situation when user cancels CSalamanderGeneralAbstract::SalCheckPath with ESC key #define ERROR_USER_TERMINATED -100 -#define PATH_MAX_PATH 248 // limit pro max. delku cesty (plne jmeno adresare), pozor: v limitu uz je zapocteny null-terminator (max. delka retezce je 247 znaku) +#define PATH_MAX_PATH 248 // the limit for maximal path length (full path name), beware: the limit includes null-terminator (max. length of string is 247 characters) -// chybove konstanty pro CSalamanderGeneralAbstract::SalParsePath: -// vstupem byla prazdna cesta a 'curPath' bylo NULL (prazdna cesta se nahrazuje aktualni cestou, -// ale ta tu neni znama) +// error constants for CSalamanderGeneralAbstract::SalParsePath +// the input was empty path and 'curPath' was NULL (empty path is replaced by current path, +// but current path is not known here) #define SPP_EMPTYPATHNOTALLOWED 1 -// windowsova cesta (normal + UNC) neexistuje, neni pristupna nebo uzivatel prerusil test -// na pristupnost cesty (soucasti je i pokus o obnoveni sit. spojeni) +// windows path (normal + UNC) does not exist, is not accessible or user cancelled the test +// for path accessibility (an attempt to restore network connection is included) #define SPP_WINDOWSPATHERROR 2 -// windowsova cesta zacina jmenem souboru, ktery ale neni archiv (jinak by slo o cestu do archivu) +// windows path begins with file name, but it is not an archive (otherwise it would be a path to an archive) #define SPP_NOTARCHIVEFILE 3 -// FS cesta - jmeno pluginoveho FS (fs-name - pred ':' v ceste) neni zname (zadnemu pluginu -// nebylo toto jmeno zaregistrovano) +// FS path - a name of plugin FS (fs-name - before ':' in path) is not known (the name was not +// registered to any plugin) #define SPP_NOTPLUGINFS 4 -// jde o relativni cestu, ale aktualni cesta neni znama nebo jde o FS (tam nelze poznat root -// a vubec nezname strukturu fs-user-part cesty, takze nelze provest prevod na absolutni cestu) -// je-li aktualni cesta FS ('curPathIsDiskOrArchive' je FALSE), nedojde v tomto pripade ke hlaseni -// chyby uzivateli (predpoklada se dalsi zpracovani na strane FS, ktere metodu SalParsePath volalo) +// it's a relative path, but current path is not known or it's a FS (root can't be recognized +// there and we don't know the structure of fs-user-part of the path, so it's not possible to +// convert it to absolute path) +// if current path is FS ('curPathIsDiskOrArchive' is FALSE), the error is not reported to user +// (it's supposed that the FS which called SalParsePath method will handle it #define SPP_INCOMLETEPATH 5 -// konstanty vnitrnich barev Salamandera -#define SALCOL_FOCUS_ACTIVE_NORMAL 0 // barvy pera pro ramecek kolem polozky +// Salamander internal colors constants +#define SALCOL_FOCUS_ACTIVE_NORMAL 0 // pen colors for frame around item #define SALCOL_FOCUS_ACTIVE_SELECTED 1 #define SALCOL_FOCUS_FG_INACTIVE_NORMAL 2 #define SALCOL_FOCUS_FG_INACTIVE_SELECTED 3 #define SALCOL_FOCUS_BK_INACTIVE_NORMAL 4 #define SALCOL_FOCUS_BK_INACTIVE_SELECTED 5 -#define SALCOL_ITEM_FG_NORMAL 6 // barvy textu polozek v panelu +#define SALCOL_ITEM_FG_NORMAL 6 // item text colors in panel #define SALCOL_ITEM_FG_SELECTED 7 #define SALCOL_ITEM_FG_FOCUSED 8 #define SALCOL_ITEM_FG_FOCSEL 9 #define SALCOL_ITEM_FG_HIGHLIGHT 10 -#define SALCOL_ITEM_BK_NORMAL 11 // barvy pozadi polozek v panelu +#define SALCOL_ITEM_BK_NORMAL 11 // item background colors in panel #define SALCOL_ITEM_BK_SELECTED 12 #define SALCOL_ITEM_BK_FOCUSED 13 #define SALCOL_ITEM_BK_FOCSEL 14 #define SALCOL_ITEM_BK_HIGHLIGHT 15 -#define SALCOL_ICON_BLEND_SELECTED 16 // barvy pro blend ikonek +#define SALCOL_ICON_BLEND_SELECTED 16 // icon blend colors #define SALCOL_ICON_BLEND_FOCUSED 17 #define SALCOL_ICON_BLEND_FOCSEL 18 -#define SALCOL_PROGRESS_FG_NORMAL 19 // barvy progress bary +#define SALCOL_PROGRESS_FG_NORMAL 19 // progress bar colors #define SALCOL_PROGRESS_FG_SELECTED 20 #define SALCOL_PROGRESS_BK_NORMAL 21 #define SALCOL_PROGRESS_BK_SELECTED 22 -#define SALCOL_HOT_PANEL 23 // barva hot polozky v panelu -#define SALCOL_HOT_ACTIVE 24 // v aktivnim window caption -#define SALCOL_HOT_INACTIVE 25 // v neaktivni caption, statusbar,... -#define SALCOL_ACTIVE_CAPTION_FG 26 // barva textu v aktivnim titulku panelu -#define SALCOL_ACTIVE_CAPTION_BK 27 // barva pozadi v aktivnim titulku panelu -#define SALCOL_INACTIVE_CAPTION_FG 28 // barva textu v neaktivnim titulku panelu -#define SALCOL_INACTIVE_CAPTION_BK 29 // barva pozadi v neaktivnim titulku panelu -#define SALCOL_VIEWER_FG_NORMAL 30 // barva textu v internim text/hex vieweru -#define SALCOL_VIEWER_BK_NORMAL 31 // barva pozadi v internim text/hex vieweru -#define SALCOL_VIEWER_FG_SELECTED 32 // barva oznaceneho textu v internim text/hex vieweru -#define SALCOL_VIEWER_BK_SELECTED 33 // barva oznaceneho pozadi v internim text/hex vieweru -#define SALCOL_THUMBNAIL_NORMAL 34 // barvy pera pro ramecek kolem thumbnail +#define SALCOL_HOT_PANEL 23 // hot item color in panel +#define SALCOL_HOT_ACTIVE 24 // active window caption +#define SALCOL_HOT_INACTIVE 25 // inactive window caption, statusbar,... +#define SALCOL_ACTIVE_CAPTION_FG 26 // text color in active window caption +#define SALCOL_ACTIVE_CAPTION_BK 27 // background color in active window caption +#define SALCOL_INACTIVE_CAPTION_FG 28 // text color in inactive window caption +#define SALCOL_INACTIVE_CAPTION_BK 29 // background color in inactive window caption +#define SALCOL_VIEWER_FG_NORMAL 30 // text color in internal text/hex viewer +#define SALCOL_VIEWER_BK_NORMAL 31 // background color in internal text/hex viewer +#define SALCOL_VIEWER_FG_SELECTED 32 // text color of selected text in internal text/hex viewer +#define SALCOL_VIEWER_BK_SELECTED 33 // background color of selected text in internal text/hex viewer +#define SALCOL_THUMBNAIL_NORMAL 34 // pen color for frame around thumbnail #define SALCOL_THUMBNAIL_SELECTED 35 #define SALCOL_THUMBNAIL_FOCUSED 36 #define SALCOL_THUMBNAIL_FOCSEL 37 -// konstanty duvodu, proc metody CSalamanderGeneralAbstract::ChangePanelPathToXXX vratily neuspech: -#define CHPPFR_SUCCESS 0 // v panelu je nova cesta, uspech (navratova hodnota je TRUE) -// novou cestu (nebo jmeno archivu) nelze prevest z relativni na absolutni nebo -// nova cesta (nebo jmeno archivu) neni pristupna nebo -// cestu na FS nelze otevrit (neni plugin, odmita svuj load, odmita otevreni FS, fatalni chyba ChangePath) +// the constats of reasons, why CSalamanderGeneralAbstract::ChangePanelPathToXXX methods returned false: +#define CHPPFR_SUCCESS 0 // there is a new path in panel (return value is TRUE) +// new path (or archive name) can't be converted from relative to absolute or +// new path (or archive name) is not accessible or +// the path to FS can't be opened (there's no plugin, plugin refused to load, plugin refused to open FS, fatal error in ChangePath) #define CHPPFR_INVALIDPATH 1 -#define CHPPFR_INVALIDARCHIVE 2 // soubor neni archiv nebo se jako archiv neda vylistovat -#define CHPPFR_CANNOTCLOSEPATH 4 // aktualni cestu nelze uzavrit -// v panelu je zkracena nova cesta, -// upresneni pro FS: v panelu je bud zkracena nova cesta nebo puvodni cesta nebo zkracena -// puvodni cesta - puvodni cesta se do panelu zkousi vratit jen pokud se nova cesta otevirala -// v aktualnim FS (metoda IsOurPath pro ni vratila TRUE) a pokud nova cesta neni pristupna -// (ani zadna jeji podcesta) +#define CHPPFR_INVALIDARCHIVE 2 // the file is not an archive or it can't be listed as an archive +#define CHPPFR_CANNOTCLOSEPATH 4 // the current path can't be closed +// there's a new trimmed path in panel, +// to make this clear for FS: there's either a new trimmed path in panel or the original path or +// a trimmed original path - the original path tries to return to panel only if the new path +// was opened in current FS (method IsOurPath returned TRUE) and if the new path is not accessible +// (nor any of its subpaths) +// #define CHPPFR_SHORTERPATH 5 -// v panelu je zkracena nova cesta; duvodem zkraceni bylo to, ze pozadovana cesta byla jmeno -// souboru - v panelu je cesta k souboru a soubor bude vyfokusen +// there is a new trimmed path in panel; the reason for trimming is that the requested path +// was a file name - there is a path to a file in panel, the file will be focused #define CHPPFR_FILENAMEFOCUSED 6 +// types for CSalamanderGeneralAbstract::ValidateVarString() and CSalamanderGeneralAbstract::ExpandVarString() // typy pro CSalamanderGeneralAbstract::ValidateVarString() a CSalamanderGeneralAbstract::ExpandVarString() typedef const char*(WINAPI* FSalamanderVarStrGetValue)(HWND msgParent, void* param); struct CSalamanderVarStrEntry { - const char* Name; // jmeno promenne v retezci (napr. u retezce "$(name)" je to "name") - FSalamanderVarStrGetValue Execute; // funkce, ktera vraci text reprezentujici promennou + const char* Name; // variable name in string (e.g. in string "$(name)" it is "name") + FSalamanderVarStrGetValue Execute; // a function which returns text which represents the variable }; class CSalamanderRegistryAbstract; -// typ call-backu pouzivany pri load/save konfigurace pomoci -// CSalamanderGeneral::CallLoadOrSaveConfiguration; 'regKey' je NULL pokud jde o load -// defaultni konfigurace (save se pri 'regKey' == NULL nevola); 'registry' je objekt pro -// praci s registry; 'param' je uzivatelsky parametr funkce (viz +// callback type used during loading/saving configuration by +// CSalamanderGeneral::CallLoadOrSaveConfiguration; 'regKey' is NULL if it is load +// of default configuration (save is not called if 'regKey' == NULL); 'registry' is +// object for registry access; 'param' is user parameter of the function (see // CSalamanderGeneral::CallLoadOrSaveConfiguration) +// typedef void(WINAPI* FSalLoadOrSaveConfiguration)(BOOL load, HKEY regKey, CSalamanderRegistryAbstract* registry, void* param); -// zaklad struktury pro CSalamanderGeneralAbstract::ViewFileInPluginViewer (kazdy plugin -// viewer muze mit tuto strukturu rozsirenou o sve parametry - struktura se predava do -// CPluginInterfaceForViewerAbstract::ViewFile - parametry muzou byt napr. titulek okna, -// mod vieweru, offset od zacatku souboru, pozice oznaceni, atp.); POZOR !!! na pakovani -// struktur (pozadovane je 4 byty - viz "#pragma pack(4)") +// structure base for CSalamanderGeneralAbstract::ViewFileInPluginViewer (each plugin +// viewer can have this structure extended by its own parameters - the structure is +// passed to CPluginInterfaceForViewerAbstract::ViewFile - the parameters can be e.g. +// window title, viewer mode, offset from the beginning of the file, position of +// selection, etc.); BEWARE OF packing of structure (4 bytes are required - see "#pragma pack(4)") struct CSalamanderPluginViewerData { - // kolik bytu od zacatku struktury je platnych (pro rozliseni verzi struktury) + // how many bytes from the beginning of the structure are valid (to distinguish the versions of structure) int Size; - // jmeno souboru, ktery se ma otevrit ve viewru (nepouzivat v metode - // CPluginInterfaceForViewerAbstract::ViewFile - jmeno souboru je dano parametrem 'name') + // name of the file which should be opened in viewer (do not use in method + // CPluginInterfaceForViewerAbstract::ViewFile - the file name is given by + // parameter 'name') const char* FileName; }; -// rozsireni struktury CSalamanderPluginViewerData pro interni text/hex viewer +// extension of structure CSalamanderPluginViewerData for internal text/hex viewer struct CSalamanderPluginInternalViewerData : public CSalamanderPluginViewerData { - int Mode; // 0 - textovy mod, 1 - hexa mod - const char* Caption; // NULL -> obsahuje caption okna FileName, jinak Caption - BOOL WholeCaption; // ma vyznam pokud je Caption != NULL. TRUE -> v titulku - // vieweru bude zobrazen pouze retezec Caption; FALSE -> za - // Caption se pripoji standardni " - Viewer". + int Mode; // 0 - text mode, 1 - hex mode + const char* Caption; // NULL -> contains caption of window FileName, otherwise Caption + BOOL WholeCaption; // makes sense if Caption != NULL. TRUE -> only Caption will be + // displayed in the caption of viewer window; FALSE -> standard + // " - Viewer" will be appended to Caption }; -// konstanty typu parametru konfigurace Salamandera (viz CSalamanderGeneralAbstract::GetConfigParameter) +// Salamander configuration parameters types constants (see CSalamanderGeneralAbstract::GetConfigParameter) #define SALCFGTYPE_NOTFOUND 0 // parameter not found #define SALCFGTYPE_BOOL 1 // TRUE/FALSE #define SALCFGTYPE_INT 2 // 32-bit integer #define SALCFGTYPE_STRING 3 // null-terminated multibyte string #define SALCFGTYPE_LOGFONT 4 // Win32 LOGFONT structure -// konstanty parametru konfigurace Salamandera (viz CSalamanderGeneralAbstract::GetConfigParameter); -// v komentari je uveden typ parametru (BOOL, INT, STRING), za STRING je v zavorce potrebna -// velikost bufferu pro retezec +// Salamander configuration parameters constants (see CSalamanderGeneralAbstract::GetConfigParameter) +// the comment contains type of parameter (BOOL, INT, STRING), for STRING, the size of buffer +// for string is required in brackets // // general parameters #define SALCFG_SELOPINCLUDEDIRS 1 // BOOL, select/deselect operations (num *, num +, num -) work also with directories @@ -487,44 +493,47 @@ struct CSalamanderPluginInternalViewerData : public CSalamanderPluginViewerData #define SALCFG_ARCSUBDIRBYARCFORUNPACK 142 // BOOL, should it unpack to subdirectory named by archive? #define SALCFG_ARCUSESIMPLEICONS 143 // BOOL, should it use simple icons in archives? +// callback type used in the method CSalamanderGeneral::SalSplitGeneralPath // typ callbacku pouzivany v metode CSalamanderGeneral::SalSplitGeneralPath typedef BOOL(WINAPI* SGP_IsTheSamePathF)(const char* path1, const char* path2); -// typ callbacku pouzivany v metode CSalamanderGeneralAbstract::CallPluginOperationFromDisk -// 'sourcePath' je zdrojova cesta na disku (ostatni cesty jsou od ni vztazeny relativne); -// oznacene soubory/adresare jsou zadany enumeracni funkci 'next' jejimz parametrem je -// 'nextParam'; 'param' je parametr predavany do CallPluginOperationFromDisk jako 'param' +// callback type used in the method CSalamanderGeneralAbstract::CallPluginOperationFromDisk +// 'sourcePath' is source path on disk (other paths are relative to it); +// selected files/directories are passed to enumeration function 'next' with parameter +// 'nextParam'; 'param' is parameter passed to CallPluginOperationFromDisk as 'param' typedef void(WINAPI* SalPluginOperationFromDisk)(const char* sourcePath, SalEnumSelection2 next, void* nextParam, void* param); -// flagy pro textove vyhledavaci algoritmy (CSalamanderBMSearchData a CSalamanderREGEXPSearchData); -// flagy se daji logicky scitat -#define SASF_CASESENSITIVE 0x01 // velikost pismen je dulezita (pokud neni nastaven, hleda se bez ohledu na vel. pismen) -#define SASF_FORWARD 0x02 // hledani smerem dopredu (pokud neni nastaven, hleda se smerem zpet) +// flags for text searching algorithms (CSalamanderBMSearchData and CSalamanderREGEXPSearchData); +// flags can be logically added +#define SASF_CASESENSITIVE 0x01 // size of letters is important (if not set, searching is case insensitive) +#define SASF_FORWARD 0x02 // searching forward (if not set, searching backward) -// ikony pro GetSalamanderIcon +// icons for GetSalamanderIcon #define SALICON_EXECUTABLE 1 // exe/bat/pif/com #define SALICON_DIRECTORY 2 // dir -#define SALICON_NONASSOCIATED 3 // neasociovany soubor -#define SALICON_ASSOCIATED 4 // asociovany soubor +#define SALICON_NONASSOCIATED 3 // non-associated file +#define SALICON_ASSOCIATED 4 // associated file #define SALICON_UPDIR 5 // up-dir ".." -#define SALICON_ARCHIVE 6 // archiv +#define SALICON_ARCHIVE 6 // archive -// velikosti ikon pro GetSalamanderIcon +// sizes of icons for GetSalamanderIcon #define SALICONSIZE_16 1 // 16x16 #define SALICONSIZE_32 2 // 32x32 #define SALICONSIZE_48 3 // 48x48 -// interface objektu Boyer-Moorova algoritmu pro vyhledavani v textu -// POZOR: kazdy alokovany objekt je mozne pouzivat jen v ramci jednoho threadu -// (nemusi jit o hlavni thread, nemusi jit u vsech objektu o jeden thread) +// +// interface of the Boyer-Moore algorithm object for text searching +// CAUTION: each allocated object can be used only in one thread +// (it doesn't have to be the main thread, it doesn't have to be the same thread for all objects) class CSalamanderBMSearchData { public: - // nastaveni vzorku; 'pattern' je null-terminated text vzorku; 'flags' jsou priznaky - // algoritmu (viz konstanty SASF_XXX) + // pattern setting; 'pattern' is null-terminated text pattern; 'flags' are flags + // of algorithm (see constants SASF_XXX) virtual void WINAPI Set(const char* pattern, WORD flags) = 0; + // pattern setting; 'pattern' is binary pattern of length 'length' (buffer 'pattern' // nastaveni vzorku; 'pattern' je binarni vzorek o delce 'length' (buffer 'pattern' musi // mit delku alespon ('length' + 1) znaku - jen pro kompatibilitu s textovymi vzorky); // 'flags' jsou priznaky algoritmu (viz konstanty SASF_XXX) From 0ad1f999d43ad4db783597e7dacca7c6e614f4ba Mon Sep 17 00:00:00 2001 From: =?UTF-8?q?Michal=20V=C3=A1rady?= Date: Tue, 19 Dec 2023 20:07:01 +0100 Subject: [PATCH 2/2] spl_gen.h, spl_com.h: translated --- src/plugins/shared/spl_com.h | 1000 +++++++++++++++++----------------- src/plugins/shared/spl_gen.h | 254 ++++----- 2 files changed, 627 insertions(+), 627 deletions(-) diff --git a/src/plugins/shared/spl_com.h b/src/plugins/shared/spl_com.h index 2d4549d9c..9b8c6b418 100644 --- a/src/plugins/shared/spl_com.h +++ b/src/plugins/shared/spl_com.h @@ -1,5 +1,6 @@ // SPDX-FileCopyrightText: 2023 Open Salamander Authors // SPDX-License-Identifier: GPL-2.0-or-later +// CommentsTranslationProject: TRANSLATED //**************************************************************************** // @@ -12,7 +13,7 @@ #pragma once #ifdef _MSC_VER -#pragma pack(push, enter_include_spl_com) // aby byly struktury nezavisle na nastavenem zarovnavani +#pragma pack(push, enter_include_spl_com) // so that the structures are independent of the alignment setting #pragma pack(4) #pragma warning(3 : 4706) // warning C4706: assignment within conditional expression #endif // _MSC_VER @@ -20,28 +21,28 @@ #pragma option -a4 #endif // __BORLANDC__ -// v pluginu je treba definovat promennou SalamanderVersion (int) a v SalamanderPluginEntry tuto -// promennou inicializovat: +// in the plugin, it is neccessary to define the variable SalamanderVersion (int) and initialize +// this variable in SalamanderPluginEntry: // SalamanderVersion = salamander->GetVersion(); -// globalni promenna s verzi Salamandera, ve kterem je tento plugin nacteny +// global variable with the version of Salamander in which this plugin is loaded extern int SalamanderVersion; // // **************************************************************************** // CSalamanderDirectoryAbstract // -// trida reprezentuje adresarovou strukturu - soubory a adresare na pozadovanych cestach, root cesta je "", -// oddelovace v ceste jsou backslashe ('\\') +// Class representing a directory structure - files and directories in the desired paths, root path is "", +// separators in the path are backslashes ('\\') // -// CQuadWord - 64-bitovy unsigned integer pro velikosti souboru -// triky: -// -rychlejsi predani vstupniho parametru typu CQuadWord: const CQuadWord & -// -priradit 64-bit integer: quadWord.Value = XXX; -// -pocitat pomer velikosti: quadWord1.GetDouble() / quadWord2.GetDouble() // ztrata presnosti pred delenim se projevi malo (max. 1e-15) -// -oriznout na DWORD: (DWORD)quadWord.Value -// -prevest (unsigned) __int64 na CQuadWord: CQuadWord().SetUI64(XXX) +// CQuadWord - 64-bit unsigned integer for file sizes +// tricks: +// -faster passing of an input parameter of type CQuadWord: const CQuadWord & +// -assign a 64-bit integer: quadWord.Value = XXX; +// -calculate the size ratio: quadWord1.GetDouble() / quadWord2.GetDouble() // the loss of precision before division will be small (max. 1e-15) +// -trim to DWORD: (DWORD)quadWord.Value +// -convert (unsigned) __int64 to CQuadWord: CQuadWord().SetUI64(XXX) struct CQuadWord { @@ -55,9 +56,9 @@ struct CQuadWord unsigned __int64 Value; }; - // POZOR: nesmi sem prijit operator prirazeni ani konstruktor pro jeden DWORD, - // jinak bude pouziti 8-bytovych cisel zcela nekontrolovatelne (C++ vse - // vzajemne prevede, coz nemusi byt vzdy prave ono) + // CAUTION: The assignment operator or constructor for a single DWORD must not be used here, + // otherwise the use of 8-bit numbers will be completely uncontrollable (C++ converts everything + // mutually, which may not always be correct) CQuadWord() {} CQuadWord(DWORD lo, DWORD hi) @@ -185,11 +186,11 @@ struct CQuadWord BOOL operator<=(const CQuadWord& qw) const { return Value <= qw.Value; } BOOL operator>=(const CQuadWord& qw) const { return Value >= qw.Value; } - // prevod na double (pozor na ztratu presnosti u velkych cisel - double ma jen 15 platnych cislic) + // Conversion to double (note the loss of precision for large numbers - double has only 15 valid digits) double GetDouble() const - { // MSVC neumi konverzi unsigned __int64 na double, takze si musime pomoct sami + { // MSVC does not know how to convert unsigned __int64 to double, so we have to help ourselves if (Value < CQuadWord(0, 0x80000000).Value) - return (double)(__int64)Value; // kladne cislo + return (double)(__int64)Value; // positive number else return 9223372036854775808.0 + (double)(__int64)(Value - CQuadWord(0, 0x80000000).Value); } @@ -197,82 +198,84 @@ struct CQuadWord #define QW_MAX CQuadWord(0xFFFFFFFF, 0xFFFFFFFF) -#define ICONOVERLAYINDEX_NOTUSED 15 // hodnota pro CFileData::IconOverlayIndex v pripade, ze ikona nema overlay +#define ICONOVERLAYINDEX_NOTUSED 15 // value for CFileData::IconOverlayIndex in case the icon has no overlay -// zaznam kazdeho souboru a adresare v Salamanderovi (zakladni data o souboru/adresari) -struct CFileData // nesmi sem prijit destruktor ! +// record of each file and directory in Salamander (basic data about the file/directory) +struct CFileData // destructor must not be here! { - char* Name; // naalokovane jmeno souboru (bez cesty), nutne alokovat na heapu - // Salamandera (viz CSalamanderGeneralAbstract::Alloc/Realloc/Free) - char* Ext; // ukazatel do Name za prvni tecku zprava (vcetne tecky na zacatku jmena, - // na Windows se chape jako pripona, narozdil od UNIXu) nebo na konec - // Name, pokud pripona neexistuje; je-li v konfiguraci nastaveno FALSE - // pro SALCFG_SORTBYEXTDIRSASFILES, je v Ext pro adresare ukazatel na konec - // Name (adresare nemaji pripony) - CQuadWord Size; // velikost souboru v bytech - DWORD Attr; // atributy souboru - ORovane konstanty FILE_ATTRIBUTE_XXX - FILETIME LastWrite; // cas posledniho zapisu do souboru (UTC-based time) - char* DosName; // naalokovane DOS 8.3 jmeno souboru, neni-li treba je NULL, nutne - // alokovat na heapu Salamandera (viz CSalamanderGeneralAbstract::Alloc/Realloc/Free) - DWORD_PTR PluginData; // pouziva plugin skrze CPluginDataInterfaceAbstract, Salamander ignoruje - unsigned NameLen : 9; // delka retezce Name (strlen(Name)) - POZOR: maximalni delka jmena je (MAX_PATH - 5) - unsigned Hidden : 1; // je hidden? (je-li 1, ikonka je pruhlednejsi o 50% - ghosted) - unsigned IsLink : 1; // je link? (je-li 1, ikonka ma overlay linku) - standardni plneni viz CSalamanderGeneralAbstract::IsFileLink(CFileData::Ext), pri zobrazeni ma prednost pred IsOffline, ale IconOverlayIndex ma prednost - unsigned IsOffline : 1; // je offline? (je-li 1, ikonka ma overlay offline - cerne hodiny), pri zobrazeni ma IsLink i IconOverlayIndex prednost - unsigned IconOverlayIndex : 4; // index icon-overlaye (pokud ikona nema zadny overlay, je zde hodnota ICONOVERLAYINDEX_NOTUSED), pri zobrazeni ma prednost pred IsLink a IsOffline - - // flagy pro interni pouziti v Salamanderovi: nuluji se pri pridani do CSalamanderDirectoryAbstract - unsigned Association : 1; // vyznam jen pro zobrazeni 'simple icons' - ikona asociovaneho souboru, jinak 0 - unsigned Selected : 1; // read-only flag oznaceni (0 - polozka neoznacena, 1 - polozka oznacena) - unsigned Shared : 1; // je adresar sdileny? u souboru se nepouziva - unsigned Archive : 1; // jedna se o archiv? pouziva se pro zobrazovani ikony archivu v panelu - unsigned SizeValid : 1; // je u adresare napocitana jeho velikost? - unsigned Dirty : 1; // je potreba tuto polozku prekreslit? (pouze docasna platnost; mezi nastavenim bitu a prekreslenim panelu nesmi byt pumpovana message queue, jinak muze dojit k prekresleni ikonky (icon reader) a tim resetu bitu! v dusledku se neprekresli polozka) - unsigned CutToClip : 1; // je CUT-nutej na clipboardu? (je-li 1, ikonka je pruhlednejsi o 50% - ghosted) - unsigned IconOverlayDone : 1; // jen pro potreby icon-reader-threadu: ziskavame nebo uz jsme ziskavali icon-overlay? (0 - ne, 1 - ano) + char* Name; // allocated file name (without path), must be allocated on the heap + // of the Salamander (see CSalamanderGeneralAbstract::Alloc/Realloc/Free) + char* Ext; // pointer to the Name after the first dot from the right (including the dot at the beginning of the name, + // on Windows it is understood as an extension, unlike UNIX) or at the end + // of Name if the extension does not exist; if FALSE is set in the configuration + // for SALCFG_SORTBYEXTDIRSASFILES, Ext for directories is a pointer to the end + // of Name (directories have no extensions) + CQuadWord Size; // file size in bytes + DWORD Attr; // file attributes - ORed constants FILE_ATTRIBUTE_XXX + FILETIME LastWrite; // time of the last write to the file (UTC-based time) + char* DosName; // allocated DOS 8.3 file name, if not needed, it is NULL, must be allocated on the heap + // of the Salamander (see CSalamanderGeneralAbstract::Alloc/Realloc/Free) + DWORD_PTR PluginData; // used by a plugin through CPluginDataInterfaceAbstract, Salamander ignores + unsigned NameLen : 9; // length of the Name string (strlen(Name)) - WARNING: the maximum length of the name is (MAX_PATH - 5) + unsigned Hidden : 1; // is hidden? (if 1, the icon is 50% transparent - ghosted) + unsigned IsLink : 1; // is links? (if 1, the icon has a link overlay) - standard filling see CSalamanderGeneralAbstract::IsFileLink(CFileData::Ext), has priority over IsOffline when displayed, but IconOverlayIndex has priority + unsigned IsOffline : 1; // is offline? (if 1, the icon has an offline overlay - black clock), when displayed, both IsLink and IconOverlayIndex have priority + unsigned IconOverlayIndex : 4; // index of the icon overlay (if the icon has no overlay, the value is ICONOVERLAYINDEX_NOTUSED), when displayed, it has priority over IsLink and IsOffline + + // flags for internal use in Salamander: reset when added to CSalamanderDirectoryAbstract + unsigned Association : 1; // makes sense only for displaying 'simple icons' - icon associated with the file, otherwise 0 + unsigned Selected : 1; // read-only flag of selection (0 - item not selected, 1 - item selected) + unsigned Shared : 1; // is the directory shared? not used for files + unsigned Archive : 1; // is it an archive? used to display the archive icon in the panel + unsigned SizeValid : 1; // is the size of the directory counted for the directory? + unsigned Dirty : 1; // is it necessary to redraw this item? (temporary validity; between setting the bit and redrawing the panel, the message queue must not be pumped, otherwise the icon (icon reader) may be redrawn and thus the bit reset! as a result, the item is not redrawn) + unsigned CutToClip : 1; // is it CUT to the clipboard? (if 1, the icon is 50% more transparent - ghosted) + unsigned IconOverlayDone : 1; // only for the needs of the icon reader thread: have we already obtained the icon overlay? (0 - no, 1 - yes) }; -// konstanty urcujici platnost dat, ktera jsou primo ulozena v CFileData (velikost, pripona, atd.) -// nebo se generuji z primo ulozenych dat automaticky (file-type se generuje z pripony); -// Name + NameLen jsou povinne (musi byt platne vzdy); platnost PluginData si ridi plugin sam -// (Salamander tento atribut ignoruje) -#define VALID_DATA_EXTENSION 0x0001 // pripona je ulozena v Ext (bez: vsechny Ext = konec Name) -#define VALID_DATA_DOSNAME 0x0002 // DOS name je ulozeno v DosName (bez: vsechny DosName = NULL) -#define VALID_DATA_SIZE 0x0004 // velikost v bytech je ulozena v Size (bez: vsechny Size = 0) -#define VALID_DATA_TYPE 0x0008 // file-type muze byt generovan z Ext (bez: negeneruje se) -#define VALID_DATA_DATE 0x0010 // datum modifikace (UTC-based) je ulozen v LastWrite (bez: vsechny datumy v LastWrite jsou 1.1.1602 v local time) -#define VALID_DATA_TIME 0x0020 // cas modifikace (UTC-based) je ulozen v LastWrite (bez: vsechny casy v LastWrite jsou 0:00:00 v local time) -#define VALID_DATA_ATTRIBUTES 0x0040 // atributy jsou ulozeny v Attr (ORovane Win32 API konstanty FILE_ATTRIBUTE_XXX) (bez: vsechny Attr = 0) -#define VALID_DATA_HIDDEN 0x0080 // "ghosted" priznak ikony je ulozen v Hidden (bez: vsechny Hidden = 0) -#define VALID_DATA_ISLINK 0x0100 // IsLink obsahuje 1 pokud jde o link, ikonka ma overlay linku (bez: vsechny IsLink = 0) -#define VALID_DATA_ISOFFLINE 0x0200 // IsOffline obsahuje 1 pokud jde o offline soubor/adresar, ikonka ma offline overlay (bez: vsechny IsOffline = 0) -#define VALID_DATA_PL_SIZE 0x0400 // ma smysl jen bez pouziti VALID_DATA_SIZE: plugin ma aspon pro nektere soubory/adresare ulozenou velikost v bytech (nekde v PluginData), pro ziskani teto velikosti Salamander vola CPluginDataInterfaceAbstract::GetByteSize() -#define VALID_DATA_PL_DATE 0x0800 // ma smysl jen bez pouziti VALID_DATA_DATE: plugin ma aspon pro nektere soubory/adresare ulozeny datum modifikace (nekde v PluginData), pro ziskani teto velikosti Salamander vola CPluginDataInterfaceAbstract::GetLastWriteDate() -#define VALID_DATA_PL_TIME 0x1000 // ma smysl jen bez pouziti VALID_DATA_TIME: plugin ma aspon pro nektere soubory/adresare ulozeny cas modifikace (nekde v PluginData), pro ziskani teto velikosti Salamander vola CPluginDataInterfaceAbstract::GetLastWriteTime() -#define VALID_DATA_ICONOVERLAY 0x2000 // IconOverlayIndex je index icon-overlaye (zadny overlay = hodnota ICONOVERLAYINDEX_NOTUSED) (bez: vsechny IconOverlayIndex = ICONOVERLAYINDEX_NOTUSED), zadani ikon viz CSalamanderGeneralAbstract::SetPluginIconOverlays - -#define VALID_DATA_NONE 0 // pomocna konstanta - platne je jen Name a NameLen +// constants determining the validity of data that is directly stored in CFileData (size, extension, etc.) +// or are generated from directly stored data automatically (file-type is generated from the extension); +// Name + NameLen are mandatory (must be valid at all times); the validity of PluginData is controlled by the plugin itself +// (Salamander ignores this attribute) +#define VALID_DATA_EXTENSION 0x0001 // extension is stored in Ext (if not set: all Ext = end of Name) +#define VALID_DATA_DOSNAME 0x0002 // DOS name is stored in DosName (if not set: all DosName = NULL) +#define VALID_DATA_SIZE 0x0004 // size in bytes is stored in Size (if not set: all Size = 0) +#define VALID_DATA_TYPE 0x0008 // file-type can be generated from Ext (if not set: not generated) +#define VALID_DATA_DATE 0x0010 // modification date (UTC-based) is stored in LastWrite (if not set: all dates in LastWrite are 1.1.1602 in local time) +#define VALID_DATA_TIME 0x0020 // modification time (UTC-based) is stored in LastWrite (if not set: all times in LastWrite are 0:00:00 in local time) +#define VALID_DATA_ATTRIBUTES 0x0040 // attributes are stored in Attr (ORed Win32 API constants FILE_ATTRIBUTE_XXX) (if not set: all Attr = 0) +#define VALID_DATA_HIDDEN 0x0080 // "ghosted" icon flag is stored in Hidden (if not set: all Hidden = 0) +#define VALID_DATA_ISLINK 0x0100 // IsLink contains 1 if it is a link, the icon has a link overlay (without: all IsLink = 0) +#define VALID_DATA_ISOFFLINE 0x0200 // IsOffline contains 1 if it is an offline file/directory, the icon has an offline overlay (without: all IsOffline = 0) +#define VALID_DATA_PL_SIZE 0x0400 // makes sense only without using VALID_DATA_SIZE: the plugin has the size of the file/directory stored in bytes (somewhere in PluginData), to get this size, Salamander calls CPluginDataInterfaceAbstract::GetByteSize() +#define VALID_DATA_PL_DATE 0x0800 // makes sense only without using VALID_DATA_DATE: the plugin has the modification date of the file/directory stored (somewhere in PluginData), to get this size, Salamander calls CPluginDataInterfaceAbstract::GetLastWriteDate() +#define VALID_DATA_PL_TIME 0x1000 // makes sense only without using VALID_DATA_TIME: the plugin has the modification time of the file/directory stored (somewhere in PluginData), to get this size, Salamander calls CPluginDataInterfaceAbstract::GetLastWriteTime() +#define VALID_DATA_ICONOVERLAY 0x2000 // IconOverlayIndex is the index of the icon overlay (no overlay = ICONOVERLAYINDEX_NOTUSED value) (if not used: all IconOverlayIndex = ICONOVERLAYINDEX_NOTUSED), icon assignment see CSalamanderGeneralAbstract::SetPluginIconOverlays + +#define VALID_DATA_NONE 0 // helper constant - valid for Name and NameLen only #ifdef INSIDE_SALAMANDER -// VALID_DATA_ALL a VALID_DATA_ALL_FS_ARC jsou jen pro interni pouziti v Salamanderovi (jadre), -// pluginy si naORuji jen konstanty odpovidajici pluginem dodavanym datum (zamezi se tak problemum -// pri zavedeni dalsich konstant a jim odpovidajicim datum) +// VALID_DATA_ALL and VALID_DATA_ALL_FS_ARC are only for internal use in Salamander (core), +// plugins only OR constants corresponding to the dates supplied by the plugins (this prevents +// problems when introducing additional constants and their corresponding dates) + #define VALID_DATA_ALL 0xFFFF -#define VALID_DATA_ALL_FS_ARC (0xFFFF & ~VALID_DATA_ICONOVERLAY) // pro FS a archivy: vse krome icon-overlays +#define VALID_DATA_ALL_FS_ARC (0xFFFF & ~VALID_DATA_ICONOVERLAY) // for FS and archives: everything except icon-overlays #endif // INSIDE_SALAMANDER -// Pokud je zapnuto skryvani hidden a system souboru a adresaru, nezobrazuji se v panelech polozky s -// Hidden==1 a Attr obsahujicim FILE_ATTRIBUTE_HIDDEN a/nebo FILE_ATTRIBUTE_SYSTEM. +// if hiding of hidden and system files and directories is turned on, items with Hidden==1 and Attr +// containing FILE_ATTRIBUTE_HIDDEN and/or FILE_ATTRIBUTE_SYSTEM are not displayed in the panels + +// constants of flags for CSalamangerDirectoryAbstract: +// names of files and directories (even in paths) are to be compared case-sensitive (without this flag, +// comparison is case-insensitive - standard behavior in Windows) -// konstanty priznaku pro CSalamanderDirectoryAbstract: -// jmena souboru a adresaru (i v cestach) se maji porovnavat case-sensitive (bez tohoto flagu je -// porovnavani case-insensitive - standardni chovani ve Windows) #define SALDIRFLAG_CASESENSITIVE 0x0001 -// jmena podadresaru v ramci kazdeho adresare se nebudou testovat na duplicitu (tento -// test je casove narocny a je nutny jen v archivech, pokud se pridavaji polozky nejen -// do rootu - aby fungovalo napr. pridani "file1" na "dir1" nasledovane pridanim -// "dir1" - "dir1" se prida prvni operaci (automaticky se prida neexistujici cesta), -// druha operace uz jen obnovi udaje o "dir1" (nesmi ho pridat znovu)) +// names of subdir in each directory are not tested for duplicity (this test is time-consuming and is +// necessary only in archives, if items are added not only to the root - to make it work, for example, +// adding "file1" to "dir1" followed by adding "dir1" - "dir1" is added by the first operation +// (the non-existent path is automatically added), the second operation only restores the data about "dir1" +// (it must not be added again) #define SALDIRFLAG_IGNOREDUPDIRS 0x0002 class CPluginDataInterfaceAbstract; @@ -280,75 +283,73 @@ class CPluginDataInterfaceAbstract; class CSalamanderDirectoryAbstract { public: - // vycisti cely objekt, pripravi ho pro dalsi pouziti; pokud 'pluginData' neni NULL, pouzije - // se pro soubory a adresare k uvolneni dat specifickych pluginu (CFileData::PluginData); - // nastavuje standardni hodnotu masky platnych dat (suma vsech VALID_DATA_XXX krome - // VALID_DATA_ICONOVERLAY) a priznaku objektu (viz metoda SetFlags) + // clear the entire object, prepare it for further use; if 'pluginData' is not NULL, it is used + // for files and directories to release data specific to plugins (CFileData::PluginData); + // sets the standard value of the mask of valid data (the sum of all VALID_DATA_XXX except + // VALID_DATA_ICONOVERLAY) and the flag of the object (see the SetFlags method) virtual void WINAPI Clear(CPluginDataInterfaceAbstract* pluginData) = 0; - // zadani masky platnych dat, podle ktere se urcuje, ktera data z CFileData jsou platna - // a ktera se maji pouze "nulovat" (viz komentar k VALID_DATA_XXX); maska 'validData' - // obsahuje ORovane hodnoty VALID_DATA_XXX; standardni hodnota masky je suma vsech - // VALID_DATA_XXX krome VALID_DATA_ICONOVERLAY; masku platnych dat je potreba nastavit - // pred volanim AddFile/AddDir + // set the mask of valid data, according to which it is determined which data from CFileData are valid + // and which should only be "zeroed" (see the comment for VALID_DATA_XXX); the mask 'validData' + // contains ORed values VALID_DATA_XXX; the standard value of the mask is the sum of all + // VALID_DATA_XXX except VALID_DATA_ICONOVERLAY; the mask of valid data must be set before calling + // AddFile/AddDir virtual void WINAPI SetValidData(DWORD validData) = 0; - // nastaveni priznaku pro tento objekt; 'flags' je kombinace ORovanych priznaku SALDIRFLAG_XXX, - // standardni hodnota priznaku objektu je nula pro archivatory (zadny priznak neni nastaven) - // a SALDIRFLAG_IGNOREDUPDIRS pro file-systemy (smi se pridavat jen do rootu, test na duplicitu - // adresaru je zbytecny) + // set the flag of the object; 'flags' is a combination of ORed flags SALDIRFLAG_XXX, the standard + // value of the object flag is zero for archivers (no flag is set) and SALDIRFLAG_IGNOREDUPDIRS + // for file systems (can only be added to the root, the test for duplicate directories is unnecessary) virtual void WINAPI SetFlags(DWORD flags) = 0; - // prida soubor na zadanou cestou (relativni k tomuto "salamander-adresari"), vraci uspech - // retezec path se pouziva jen uvnitr funkce, obsah struktury file se pouziva i mimo funkci - // (neuvolnovat pamet naalokovanou pro promenne uvnitr struktury) - // v pripade neuspechu, je treba obsah struktury file uvolnit; - // parametr 'pluginData' neni NULL jen pro archivy (FS pouzivaji jen prazdne 'path' (==NULL)); - // neni-li 'pluginData' NULL, pouziva se 'pluginData' pri zakladani novych adresaru (pokud - // 'path' neexistuje), viz CPluginDataInterfaceAbstract::GetFileDataForNewDir; - // kontrola unikatnosti jmena souboru na ceste 'path' se neprovadi + // add a file to the specified path (relative to this "salamander directory"), returns success + // the string 'path' is used only inside the function, the contents of the file structure are + // used outside the function as well (do not release the memory allocated for variables inside the structure) + // (if case of failure, the contents of the file structure must be released; + // the 'pluginData' parameter is not NULL only for archives (FS only use empty 'path' (==NULL)); + // if 'pluginData' is not NULL, it is used to create new directories (if 'path' does not exist), + // see CPluginDataInterfaceAbstract::GetFileDataForNewDir; + // the uniqueness of the file name on the path 'path' is not checked virtual BOOL WINAPI AddFile(const char* path, CFileData& file, CPluginDataInterfaceAbstract* pluginData) = 0; - // prida adresar na zadanou cestu (relativni k tomuto "salamander-adresari"), vraci uspech - // retezec path se pouziva jen uvnitr funkce, obsah struktury file se pouziva i mimo funkci - // (neuvolnovat pamet naalokovanou pro promenne uvnitr struktury) - // v pripade neuspechu, je treba obsah struktury file uvolnit; - // parametr 'pluginData' neni NULL jen pro archivy (FS pouzivaji jen prazdne 'path' (==NULL)); - // neni-li 'pluginData' NULL, pouziva se pri zakladani novych adresaru (pokud 'path' neexistuje), - // viz CPluginDataInterfaceAbstract::GetFileDataForNewDir; - // kontrola unikatnosti jmena adresare na ceste 'path' se provadi, dochazi-li k pridani - // jiz existujiciho adresare, dojde k uvolneni puvodnich dat (neni-li 'pluginData' NULL, vola - // se pro uvolneni dat i CPluginDataInterfaceAbstract::ReleasePluginData) a ulozeni dat z 'dir' - // (je nutne pro obnovu dat adresaru, ktere se vytvori automaticky pri neexistenci 'path'); - // specialita pro FS (nebo objekt alokovany pres CSalamanderGeneralAbstract::AllocSalamanderDirectory - // s 'isForFS'==TRUE): je-li dir.Name "..", je adresar pridan jako up-dir (muze byt jen jeden, - // zobrazuje se vzdy na zacatku listingu a ma specialni ikonu) + // add a directory to the specified path (relative to this "salamander directory"), returns success + // the string 'path' is used only inside the function, the contents of the file structure are + // used outside the function as well (do not release the memory allocated for variables inside the structure) + // (if case of failure, the contents of the file structure must be released; + // the 'pluginData' parameter is not NULL only for archives (FS only use empty 'path' (==NULL)); + // if 'pluginData' is not NULL, it is used to create new directories (if 'path' does not exist), + // see CPluginDataInterfaceAbstract::GetFileDataForNewDir; + // the uniqueness of the directory name on the path 'path' is checked, if a directory with the same + // name already exists, the original data are released (if 'pluginData' is not NULL, CPluginDataInterfaceAbstract::ReleasePluginData + // is called to release the data) and the data from 'dir' are saved (it is necessary to restore the data + // of the directory, which is automatically created when 'path' does not exist); + // speciality for FS (or an object allocated via CSalamanderGeneralAbstract::AllocSalamanderDirectory + // with 'isForFS'==TRUE): if dir.Name == "..", the directory is added as an up-dir (there can be only + // one, it is always displayed at the beginning of the listing and has a special icon) virtual BOOL WINAPI AddDir(const char* path, CFileData& dir, CPluginDataInterfaceAbstract* pluginData) = 0; - // vraci pocet souboru v objektu + // returns the number of files in the object virtual int WINAPI GetFilesCount() const = 0; - // vraci pocet adresaru v objektu + // returns the number of directories in the object virtual int WINAPI GetDirsCount() const = 0; - // vraci soubor z indexu 'index', vracena data lze pouzit jen pro cteni + // returns the files from the 'index' index, the returned data can only be used for reading virtual CFileData const* WINAPI GetFile(int index) const = 0; - // vraci adresar z indexu 'index', vracena data lze pouzit jen pro cteni + // returns the directory from the 'index' index, the returned data can only be used for reading virtual CFileData const* WINAPI GetDir(int index) const = 0; - // vraci objekt CSalamanderDirectory pro adresar z indexu 'index', vraceny objekt lze - // pouzit jen pro cteni (objekty pro prazdne adresare nejsou alokovany, vraci se jeden - // globalni prazdny objekt - zmena tohoto objektu by se projevila globalne) + // returns the object CSalamanderDirectory for the directory from the 'index' index, the returned object + // can only be used for reading (objects for empty directories are not allocated, one global empty object is returned + // - changing this object would be reflected globally) virtual CSalamanderDirectoryAbstract const* WINAPI GetSalDir(int index) const = 0; - // Pluginu umoznuje predem sdelit predpokladany pocet souboru a adresaru v tomto adresari. - // Salamander si upravi realokacni strategii tak, aby pridavani prvku prilis nebrzdilo. - // Ma smysl volat pro adresare obsahujici tisice souboru nebo adresaru. V pripade desitek - // tisic uz je zavolani teto metody temer nutnost, jinak realokace zaberou nekolik vterin. - // 'files' a 'dirs' tedy vyjadruji priblizny celkovy pocet souboru a adresaru. - // Pokud je nektera z hodnot -1, bude ji Salamander ignorovat. - // Metodu ma vyznam volat pouze pokud je adresar prazdny, tedy nebylo volano AddFile nebo AddDir. + // allows to inform the Plugin about expected number of files and directories in this directory beforehand. + // Salamander will adjust its reallocation strategy to avoid slowdowns when adding items. Makes sense only + // for directories containing thousands of files or directories. For tens of thousands of items it is + // almost a necessity, otherwise reallocations take several seconds. 'files' and 'dirs' express approximate + // total number of files and directories. If any of the values is -1, Salamander will ignore it. + // This method makes sense only if the directory is empty, i.e. AddFile or AddDir was not called. virtual void WINAPI SetApproximateCount(int files, int dirs) = 0; }; @@ -357,57 +358,54 @@ class CSalamanderDirectoryAbstract // SalEnumSelection a SalEnumSelection2 // -// konstanty vracene z SalEnumSelection a SalEnumSelection2 v parametru 'errorOccured' -#define SALENUM_SUCCESS 0 // chyba nenastala -#define SALENUM_ERROR 1 // nastala chyba a uzivatel si preje pokracovat v operaci (vynechaly se jen chybne soubory/adresare) -#define SALENUM_CANCEL 2 // nastala chyba a uzivatel si preje zrusit operaci - -// enumerator, vraci jmena souboru, konci vracenim NULL; -// 'enumFiles' == -1 -> reset enumerace (po tomto volani zacina enumerace opet od zacatku), vsechny -// dalsi parametry (az na 'param') jsou ignorovany, nema navratove hodnoty (dava -// vse na nulu) -// 'enumFiles' == 0 -> enumerace souboru a podadresaru jen z korene -// 'enumFiles' == 1 -> enumerace vsech souboru a podadresaru -// 'enumFiles' == 2 -> enumerace vsech podadresaru, soubory jen z korene; -// k chybe muze dojit jen pri 'enumFiles' == 1 nebo 'enumFiles' == 2 ('enumFiles' == 0 nekompletuje -// jmena a cesty); 'parent' je parent pripadnych messageboxu s chybami (NULL znamena nezobrazovat -// chyby); v 'isDir' (neni-li NULL) vraci TRUE pokud jde o adresar; v 'size' (neni-li NULL) vraci -// velikost souboru (u adresaru se vraci velikost jen pri 'enumFiles' == 0 - jinak je nulova); -// neni-li 'fileData' NULL, vraci se v nem ukazatel na strukturu CFileData vraceneho -// souboru/adresare (pokud enumerator vraci NULL, vraci se v 'fileData' take NULL); -// 'param' je parametr 'nextParam' predavany spolu s ukazatelem na funkci tohoto -// typu; v 'errorOccured' (neni-li NULL) se vraci SALENUM_ERROR, pokud se pri sestavovani vracenych -// jmen narazilo na prilis dlouhe jmeno a uzivatel se rozhodl preskocit jen chybne soubory/adresare, -// POZOR: chyba se netyka prave vraceneho jmena, to je OK; v 'errorOccured' (neni-li NULL) se vraci -// SALENUM_CANCEL pokud se pri chybe uzivatel rozhodl pro zruseni operace (cancel), zaroven -// enumerator vraci NULL (konci); v 'errorOccured' (neni-li NULL) se vraci SALENUM_SUCCESS pokud -// zadna chyba nenastala +// constants returned from SalEnumSelection a SalEnumSelection2 in the 'errorOccured' parameter +#define SALENUM_SUCCESS 0 // error did not occur +#define SALENUM_ERROR 1 // error occurred and the user wants to continue the operation (only incorrectly named files/directories were skipped) +#define SALENUM_CANCEL 2 // error occurred and the user wants to cancel the operation + +// enumerator, returns file names, ends with NULL; +// 'enumFiles' == -1 -> enumeration reset (after this call, the enumeration starts again from the beginning), +// all other parameters (except 'param') are ignored, no return values (everything is set to zero) +// 'enumFiles' == 0 -> enumeration of files and subdirectories only from the root +// 'enumFiles' == 1 -> enumeration of all files and subdirectories +// 'enumFiles' == 2 -> enumeration of all subdirectories, files only from the root; +// an error can occur only when 'enumFiles' == 1 or 'enumFiles' == 2 ('enumFiles' == 0 does not make +// names and paths complete); 'parent' is the parent of any error message boxes (NULL means not to show errors); +// 'isDir' (if not NULL) returns TRUE if it is a directory; 'size' (if not NULL) returns the size of the file +// (for directories it only returns the size when 'enumFiles' == 0 - otherwise it is zero); +// if 'fileData' is not NULL, it returns a pointer to the CFileData structure of the returned file/directory +// (if the enumerator returns NULL, NULL is also returned in 'fileData'); +// 'param' is the parameter 'nextParam' passed together with the pointer to the function of this type; +// 'errorOccured' (if not NULL) returns SALENUM_ERROR, if a very long name was encountered during the +// compilation of the returned names and the user decided to skip only the incorrect files/directories, +// CAUTION: the error does not apply to the name returned, it is OK; 'errorOccured' (if not NULL) returns +// SALENUM_CANCEL if the user decided to cancel the operation (cancel), at the same time the enumerator +// returns NULL (ends); 'errorOccured' (if not NULL) returns SALENUM_SUCCESS if no error occurred typedef const char*(WINAPI* SalEnumSelection)(HWND parent, int enumFiles, BOOL* isDir, CQuadWord* size, const CFileData** fileData, void* param, int* errorOccured); -// enumerator, vraci jmena souboru, konci vracenim NULL; -// 'enumFiles' == -1 -> reset enumerace (po tomto volani zacina enumerace opet od zacatku), vsechny -// dalsi parametry (az na 'param') jsou ignorovany, nema navratove hodnoty (dava -// vse na nulu) -// 'enumFiles' == 0 -> enumerace souboru a podadresaru jen z korene -// 'enumFiles' == 1 -> enumerace vsech souboru a podadresaru -// 'enumFiles' == 2 -> enumerace vsech podadresaru, soubory jen z korene; -// 'enumFiles' == 3 -> enumerace vsech souboru a podadresaru + symbolicke linky na soubory maji -// velikost ciloveho souboru (pri 'enumFiles' == 1 maji velikost linku, coz je snad -// vzdy nula); POZOR: 'enumFiles' musi zustat 3 pro vsechna volani enumeratoru; -// k chybe muze dojit jen pri 'enumFiles' == 1, 2 nebo 3 ('enumFiles' == 0 vubec -// nepracuje s diskem ani nekompletuje jmena a cesty); 'parent' je parent pripadnych messageboxu -// s chybami (NULL znamena nezobrazovat chyby); v 'dosName' (neni-li NULL) vraci DOSovy nazev -// (8.3; jen pokud existuje, jinak NULL); v 'isDir' (neni-li NULL) vraci TRUE pokud jde o adresar; -// v 'size' (neni-li NULL) vraci velikost souboru (u adresaru nulu); v 'attr' (neni-li NULL) -// vraci atributy souboru/adresare; v 'lastWrite' (neni-li NULL) vraci cas posledniho zapisu -// do souboru/adresare; 'param' je parametr 'nextParam' predavany spolu s ukazatelem na funkci -// tohoto typu; v 'errorOccured' (neni-li NULL) se vraci SALENUM_ERROR, pokud doslo behem cteni -// dat z disku k chybe nebo se pri sestavovani vracenych jmen narazilo na prilis dlouhe jmeno -// a uzivatel se rozhodl preskocit jen chybne soubory/adresare, POZOR: chyba se netyka prave -// vraceneho jmena, to je OK; v 'errorOccured' (neni-li NULL) se vraci SALENUM_CANCEL pokud se -// pri chybe uzivatel rozhodl pro zruseni operace (cancel), zaroven enumerator vraci NULL (konci); -// v 'errorOccured' (neni-li NULL) se vraci SALENUM_SUCCESS pokud zadna chyba nenastala +// enumerator, returns file names, ends with NULL; +// 'enumFiles' == -1 -> enumeration reset (after this call, the enumeration starts again from the beginning), +// all other parameters (except 'param') are ignored, no return values (everything is set to zero) +// 'enumFiles' == 0 -> enumeration of files and subdirectories only from the root +// 'enumFiles' == 1 -> enumeration of all files and subdirectories +// 'enumFiles' == 2 -> enumeration of all subdirectories, files only from the root; +// 'enumFiles' == 3 -> enumeration of all files and subdirectories, symbolic links to files have +// the size of the target file (for 'enumFiles' == 1 they have the size of the link, +// which is probably always zero); CAUTION: 'enumFiles' must remain 3 for all calls +// to the enumerator; +// an error can occur only when 'enumFiles' == 1, 2 or 3 ('enumFiles' == 0 does not work with the disk +// or complete names and paths); 'parent' is the parent of any error message boxes (NULL means not to show errors); +// 'dosName' (if not NULL) returns the DOS name (8.3; only if it exists, otherwise NULL); 'isDir' (if not NULL) +// returns TRUE if it is a directory; 'size' (if not NULL) returns the size of the file (for directories +// returns zero); 'attr' (if not NULL) returns the attributes of the file/directory; 'lastWrite' (if not NULL) +// returns the time of the last write to the file/directory; 'param' is the parameter 'nextParam' passed +// together with the pointer to the function of this type; 'errorOccured' (if not NULL) returns SALENUM_ERROR, +// if an error occurred while reading data from the disk or if a very long name was encountered during the +// compilation of the returned names and the user decided to skip only the incorrect files/directories, +// CAUTION: the error does not apply to the name returned, it is OK; 'errorOccured' (if not NULL) returns +// SALENUM_CANCEL if the user decided to cancel the operation (cancel), at the same time the enumerator +// returns NULL (ends); 'errorOccured' (if not NULL) returns SALENUM_SUCCESS if no error occurred typedef const char*(WINAPI* SalEnumSelection2)(HWND parent, int enumFiles, const char** dosName, BOOL* isDir, CQuadWord* size, DWORD* attr, FILETIME* lastWrite, void* param, int* errorOccured); @@ -416,8 +414,9 @@ typedef const char*(WINAPI* SalEnumSelection2)(HWND parent, int enumFiles, const // **************************************************************************** // CSalamanderViewAbstract // -// sada metod Salamandera pro praci se sloupci v panelu (vypinani/zapinani/pridavani/nastavovani) +// set of Salamander methods for working with columns in the panel (turning off/on/adding/setting) +// panel view modes // rezimy pohledu panelu #define VIEW_MODE_TREE 1 #define VIEW_MODE_BRIEF 2 @@ -426,164 +425,157 @@ typedef const char*(WINAPI* SalEnumSelection2)(HWND parent, int enumFiles, const #define VIEW_MODE_THUMBNAILS 5 #define VIEW_MODE_TILES 6 -#define TRANSFER_BUFFER_MAX 1024 // velikost bufferu pro prenos obsahu sloupcu z pluginu do Salamandera +#define TRANSFER_BUFFER_MAX 1024 // buffer size for transferring column contents from the plugin to Salamander #define COLUMN_NAME_MAX 30 #define COLUMN_DESCRIPTION_MAX 100 -// Identifikatory sloupcu. Sloupce vlozene pluginem maji nastaveno ID==COLUMN_ID_CUSTOM. -// Standardni sloupce Salamandera maji ostatni ID. -#define COLUMN_ID_CUSTOM 0 // sloupec je poskytovan pluginem - o ulozeni jeho dat se postara plugin -#define COLUMN_ID_NAME 1 // zarovnano vlevo, podporuje FixedWidth -// zarovnano vlevo, podporuje FixedWidth; samostatny sloupec "Ext", muze byt jen na indexu==1; -// pokud sloupec neexistuje a v datech panelu (viz CSalamanderDirectoryAbstract::SetValidData()) -// se nastavi VALID_DATA_EXTENSION, je sloupec "Ext" zobrazen ve sloupci "Name" +// Columns identifiers. Columns added by the plugin have ID==COLUMN_ID_CUSTOM. +// Salamander default columns have other IDs. +#define COLUMN_ID_CUSTOM 0 // the column is provided by the plugin - the plugin will take care of saving its data +#define COLUMN_ID_NAME 1 // aligned to the left, supports FixedWidth +// aligned to the left, supports FixedWidth; separate column "Ext" can only be at index==1; +// if the column does not exist and VALID_DATA_EXTENSION is set in the panel data (see CSalamanderDirectoryAbstract::SetValidData()), +// the column "Ext" is displayed in the column "Name" #define COLUMN_ID_EXTENSION 2 -#define COLUMN_ID_DOSNAME 3 // zarovnano vlevo -#define COLUMN_ID_SIZE 4 // zarovnano vpravo -#define COLUMN_ID_TYPE 5 // zarovnano vlevo, podporuje FixedWidth -#define COLUMN_ID_DATE 6 // zarovnano vpravo -#define COLUMN_ID_TIME 7 // zarovnano vpravo -#define COLUMN_ID_ATTRIBUTES 8 // zarovnano vpravo -#define COLUMN_ID_DESCRIPTION 9 // zarovnano vlevo, podporuje FixedWidth - -// Callback pro naplneni bufferu znakama, ktere se maji zobrazit v prislusnem sloupci. -// Z duvodu optimalizace funkce nedostava/nevraci promenne prostrednictvim parametru, -// ale prostrednictvim globalni promennych (CSalamanderViewAbstract::GetTransferVariables). +#define COLUMN_ID_DOSNAME 3 // aligned to the left +#define COLUMN_ID_SIZE 4 // aligned to the right +#define COLUMN_ID_TYPE 5 // aligned to the left, supports FixedWidth +#define COLUMN_ID_DATE 6 // aligned to the right +#define COLUMN_ID_TIME 7 // aligned to the right +#define COLUMN_ID_ATTRIBUTES 8 // aligned to the right +#define COLUMN_ID_DESCRIPTION 9 // aligned to the left, supports FixedWidth + +// Callback for filling the buffer with characters to be displayed in the corresponding column. +// For optimization reasons, the function does not receive/return variables via parameters, +// but via global variables (CSalamanderViewAbstract::GetTransferVariables). typedef void(WINAPI* FColumnGetText)(); -// Callback pro ziskani indexu jednoduchych ikon pro FS s vlastnimi ikonami (pitFromPlugin). -// Z duvodu optimalizace funkce nedostava/nevraci promenne prostrednictvim parametru, -// ale prostrednictvim globalni promennych (CSalamanderViewAbstract::GetTransferVariables). -// Z globalnich promennych callback vyuziva jen TransferFileData a TransferIsDir. +// Callback to get index of simple icons for FS with custom icons (pitFromPlugin). +// For optimization reasons, the function does not receive/return variables via parameters, +// but via global variables (CSalamanderViewAbstract::GetTransferVariables). +// Only TransferFileData and TransferIsDir are used from the global variables. typedef int(WINAPI* FGetPluginIconIndex)(); -// sloupec muze vzniknout dvema zpusoby: -// 1) Sloupec vytvoril Salamander na zaklade sablony aktualniho pohledu. -// V tomto pripade ukazatel 'GetText' (na plnici funkci) ukazuje do Salamandera -// a ziskava texty standardne z CFileData. -// Hodnota promenne 'ID' je ruzna od COLUMN_ID_CUSTOM. +// column can only be created by these two ways: +// 1) Salamander creates a column based on the template of the current view. +// In this case, the 'GetText' pointer (to the filler function) points to Salamander +// and gets the texts from CFileData. +// The value of the 'ID' variable is different from COLUMN_ID_CUSTOM. // -// 2) Sloupec pridal plugin na zaklade svych potreb. -// 'GetText' ukazuje do pluginu a 'ID' je rovno COLUMN_ID_CUSTOM. +// 2) The plugin added the column based on its needs. +// 'GetText' points to the plugin and 'ID' is equal to COLUMN_ID_CUSTOM. struct CColumn { - char Name[COLUMN_NAME_MAX]; // "Name", "Ext", "Size", ... nazev sloupce, pod - // kterym sloupec vystupuje v pohledu a v menu - // Nesmi obsahovat prazdny retezec. - // POZOR: Muze obsahovat (za prvnim null-terminatorem) - // i nazev sloupce "Ext" - toto nastava pokud neexistuje - // samostatny sloupec "Ext" a v datech panelu (viz - // CSalamanderDirectoryAbstract::SetValidData()) se - // nastavi VALID_DATA_EXTENSION. Pro spojeni dvou - // retezcu poslouzi CSalamanderGeneralAbstract::AddStrToStr(). - - char Description[COLUMN_DESCRIPTION_MAX]; // Tooltip v header line - // Nesmi obsahovat prazdny retezec. - // POZOR: Muze obsahovat (za prvnim null-terminatorem) - // i popis sloupce "Ext" - toto nastava pokud neexistuje - // samostatny sloupec "Ext" a v datech panelu (viz - // CSalamanderDirectoryAbstract::SetValidData()) se - // nastavi VALID_DATA_EXTENSION. Pro spojeni dvou - // retezcu poslouzi CSalamanderGeneralAbstract::AddStrToStr(). - - FColumnGetText GetText; // callback pro ziskani textu (popis u deklatace typu FColumnGetText) - - // FIXME_X64 - male pro ukazatel, neni nekdy potreba? - DWORD CustomData; // Neni pouzivana Salamanderem; plugin ji muze - // vyuzit pro rozliseni svych pridanych sloupcu. - - unsigned SupportSorting : 1; // je sloupec mozne radit? - - unsigned LeftAlignment : 1; // pro TRUE je sloupec zarovnavan vlevo; jinak vpravo - - unsigned ID : 4; // identifikator sloupce - // Pro standardni sloupce poskytovane Salamanderem - // obsahuje hodnoty ruzne od COLUMN_ID_CUSTOM. - // Pro sloupce pridane pluginem obsahuje vzdy - // hodnotu COLUMN_ID_CUSTOM. - - // Promenne Width a FixedWidth muzou byt zmeneny uzivatelem behem prace s panelem. - // Standardni sloupce poskytovane Salamanderem maji zajisteno ukladani/nacitani - // techto hodnot. - // Hodnoty techto promennych pro sloupce poskytovane pluginem je treba ulozit/nacist - // v ramci pluginu. - // Sloupce, jejichz sirku pocita Salamander na zaklade obsahu a uzivatel ji nemuze - // menit, nazyvame 'elasticke'. Sloupce, pro ktere muze uzivatel nastavit sirku nazyvame - // 'pevne'/'fixed'. - unsigned Width : 16; // Sirka sloupce v pripade, ze je v rezimu pevne (nastavitelne) sirky. - unsigned FixedWidth : 1; // Je sloupec v rezimu pevne (nastavitelne) sirky? - - // pracovni promenne (nikam se neukladaji a neni treba je inicializovat) - // jsou urcene pro interni potreby Salamandera a pluginy je ignoruji, - // protoze jejich obsah neni pri volani pluginu zaruceny - unsigned MinWidth : 16; // Minimalni sirka, na kterou muze byt sloupce smrsten. - // Je pocitana na zaklade nazvu sloupce a jeho raditelnosti - // tak, aby byla hlavicka sloupce vzdy viditelna + char Name[COLUMN_NAME_MAX]; // "Name", "Ext", "Size", ... name of column, under + // which the column appears in the view and in the menu + // Must not contain an empty string. + // CAUTION: It may contain (after the first null-terminator) + // also the name of the column "Ext" - this happens if there is no + // separate column "Ext" and in the data of the panel (see + // CSalamanderDirectoryAbstract::SetValidData()) VALID_DATA_EXTENSION is set. + // To join two strings, use CSalamanderGeneralAbstract::AddStrToStr(). + + char Description[COLUMN_DESCRIPTION_MAX]; // Tooltip in header line + // Must not contain an empty string. + // CAUTION: It may contain (after the first null-terminator) + // also the description of the column "Ext" - this happens if there is no + // separate column "Ext" and in the data of the panel (see + // CSalamanderDirectoryAbstract::SetValidData()) VALID_DATA_EXTENSION is set. + // To join two strings, use CSalamanderGeneralAbstract::AddStrToStr(). + + FColumnGetText GetText; // callback to get the text (description at the FColumnGetText type declaration) + + // FIXME_X64 - small for pointer, isn't it sometimes needed? + DWORD CustomData; // not used by Salamander; the plugin can use it to distinguish its added columns. + + unsigned SupportSorting : 1; // can the column be sorted? + + unsigned LeftAlignment : 1; // for TRUE, the column is aligned to the left; otherwise to the right + + unsigned ID : 4; // column identifier + // For standard columns provided by Salamander + // it contains values other than COLUMN_ID_CUSTOM. + // For columns added by the plugin, it always contains + // the value COLUMN_ID_CUSTOM. + // The variables Width and FixedWidth can be changed by the user during work with the panel. + // Standard columns provided by Salamander have the saving/loading of these values + // ensured. The values of these variables for columns provided by the plugin must be saved/loaded + // within the plugin. + // Columns whose width is calculated by Salamander based on the content and the user cannot + // change it are called 'elastic'. Columns for which the user can set the width are called + // 'fixed'. + unsigned Width : 16; // Column width in case of fixed (adjustable) width. + unsigned FixedWidth : 1; // Is the column in fixed (adjustable) width mode? + + // working variables (not saved anywhere and it is not necessary to initialize them) + // they are intended for internal needs of Salamander and plugins ignore them, + // because their content is not guaranteed when calling plugins + unsigned MinWidth : 16; // Minimal width to which the column can be narrowed. + // It is calculated based on the column name and its sortability + // so that the column header is always visible }; -// Plugin prostrednictvim tohoto rozhrani muze pri zmene cesty zmenit rezim -// zobrazeni v panelu. Veskera prace se sloupci se tyka jen vsech detailed rezimu -// (Detailed + Types + tri volitelne rezimy Alt+8/9/0). Pri zmene cesty dostane -// plugin standardni sadu sloupcu nagenerovanou na zaklade sablony aktualniho -// pohledu. Plugin muze tuto sadu modifikovat. Modifikace neni trvaleho razu -// a pri pristi zmene cesty obdrzi plugin opet standardni sadu sloupcu. Muze tak -// napriklad odstranit nektery ze std. sloupcu. Pred novym plnenim std. sloupci -// dostane plugin prilezitost ulozeni informaci o svych sloupcich (COLUMN_ID_CUSTOM). -// Muze tak ulozit jejich 'Width' a 'FixedWidth', ktere uzivatel mohl v panelu -// nastavit (viz ColumnFixedWidthShouldChange() a ColumnWidthWasChanged() v interfacu -// CPluginDataInterfaceAbstract). Pokud plugin zmeni rezim pohledu, zmena je trvala -// (napr. prepnuti na rezim Thumbnails zustane i po opusteni pluginove cesty). +// Plugin can change the mode of displaying the panel via this interface when the path changes. +// All work with columns concerns only all detailed modes (Detailed + Types + three optional modes Alt+8/9/0). +// When the path changes, the plugin gets the standard set of columns generated based on the template +// of the current view. The plugin can modify this set. The modification is not permanent and when the +// path changes again, the plugin gets the standard set of columns again. It can, for example, remove +// some of the std. columns. Before filling the std. columns again, the plugin gets the opportunity +// to save information about its columns (COLUMN_ID_CUSTOM). It can save their 'Width' and 'FixedWidth', +// which the user could set in the panel (see ColumnFixedWidthShouldChange() and ColumnWidthWasChanged() +// in the interface CPluginDataInterfaceAbstract). If the plugin changes the view mode, the change is permanent +// (e.g. switching to the Thumbnails mode remains even after leaving the plugin path). class CSalamanderViewAbstract { public: // -------------- panel ---------------- - // vraci rezim, ve kterem je zobrazen panel (tree/brief/detailed/icons/thumbnails/tiles) - // vraci jednu z hodnot VIEW_MODE_xxxx (rezim Detailed, Types a tri volitelne rezimy jsou - // vsechny VIEW_MODE_DETAILED) + // returns mode in which the panel is displayed (tree/brief/detailed/icons/thumbnails/tiles) + // returns one of the values VIEW_MODE_xxxx (mode Detailed, Types and three optional modes are + // all VIEW_MODE_DETAILED) virtual DWORD WINAPI GetViewMode() = 0; - // Nastavi rezim panelu na 'viewMode'. Pokud jde o nektery z detailed rezimu, muze - // odstranit nektere ze standardnich sloupcu (viz. 'validData'). Proto je vhodne tuto - // funkci volat jako prvni - pred ostatnimi funkcemi z toho ifacu, ktere modifikuji - // sloupce. + // set the panel mode to 'viewMode'. If it is one of the detailed modes, it can remove some of + // the standard columns (see 'validData'). Therefore, it is appropriate to call this function + // first - before other functions from this interface that modify columns. // - // 'viewMode' je jedna z hodnot VIEW_MODE_xxxx - // Rezim panelu nelze zmenit ani na Types ani na jeden ze tri volitelnych detailed rezimu - // (vsechny zastupuje konstanta VIEW_MODE_DETAILED pouzita pro Detailed rezim panelu). - // Ovsem pokud je zrovna jeden z techto ctyr rezimu v panelu zvoleny a 'viewMode' je - // VIEW_MODE_DETAILED, zustane tento rezim zvoleny (aneb neprepne se na Detailed rezim). - // Zmena rezimu panelu je trvala (pretrva i po opusteni pluginove cesty). + // 'viewMode' is one of the values VIEW_MODE_xxxx + // The panel mode cannot be changed to Types or one of the three optional detailed modes + // (all are represented by the constant VIEW_MODE_DETAILED used in the Detailed mode of the panel). + // However, if one of these four modes is currently selected in the panel and 'viewMode' is + // VIEW_MODE_DETAILED, this mode remains selected (or in other words, it does not switch to + // the Detailed mode). + // Changing the panel mode is permanent (it persists even after leaving the plugin path). // - // 'validData' informuje o tom, jaka data si plugin preje zobrazit v detailed rezimu, hodnota - // se ANDuje s maskou platnych dat zadanou pomoci CSalamanderDirectoryAbstract::SetValidData - // (nema smysl zobrazovat sloupce s "nulovanymi" hodnotami). + // 'validData' informs about what data the plugin wants to display in the detailed mode, the value + // is ANDed with the mask of valid data specified by CSalamanderDirectoryAbstract::SetValidData + // (it does not make sense to display columns with "zeroed" values). virtual void WINAPI SetViewMode(DWORD viewMode, DWORD validData) = 0; - // Vyzvedne ze Salamandera umisteni promennych, ktere nahrazuji parametry callbacku - // CColumn::GetText. Na strane Salamandera se jedna o globalni promenne. Plugin si - // ukazatele na ne ulozi do vlastnich globalnich promennych. + // Get locations of variables from Salamander that replace callback parameters + // CColumn::GetText. On the Salamander side, these are global variables. The plugin + // saves pointers to them in its own global variables. // - // promenne: - // transferFileData [IN] data, na jejichz zaklade se ma vykreslit polozka - // transferIsDir [IN] rovno 0, pokud jde o soubor (lezi v poli Files), - // rovno 1, pokud jde o adresar (lezi v poli Dirs), - // rovno 2, pokud jde o up-dir symbol - // transferBuffer [OUT] sem se nalejou data, maximalne TRANSFER_BUFFER_MAX znaku - // neni treba je terminovat nulou - // transferLen [OUT] pred navratem z callbacku se do teto promenne nastavi - // pocet naplnenych znaku bez terminatoru (terminator neni - // treba do bufferu zapisovat) - // transferRowData [IN/OUT] ukazuje na DWORD, ktery je vzdy pred kreslenim sloupcu - // pro kazdy radek nulovan; lze pouzit pro optimalizace - // Salamander ma vyhrazene bity 0x00000001 az 0x00000008. - // Ostatni bity jsou k dispozici pro plugin. - // transferPluginDataIface [IN] plugin-data-interface panelu, do ktereho se polozka - // vykresluje (patri k (*transferFileData)->PluginData) - // transferActCustomData [IN] CustomData sloupce, pro ktery se ziskava text (pro ktery - // se vola callback) + // variables: + // transferFileData [IN] data based on which the item is to be drawn + // transferIsDir [IN] equal to 0 if it is a file (it is in the array Files), + // equal to 1 if it is a directory (it is in the array Dirs), + // equal to 2 if it is an up-dir symbol + // transferBuffer [OUT] data are poured into this buffer, maximum TRANSFER_BUFFER_MAX characters + // it is not necessary to terminate them with a zero + // transferLen [OUT] before returning from the callback, the number of filled characters + // without a terminator is set in this variable (the terminator does not + // need to be written to the buffer) + // transferRowData [IN/OUT] points to DWORD, which is always zeroed before drawing columns + // for each row; can be used for optimizations + // Salamander has reserved bits 0x00000001 to 0x00000008. + // Other bits are available for the plugin. + // transferPluginDataIface [IN] plugin-data-interface of the panel to which the item is drawn + // (belongs to (*transferFileData)->PluginData) + // transferActCustomData [IN] CustomData of the column for which the text is obtained (for which + // the callback is called) virtual void WINAPI GetTransferVariables(const CFileData**& transferFileData, int*& transferIsDir, char*& transferBuffer, @@ -592,49 +584,47 @@ class CSalamanderViewAbstract CPluginDataInterfaceAbstract**& transferPluginDataIface, DWORD*& transferActCustomData) = 0; - // jen pro FS s vlastnimi ikonami (pitFromPlugin): - // Nastavi callback pro ziskani indexu jednoduchych ikon (viz - // CPluginDataInterfaceAbstract::GetSimplePluginIcons). Pokud tento callback - // plugin nenastavi, bude se vykreslovat vzdy jen ikona z indexu 0. - // Z globalnich promennych callback vyuziva jen TransferFileData a TransferIsDir. + // for FS with custom icons only (pitFromPlugin): + // Sets callback for getting index of simple icons (see CPluginDataInterfaceAbstract::GetSimplePluginIcons). + // If this callback is not set by the plugin, only icon from index 0 will be drawn. + // Only TransferFileData and TransferIsDir are used from the global variables. virtual void WINAPI SetPluginSimpleIconCallback(FGetPluginIconIndex callback) = 0; // ------------- columns --------------- - // vraci pocet sloupcu v panelu (vzdy minimalne jeden, protoze nazev bude vzdy zobrazen) + // returns the number of columns in the panel (always at least one, because the column "Name" is always displayed) virtual int WINAPI GetColumnsCount() = 0; - // vraci ukazatel na sloupec (pouze pro cteni) - // 'index' udava, ktery ze sloupcu bude vracen; pokud sloupec 'index' neexistuje, vraci NULL + // returns a pointer to the column (read-only) + // 'index' specifies which of the columns will be returned; if the column 'index' does not exist, NULL is returned virtual const CColumn* WINAPI GetColumn(int index) = 0; - // Vlozi sloupec na pozici 'index'. Na pozici 0 je vzdy umisten sloupec Name, - // pokud je zobrazen sloupec Ext, bude na pozici 1. Jinak lze sloupec umistit - // libovolne. Struktura 'column' bude prekopirovana do vnitrnich struktur - // Salamandera. Vraci TRUE pokud byl sloupec vlozen. + // returns column to the position 'index'. The column Name is always placed at position 0, + // if the column Ext is displayed, it will be at position 1. Otherwise, the column can be placed + // anywhere. The structure 'column' will be copied to the Salamander internal structures. + // Returns TRUE if the column was inserted. virtual BOOL WINAPI InsertColumn(int index, const CColumn* column) = 0; - // Vlozi standardni sloupec s ID 'id' na pozici 'index'. Na pozici 0 je vzdy - // umisten sloupec Name, pokud je vkladan sloupec Ext, musi to byt na pozici 1. - // Jinak lze sloupec umistit libovolne. 'id' je jedna z hodnot COLUMN_ID_xxxx, - // mimo COLUMN_ID_CUSTOM a COLUMN_ID_NAME. + // inserts the standard column with ID 'id' at position 'index'. The column Name is always placed + // at position 0, if the column Ext is inserted, it must be at position 1. Otherwise, the column + // can be placed anywhere. 'id' is one of the values COLUMN_ID_xxxx, except COLUMN_ID_CUSTOM and + // COLUMN_ID_NAME. virtual BOOL WINAPI InsertStandardColumn(int index, DWORD id) = 0; - // Nastavi nazev a popis sloupce (nesmi byt prazdne retezce ani NULL). Delky - // retezu se omezi na COLUMN_NAME_MAX a COLUMN_DESCRIPTION_MAX. Vraci uspech. - // POZOR: Jmeno a popis sloupce "Name" muzou obsahovat (vzdy za prvnim - // null-terminatorem) i jmeno a popis sloupce "Ext" - toto nastava pokud - // neexistuje samostatny sloupec "Ext" a v datech panelu (viz - // CSalamanderDirectoryAbstract::SetValidData()) se nastavi VALID_DATA_EXTENSION. - // V tomto pripade je potreba nastavovat dvojite retezce (s dvoumi - // null-terminatory) - viz CSalamanderGeneralAbstract::AddStrToStr(). + // sets the name and description of the column (cannot be empty strings or NULL). The length of + // the string is limited to COLUMN_NAME_MAX and COLUMN_DESCRIPTION_MAX. Returns success. + // CAUTION: The name and description of the column "Name" may contain (always after the first + // null-terminator) also the name and description of the column "Ext" - this happens if there is + // no separate column "Ext" and in the data of the panel (see CSalamanderDirectoryAbstract::SetValidData()) + // VALID_DATA_EXTENSION is set. In this case, it is necessary to set double strings (with two + // null-terminators) - see CSalamanderGeneralAbstract::AddStrToStr(). virtual BOOL WINAPI SetColumnName(int index, const char* name, const char* description) = 0; - // Odstrani sloupec na pozici 'index'. Lze odstranit jak sloupce pridane pluginem, - // tak standardni sloupce Salamandera. Nelze odstranit sloupec 'Name', ktery je vzdy - // na indexu 0. Pozor pri odstranovani sloupce 'Ext', pokud je v datech pluginu - // (viz CSalamanderDirectoryAbstract::SetValidData()) VALID_DATA_EXTENSION, musi - // se jmeno+popis sloupce 'Ext' objevit u sloupce 'Name'. + // removes column at position 'index'. It is possible to remove both columns added by the plugin + // and standard columns provided by Salamander. The column 'Name' cannot be removed, it is always + // at position 0. Be careful when removing the column 'Ext', if the plugin data (see + // CSalamanderDirectoryAbstract::SetValidData()) VALID_DATA_EXTENSION is set, the column 'Ext' + // must be displayed in the column 'Name'. virtual BOOL WINAPI DeleteColumn(int index) = 0; }; @@ -642,184 +632,184 @@ class CSalamanderViewAbstract // **************************************************************************** // CPluginDataInterfaceAbstract // -// sada metod pluginu, ktere potrebuje Salamander pro ziskani specifickych dat -// pluginu do pluginem pridanych sloupcu (pracuje s CFileData::PluginData) +// set of plugin methods which are needed by Salamander to get specific data of the plugin +// into the columns added by the plugin (works with CFileData::PluginData) class CPluginInterfaceAbstract; class CPluginDataInterfaceAbstract { #ifdef INSIDE_SALAMANDER -private: // ochrana proti nespravnemu primemu volani metod (viz CPluginDataInterfaceEncapsulation) +private: // protection against incorrect calling of methods (see CPluginDataInterfaceEncapsulation) friend class CPluginDataInterfaceEncapsulation; #else // INSIDE_SALAMANDER public: #endif // INSIDE_SALAMANDER - // vraci TRUE pokud se ma zavolat metoda ReleasePluginData pro vsechny soubory vazane - // k tomuto interfacu, jinak vraci FALSE + // returns TRUE if the method ReleasePluginData is about to be called for all files related + // to this interface, otherwise return FALSE virtual BOOL WINAPI CallReleaseForFiles() = 0; - // vraci TRUE pokud se ma zavolat metoda ReleasePluginData pro vsechny adresare vazane - // k tomuto interfacu, jinak vraci FALSE + // returns TRUE if the method ReleasePluginData is about to be called for all directories related + // to this interface, otherwise return FALSE virtual BOOL WINAPI CallReleaseForDirs() = 0; - // uvolni data specificka pluginu (CFileData::PluginData) pro 'file' (soubor nebo - // adresar - 'isDir' FALSE nebo TRUE; struktura vlozena do CSalamanderDirectoryAbstract - // pri listovani archivu nebo FS); vola se pro vsechny soubory, pokud CallReleaseForFiles - // vrati TRUE, a pro vsechny adresare, pokud CallReleaseForDirs vrati TRUE + // releeases data specific to the plugin (CFileData::PluginData) for 'file' (file or directory - + // 'isDir' FALSE or TRUE; structure inserted into CSalamanderDirectoryAbstract when listing archives + // or FS); called for all files if CallReleaseForFiles returns TRUE, and for all directories if + // CallReleaseForDirs returns TRUE virtual void WINAPI ReleasePluginData(CFileData& file, BOOL isDir) = 0; - // jen pro data archivu (pro FS se nedoplnuje up-dir symbol): - // pozmenuje navrhovany obsah up-dir symbolu (".." nahore v panelu); 'archivePath' - // je cesta v archivu, pro kterou je symbol urcen; v 'upDir' vstupuji navrzena - // data symbolu: jmeno ".." (nemenit), date&time archivu, zbytek nulovany; - // v 'upDir' vystupuji zmeny pluginu, predevsim by mel zmenit 'upDir.PluginData', - // ktery bude vyuzivan na up-dir symbolu pri ziskavani obsahu pridanych sloupcu; - // pro 'upDir' se nebude volat ReleasePluginData, jakekoliv potrebne uvolnovani - // je mozne provest vzdy pri dalsim volani GetFileDataForUpDir nebo pri uvolneni - // celeho interfacu (v jeho destruktoru - volan z - // CPluginInterfaceAbstract::ReleasePluginDataInterface) + // for archive data only (for FS, the up-dir symbol is not added): + // modified the suggested content of the up-dir symbol (".." at the top of the panel); 'archivePath' + // is the path in the archive for which the symbol is intended; the proposed data of the symbol + // are entered in 'upDir': the name ".." (do not change), date&time of the archive, the rest is + // zeroed; the changes of the plugin are entered in 'upDir', especially 'upDir.PluginData', which + // will be used for the up-dir symbol when getting the content of the added columns; + // for 'upDir', ReleasePluginData will not be called, any necessary release can be performed + // either when calling GetFileDataForUpDir again or when releasing the entire interface (in its + // destructor - called from CPluginInterfaceAbstract::ReleasePluginDataInterface) virtual void WINAPI GetFileDataForUpDir(const char* archivePath, CFileData& upDir) = 0; - // jen pro data archivu (FS pouziva jen root cestu v CSalamanderDirectoryAbstract): - // pri pridavani souboru/adresare do CSalamanderDirectoryAbstract se muze stat, ze - // zadana cesta neexistuje a je ji tedy potreba vytvorit, jednotlive adresare teto - // cesty se tvori automaticky a tato metoda umoznuje pluginu pridat sva specificka - // data (pro sve sloupce) k temto vytvarenym adresarum; 'dirName' je plna cesta - // pridavaneho adresare v archivu; v 'dir' vstupuji navrhovana data: jmeno adresare - // (alokovane na heapu Salamandera), date&time prevzaty od pridavaneho souboru/adresare, - // zbytek nulovany; v 'dir' vystupuji zmeny pluginu, predevsim by mel zmenit - // 'dir.PluginData'; vraci TRUE pokud se pridani dat pluginu povedlo, jinak FALSE; - // pokud vrati TRUE, bude 'dir' uvolnen klasickou cestou (Salamanderovska cast + - // ReleasePluginData) a to bud az pri kompletnim uvolneni listingu nebo jeste behem - // jeho tvorby v pripade, ze bude ten samy adresar pridan pomoci - // CSalamanderDirectoryAbstract::AddDir (premazani automatickeho vytvoreni pozdejsim - // normalnim pridanim); pokud vrati FALSE, bude z 'dir' uvolnena jen Salamanderovska cast + // for archive data only (FS uses only root path in CSalamanderDirectoryAbstract): + // when adding a file or directory to CsalamanderDirectoryAbstract, it may happen that the specified + // path does not exist and it is therefore necessary to create it, the individual directories of this + // path are created automatically and this method allows the plugin to add its specific data (for its + // columns) to these created directories; 'dirName' is the full path of the added directory in the + // archive; the proposed data of the directory are entered in 'dir': the name of the directory + // (allocated on the heap of Salamander), date&time taken from the added file/directory, the rest + // is zeroed; the changes of the plugin are entered in 'dir', especially 'dir.PluginData'; returns + // TRUE if adding the plugin data was successful, otherwise FALSE; if it returns TRUE, 'dir' will + // be released in the standard way (Salamander part + ReleasePluginData) and either when releasing + // the entire listing or still during its creation in case the same directory is added using + // CSalamanderDirectoryAbstract::AddDir (overwriting the automatic creation by later normal addition); + // if it returns FALSE, only the Salamander part of 'dir' will be released virtual BOOL WINAPI GetFileDataForNewDir(const char* dirName, CFileData& dir) = 0; - // jen pro FS s vlastnimi ikonami (pitFromPlugin): - // vraci image-list s jednoduchymi ikonami, behem kresleni polozek v panelu se - // pomoci call-backu ziskava icon-index do tohoto image-listu; vola se vzdy po - // ziskani noveho listingu (po volani CPluginFSInterfaceAbstract::ListCurrentPath), - // takze je mozne image-list predelavat pro kazdy novy listing; - // 'iconSize' urcuje pozadovanou velikost ikon a jde o jednu z hodnot SALICONSIZE_xxx - // destrukci image-listu si plugin zajisti pri dalsim volani GetSimplePluginIcons - // nebo pri uvolneni celeho interfacu (v jeho destruktoru - volan z + // for FS with custom icons only (pitFromPlugin): + // returns image-list with simple icons, during drawing items in the panel, the icon-index + // into this image-list is obtained using a call-back; it is called only after getting a new + // listing (after calling CPluginFSInterfaceAbstract::ListCurrentPath), so it is possible to + // modify the image-list for each new listing; + // 'iconSize' specifies the required size of the icons and is one of the values SALICONSIZE_xxx + // the plugin will take care of destroying the image-list when calling GetSimplePluginIcons again + // or when releasing the entire interface (in its destructor - called from // CPluginInterfaceAbstract::ReleasePluginDataInterface) - // pokud image-list nelze vytvorit, vraci NULL a aktualni plugin-icons-type - // degraduje na pitSimple + // if the image-list cannot be created, it returns NULL and the current plugin-icons-type + // degrades to pitSimple virtual HIMAGELIST WINAPI GetSimplePluginIcons(int iconSize) = 0; - // jen pro FS s vlastnimi ikonami (pitFromPlugin): - // vraci TRUE, pokud pro dany soubor/adresar ('isDir' FALSE/TRUE) 'file' - // ma byt pouzita jednoducha ikona; vraci FALSE, pokud se ma pro ziskani ikony volat - // z threadu pro nacitani ikon metoda GetPluginIcon (nacteni ikony "na pozadi"); - // zaroven v teto metode muze byt predpocitan icon-index pro jednoduchou ikonu - // (u ikon ctenych "na pozadi" se az do okamziku nacteni pouzivaji take jednoduche - // ikony) a ulozen do CFileData (nejspise do CFileData::PluginData); - // omezeni: z CSalamanderGeneralAbstract je mozne pouzivat jen metody, ktere lze - // volat z libovolneho threadu (metody nezavisle na stavu panelu) + // for FS with custom icons only (pitFromPlugin): + // returns TRUE, if a simple icon for the file/directory ('isDir' FALSE/TRUE) 'file' should be + // used; returns FALSE, if the icon should be obtained by calling the method GetPluginIcon + // from the thread for loading icons (loading icons "in the background"); + // at the same time, the icon-index for a simple icon (for icons loaded "in the background", + // simple icons are used until the icon is loaded) can be pre-calculated in this method + // and saved in CFileData (most likely in CFileData::PluginData); + // limitation: only methods that can be called from any thread (methods independent of the + // panel state) can be used from CSalamanderGeneralAbstract virtual BOOL WINAPI HasSimplePluginIcon(CFileData& file, BOOL isDir) = 0; - // jen pro FS s vlastnimi ikonami (pitFromPlugin): - // vraci ikonu pro soubor nebo adresar 'file' nebo NULL pokud ikona nelze ziskat; vraci-li - // v 'destroyIcon' TRUE, vola se pro uvolneni vracene ikony Win32 API funkce DestroyIcon; - // 'iconSize' urcuje velikost pozadovane ikony a jde o jednu z hodnot SALICONSIZE_xxx - // omezeni: jelikoz se vola z threadu pro nacitani ikon (neni to hlavni thread), lze z - // CSalamanderGeneralAbstract pouzivat jen metody, ktere lze volat z libovolneho threadu + // for FS with custom icons only (pitFromPlugin): + // returns icon for the file/directory or NULL if the icon cannot be obtained; if + // 'destroyIcon' is TRUE, the Win32 API function DestroyIcon is called to release the icon; + // 'iconSize' specifies the required size of the icon and is one of the values SALICONSIZE_xxx + // limitation: since it is called from the thread for loading icons (it is not the main thread), + // you can use only methods from CSalamanderGeneralAbstract that can be called from any thread virtual HICON WINAPI GetPluginIcon(const CFileData* file, int iconSize, BOOL& destroyIcon) = 0; - // jen pro FS s vlastnimi ikonami (pitFromPlugin): - // porovna 'file1' (muze jit o soubor i adresar) a 'file2' (muze jit o soubor i adresar), - // nesmi pro zadne dve polozky listingu vratit, ze jsou shodne (zajistuje jednoznacne - // prirazeni vlastni ikony k souboru/adresari); pokud nehrozi duplicitni jmena v listingu - // cesty (obvykly pripad), lze jednoduse implementovat jako: + // for FS with custom icons only (pitFromPlugin): + // compares 'file1' (can be a file or directory) and 'file2' (can be a file or directory), + // must not return that two listing items are the same (ensures unambiguous assignment of + // a custom icon to a file/directory); if there is no risk of duplicate names in the listing + // paths (usual case), it can be easily implemented as: // {return strcmp(file1->Name, file2->Name);} - // vraci cislo mensi nez nula pokud 'file1' < 'file2', nulu pokud 'file1' == 'file2' a - // cislo vetsi nez nula pokud 'file1' > 'file2'; - // omezeni: jelikoz se vola i z threadu pro nacitani ikon (nejen z hlavniho threadu), lze - // z CSalamanderGeneralAbstract pouzivat jen metody, ktere lze volat z libovolneho threadu + // returns a number less than zero if 'file1' < 'file2', zero if 'file1' == 'file2' and + // a number greater than zero if 'file1' > 'file2'; + // limitation: since it is called from the thread for loading icons (it is not the main thread), + // you can use only methods from CSalamanderGeneralAbstract that can be called from any thread virtual int WINAPI CompareFilesFromFS(const CFileData* file1, const CFileData* file2) = 0; - // slouzi k nastaveni parametru pohledu, tato metoda je zavolana vzdy pred zobrazenim noveho - // obsahu panelu (pri zmene cesty) a pri zmene aktualniho pohledu (i rucni zmena sirky - // sloupce); 'leftPanel' je TRUE pokud jde o levy panel (FALSE pokud jde o pravy panel); - // 'view' je interface pro modifikaci pohledu (nastaveni rezimu, prace se - // sloupci); jde-li o data archivu, obsahuje 'archivePath' soucasnou cestu v archivu, - // pro data FS je 'archivePath' NULL; jde-li o data archivu, je 'upperDir' ukazatel na - // nadrazeny adresar (je-li soucasna cesta root archivu, je 'upperDir' NULL), pro data - // FS je vzdy NULL; - // POZOR: behem volani teto metody nesmi dojit k prekresleni panelu (muze se zde zmenit - // velikost ikon, atd.), takze zadne messageloopy (zadne dialogy, atd.)! - // omezeni: z CSalamanderGeneralAbstract je mozne pouzivat jen metody, ktere lze - // volat z libovolneho threadu (metody nezavisle na stavu panelu) + // used to set the view parameter, this method is called before displaying new content + // of the panel (when changing the path) and when changing the current view (also when + // manually changing the width of the column); 'leftPanel' is TRUE if it is the left panel + // (FALSE if it is the right panel); 'view' is an interface for modifying the view + // (setting the mode, working with columns); if it is archive data, 'archivePath' contains + // the current path in the archive, for FS data it is NULL; if it is archive data, 'upperDir' + // is a pointer to the parent directory (if the current path is the root of the archive, + // 'upperDir' is NULL), for FS data it is always NULL; + // CAUTION: during the call to this method, the panel must not be repainted (the size of + // the icons, etc. may change here), so no message loops (no dialogs, etc.)! + // limitation: only methods that can be called from any thread (methods independent of the + // panel state) can be used from CSalamanderGeneralAbstract virtual void WINAPI SetupView(BOOL leftPanel, CSalamanderViewAbstract* view, const char* archivePath, const CFileData* upperDir) = 0; - // nastaveni nove hodnoty "column->FixedWidth" - uzivatel pouzil kontextove menu - // na pluginem pridanem sloupci v header-line > "Automatic Column Width"; plugin - // by si mel ulozit novou hodnotu column->FixedWidth ulozenou v 'newFixedWidth' - // (je to vzdy negace column->FixedWidth), aby pri nasledujicich volanich SetupView() mohl - // sloupec pridat uz se spravne nastavenou FixedWidth; zaroven pokud se zapina pevna - // sirka sloupce, mel by si plugin nastavit soucasnou hodnotu "column->Width" (aby - // se timto zapnutim pevne sirky nezmenila sirka sloupce) - idealni je zavolat - // "ColumnWidthWasChanged(leftPanel, column, column->Width)"; 'column' identifikuje - // sloupec, ktery se ma zmenit; 'leftPanel' je TRUE pokud jde o sloupec z leveho - // panelu (FALSE pokud jde o sloupec z praveho panelu) + // setting new value "column->FixedWidth" - the user used the context menu on the column + // added by the plugin in the header-line > "Automatic Column Width"; the plugin should + // save the new value of column->FixedWidth stored in 'newFixedWidth' (it is always the + // negation of column->FixedWidth), so that when calling SetupView() again, the column + // can be added with the correct FixedWidth; at the same time, if the fixed width of the + // column is turned on, the plugin should set the current value of "column->Width" (so + // that the width of the column does not change when turning on this fixed width) - the + // ideal is to call "ColumnWidthWasChanged(leftPanel, column, column->Width)"; 'column' + // identifies the column to be changed; 'leftPanel' is TRUE if it is a column from the + // left panel (FALSE if it is a column from the right panel) virtual void WINAPI ColumnFixedWidthShouldChange(BOOL leftPanel, const CColumn* column, int newFixedWidth) = 0; - // nastaveni nove hodnoty "column->Width" - uzivatel mysi zmenil sirku pluginem pridaneho - // sloupce v header-line; plugin by si mel ulozit novou hodnotu column->Width (je ulozena - // i v 'newWidth'), aby pri nasledujicich volanich SetupView() mohl sloupec pridat uz se - // spravne nastavenou Width; 'column' identifikuje sloupec, ktery se zmenil; 'leftPanel' - // je TRUE pokud jde o sloupec z leveho panelu (FALSE pokud jde o sloupec z praveho panelu) + // setting new value "column->Width" - the user changed the width of the column added + // by the plugin in the header-line by the mouse; the plugin should save the new value + // of column->Width stored in 'newWidth', so that when calling SetupView() again, the + // column can be added with the correct Width; 'column' identifies the column that has + // changed; 'leftPanel' is TRUE if it is a column from the left panel (FALSE if it is + // a column from the right panel) virtual void WINAPI ColumnWidthWasChanged(BOOL leftPanel, const CColumn* column, int newWidth) = 0; - // ziska obsah Information Line pro soubor/adresar ('isDir' TRUE/FALSE) 'file' - // nebo oznacene soubory a adresare ('file' je NULL a pocty oznacenych souboru/adresaru - // jsou v 'selectedFiles'/'selectedDirs') v panelu ('panel' je jeden z PANEL_XXX); - // vola se i pri prazdnem listingu (tyka se jen FS, u archivu nemuze nastat, 'file' je NULL, - // 'selectedFiles' a 'selectedDirs' jsou 0); je-li 'displaySize' TRUE, je znama velikost - // vsech oznacenych adresaru (viz CFileData::SizeValid; pokud neni nic oznaceneho, je zde - // TRUE); v 'selectedSize' je soucet cisel CFileData::Size oznacenych souboru a adresaru - // (pokud neni nic oznaceneho, je zde nula); 'buffer' je buffer pro vraceny text (velikost - // 1000 bytu); 'hotTexts' je pole (velikost 100 DWORDu), ve kterem se vraci informace o poloze - // hot-textu, vzdy spodni WORD obsahuje pozici hot-textu v 'buffer', horni WORD obsahuje - // delku hot-textu; v 'hotTextsCount' je velikost pole 'hotTexts' (100) a vraci se v nem pocet - // zapsanych hot-textu v poli 'hotTexts'; vraci TRUE pokud je 'buffer' + 'hotTexts' + - // 'hotTextsCount' nastaveno, vraci FALSE pokud se ma Information Line plnit standardnim - // zpusobem (jako na disku) + // gets the content of Information Line for the file/directory ('isDir' TRUE/FALSE) 'file' + // or the selected files and directories ('file' is NULL and the number of selected files + // and directories are in 'selectedFiles'/'selectedDirs') in the panel ('panel' is one of + // PANEL_XXX); it is also called when the listing is empty (it only applies to FS, it cannot + // occur for archives, 'file' is NULL, 'selectedFiles' and 'selectedDirs' are 0); if 'displaySize' + // is TRUE, the size of all selected directories is known (see CFileData::SizeValid; if nothing + // is selected, it is TRUE); the sum of the numbers CFileData::Size of the selected files and + // directories is in 'selectedSize' (if nothing is selected, it is zero); 'buffer' is a buffer + // for the returned text (size 1000 bytes); 'hotTexts' is an array (size 100 DWORDs), in which + // information about the position of the hot-text is returned, the lower WORD always contains + // the position of the hot-text in 'buffer', the upper WORD contains the length of the hot-text; + // 'hotTextsCount' is the size of the 'hotTexts' array (100) and returns the number of written + // hot-texts in the 'hotTexts' array; returns TRUE if 'buffer' + 'hotTexts' + 'hotTextsCount' + // is set, returns FALSE if the Information Line is to be filled in the standard way (as on disk) virtual BOOL WINAPI GetInfoLineContent(int panel, const CFileData* file, BOOL isDir, int selectedFiles, int selectedDirs, BOOL displaySize, const CQuadWord& selectedSize, char* buffer, DWORD* hotTexts, int& hotTextsCount) = 0; - // jen pro archivy: uzivatel ulozil soubory/adresare z archivu na clipboard, ted zavira - // archiv v panelu: pokud metoda vrati TRUE, tento objekt zustane otevreny (optimalizace - // pripadneho Paste z clipboardu - archiv uz je vylistovany), pokud metoda vrati FALSE, - // tento objekt se uvolni (pripadny Paste z clipboardu zpusobi listovani archivu, pak - // teprve dojde k vybaleni vybranych souboru/adresaru); POZNAMKA: pokud je po zivotnost - // objektu otevreny soubor archivu, metoda by mela vracet FALSE, jinak bude po celou - // dobu "pobytu" dat na clipboardu soubor archivu otevreny (nepujde smazat, atd.) + // for archives only: user stored files/directories from the archive to the clipboard, now + // the archive in the panel is being closed: if the method returns TRUE, the archive will + // remain open (optimization of possible Paste from the clipboard - the archive is already + // listed), if the method returns FALSE, the object will be released (possible Paste from + // the clipboard will cause listing of the archive, then the selected files/directories + // will be unpacked); NOTE: if the file of the archive is open during the lifetime of the + // object, the method should return FALSE, otherwise the file of the archive will remain + // open for the entire "stay" of the data on the clipboard (cannot be deleted, etc.) virtual BOOL WINAPI CanBeCopiedToClipboard() = 0; - // jen pri zadani VALID_DATA_PL_SIZE do CSalamanderDirectoryAbstract::SetValidData(): - // vraci TRUE pokud je velikost souboru/adresare ('isDir' TRUE/FALSE) 'file' znama, - // jinak vraci FALSE; velikost vraci v 'size' + // only when entering VALID_DATA_PL_SIZE into CSalamanderDirectoryAbstract::SetValidData(): + // returns TRUE if the size of the file/directory ('isDir' TRUE/FALSE) 'file' is known, + // otherwise returns FALSE; the size is returned in 'size' virtual BOOL WINAPI GetByteSize(const CFileData* file, BOOL isDir, CQuadWord* size) = 0; - // jen pri zadani VALID_DATA_PL_DATE do CSalamanderDirectoryAbstract::SetValidData(): - // vraci TRUE pokud je datum souboru/adresare ('isDir' TRUE/FALSE) 'file' znamy, - // jinak vraci FALSE; datum vraci v "datumove" casti struktury 'date' ("casova" cast - // by mela zustat netknuta) + // only when entering VALID_DATA_PL_DATE into CSalamanderDirectoryAbstract::SetValidData(): + // returns TRUE if the date of the file/directory ('isDir' TRUE/FALSE) 'file' is known, + // otherwise returns FALSE; the date is returned in 'date' part of the 'date' structure + // ("time" part of the structure should remain untouched) virtual BOOL WINAPI GetLastWriteDate(const CFileData* file, BOOL isDir, SYSTEMTIME* date) = 0; - // jen pri zadani VALID_DATA_PL_TIME do CSalamanderDirectoryAbstract::SetValidData(): - // vraci TRUE pokud je cas souboru/adresare ('isDir' TRUE/FALSE) 'file' znamy, - // jinak vraci FALSE; cas vraci v "casove" casti struktury 'time' ("datumova" cast - // by mela zustat netknuta) + // only when entering VALID_DATA_PL_TIME into CSalamanderDirectoryAbstract::SetValidData(): + // returns TRUE if the time of the file/directory ('isDir' TRUE/FALSE) 'file' is known, + // otherwise returns FALSE; the time is returned in 'time' part of the 'time' structure + // ("date" part of the structure should remain untouched) virtual BOOL WINAPI GetLastWriteTime(const CFileData* file, BOOL isDir, SYSTEMTIME* time) = 0; }; @@ -827,57 +817,57 @@ class CPluginDataInterfaceAbstract // **************************************************************************** // CSalamanderForOperationsAbstract // -// sada metod ze Salamandera pro podporu provadeni operaci, platnost interfacu je -// omezena na metodu, ktere je interface predan jako parametr; tedy lze volat pouze -// z tohoto threadu a v teto metode (objekt je na stacku, takze po navratu zanika) +// set of Salamander methods for supporting the execution of operations, the validity of the interface is +// limited to the method that is passed as a parameter; therefore, it can only be called from this thread +// and in this method (the object is on the stack, so it disappears after returning) class CSalamanderForOperationsAbstract { public: - // PROGRESS DIALOG: dialog obsahuje jeden/dva ('twoProgressBars' FALSE/TRUE) progress-metry - // otevre progress-dialog s titulkem 'title'; 'parent' je parent okno progress-dialogu (je-li - // NULL, pouzije se hlavni okno); pokud obsahuje jen jeden progress-metr, muze byt popsan - // jako "File" ('fileProgress' je TRUE) nebo "Total" ('fileProgress' je FALSE) + // PROGRESS DIALOG: the dialog contains one/two ('twoProgressBars' FALSE/TRUE) progress meters + // opens a progress dialog with the title 'title'; 'parent' is the parent window of the progress + // dialog (if NULL, the main window is used); if it contains only one progress meter, it can be + // described as "File" ('fileProgress' is TRUE) or "Total" ('fileProgress' is FALSE) // - // dialog nebezi ve vlastnim threadu; pro jeho fungovani (tlacitko Cancel + vnitrni timer) - // je treba obcas vyprazdni message queue; to zajistuji metody ProgressDialogAddText, - // ProgressAddSize a ProgressSetSize + // the dialog does not run in its own thread; for its functioning (Cancel button + internal timer) + // it is necessary to occasionally empty the message queue; this is ensured by the methods + // ProgressDialogAddText, ProgressAddSize and ProgressSetSize // - // protoze real-time zobrazovani textu a zmen v progress bare silne zdrzuje, maji - // metody ProgressDialogAddText, ProgressAddSize a ProgressSetSize parametr - // 'delayedPaint'; ten by mel byt TRUE pro vsechny rychle se menici texty a hodnoty; - // metody si pak ulozi texty a zobrazi je az po doruceni vnitrniho timeru dialogu; - // 'delayedPaint' nastavime na FALSE pro inicializacni/koncove texty typu "preparing data..." - // nebo "canceling operation...", po jejiz zobrazeni nedame dialogu prilezitost k distribuci - // zprav (timeru); pokud je u takove operace pravdepodobne, ze bude trvat dlouho, meli - // bychom behem teto doby dialog "obcerstvovat" volanim ProgressAddSize(CQuadWord(0, 0), TRUE) - // a podle jeji navratove hodnoty akci pripadne predcasne ukoncit + // because real-time display of text and changes in progress bars is very slow, the methods + // ProgressDialogAddText, ProgressAddSize and ProgressSetSize have the parameter 'delayedPaint'; + // it should be TRUE for all quickly changing texts and values; the methods then save the texts + // and display them only after the internal timer of the dialog is delivered; + // 'delayedPaint' should be set to FALSE for initialization/ending texts such as "preparing data..." + // or "canceling operation..."; after displaying them, we do not give the dialog a chance to + // distribute messages (timers); if such an operation is likely to take a long time, we should + // "refresh" the dialog during this time by calling ProgressAddSize(CQuadWord(0, 0), TRUE) and + // depending on its return value, possibly terminate the action prematurely virtual void WINAPI OpenProgressDialog(const char* title, BOOL twoProgressBars, HWND parent, BOOL fileProgress) = 0; - // vypise text 'txt' (i nekolik radku - provadi se rozpad na radky) do progress-dialogu + // prints the text 'txt' (even several lines - the text is broken down into lines) to the progress dialog virtual void WINAPI ProgressDialogAddText(const char* txt, BOOL delayedPaint) = 0; - // neni-li 'totalSize1' CQuadWord(-1, -1), nastavi 'totalSize1' jako 100 procent prvniho progress-metru, - // neni-li 'totalSize2' CQuadWord(-1, -1), nastavi 'totalSize2' jako 100 procent druheho progress-metru - // (pro progress-dialog s jednim progress-metrem je povinne 'totalSize2' CQuadWord(-1, -1)) + // if 'totalSize1' is not CQuadWord(-1, -1), sets 'totalSize1' as 100 percent of the first progress meter, + // if 'totalSize2' is not CQuadWord(-1, -1), sets 'totalSize2' as 100 percent of the second progress meter + // (for a progress dialog with one progress meter, 'totalSize2' CQuadWord(-1, -1) is mandatory) virtual void WINAPI ProgressSetTotalSize(const CQuadWord& totalSize1, const CQuadWord& totalSize2) = 0; - // neni-li 'size1' CQuadWord(-1, -1), nastavi velikost 'size1' (size1/total1*100 procent) na prvnim progress-metru, - // neni-li 'size2' CQuadWord(-1, -1), nastavi velikost 'size2' (size2/total2*100 procent) na druhem progress-metru - // (pro progress-dialog s jednim progress-metrem je povinne 'size2' CQuadWord(-1, -1)), vraci informaci jestli ma - // akce pokracovat (FALSE = konec) + // if 'size1' is not CQuadWord(-1, -1), sets the size 'size1' (size1/total1*100 percent) on the first progress meter, + // if 'size2' is not CQuadWord(-1, -1), sets the size 'size2' (size2/total2*100 percent) on the second progress meter + // (for a progress dialog with one progress meter, 'size2' CQuadWord(-1, -1) is mandatory), returns whether the action + // should continue (FALSE = end) virtual BOOL WINAPI ProgressSetSize(const CQuadWord& size1, const CQuadWord& size2, BOOL delayedPaint) = 0; - // prida (pripadne k oboum progress-metrum) velikost 'size' (size/total*100 procent progressu), - // vraci informaci jestli ma akce pokracovat (FALSE = konec) + // adds (possibly to both progress meters) the size 'size' (size/total*100 percent of the progress) + // returns an information whether the action should continue (FALSE = end) virtual BOOL WINAPI ProgressAddSize(int size, BOOL delayedPaint) = 0; - // enabluje/disabluje tlacitko Cancel + // enables/disables the Cancel button virtual void WINAPI ProgressEnableCancel(BOOL enable) = 0; - // vraci HWND dialogu progressu (hodi se pri vypisu chyb a dotazu pri otevrenem progress-dialogu) + // returns HWND of the progress dialog (useful when displaying errors and queries with an open progress dialog) virtual HWND WINAPI ProgressGetHWND() = 0; - // zavre progress-dialog + // closes the progress dialog virtual void WINAPI CloseProgressDialog() = 0; - // presune vsechny soubory ze 'source' adresare do 'target' adresare, - // navic premapovava predpony zobrazovanych jmen ('remapNameFrom' -> 'remapNameTo') - // vraci uspech operace + // moves all files from 'source' to 'target' directory, + // moreover, it remaps the prefixes of the displayed names ('remapNameFrom' -> 'remapNameTo') + // returns success of the operation virtual BOOL WINAPI MoveFiles(const char* source, const char* target, const char* remapNameFrom, const char* remapNameTo) = 0; }; diff --git a/src/plugins/shared/spl_gen.h b/src/plugins/shared/spl_gen.h index 28c8c00f6..73397fed2 100644 --- a/src/plugins/shared/spl_gen.h +++ b/src/plugins/shared/spl_gen.h @@ -1,5 +1,6 @@ // SPDX-FileCopyrightText: 2023 Open Salamander Authors // SPDX-License-Identifier: GPL-2.0-or-later +// CommentsTranslationProject: TRANSLATED //**************************************************************************** // @@ -12,7 +13,7 @@ #pragma once #ifdef _MSC_VER -#pragma pack(push, enter_include_spl_gen) // aby byly struktury nezavisle na nastavenem zarovnavani +#pragma pack(push, enter_include_spl_gen) // so that the structures are independent of the alignment setting #pragma pack(4) #endif // _MSC_VER #ifdef __BORLANDC__ @@ -26,9 +27,9 @@ class CPluginDataInterfaceAbstract; // **************************************************************************** // CSalamanderGeneralAbstract // -// obecne pouzitelne metody Salamandera (pro vsechny typy pluginu) +// generally usable methods of Salamander (for all types of plugins) -// typy message-boxu +// message-box types #define MSGBOX_INFO 0 #define MSGBOX_ERROR 1 #define MSGBOX_EX_ERROR 2 @@ -37,7 +38,7 @@ class CPluginDataInterfaceAbstract; #define MSGBOX_WARNING 5 #define MSGBOX_EX_WARNING 6 -// konstanty pro CSalamanderGeneralAbstract::SalMessageBoxEx +// CSlamanderGeneralAbstract::SalMessageBoxEx constants #define MSGBOXEX_OK 0x00000000 // MB_OK #define MSGBOXEX_OKCANCEL 0x00000001 // MB_OKCANCEL #define MSGBOXEX_ABORTRETRYIGNORE 0x00000002 // MB_ABORTRETRYIGNORE @@ -63,12 +64,13 @@ class CPluginDataInterfaceAbstract; #define MSGBOXEX_SETFOREGROUND 0x00010000 // MB_SETFOREGROUND (bit mask) // altap specific -#define MSGBOXEX_SILENT 0x10000000 // messagebox nevyda pri otevreni zadny zvuk (bit mask) -// v pripade MB_YESNO messageboxu povoli Escape (generuje IDNO); v MB_ABORTRETRYIGNORE messageboxu -// povoli Escape (generuje IDCANCEL) (bit mask) +#define MSGBOXEX_SILENT 0x10000000 // messsagebox won't play any sound when opened (bit mask) +// in case of MB_YESNO messagebox, it allows Escape (generates IDNO); in case of MB_ABORTRETRYIGNORE +// messagebox, it allows Escape (generates IDCANCEL) (bit mask) #define MSGBOXEX_ESCAPEENABLED 0x20000000 -#define MSGBOXEX_HINT 0x40000000 // pokud se pouziva CheckBoxText, bude v nem vyhledan oddelovac \t a zobrazen jako hint -// Vista: defaultni tlacitko bude mit stav "pozaduje elevaci" (zobrazi se elevated icon) +#define MSGBOXEX_HINT 0x40000000 // if the CheckBoxText is used, it will be searched for +// the \t separator and displayed as a hint +// Vista: the default button will have "requires elevation" state (elevated icon will be displayed) #define MSGBOXEX_SHIELDONDEFBTN 0x80000000 #define MSGBOXEX_TYPEMASK 0x0000000F // MB_TYPEMASK @@ -78,9 +80,9 @@ class CPluginDataInterfaceAbstract; #define MSGBOXEX_MISCMASK 0x0000C000 // MB_MISCMASK #define MSGBOXEX_EXMASK 0xF0000000 -// navratove hodnoty message boxu -#define DIALOG_FAIL 0x00000000 // dialog se nepodarilo otevrit -// jednotliva tlacitka +// message box return values +#define DIALOG_FAIL 0x00000000 // dialog could not be opened +// individual buttons #define DIALOG_OK 0x00000001 // IDOK #define DIALOG_CANCEL 0x00000002 // IDCANCEL #define DIALOG_ABORT 0x00000003 // IDABORT @@ -242,19 +244,19 @@ URLText */ -// identifikace panelu -#define PANEL_SOURCE 1 // zdrojovy panel (aktivni panel) -#define PANEL_TARGET 2 // cilovy panel (neaktivni panel) -#define PANEL_LEFT 3 // levy panel -#define PANEL_RIGHT 4 // pravy panel +// panel identification +#define PANEL_SOURCE 1 // source panel (active panel) +#define PANEL_TARGET 2 // target panel (inactive panel) +#define PANEL_LEFT 3 // left panel +#define PANEL_RIGHT 4 // right panel -// typy cest -#define PATH_TYPE_WINDOWS 1 // windowsova cesta ("c:\path" nebo UNC cesta) -#define PATH_TYPE_ARCHIVE 2 // cesta do archivu (archiv lezi na windowsove ceste) -#define PATH_TYPE_FS 3 // cesta na pluginovy file-system +// types of paths +#define PATH_TYPE_WINDOWS 1 // windows path ("c:\path" or UNC path) +#define PATH_TYPE_ARCHIVE 2 // a path to archive (archive is on windows path) +#define PATH_TYPE_FS 3 // a path to plugin file-system -// Z nasledujici skupiny flagu lze vybrat pouze jeden. -// Definuji sadu zobrazenych tlacitek v ruznych chybovych hlasenich. +// It is possible to choose one of the following flags +// They define a set of buttons displayed in various error messages. #define BUTTONS_OK 0x00000000 // OK #define BUTTONS_RETRYCANCEL 0x00000001 // Retry / Cancel #define BUTTONS_SKIPCANCEL 0x00000002 // Skip / Skip all / Cancel @@ -262,9 +264,9 @@ URLText #define BUTTONS_YESALLSKIPCANCEL 0x00000004 // Yes / All / Skip / Skip all / Cancel #define BUTTONS_YESNOCANCEL 0x00000005 // Yes / No / Cancel #define BUTTONS_YESALLCANCEL 0x00000006 // Yes / All / Cancel -#define BUTTONS_MASK 0x000000FF // interni maska, nepouzivat -// detekci zda kombinace ma tlacitko SKIP nebo YES nechavam zde ve forme inline, aby -// v pripade zavadeni novych kombinaci byla dobre na ocich a nezapomeli jsme ji doplnit +#define BUTTONS_MASK 0x000000FF // internal mask, do not use +// The detection if the combination contains SKIP or YES button is kept here in the inline form, +// so that in case of adding new combinations it is easy to see and not to forget to add it here inline BOOL ButtonsContainsSkip(DWORD btn) { return (btn & BUTTONS_MASK) == BUTTONS_SKIPCANCEL || @@ -278,148 +280,153 @@ inline BOOL ButtonsContainsYes(DWORD btn) (btn & BUTTONS_MASK) == BUTTONS_YESALLCANCEL; } -// chybove konstanty pro CSalamanderGeneralAbstract::SalGetFullName -#define GFN_SERVERNAMEMISSING 1 // v UNC ceste chybi server name -#define GFN_SHARENAMEMISSING 2 // v UNC ceste chybi share name -#define GFN_TOOLONGPATH 3 // operaci by vznikla prilis dlouha cesta -#define GFN_INVALIDDRIVE 4 // u normalni cesty (c:\) neni pismenko A-Z (ani a-z) -#define GFN_INCOMLETEFILENAME 5 // relativni cesta bez zadaneho 'curDir' -> neresitelne -#define GFN_EMPTYNAMENOTALLOWED 6 // prazdny retezec 'name' -#define GFN_PATHISINVALID 7 // nelze vyloucit "..", napr. "c:\.." +// error constants for CSalamanderGeneralAbstract::SalCheckPath +#define GFN_SERVERNAMEMISSING 1 // server name is missing in UNC path +#define GFN_SHARENAMEMISSING 2 // share name is missing in UNC path +#define GFN_TOOLONGPATH 3 // by using this operation, too long path would be created +#define GFN_INVALIDDRIVE 4 // there's no A-Z (or a-z) letter in the ordinary path (c:\) +#define GFN_INCOMLETEFILENAME 5 // a relative path without specified 'curDir' -> not solvable +#define GFN_EMPTYNAMENOTALLOWED 6 // empty 'name' string +#define GFN_PATHISINVALID 7 // ".." can't be excluded, e.g. "c:\.." -// chybovy kod pro stav, kdy uzivatel prerusi CSalamanderGeneralAbstract::SalCheckPath klavesou ESC +// error state for the situation when user cancels CSalamanderGeneralAbstract::SalCheckPath with ESC key #define ERROR_USER_TERMINATED -100 -#define PATH_MAX_PATH 248 // limit pro max. delku cesty (plne jmeno adresare), pozor: v limitu uz je zapocteny null-terminator (max. delka retezce je 247 znaku) +#define PATH_MAX_PATH 248 // the limit for maximal path length (full path name), beware: the limit includes null-terminator (max. length of string is 247 characters) -// chybove konstanty pro CSalamanderGeneralAbstract::SalParsePath: -// vstupem byla prazdna cesta a 'curPath' bylo NULL (prazdna cesta se nahrazuje aktualni cestou, -// ale ta tu neni znama) +// error constants for CSalamanderGeneralAbstract::SalParsePath +// the input was empty path and 'curPath' was NULL (empty path is replaced by current path, +// but current path is not known here) #define SPP_EMPTYPATHNOTALLOWED 1 -// windowsova cesta (normal + UNC) neexistuje, neni pristupna nebo uzivatel prerusil test -// na pristupnost cesty (soucasti je i pokus o obnoveni sit. spojeni) +// windows path (normal + UNC) does not exist, is not accessible or user cancelled the test +// for path accessibility (an attempt to restore network connection is included) #define SPP_WINDOWSPATHERROR 2 -// windowsova cesta zacina jmenem souboru, ktery ale neni archiv (jinak by slo o cestu do archivu) +// windows path begins with file name, but it is not an archive (otherwise it would be a path to an archive) #define SPP_NOTARCHIVEFILE 3 -// FS cesta - jmeno pluginoveho FS (fs-name - pred ':' v ceste) neni zname (zadnemu pluginu -// nebylo toto jmeno zaregistrovano) +// FS path - a name of plugin FS (fs-name - before ':' in path) is not known (the name was not +// registered to any plugin) #define SPP_NOTPLUGINFS 4 -// jde o relativni cestu, ale aktualni cesta neni znama nebo jde o FS (tam nelze poznat root -// a vubec nezname strukturu fs-user-part cesty, takze nelze provest prevod na absolutni cestu) -// je-li aktualni cesta FS ('curPathIsDiskOrArchive' je FALSE), nedojde v tomto pripade ke hlaseni -// chyby uzivateli (predpoklada se dalsi zpracovani na strane FS, ktere metodu SalParsePath volalo) +// it's a relative path, but current path is not known or it's a FS (root can't be recognized +// there and we don't know the structure of fs-user-part of the path, so it's not possible to +// convert it to absolute path) +// if current path is FS ('curPathIsDiskOrArchive' is FALSE), the error is not reported to user +// (it's supposed that the FS which called SalParsePath method will handle it #define SPP_INCOMLETEPATH 5 -// konstanty vnitrnich barev Salamandera -#define SALCOL_FOCUS_ACTIVE_NORMAL 0 // barvy pera pro ramecek kolem polozky +// Salamander internal colors constants +#define SALCOL_FOCUS_ACTIVE_NORMAL 0 // pen colors for frame around item #define SALCOL_FOCUS_ACTIVE_SELECTED 1 #define SALCOL_FOCUS_FG_INACTIVE_NORMAL 2 #define SALCOL_FOCUS_FG_INACTIVE_SELECTED 3 #define SALCOL_FOCUS_BK_INACTIVE_NORMAL 4 #define SALCOL_FOCUS_BK_INACTIVE_SELECTED 5 -#define SALCOL_ITEM_FG_NORMAL 6 // barvy textu polozek v panelu +#define SALCOL_ITEM_FG_NORMAL 6 // item text colors in panel #define SALCOL_ITEM_FG_SELECTED 7 #define SALCOL_ITEM_FG_FOCUSED 8 #define SALCOL_ITEM_FG_FOCSEL 9 #define SALCOL_ITEM_FG_HIGHLIGHT 10 -#define SALCOL_ITEM_BK_NORMAL 11 // barvy pozadi polozek v panelu +#define SALCOL_ITEM_BK_NORMAL 11 // item background colors in panel #define SALCOL_ITEM_BK_SELECTED 12 #define SALCOL_ITEM_BK_FOCUSED 13 #define SALCOL_ITEM_BK_FOCSEL 14 #define SALCOL_ITEM_BK_HIGHLIGHT 15 -#define SALCOL_ICON_BLEND_SELECTED 16 // barvy pro blend ikonek +#define SALCOL_ICON_BLEND_SELECTED 16 // icon blend colors #define SALCOL_ICON_BLEND_FOCUSED 17 #define SALCOL_ICON_BLEND_FOCSEL 18 -#define SALCOL_PROGRESS_FG_NORMAL 19 // barvy progress bary +#define SALCOL_PROGRESS_FG_NORMAL 19 // progress bar colors #define SALCOL_PROGRESS_FG_SELECTED 20 #define SALCOL_PROGRESS_BK_NORMAL 21 #define SALCOL_PROGRESS_BK_SELECTED 22 -#define SALCOL_HOT_PANEL 23 // barva hot polozky v panelu -#define SALCOL_HOT_ACTIVE 24 // v aktivnim window caption -#define SALCOL_HOT_INACTIVE 25 // v neaktivni caption, statusbar,... -#define SALCOL_ACTIVE_CAPTION_FG 26 // barva textu v aktivnim titulku panelu -#define SALCOL_ACTIVE_CAPTION_BK 27 // barva pozadi v aktivnim titulku panelu -#define SALCOL_INACTIVE_CAPTION_FG 28 // barva textu v neaktivnim titulku panelu -#define SALCOL_INACTIVE_CAPTION_BK 29 // barva pozadi v neaktivnim titulku panelu -#define SALCOL_VIEWER_FG_NORMAL 30 // barva textu v internim text/hex vieweru -#define SALCOL_VIEWER_BK_NORMAL 31 // barva pozadi v internim text/hex vieweru -#define SALCOL_VIEWER_FG_SELECTED 32 // barva oznaceneho textu v internim text/hex vieweru -#define SALCOL_VIEWER_BK_SELECTED 33 // barva oznaceneho pozadi v internim text/hex vieweru -#define SALCOL_THUMBNAIL_NORMAL 34 // barvy pera pro ramecek kolem thumbnail +#define SALCOL_HOT_PANEL 23 // hot item color in panel +#define SALCOL_HOT_ACTIVE 24 // active window caption +#define SALCOL_HOT_INACTIVE 25 // inactive window caption, statusbar,... +#define SALCOL_ACTIVE_CAPTION_FG 26 // text color in active window caption +#define SALCOL_ACTIVE_CAPTION_BK 27 // background color in active window caption +#define SALCOL_INACTIVE_CAPTION_FG 28 // text color in inactive window caption +#define SALCOL_INACTIVE_CAPTION_BK 29 // background color in inactive window caption +#define SALCOL_VIEWER_FG_NORMAL 30 // text color in internal text/hex viewer +#define SALCOL_VIEWER_BK_NORMAL 31 // background color in internal text/hex viewer +#define SALCOL_VIEWER_FG_SELECTED 32 // text color of selected text in internal text/hex viewer +#define SALCOL_VIEWER_BK_SELECTED 33 // background color of selected text in internal text/hex viewer +#define SALCOL_THUMBNAIL_NORMAL 34 // pen color for frame around thumbnail #define SALCOL_THUMBNAIL_SELECTED 35 #define SALCOL_THUMBNAIL_FOCUSED 36 #define SALCOL_THUMBNAIL_FOCSEL 37 -// konstanty duvodu, proc metody CSalamanderGeneralAbstract::ChangePanelPathToXXX vratily neuspech: -#define CHPPFR_SUCCESS 0 // v panelu je nova cesta, uspech (navratova hodnota je TRUE) -// novou cestu (nebo jmeno archivu) nelze prevest z relativni na absolutni nebo -// nova cesta (nebo jmeno archivu) neni pristupna nebo -// cestu na FS nelze otevrit (neni plugin, odmita svuj load, odmita otevreni FS, fatalni chyba ChangePath) +// the constats of reasons, why CSalamanderGeneralAbstract::ChangePanelPathToXXX methods returned false: +#define CHPPFR_SUCCESS 0 // there is a new path in panel (return value is TRUE) +// new path (or archive name) can't be converted from relative to absolute or +// new path (or archive name) is not accessible or +// the path to FS can't be opened (there's no plugin, plugin refused to load, plugin refused to open FS, fatal error in ChangePath) #define CHPPFR_INVALIDPATH 1 -#define CHPPFR_INVALIDARCHIVE 2 // soubor neni archiv nebo se jako archiv neda vylistovat -#define CHPPFR_CANNOTCLOSEPATH 4 // aktualni cestu nelze uzavrit -// v panelu je zkracena nova cesta, -// upresneni pro FS: v panelu je bud zkracena nova cesta nebo puvodni cesta nebo zkracena -// puvodni cesta - puvodni cesta se do panelu zkousi vratit jen pokud se nova cesta otevirala -// v aktualnim FS (metoda IsOurPath pro ni vratila TRUE) a pokud nova cesta neni pristupna -// (ani zadna jeji podcesta) +#define CHPPFR_INVALIDARCHIVE 2 // the file is not an archive or it can't be listed as an archive +#define CHPPFR_CANNOTCLOSEPATH 4 // the current path can't be closed +// there's a new trimmed path in panel, +// to make this clear for FS: there's either a new trimmed path in panel or the original path or +// a trimmed original path - the original path tries to return to panel only if the new path +// was opened in current FS (method IsOurPath returned TRUE) and if the new path is not accessible +// (nor any of its subpaths) +// #define CHPPFR_SHORTERPATH 5 -// v panelu je zkracena nova cesta; duvodem zkraceni bylo to, ze pozadovana cesta byla jmeno -// souboru - v panelu je cesta k souboru a soubor bude vyfokusen +// there is a new trimmed path in panel; the reason for trimming is that the requested path +// was a file name - there is a path to a file in panel, the file will be focused #define CHPPFR_FILENAMEFOCUSED 6 +// types for CSalamanderGeneralAbstract::ValidateVarString() and CSalamanderGeneralAbstract::ExpandVarString() // typy pro CSalamanderGeneralAbstract::ValidateVarString() a CSalamanderGeneralAbstract::ExpandVarString() typedef const char*(WINAPI* FSalamanderVarStrGetValue)(HWND msgParent, void* param); struct CSalamanderVarStrEntry { - const char* Name; // jmeno promenne v retezci (napr. u retezce "$(name)" je to "name") - FSalamanderVarStrGetValue Execute; // funkce, ktera vraci text reprezentujici promennou + const char* Name; // variable name in string (e.g. in string "$(name)" it is "name") + FSalamanderVarStrGetValue Execute; // a function which returns text which represents the variable }; class CSalamanderRegistryAbstract; -// typ call-backu pouzivany pri load/save konfigurace pomoci -// CSalamanderGeneral::CallLoadOrSaveConfiguration; 'regKey' je NULL pokud jde o load -// defaultni konfigurace (save se pri 'regKey' == NULL nevola); 'registry' je objekt pro -// praci s registry; 'param' je uzivatelsky parametr funkce (viz +// callback type used during loading/saving configuration by +// CSalamanderGeneral::CallLoadOrSaveConfiguration; 'regKey' is NULL if it is load +// of default configuration (save is not called if 'regKey' == NULL); 'registry' is +// object for registry access; 'param' is user parameter of the function (see // CSalamanderGeneral::CallLoadOrSaveConfiguration) +// typedef void(WINAPI* FSalLoadOrSaveConfiguration)(BOOL load, HKEY regKey, CSalamanderRegistryAbstract* registry, void* param); -// zaklad struktury pro CSalamanderGeneralAbstract::ViewFileInPluginViewer (kazdy plugin -// viewer muze mit tuto strukturu rozsirenou o sve parametry - struktura se predava do -// CPluginInterfaceForViewerAbstract::ViewFile - parametry muzou byt napr. titulek okna, -// mod vieweru, offset od zacatku souboru, pozice oznaceni, atp.); POZOR !!! na pakovani -// struktur (pozadovane je 4 byty - viz "#pragma pack(4)") +// structure base for CSalamanderGeneralAbstract::ViewFileInPluginViewer (each plugin +// viewer can have this structure extended by its own parameters - the structure is +// passed to CPluginInterfaceForViewerAbstract::ViewFile - the parameters can be e.g. +// window title, viewer mode, offset from the beginning of the file, position of +// selection, etc.); BEWARE OF packing of structure (4 bytes are required - see "#pragma pack(4)") struct CSalamanderPluginViewerData { - // kolik bytu od zacatku struktury je platnych (pro rozliseni verzi struktury) + // how many bytes from the beginning of the structure are valid (to distinguish the versions of structure) int Size; - // jmeno souboru, ktery se ma otevrit ve viewru (nepouzivat v metode - // CPluginInterfaceForViewerAbstract::ViewFile - jmeno souboru je dano parametrem 'name') + // name of the file which should be opened in viewer (do not use in method + // CPluginInterfaceForViewerAbstract::ViewFile - the file name is given by + // parameter 'name') const char* FileName; }; -// rozsireni struktury CSalamanderPluginViewerData pro interni text/hex viewer +// extension of structure CSalamanderPluginViewerData for internal text/hex viewer struct CSalamanderPluginInternalViewerData : public CSalamanderPluginViewerData { - int Mode; // 0 - textovy mod, 1 - hexa mod - const char* Caption; // NULL -> obsahuje caption okna FileName, jinak Caption - BOOL WholeCaption; // ma vyznam pokud je Caption != NULL. TRUE -> v titulku - // vieweru bude zobrazen pouze retezec Caption; FALSE -> za - // Caption se pripoji standardni " - Viewer". + int Mode; // 0 - text mode, 1 - hex mode + const char* Caption; // NULL -> contains caption of window FileName, otherwise Caption + BOOL WholeCaption; // makes sense if Caption != NULL. TRUE -> only Caption will be + // displayed in the caption of viewer window; FALSE -> standard + // " - Viewer" will be appended to Caption }; -// konstanty typu parametru konfigurace Salamandera (viz CSalamanderGeneralAbstract::GetConfigParameter) +// Salamander configuration parameters types constants (see CSalamanderGeneralAbstract::GetConfigParameter) #define SALCFGTYPE_NOTFOUND 0 // parameter not found #define SALCFGTYPE_BOOL 1 // TRUE/FALSE #define SALCFGTYPE_INT 2 // 32-bit integer #define SALCFGTYPE_STRING 3 // null-terminated multibyte string #define SALCFGTYPE_LOGFONT 4 // Win32 LOGFONT structure -// konstanty parametru konfigurace Salamandera (viz CSalamanderGeneralAbstract::GetConfigParameter); -// v komentari je uveden typ parametru (BOOL, INT, STRING), za STRING je v zavorce potrebna -// velikost bufferu pro retezec +// Salamander configuration parameters constants (see CSalamanderGeneralAbstract::GetConfigParameter) +// the comment contains type of parameter (BOOL, INT, STRING), for STRING, the size of buffer +// for string is required in brackets // // general parameters #define SALCFG_SELOPINCLUDEDIRS 1 // BOOL, select/deselect operations (num *, num +, num -) work also with directories @@ -487,44 +494,47 @@ struct CSalamanderPluginInternalViewerData : public CSalamanderPluginViewerData #define SALCFG_ARCSUBDIRBYARCFORUNPACK 142 // BOOL, should it unpack to subdirectory named by archive? #define SALCFG_ARCUSESIMPLEICONS 143 // BOOL, should it use simple icons in archives? +// callback type used in the method CSalamanderGeneral::SalSplitGeneralPath // typ callbacku pouzivany v metode CSalamanderGeneral::SalSplitGeneralPath typedef BOOL(WINAPI* SGP_IsTheSamePathF)(const char* path1, const char* path2); -// typ callbacku pouzivany v metode CSalamanderGeneralAbstract::CallPluginOperationFromDisk -// 'sourcePath' je zdrojova cesta na disku (ostatni cesty jsou od ni vztazeny relativne); -// oznacene soubory/adresare jsou zadany enumeracni funkci 'next' jejimz parametrem je -// 'nextParam'; 'param' je parametr predavany do CallPluginOperationFromDisk jako 'param' +// callback type used in the method CSalamanderGeneralAbstract::CallPluginOperationFromDisk +// 'sourcePath' is source path on disk (other paths are relative to it); +// selected files/directories are passed to enumeration function 'next' with parameter +// 'nextParam'; 'param' is parameter passed to CallPluginOperationFromDisk as 'param' typedef void(WINAPI* SalPluginOperationFromDisk)(const char* sourcePath, SalEnumSelection2 next, void* nextParam, void* param); -// flagy pro textove vyhledavaci algoritmy (CSalamanderBMSearchData a CSalamanderREGEXPSearchData); -// flagy se daji logicky scitat -#define SASF_CASESENSITIVE 0x01 // velikost pismen je dulezita (pokud neni nastaven, hleda se bez ohledu na vel. pismen) -#define SASF_FORWARD 0x02 // hledani smerem dopredu (pokud neni nastaven, hleda se smerem zpet) +// flags for text searching algorithms (CSalamanderBMSearchData and CSalamanderREGEXPSearchData); +// flags can be logically added +#define SASF_CASESENSITIVE 0x01 // size of letters is important (if not set, searching is case insensitive) +#define SASF_FORWARD 0x02 // searching forward (if not set, searching backward) -// ikony pro GetSalamanderIcon +// icons for GetSalamanderIcon #define SALICON_EXECUTABLE 1 // exe/bat/pif/com #define SALICON_DIRECTORY 2 // dir -#define SALICON_NONASSOCIATED 3 // neasociovany soubor -#define SALICON_ASSOCIATED 4 // asociovany soubor +#define SALICON_NONASSOCIATED 3 // non-associated file +#define SALICON_ASSOCIATED 4 // associated file #define SALICON_UPDIR 5 // up-dir ".." -#define SALICON_ARCHIVE 6 // archiv +#define SALICON_ARCHIVE 6 // archive -// velikosti ikon pro GetSalamanderIcon +// sizes of icons for GetSalamanderIcon #define SALICONSIZE_16 1 // 16x16 #define SALICONSIZE_32 2 // 32x32 #define SALICONSIZE_48 3 // 48x48 -// interface objektu Boyer-Moorova algoritmu pro vyhledavani v textu -// POZOR: kazdy alokovany objekt je mozne pouzivat jen v ramci jednoho threadu -// (nemusi jit o hlavni thread, nemusi jit u vsech objektu o jeden thread) +// +// interface of the Boyer-Moore algorithm object for text searching +// CAUTION: each allocated object can be used only in one thread +// (it doesn't have to be the main thread, it doesn't have to be the same thread for all objects) class CSalamanderBMSearchData { public: - // nastaveni vzorku; 'pattern' je null-terminated text vzorku; 'flags' jsou priznaky - // algoritmu (viz konstanty SASF_XXX) + // pattern setting; 'pattern' is null-terminated text pattern; 'flags' are flags + // of algorithm (see constants SASF_XXX) virtual void WINAPI Set(const char* pattern, WORD flags) = 0; + // pattern setting; 'pattern' is binary pattern of length 'length' (buffer 'pattern' // nastaveni vzorku; 'pattern' je binarni vzorek o delce 'length' (buffer 'pattern' musi // mit delku alespon ('length' + 1) znaku - jen pro kompatibilitu s textovymi vzorky); // 'flags' jsou priznaky algoritmu (viz konstanty SASF_XXX)