# Documentation de la bibliothèque MLV-0.6.716

- Presentation
- Téléchargement
- Installation
- Compilation
- Exemples
- API
- Liste des fonctions
- bogues
- contacts

# Référence du fichier MLV_event.h

Ce fichier définit les prototypes des fonctions permettant d'utiliser les évènements dans la bibliothèque MLV. Plus de détails...

Aller au code source de ce fichier.

## Énumérations
enum | MLV_Event { MLV_NONE = 0, MLV_KEY = 1, MLV_INPUT_BOX = 2, MLV_MOUSE_BUTTON = 3, MLV_MOUSE_MOTION = 4 }
| Énumère les différents types d'évènement de la bibliothèque MLV. Plus de détails...
## Fonctions
MLV_Event | MLV_get_event (MLV_Keyboard_button *key_sym, MLV_Keyboard_modifier *key_mod, int *unicode, char **texte, MLV_Input_box **input_box, int *mouse_x, int *mouse_y, MLV_Mouse_button *mouse_button, MLV_Button_state *state)
| Cette fonction récupère un évènement dans la file d'attente, remplit en fonction de l'évènement récupéré une partie des paramètres de la fonction et renvoie un entier codant le type de l'évènement qui a été récupéré.
MLV_Event | MLV_wait_event (MLV_Keyboard_button *key_sym, MLV_Keyboard_modifier *key_mod, int *unicode, char **texte, MLV_Input_box **input_box, int *mouse_x, int *mouse_y, MLV_Mouse_button *mouse_button, MLV_Button_state *state)
| Cette fonction suspends l'éxecution du programme jusqu'à ce qu'un évènement apparaît dans la file d'attente. Lorsqu'un nouvel évènement apparaît, la fonction remplit ses paramètres et renvoie un entier codant le type de l'évènement qui a été récupéré, si les paramètres passés en argument concernent l'évènement récupéré. se rendort en l'attente d'un nouvel évènement, dans le cas contraire.
MLV_Event | MLV_wait_event_or_seconds (MLV_Keyboard_button *key_sym, MLV_Keyboard_modifier *key_mod, int *unicode, char **texte, MLV_Input_box **input_box, int *mouse_x, int *mouse_y, MLV_Mouse_button *mouse_button, MLV_Button_state *state, int seconds)
| Cette fonction suspends l'éxecution du programme jusqu'à ce qu'un évènement apparaît dans la file d'attente ou jusqu'à ce qu'un certain nombre de secondes se soient écoulées. Si le temps s'est complètement écoulé, la fonction renvoie MLV_NONE. Si un nouvel évènement apparaît et que les paramètres passés en arguments sont en rapport avec l'évènement récupéré, alors la fonction remplit les paramètres et renvoie un entier codant le type de l'évènement qui a été récupéré. Si un nouvel évènement apparaît et qu'il n'est pas en rapport avec les paramètres de la fonction, alors il se rendort dans l'attente d'un nouvel évènement ou de la fin du temps.
void | MLV_flush_event_queue ()
| Cette fonction vide la file d'évènements.
MLV_Event | MLV_wait_keyboard_or_mouse (MLV_Keyboard_button *sym, MLV_Keyboard_modifier *mod, int *unicode, int *mouse_x, int *mouse_y)
| Suspend l'exécution jusqu'à ce que l'utilisateur appuie sur une touche du clavier ou sur le bouton gauche de la souris.
MLV_Event | MLV_wait_keyboard_or_mouse_or_seconds (MLV_Keyboard_button *sym, MLV_Keyboard_modifier *mod, int *unicode, int *mouse_x, int *mouse_y, int seconds)
| Suspend l'exécution jusqu'à ce que l'utilisateur appuie sur une touche du clavier, sur le bouton gauche de la souris ou qu'un certain nombre de secondes passées en paramètres se soient écoulées.
const char * | MLV_convert_event_to_string (MLV_Event event_code)
| Convertit le code d'un évènement en une chaîne de caractères.
MLV_Event | MLV_convert_string_to_event (const char *event_string)
| Convertit le nom d'un évènement en son code associé.
const char * | MLV_convert_button_state_to_string (MLV_Button_state state_code)
| Convertit le code d'un état en une chaîne de caractères.
MLV_Button_state | MLV_convert_string_to_button_state (const char *state_string)
| Convertit le nom d'un état en son code associé.

## Description détaillée

Ce fichier définit les prototypes des fonctions permettant d'utiliser les évènements dans la bibliothèque MLV.

Auteur:
  Adrien Boussicault
  Marc Zipstein

## Documentation du type de l'énumération

enum MLV_Event

Énumère les différents types d'évènement de la bibliothèque MLV.

