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

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

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

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

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);

a GdictMatch

Since: 1.0

gdict_match_get_word ()

const gchar *
gdict_match_get_word (GdictMatch *match);

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.

Owner: GdictContext

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