Fotografický magazín "iZIN IDIF" každý týden ve Vašem e-mailu.
Co nového ve světě fotografie!
Zadejte Vaši e-mailovou adresu:
Kamarád fotí rád?
Přihlas ho k odběru fotomagazínu!
Zadejte e-mailovou adresu kamaráda:
Delphi
API funkce SHFileOperation
10. ledna 2002, 00.00 | Většinou nebývá zvykem věnovat článek jen jediné Win32 API funkci, ale tentokrát uděláme vyjímku. Mimo jiné se naučíte, jak mazat soubory do koše.
Často je v programu potřeba různým způsobem manipulovat se soubory. Teď nemám na mysli čtení/zápis, ale kopírování, přesouvání a mazání. Na tyto věci samozřejmě existují API funkce (CopyFile a spol.). Někdy je ale potřeba, aby tyto funkce uměly víc - třeba zobrazit dialog ukazující průběh prováděné operace nebo provést operaci najednou s více soubory. A v neposlední řadě je někdy potřeba umět mazat soubory nikoliv přímo, ale do koše. Všechny výše uvedené možnosti jsou dostupné v API funkci SHFileOperation, kterou si teď představíme.
Funkce je deklarována v unitě ShellAPI takto:
|
Jejím jediným parametrem je struktura TSHFileOpStruct. V té určujeme, co všechno má funkce provést - jsou v ní tedy "zabaleny" všechny potřebné parametry. Její deklarace se nachází opět u unitě ShellAPI:
|
Poznámka pro pokročilejší: Funkce i její parametrová struktura je v dispozici jak v ANSI tak v Unicode variantě (jak už pozorní čtenáři možná usoudili z výpisu). Proto je nejdřív deklarován typ TSHFileOpStructA (a analogicky i TSHFileOpStructW). TSHFileOpStruct je pak defaultně nadefinována jako ekvivalentní s ANSI variantou.
Nyní si popišme jednotlivé parametry.
- Wnd
- Handle okna, kde se mají zobrazovat informace o průběhu.
- wFunc
- Hodnota tohoto parametru určuje, jaká operace se má
provádět. Lze použít následující čtyři konstanty:
FO_COPY, FO_DELETE, FO_MOVE, FO_RENAME.
Řekl bych, že názvy konstant mluví samy za sebe.
- pFrom
- Ukazatel na buffer obsahující názvy souborů, se kterými
se má manipulovat. Každý název souboru je ukončen
znakem #0. Celý seznam je pak ukončen dvěma znaky #0.
Seznam souborů lze také specifikovat pomocí klasické
hvězdičkové konvence.
- pTo
- Ve většině případů je hodnotou tohoto parametru
adresář, kam soubory zkopírovat/přemístit. V případě
mazání je tento parametr ignorován. Zajímavou možností
je použít vlajku FOF_MULTIDESTFILES (viz níže)
- pak je hodnotou parametru seznam souborů zapsaný ve
stejném formátu jako u pFrom a funkce zkopíruje/přejmenuje
soubory z pFrom na soubory na odpovídajících
místech seznamu pTo.
- fFlags
- Vlajky upřesňující provedení operace. Hodnotou je
součet libovolných z následujících konstant:
FOF_ALLOWUNDO V helpu je napsáno, že použití této vlajky zachovává informaci pro undo. Praktický význam je, že použití této vlajky při mazání maže soubory do koše, nikoliv přímo z harddisku. FOF_FILESONLY Pokud je v pFrom použita hvězdičková konvence, nezahrnou se do výběru adresáře. FOF_MULTIDESTFILES Signalizuje, že v pTo je použit seznam souborů místo adresáře. FOF_NOCONFIRMATION Nezobrazuje žádné potvrzovací dialogy (při kolizích jmen souborů apod.), automaticky předpokládá odpověď "Ano". FOF_NOCONFIRMMKDIR Nevyžaduje potvrzení vytvoření nového adresáře. FOF_NOERRORUI Pokud nastane nějaká chyba, nezobrazí se dialog, který o tom inforuje uživatele. FOF_RENAMEONCOLLISION Pokud při kopírování/přesunu dojde ke kolizi jmen (tj. cílový soubor už bude existovat), jméno cílového souboru se upraví (např. v českých Windiws se přidá předpona "Kopie - "). FOF_SILENT Naní zobrazován dialog s průběhem operace (defaultně zobrazován vždy je!) FOF_SIMPLEPROGRESS Je zobrazena jen zjednodušená verze dialogu s průběhem operace (nejsou zobrazena jména jednotlivých souborů). Poznámka 1: Nepopisoval jsem vlajky FOF_CONFIRMMOUSE, FOF_NOCOPYSECURITYATTRIBS a FOF_WANTMAPPINGHANDLE, protože je velmi pravděpodobně nevyužijete. Jejich popis zájemci najdou v nápovědě.
Poznámka 2: Typ FILEOP_FLAGS (tedy typ proměnné fFlags) je definován jako Word.
- fAnyOperationsAborted
- Tato položka je výstupní - po volání funkce je zde
hodnota True, pokud uživatel některou z operací
přeruší kliknutím na tlačítko Storno. Pokud ne, je
zde vrácena hodnota False.
- hNameMappings
- Pravděpodobně nebudete potřebovat. Funkce zde (pokud
použijete vlajku FOF_WANTMAPPINGHANDLE) vrací
ve speciálním formátu seznam starých a nových jmen všech
souborů
- lpszProgressTitle
- Nadpis dialogu s průběhem operace. Tento parametr je ignorován, pokud není nastavena vlajka FOF_SIMPLEPROGRESS.
Co dodat? Že když nespecifikujete v pTo nebo pFrom úplnou cestu k souboru (tj. začínající kořenovým adresářem), cesta se považuje za relativní vůči aktuálnímu adresáři. Ještě k návratové hodnotě: Je rovná nule, pokud vše proběhne hladce, nebo různá od nuly, nastane-li při manipulaci se soubory nějaká chyba.
Podle mého názoru je představená funkce poměrně silným nástrojem, který se někdy docela vyplatí používat - tento článek tedy prosím chápejte jako nastínění možností, které SHFileOperation může programátorovi nabídnout.
Diskuse k článku
-
25. listopadu 2012
-
30. srpna 2002
-
10. října 2002
-
4. listopadu 2002
-
12. září 2002
-
25. listopadu 2012
-
28. července 1998
-
31. července 1998
-
28. srpna 1998
-
6. prosince 2000
-
27. prosince 2007
-
4. května 2007