Skip to content

Latest commit

 

History

History
322 lines (223 loc) · 6.7 KB

app_dirs.md

File metadata and controls

322 lines (223 loc) · 6.7 KB
Raw

app_dirs.dart

A library to locate common directories using platform-specific conventions.

To use:

var appDirs = getAppDirs(application: 'FooBar App');
var configDir = appDirs.config;
...

getAppDirs()

AppDirs getAppDirs({
  String? qualifier,
  String? organization,
  String application,
  bool preferUnixConventions = false,
})

Returns the directory locations for the current platform's conventions, factoring in information like the application name.

The application, qualifier and organization information is used to construct the correct app path. For instance, in Unix that path might be 'foobar-app', on Windows 'Baz Corp/Foo Bar App' and on MacOS 'org.Baz-Corp.Foo-Bar-App'.

The preferUnixConventions param is used to configure the MacOS directory conventions used. This library defaults to the standard Mac conventions - an app's config directory may look something like ~/Library/Application support/org.Baz-Corp.Foo-Bar-App. However, for some apps - like command-line tools - a Unix convention may be more familiar to users. Specify preferUnixConventions: true to use thos conventions instead (the above path may then look something like ~/.config/foobar-app).

Class Directories

class Directories

The main entry-point to package:app_dirs.

Most callers will use appDirs; this returns the correct platform directories to use given your application metadata.

baseDirs returns the base directories for the current platform. These are the standard directories for the platform's conventions, but without taking into account things like the application name.

baseDirs

final BaseDirs baseDirs

The base directories for the current platform. These are the standard directories for the platform's conventions, but without taking into account things like the application name.

Most applications should instead use Directories.getAppDirectories to locate directories. That will take in account things like the application and organization name, and will locate directories using the platform's conventions.

Directories()

Directories({Map<String, String>? env, OperatingSystem? os})

Create a new Directories instance.

The env and os parameters allow you to override the system defaults. This is generally only useful for testing.

appDirs()

AppDirs appDirs({
  String? qualifier,
  String? organization,
  String application,
  bool preferUnixConventions = false,
})

Returns the directory locations for the current platform's conventions, factoring in information like the application name.

The application, qualifier and organization information is used to construct the correct app path. For instance, in Unix that path might be 'foobar-app', on Windows 'Baz Corp/Foo Bar App' and on MacOS 'org.Baz-Corp.Foo-Bar-App'.

The preferUnixConventions param is used to configure the MacOS directory conventions used. This library defaults to the standard Mac conventions - an app's config directory may look something like ~/Library/Application support/org.Baz-Corp.Foo-Bar-App. However, for some apps - like command-line tools - a Unix convention may be more familiar to users. Specify preferUnixConventions: true to use thos conventions instead (the above path may then look something like ~/.config/foobar-app).

toString()

String toString()

Class BaseDirs

abstract class BaseDirs

The base directories for the current platform. These are the standard directories for the platform's conventions, but without taking into account things like the application name.

For directory locations that take application name into account, see Directories.appDirs and AppDirs.

BaseDirs()

BaseDirs()

get home

String get home

The user's home directory. On Unix like systems, this will be $HOME. On Windows, this will be $USERPROFILE.

get cache

String get cache

The directory relative to which user-specific non-essential data files should be stored.

get config

String get config

The directory for user-specific configuration files.

get data

String get data

The directory for user-specific data files.

get dataLocal

String get dataLocal

The directory for local, user-specific data files.

On Windows, this will return %LOCALAPPDATA% (vs. %APPDATA% for data).

get preference

String get preference

The directory for user preference data.

get state

String? get state

The directory for user-specific state data.

This is data that should persist between (application) restarts, but that is not important or portable enough to the user that it should be stored in data. Some examples are actions history (recently used files, ...) or current state of the application that can be reused on a restart (window layout, open files, ...).

Class AppDirs

abstract class AppDirs

The directory locations for the current platform's conventions. This class factors in information like the application and company name.

baseDirs

final BaseDirs baseDirs

The base directories backing this AppDirs instance.

AppDirs()

AppDirs({BaseDirs baseDirs})

get cache

String get cache

The directory relative to which user-specific non-essential data files should be stored.

get config

String get config

The directory for user-specific configuration files.

get data

String get data

The directory for user-specific data files.

get dataLocal

String get dataLocal

The directory for local, user-specific data files.

On Windows, this will return a directory relative to %LOCALAPPDATA% (vs. %APPDATA% for data).

get preference

String get preference

The directory for user preference data.

get state

String? get state

The directory for user-specific state data.

This is data that should persist between (application) restarts, but that is not important or portable enough to the user that it should be stored in data. Some examples are actions history (recently used files, ...) or current state of the application that can be reused on a restart (window layout, open files, ...).

Enum OperatingSystem

enum OperatingSystem

The operating system to assume for directory conventions; passed as a param to Directories.

value unix

OperatingSystem unix

value windows

OperatingSystem windows

value mac

OperatingSystem mac

OperatingSystem()

OperatingSystem()

detect()

static OperatingSystem detect()

Return the correct OperatingSystem enum for the current platform.