BPropertyInfo

Biblothèque : libbe.so

Résumé

BPropertyInfo est une classe simple qui gère les scripts. Un programme décrit son interface de scripts dans un objet BPropertyInfo via un tableau de structures property_info, dont chaque entrée décrit un élément du script de commandes. Définition de la structure :

   struct 
property_info
 {
      char *name;
      uint32 commands[10];
      uint32 specifiers[10];
      char *usage;
      uint32 extra_data;
   };

name fournit le nom de la propriété décrite dans la structure.
commands est un tableau, se terminant par zéro, de commandes interprétables par la propriété, c.a.d. par B_GET_PROPERTY. Le premier élément, s'il est égal à 0, agit comme un joker correspondant à toutes les commandes possibles.
specifiers est un tableau, se terminant par zéro, de "spécifieurs" interprétables par la propriété, c.a.d. par B_DIRECT_SPECIFIER. Le premier élément, s'il est égal à 0, agit comme un joker correspondant à toutes les "spécifieurs" possibles.
usage fournit un texte, destiné à un lecteur humain, décrivant la propriété, ses commandes autorisées et ses "spécifieurs".
extra_data est une zone libre à usage général ; le système d'exploitation ignore son contenu.

Une BPropertyInfo est instanciée en passant à son constructeur un tableau de property_info, terminé par zéro. Une initialisation typique de BPropertyInfo ressemble à ceci :

   static property_info prop_list[] = {
      { "duck", {B_GET_PROPERTY, B_SET_PROPERTY, 0}, 
      {B_DIRECT_SPECIFIER, B_INDEX_SPECIFIER, 0}, "get or set duck"},
      { "head", {B_GET_PROPERTY, 0}, {B_DIRECT_SPECIFIER, 0}, "get head"},
      { "head", {B_SET_PROPERTY, 0}, {B_DIRECT_SPECIFIER, 0}, "set head"},
      { "feet", {0}, {0}, "can do anything with his orange feet"},
      0 // terminate list
   };
   
   BPropertyInfo prop_info(prop_list);

Comme BPropertyInfo stocke uniquement un pointeur vers le tableau, il est essentiel que la durée de vie de ce dernier soit au moins aussi longue que l'objet BPropertyInfo.

Remarquez que BPropertyInfo n'impose aucune structure particulière de tableau ; en particulier, toutes les commandes ou les "spécifieurs" d'une propriété donnée n'ont pas besoin d'être représentés un à un par une entrée du tableau. Vous êtes libres d'organiser votre scipts de commandes de la manière la plus pratique pour votre objet particulier.

BPropertyInfo hérite de BFlattenable, et peut donc être utilisée pour stocker la description d'un script compatible de commandes d'un objet. Ceci est particulièrement utile quand on force (overriding) GetSupportedSuites():

   status_t MyHandler::GetSupportedSuites(BMessage *msg)
   {
      msg->AddString("suites", "suite/vnd.Me-my_handler");
      BPropertyInfo prop_info(prop_list);
      msg->AddFlat("messages", &prop_info);
      return baseClass::GetSupportedSuites(msg);
   }

Naturellement, BPropertyInfo est également utile pour interprêter les résultats obtenus en interrogeant un objet au sujet de ses scripts de commandes.

BPropertyInfo définit la méthode FindMatch() conçue pour simplifier la mise en oeuvre de ResolveSpecifier(). Elle retourne l'index de la propriété info correspondant à la description donnée, ou -1 si aucune ne correspond. Dans le plus simple des cas, ceci réduit ResolveSpecifier() à :

   BHandler *MyHandler::ResolveSpecifier(BMessage *msg, int32 index,
      BMessage *spec, int32 form, const char *prop)
   {
      BPropertyInfo prop_info(prop_list);
      if (prop_info.FindMatch(msg, index, spec, form, prop) >= 0)
      return this;
      return baseClass::ResolveSpecifier(msg, index, spec, form, prop);
   }

Bien sūr, pour des objets plus complexes, ResolveSpecifier() peut avoir besoin de positionner le handler de la cible sur un objet autre que lui-même, un processus plus long peut alors être nécessaire. Dans ce cas, l'objet peut utiliser l'index retourné par FindMatch() pour l'aider à déterminer le destinataire du message de scripts.

Constructeur et Destructeur

BPropertyInfo()

BPropertyInfo(property_info *p = NULL, bool free_on_delete = false)

Initialise l'objet avec le tableau de property_info p spécifié, terminé par zéro. Passer true dans free_on_delete ordonne à l'objet de libérer la mémoire associée à property_info quand il est détruit. BPropertyInfo ne recopie pas le tableau, il est donc important que le tableau ne soit pas effacé ou détruit d'une manière ou d'une autre tant que BPropertyInfo est utilisée.

~BPropertyInfo()

~BPropertyInfo()

Si free_on_delete est positionné à true dans le constructeur, le destructeur libère toute la mémoire associée à property_info. Sinon, il ne fait rien.

Fonctions Membre

AllowsTypeCode()

Détail de mise en oeuvre. Voir BFlattenable::AllowsTypeCode().

FindMatch()

int32 FindMatch(BMessage *msg, int32 index, BMessage *spec, int32 form,
      const char *prop, void *data = NULL) const

Recherche dans le tableau de property_info un élément fournissant la demande de scripts spécifiée, une fois passé un nom de propriété dans prop, un "spécifieur" dans form, et une commande dans msg->what. Si index est différent de zéro, FindMatch() recherche uniquement les structures de property_info avec la commande joker (premier élément du tableau de commande égal à 0). Sinon, il recherche une correspondance parmi toutes les structures disponibles de property_info. Si une correspondance est trouvée, il remplit la mémoire à data avec le contenu du champ extra_data et retourne l'index correspondant du tableau. Si aucune correspondance n'est trouvée, il retourne B_ERROR.

Flatten

Détail de mise en oeuvre. Voir BFlattenable::Flatten().

FlattenedSize()

Détail de mise en oeuvre. Voir BFlattenable::FlattenedSize().

IsFixedSize()

Détail de mise en oeuvre. Voir BFlattenable::IsFixedSize().

TypeCode()

Détail de mise en oeuvre. Voir BFlattenable::TypeCode().

PrintToStream()

void PrintToStream(void) const

Imprime des informations au sujet de BPropertyInfo vers la sortie standard.

PropertyInfo()

const property_info *PropertyInfo(void) const

Retourne la liste de property_info associée à l'objet.

Unflatten()

Détail de mise en oeuvre. Voir BFlattenable::Unflatten().

Sommaire du Kit d'Application

Index du Kit d'Application

The Be Book,
...in lovely HTML...
for BeOS Release 5.