/*
 * Copyright (C) 2008 The Android Open Source Project
 *
 * 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.
 */

package android.provider;

import java.util.Locale;

import android.content.ContentResolver;
import android.content.ContentValues;
import android.content.Context;
import android.net.Uri;
import android.text.TextUtils;

A provider of user defined words for input methods to use for predictive text input.
Applications and input methods may add words into the dictionary. Words can have associated
frequency information and locale information.
NOTE: Starting on API 23, the user dictionary is only accessible through
IME and spellchecker.
/**
 * A provider of user defined words for input methods to use for predictive text input.
 * Applications and input methods may add words into the dictionary. Words can have associated
 * frequency information and locale information.
 *
 * <p><strong>NOTE: </strong>Starting on API 23, the user dictionary is only accessible through
 * IME and spellchecker.
 */
public class UserDictionary {

    
Authority string for this provider. /** Authority string for this provider. */
    public static final String AUTHORITY = "user_dictionary";

    
The content:// style URL for this provider
/**
     * The content:// style URL for this provider
     */
    public static final Uri CONTENT_URI =
        Uri.parse("content://" + AUTHORITY);

    private static final int FREQUENCY_MIN = 0;
    private static final int FREQUENCY_MAX = 255;

    
Contains the user defined words.
/**
     * Contains the user defined words.
     */
    public static class Words implements BaseColumns {
        
The content:// style URL for this table
/**
         * The content:// style URL for this table
         */
        public static final Uri CONTENT_URI =
                Uri.parse("content://" + AUTHORITY + "/words");

        
The MIME type of CONTENT_URI providing a directory of words. /**
         * The MIME type of {@link #CONTENT_URI} providing a directory of words.
         */
        public static final String CONTENT_TYPE = "vnd.android.cursor.dir/vnd.google.userword";

        
The MIME type of a CONTENT_URI sub-directory of a single word. /**
         * The MIME type of a {@link #CONTENT_URI} sub-directory of a single word.
         */
        public static final String CONTENT_ITEM_TYPE = "vnd.android.cursor.item/vnd.google.userword";

        public static final String _ID = BaseColumns._ID;

        
The word column.
TYPE: TEXT
/**
         * The word column.
         * <p>TYPE: TEXT</p>
         */
        public static final String WORD = "word";

        
The frequency column. A value between 1 and 255. Higher values imply higher frequency.
TYPE: INTEGER
/**
         * The frequency column. A value between 1 and 255. Higher values imply higher frequency.
         * <p>TYPE: INTEGER</p>
         */
        public static final String FREQUENCY = "frequency";

        
The locale that this word belongs to. Null if it pertains to all
locales. Locale is as defined by the string returned by Locale.toString().
TYPE: TEXT
/**
         * The locale that this word belongs to. Null if it pertains to all
         * locales. Locale is as defined by the string returned by Locale.toString().
         * <p>TYPE: TEXT</p>
         */
        public static final String LOCALE = "locale";

        
The uid of the application that inserted the word.
TYPE: INTEGER
/**
         * The uid of the application that inserted the word.
         * <p>TYPE: INTEGER</p>
         */
        public static final String APP_ID = "appid";

        
An optional shortcut for this word. When the shortcut is typed, supporting IMEs should
suggest the word in this row as an alternate spelling too.
/**
         * An optional shortcut for this word. When the shortcut is typed, supporting IMEs should
         * suggest the word in this row as an alternate spelling too.
         */
        public static final String SHORTCUT = "shortcut";

        
Deprecated:
Use addWord(Context, String, int, String, Locale)./**
         * @deprecated Use {@link #addWord(Context, String, int, String, Locale)}.
         */
        @Deprecated
        public static final int LOCALE_TYPE_ALL = 0;

        
Deprecated:
Use addWord(Context, String, int, String, Locale)./**
         * @deprecated Use {@link #addWord(Context, String, int, String, Locale)}.
         */
        @Deprecated
        public static final int LOCALE_TYPE_CURRENT = 1;

        
Sort by descending order of frequency.
/**
         * Sort by descending order of frequency.
         */
        public static final String DEFAULT_SORT_ORDER = FREQUENCY + " DESC";

        
Adds a word to the dictionary, with the given frequency and the specified specified locale type. @deprecated Please use addWord(Context, String, int, String, Locale) instead. @param context the current application context @param word the word to add to the dictionary. This should not be null or empty. @param localeType the locale type for this word. It should be one of LOCALE_TYPE_ALL or LOCALE_TYPE_CURRENT. /** Adds a word to the dictionary, with the given frequency and the specified
         *  specified locale type.
         *
         *  @deprecated Please use
         *  {@link #addWord(Context, String, int, String, Locale)} instead.
         *
         *  @param context the current application context
         *  @param word the word to add to the dictionary. This should not be null or
         *  empty.
         *  @param localeType the locale type for this word. It should be one of
         *  {@link #LOCALE_TYPE_ALL} or {@link #LOCALE_TYPE_CURRENT}.
         */
        @Deprecated
        public static void addWord(Context context, String word,
                int frequency, int localeType) {

            if (localeType != LOCALE_TYPE_ALL && localeType != LOCALE_TYPE_CURRENT) {
                return;
            }

            final Locale locale;

            if (localeType == LOCALE_TYPE_CURRENT) {
                locale = Locale.getDefault();
            } else {
                locale = null;
            }

            addWord(context, word, frequency, null, locale);
        }

        
Adds a word to the dictionary, with the given frequency and the specified
 locale type.
 @param context the current application context
 @param word the word to add to the dictionary. This should not be null or
 empty.
 @param shortcut optional shortcut spelling for this word. When the shortcut
 is typed, the word may be suggested by applications that support it. May be null.
 @param locale the locale to insert the word for, or null to insert the word
 for all locales.
/** Adds a word to the dictionary, with the given frequency and the specified
         *  locale type.
         *
         *  @param context the current application context
         *  @param word the word to add to the dictionary. This should not be null or
         *  empty.
         *  @param shortcut optional shortcut spelling for this word. When the shortcut
         *  is typed, the word may be suggested by applications that support it. May be null.
         *  @param locale the locale to insert the word for, or null to insert the word
         *  for all locales.
         */
        public static void addWord(Context context, String word,
                int frequency, String shortcut, Locale locale) {
            final ContentResolver resolver = context.getContentResolver();

            if (TextUtils.isEmpty(word)) {
                return;
            }

            if (frequency < FREQUENCY_MIN) frequency = FREQUENCY_MIN;
            if (frequency > FREQUENCY_MAX) frequency = FREQUENCY_MAX;

            final int COLUMN_COUNT = 5;
            ContentValues values = new ContentValues(COLUMN_COUNT);

            values.put(WORD, word);
            values.put(FREQUENCY, frequency);
            values.put(LOCALE, null == locale ? null : locale.toString());
            values.put(APP_ID, 0); // TODO: Get App UID
            values.put(SHORTCUT, shortcut);

            Uri result = resolver.insert(CONTENT_URI, values);
            // It's ok if the insert doesn't succeed because the word
            // already exists.
        }
    }
}