Libgdx's Files

Introduction

Libgdx applications run on four different platforms: desktop systems (Windows, Linux, Mac OS X, headless), Android, iOS, and JavaScript/WebGL capable browsers. Each of these platforms handles file I/O a little differently.

Libgdx's Files (code) module provides the ability to:

Read from a file
Write to a file
Copy a file
Move a file
Delete a file

List files and directories

Check whether a file/directory exists

Before we can dive into that aspect of Libgdx, we have to first review the different notions of filesystems for all supported platforms.


Platform Filesystems


Here we review the filesystem paradigms of the platforms Libgdx supports


Desktop (Windows, Linux, Mac OS X, Headless)


On a desktop OS, the filesystem is one big chunk of memory. Files can be referenced with paths relative to the current working directory (the directory the application was executed in) or absolute paths. Ignoring file permissions, files and directories are usually readable and writable by all applications.
//在桌面系统上，文件系统是一个大大块的内存。文件被索引相对于“当前工作目录”（应用被执行的目录）或者绝对路径。
//忽视文件访问权限，文件和目录通常对所有应用是可读可写的。
Android


On Android the situation is a little bit more complex. Files can be stored inside the application's APK either as resources or as assets. These files are read-only. Libgdx only uses the assets mechanism, as it provides raw access to the byte streams and more closely resembles a traditional filesystem. Resources better lend themselves to normal Android applications but introduce problems when used in games. Android manipulates them at load time, e.g. it automatically resizes images.
//在android系统上，这个情况就有点复杂了。文件可以被存储在应用的apk包中，要么作为res资源，或者作为assets。这些文件是只读的。
//Libgdx 只使用assets机制，


Assets are stored in your Android project's assets directory and will be packaged with your APK automatically when you deploy your application. No other application can access these files.
//资源被存储在Android 项目的assets文件夹。部署项目的时候被打包进apk包中。其他应用不能访问这个资源文件。


Files can also be stored on the internal storage, where they are readable and writable. Each installed application has a dedicated internal storage directory. This directory is again only accessible by that application. One can think of this storage as a private working area for the application.
//android系统上，文件也可以被存储在内部存储空间，这里是可读可写的。每一个安装的应用都有一个专门的内部存储目录。这个目录也是只能被该应用访问。你可以把想象成这个应用的私人空间。


Finally, files can be stored on the external storage, such as an SD-card. External storage might not always be available, e.g. the user could pull out the SD-card. Files in this storage location should thus be considered volatile. You will need to add a permission to your AndroidManifest.xml file to be allowed to write to the external storage, see Permissions
//最后，文件也可以被存储在外部存储上，比如SD卡。注意，外部存储可能是不可用的，比如用户拔掉SD卡。
//因此，文件存储在外部要考虑这个不稳定的因素。
//另外，你需要增加一个 权限 在AndroidManifest清单文件里，允许你写数据到外部存储上。


iOS


On iOS all file types are available.
//iOS支持所有的文件类型。


Javascript/WebGL


A raw Javascript/WebGL application doesn't have a traditional filesystem concept. Instead, assets like images are referenced by URLs pointing to files on one or more servers. Modern browsers also support Local Storage which comes close to a traditional read/write filesystem.


Libgdx does some magic under the hood to provide you with a read-only filesystem abstraction.


File (Storage) Types


A file in libgdx is represented by an instance of the FileHandle class. A FileHandle has a type which defines where the file is located. The following table illustrates the availability and location of each file type for each platform.
//文件存储类型
//FileHandle的实例代表了一个文件。
//FileHandle有一个类型，这个类型定义了文件放在哪里。


Classpath
Classpath files are directly stored in your source folders. These get packaged with your jars and are always read-only. They have their purpose, but should be avoided if possible.
//Classpath文件直接存储在你的src文件夹下。
//这些文件被打包进你的jar中，总是只读的。
//这个类型可以存一些资源随着jar包，比如gdx的bitmapFont就在jar中。开发者尽量避免使用这种方式。


Internal
Internal files are relative to the application’s root or working directory on desktops, relative to the assets directory on Android, and relative to the war/assets/ directory of your GWT project. These files are read-only. If a file can't be found on the internal storage, the file module falls back to searching the file on the classpath. This is necessary if one uses the asset folder linking mechanism of Eclipse, see Project Setup
//Internal文件，是相对于应用的根目录，桌面上是工作目录(就是你的工程中desktop项目的根目录)，android上是assets目录，GWT上是war/assets/目录。
//这些文件是只读的。
//如果文件在internal方式没有找到，gdx会按照classpath方式查找。


