/* -*- mode: C; c-basic-offset: 4; indent-tabs-mode: nil; -*- */

/* vim:set et sts=4: */

/* bus - The Input Bus

 * Copyright (C) 2008-2015 Peng Huang <shawn.p.huang@gmail.com>

 * Copyright (C) 2008-2015 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 <ibus.h> can be included directly"

#endif

#ifndef __IBUS_COMPONENT_H_

#define __IBUS_COMPONENT_H_

/**

 * SECTION: ibuscomponent

 * @short_description:  Component (executable) specification.

 * @title: IBusComponent

 * @stability: Stable

 *

 * An IBusComponent is an executable program.

 * It provides services such as user interface, configuration,

 * and input method engine (IME).

 *

 * It is recommended that IME developers provide

 * a component XML file and

 * load the XML file by ibus_component_new_from_file().

 *

 * The format of a component XML file is described  at

 * <ulink url="https://github.com/ibus/ibus/wiki/DevXML">https://github.com/ibus/ibus/wiki/DevXML</ulink>

 */

#include "ibusserializable.h"

#include "ibusobservedpath.h"

#include "ibusenginedesc.h"

#include "ibusxml.h"

/*

 * Type macros.

 */

/* define GOBJECT macros */

#define IBUS_TYPE_COMPONENT             \

    (ibus_component_get_type ())

#define IBUS_COMPONENT(obj)             \

    (G_TYPE_CHECK_INSTANCE_CAST ((obj), IBUS_TYPE_COMPONENT, IBusComponent))

#define IBUS_COMPONENT_CLASS(klass)     \

    (G_TYPE_CHECK_CLASS_CAST ((klass), IBUS_TYPE_COMPONENT, IBusComponentClass))

#define IBUS_IS_COMPONENT(obj)          \

    (G_TYPE_CHECK_INSTANCE_TYPE ((obj), IBUS_TYPE_COMPONENT))

#define IBUS_IS_COMPONENT_CLASS(klass)  \

    (G_TYPE_CHECK_CLASS_TYPE ((klass), IBUS_TYPE_COMPONENT))

#define IBUS_COMPONENT_GET_CLASS(obj)   \

    (G_TYPE_INSTANCE_GET_CLASS ((obj), IBUS_TYPE_COMPONENT, IBusComponentClass))

G_BEGIN_DECLS

typedef struct _IBusComponent IBusComponent;

typedef struct _IBusComponentClass IBusComponentClass;

typedef struct _IBusComponentPrivate IBusComponentPrivate;

/**

 * IBusComponent:

 *

 * An IBusComponent stores component information.

 * You can get extended values with g_object_get_properties.

 */

struct _IBusComponent {

    /*< private >*/

    IBusSerializable parent;

    IBusComponentPrivate *priv;

    /* instance members */

    /*< public >*/

    /*< private >*/

    /* padding */

    gpointer pdummy[7];  // We can add 7 pointers without breaking the ABI.

};

struct _IBusComponentClass {

  IBusSerializableClass parent;

  /* class members */

};

GType            ibus_component_get_type        (void);

/**

 * ibus_component_new:

 * @name: Name of the component.

 * @description: Detailed description of component.

 * @version: Component version.

 * @license: Distribution license of this component.

 * @author: Author(s) of the component.

 * @homepage: Homepage of the component.

 * @command_line: path to component executable.

 * @textdomain: Domain name for dgettext()

 *

 * Creates a new #IBusComponent.

 *

 * Returns: A newly allocated #IBusComponent.

 */

IBusComponent   *ibus_component_new             (const gchar    *name,

                                                 const gchar    *description,

                                                 const gchar    *version,

                                                 const gchar    *license,

                                                 const gchar    *author,

                                                 const gchar    *homepage,

                                                 const gchar    *command_line,

                                                 const gchar    *textdomain);

/**

 * ibus_component_new_varargs:

 * @first_property_name: Name of the first property.

 * @...: the NULL-terminated arguments of the properties and values.

 *

 * Creates a new #IBusComponent.

 * ibus_component_new_varargs() supports the va_list format.

 * name property is required. e.g.

 * IBusComponent *component = ibus_component_new_varargs ("name", "ibus-foo",

 *                                                        "command_line", "/usr/libexec/ibus-engine-foo --ibus",

 *                                                     NULL)

 *

 * Returns: A newly allocated #IBusComponent.

 */

IBusComponent   *ibus_component_new_varargs     (const gchar    *first_property_name,

                                                 ...);

/**

 * ibus_component_new_from_xml_node:

 * @node: Root node of component XML tree.

 *

 * Creates a new #IBusComponent from an XML tree.

 *

 * Returns: A newly allocated #IBusComponent.

 */

IBusComponent   *ibus_component_new_from_xml_node

                                                (XMLNode        *node);

