# tray

**Repository Path**: HarmonyOS-tpc/tray

## Basic Information

- **Project Name**: tray
- **Description**: a Preferences replacement for openharmony
- **Primary Language**: Unknown
- **License**: Apache-2.0
- **Default Branch**: master
- **Homepage**: None
- **GVP Project**: No

## Statistics

- **Stars**: 3
- **Forks**: 0
- **Created**: 2021-04-15
- **Last Updated**: 2023-04-17

## Categories & Tags

**Categories**: harmonyos-toolkit

**Tags**: None

## README

## Tray - a Preferences replacement for openharmony

## Introduction
Tray is this mentioned _explicit cross-process data management approach_. Tray also provides an advanced API which makes it super easy to access and maintain your data with upgrade and migrate mechanisms. Welcome to Preferences 2.0 aka Tray.

### Supported Feature:

1)	Migrate Preferences data into tray
2)	Update counter
3)	Read Preference data from other process

## Usage instructions

Simple tutorial how to use Tray in your project instead of the Preferences

### Save and read preferences

```java
// Load sqlcipher and initialize db name and version
SQLiteDatabase.loadLibs(this);
SqlcipherDbHelper.setDbVerName(DATABASE_VERSION, DATABASE_NAME);

preferencesHelper = PreferencesHelper.getInstance();
preferencesHelper.init(this);
preferencesHelper.putInt(KEY_COUNTER, INT_VALUE);
preferencesHelper.putString(KEY_WRITE_SHARED, STRING_VALUE);

// migrate preference value to tray
mAppPrefs = new AppPreferences(this);
mImportPreference = new ImportTrayPreferences(this);
mImportPreference.migrate(sharedPreferencesImport);
```

No `Editor`, no `commit()` or `apply()`

### Create your own preference module

It's recommended to bundle preferences in groups, so called modules instead of putting everything in one global module. If you were using `Preferences` before, you might have used different files to group your preferences. Extending the `TrayModulePreferences` and put all Keys inside this class is a recommended way to keep your code clean.

```java
// create a preference accessor for a module
public class MyModulePreference extends TrayPreferences {

public static String KEY_IS_FIRST_LAUNCH = "first_launch";

public MyModulePreference(final Context context) {
super(context, "myModule", 1);
}
}
```

```java
// accessing the preferences for my own module
final MyModulePreference myModulePreference = new MyModulePreference(this);
myModulePreference.put(MyModulePreference.KEY_IS_FIRST_LAUNCH, false);
```

### Migrate from Preferences to Tray

To migrate values from Preferences you have to create you own preference module. This module will be now store all of your Preferences values.

```java
public class ImportPreferences extends TrayPreferences {

// The SharedPreferences name
private static final String SHARED_PREFERENCES_FILE_NAME = "PREF_NAME";

// The key inside the SHARED_PREFERENCES_NAME
private static final String KEY_FIRST_LAUNCH = "KEY_FIRST_LAUNCH";

// The new key for this module
private static final String KEY_FIRST_LAUNCH_TRAY = "KEY_FIRST_LAUNCH_TRAY";

public ImportPreferences(@NonNull Context context) {
super(context, "myImportModule", 1);
}

// Called only once when the module was created
@Override
protected void onCreate(int initialVersion) {
super.onCreate(initialVersion);

// Create a SharedPreferencesImport object
final SharedPreferencesImport sharedPreferencesImport =
new SharedPreferencesImport(this, MainAbilitySlice.SHARED_PREF_NAME,
MainAbilitySlice.SHARED_PREF_KEY, TRAY_PREF_KEY);

// Finally migrate it
mImportPreference.migrate(sharedPreferencesImport);
}
}
```
## Installation instruction
### Method 1:
Generate the .har package through the library and add the .har package to the libs folder.
1. Add the .har package to the libs folder.
2. Add the sqlcipher.so file to file to the libs/arm64-v8a folder.
3. Add the following code to the gradle of the entry:
implementation fileTree(dir: 'libs', include: ['*.jar', '*.har'])
implementation files('libs/sqlcipher_hmos-release.har')

### Method 2:
Add the sqlcipher.so file to file to the libs/arm64-v8a folder.
```gradle
allprojects {
    repositories {
        mavenCentral()
    }
}

dependencies {
    implementation 'io.openharmony.tpc.thirdlib:tray:1.0.1'
    implementation 'io.openharmony.tpc.thirdlib:ohos-database-sqlcipher:1.0.1'
}
```

## License

```
Copyright 2015 grandcentrix GmbH

Licensed under the Apache License, Version 2.0 (the "License");
you may not use this file except in compliance with the License.
You may obtain a copy of the License at

http://www.apache.org/licenses/LICENSE-2.0

Unless required by applicable law or agreed to in writing, software
distributed under the License is distributed on an "AS IS" BASIS,
WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
See the License for the specific language governing permissions and
limitations under the License.
```