NOTE: This tutorial was written in march 2010. It is extremely outdated. Please go to the new fangled wiki at http://code.google.com/p/libgdx/wiki/TableOfContents?tm=6
It’s been a while since the last post on libgdx. Let’s see with how files get handled by libgdx.
As you might already know file handling on Android is a bit different as compared to a desktop environment. Each application can have resources and assets which are packaged within the apk of an Android application. Apart from these files you can also access external storage paths like the SD-card.
Libgdx aims to be a cross platform library so i had to map this resources and assets paradigmn of an Android application to also work on the desktop. The first thing i did was throwing out support for resources, they just can’t be mapped in a sane way to the desktop. So if you package files with your application on Android you will store them as assets.
In libgdx there’s 3 types of files: internal, external and absolut files. Internal files refer to assets on Android and to any file relative to the root directory of the application on the desktop. External files refer to files on the SD-card on Android and to any file in the home directory of the current user on the desktop. Finally, absolute files are just that, fully qualified file names.
Internal files can only be read as there’s no way to create new assets in an APK. To minimize confusion it’s also not allowed to write internal files on the desktop. External files can be read and written to, the same is true for absolute files.
So how do you get access to the various files? Via the Files interface that you can get from an Application via a call to Application.getFiles(). Here’s the interface in short:
public interface Files
public enum FileType
public InputStream readFile( String fileName, FileType type );
public OutputStream writeFile( String filename, FileType type );
public boolean makeDirectory( String directory, FileType type );
public String listDirectory( String directory, FileType type );
public FileHandle getFileHandle( String filename, FileType type );
The enum FileType specifies the three different file types, internal, external and absolute. It is used with all the methods of the Files interface to specify which file type the filename or directory name is pointing to. Depending on the FileType the given filename/directory will then be relative to asset directory/application root directory for internal files, relative to the SD-card/home directory for external files and absolut files will be just that, absolut.
Files.readFile() and Files.writeFile() go the old way of the InputStream and OutputStream. They do what you’d expect. Note that none of the methods throws an Exception, instead null is returned in case something bad happened.
Files.makeDirectory() and Files.listDirectory should be easily understandable too.
Finally there’s Files.getFileHandle which returns an instance of FileHandle. A FileHandle is a plattform specific wrapper for a file descriptor. This is used with some of the other classes in libgdx, namely the sound module and the graphics module. The reason is that many APIs on Android don’t directly work with InputStreams and OutputStreams as their implementation is done in native code which can’t handle streams. Thus i had to introduce this FileHandle wrapper which will get passed to those APIs instead of an InputStream.
That’s it for now.