/* -*- 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 <shawn.p.huang@gmail.com>

 * 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 <ibus.h> can be included directly"

#endif

#ifndef __IBUS_LOOKUP_TABLE_H_

#define __IBUS_LOOKUP_TABLE_H_

/**

 * SECTION: ibuslookuptable

 * @short_description: Candidate word/phrase lookup table.

 * @stability: Stable

 *

 * An IBusLookuptable stores the candidate words or phrases for users to

 * choose from.

 *

 * Use ibus_engine_update_lookup_table(), ibus_engine_show_lookup_table(),

 * and ibus_engine_hide_lookup_table() to update, show and hide the lookup

 * table.

 *

 * see_also: #IBusEngine

 */

#include "ibusserializable.h"

#include "ibustext.h"

/*

 * Type macros.

 */

/* define IBusLookupTable macros */

#define IBUS_TYPE_LOOKUP_TABLE             \

    (ibus_lookup_table_get_type ())

#define IBUS_LOOKUP_TABLE(obj)             \

    (G_TYPE_CHECK_INSTANCE_CAST ((obj), IBUS_TYPE_LOOKUP_TABLE, IBusLookupTable))

#define IBUS_LOOKUP_TABLE_CLASS(klass)     \

    (G_TYPE_CHECK_CLASS_CAST ((klass), IBUS_TYPE_LOOKUP_TABLE, IBusLookupTableClass))

#define IBUS_IS_LOOKUP_TABLE(obj)          \

    (G_TYPE_CHECK_INSTANCE_TYPE ((obj), IBUS_TYPE_LOOKUP_TABLE))

#define IBUS_IS_LOOKUP_TABLE_CLASS(klass)  \

    (G_TYPE_CHECK_CLASS_TYPE ((klass), IBUS_TYPE_LOOKUP_TABLE))

#define IBUS_LOOKUP_TABLE_GET_CLASS(obj)   \

    (G_TYPE_INSTANCE_GET_CLASS ((obj), IBUS_TYPE_LOOKUP_TABLE, IBusLookupTableClass))

G_BEGIN_DECLS

typedef struct _IBusLookupTable IBusLookupTable;

typedef struct _IBusLookupTableClass IBusLookupTableClass;

/**

 * IBusLookupTable:

 * @page_size: number of candidate shown per page.

 * @cursor_pos: position index of cursor.

 * @cursor_visible: whether the cursor is visible.

 * @round: TRUE for lookup table wrap around.

 * @orientation: orientation of the table.

 * @candidates: Candidate words/phrases.

 * @labels: Candidate labels which identify individual candidates in the same page. Default is 1, 2, 3, 4 ...

 *

 * An IBusLookuptable stores the candidate words or phrases for users to choose from.

 * Note that some input methods allow you to select candidate by pressing non-numeric

 * keys such as "asdfghjkl;".

 * Developers of these input methods should change the labels with

 * ibus_lookup_table_append_label().

 */

struct _IBusLookupTable {

    IBusSerializable parent;

    /*< public >*/

    guint page_size;

    guint cursor_pos;

    gboolean cursor_visible;

    gboolean round;

    gint orientation;

    GArray *candidates;

    GArray *labels;

};

struct _IBusLookupTableClass {

    IBusSerializableClass parent;

};

GType                ibus_lookup_table_get_type (void);

/**

 * ibus_lookup_table_new:

 * @page_size: number of candidate shown per page, the max value is 16.

 * @cursor_pos: position index of cursor.

 * @cursor_visible: whether the cursor is visible.

 * @round: TRUE for lookup table wrap around.

 *

 * Craetes a new #IBusLookupTable.

 *

 * Returns: A newly allocated #IBusLookupTable.

 */

IBusLookupTable     *ibus_lookup_table_new      (guint               page_size,

                                                 guint               cursor_pos,

                                                 gboolean            cursor_visible,

                                                 gboolean            round);

