NGDesktop File (ref)

(part of package 'NGDesktop File')

You can access it in code via: plugins.ngdesktopfile

API

appendToTXTFile(path,text,encoding)

Synchronously append data to a file, creating the file if it does not yet exist.

Parameters:

• {String} path - file's full path

• {String} text - text to be added

• {String} [encoding] - default utf8

Returns: Boolean True if the data was successfully appended to the file; otherwise, false.

---

clearTempFiles()

Clears the directory where temporary files are stored (e.g. when using writeTempFileSync(bytes)).

Returns: Boolean True if the temporary files directory was successfully cleared; otherwise, false.

---

copyFile(src,dest,overwriteDest)

Synchronously copies src to dest. By default, dest is overwritten if it already exists.

Parameters:

• {String} src - source filepath to copy
• {String} dest - destination filepath of the copy operation
• {Boolean} [overwriteDest] - default true

Returns: Boolean True if the file was successfully copied; otherwise, false.

---

createFolder(path)

Synchronously creates a folder, including any necessary but nonexistent parent folders.

Parameters:

• {String} path - folders full path

Returns: Boolean True if the folder was successfully created; otherwise, false.

---

deleteFile(path,errorCallback)

Deletes the given file, optionally calling the error callback when unsuccessful

Parameters:

• {String} path The full path of the file to be deleted.
• {Function} [errorCallback] An optional callback function that will be invoked if the deletion fails.

---

deleteFileSync(path)

Delete the given file, returning a boolean indicating success or failure

Parameters:

• {String} path The full path of the file to be deleted.

Returns: Boolean True if the file was successfully deleted; otherwise, false.

---

deleteFolder(path)

Synchronously deletes a folder, fails when folder is not empty

Parameters:

• {String} path - folders full path

Returns: Boolean True if the folder was successfully deleted; otherwise, false.

---

exists(path)

Test whether or not the given path exists by checking with the file system. It returns true if the path exists, false otherwise.

Parameters:

• {String} path - file's full path

Returns: Boolean True if the specified path exists in the file system; otherwise, false.

---

getFileStats(path)

Return a 'stats' object containing related file's information's. Please use forward slashes (/) instead of backward slashes in the path

Parameters:

• {String} path The full path of the file whose statistics are to be retrieved.

Returns: CustomType<ngdesktopfile.stats> An object containing file-related information.

---

getPath(path)

Retrieves the path to a special directory or file associated with the given name.

Parameters:

• {String} path {('home' | 'desktop' | 'temp' | 'documents' | 'downloads')} name - The name of the directory or file.

Returns: String The path to a special directory or file associated with the name, or an empty string if the name is not one of the allowed values.

---

getReadOnly(path)

Verify readonly status on the specified path. Returns true for readonly otherwise false

Parameters:

• {String} path - directory's full path

Returns: Boolean True if the file or folder is read-only; otherwise, false.

---

homeDir()

Returns the home dir of the user like c:/users/[username] under windows. Will return always a both with forward slashes.

Returns: String The full path of the user's home directory, using forward slashes.

---

listDir(path)

returns an array of filenames that are in the given path. Please use forward slashes (/) instead of backward slashes.

Parameters:

• {String} path The full path of the directory to list files from.

Returns: Array<String> An array of filenames present in the specified directory path.

---

openFile(path)

Opens a file specified at the given path on the client. It will open it in the desktop's default manner. This path must exist on the client's machine, you can't open a file with a path pointing to a file on the server; use writeFile() first to write it to the clients machine.

If it fails, it returns a string containing the error message corresponding to the failure. If the file has been successfully opened, it will return an empty string.

Parameters:

• {String} path - file's full path on the client.

Returns: String An empty string if the file was successfully opened or a string containing the error message corresponding to the failure otherwise.

---

readFile(callback,path)

Reads the given bytes of a path, the callback is a function that will get as parameters the 'path' as a String and the 'file' as a JSUpload object If an error is happening in the browser then this error will be given as a 3rd argyument and the second file argument is then null. If the path is missing or contain only the file name then the native system dialog for opening files it is called. Please use forward slashes (/) instead of backward slashes in the path/filename

Parameters:

• {Function} callback A function that receives the file path as a string and the file content as a JSUpload object or a 3rd argument with the error message.
• {String} [path] The full path of the file to read. If omitted or only a filename is provided, a file open dialog will be shown.

---

readFileSync(path)

Reads and returns the content of the given file This will throw an error if something goes wrong on the client, the error is then the message string. So this needs to be try/catched

Parameters:

• {String} [path] The full path of the file to read.

Returns: Object The content of the file.

---

