path: root/src/ibusproperty.h

/* -*- mode: C; c-basic-offset: 4; indent-tabs-mode: nil; -*- */
/* vim:set et sts=4: */
/* IBus - The Input Bus
 * Copyright (C) 2008-2010 Peng Huang <shawn.p.huang@gmail.com>
 * Copyright (C) 2008-2010 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_PROPERTY_H_
#define __IBUS_PROPERTY_H_

#include "ibusserializable.h"
#include "ibustext.h"

/**
 * SECTION: ibusproperty
 * @short_description: UI component for input method engine property.
 * @title: IBusProperty
 * @stability: Stable
 *
 * An IBusProperty is an UI component like a button or a menu item
 * which shows the status of corresponding input method engine property.
 * End user can operate and see the current status of IME through these components.
 * For example, ibus-chewing users change the English/Chinese input mode by
 * pressing ctrl-space or click on the Eng/Chi switch button.
 * And the IBusProperty shows the change correspondingly.
 *
 * see_also: #IBusPropList, #IBusEngine
 */
G_BEGIN_DECLS

/*
 * Type macros.
 */
/* define IBusProperty macros */
#define IBUS_TYPE_PROPERTY             \
    (ibus_property_get_type ())
#define IBUS_PROPERTY(obj)             \
    (G_TYPE_CHECK_INSTANCE_CAST ((obj), IBUS_TYPE_PROPERTY, IBusProperty))
#define IBUS_PROPERTY_CLASS(klass)     \
    (G_TYPE_CHECK_CLASS_CAST ((klass), IBUS_TYPE_PROPERTY, IBusPropertyClass))
#define IBUS_IS_PROPERTY(obj)          \
    (G_TYPE_CHECK_INSTANCE_TYPE ((obj), IBUS_TYPE_PROPERTY))
#define IBUS_IS_PROPERTY_CLASS(klass)  \
    (G_TYPE_CHECK_CLASS_TYPE ((klass), IBUS_TYPE_PROPERTY))
#define IBUS_PROPERTY_GET_CLASS(obj)   \
    (G_TYPE_INSTANCE_GET_CLASS ((obj), IBUS_TYPE_PROPERTY, IBusPropertyClass))

/**
 * IBusPropType:
 * @PROP_TYPE_NORMAL: Property is shown as normal text.
 * @PROP_TYPE_TOGGLE: Property is shown as a toggle button.
 * @PROP_TYPE_RADIO: Property is shown as a radio selection option.
 * @PROP_TYPE_MENU: Property is shown as a menu, usually imply it has sub menu
 * items.
 * @PROP_TYPE_SEPARATOR: A separator for menu.
 *
 * Type enumeration of IBusProperty.
 */
typedef enum {
    PROP_TYPE_NORMAL = 0,
    PROP_TYPE_TOGGLE = 1,
    PROP_TYPE_RADIO = 2,
    PROP_TYPE_MENU = 3,
    PROP_TYPE_SEPARATOR = 4,
} IBusPropType;

/**
 * IBusPropState:
 * @PROP_STATE_UNCHECKED: Property option is unchecked.
 * @PROP_STATE_CHECKED: Property option is checked.
 * @PROP_STATE_INCONSISTENT: The state is inconsistent with the associated IME
 * property.
 *
 * State of #IBusProperty. The actual effect depends on #IBusPropType of the
 * IBusProperty.
 *
 * <variablelist>
 *     <varlistentry>
 *         <term>PROP_TYPE_TOGGLE</term>
 *         <listitem><para>Emphasized if PROP_STATE_CHECKED, normal otherwise.</para></listitem>
 *     </varlistentry>
 *     <varlistentry>
 *         <term>PROP_TYPE_RADIO</term>
 *         <listitem><para>Option checked if PROP_STATE_CHECKED, unchecked otherwise.</para></listitem>
 *     </varlistentry>
 * </variablelist>
 * No effect on other types.
 */
typedef enum {
    PROP_STATE_UNCHECKED = 0,
    PROP_STATE_CHECKED = 1,
    PROP_STATE_INCONSISTENT = 2,
} IBusPropState;