Local
Local files are stored relative to the application's root or working directory on desktops and relative to the internal (private) storage of the application on Android. Note that Local and internal are mostly the same on the desktop.
//Local文件，是相对于应用的根目录，桌面上是工作目录(就是你的工程中desktop项目的根目录)，android上是应用的私有目录。
//注意，Local 和 internal 类型的存储位置在桌面上差不多都是相同的，都是(你的工程中desktop项目的根目录)。
//我们主要使用这两种存储方式：
//Internal是只读的。  Local是可读可写的。


External
External files paths are relative to the SD card root on Android and to the home directory of the current user on desktop systems.
//External文件，在Android上相对于SD卡的根目录。桌面上是当前用户的home目录(比如，我用Administrator登陆，用的就是Administrator这个目录)。


Absolute
Absolute files need to have their fully qualified paths specified. 
Note: For the sake of portability, this option must be used only when absolutely necessary
//Absolute文件，很简单，直接用全称的文件名。
//注意，为了可移植性，这个方式一般不用的。


Absolute and classpath files are mostly used for tools such as desktop editors, that have more complex file i/o requirements. For games these can be safely ignored. The order in which you should use the types is as follows:
//Absolute and classpath 文件类型，我们一般不用。
//我们只用下面的：


Internal Files: all the assets (images, audio files, etc.) that are packaged with your application are internal files. If you use the Setup UI, just drop them in your Android project's assets folder.
//Internal Files，所有的图片，声音等等。在Android 项目的 assets文件夹下。


Local Files: if you need to write small files, e.g. save a game state, use local files. These are in general private to your application. If you want a key/value store instead, you can also look into Preferences.
//如果你需要写数据到文件中，比如游戏状态时使用local files。
//一般来讲，是应用私有的。如果你想存储 键值对，使用Preferences。


External Files: if you need to write big files, e.g. screenshots, or download files from the web, they should go on the external storage. Note that the external storage is volatile, a user can remove it or delete the files you wrote.
//如果你需要写很大的文件，比如，截屏，下载文件。应该使用external存储。
//注意，外部存储不稳定。用户可能会删除你的文件。


Checking Storage availability and paths
//检查文件的可用性和路径。
The different storage types might not be available depending on the platform your application runs on. You can query this kind of information via the Files module:
//不同的存储类型，可用性也不同。用之前，先检查。
boolean isExtAvailable = Gdx.files.isExternalStorageAvailable();//外部存储是否可用。
boolean isLocAvailable = Gdx.files.isLocalStorageAvailable();//local存储是否可用。
You can also query the root paths for external and local storage:


String extRoot = Gdx.files.getExternalStoragePath();//获得外部存储。
String locRoot = Gdx.files.getLocalStoragePath();//获得local存储。


Obtaining FileHandles
//获得文件句柄
A FileHandle is obtained by using one of the aforementioned types directly from the Files module. The following code obtains a handle for the internal myfile.txt file.


FileHandle handle = Gdx.files.internal("data/myfile.txt");
If you used the [setup UI | Project Setup, Running & Debugging], this file will be contained in your Android project's assets folder, $ANDROID_PROJECT/assets/data to be exact. Your desktop and html projects link to this folder in Eclipse, and will pick it up automatically when executed from within Eclipse.
//android上指的是assets/data/myfile.txt。


FileHandle handle = Gdx.files.classpath("myfile.txt");
The “myfile.txt” file is located in the directory where the compiled classes reside or the included jar files.


FileHandle handle = Gdx.files.external("myfile.txt");
In this case, “myfile.txt” needs to be in the users’ home directory (/home/<user>/myfile.txt on Linux, /Users/<user>/myfile.txt on OSX and C:\Users\<user>\myfile.txt on Windows) on desktop, and in the root of the SD card on Android.
//Linux上指的是 /home/<user>/myfile.txt 
//OSX上指的是 /Users/<user>/myfile.txt 
//Windows上指的是 C:\Users\<user>\myfile.txt
//Android上指的是 SD卡的根目录。


FileHandle handle = Gdx.files.absolute("/some_dir/subdir/myfile.txt");
In the case of absolute file handle, the file has to be exactly where the full path points. In /some_dir/subdir/ of the current drive on Windows or the exact path on linux, MacOS and Android.
//Windows上 应用在哪个磁盘，就从磁盘根目录开始。比如，E:/some_dir/subdir/myfile.txt
//linux, MacOS and Android.直接指定。


