A new build of Corona SDK is now available to subscribers. Not a subscriber? Subscribe now.
CoronaSDK 2012.751 | Released: 22 Feb 2012, 2:44am | What's New | Download Now
system.DocumentsDirectory
Description:
Used with system.pathForFile to create a path for storing and retrieving files that need to persist between application sessions. The path is "/Documents".
This property can also be used with other APIs requesting a "baseDirectory" as a parameter (e.g., display.newImage, display.save, media.playSound, etc.).
On the Corona Simulator this will be in a sandboxed folder on a per-application basis. You can view the directories and the files by clicking on "Show Project Sandbox" in the Simulator.
Syntax:
path = system.pathForFile( filename, system.DocumentsDirectory )
Example:
local path = system.pathForFile( "data.txt", system.DocumentsDirectory ) -- io.open opens a file at path. returns nil if no file found local fh, reason = io.open( path, "r" ) if fh then -- read all contents of file into a string local contents = fh:read( "*a" ) print( "Contents of " .. path .. "\n" .. contents ) else print( "Reason open failed: " .. reason ) -- display failure message in terminal -- create file because it doesn't exist yet fh = io.open( path, "w" ) if fh then print( "Created file" ) else print( "Create file failed!" ) end local numbers = {1,2,3,4,5,6,7,8,9} fh:write( "Feed me data!\n", numbers[1], numbers[2], "\n" ) for _,v in ipairs( numbers ) do fh:write( v, " " ) end fh:write( "\nNo more data\n" ) end io.close( fh )
Parameters:
None.
Returns:
userdata
Returns a special userdata constant pointing to the "/Documents" directory. (This is not a string.)
Remarks:
Use the Documents directory for storing files that need to persist after the application exits. Use the Temporary directory for files only needed while the application is running. Files cannot be written to the Resource directory -- it's read-only and contains the files bundled in your application's project folder.
Files in the Documents directory are NOT removed when the app is updated to a new version.
Supported on operating systems and platforms for build numbers shown:
- Mac OS X:Corona SDK 1.0
- Windows:Corona SDK 2.0
- iOS:Corona SDK 1.0
- Android:Corona SDK 2.0
- API tags:
Replies
Posted on Wed, 2011-05-11 08:03
#2
I added the "/Documents" path to the API page since it was missing. You can view the structure of the directories in the Corona Simulator by clicking on "Show Project Sandbox".
Thanks for the feedback.
Posted on Wed, 2011-10-26 01:37
#3
one simple questions: if I update my app, will those files in the /Documents folder still exist? If so, game progress, unlocked items etc could be stored as a JSON string in a .dat file?
Posted on Wed, 2011-10-26 08:09
#4
Files in the /Documents folder still exist after an app update. Files in the /Temporary folder will not exist.
Posted on Sat, 2011-11-19 07:07
#5
@Tom That will good if you can add this to corona docs, i was searching this question in the forums, but found it here,Thanks a lot!
Posted on Sat, 2011-11-19 08:14
#6
There was a mention of this in the system.TemporaryDirectory but I added the information in the Remarks section of this page. Thanks.
Posted on Fri, 2011-11-25 04:13
#7
Is the DocumentsDirectory local to each app? I would like to be able to use the same database from two separate apps, with either of them able to alter the data. I've tried using the same name for the database in each app, but they remain exclusive to the app that is running, so updates of the data from one app do not carry across to the other app. Is there any way to save a data file so that I can access it and alter it from more than one app?
Any ideas gratefully received!
Thanks
Pete
Posted on Fri, 2011-11-25 08:30
#8
As required by the OS, all apps are "sandboxed" and have their own copy of system folders which are isolated from other apps.
Posted on Fri, 2011-11-25 08:43
#9
Thanks Tom.
Just as a matter of interest, how does something like Documents to Go save files to the Documents folder?
Posted on Thu, 2011-12-01 12:03
#10
Thanks to all above for a helpful thread.
With respect to image caching, under the API description for "display.newImageRect()" the remarks say
"A negative side-effect to the image caching is the comparison is based on the file name and not the file content. This means if an image file is displayed and then deleted from the directory, any file loaded after that with the same file name will still display the previous cached image. Use a different file name to avoid this problem."
Question: Other than a specific delete line in the game code and terminating the game, what would cause the image file to be deleted from the Document directory?
Thanks!
Posted on Mon, 2011-12-26 04:35
#11
in the IOS the file will be saved in a folder called "Document", but in Android where it will be saved?
Posted on Mon, 2012-02-20 15:45
#12
Hmm seems a bit ifan centric
On android system.documentsdirectory seems to point to /data/data/com.your.package/app_data. But this is unreadable from the UI.
Does Corona provide an easy way to read and write to the sdcard on android? it would be nice to have a system.SDCardDirectory parameter that automatically creates the com.your.app folder under /sdcard
> "On the Corona Simulator this will be in a sandboxed folder on a per-application basis."
Sorry, but what does this mean?
You've got system.pathForFile followed by what looks like 'no path', just a local file.
What does the physical directory structure of the local folder look like in a corona application when using file i/o?
Is there a /Documents directory?
The above example isn't all that helpful because it's not clear where the "data.txt" file lives? Is it in the root directory?