/**

 * ibus_component_new_from_file:

 * @filename: An XML file that contains component information.

 *

 * Creates a new #IBusComponent from an XML file.

 * Note that a component file usually contains engine descriptions,

 * if it does, ibus_engine_desc_new_from_xml_node() will be called

 * to load the engine descriptions.

 *

 * Returns: A newly allocated #IBusComponent.

 */

IBusComponent   *ibus_component_new_from_file   (const gchar    *filename);

/**

 * ibus_component_get_name:

 * @component: An #IBusComponent

 *

 * Gets the name property in #IBusComponent. It should not be freed.

 *

 * Returns: name property in #IBusComponent

 */

const gchar     *ibus_component_get_name        (IBusComponent  *component);

/**

 * ibus_component_get_description:

 * @component: An #IBusComponent

 *

 * Gets the description property in #IBusComponent. It should not be freed.

 *

 * Returns: description property in #IBusComponent

 */

const gchar     *ibus_component_get_description (IBusComponent  *component);

/**

 * ibus_component_get_version:

 * @component: An #IBusComponent

 *

 * Gets the version property in #IBusComponent. It should not be freed.

 *

 * Returns: version property in #IBusComponent

 */

const gchar     *ibus_component_get_version     (IBusComponent  *component);

/**

 * ibus_component_get_license:

 * @component: An #IBusComponent

 *

 * Gets the license property in #IBusComponent. It should not be freed.

 *

 * Returns: license property in #IBusComponent

 */

const gchar     *ibus_component_get_license     (IBusComponent  *component);

/**

 * ibus_component_get_author:

 * @component: An #IBusComponent

 *

 * Gets the author property in #IBusComponent. It should not be freed.

 *

 * Returns: author property in #IBusComponent

 */

const gchar     *ibus_component_get_author      (IBusComponent  *component);

/**

 * ibus_component_get_homepage:

 * @component: An #IBusComponent

 *

 * Gets the homepage property in #IBusComponent. It should not be freed.

 *

 * Returns: homepage property in #IBusComponent

 */

const gchar     *ibus_component_get_homepage    (IBusComponent  *component);

/**

 * ibus_component_get_exec:

 * @component: An #IBusComponent

 *

 * Gets the exec property in #IBusComponent. It should not be freed.

 *

 * Returns: exec property in #IBusComponent

 */

const gchar     *ibus_component_get_exec        (IBusComponent  *component);

/**

 * ibus_component_get_textdomain:

 * @component: An #IBusComponent

 *

 * Gets the textdomain property in #IBusComponent. It should not be freed.

 *

 * Returns: textdomain property in #IBusComponent

 */

const gchar     *ibus_component_get_textdomain  (IBusComponent  *component);

/**

 * ibus_component_add_observed_path:

 * @component: An #IBusComponent

 * @path: Observed path to be added.

 * @access_fs: %TRUE for filling the file status; %FALSE otherwise.

 *

 * Add an observed path to #IBusComponent.

 */

void             ibus_component_add_observed_path

                                                (IBusComponent  *component,

                                                 const gchar    *path,

                                                 gboolean        access_fs);

/**

 * ibus_component_add_engine:

 * @component: An #IBusComponent

 * @engine: A description of an engine.

 *

 * Add an engine to #IBusComponent according to the description in @engine.

 */

void             ibus_component_add_engine      (IBusComponent  *component,

                                                 IBusEngineDesc *engine);

/**

 * ibus_component_get_engines:

 * @component: An #IBusComponent.

 *

 * Gets the engines of this component.

 *

 * Returns: (transfer container) (element-type IBusEngineDesc):

 * A newly allocated GList that contains engines.

 */

GList           *ibus_component_get_engines     (IBusComponent  *component);

/**

 * ibus_component_output:

 * @component: An #IBusComponent.

 * @output: GString that holds the result.

 * @indent: level of indent.

 *

 * Output #IBusComponent as an XML-formatted string.

 * The output string can be then shown on the screen or written to file.

 */

void             ibus_component_output          (IBusComponent  *component,

                                                 GString        *output,

                                                 gint            indent);

/**

 * ibus_component_output_engines:

 * @component: An #IBusComponent.

 * @output: GString that holds the result.

 * @indent: level of indent.

 *

 * Output engine description  as an XML-formatted string.

 * The output string can be then shown on the screen or written to file.

 */

void             ibus_component_output_engines  (IBusComponent  *component,

                                                 GString        *output,

                                                 gint            indent);

/**

 * ibus_component_check_modification:

 * @component: An #IBusComponent.

 *

 * Check whether the observed paths of component is modified.

 *

 * Returns: %TRUE if at least one of the observed paths is modified;

 * %FALSE otherwise.

 */

gboolean         ibus_component_check_modification

                                                (IBusComponent  *component);

/**

 * ibus_component_get_observed_paths:

 * @component: An #IBusComponent.

 *

 * Gets the observed paths of this component.

 *

 * Returns: (transfer container) (element-type IBusObservedPath): A

 * newly allocated GList that contains observed paths.

 */

GList           *ibus_component_get_observed_paths

                                                (IBusComponent *component);

G_END_DECLS

#endif