GdictContext: MATE Dictionary Library Reference Manual

## GdictContext GdictContext — Interface for dictionary transports |

## Functions

GQuark | gdict_context_error_quark ()
GdictDatabase * | gdict_database_ref ()
void | gdict_database_unref ()
const gchar * | gdict_database_get_name ()
const gchar * | gdict_database_get_full_name ()
GdictStrategy * | gdict_strategy_ref ()
void | gdict_strategy_unref ()
const gchar * | gdict_strategy_get_name ()
const gchar * | gdict_strategy_get_description ()
GdictMatch * | gdict_match_ref ()
void | gdict_match_unref ()
const gchar * | gdict_match_get_word ()
const gchar * | gdict_match_get_database ()
GdictDefinition * | gdict_definition_ref ()
void | gdict_definition_unref ()
gint | gdict_definition_get_total ()
const gchar * | gdict_definition_get_word ()
const gchar * | gdict_definition_get_database ()
const gchar * | gdict_definition_get_text ()
void | gdict_context_set_local_only ()
gboolean | gdict_context_get_local_only ()
gboolean | gdict_context_lookup_databases ()
gboolean | gdict_context_lookup_strategies ()
gboolean | gdict_context_match_word ()
gboolean | gdict_context_define_word ()

## Properties

gboolean | local-only | Read / Write

## Signals

void | database-found | Run Last
void | definition-found | Run Last
void | error | Run Last
void | lookup-end | Run Last
void | lookup-start | Run Last
void | match-found | Run Last
void | strategy-found | Run Last

## Types and Values

#define | GDICT_CONTEXT_ERROR
enum | GdictContextError
struct | GdictContextIface
| GdictDatabase
| GdictDefinition
| GdictMatch
| GdictStrategy

## Object Hierarchy

        GBoxed
        ├── GdictDatabase
        ├── GdictDefinition
        ├── GdictMatch
        ╰── GdictStrategy
        GInterface
        ╰── GdictContext

## Description

GdictContext is an interface used to uniformly access dictionary transport objects. Each implementation of GdictContext must provide functions for accessing the list of databases available on a dictionary source and the available matching strategies; a function for retrieving all words matching a given string, inside one (or more) of those databases and using one of those strategies; a function for querying one (or more) of those databases for a definition of a word.

Implementations of the GdictContext interface should query their dictionary sources asynchronously; methods of the GdictContext interface should return immediately, and each time a new database, strategy, match or definition has been found, a signal should be fired by those implementations.

## Functions

### gdict_context_error_quark ()

    GQuark
    gdict_context_error_quark (void);

### gdict_database_ref ()

    GdictDatabase *
    gdict_database_ref (GdictDatabase *db);

Increases the reference count of `db` by one.

#### Parameters

db | a GdictDatabase |

#### Returns

`db` with its reference count increased

Since: 1.0

### gdict_database_unref ()

    void
    gdict_database_unref (GdictDatabase *db);

Decreases the reference count of `db` by one. If the reference count reaches zero, `db` is destroyed.

#### Parameters

db | a GdictDatabase |

Since: 1.0

### gdict_database_get_name ()

    const gchar *
    gdict_database_get_name (GdictDatabase *db);

Gets the short name of the database, to be used with functions like `gdict_context_match_word()` or `gdict_context_define_word()`.

#### Parameters

db | a GdictDatabase |

#### Returns

the short name of the database. The string is owned by the GdictDatabase object, and should never be modified or freed.

Since: 1.0

### gdict_database_get_full_name ()

    const gchar *
    gdict_database_get_full_name (GdictDatabase *db);

Gets the full name of the database, suitable for display.

#### Parameters

db | a GdictDatabase |

#### Returns

the full name of the database. The string is owned by the GdictDatabase object, and should never be modified or freed.

Since: 1.0

### gdict_strategy_ref ()

    GdictStrategy *
    gdict_strategy_ref (GdictStrategy *strat);

