02 Rutinas de configuración

Varias partes de Allegro, como las rutinas de sonido y la función load_joystick_data, requieren cierta información de configuración. Estos datos son almacenados en ficheros de texto como una colección de líneas "variable=valor", junto con comentarios que empiezan con el caracter '#' y acaban al fina de la línea. El fichero de configuración puede estar dividido en secciones que empiezan con una línea "[nombresección]". Cada sección tiene un nombre único, para prevenir conflictos con los nombres, pero la variable que no esté en una sección determinada es considerada perteneciente a todas simultáneamente.

Por defecto los datos de configuración se lee de un fichero llamado allegro.cfg, que puede estar en el mismo directoria que el programa ejecutable o en el directorio apuntado por la variable de entorno ALLEGRO. En Unix también busca en ~/allegro.cfg, ~/.allegrorc, /etc/allegro.cfg, y /etc/allegrorc, en ese orden; bajo BeOS sólo comprueba los dós últimos. Si esto no te gusta puedes especificar cualquier nombre de fichero, o usar un bloque binario de datos de configuracion proporcionado por tu programa (que, por ejemplo, puede ser cargado desde un fichero de datos).

Puede almacenar cualquier información que quiera en el fichero de configuración, junto con las variables estándar usadas por Allegro (mire abajo).


void set_config_file(const char *filename);
Especifica el fichero de configuración que será usado por las siguientes rutinas de configuración. Si no llama esta función, Allegro usará el fichero allegro.cfg, mirando primero en el directorio de su programa y luego en el directorio apuntado por la variable de entorno ALLEGRO.

¡Todos los punteros devueltos por llamadas previas a get_config_string() y demás funciones similares son invalidados tras llamar a esta función!

