/* -*- 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