ZScript FileUtils

From ZBrush Info

Jump to: navigation, search

Contents

ZFileUtils DLL

ZFileUtils.dll is a DLL that provides useful utilities to ZScript. This page describes these utilities and gives examples for their use in script.

NOTE: for custom zscript plugins, the ZFileUtils.dll should be placed in a data folder unique to the plugin (and installed with it in the ZStartup\ZPlugs folder). This is so that users who download plugins with older versions of the dll will not inadvertently overwrite a newer version.


Download the latest ZFileUtils DLL here

General Routines

The CheckSystem routine shown below is a standard routine that needs to be defined for all ZScripts that use the file utilities DLL. It links up to ZFileUitls DLL and check that the version is as expected. Substitute your own folder name for the placeholder MyDataFolder.

Note: The version is multiplied by 10 for the comparison to work.


 [VarDef, isMac, 0]          // Mac or Win?
 [VarDef, utilDLLPath," "]   // Where is the ZFileUtil dll?
 [VarDef, utilDLLVersion, 0] // What is the version of ZFileUtil?
 
 [RoutineDef, CheckSystem,	
   [VarSet,isMac, [ZBrushInfo,6]]	
   // Make sure we have the dll.
   [If,isMac,
     [VarSet,utilDLLPath,"ZSTARTUP_ZPLUGS/MyDataFolder/ZFileUtils.lib"],
     [VarSet,utilDLLPath,"ZSTARTUP_ZPLUGS/MyDataFolder/ZFileUtils.dll"]
   ]
   [If, [FileExists, [Var,utilDLLPath]], //check that correct version
     [VarSet, utilDLLVersion, [FileExecute, [Var,utilDLLPath], Version]]
     [If, [Val,utilDLLVersion*10] >= 18, // Multiply version by 10 for test
       //OK
     , //else earlier version			
       [Note,"\Cff9923ZScript Note:\Cc0c0c0 The \Cff9923Z\CffffffFileUtils\Cc0c0c0 DLL is an earlier version. Please install correct version."]
       [Exit]
     ]			
   , // else no DLL.
     [Note,"\Cff9923ZScript Note:\Cc0c0c0 The \Cff9923Z\CffffffFileUtils\Cc0c0c0 plugin could not be found."]
     [Exit]
   ]
 ]


Files and Directories

These routines allow access to files and directories. You must have called the CheckSystem routine defined above before using these calls.

COPY a FILE to another file. Routines return 0 if successful.

 [FileExecute, [Var,utilDLLPath], FileCopyFrom, "C:\Temp\photo.bmp"]] // Sets source file...
 [VarSet, err, [FileExecute, [Var,utilDLLPath], FileCopyTo, "C:\Temp\photo_copy.bmp"]] // ...copies source file to this file.


DELETE a FILE. Returns 0 if successful.

 [VarSet, err, [FileExecute, [Var,utilDLLPath], FileDelete, "C:\Temp\photo.bmp"]]


DELETE a DIRECTORY (it must be empty). Returns 0 if successful.

 [VarSet, err, [FileExecute, [Var,utilDLLPath], DirDelete, "C:\Temp"]]


CREATE a DIRECTORY (path to directory must exist). Returns 0 if successful.

 [VarSet, err, [FileExecute, [Var,utilDLLPath], DirCreate, "C:\Temp"]]


LIST DIRECTORY files (excludes hidden and system files). Returns # files found, 0 on error or no files.

 [VarSet, fileCount, [FileExecute, [Var,utilDLLPath], GetDirFileList, [FileNameResolvePath, "ZSTARTUP_ZPLUGS"]]]

Then use GetFileInfo as as described in the List Files section to get the filenames.

List Files

These routines allow you to put up a file brower to choose one or more files. You can then iterate through the chosen files an perform an action in script. You must have called the CheckSystem routine defined above before using these calls.

Set the DEFAULT DIRECTORY for the next FILE BROWSE dialog (GetFileList routine). Returns 0 if OK.

 [VarDef, err, 0]
 [VarSet, err, [FileExecute, [Var,utilDLLPath], SetDefaultDir, "C:\Test"]]


Set the TITLE for the next FILE BROWSE dialog (GetFileList routine). Returns 0 if OK. Default title is "Select Files".

 [VarSet, err, [FileExecute, [Var,utilDLLPath], SetDialogTitle, "Import ONE Texture"]]


