Edje Development of External Plugins

Functions
Edje Development of External Plugins
Edje » Edje External

Functions to register, unregister EXTERNAL types and develop the plugins. More...

## Functions
Eina_Bool | edje_external_type_register (const char *type_name, const Edje_External_Type *type_info)
| Registers a type to be used by EXTERNAL parts. More...
Eina_Bool | edje_external_type_unregister (const char *type_name)
| Unregisters a previously registered EXTERNAL type. More...
void | edje_external_type_array_register (const Edje_External_Type_Info *array)
| Registers a batch of types and their information. More...
void | edje_external_type_array_unregister (const Edje_External_Type_Info *array)
| Unregisters a batch of given external type previously registered. More...
unsigned int | edje_external_type_abi_version_get (void)
| Returns the current ABI version for Edje_External_Type structure. More...
Eina_Iterator * | edje_external_iterator_get (void)
Edje_External_Param * | edje_external_param_find (const Eina_List *params, const char *key)
| Convenience function to find a specific parameter in a list of them. More...
Eina_Bool | edje_external_param_int_get (const Eina_List *params, const char *key, int *ret)
| Gets the value of the given parameter of integer type. More...
Eina_Bool | edje_external_param_double_get (const Eina_List *params, const char *key, double *ret)
| Gets the value of the given parameter of double type. More...
Eina_Bool | edje_external_param_string_get (const Eina_List *params, const char *key, const char **ret)
| Gets the value of the given parameter of string type. More...
Eina_Bool | edje_external_param_bool_get (const Eina_List *params, const char *key, Eina_Bool *ret)
| Gets the value of the given parameter of boolean type. More...
Eina_Bool | edje_external_param_choice_get (const Eina_List *params, const char *key, const char **ret)
| Gets the value of the given parameter of choice type. More...
const Edje_External_Param_Info * | edje_external_param_info_get (const char *type_name)
| Gets the array of parameters information about a type given its name. More...
const Edje_External_Type * | edje_external_type_get (const char *type_name)
| Gets the Edje_External_Type that defines an EXTERNAL type registered with the name `type_name`.

## Detailed Description

Functions to register, unregister EXTERNAL types and develop the plugins.

This group discusses functions useful for the development of new plugins. These functions deal with the newly EXTERNAL types by registering, unregistering and manipulating them.

## Function Documentation

## ◆ edje_external_type_register()

Eina_Bool edje_external_type_register | ( | const char * | type_name,
|  | const Edje_External_Type * | type_info
| ) |  |

Registers a type to be used by EXTERNAL parts.

Parts of type EXTERNAL will call user defined functions to create and manipulate the object that's allocated in that part. This is done by expecifying in the `source` property of the part the name of the external to use, which must be one registered with this function.

Parameters

  type_name | Name to register and be known by edje's "source:" parameter of "type: EXTERNAL" parts.
  type_info | Meta-information describing how to interact with it.

Returns
  `EINA_TRUE` on success, `EINA_FALSE` on failure (like type already registered).

See also
  edje_external_type_array_register()

References _Edje_External_Type::abi_version, EDJE_EXTERNAL_TYPE_ABI_VERSION, EINA_FALSE, eina_hash_add(), eina_hash_find(), and ERR.

## ◆ edje_external_type_unregister()

Eina_Bool edje_external_type_unregister | ( | const char * | type_name | ) |

Unregisters a previously registered EXTERNAL type.

Parameters

  type_name | name to unregister. It should have been registered with edje_external_type_register() before.

Returns
  `EINA_TRUE` on success, `EINA_FALSE` on failure (like type_name did not exist).

See also
  edje_external_type_array_unregister()

References EINA_FALSE, and eina_hash_del_by_key().

## ◆ edje_external_type_array_register()

void edje_external_type_array_register | ( | const Edje_External_Type_Info * | array | ) |

Registers a batch of types and their information.

When several types will be registered it is recommended to use this function instead of several calls to edje_external_type_register(), as it is faster.

Note
  The contents of the array will be referenced directly for as long as the type remains registered, so both the `name` and `info` in the `array` must be kept alive during all this period (usually, the entire program lifetime). The most common case would be to keep the array as a `static` `const` type anyway.

Parameters

  array | `NULL` terminated array with type name and information. Note that type name or information are referenced directly, so they must be kept alive after this function returns!

Returns
  `EINA_TRUE` on success, `EINA_FALSE` on failure (like type already registered).

See also
  edje_external_type_register()

References _Edje_External_Type::abi_version, EDJE_EXTERNAL_TYPE_ABI_VERSION, eina_hash_direct_add(), ERR, _Edje_External_Type_Info::info, and _Edje_External_Type_Info::name.

## ◆ edje_external_type_array_unregister()

void edje_external_type_array_unregister | ( | const Edje_External_Type_Info * | array | ) |

Unregisters a batch of given external type previously registered.

Parameters

  array | `NULL` terminated array, should be the same as the one used to register with edje_external_type_array_register()

See also
  edje_external_type_unregister()