/**

 * ibus_lookup_table_append_candidate:

 * @table: An IBusLookupTable.

 * @text: candidate word/phrase to be appended (in IBusText format).

 *

 * Append a candidate word/phrase to IBusLookupTable, and increase reference.

 */

void                 ibus_lookup_table_append_candidate

                                                (IBusLookupTable    *table,

                                                 IBusText           *text);

/**

 * ibus_lookup_table_get_number_of_candidates:

 * @table: An IBusLookupTable.

 *

 * Return the number of candidate in the table.

 *

 * Returns: The number of candidates in the table

 */

guint               ibus_lookup_table_get_number_of_candidates

                                                (IBusLookupTable    *table);

/**

 * ibus_lookup_table_get_candidate:

 * @table: An IBusLookupTable.

 * @index: Index in the Lookup table.

 *

 * Return #IBusText at the given index. Borrowed reference.

 *

 * Returns: (transfer none): IBusText at the given index; NULL if no such

 *         #IBusText.

 */

IBusText            *ibus_lookup_table_get_candidate

                                                (IBusLookupTable    *table,

                                                 guint               index);

/**

 * ibus_lookup_table_append_label:

 * @table: An IBusLookupTable.

 * @text: A candidate label to be appended (in IBusText format).

 *

 * Append a candidate word/phrase to IBusLookupTable, and increase reference.

 * This function is needed if the input method select candidate with

 * non-numeric keys such as "asdfghjkl;".

 */

void                 ibus_lookup_table_append_label

                                                (IBusLookupTable    *table,

                                                 IBusText           *text);

/**

 * ibus_lookup_table_set_label:

 * @table: An IBusLookupTable.

 * @index: Intex in the Lookup table.

 * @text: A candidate label to be appended (in IBusText format).

 *

 * Append a candidate word/phrase to IBusLookupTable, and increase reference.

 * This function is needed if the input method select candidate with

 * non-numeric keys such as "asdfghjkl;".

 */

void                 ibus_lookup_table_set_label

                                                (IBusLookupTable    *table,

                                                 guint               index,

                                                 IBusText           *text);

/**

 * ibus_lookup_table_get_label:

 * @table: An IBusLookupTable.

 * @index: Index in the Lookup table.

 *

 * Return #IBusText at the given index. Borrowed reference.

 *

 * Returns: (transfer none): #IBusText at the given index; %NULL if no such

 *         #IBusText.

 */

IBusText            *ibus_lookup_table_get_label

                                                (IBusLookupTable    *table,

                                                 guint               index);

/**

 * ibus_lookup_table_set_cursor_pos:

 * @table: An IBusLookupTable.

 * @cursor_pos: The position of cursor.

 *

 * Set the cursor position of IBusLookupTable.

 */

void                 ibus_lookup_table_set_cursor_pos

                                                (IBusLookupTable    *table,

                                                 guint               cursor_pos);

/**

 * ibus_lookup_table_get_cursor_pos:

 * @table: An IBusLookupTable.

 *

 * Gets the cursor position of #IBusLookupTable.

 *

 * Returns: The position of cursor.

 */

guint                ibus_lookup_table_get_cursor_pos

                                                (IBusLookupTable    *table);

/**

 * ibus_lookup_table_set_cursor_visible:

 * @table: An IBusLookupTable.

 * @visible: Whether to make the cursor of @table visible.

 *

 * Set whether to make the cursor of an IBusLookupTable visible or not.

 */

void                 ibus_lookup_table_set_cursor_visible

                                                (IBusLookupTable    *table,

                                                 gboolean            visible);

/**

 * ibus_lookup_table_is_cursor_visible:

 * @table: An #IBusLookupTable.

 *

 * Returns whether the cursor of an #IBusLookupTable is visible.

 *

 * Returns: Whether the cursor of @table is visible.

 */

gboolean             ibus_lookup_table_is_cursor_visible

                                                (IBusLookupTable    *table);

/**

 * ibus_lookup_table_get_cursor_in_page:

 * @table: An IBusLookupTable.

 *

 * Gets the cursor position in current page of #IBusLookupTable.

 *

 * Returns: The position of cursor in current page.

 */