readTXTFileSync(path,encoding)

Reads and returns the text of the given path/filename

Parameters:

• {String} path The full path of the file to read.
• {String} [encoding] Optional, default 'utf8'

Returns: String The content of the file as a string, or an empty string if the file could not be read.

---

renameFile(oldPath,newPath)

Synchronously rename file at oldPath to the pathname provided as newPath. In the case that newPath already exists, it will be overwritten.

Parameters:

• {String} oldPath - old file full path
• {String} newPath - new file full path

Returns: Boolean True if the file was successfully renamed; otherwise, false.

---

selectDirectory(callback)

Select a folder and pass its path to the callback.

Parameters:

• {Function} callback A function that receives the selected folder's path as an argument.

---

selectDirectorySync(path)

Return the selected folder.

Parameters:

• {String} [path] The initial path to open the directory selection dialog at.

Returns: String The full path of the selected folder, or an empty string if no folder was selected.

---

selectFileSync(path)

Return the selected file.

Parameters:

• {String} [path] The initial path to open the file selection dialog at.

Returns: String The full path of the selected file, or an empty string if no file was selected.

---

setReadOnly(path,flag)

Set permisions to the specified file. If readOnly parameter is false, the file permisions flags will be set to read/write mode

Parameters:

• {String} path - File path
• {Boolean} flag If true, sets the file to read-only mode; if false, allows read/write access.

Returns: Object True if the file permissions were successfully updated; otherwise, false.

---

showOpenDialog(callback,options)

Shows a file open dialog and calls the callback with the selected file path(s).

For the options object see https://www.electronjs.org/docs/api/dialog#dialogshowopendialogbrowserwindow-options

The core options are:

• title: String the dialog title

• defaultPath: String the default (starting) path

• buttonLabel: String custom label for the confirmation button, when left empty the default label will be used.

• filters: Array<{name: String, extensions: Array<String>}> an array of file filters (e.g. [{ name: 'Images', extensions: ['jpg', 'png', 'gif'] }])

• properties: an Array of property keywords such as:

  • openFile - Allow files to be selected.

  • openDirectory - Allow directories to be selected.

  • multiSelections - Allow multiple paths to be selected.

Parameters:

• {Function} callback A function that receives the selected file path(s) as an argument.
• {Object} [options] {{title: String=, defaultPath: String=, buttonLabel: String=, filters: Array<{name: String, extensions: Array<String>}>=, properties: Array<String>}}

---

showOpenDialogSync(options)

Shows a file open dialog and returns the selected file path(s).

To not block any process, showOpenDialog with a callback method is preferred over this method.

For the options object see https://www.electronjs.org/docs/api/dialog#dialogshowopendialogsyncbrowserwindow-options

Core options are:

• title: String the dialog title

• defaultPath: String the default (starting) path

• buttonLabel: String custom label for the confirmation button, when left empty the default label will be used.

• filters: Array<{name: String, extensions: Array<String>}> an array of file filters (e.g. [{ name: 'Images', extensions: ['jpg', 'png', 'gif'] }])

• properties: an Array of property keywords such as:

  • openFile - Allow files to be selected.

  • openDirectory - Allow directories to be selected.

  • multiSelections - Allow multiple paths to be selected.

Parameters:

• {Object} [options] {{title: String=, defaultPath: String=, buttonLabel: String=, filters: Array<{name: String, extensions: Array<String>}>=, properties: Array<String>}} [options]

Returns: Array<String> An array of selected file or directory paths, or an empty array if no selection was made.

---

showSaveDialog(callback,options)

Shows a file save dialog and calls the callback method with the file path.

For the options object see https://www.electronjs.org/docs/api/dialog#dialogshowsavedialogbrowserwindow-options

Core options are:

• title: String the dialog title

• defaultPath: String - absolute directory path, absolute file path, or file name to use by default.

• buttonLabel: String - custom label for the confirmation button, when left empty the default label will be used.

• filters: Array<{name: String, extensions: Array<String>}> - an array of file filters (e.g. [{ name: 'Images', extensions: ['jpg', 'png', 'gif'] }])

Parameters:

• {Function} callback A function that receives the selected file path as an argument.
• {Object} [options] {{title: String=, defaultPath: String=, buttonLabel: String=, filters: Array<{name: String, extensions: Array<String>}>=}} [options]

---

showSaveDialogSync(options)

Shows a file save dialog.

To not block any process, showSaveDialog with a callback method is preferred over this method.

For the options object see https://www.electronjs.org/docs/api/dialog#dialogshowsavedialogsyncbrowserwindow-options

Core options are:

• title: String the dialog title

• defaultPath: String - absolute directory path, absolute file path, or file name to use by default.