typedef struct _IBusProperty IBusProperty;
typedef struct _IBusPropertyClass IBusPropertyClass;
typedef struct _IBusPropertyPrivate IBusPropertyPrivate;

#ifndef __PROPLIST_DEFINED
#define __PROPLIST_DEFINED
typedef struct _IBusPropList IBusPropList;
typedef struct _IBusPropListClass IBusPropListClass;
#endif

/**
 * IBusProperty:
 * UI component for input method engine property.
 */
struct _IBusProperty {
    /*< private >*/
    IBusSerializable parent;
    IBusPropertyPrivate *priv;

    gpointer pdummy[7];
};

struct _IBusPropertyClass {
    IBusSerializableClass parent;
};

GType            ibus_property_get_type     ();

/**
 * ibus_property_new:
 * @key: Unique Identity for the #IBusProperty.
 * @type: #IBusPropType of #IBusProperty.
 * @label: Text shown in UI.
 * @icon: (allow-none): Icon file for the #IBusProperty.
 * @tooltip: Message shown if mouse hovered the  #IBusProperty.
 * @sensitive: Whether the #IBusProperty is sensitive to keyboard and mouse event.
 * @visible: Whether the #IBusProperty is visible.
 * @state: IBusPropState of #IBusProperty.
 * @prop_list: (allow-none): #IBusPropList that contains sub IBusProperties.
 *
 * Creates a new #IBusProperty.
 *
 * Returns: A newly allocated #IBusProperty.
 */
IBusProperty    *ibus_property_new          (const gchar    *key,
                                             IBusPropType    type,
                                             IBusText       *label,
                                             const gchar    *icon,
                                             IBusText       *tooltip,
                                             gboolean        sensitive,
                                             gboolean        visible,
                                             IBusPropState   state,
                                             IBusPropList   *prop_list);

/**
 * ibus_property_new_varargs:
 * @first_property_name: Name of the first property.
 * @...: the NULL-terminated arguments of the properties and values.
 *
 * Creates a new #IBusProperty.
 * ibus_property_new_varargs() supports the va_list format.
 * name property is required. e.g.
 * ibus_property_new_varargs("key", "TypingMode", "type", PROP_TYPE_MENU, NULL)
 *
 * Returns: A newly allocated #IBusProperty.
 */
IBusProperty    *ibus_property_new_varargs  (const gchar    *first_property_name,
                                                             ...);

/**
 * ibus_property_get_key:
 * @prop: An #IBusProperty.
 *
 * Get the key of #IBusProperty.
 *
 * Returns: the key of #IBusProperty. Should not be freed.
 */
const gchar *    ibus_property_get_key      (IBusProperty   *prop);

/**
 * ibus_property_get_label:
 * @prop: An #IBusProperty.
 *
 * Get the label of #IBusProperty.
 *
 * Returns: (transfer none): the label of #IBusProperty. Should not be freed.
 */
IBusText *       ibus_property_get_label    (IBusProperty   *prop);

/**
 * ibus_property_set_label:
 * @prop: An #IBusProperty.
 * @label: Text shown in UI.
 *
 * Set the label of #IBusProperty.
 */
void             ibus_property_set_label    (IBusProperty   *prop,
                                             IBusText       *label);

/**
 * ibus_property_get_symbol:
 * @prop: An #IBusProperty.
 *
 * Get the symbol of #IBusProperty.
 *
 * Returns: (transfer none): the symbol of #IBusProperty. Should not be freed.
 */
IBusText *       ibus_property_get_symbol   (IBusProperty   *prop);

/**
 * ibus_property_set_symbol:
 * @prop: An #IBusProperty.
 * @symbol: Text shown in UI.
 *
 * Set the symbol of #IBusProperty.
 */
void             ibus_property_set_symbol   (IBusProperty   *prop,
                                             IBusText       *symbol);

/**
 * ibus_property_get_icon:
 * @prop: An #IBusProperty.
 *
 * Get the icon of #IBusProperty.
 *
 * Returns: the icon of #IBusProperty. Should not be freed.
 */
const gchar *    ibus_property_get_icon     (IBusProperty   *prop);

