Documentation for Win32lib v0.70.18
Table of Contents

File Operations

The basic File I/O routines using Windows API routines.


  • func buildDefaultOfn( integer window, sequence file, sequence filters, atom flags )   Creates a OpenFile structure used by the standard dialog.
  • func copyFile(sequence CurrentName, sequence NewName, integer Flag)   Copies a file.
  • func createDirectory(sequence Name)   Creates a new directory
  • func deleteFile(sequence Name)   Deletes an operating system file.
  • func getCurrentDirectory()   Gets the current directory
  • func getFileInfo(object pPath, object pAttrib, object pItems)   Retrieves various properties of a file.
  • func getFullPathName(sequence File, integer Option)    Returns the path and long file name that File refers to.
  • func getOpenFileName( window, file, filters )   "Open File" dialog.
  • func getOpenFileNameEx( window, file, filters )   "Open File" dialog.
  • func getSaveFileName( window, file, filters )   "Save File" dialog.
  • func getTempFile(object Dir, sequence Prefix)   Used to create an empty file, intended to temporary use.
  • func getTempPath()   Used to find out the directory designated for temporary files.
  • func moveFile(sequence CurrentName, sequence NewName)   Renames or Moves a file.
  • func selectDirectory(sequence title, object flags, atom callback, atom cbData)   Displays a dialog for selecting directories.
  • proc setCurrentDirectory(sequence Path)   Sets the current directory
  • func setFileAttr(sequence pPath, object pAttribs)   Sets one or more attibutes for the specified file.
  • func setSearchPaths(object Paths)   Possibly sets the file system paths to use when searching for files
  • func w32FileOpen(sequence Path, sequence Mode)   Search the set 'searchpaths' for the file then opens it.
  • func w32FindFile(sequence File)   Search the set 'searchpaths' for the file and returns its path specification.

    Documentation for Win32lib v0.70.18
    Table of Contents

    [func]
    buildDefaultOfn
    ( integer window, sequence file, sequence filters, atom flags )

    Creates a OpenFile structure used by the standard dialog.

    Returns: The address of the structure.

    Category: File Operations

    Note, you must call w32release_mem() when you have finished with the structure.

           atom lOfn
           lOfn = buildDefaultOfn(0, "newfile.txt", {"Text Files","*.txt"},
                    OFN_FILEMUSTEXIST)
           w32store(lOfn, OfnDefExt, "TXT")
           if w32Func(xGetOpenFileName, {lOfn}) then
             -- get the name
             fName = w32fetch( lOfn, ofnFile )
             fNamePtr = w32fetch( lOfn, ofnFileOffset)
             fExtPtr = w32fetch( lOfn, ofnFileExtension)
           else
             fName = ""
           end if
           w32release_mem(lOfn)
    

    See Also: copyFile, createDirectory, deleteFile, getCurrentDirectory, getFileInfo, getFullPathName, getOpenFileName, getOpenFileNameEx, getSaveFileName, getTempFile, getTempPath, moveFile, selectDirectory, setCurrentDirectory, setFileAttr, setSearchPaths, w32FileOpen, w32FindFile


    Documentation for Win32lib v0.70.18
    Table of Contents

    [func]
    copyFile
    (sequence CurrentName, sequence NewName, integer Flag)

    Copies a file.

    Returns: ATOM: w32True if successful, w32False if not.

    Category: File Operations

    If Flag is w32True then it will not copy the file if the NewName already exists.

            returnCode = copyFile("C:\\TEMP\\~xyz.tmp", "D:\\PROJECT\\input.txt")
    

    See Also: buildDefaultOfn, createDirectory, deleteFile, getCurrentDirectory, getFileInfo, getFullPathName, getOpenFileName, getOpenFileNameEx, getSaveFileName, getTempFile, getTempPath, moveFile, selectDirectory, setCurrentDirectory, setFileAttr, setSearchPaths, w32FileOpen, w32FindFile


    Documentation for Win32lib v0.70.18
    Table of Contents

    [func]
    createDirectory
    (sequence Name)

    Creates a new directory

    Returns: ATOM: w32True if successful, w32False if not.

    Category: File Operations

    Name is the name of the directory to create. If you need this routine to also create all the intervening directories, specify the Name as {w32True, Name }

          -- Create the PROJECT directory in the D: drive
          returnCode = createDirectory("D:\\PROJECT")
          -- Create the 'saves' directory and 'temp' and 'temp\project'
          -- if required.
          returnCode = createDirectory({w32True, "C:\\temp\\project\\saves"})
    

    See Also: buildDefaultOfn, copyFile, deleteFile, getCurrentDirectory, getFileInfo, getFullPathName, getOpenFileName, getOpenFileNameEx, getSaveFileName, getTempFile, getTempPath, moveFile, selectDirectory, setCurrentDirectory, setFileAttr, setSearchPaths, w32FileOpen, w32FindFile


    Documentation for Win32lib v0.70.18
    Table of Contents

    [func]
    deleteFile
    (sequence Name)

    Deletes an operating system file.

    Returns: ATOM: w32True if successful, w32False if not.

    Category: File Operations

           returnCode = deleteFile("C:\\TEMP\\~xyz.tmp")
    

    See Also: buildDefaultOfn, copyFile, createDirectory, getCurrentDirectory, getFileInfo, getFullPathName, getOpenFileName, getOpenFileNameEx, getSaveFileName, getTempFile, getTempPath, moveFile, selectDirectory, setCurrentDirectory, setFileAttr, setSearchPaths, w32FileOpen, w32FindFile


    Documentation for Win32lib v0.70.18
    Table of Contents

    [func]
    getCurrentDirectory
    ()

    Gets the current directory

    Returns: SEQUENCE: Name of current directory path

    Category: File Operations

    Example

          sequence lPath
          lPath = getCurrentDirectory()
    

    See Also: buildDefaultOfn, copyFile, createDirectory, deleteFile, getFileInfo, getFullPathName, getOpenFileName, getOpenFileNameEx, getSaveFileName, getTempFile, getTempPath, moveFile, selectDirectory, setCurrentDirectory, setFileAttr, setSearchPaths, w32FileOpen, w32FindFile


    Documentation for Win32lib v0.70.18
    Table of Contents

    [func]
    getFileInfo
    (object pPath, object pAttrib, object pItems)

    Retrieves various properties of a file.

    Returns: SEQUENCE: {Name, Type, Attrib, hIcon, iIcon, ExeType, ImageList}

    Category: File Operations

    pPath is either a path name (absolute or relative) or a pointer to an ItemIDList

    The possbile values for pAttrib are listed here. These are either given as a sequence or an or'd atom.

    The possbile values for Items are are enumerated here.. Again, these are either given as a sequence or an or'd atom.

    This routine returns seven items in a sequence...

  • Name -- Display name of file.
  • Type -- Type of file
  • Attrib -- File's properties.
  • hIcon -- Handle to file's icon
  • iIcon -- Index into the .exe for this icon
  • ExeType -- Type of executable
  • ImageList -- Pointer to the system's image list

    Note that if you request the file's icon, you are responsible for calling destroy() on the icon when you have finished with it.

    Examples:

        sequence Props
        Props = getFileInfo("test.bmp",
                      0,
                      w32or_all({
                            SHGFI_ICON,
                            SHGFI_DISPLAYNAME,
                            SHGFI_TYPENAME,
                            SHGFI_ATTRIBUTES
                      }
                      )
                    )
    

    The returned Attrib value is a combination of flags which are listed here.

    See Also: buildDefaultOfn, copyFile, createDirectory, deleteFile, getCurrentDirectory, getFullPathName, getOpenFileName, getOpenFileNameEx, getSaveFileName, getTempFile, getTempPath, moveFile, selectDirectory, setCurrentDirectory, setFileAttr, setSearchPaths, w32FileOpen, w32FindFile


    Documentation for Win32lib v0.70.18
    Table of Contents

    [func]
    getFullPathName
    (sequence File, integer Option)

    Returns the path and long file name that File refers to.

    Returns: SEQUENCE: {PathName, FileName}

    Category: File Operations

    File is a reference to a file.
    Option is w32True if the file must exist, w32False if it doesn't have to exist.

    Note that the Path value returned always ends with a '/' character.

    If Option is w32True and the file does not exist, then empty strings are returned. If Option is w32False and the file does not exist then the returned Path value is prefixed with '?'.

    Example

          sequence lPaths
          lNames = getFullPathName("D:..\\demosa~1.fil")
    

    Given that the current directory for D: drive is "\windows\system" and the short name of "demosample.fil" is "demosa~1.fil" then this example would return ...
    {"D:\windows\", "demosample.fil"}

    See Also: buildDefaultOfn, copyFile, createDirectory, deleteFile, getCurrentDirectory, getFileInfo, getOpenFileName, getOpenFileNameEx, getSaveFileName, getTempFile, getTempPath, moveFile, selectDirectory, setCurrentDirectory, setFileAttr, setSearchPaths, w32FileOpen, w32FindFile


    Documentation for Win32lib v0.70.18
    Table of Contents

    [func]
    getOpenFileName
    ( window, file, filters )

    "Open File" dialog.

    Returns: Selected file name, or empty sequence if cancelled.

    Category: File Operations

    Calling this function brings up the modal "Open File" dialog, allowing the user to select a file name. file is a sequence holding the default file name. filters is a list of patterns to limit displayed files to, in the format:

          { "text", pattern, "text", pattern ... }
    

    For example:

          constant FileTypes = {
              "Text File", "*.TXT",
              "Euphoria Program", "*.EX;*.EXW;*.E;*.EW",
              "All Files", "*.*" }
    

    Note that a pattern can contain several different values.

    Example:

              -- get file name to open
              sequence filename
    

    filename = getOpenFileName( TheWindow, -- parent window "", -- no default name { "Text File", "*.TXT", -- text files "All Files", "*.*" } ) -- everything else

    It is possible to modify the default flags set for the dialog by adding a special 'pattern' of "DIALOG FLAGS" followed by the additional flags required. The usual use of this is to allow multiple files to be selected.

    Multiple Selections
    When doing this, the routine returns a sequence of sequences. The first element is the directory name, which always ends with a '\', and each subsequent element is a file name selected from that directory.

              filename = getOpenFileName(
                              TheWindow,                  -- parent window
                              "",                         -- no default name
                              { "Dialog Flags", {OFN_ALLOWMULTISELECT},
                                "Text File", "*.TXT",     -- text files
                                "All Files", "*.*" } )    -- everything else
    

    if length(filename) > 0 then theDir = filename[1] for i = 2 to length(filename) do ProcessTheFile( theDir, filename[i]) end for end if

    See Also: buildDefaultOfn, copyFile, createDirectory, deleteFile, getCurrentDirectory, getFileInfo, getFullPathName, getOpenFileNameEx, getSaveFileName, getTempFile, getTempPath, moveFile, selectDirectory, setCurrentDirectory, setFileAttr, setSearchPaths, w32FileOpen, w32FindFile


    Documentation for Win32lib v0.70.18
    Table of Contents

    [func]
    getOpenFileNameEx
    ( window, file, filters )

    "Open File" dialog.

    Returns: Selected file name, or empty sequence if cancelled.

    Category: File Operations

    Calling this function brings up the modal "Open File" dialog, with more control over options than with getOpenFileName(). Note however that the "DIALOG FLAGS" construct is not supported. Instead, the extra sequence is a sequence of pairs {field definition,field value}, where the field definition is a field of the ID_OPENFILENAME structure. If a field is no provided, it is assumed to be 0 or "" as appropriate, with one exception.
    If the ofnFlags member appears in the extra sequence, the value may be either an atom or a sequence, like for createEx(). Specifying a sequence obliterates any default setting. Specifying an atom causes or'ing with whatever value is already set. The default flags are OFN_EXPLORER + OFN_LONGNAMES. Here is a list of known flag values.

    See Also: buildDefaultOfn, copyFile, createDirectory, deleteFile, getCurrentDirectory, getFileInfo, getFullPathName, getOpenFileName, getSaveFileName, getTempFile, getTempPath, moveFile, selectDirectory, setCurrentDirectory, setFileAttr, setSearchPaths, w32FileOpen, w32FindFile


    Documentation for Win32lib v0.70.18
    Table of Contents

    [func]
    getSaveFileName
    ( window, file, filters )

    "Save File" dialog.

    Returns: Selected file name, or empty sequence if cancelled.

    Category: File Operations

    Calling this function brings up the modal "Save File" dialog, allowing the user to select a file name. file is a sequence holding the default file name. filters is a list of patterns to limit displayed files to, in the format:

          { "text", pattern, "text", pattern ... }
    

    For example:

          constant FileTypes = {
              "Text File", "*.TXT",
              "Euphoria Program", "*.EX;*.EXW;*.E;*.EW",
              "All Files", "*.*" }
    

    Note that a pattern can contain several different values.

    Example:

              -- get file name to save
              filename = getSaveFileName(
                              TheWindow,                  -- parent window
                              "MyFile.txt",               -- default name
                              { "Text File", "*.TXT",     -- text files
                                "All Files", "*.*" } )    -- everything else
    

    See Also: buildDefaultOfn, copyFile, createDirectory, deleteFile, getCurrentDirectory, getFileInfo, getFullPathName, getOpenFileName, getOpenFileNameEx, getTempFile, getTempPath, moveFile, selectDirectory, setCurrentDirectory, setFileAttr, setSearchPaths, w32FileOpen, w32FindFile


    Documentation for Win32lib v0.70.18
    Table of Contents

    [func]
    getTempFile
    (object Dir, sequence Prefix)

    Used to create an empty file, intended to temporary use.

    Returns: SEQUENCE: The name of the file created.

    Category: File Operations

    If Dir is a number or an empty string, the temporary directory is used.
    If Prefix is less than 3 characters long, it is padded out with underscores. Only the first three characters are used.
    The filename created has the form nnnn.TMP, where nnnn is a number used to enforce uniqueness.

            TempFilename = getTempFile(0, "my")
    

    See Also: buildDefaultOfn, copyFile, createDirectory, deleteFile, getCurrentDirectory, getFileInfo, getFullPathName, getOpenFileName, getOpenFileNameEx, getSaveFileName, getTempPath, moveFile, selectDirectory, setCurrentDirectory, setFileAttr, setSearchPaths, w32FileOpen, w32FindFile


    Documentation for Win32lib v0.70.18
    Table of Contents

    [func]
    getTempPath
    ()

    Used to find out the directory designated for temporary files.

    Returns: Sequence: The name of a directory. It always ends with a '\' character.

    Category: File Operations

            TempPath = getTempPath()
    

    See Also: buildDefaultOfn, copyFile, createDirectory, deleteFile, getCurrentDirectory, getFileInfo, getFullPathName, getOpenFileName, getOpenFileNameEx, getSaveFileName, getTempFile, moveFile, selectDirectory, setCurrentDirectory, setFileAttr, setSearchPaths, w32FileOpen, w32FindFile


    Documentation for Win32lib v0.70.18
    Table of Contents

    [func]
    moveFile
    (sequence CurrentName, sequence NewName)

    Renames or Moves a file.

    Returns: ATOM: w32True if successful, w32False if not.

    Category: File Operations

           returnCode = moveFile("C:\\TEMP\\~xyz.tmp", "D:\\PROJECT\\input.txt")
    

    See Also: buildDefaultOfn, copyFile, createDirectory, deleteFile, getCurrentDirectory, getFileInfo, getFullPathName, getOpenFileName, getOpenFileNameEx, getSaveFileName, getTempFile, getTempPath, selectDirectory, setCurrentDirectory, setFileAttr, setSearchPaths, w32FileOpen, w32FindFile


    Documentation for Win32lib v0.70.18
    Table of Contents

    [func]
    selectDirectory
    (sequence title, object flags, atom callback, atom cbData)

    Displays a dialog for selecting directories.

    Returns: SEQUENCE: The folder name last selected. "" if dialog is cancelled.

    Category: File Operations

    title is the Title that will apear on the dialog box, a child of the main window.
    flags are zero or more of the BIF_ values or'ed together.
    callback is the machine affress of a callback used to handle events in the dialog box. Only advanced users will use anything else than 0. The prototype for the callback routine is described as BrowseCallbackProc in the Win32 API. cbData is any atom. If callback is nonzero, this will be passed as an argument to the callback routine.

         -- ask the user to choose a valid printer name.
         selectedPrinterName = selectDirectory("Choose a printer",BIF_VALIDATE+BIF_BROWSEFORPRINTER,0,0)
    

    See Also: buildDefaultOfn, copyFile, createDirectory, deleteFile, getCurrentDirectory, getFileInfo, getFullPathName, getOpenFileName, getOpenFileNameEx, getSaveFileName, getTempFile, getTempPath, moveFile, setCurrentDirectory, setFileAttr, setSearchPaths, w32FileOpen, w32FindFile


    Documentation for Win32lib v0.70.18
    Table of Contents

    [proc]
    setCurrentDirectory
    (sequence Path)

    Sets the current directory

    Category: File Operations

    Path is the name of directory path you wish to set as the new current directory.

    Example

          -- set the new directory to current dirs parent.
          setCurrentDirectory("..")
          -- set directory to BIN folder
          setCurrentDirectory("BIN")
    

    See Also: buildDefaultOfn, copyFile, createDirectory, deleteFile, getCurrentDirectory, getFileInfo, getFullPathName, getOpenFileName, getOpenFileNameEx, getSaveFileName, getTempFile, getTempPath, moveFile, selectDirectory, setFileAttr, setSearchPaths, w32FileOpen, w32FindFile


    Documentation for Win32lib v0.70.18
    Table of Contents

    [func]
    setFileAttr
    (sequence pPath, object pAttribs)

    Sets one or more attibutes for the specified file.

    Category: File Operations

    ret: ATOM: 0 if this fails. pPath is a file's path and name
    pAttribs is either an atom that contains all the required attributes, or a sequence containing a list of required attrbutes.

    Examples:

          if setFileAttr("C:\\spec.fil", FILE_ATTRIBUTE_READONLY) = 0 then
              errmsg("Failed to set file to read only")
          end if
    

    See Also: buildDefaultOfn, copyFile, createDirectory, deleteFile, getCurrentDirectory, getFileInfo, getFullPathName, getOpenFileName, getOpenFileNameEx, getSaveFileName, getTempFile, getTempPath, moveFile, selectDirectory, setCurrentDirectory, setSearchPaths, w32FileOpen, w32FindFile


    Documentation for Win32lib v0.70.18
    Table of Contents

    [func]
    setSearchPaths
    (object Paths)

    Possibly sets the file system paths to use when searching for files

    Returns: SEQUENCE: The previously set paths.

    Category: File Operations

    The initial search path is empty.
    Paths is a list of one or more directory paths, separated by either commas or semi-colons.

    These paths are used by any of the library routines that take a file name, to search for the file.

    For example: setBitmap() setIcon() loadBitmapFromFile() loadForm() Pass an atom to simply return the current set of paths.

    Example:

          sequence old
          old = setSearchPaths("..\\images\\;..\\sounds\\")
    

    See Also: buildDefaultOfn, copyFile, createDirectory, deleteFile, getCurrentDirectory, getFileInfo, getFullPathName, getOpenFileName, getOpenFileNameEx, getSaveFileName, getTempFile, getTempPath, moveFile, selectDirectory, setCurrentDirectory, setFileAttr, w32FileOpen, w32FindFile


    Documentation for Win32lib v0.70.18
    Table of Contents

    [func]
    w32FileOpen
    (sequence Path, sequence Mode)

    Search the set 'searchpaths' for the file then opens it.

    Returns: INTEGER: File Handle.

    Category: File Operations

    This operates just like the standard open() routine except that when opening a file for reading or appending, it searchs the paths defined by setSearchPaths() for the file.

    Note 1: If the Path contains an explicit drive value (eg. C:) or the path starts with a slash, the defined search paths are not used as the library believes you are specifying a non-relative path.

    Note 2: If the Mode is set for output ("w" or "wb") then the search paths are not used.

    Example:

          VOID = setSearchPaths(".\\images\\;.\\sounds\\")
          fh1 = w32FileOpen("welcome.bmp", "r") -- looks in the search paths
          fh2 = w32FileOPen("welcome.wav", "r") -- looks in the search paths
          fh3 = w32FileOpen("C:\\autoexec.bat", "r") -- does not look in the search paths
    

    See Also: buildDefaultOfn, copyFile, createDirectory, deleteFile, getCurrentDirectory, getFileInfo, getFullPathName, getOpenFileName, getOpenFileNameEx, getSaveFileName, getTempFile, getTempPath, moveFile, selectDirectory, setCurrentDirectory, setFileAttr, setSearchPaths, w32FindFile


    Documentation for Win32lib v0.70.18
    Table of Contents

    [func]
    w32FindFile
    (sequence File)

    Search the set 'searchpaths' for the file and returns its path specification.

    Returns: SEQUENCE: Path name and file name.

    Category: File Operations

    This searchs the current directory and then the paths defined by setSearchPaths() for the File. If it finds the file, it returns the path-file specification.

    Example:

          VOID = setSearchPaths(".\\images\\;.\\sounds\\")
          fh1 = w32FindFile("welcome.bmp") -- returns .\images\welcome.bmp
          fh2 = w32FindFile("welcome.wav") -- returns .\sounds\welcome.wav
          fh3 = w32FindFile("C:\\autoexec.bat") -- returns C:\\autoexec.bat
    

    See Also: buildDefaultOfn, copyFile, createDirectory, deleteFile, getCurrentDirectory, getFileInfo, getFullPathName, getOpenFileName, getOpenFileNameEx, getSaveFileName, getTempFile, getTempPath, moveFile, selectDirectory, setCurrentDirectory, setFileAttr, setSearchPaths, w32FileOpen