xtra BinFile
-- v0.13 (c) 2017 Valentin Schmidt
new object me

-- FILE INSTANCE FUNCTIONS
bx_fopen object me, string filename, string mode
bx_fclose object me
bx_fread object me, integer n -- returns ByteArray
bx_fwrite object me, any stringOrByteArray, *maxLength
bx_ftell object me
bx_fseek object me, any pos, *whence
bx_fsize object me

-- FILE UTILITIES
*bx_file_get_contents string filename -- returns ByteArray
*bx_file_put_contents string filename, any stringOrByteArray
*bx_file_size string filename
*bx_file_date string filename -- returns list of UNIX timestamps for creationTime, lastWriteTime and lastAccessTime (or VOID)
*bx_file_delete string filename
*bx_file_recycle string filename
*bx_file_truncate string filename, any size
*bx_file_copy string filename, string newName

-- FOLDER UTILITIES
*bx_folder_create string foldername
*bx_folder_delete string foldername -- only deletes empty folders
*bx_folder_get_contents string foldername -- non-recursive, returns List
*bx_folder_copy string foldername, string newName

-- FILE AND FOLDER UTILITIES
*bx_exists string fileOrFolderName
*bx_rename string fileOrFolderName, string newName

-- FILE DIALOGS
*bx_display_open *title, filterMask, defaultFileName, flags, displayMode
*bx_display_save *title, filterMask, defaultFileName, flags, displayMode


INFOS
=====

Free cross-platform xtra for file read/write operations and various filesystem utilities.


Win-Only Features
=================

1.) Large file support

BinFile xtra supports large files. Positions beyond the 2 GB maxInteger limit
can be specified as negative integer (which the xtra interprets as unsigned int)
or float values.

Functions bx_ftell, bx_fsize, bx_filesize return values according to the following scheme:
- integers for values below or equal to the maxInteger (= 2147483647 = 2GB)
- floats for values above the maxInteger


2.) File Open/Save Dialogs

*bx_display_open *title, filterMask, defaultFileName, flags, displayMode
*bx_display_save *title, filterMask, defaultFileName, flags, displayMode

All arguments are optional.


Argument 'filterMask' (optional)

"<description>,<type>,<description>,<type>,..."


  Code Example:

  filterMask = "Text Files (*.txt),*.txt,All Files (*.*),*.*"


Argument 'flags' (optional)

  -- FLAGS
  OFN_READONLY                 = 1
  OFN_OVERWRITEPROMPT          = 2
  OFN_HIDEREADONLY             = 4
  OFN_NOCHANGEDIR              = 8
  OFN_SHOWHELP                 = 16
  OFN_ENABLEHOOK               = 32
  OFN_ENABLETEMPLATE           = 64
  OFN_ENABLETEMPLATEHANDLE     = 128
  OFN_NOVALIDATE               = 256
  OFN_ALLOWMULTISELECT         = 512
  OFN_EXTENSIONDIFFERENT       = 1024
  OFN_PATHMUSTEXIST            = 2048
  OFN_FILEMUSTEXIST            = 4096
  OFN_CREATEPROMPT             = 8192
  OFN_SHAREAWARE               = 16384
  OFN_NOREADONLYRETURN         = 32768
  OFN_NOTESTFILECREATE         = 65536
  OFN_NONETWORKBUTTON          = 131072
  OFN_NOLONGNAMES              = 262144
  OFN_EXPLORER                 = 524288
  OFN_NODEREFERENCELINKS       = 1048576
  OFN_LONGNAMES                = 2097152
  OFN_ENABLEINCLUDENOTIFY      = 4194304
  OFN_ENABLESIZING             = 8388608

  Multiple flags are combined via bitOr().


  Code Example:

  flags = OFN_EXPLORER
  flags = bitOr(flags, OFN_HIDEREADONLY)
  flags = bitOr(flags, OFN_OVERWRITEPROMPT)
  flags = bitOr(flags, OFN_ALLOWMULTISELECT)


Argument 'displayMode' (optional)

  -- DISPLAY_MODE
  ODM_VIEW_ICONS  = 28713
  ODM_VIEW_LIST   = 28715
  ODM_VIEW_DETAIL = 28716
  ODM_VIEW_THUMBS = 28717
  ODM_VIEW_TILES  = 28718


  Code Example:

  displayMode = ODM_VIEW_THUMBS -- open dialog in ThumbnailMode