References eina_hash_del(), _Edje_External_Type_Info::info, and _Edje_External_Type_Info::name.

## ◆ edje_external_type_abi_version_get()

unsigned int edje_external_type_abi_version_get | ( | void |  | ) |

Returns the current ABI version for Edje_External_Type structure.

Always check this number before accessing Edje_External_Type in your own software. If the number is not the same, your software may access invalid memory and crash, or just get garbage values.

Warning
  NEVER, EVER define your own Edje_External_Type using the return of this function as it will change as Edje library (libedje.so) changes, but your type definition will not. Instead, use EDJE_EXTERNAL_TYPE_ABI_VERSION.

Summary:

- use edje_external_type_abi_version_get() to check.
- use EDJE_EXTERNAL_TYPE_ABI_VERSION to define/declare.

Returns
  The external ABI version the Edje library was compiled with. That is, the value EDJE_EXTERNAL_TYPE_ABI_VERSION had at that moment.

References EDJE_EXTERNAL_TYPE_ABI_VERSION.

## ◆ edje_external_iterator_get()

Eina_Iterator* edje_external_iterator_get | ( | void |  | ) |

Returns
  An iterator of all the registered EXTERNAL types.

Each item in the iterator is an `Eina_Hash_Tuple` which has the type of the external in the `key` and Edje_External_Type as `data`.

const Eina_Hash_Tuple *tuple;
Eina_Iterator *itr;
const Eina_List *l, *modules;
const char *s;
modules = edje_available_modules_get();
EINA_LIST_FOREACH(modules, l, s)
{
if (!edje_module_load(s))
printf("Error loading edje module: %s\n", s);
}
itr = edje_external_iterator_get();
EINA_ITERATOR_FOREACH(itr, tuple)
{
const char *name = tuple->key;
const Edje_External_Type *type = tuple->data;
if ((!type) ||
(type->abi_version != edje_external_type_abi_version_get()))
{
printf("Error: invalid type %p (abi: %d, expected: %d)\n",
type, type ? type->abi_version : 0,
edje_external_type_abi_version_get());
continue;
}
printf("%s: %s (%s) label='%s' desc='%s'\n",
name, type->module, type->module_name,
type->label_get ? type->label_get(type->data) : "",
type->description_get ? type->description_get(type->data) : "");
}
edje_external_type_abi_version_get
unsigned int edje_external_type_abi_version_get(void)
Returns the current ABI version for Edje_External_Type structure.
Definition: edje_external.c:222
edje_external_iterator_get
Eina_Iterator * edje_external_iterator_get(void)
Definition: edje_external.c:228
edje_available_modules_get
const Eina_List * edje_available_modules_get(void)
Retrieves all modules that can be loaded.
Definition: edje_module.c:149
edje_module_load
Eina_Bool edje_module_load(const char *module)
Loads a new module in Edje.
Definition: edje_module.c:15
EINA_ITERATOR_FOREACH
#define EINA_ITERATOR_FOREACH(itr, data)
Definition for the macro to iterate over all elements easily.
Definition: eina_iterator.h:448
EINA_LIST_FOREACH
#define EINA_LIST_FOREACH(list, l, _data)
Definition for the macro to iterate over a list.
Definition: eina_list.h:1415
_Edje_External_Type
Information about an external type to be used.
Definition: Edje_Common.h:833
_Eina_Hash_Tuple
Data for a hash table of key/value pairs.
Definition: eina_hash.h:298
_Eina_Hash_Tuple::data
void * data
The data associated to the key.
Definition: eina_hash.h:300
_Eina_Hash_Tuple::key
const void * key
The key.
Definition: eina_hash.h:299
_Eina_Iterator
structure of an iterator
Definition: eina_iterator.h:159
_Eina_List
Type for a generic double linked list.
Definition: eina_list.h:318

References eina_hash_iterator_tuple_new().

## ◆ edje_external_param_find()

Edje_External_Param* edje_external_param_find | ( | const Eina_List * | params,
|  | const char * | key
| ) |  |

Convenience function to find a specific parameter in a list of them.

Parameters

  params | The list of parameters for the external
  key | The parameter to look for

Returns
  The matching Edje_External_Param or NULL if it's not found.

References EINA_LIST_FOREACH, and _Edje_External_Param::name.

Referenced by edje_external_param_bool_get(), edje_external_param_choice_get(), edje_external_param_double_get(), edje_external_param_int_get(), and edje_external_param_string_get().

## ◆ edje_external_param_int_get()

Eina_Bool edje_external_param_int_get | ( | const Eina_List * | params,
|  | const char * | key,
|  | int * | ret
| ) |  |

Gets the value of the given parameter of integer type.

Look for the `key` parameter in the `params` list and return its value in `ret`. If the parameter is found and is of type EDJE_EXTERNAL_PARAM_TYPE_INT, its value will be stored in the int pointed by `ret`, returning EINA_TRUE. In any other case, the function returns EINA_FALSE.