Increases the reference count of `strat` by one.

#### Parameters

strat | a GdictStrategy |

#### Returns

the GdictStrategy object with its reference count increased

Since: 1.0

### gdict_strategy_unref ()

    void
    gdict_strategy_unref (GdictStrategy *strat);

Decreases the reference count of `strat` by one. If the reference count reaches zero, the GdictStrategy object is freed.

#### Parameters

strat | a GdictStrategy |

Since: 1.0

### gdict_strategy_get_name ()

    const gchar *
    gdict_strategy_get_name (GdictStrategy *strat);

FIXME

#### Parameters

strat | a GdictStrategy |

#### Returns

FIXME

Since: 1.0

### gdict_strategy_get_description ()

    const gchar *
    gdict_strategy_get_description (GdictStrategy *strat);

FIXME

#### Parameters

strat | a GdictStrategy |

#### Returns

FIXME

Since: 1.0

### gdict_match_ref ()

    GdictMatch *
    gdict_match_ref (GdictMatch *match);

FIXME

#### Parameters

match | a GdictMatch |

#### Returns

FIXME

Since: 1.0

### gdict_match_unref ()

    void
    gdict_match_unref (GdictMatch *match);

FIXME

#### Parameters

match | a GdictMatch |

Since: 1.0

### gdict_match_get_word ()

    const gchar *
    gdict_match_get_word (GdictMatch *match);

FIXME

#### Parameters

match | a GdictMatch |

#### Returns

FIXME

Since: 1.0

### gdict_match_get_database ()

    const gchar *
    gdict_match_get_database (GdictMatch *match);

FIXME

#### Parameters

match | a GdictMatch |

#### Returns

FIXME

Since: 1.0

### gdict_definition_ref ()

    GdictDefinition *
    gdict_definition_ref (GdictDefinition *def);

Increases the reference count of `def` by one.

#### Parameters

def | a GdictDefinition |

#### Returns

the GdictDefinition object with its reference count increased.

Since: 1.0

### gdict_definition_unref ()

    void
    gdict_definition_unref (GdictDefinition *def);

Decreases the reference count of `def` by one. If the reference count reaches zero, the GdictDefinition object is freed.

#### Parameters

def | a GdictDefinition |

Since: 1.0

### gdict_definition_get_total ()

    gint
    gdict_definition_get_total (GdictDefinition *def);

Retrieves the total number of definitions that were found on a dictionary.

#### Parameters

def | a GdictDefinition |

#### Returns

the number of definitions.

Since: 1.0

### gdict_definition_get_word ()

    const gchar *
    gdict_definition_get_word (GdictDefinition *def);

Retrieves the word used by the dictionary database to store the definition.

#### Parameters

def | a GdictDefinition |

#### Returns

a word. The returned string is owned by the GdictDefinition object and should not be modified or freed.

Since: 1.0

### gdict_definition_get_database ()

    const gchar *
    gdict_definition_get_database (GdictDefinition *def);

Retrieves the full name of the dictionary database where the definition is stored.

#### Parameters

def | a GdictDefinition |

#### Returns

the full name of a database. The returned string is owned by the GdictDefinition object and should not be modified or freed.

Since: 1.0

### gdict_definition_get_text ()

    const gchar *
    gdict_definition_get_text (GdictDefinition *def);

Retrieves the text of the definition.

#### Parameters

def | a GdictDefinition |

#### Returns

the text of the definition. The returned string is owned by the GdictDefinition object, and should not be modified or freed.

Since: 1.0

### gdict_context_set_local_only ()

    void
    gdict_context_set_local_only (GdictContext *context,
                                  gboolean local_only);

Sets whether only local resources will be used when querying for databases, strategies, matches or definitions.

#### Parameters

context | a GdictContext |
local_only | `TRUE` if only local resources will be used |

Since: 1.0

### gdict_context_get_local_only ()

    gboolean
    gdict_context_get_local_only (GdictContext *context);