• buttonLabel: String - custom label for the confirmation button, when left empty the default label will be used.

• filters: Array<{name: String, extensions: Array<String>}> - an array of file filters (e.g. [{ name: 'Images', extensions: ['jpg', 'png', 'gif'] }])

Parameters:

• {Object} [options] {{title: String=, defaultPath: String=, buttonLabel: String=, filters: Array<{name: String, extensions: Array<String>}>=}}

Returns: String The full path of the selected file if the user confirmed the dialog, or an empty string if the dialog was canceled.

---

tmpDir()

Returns the tmp directory of the client machine. Will return always a both with forward slashes.

Returns: String The full path of the system's temporary directory, using forward slashes.

---

unwatchDir(path)

Stop watching a directory found at the given path.

Parameters:

• {String} path The full path of the directory to stop watching for changes.

---

unwatchFile(path)

Removes the watch to the file that was added by the watchFile() function. Please use forward slashes (/) instead of backward slashes in the path/filename

Parameters:

• {String} path The full path of the file to stop watching for modifications.

---

watchDir(path,callback)

Watches a directory for changes at the given path.

Parameters:

• {String} path - directory's full path
• {Function} callback - the callback method to be executed

---

watchFile(path,callback)

Watches a give path, that should represent a file, for modifications. Please use forward slashes (/) instead of backward slashes in the path/filename

Parameters:

• {String} path The full path of the file to watch for modifications.
• {Function} callback A function that will be triggered when the file is modified.

---

writeFile(path,bytes,callback,passThru)

Writes the given bytes to the path; if the path has sub-directories that are not there, then those are created. If the path is missing or contains only the file name, then the native system dialog for saving files is used.

When done, the optional callback is called with the written path (as a string), or 'error'. An optional passThru object is also passed back to the callback function. Please use forward slashes (/) instead of backward slashes in path/filename.

Parameters:

• {String} path The full path where the file will be written. If only a filename is provided, a save dialog will be shown.
• {Array<Number>} bytes The binary data to write to the file.
• {Function} [callback] An optional function that receives the written file path or an 'error' string if the operation fails.
• {Object} [passThru] An optional object that will be passed back to the callback function.

---

writeTXTFileSync(path,text_data,encoding)

Writes text to the given path/filename

Parameters:

• {String} path The full path of the file where the text will be written.
• {String} text_data The text content to write into the file.
• {String} [encoding] Encoding code (default 'utf8')

Returns: Boolean True if the text was successfully written to the file; otherwise, false.

---

writeTempFileSync(bytes)

A synchronous way to write bytes to a temporary file with a unique pseudo-random name, in a directory for temporary files. This directory will be cleared when the ngDesktop window is closed or when clearTempFiles() is called.

The function returns the path of the created file as a string.

Parameters:

• {Array<Number>} bytes The binary data to be written to the temporary file.

Returns: String The full path of the created temporary file.

---

Types

stats

Represents file system statistics for a file or directory. scripting type: CustomType<ngdesktopfile.stats>

• atimeMs

  • The last access time in milliseconds.

  • Type: long
• birthtimeMs

  • The birth time (creation time) in milliseconds.

  • Type: long
• blksize

  • The block size for file system I/O.

  • Type: long
• blocks

  • The number of blocks allocated for the file.

  • Type: long
• ctimeMs

  • The last status change time in milliseconds.

  • Type: long
• dev

  • The device ID.

  • Type: long
• gid

  • The group ID of the file's owner.

  • Type: long
• ino

  • The inode number.

  • Type: long
• isBlockDevice

  • Indicates if the file is a block device.

  • Type: boolean
  • Default Value: false

• isCharacterDevice

  • Indicates if the file is a character device.

  • Type: boolean
  • Default Value: false

• isDirectory

  • Indicates if the path is a directory.

  • Type: boolean
  • Default Value: false

• isFIFO

  • Indicates if the file is a FIFO (named pipe).

  • Type: boolean
  • Default Value: false

• isFile

  • Indicates if the path is a regular file.

  • Type: boolean
  • Default Value: false

• isSocket

  • Indicates if the file is a socket.

  • Type: boolean
  • Default Value: false

• isSymbolicLink

  • Indicates if the file is a symbolic link.

  • Type: boolean
  • Default Value: false

• mode

  • The file mode (permissions).

  • Type: long
• mtimeMs

  • The last modification time in milliseconds.

  • Type: long
• nlink

  • The number of hard links.

  • Type: long
• rdev

  • The device ID (if the file is a special file).

  • Type: long
• uid

  • The user ID of the file's owner.

  • Type: long

---