Parameters

  params | List of parameters where to look
  key | Name of the parameter to fetch
  ret | Int pointer where to store the value, must not be NULL.

Returns
  `EINA_TRUE` if the parameter was found and is of integer type, `EINA_FALSE` otherwise.

References edje_external_param_find(), EDJE_EXTERNAL_PARAM_TYPE_INT, EINA_FALSE, EINA_TRUE, _Edje_External_Param::i, and _Edje_External_Param::type.

## ◆ edje_external_param_double_get()

Eina_Bool edje_external_param_double_get | ( | const Eina_List * | params,
|  | const char * | key,
|  | double * | ret
| ) |  |

Gets the value of the given parameter of double type.

Look for the `key` parameter in the `params` list and return its value in `ret`. If the parameter is found and is of type EDJE_EXTERNAL_PARAM_TYPE_DOUBLE, its value will be stored in the double pointed by `ret`, returning EINA_TRUE. In any other case, the function returns EINA_FALSE.

Parameters

  params | List of parameters where to look
  key | Name of the parameter to fetch
  ret | Double pointer where to store the value, must not be NULL.

Returns
  `EINA_TRUE` if the parameter was found and is of double type, `EINA_FALSE` otherwise.

References _Edje_External_Param::d, edje_external_param_find(), EDJE_EXTERNAL_PARAM_TYPE_DOUBLE, EINA_FALSE, EINA_TRUE, and _Edje_External_Param::type.

## ◆ edje_external_param_string_get()

Eina_Bool edje_external_param_string_get | ( | const Eina_List * | params,
|  | const char * | key,
|  | const char ** | ret
| ) |  |

Gets the value of the given parameter of string type.

Look for the `key` parameter in the `params` list and return its value in `ret`. If the parameter is found and is of type EDJE_EXTERNAL_PARAM_TYPE_STRING, its value will be stored in the pointer pointed by `ret`, returning EINA_TRUE. In any other case, the function returns EINA_FALSE.

The string stored in `ret` must not be freed or modified.

Parameters

  params | List of parameters where to look
  key | Name of the parameter to fetch
  ret | String pointer where to store the value, must not be NULL.

Returns
  `EINA_TRUE` if the parameter was found and is of string type, `EINA_FALSE` otherwise.

References edje_external_param_find(), EDJE_EXTERNAL_PARAM_TYPE_STRING, EINA_FALSE, EINA_TRUE, _Edje_External_Param::s, and _Edje_External_Param::type.

## ◆ edje_external_param_bool_get()

Eina_Bool edje_external_param_bool_get | ( | const Eina_List * | params,
|  | const char * | key,
|  | Eina_Bool * | ret
| ) |  |

Gets the value of the given parameter of boolean type.

Look for the `key` parameter in the `params` list and return its value in `ret`. If the parameter is found and is of type EDJE_EXTERNAL_PARAM_TYPE_BOOL, its value will be stored in the Eina_Bool pointed by `ret`, returning EINA_TRUE. In any other case, the function returns EINA_FALSE.

Parameters

  params | List of parameters where to look
  key | Name of the parameter to fetch
  ret | Eina_Bool pointer where to store the value, must not be NULL.

Returns
  `EINA_TRUE` if the parameter was found and is of boolean type, `EINA_FALSE` otherwise.

References edje_external_param_find(), EDJE_EXTERNAL_PARAM_TYPE_BOOL, EINA_FALSE, EINA_TRUE, _Edje_External_Param::i, and _Edje_External_Param::type.

## ◆ edje_external_param_choice_get()

Eina_Bool edje_external_param_choice_get | ( | const Eina_List * | params,
|  | const char * | key,
|  | const char ** | ret
| ) |  |

Gets the value of the given parameter of choice type.

Look for the `key` parameter in the `params` list and return its value in `ret`. If the parameter is found and is of type EDJE_EXTERNAL_PARAM_TYPE_CHOICE, its value will be stored in the string pointed by `ret`, returning EINA_TRUE. In any other case, the function returns EINA_FALSE.

The string stored in `ret` must not be freed or modified.

Parameters

  params | List of parameters where to look
  key | Name of the parameter to fetch
  ret | String pointer where to store the value, must not be NULL.

Returns
  EINA_TRUE if the parameter was found and is of integer type, EINA_FALSE otherwise.

References edje_external_param_find(), EDJE_EXTERNAL_PARAM_TYPE_CHOICE, EINA_FALSE, EINA_TRUE, _Edje_External_Param::s, and _Edje_External_Param::type.

## ◆ edje_external_param_info_get()

const Edje_External_Param_Info* edje_external_param_info_get | ( | const char * | type_name | ) |

Gets the array of parameters information about a type given its name.

Note
  the type names and other strings are static, that means they are NOT translated. One must use Edje_External_Type::translate() to translate those.

Parameters

  type_name | Edje external type name

Returns
  the NULL terminated array, or `NULL` if type is unknown or it does not have any parameter information.

See also
  edje_external_type_get()

References eina_hash_find().

Referenced by edje_edit_state_add().