Gets whether only local resources will be used when querying.

#### Parameters

context | a GdictContext |

#### Returns

`TRUE` if only local resources will be used.

Since: 1.0

### gdict_context_lookup_databases ()

    gboolean
    gdict_context_lookup_databases (GdictContext *context,
                                    GError **error);

Query `context` for the list of databases available. Each time a database is found, the "database-found" signal is fired.

#### Parameters

context | a GdictContext |
error | return location for a GError, or `NULL` |

#### Returns

`TRUE` if the query was successfully started.

Since: 1.0

### gdict_context_lookup_strategies ()

    gboolean
    gdict_context_lookup_strategies (GdictContext *context,
                                     GError **error);

Query `context` for the list of matching strategies available. Each time a new strategy is found, the "strategy-found" signal is fired.

#### Parameters

context | a GdictContext |
error | return location for a GError, or `NULL` |

#### Returns

`TRUE` if the query was successfully started.

Since: 1.0

### gdict_context_match_word ()

    gboolean
    gdict_context_match_word (GdictContext *context,
                              const gchar *database,
                              const gchar *strategy,
                              const gchar *word,
                              GError **error);

Query `context` for a list of word matching `word` inside `database` , using `strategy` as a matching strategy. Each time a matching word is found, the "match-found" signal is fired.

#### Parameters

context | a GdictContext |
database | a database name to search into, or `NULL` for the default database |
strategy | a strategy name to use for matching, or `NULL` for the default strategy |
word | the word to match |
error | return location for a GError, or `NULL` |

#### Returns

`TRUE` if the query was successfully started.

Since: 1.0

### gdict_context_define_word ()

    gboolean
    gdict_context_define_word (GdictContext *context,
                               const gchar *database,
                               const gchar *word,
                               GError **error);

Query `context` for a list of definitions of `word` inside `database` . Each time a new definition is found, the "definition-found" signal is fired.

#### Parameters

context | a GdictContext |
database | a database name to search into, or `NULL` for the default database |
word | the word to search |
error | return location for a GError, or `NULL` |

#### Returns

`TRUE` if the query was successfully sent.

Since: 1.0

## Types and Values

### GDICT_CONTEXT_ERROR

    #define GDICT_CONTEXT_ERROR (gdict_context_error_quark ())

### enum GdictContextError

GdictContext error enumeration.

#### Members

GDICT_CONTEXT_ERROR_PARSE |  |
GDICT_CONTEXT_ERROR_NOT_IMPLEMENTED |  |
GDICT_CONTEXT_ERROR_INVALID_DATABASE |  |
GDICT_CONTEXT_ERROR_INVALID_STRATEGY |  |
GDICT_CONTEXT_ERROR_INVALID_COMMAND |  |
GDICT_CONTEXT_ERROR_NO_MATCH |  |
GDICT_CONTEXT_ERROR_NO_DATABASES |  |
GDICT_CONTEXT_ERROR_NO_STRATEGIES |  |

### struct GdictContextIface

    struct GdictContextIface {
      /* methods, not signals */
      gboolean (*get_databases)     (GdictContext  *context,
      			         GError       **error);
      gboolean (*get_strategies)    (GdictContext  *context,
      			         GError       **error);
      gboolean (*match_word)        (GdictContext  *context,
      			         const gchar   *database,
      			         const gchar   *strategy,
      			         const gchar   *word,
      			         GError       **error);
      gboolean (*define_word)       (GdictContext  *context,
      			         const gchar   *database,
      			         const gchar   *word,
      			         GError       **error);

      /* signals */
      void (*lookup_start)     (GdictContext    *context);
      void (*lookup_end)       (GdictContext    *context);

      void (*database_found)   (GdictContext    *context,
      			    GdictDatabase   *database);
      void (*strategy_found)   (GdictContext    *context,
      			    GdictStrategy   *strategy);
      void (*match_found)      (GdictContext    *context,
      			    GdictMatch      *match);
      void (*definition_found) (GdictContext    *context,
      			    GdictDefinition *definition);

      /* fired each time there's an error; the GError is owned
       * by the context, and should never be modified or freed
       */
      void (*error)            (GdictContext    *context,
      			    const GError    *error);
    };

