/* -*- mode: C; c-basic-offset: 4; indent-tabs-mode: nil; -*- */ /* vim:set et sts=4: */ /* ibus - The Input Bus * Copyright (C) 2008-2013 Peng Huang * Copyright (C) 2008-2013 Red Hat, Inc. * * This library is free software; you can redistribute it and/or * modify it under the terms of the GNU Lesser General Public * License as published by the Free Software Foundation; either * version 2.1 of the License, or (at your option) any later version. * * This library is distributed in the hope that it will be useful, * but WITHOUT ANY WARRANTY; without even the implied warranty of * MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the GNU * Lesser General Public License for more details. * * You should have received a copy of the GNU Lesser General Public * License along with this library; if not, write to the Free Software * Foundation, Inc., 51 Franklin Street, Fifth Floor, Boston, MA 02110-1301 * USA */ #if !defined (__IBUS_H_INSIDE__) && !defined (IBUS_COMPILATION) #error "Only can be included directly" #endif #ifndef __IBUS_CONFIG_H_ #define __IBUS_CONFIG_H_ /** * SECTION: ibusconfig * @title: IBusConfig * @short_description: IBus engine configuration module. * * An IBusConfig provides engine configuration methods * such as get and set the configure settings to configuration file. * * Currently, IBusConfig supports gconf. */ #include "ibusproxy.h" /* * Type macros. */ /* define GOBJECT macros */ #define IBUS_TYPE_CONFIG \ (ibus_config_get_type ()) #define IBUS_CONFIG(obj) \ (G_TYPE_CHECK_INSTANCE_CAST ((obj), IBUS_TYPE_CONFIG, IBusConfig)) #define IBUS_CONFIG_CLASS(klass) \ (G_TYPE_CHECK_CLASS_CAST ((klass), IBUS_TYPE_CONFIG, IBusConfigClass)) #define IBUS_IS_CONFIG(obj) \ (G_TYPE_CHECK_INSTANCE_TYPE ((obj), IBUS_TYPE_CONFIG)) #define IBUS_IS_CONFIG_CLASS(klass) \ (G_TYPE_CHECK_CLASS_TYPE ((klass), IBUS_TYPE_CONFIG)) #define IBUS_CONFIG_GET_CLASS(obj) \ (G_TYPE_INSTANCE_GET_CLASS ((obj), IBUS_TYPE_CONFIG, IBusConfigClass)) G_BEGIN_DECLS typedef struct _IBusConfig IBusConfig; typedef struct _IBusConfigClass IBusConfigClass; typedef struct _IBusConfigPrivate IBusConfigPrivate; /** * IBusConfig: * * An opaque data type representing an IBusConfig. */ struct _IBusConfig { /*< private >*/ IBusProxy parent; IBusConfigPrivate *priv; /* instance members */ }; struct _IBusConfigClass { /*< private >*/ IBusProxyClass parent; /* class members */ }; GType ibus_config_get_type (void); /** * ibus_config_new: * @connection: A #GDBusConnection. * @cancellable: A #GCancellable or %NULL. * @error: Return location for error or %NULL. * * Create a new #IBusConfig from existing #GDBusConnection. * * Returns: A newly allocated #IBusConfig corresponding to @connection. */ IBusConfig *ibus_config_new (GDBusConnection *connection, GCancellable *cancellable, GError **error); /** * ibus_config_new_async: * @connection: An #GDBusConnection. * @cancellable: A #GCancellable or %NULL. * @callback: A #GAsyncReadyCallback to call when the request is satisfied. * The callback should not be %NULL. * @user_data: The data to pass to callback. * * New an #IBusConfig asynchronously. */ void ibus_config_new_async (GDBusConnection *connection, GCancellable *cancellable, GAsyncReadyCallback callback, gpointer user_data); /** * ibus_config_new_async_finish: * @res: A #GAsyncResult obtained from the #GAsyncReadyCallback pass to * ibus_config_new_async(). * @error: Return location for error or %NULL. * * Finishes an operation started with ibus_config_new_async(). * * Returns: A newly allocated #IBusConfig. */ IBusConfig *ibus_config_new_async_finish (GAsyncResult *res, GError **error); /** * ibus_config_get_value: * @config: An #IBusConfig * @section: Section name of the configuration option. * @name: Name of the configure option. * * Get the value of a configuration option synchronously. * * GConf stores configure options in a tree-like structure, * and the IBus related setting is at /desktop/ibus, * thus, @section here is a path from there, * while @name is the key of that configuration option. * * ibus-chewing, for example, stores its setting in /desktop/ibus/engine/Chewing, * so the section name for it is "engine/Chewing". * See also: ibus_config_set_value(). * * Returns: A #GVariant or %NULL. Free with g_variant_unref(). */ GVariant *ibus_config_get_value (IBusConfig *config, const gchar *section, const gchar *name); /** * ibus_config_get_value_async: * @config: An #IBusConfig * @section: Section name of the configuration option. * @name: Name of the configure option. * @timeout_ms: The timeout in milliseconds or -1 to use the default timeout. * @cancellable: A #GCancellable or %NULL. * @callback: Callback function to invoke when the return value is ready. * @user_data: The data to pass to callback. * * Get the value of a configuration option asynchronously. * * See also: ibus_config_get_value(). */ void ibus_config_get_value_async (IBusConfig *config, const gchar *section, const gchar *name, gint timeout_ms, GCancellable *cancellable, GAsyncReadyCallback callback, gpointer user_data); /** * ibus_config_get_value_async_finish: * @config: A #IBusConfig. * @result: A #GAsyncResult. * @error: Return location for error or %NULL. * * Finish get value of a configuration option. * * Returns: A #GVariant or %NULL if error is set. Free with g_variant_unref(). * * See also: ibus_config_get_value_async(). */ GVariant *ibus_config_get_value_async_finish (IBusConfig *config, GAsyncResult *result, GError **error); /** * ibus_config_get_values: * @config: An #IBusConfig * @section: Section name of the configuration option. * * Get all values in a section synchronously. * * Returns: A #GVariant or %NULL. Free with g_variant_unref(). * * See also: ibus_config_set_value(). */ GVariant *ibus_config_get_values (IBusConfig *config, const gchar *section); /** * ibus_config_get_values_async: * @config: An #IBusConfig * @section: Section name of the configuration option. * @timeout_ms: The timeout in milliseconds or -1 to use the default timeout. * @cancellable: A #GCancellable or %NULL. * @callback: Callback function to invoke when the return value is ready. * @user_data: The data to pass to callback. * * Get all values in a section asynchronously. * * See also: ibus_config_get_values(). */ void ibus_config_get_values_async(IBusConfig *config, const gchar *section, gint timeout_ms, GCancellable *cancellable, GAsyncReadyCallback callback, gpointer user_data); /** * ibus_config_get_values_async_finish: * @config: A #IBusConfig. * @result: A #GAsyncResult. * @error: Return location for error or %NULL. * * Finish get values in a section. * * Returns: A #GVariant or %NULL if error is set. Free with g_variant_unref(). * * See also: ibus_config_get_values_async(). */ GVariant *ibus_config_get_values_async_finish (IBusConfig *config, GAsyncResult *result, GError **error); /** * ibus_config_set_value: * @config: An #IBusConfig * @section: Section name of the configuration option. * @name: Name of the configure option its self. * @value: A #GVariant that holds the value. If the value is floating, the * function takes ownership of it. * * Set the value of a configuration option synchronously. * * Returns: %TRUE if succeed; %FALSE otherwise. * * See also: ibus_config_get_value(). */ gboolean ibus_config_set_value (IBusConfig *config, const gchar *section, const gchar *name, GVariant *value); /** * ibus_config_set_value_async: * @config: An #IBusConfig * @section: Section name of the configuration option. * @name: Name of the configure option. * @value: A #GVariant that holds the value. If the value is floating, the * function takes ownership of it. * @timeout_ms: The timeout in milliseconds or -1 to use the default timeout. * @cancellable: A #GCancellable or %NULL. * @callback: Callback function to invoke when the return value is ready. * @user_data: The data to pass to callback. * * Set the value of a configuration option asynchronously. * * See also: ibus_config_set_value(). */ void ibus_config_set_value_async (IBusConfig *config, const gchar *section, const gchar *name, GVariant *value, gint timeout_ms, GCancellable *cancellable, GAsyncReadyCallback callback, gpointer user_data); /** * ibus_config_set_value_async_finish: * @config: A #IBusConfig. * @result: A #GAsyncResult. * @error: Return location for error or %NULL. * * Finish set value of a configuration option. * * Returns: %TRUE or %FALSE if error is set. * * See also: ibus_config_set_value_async(). */ gboolean ibus_config_set_value_async_finish (IBusConfig *config, GAsyncResult *result, GError **error); /** * ibus_config_unset: * @config: An #IBusConfig * @section: Section name of the configuration option. * @name: Name of the configure option its self. * * Remove an entry of a configuration option. * * Returns: %TRUE if succeed; %FALSE otherwise. * * See also: ibus_config_get_value(). */ gboolean ibus_config_unset (IBusConfig *config, const gchar *section, const gchar *name); /* FIXME add an asynchronous version of unset */ /** * ibus_config_watch: * @config: An #IBusConfig * @section: (allow-none): Section name of the configuration option. * @name: (allow-none): Name of the configure option its self. * * Subscribe to the configuration option change notification. * * Until this function is called, every change will be notified to the * client through #IBusConfig::value-changed signal. Clients should * call ibus_config_watch() with the sections they are interested in, * to reduce the number of D-Bus messages. * * Returns: %TRUE if succeed; %FALSE otherwise. * * See also: ibus_config_unwatch(). */ gboolean ibus_config_watch (IBusConfig *config, const gchar *section, const gchar *name); /* FIXME add an asynchronous version of watch */ /** * ibus_config_unwatch: * @config: An #IBusConfig * @section: (allow-none): Section name of the configuration option. * @name: (allow-none): Name of the configure option its self. * * Unsubscribe from the configuration option change notification. * * Returns: %TRUE if succeed; %FALSE otherwise. * * See also: ibus_config_watch. */ gboolean ibus_config_unwatch (IBusConfig *config, const gchar *section, const gchar *name); /* FIXME add an asynchronous version of unwatch */ G_END_DECLS #endif