Valeurs énumérées:

  MLV_NONE | Aucun évènement
  MLV_KEY | Evnènement provenant du clavier
  MLV_INPUT_BOX | Évènement provenant de la validation d'un texte dans une boîte de saisie.
  MLV_MOUSE_BUTTON | Évènement provenant d'un clique de souris.
  MLV_MOUSE_MOTION | Évènement provenant du déplacement de la souris.

## Documentation des fonctions

const char* MLV_convert_button_state_to_string | ( | MLV_Button_state | state_code | ) |

Convertit le code d'un état en une chaîne de caractères.

Paramètres:

  | state_code | le code de l'état

Renvoie:
  La chaîne de caractères associée au code de l'état.

const char* MLV_convert_event_to_string | ( | MLV_Event | event_code | ) |

Convertit le code d'un évènement en une chaîne de caractères.

Paramètres:

  | event_code | le code de l'évènement

Renvoie:
  La chaîne de caractères associée au code de l'évènement.

MLV_Button_state MLV_convert_string_to_button_state | ( | const char * | state_string | ) |

Convertit le nom d'un état en son code associé.

Paramètres:

  | state_string | le nom de l'état.

Renvoie:
  Le code de l'état associé à la chaîne de caractères.

MLV_Event MLV_convert_string_to_event | ( | const char * | event_string | ) |

Convertit le nom d'un évènement en son code associé.

Paramètres:

  | event_string | le nom de l'évènement.

Renvoie:
  Le code de l'évènement associé à la chaîne de caractères.

MLV_Event MLV_get_event | ( | MLV_Keyboard_button * | key_sym,
|  | MLV_Keyboard_modifier * | key_mod,
|  | int * | unicode,
|  | char ** | texte,
|  | MLV_Input_box ** | input_box,
|  | int * | mouse_x,
|  | int * | mouse_y,
|  | MLV_Mouse_button * | mouse_button,
|  | MLV_Button_state * | state |
| ) |  |  |

Cette fonction récupère un évènement dans la file d'attente, remplit en fonction de l'évènement récupéré une partie des paramètres de la fonction et renvoie un entier codant le type de l'évènement qui a été récupéré.

Le type des évènements est défini par :

MLV_Event

et peut valoir les valeurs suivantes:

Valeur ........... Signification

----------------------------------

MLV_NONE .......... Aucun évènement récupéré

MLV_KEY ........... Une touche du clavier a été appuyée ou relachée.

MLV_INPUT_BOX ..... L'utilisateur a écrit une chaîne de caractères et validé cette chaîne par la touche entrée.

MLV_MOUSE_BUTTON .. Un des boutons de la souris a été appuyé.

MLV_MOUS_MOTION ... La souris a été déplacée.

Voici un tableau qui donne les champs modifiés en fonction de l'évènement qui a été récupéré.

Type Évènement .... Paramètres modifiés

---------------------------------------

MLV_NONE .......... AUCUN

MLV_KEY ........... key_sym, key_mod, state

MLV_INPUT_BOX ..... texte, input_box

MLV_MOUSE_BUTTON .. mouse_x, mouse_y, mouse_button, state

MLV_MOUSE_MOTION .. mouse_x, mouse_y

L'utilisateur n'est pas obligé d'utiliser un champs s'il n'en a pas l'utilité. Dans ce cas, il peut mettre la valeur NULL. Le champs est alors ignoré.

Bogue:
  Il est possible que la récuperation du caractère unicode sous Windows ne fonctionne pas bien. En effet, aucun code de portage spécifique n'a été fait à ce sujet.

Bogue:
  Sous WINDOWS, le clavier est configuré en "qwerty".

Renvoie:
  La fonction renvoie un entier codant le type de l'évènement qui a été récupéré.

Paramètres:

  | key_sym | Code de la touche qui a été appuyée ou relachée. La valeur de ce champs est définie par l'énumération : MLV_Keyboard_button.
  | key_mod | Mode dans lequel se trouve le clavier lorsqu'une touche est appuyée ou relachée. La valeur de ce champs est définie par l'énumération : MLV_Keyboard_modifier.
  | unicode | Caractère codé en unicode de la lettre obtenue en combinant le code et le mode précédent
  | texte | Texte récupéré par la boîte de saisie. L'allocation est affectée par la fonction elle-même. La désallocation est à la charge de l'utilisateur.
  | input_box | La boîte de saisie qui a récupérée le texte
  | mouse_x | Coordonnée en X de la position de la souris
  | mouse_y | Coordonnée en Y de la position de la souris
  | mouse_button | Bouton de la souris qui a été appuyé ou relaché. Ce champs est défini par l'énumération MLV_Mouse_button.
  | state | Etat de la touche concernée par l'évènement. La valeur de ce champs est défini par l'énumération: MLV_Button_state.