Interface defintion

### GdictDatabase

    typedef struct _GdictDatabase GdictDatabase;

A GdictDatabase represents a database inside a dictionary source.

The GdictDatabase structure is private and should only be accessed using the available functions.

### GdictDefinition

    typedef struct _GdictDefinition GdictDefinition;

A GdictDefinition represents a single definition for the searched word.

The GdictDefinition structure is private and should only be accessed using the available functions.

### GdictMatch

    typedef struct _GdictMatch GdictMatch;

A GdictMatch represents a single match for the searched word.

The GdictMatch structure is private and should only be accessed using the available functions.

### GdictStrategy

    typedef struct _GdictStrategy GdictStrategy;

A GdictStrategy represents a matching strategy implemented by a dictionary source.

The GdictStrategy structure is private and should only be accessed using the available functions.

## Property Details

### The `“local-only”` property

      “local-only”               gboolean

Whether the context uses only local dictionaries or not.

Flags: Read / Write

Default value: FALSE

Since: 1.0

## Signal Details

### The `“database-found”` signal

    void
    user_function (GdictContext  *context,
                   GdictDatabase *database,
                   gpointer       user_data)

This signal is emitted when a database request has found a database.

#### Parameters

context | the object which received the signal |
database | a GdictDatabase |
user_data | user data set when the signal handler was connected. |

Flags: Run Last

Since: 1.0

### The `“definition-found”` signal

    void
    user_function (GdictContext    *context,
                   GdictDefinition *definition,
                   gpointer         user_data)

This signal is emitted when a definition request has found a definition.

#### Parameters

context | the object which received the signal |
definition | a GdictDefinition |
user_data | user data set when the signal handler was connected. |

Flags: Run Last

Since: 1.0

### The `“error”` signal

    void
    user_function (GdictContext *context,
                   gpointer      error,
                   gpointer      user_data)

This signal is emitted when an error happened during an asynchronous request.

#### Parameters

context | the object which received the signal |
error | a GError |
user_data | user data set when the signal handler was connected. |

Flags: Run Last

Since: 1.0

### The `“lookup-end”` signal

    void
    user_function (GdictContext *context,
                   gpointer      user_data)

This signal is emitted when a look up operation that has been issued using a GdictContext has been completed. Since every operation using a context is asynchronous, you can use this signal to know if the request has been completed or not.

#### Parameters

context | the object which received the signal |
user_data | user data set when the signal handler was connected. |

Flags: Run Last

Since: 1.0

### The `“lookup-start”` signal

    void
    user_function (GdictContext *context,
                   gpointer      user_data)

This signal is emitted when a look up operation has been issued using a GdictContext. Since every operation using a context is asynchronous, you can use this signal to know if the request has been issued or not.

#### Parameters

context | the object which received the signal |
user_data | user data set when the signal handler was connected. |

Flags: Run Last

Since: 1.0

### The `“match-found”` signal

    void
    user_function (GdictContext *context,
                   GdictMatch   *match,
                   gpointer      user_data)

This signal is emitted when a match request has found a match.

#### Parameters

context | the object which received the signal |
match | a GdictMatch |
user_data | user data set when the signal handler was connected. |

Flags: Run Last

Since: 1.0

### The `“strategy-found”` signal

    void
    user_function (GdictContext  *context,
                   GdictStrategy *strategy,
                   gpointer       user_data)

This signal is emitted when a strategy request has found a strategy.

#### Parameters

context | the object which received the signal |
strategy | a GdictStrategy |
user_data | user data set when the signal handler was connected. |

Flags: Run Last

Since: 1.0