Relacionado con: set_config_data, override_config_file, push_config_state, Variables de configuración estándar, set_config_string, get_config_string.
void set_config_data(const char *data, int length);
Especifica un bloque de datos que será usados por las siguientes rutinas de configuración, que previamente ha cargado del disco (ejemplo: como parte de un formato propio más complicado, o desde un fichero de datos). Esta rutina hace una copia de la información, por lo que puede liberar los datos después de llamarla.
Relacionado con: set_config_file, override_config_data, push_config_state, Variables de configuración estándar, set_config_string, get_config_string.
void override_config_file(const char *filename);
Especifica un fichero que contiene una configuración de sobreescritura. Sus datos serán usados además de los parámetros del fichero de configuración principal, y si hay una misma variable en ambos ficheros, la del fichero de sobreescritura tendrá preferencia. Esto puede ser usado por las aplicaciones del programador que deben tener ciertos valores de configuración fijos, pero otros del fichero de configuración principal pueden ser modificados por el usuario. Por ejemplo, podría especificar una frecuencia de muestreo de sonido y un fichero de instrumentos IBK específicos, pero el usuario podría usar un fichero sound.cfg o allegro.cfg para especificar los ajustes de su tarjeta de sonido (puertos, valores IRQ, etc).
Relacionado con: override_config_data, set_config_file.
void override_config_data(const char *data, int length);
Versión de override_config_file() que usa un bloque de datos que ya ha sido cargado en memoria.
Relacionado con: override_config_file, set_config_data.
void push_config_state();
Almacena el estado actual de configuración (nombre de fichero, valores de las variables, etc) en una pila interna, permitiéndole seleccionar otro fichero de configuración para después recuperar la configuración actual llamando pop_config_state(). Esta función está pensada para uso interno por otras funciones de la biblioteca, por ejemplo, cuando quiere especificar el fichero de configuración de la función save_joystick_data(), almacena la configuración actual antes de usar la del fichero especificado.
Relacionado con: pop_config_state, set_config_file.
void pop_config_state();
Recupera el estado previo de la configuración almacenado por la función push_config_state() sobreescribiendo el código del fichero de configuración actual.
Relacionado con: push_config_state.
void flush_config_file();
Escribe el contenido del fichero de configuración actual al disco en caso de que haya cambiado desde que fue cargado o desde la última llamada a esta función.
Relacionado con: set_config_file, override_config_file, push_config_state.
void reload_config_texts(const char *new_language);
Recarga las cadenas traducidas devueltas por get_config_text. Esto es útil para cambiar a otro lenguaje en su programa en tiempo de ejecución. Si quiere modificar manualmente la variable de configuración [system] language, o ha cambiado de ficheros de comfiguración, querrá pasar NULL para recargar el lenguaje que esté seleccionado actualmente. O puede pasar una cadena que contenga el código de dos letras del lenguaje al que desea cambiar, y la función modificará la variable language. Tras la llamada a esta función, los punteros previamente devueltos por get_config_text serán inválidos.
Relacionado con: get_config_text, get_config_string, Variables de configuración estándar.
void hook_config_section(const char *section, int (*intgetter)(const char *name, int def), const char *(*stringgetter)(const char *name, char *def), void (*stringsetter)(const char *name, const char *value));
Toma control de la sección especificada del fichero de configuración, para que sus funciones de enganche sean usadas para manipularlo, en vez del acceso de disco normal. Si tanto las funciones getter como setter son NULL, un enganche presente será desenganchado. Las funciones enganchadas tienen la máxima prioridad. Si una sección está enganchada, la función de enganche siempre será llamada, por lo que puede enganchar una sección '#': incluso tengrá prioridad sobre la función verride_config_file().
Relacionado con: config_is_hooked.
int config_is_hooked(const char *section);
Devuelve TRUE si la sección especificada está siendo enganchada.
Relacionado con: hook_config_section.
char *get_config_string(const char *section, const char *name, const char *def);
Recupera la cadena de texto de la variable name del fichero de configuración actual. Si la variable mencionada no es encontrada o su entrada está vacía, el valor def es devuelto. El nombre de sección puede ser NULL para aceptar variables de cualquier parte del fichero, o puede ser usado para controlar en qué conjunto de parámetros (ejemplo: sonido o joystick) va a buscar la variable.
Relacionado con: get_config_hex, get_config_int, get_config_id, set_config_file, set_config_string, get_config_argv, get_config_float.
int get_config_int(const char *section, const char *name, int def);
Lee un entero de la variable name del fichero de configuración actual. Lea el comentario de la función get_config_string().
Relacionado con: get_config_float, get_config_hex, get_config_id, set_config_file, set_config_int, get_config_string, get_config_argv.
int get_config_hex(const char *section, const char *name, int def);
Lee un entero de la variable name del fichero de configuración actual, en formato hexadecimal. Lea el comentario de la función get_config_string().
Relacionado con: get_config_float, get_config_int, get_config_id, set_config_file, set_config_hex, get_config_string, get_config_argv.
float get_config_float(const char *section, const char *name, float def);
Lee un número en coma flotante de la variable name del fichero de configuración actual. Lea el comentario de la función get_config_string().
Relacionado con: get_config_hex, get_config_int, get_config_id, set_config_file, set_config_float, get_config_string, get_config_argv.
int get_config_id(const char *section, const char *name, int def);
Lee una variable ID de 4 letras del fichero de configuración actual. Lea el comentario de la función get_config_string();
Relacionado con: get_config_float, get_config_hex, get_config_int, set_config_file, set_config_id, get_config_string, get_config_argv.
char **get_config_argv(const char *section, const char *name, int *argc);
Lee una lista de tokens (palabras separadas por espacios) del fichero de configuración actual, devolviendo una lista de argumentos al estilo de argv, y ajustando argc al número de tokens (a diferencia de argc/argv, esta lista tiene como base el cero). Devuelve NULL y ajusta argc a cero si la variable no esta presente. La lista de tokens es almacenada en un buffer temporal que será sobreescrito por la siguiente llamada a get_config_argv(), por lo que no espere que los datos persistan allí.
Relacionado con: get_config_int, get_config_id, set_config_file, get_config_string, get_config_float, get_config_hex.
char *get_config_text(const char *msg);
Esta función es usada principalmente por código interno de la biblioteca, pero también puede serle útil a los programadores de aplicaciones. Usa el fichero language.dat o los ficheros XXtext.cfg (donde XX es el código del lenguaje) para mirar una versión traducida del parámetro en el lenguage actualmente seleccionado, devolviendo una traducción si ésta existe o una copia del parámetro si no hay otra cosa disponible. Esto es básicamente lo mismo que llamar get_config_string() con [language] como sección, msg como nombre de variable, y msg como como valor por defecto, pero tiene código especial añadido para manejar conversiones entre formatos Unicode. El parámetro msg siempre se pasa en ASCII, pero la cadena devuelta será convertida al formato de texto actual, reservando memoria siempre que sea necesario, por lo que puede asumir que el puntero devuelto persistirá, sin que tenga que reservar memoria manualmente para cada cadena.
Relacionado con: get_config_string, reload_config_texts, Variables de configuración estándar.
void set_config_string(const char *section, const char *name, const char *val);
Escribe una cadena en la variable name del fichero de configuración actual, sobreescribiendo cualquier valor previo, o borra la variable si val es NULL. El nombre de sección puede ser NULL para escribir la variable en la raíz del fichero, o puede ser usada para especificar la sección en la que desea insertar la variable. El fichero alterado será puesto en memoria cache, y no será escrito en disco hasta que llame allegro_exit(). Tenga en cuenta que sólo puede escribir en los ficheros de este modo, por lo que la función no tendrá efecto si el fichero de configuración actual fue especificado con set_config_data() en vez de con set_config_file().

Como caso especial, las variables o nombres de sección que comienzan con el carácter '#' son tratadas especialmente y no serán leídas o escritas en disco. Los paquetes adicionales pueden usar esto para almacenar información de version y otra información de estado en el módulo de configuración, desde el cual puede ser leída con la función get_config_string().

Relacionado con: set_config_file, get_config_string, set_config_float, set_config_hex, set_config_int, set_config_id.
void set_config_int(const char *section, const char *name, int val);
Escribe un entero en una variable en el fichero de configuración actual. Lea el comentario de set_config_string().
Relacionado con: set_config_file, get_config_int, set_config_string, set_config_float, set_config_hex, set_config_id.
void set_config_hex(const char *section, const char *name, int val);
Escribe un entero en una variable en el fichero de configuración actual, en formato hexadecimal. Lea el comentario de set_config_string().
Relacionado con: set_config_file, get_config_hex, set_config_string, set_config_float, set_config_int, set_config_id.
void set_config_float(const char *section, const char *name, float val);
Escribe un número en coma flotante en una variable en el fichero de configuración actual. Lea el comentario de set_config_string().
Relacionado con: set_config_file, get_config_float, set_config_string, set_config_hex, set_config_int, set_config_id.
void set_config_id(const char *section, const char *name, int val);
Escribe una variable ID de 4 letras en el fichero de configuración actual. Lea el comentario de la función set_config_string().
Relacionado con: set_config_file, get_config_id, set_config_string, set_config_float, set_config_hex, set_config_int.

Variables de configuración estándar

Allegro usa las siguientes variables estándar del fichero de configuración:

Relacionado con: set_config_file, set_config_string, get_config_string.

Volver al Indice