Pointui Home 2 - DataTable

Modifié le samedi, 07 février 2009 18:32 par Montecristoff — Catégorisé en: Pointui Home

Fournit l'accès à une table de données. Elle est utilisée pour accéder aux Rendez-vous (Appointments), Contacts, Tâches (Tasks), Messages et à d'autres données.

La classe DataTable est extrêmement importante. Elle fournit une structure générique pour beaucoup de tables de données qui proviennent de l'appareil comme les rendez-vous, les contacts, les tâches, les messages, les applications actives et même des documents XML. Plutôt que d'utiliser un moyen d'accès spécifique à chacun de ces types de données, nous avons décidé de créer une classe DataTable permettant d'en uniformiser l'accès. Il est important que vous deveniez familier avec l'usage d'objets de type DataTable car la plupart des choses dont vous avez besoin les utilisent.

Une DataTable contient de 0 à n lignes (rows). Chaque ligne peut représenter une entité (comme un rendez-vous ou un contact,), une ligne contenant les détails d'une seule entité. Étant donné que votre calendrier contient plusieurs rendez-vous, cela signifie que la DataTable contiendra beaucoup de lignes, une ligne par rendez-vous.

Chaque ligne contient une ou plusieurs colonnes (columns). Une colonne correspond à une information rattachée à l'entité représentée par la ligne. Par exemple, si une ligne correspond à un rendez-vous, elle contiendra alors les colonnes «Objet», « Début », « Fin », « Fréquence », etc. Mais si une ligne correspond à un message elle contiendra alors les colonnes « Sujet », « Destinataire », « Est lu », etc.

La plupart des types de données contenus dans des objets DataTable supportent uniquement une navigation séquentielle dans les lignes de la structure. Pour être plus précis, l'accès aléatoire à une ligne n'est pas supporté. Habituellement, une DataTable est initialisée et exploitée jusqu'à la ligne finale comme le montre l'exemple suivant :

DataTable rendezvous; 
//Alimentation de la table avec tous les rendez-vous 
Appointments.GetAppointments(rendezvous); 
 
//Boucle pour parcourir la table des rendez-vous 
while (rendezvous.MoveNext()) 
{ 
	//faire quelque chose avec ce rendez-vous 
	DateTime dt;
	appts.GetValue(“StartDate”, dt);
}

Certains types de données autorisent l'instruction MoveTo(index) pour un accès ciblé à une occurrence. Dans ce cas, la documentation le précise.

Une liste entière d'élément est généralement requise pour une DataTable et cette liste est alors restreinte en utilisant SetRestriction() à partir d'une requête si nécessaire. Il n'est pas plus performant de requêter toute la table et de la restreindre étant donné que la restriction effectue une tentative pour parcourir la DataTable en utilisant MoveNext() etc.

Le nombre de lignes d'une DataTable peut être limité en utilisant SetMaxItems().

Méthodes

bool MoveNext()
Lit la ligne suivante dans la table.
Remarque importante : Il est impératif d'utiliser au moins une fois cette méthode avant de pouvoir récupérer la première ligne avec la méthode GetValue() (voir exemple ci-dessous).

Valeur retournée Retourne true si la ligne suivante existe et a été lue avec succès. Si une valeur true est retournée, un GetValue() peut être alors utilisé pour récupérer les valeurs de la ligne. Si plus aucune ligne n'existe dans la table, la valeur false est retournée.

Compatibilité

Supporté pour toute table de données.

Exemple

DataTable rendezvous;

// Récupération de tous les rendez-vous
Appointments.GetAppointments(rendezvous);

//lecture de tous les rendez-vous
//remarquez que MoveNext est appeler avant d'accéder aux valeurs de la première ligne
while (rendezvous.MoveNext())
{
	//récupération de la date et l'heure de début du rendez-vous lu
	DateTime debut;
	appts.GetValue("StartDate", debut);
}

bool MoveTo(int index)
Accède à une ligne spécifique dans la table.

Valeur retournée

Retourne true si la ligne suivante existe et a été lue avec succès. Si une valeur true est retournée, un GetValue() peut être alors utilisé pour récupérer les valeurs de la ligne. Si plus aucune ligne n'existe dans la table, la valeur false est retournée.

Compatibilité

Uniquement supporté pour les tables de données retournées par :
- Path.Get.Files()