guint                ibus_lookup_table_get_cursor_in_page

                                                (IBusLookupTable    *table);

/**

 * ibus_lookup_table_set_page_size:

 * @table: An IBusLookupTable.

 * @page_size: number of candidate shown per page.

 *

 * Set the number of candidate shown per page.

 */

void                 ibus_lookup_table_set_page_size

                                                (IBusLookupTable    *table,

                                                 guint               page_size);

/**

 * ibus_lookup_table_get_page_size:

 * @table: An IBusLookupTable.

 *

 * Gets the number of candidate shown per page.

 *

 * Returns: Page size, i.e., number of candidate shown per page.

dd

 */

guint                ibus_lookup_table_get_page_size

                                                (IBusLookupTable    *table);

/**

 * ibus_lookup_table_set_round:

 * @table: An IBusLookupTable.

 * @round: Whether to make @table round.

 *

 * Set whether to make the IBusLookupTable round or not.

 */

void                 ibus_lookup_table_set_round

                                                (IBusLookupTable    *table,

                                                 gboolean            round);

/**

 * ibus_lookup_table_is_round:

 * @table: An IBusLookupTable.

 *

 * Returns whether the #IBusLookupTable is round.

 *

 * Returns: Whether the @table is round.

 */

gboolean             ibus_lookup_table_is_round (IBusLookupTable    *table);

/**

 * ibus_lookup_table_set_orientation:

 * @table: An IBusLookupTable.

 * @orientation: .

 *

 * Set the orientation.

 */

void                 ibus_lookup_table_set_orientation

                                                (IBusLookupTable    *table,

                                                 gint                orientation);

/**

 * ibus_lookup_table_get_orientation:

 * @table: An IBusLookupTable.

 *

 * Returns the orientation of the #IBusLookupTable.

 *

 * Returns: The orientation of the @table.

 */

gint                 ibus_lookup_table_get_orientation

                                                (IBusLookupTable    *table);

/**

 * ibus_lookup_table_clear:

 * @table: An IBusLookupTable.

 *

 * Clear and remove all candidate from an IBusLookupTable.

 */

void                 ibus_lookup_table_clear    (IBusLookupTable    *table);

/**

 * ibus_lookup_table_page_up:

 * @table: An IBusLookupTable.

 *

 * Go to previous page of an #IBusLookupTable.

 *

 * It returns FALSE if it is already at the first page,

 * unless  table>-round==TRUE, where it will go

 * to the last page.

 *

 * Returns: %TRUE if succeed.

 */

gboolean             ibus_lookup_table_page_up  (IBusLookupTable    *table);

/**

 * ibus_lookup_table_page_down:

 * @table: An IBusLookupTable.

 *

 * Go to next page of an #IBusLookupTable.

 *

 * It returns FALSE if it is already at the last page,

 * unless  table>-round==TRUE, where it will go

 * to the first page.

 *

 * Returns: %TRUE if succeed.

 */

gboolean             ibus_lookup_table_page_down(IBusLookupTable    *table);

/**

 * ibus_lookup_table_cursor_up:

 * @table: An IBusLookupTable.

 *

 * Go to previous candidate of an #IBusLookupTable.

 *

 * It returns FALSE if it is already at the first candidate,

 * unless  table>-round==TRUE, where it will go

 * to the last candidate.

 *

 * Returns: %TRUE if succeed.

 */

gboolean             ibus_lookup_table_cursor_up(IBusLookupTable    *table);

/**

 * ibus_lookup_table_cursor_down:

 * @table: An IBusLookupTable.

 *

 * Go to next candidate of an #IBusLookupTable.

 *

 * It returns FALSE if it is already at the last candidate,

 * unless  table>-round==TRUE, where it will go

 * to the first candidate.

 *

 * Returns: %TRUE if succeed.

 */

gboolean             ibus_lookup_table_cursor_down

                                                (IBusLookupTable    *table);

G_END_DECLS

#endif