FileHandle instances are passed to methods of classes the are responsible for reading and writing data. E.g. a FileHandle needs to be specified when loading an image via the Texture class, or when loading an audio file via the Audio module.
//读写文件时，需要指定特定文件类型。


Listing and Checking Properties of Files


Sometimes it is necessary to check for the existence of a specific file or list the contents of a directory. FileHandle provides methods to do just that in a concise way.
//有时候，需要检查文件的存在，或者列出一个目录的内容。FileHandle 有方便的方法。


Here's an example that checks whether a specific file exists and whether a file is actually a directory or not.


boolean exists = Gdx.files.external("doitexist.txt").exists();//external文件是否存在
boolean isDirectory = Gdx.files.external("test/").isDirectory();//test 是不是目录
Listing a directory is equally simple:


FileHandle[] files = Gdx.files.local("mylocaldir/").list();//列出这个目录下的所有文件。
for(FileHandle file: files) {
   // do something interesting here
}
WARNING: If you don't specify a folder the list will be empty.
//废话，不指定目录时，list为空。


Note: Listing of internal directories is not supported on Desktop.
//真的要注意：在 Desktop 上，“ internal ”类型的目录不支持列出目录内容。


We can also ask for the parent directory of a file or create a FileHandle for a file in a directory (aka "child").
//关于，父目录 和 子文件 的操作。
FileHandle parent = Gdx.files.internal("data/graphics/myimage.png").parent();
FileHandle child = Gdx.files.internal("data/sounds/").child("myaudiofile.mp3");
parent would point to "data/graphics/", child would point to data/sounds/myaudiofile.mp3".


There are many more methods in FileHandle that let you check for specific attributes of a file. Please refer to the Javadocs for detail.
//更多方法查看API


Note: These functions are mostly unimplemented in the HTML5 back-end at the moment. Try not to rely on them too much if HTML5 will be a target of your application.
//HTML5上 很多方法都没有实现。避免。


Error Handling


Some operations on FileHandles can fail. We adopted RuntimeExceptions to signal errors instead of checked Exceptions. Our reasoning goes like this: 90% of the time we will access files that we know exist and are readable (e.g. internal files packaged with our application).
//出现错误时请注意。


Reading from a File
//读取文件，字符串或者字节。
After obtaining a FileHandle, we can either pass it to a class that knows how to load content from the file (e.g. an image), or read it ourselves. The latter is done through any of the input methods in the FileHandle class. The following example illustrates how to load text from an internal file:


FileHandle file = Gdx.files.internal("myfile.txt");
String text = file.readString();
If you have binary data, you can easily load the file into a {{{byte[]}}} array:


FileHandle file = Gdx.files.internal("myblob.bin");
byte[] bytes = file.readBytes();
The FileHandle class has many more read methods. Check the Javadocs for more information.


Writing to a File
//写文件，字符串或者字节。
Similarly to reading files, FileHandle also provides methods to write to a file. Note that only the local, external and absolute file types support writing to a file. Writing a string to a file works as follows:


FileHandle file = Gdx.files.local("myfile.txt");
file.writeString("My god, it's full of stars", false);
The second parameter of FileHandle#writeString specifies if the content should be appended to the file. If set to false, the current content of the file will be overwritten.
//写文件时，注意 覆盖 还是追加。


One can of course also write binary data to a file:


FileHandle file = Gdx.files.local("myblob.bin");
file.writeBytes(new byte[] { 20, 3, -2, 10 }, false);
There are many more methods in FileHandle that facilitate writing in different ways, e.g. using OutputStream. Again, refer to the Javadocs for details.
//写文件时，我们常用 OutputStream，查看API。


Deleting, Copying, Renaming and Moving Files/Directories
// 文件或目录的 删除，复制，重命名。
These operations are again only possible for writable file types (local, external, absolute). 
Note however, that the source for a copying operation can also be a read only FileHandle. A few examples:
//当然，这些操作只能针对于可写的文件类型。(local, external, absolute 是可读可写的。internal，classpath是只读的。)
//把一个internal类型的文件 复制到 一个local类型的文件，这个local类型的文件就成可读可写的。但原来的internal文件仍是只读的。
FileHandle from = Gdx.files.internal("myresource.txt");
from.copyTo(Gdx.files.external("myexternalcopy.txt");


Gdx.files.external("myexternalcopy.txt").rename("mycopy.txt");
Gdx.files.external("mycopy.txt").moveTo(Gdx.files.local("mylocalcopy.txt"));


Gdx.files.local("mylocalcopy.txt").delete();
Note that source and target can be files or directories.
//文件和目录都可以使用同样的操作。
For more information on available methods, check the FileHandle Javadocs.