Exemples:
  advanced/09_animation.c, advanced/11_animation_book.c, medium/01_keyboard_events.c, medium/02_mouse_events.c, medium/03_input_box_events.c, medium/04_events.c, et medium/06_colors.c.

MLV_Event MLV_wait_event | ( | MLV_Keyboard_button * | key_sym,
|  | MLV_Keyboard_modifier * | key_mod,
|  | int * | unicode,
|  | char ** | texte,
|  | MLV_Input_box ** | input_box,
|  | int * | mouse_x,
|  | int * | mouse_y,
|  | MLV_Mouse_button * | mouse_button,
|  | MLV_Button_state * | state |
| ) |  |  |

Cette fonction suspends l'éxecution du programme jusqu'à ce qu'un évènement apparaît dans la file d'attente. Lorsqu'un nouvel évènement apparaît, la fonction

- remplit ses paramètres et renvoie un entier codant le type de l'évènement qui a été récupéré, si les paramètres passés en argument concernent l'évènement récupéré.
- se rendort en l'attente d'un nouvel évènement, dans le cas contraire.

Pour plus d'informations sur les différents types d'évènements et leurs liens avec les paramètres de la fonction, veuillez consulter la documentation de la fonction MLV_get_event().

L'utilisateur n'est pas obligé d'utiliser un champs s'il n'en a pas l'utilité. Dans ce cas, il peut mettre la valeur NULL et le paramètre est ignoré.

Bogue:
  Voir les bugs de la fonction MLV_get_event().

Paramètres:

  | key_sym | Code de la touche qui a été appuyée ou relachée. La valeur de ce champs est définie par l'énumération : MLV_Keyboard_button.
  | key_mod | Mode dans lequel se trouve le clavier lorsqu'une touche est appuyée ou relachée. La valeur de ce champs est définie par l'énumération : MLV_Keyboard_modifier.
  | unicode | Caractère codé en unicode de la lettre obtenue en combinant le code et le mode précédent
  | texte | Texte récupéré par la boîte de saisie. L'allocation est affecté par la la fonction elle même. La désallocation est à la charge de l'utilisateur.
  | input_box | La boîte de saisie qui a récupérée le texte
  | mouse_x | Coordonnée en X de la position de la souris
  | mouse_y | Coordonnée en Y de la position de la souris
  | mouse_button | Bouton de la souris qui a été appuyé ou relaché. Ce champs est défini par l'énumération MLV_Mouse_button.
  | state | Etat de la touche concernée par l'évènement. La valeur de ce champs est défini par l'énumération: MLV_Button_state.

Renvoie:
  La fonction renvoie un entier codant le type de l'évènement qui a été récupéré.

MLV_Event MLV_wait_event_or_seconds | ( | MLV_Keyboard_button * | key_sym,
|  | MLV_Keyboard_modifier * | key_mod,
|  | int * | unicode,
|  | char ** | texte,
|  | MLV_Input_box ** | input_box,
|  | int * | mouse_x,
|  | int * | mouse_y,
|  | MLV_Mouse_button * | mouse_button,
|  | MLV_Button_state * | state,
|  | int | seconds |
| ) |  |  |

Cette fonction suspends l'éxecution du programme jusqu'à ce qu'un évènement apparaît dans la file d'attente ou jusqu'à ce qu'un certain nombre de secondes se soient écoulées. Si le temps s'est complètement écoulé, la fonction renvoie MLV_NONE. Si un nouvel évènement apparaît et que les paramètres passés en arguments sont en rapport avec l'évènement récupéré, alors la fonction remplit les paramètres et renvoie un entier codant le type de l'évènement qui a été récupéré. Si un nouvel évènement apparaît et qu'il n'est pas en rapport avec les paramètres de la fonction, alors il se rendort dans l'attente d'un nouvel évènement ou de la fin du temps.

Pour plus d'informations sur les différents types d'évènements et leurs liens avec les paramètres de la fonction, veuillez consulter la documentation de la fonction MLV_get_event().

L'utilisateur n'est pas obligé d'utiliser un champs s'il n'en a pas l'utilité. Dans ce cas, il peut mettre la valeur NULL. Le champs est alors ignoré.

Bogue:
  Voir les bugs de la fonction MLV_get_event().