void GetValue(String columnName, Strign result)
void GetValue(String columnName, int result)
void GetValue(String columnName, DateTime result)
Délivre la valeur de la colonne spécifiée et copie sa valeur dans le paramètre résultat. Cela permet de récupérer les valeurs des colonnes de la ligne courante.

Paramètres

columnName nom de la colonne dont la valeur doit être retournée (sensible à la casse)
result valeur retournée qui est le contenu de la colonne. Le type de variable déclaré doit correspondre au type de valeur demandé.

Compatibilité

Supporté pour toute table de données.

Exemple

DataTable rendezvous; 
Appointments.GetAppointments(rendezvous); 
while (rendezvous .MoveNext()) 
{ 
	//récupération de la date et heure de début du rendez-vous
	DateTime rvDebut; 
	rendezvous.GetValue(“StartDate”, rvDebut); 
 
	//récupération de l'objet du rendez-vous
	String rvObjet; 
	rendezvous.GetValue(“Subject”, rvObjet); 
}

void SetColumns(String columns)
Définit les colonnes qui sont retournée dans la table. Seules les colonnes spécifiées peuvent être accédées par GetValue() pour les tables de données qui comportent des colonnes spéicifiques. Voir la compatibilité ci-dessous.

Paramètre

columns contient une liste de noms de colonnes séparés par des vrigules. Ces colonnes seront ajoutées dans la table lors de sa préparation.

Compatibilité

Uniquement supporté pour les tables de données retournées par :
- Messages.GetMessages()

Exemple

DataTable rendezvous; 
Appointments.GetAppointments(rendezvous); 
while (rendezvous .MoveNext()) 
{ 
	//récupération de la date et heure de début du rendez-vous
	DateTime rvDebut; 
	rendezvous.GetValue(“StartDate”, rvDebut); 
 
	//récupération de l'objet du rendez-vous
	String rvObjet; 
	rendezvous.GetValue(“Subject”, rvObjet); 
}

void SetSort(String columnName, String sortDirection)
Définit le nom de colonne à trier ainsi que le sens du tri.

Paramètres

columnName nom de la colonne utilisée comme critère de tri
sortDirection (optionnel) sens du tri qui peut prendre une des valeurs suivantes :
- "Ascending" tri en ascendant (valeur par défaut si non spécifié)
- "Descending" tri en descendant

Compatibilité

Uniquement supporté pour les tables de données retournées par :
- Appointments.GetAppointments()
- Contacts.GetContacts()
- Messages.GetMessages()
- Tasks.GetTasks()

void SetRestriction(String query)
Restreint la table afin qu'elle ne contienne que les lignes correspondant à la requête fournie en paramètre.

Paramètre

query requête à appliquer à la table pour limiter les lignes retournées.

Le format de la requête peut être différent selon le type de données contenu de la table.

Exemple

//récupération des rendez-vous 
DataTable rendezvous; 
Appointments.GetAppointments(rendezvous); 
 
//ne pas retourner plus de 4 éléments 
rendezvous.SetMaxItems(4); 
 
//Tri des de la table sur la date et heure de début 
rendezvous.SetSort("Start"); 
 
//élaboration d'une requête qui sera utilisé pour filtrer les rendez-vous
String filtre; 
filtre = "End >= <{Now} AND Start < <{End}"; 
 
//récupération de la date et heure courante 
DateTime aujourdhui; 
aujourdhui.Now(); 
 
//conversion de l'heure courante au format attendu par POOM 
String tmp; 
float f; 
 
f = aujourdhui.ToVariantTime(); 
tmp = f.ToString("%.5f"); 
filtre = filtre.Replace("{Now}", tmp); 
 
//récupération de l'heure de début du jour suivant 
aujourdhui.AddDays(1);
f = aujourdhui.ToVariantTime(); 
f.Trunc(); 
tmp = f.ToString("%.0f"); 
filtre = filtre.Replace("{End}", tmp); 
 
//application de la restriction (avec le filtre) 
rendezvous.SetRestriction(filtre); 
 
//faire quelque chose avec les rendez-vous obtenus 
while (rendezvous .MoveNext()) 
{ 
	//… 
}

void SetMaxitems(int maxItems)
Définit le nombre maximum d'éléments de la table à retourner même si elle en contient plus.

Paramètres

maxItems nombre maximum d'éléments à retourner

Compatibilité

Supporté pour toute table de données.

int GetCount()
Retourne le nombre de lignes contenues dans la table.

Compatibilité

Uniquement supporté pour les tables de données retournées par :
- Process.GetRunningApplications()