/**
 * ibus_property_set_icon:
 * @prop: An #IBusProperty.
 * @icon: Icon shown in UI. It could be a full path of an icon file or an icon name.
 *
 * Set the icon of #IBusProperty.
 */
void             ibus_property_set_icon     (IBusProperty   *prop,
                                             const gchar    *icon);

/**
 * ibus_property_get_tooltip:
 * @prop: An #IBusProperty.
 *
 * Get the tooltip of #IBusProperty.
 *
 * Returns: (transfer none): the tooltip of #IBusProperty. Should not be freed.
 */
IBusText *       ibus_property_get_tooltip  (IBusProperty   *prop);

/**
 * ibus_property_set_tooltip:
 * @prop: An #IBusProperty.
 * @tooltip: Text of the tooltip.
 *
 * Set the tooltip of #IBusProperty.
 */
void             ibus_property_set_tooltip  (IBusProperty   *prop,
                                             IBusText       *tooltip);

/**
 * ibus_property_get_sensitive:
 * @prop: An #IBusProperty.
 *
 * Get the sensitive of #IBusProperty.
 *
 * Returns: the sensitive of #IBusProperty.
 */
gboolean         ibus_property_get_sensitive(IBusProperty   *prop);

/**
 * ibus_property_set_sensitive:
 * @prop: An #IBusProperty.
 * @sensitive: Whether the #IBusProperty is sensitive.
 *
 * Set whether the #IBusProperty is sensitive.
 */
void             ibus_property_set_sensitive(IBusProperty   *prop,
                                             gboolean        sensitive);

/**
 * ibus_property_get_visible:
 * @prop: An #IBusProperty.
 *
 * Get the visible of #IBusProperty.
 *
 * Returns: the visible of #IBusProperty.
 */
gboolean         ibus_property_get_visible  (IBusProperty   *prop);

/**
 * ibus_property_set_visible:
 * @prop: An #IBusProperty.
 * @visible: Whether the #IBusProperty is visible.
 *
 * Set whether the #IBusProperty is visible.
 */
void             ibus_property_set_visible  (IBusProperty   *prop,
                                             gboolean        visible);

/**
 * ibus_property_get_property_type:
 * @prop: An #IBusProperty.
 *
 * Get the type of #IBusProperty.
 *
 * Returns: the type of #IBusProperty.
 */
IBusPropType     ibus_property_get_prop_type(IBusProperty   *prop);

/**
 * ibus_property_get_state:
 * @prop: An #IBusProperty.
 *
 * Get the state of #IBusProperty.
 *
 * Returns: the state of #IBusProperty.
 */
IBusPropState    ibus_property_get_state    (IBusProperty   *prop);

/**
 * ibus_property_set_state:
 * @prop: An #IBusProperty.
 * @state: The state of the #IBusProperty.
 *
 * Set the state of the #IBusProperty.
 */
void             ibus_property_set_state    (IBusProperty   *prop,
                                             IBusPropState   state);

/**
 * ibus_property_get_sub_props:
 * @prop: An #IBusProperty.
 *
 * Get the IBusPropList of #IBusProperty.
 *
 * Returns: (transfer none): the IBusPropList of #IBusProperty.
 *     Should not be freed.
 */
IBusPropList *   ibus_property_get_sub_props(IBusProperty   *prop);

/**
 * ibus_property_set_sub_props:
 * @prop: An #IBusProperty.
 * @prop_list: #IBusPropList that contains sub IBusProperties.
 *
 * Set the sub IBusProperties.
 */
void             ibus_property_set_sub_props(IBusProperty   *prop,
                                             IBusPropList   *prop_list);

/**
 * ibus_property_update:
 * @prop: An #IBusProperty.
 * @prop_update: #IBusPropList that contains sub IBusProperties.
 *
 * Update the content of an #IBusProperty.
 * #IBusProperty @prop_update can either be sub-property of @prop,
 * or holds new values for @prop.
 *
 * Returns: TRUE for update suceeded; FALSE otherwise.
 */

gboolean         ibus_property_update       (IBusProperty   *prop,
                                             IBusProperty   *prop_update);

G_END_DECLS
#endif