GET FILE LIST:
Get a single or list of files chosen via the standard file browser. You supply a file filter. Omitting the 1 gives many file selection. File filters are defined by name1|filter1;filter2;...;filtern[name2|filter1;filter2;...;filtern| more if wanted]. GetFileList returns 0 if failed or cancelled, otherwise number of files selected and placed in the file list. 

 [VarDef, fileCount, 0]
 [VarSet, fileCount, [FileExecute, [Var,utilDLLPath],  
 		      // name1 of filter               | filter for name1| name2           | filter2     Restricts to ONE file selection.
        GetFileList, "Texture Files (*.psd;*.bmp;*.jpg)|*.psd;*.bmp;*.jpg|Photoshop (*.psd)|*.psd",      1]]


Get FILE NAME/FULLNAME:

Get the FULL NAME, or NAME (with extension) of a file in the file list obtained through GetFileList. Returns non-zero name length if OK else 0. Index is from 1 to fileCount obtained by GetFileList.

 [VarDef, fileNameLen, 0]
 [VarDef, fileName, " "]
 [If, fileCount >= 1,
   [MemCreate, TestF_Filename, 256, 0] // Make a buffer to get the response string.
 
   [VarSet, fileNameLen, [FileExecute, [Var,utilDLLPath], GetFileInfo, "fullname", 1, TestF_Filename]] // Get the full path and name and extension.
   [VarSet, fileNameLen, [FileExecute, [Var,utilDLLPath], GetFileInfo, "name", 1, TestF_Filename]] // Just get the name and exension.
 
   [If, fileNameLen,
     [MemReadString, TestF_Filename, fileName]
     [MessageOK, [StrMerge, "Should have imported texture: ", fileName], utilDLLPath]
   , // else
     [MessageOK, "Got one file, but ERROR getting name info.", utilDLLPath]
   ]
 
   [MemDelete, TestF_Filename] // Destroy global buffer.
 ]


Sample Load Textures Script

Example ZScript code to load some textures. 

 [VarDef, err, 0]
 [VarDef, fileCount, 0]
 [VarDef, fileNameLen, 0]
 [VarDef, fileName, ""]
 
 [IButton, iLoadSomeTexturesButton,
   "Asks for and loads some textures using the ZFileUtils DLL API.",
 
   [RoutineCall, CheckSystem] // NEED to call this to be sure we have the DLL.
 
   [VarSet, err, [FileExecute, [Var,utilDLLPath], SetDialogTitle, "Import Some Textures"]]
   // I will test error, but not required.
   [If, err, [MessageOK, [StrMerge, "SetDialogTitle failed with ", err], utilDLLPath] ]
   
   // Get the files to load. Passing no second parameter defaults to many files can be selected.
   [VarSet, fileCount, [FileExecute, [Var,utilDLLPath], GetFileList,
                       "Texture Files (*.psd;*.bmp;*.jpg)|*.psd;*.bmp;*.jpg|Photoshop (*.psd)|*.psd"]]
   [If, fileCount != 0,
     [MessageOK, [StrMerge, "Got ", fileCount, " files."], utilDLLPath]
     [MemCreate, TestF_Filename, 256, 0] // Make a buffer to get the response string.
     
     // Loop over the names and load the textures.
     [Loop, fileCount,
       [VarSet, fileNameLen, [FileExecute, [Var,utilDLLPath], GetFileInfo, "fullname", n+1, TestF_Filename]]
       [If, fileNameLen,
         [MemReadString, TestF_Filename, fileName]
         [MessageOK, [StrMerge, "Load file: ", fileName], utilDLLPath]
         [FileNameSetNext, fileName] // the one to load.
         [IPress, Texture:Import]		
         
         // Now get just the name part.
         [VarSet, fileNameLen, [FileExecute, [Var,utilDLLPath], GetFileInfo, "name", n+1, TestF_Filename]]
         [If, fileNameLen,
           [MemReadString, TestF_Filename, fileName]
           [MessageOK, [StrMerge, "Should have imported texture: ", fileName], utilDLLPath]
         , // else
           [MessageOK, [StrMerge, "ERROR getting name info info for file:", n+1], utilDLLPath]
         ]
         
       , // else problem getting the filename.
         [MessageOK, [StrMerge, "ERROR getting fullname info for file: ", n+1], utilDLLPath]
       ]
     , n]
     [MemDelete, TestF_Filename] // Destroy global buffer.
   ]
 ]


Retrieved from "http://www.pixologic.com/docs/index.php/ZScript_FileUtils"
Personal tools
Editing ZBrushInfo