Paramètres:

  | key_sym | Code de la touche qui a été appuyée ou relachée. La valeur de ce champs est définie par l'énumération : MLV_Keyboard_button.
  | key_mod | Mode dans lequel se trouve le clavier lorsqu'une touche est appuyée ou relachée. La valeur de ce champs est définie par l'énumération : MLV_Keyboard_modifier.
  | unicode | Caractère codé en unicode de la lettre obtenue en combinant le code et le mode précédent
  | texte | Texte récupéré par la boîte de saisie. L'allocation est affecté par la la fonction elle même. La désallocation est à la charge de l'utilisateur.
  | input_box | La boîte de saisie qui a récupérée le texte
  | mouse_x | Coordonnée en X de la position de la souris
  | mouse_y | Coordonnée en Y de la position de la souris
  | mouse_button | Bouton de la souris qui a été appuyé ou relaché. Ce champs est défini par l'énumération MLV_Mouse_button.
  | state | Etat de la touche concernée par l'évènement. La valeur de ce champs est défini par l'énumération: MLV_Button_state.
  | seconds | Nombre de secondes à attendre avant de terminer l'execution de la fonction en renvoyant MLV_NONE.

Renvoie:
  La fonction renvoie un entier codant le type de l'évènement qui a été récupéré ou MLV_NONE si le temps s'est écoulé.

MLV_Event MLV_wait_keyboard_or_mouse | ( | MLV_Keyboard_button * | sym,
|  | MLV_Keyboard_modifier * | mod,
|  | int * | unicode,
|  | int * | mouse_x,
|  | int * | mouse_y |
| ) |  |  |

Suspend l'exécution jusqu'à ce que l'utilisateur appuie sur une touche du clavier ou sur le bouton gauche de la souris.

Cette fonction renvoie un entier codant le type de l'évènement qui a été récupéré ( clavier ou souris )

Lorsque l'utilisateur appuie sur une touche, la fonction retourne trois valeurs ( sym, mod et unicode ) correspondant respectivement au code de la touche, au mode dans lequel se trouve le clavier (majuscule etc ...) et au caractère unicode correspondnant obtenu en combinant le mode du clavier et le code de la touche appuyée.

Lorsque l'utilisateur appuie sur le bouton gauche de la souris, la fonction remplit les parametres correspondant aux coordonnées en X et Y de la position de la souris sur l'écran.

Bogue:
  Voir les bugs de la fonction MLV_get_event().

Paramètres:

  | sym | Code de la touche qui a été appuyée ou relachée. La valeur de ce champs est définie par l'énumération : MLV_Keyboard_button.
  | mod | Mode dans lequel se trouve le clavier lorsqu'une touche est appuyée ou relachée. La valeur de ce champs est définie par l'énumération : MLV_Keyboard_modifier.
  | unicode | Caractère codé en unicode de la lettre obtenue en combinant le code et le mode précédent
  | mouse_x | Coordonnée en X de la position de la souris
  | mouse_y | Coordonnée en Y de la position de la souris

Renvoie:
  un entier codant le type de l'évènement qui a été récupéré ( MLV_KEY ou MLV_MOUSE_BUTTON )

Exemples:
  advanced/08_zone_click.c, et beginner/08_mouse_keyboard_timer.c.

MLV_Event MLV_wait_keyboard_or_mouse_or_seconds | ( | MLV_Keyboard_button * | sym,
|  | MLV_Keyboard_modifier * | mod,
|  | int * | unicode,
|  | int * | mouse_x,
|  | int * | mouse_y,
|  | int | seconds |
| ) |  |  |

Suspend l'exécution jusqu'à ce que l'utilisateur appuie sur une touche du clavier, sur le bouton gauche de la souris ou qu'un certain nombre de secondes passées en paramètres se soient écoulées.

Cette fonction renvoie un entier codant le type de l'évènement qui a été récupéré ( clavier, souris ou aucun des deux ).

Voir les fonctions MLV_wait_keyboard_seconds() et MLV_wait_mouse_seconds() pour plus d'informations.

Bogue:
  Voir les bugs de la fonction MLV_get_event().

Paramètres:

  | sym | Code de la touche qui a été appuyée ou relachée. La valeur de ce champs est définie par l'énumération : MLV_Keyboard_button.
  | mod | Mode dans lequel se trouve le clavier lorsqu'une touche est appuyée ou relachée. La valeur de ce champs est définie par l'énumération : MLV_Keyboard_modifier.
  | unicode | Caractère codé en unicode de la lettre obtenue en combinant le code et le mode précédent
  | mouse_x | Coordonnée en X de la position de la souris
  | mouse_y | Coordonnée en Y de la position de la souris
  | seconds | Le nombre de seconde à attendre avant d'arrêter la fonction

Renvoie:
  un entier codant le type de l'évènement qui a été récupéré ( MLV_KEY ou MLV_MOUSE_BUTTON ), ou MLV_NONE si le temps s'est écoulé.

Exemples:
  beginner/08_mouse_keyboard_timer.c.