Tutoriel mobile : Utilisation d'un composant carnet d'adresses (iOS et Android)
Remonter à Tutoriels mobiles : Développement d'applications mobiles (iOS et Android)
Avant de commencer ce tutoriel, il est recommandé de lire et suivre les tutoriels suivants :
- Tutoriel mobile : Utilisation d'un composant Vue multiple pour afficher d'autres vues d'informations (iOS et Android)
- Tutoriel mobile : Utilisation des composants Zone de liste pour afficher une vue table (iOS et Android)
FireMonkey fournit le composant TAddressBook afin de travailler avec le Carnet d'adresses sur des périphériques iOS et Android.
Ce tutoriel explique comment créer une application FireMonkey simple qui utilise le composant TAddressBook.
iOS | Android |
---|---|
Sommaire
- 1 Fonctionnalités élémentaires du composant TAddressBook
- 2 Création d'une application exemple
- 3 Exécution de l'application exemple
- 4 Voir aussi
Fonctionnalités élémentaires du composant TAddressBook
Sur les plates-formes mobiles (Android et iOS), FireMonkey prend en charge le composant TAddressBook qui permet à vos applications d'accéder au Carnet d'adresses du périphérique. Les fonctionnalités élémentaires de ce composant sont les suivantes :
- Envoi d'une requête pour accéder au Carnet d'adresses d'un périphérique et obtention du statut de l'accès.
- Accès à toutes les sources définies dans le Carnet d'adresses.
- Extraction de tout ou partie des contacts depuis la source spécifiée.
- Extraction de tous les contacts depuis les groupes spécifiés.
- Modification ou suppression de contacts et de groupes existants.
- Création de nouveaux contacts.
- Création de nouveaux groupes.
Création d'une application exemple
Cette section vous aide à développer une application exemple (pour plates-formes cible Android et iOS) qui illustre l'utilisation du composant TAddressBook. Cette application fait la démonstration des techniques suivantes :
- Demande de permission d'accès au Carnet d'adresses.
- Récupération de tous les contacts depuis la source par défaut dans le Carnet d'adresses du périphérique.
- Ajout d'un nouveau contact au Carnet d'adresses.
- Retrait d'un contact sélectionné du Carnet d'adresses.
Conception de l'interface utilisateur
- Créez une application multi-périphérique vide en sélectionnant :
- Pour Delphi, Fichier > Nouveau > Application multi-périphérique - Delphi > Application vide.
- Pour C++ : Fichier > Nouveau > Application multi-périphérique - C++Builder > Application vide
- Dans le Gestionnaire de projets, définissez la plate-forme cible sur Android ou iOS.
- Dans la palette d'outils, sélectionnez les composants TToolBar, TAddressBook et TListBox et déposez-les sur le Concepteur de fiches.
- Dans l'inspecteur d'objets, définissez la propriété Align du TListBox sur
Client
. - Sur le Concepteur de fiches, faites un clic droit sur TListBox, puis sur le menu de raccourcis et sélectionnez Ajouter un élément > TSearchBox.
- Dans la palette d'outils, sélectionnez le composant TMultiView et déposez-le sur le Concepteur de fiches.
Conception de la barre d'outils et du volet maître de l'application
Placez tous les contrôles sur la barre d'outils et le volet maître :
- La barre d'outils contient trois turboboutons :
- Le volet maître fournit une fiche pour spécifier un nouveau contact à ajouter dans le Carnet d'adresses.
Pour concevoir la barre d'outils de l'application :
- Sur la barre d'outils supérieure, déposez trois composants TSpeedButton.
- Dans le Concepteur de fiches, procédez comme suit :
- Sélectionnez SpeedButton1, et définissez les propriétés Name et StyleLookup sur
btnRemove
ettrashtoolbuttonordered
respectivement. - Sélectionnez SpeedButton2 et définissez les propriétés Name et StyleLookup sur
btnRefresh
etrefreshtoolbuttonordered
respectivement. - Sélectionnez SpeedButton3 et définissez les propriétés Name et StyleLookup sur
btnAdd
etaddtoolbuttonordered
respectivement.
- Sélectionnez SpeedButton1, et définissez les propriétés Name et StyleLookup sur
Après avoir suivi les étapes ci-dessus, votre Concepteur de fiches sera similaire à l'écran suivant :
Pour concevoir le volet maître :
- Dans la vue Structure, sélectionnez MultiView1, puis, dans l'inspecteur d'objets, spécifiez les propriétés suivantes :
- Définissez la propriété MasterButton sur
btnAdd
. - Définissez la propriété Mode sur
Drawer
. - Afin de rendre le MultiView1 visible, définissez la propriété Visible sur
True
.
- Définissez la propriété MasterButton sur
- Dans la palette d'outils, sélectionnez trois composants TLabel, trois composants TEdit et deux composants TButton, et déposez-les sur Multiview1.
- Dans l'inspecteur d'objets, spécifiez les propriétés suivantes des éléments contrôles que vous avez placés sur MultiView1 :
- Pour Label1, Label2 et Label3 : définissez les propriétés Text sur
First Name
,Last Name
etWork Mail
respectivement. - Pour Edit1, Edit2 et Edit3 :
- définissez la propriété Name sur
edtFirstName
,edtLastName
etedtWorkMail
, respectivement. - définissez la propriété KillFocusByReturn sur
true
- définissez la propriété ReturnKeyType sur
Go
.
- définissez la propriété Name sur
- Pour Button1 et Button2 :
- définissez la propriété Text sur
Add
etCancel
- définissez la propriété Name sur
btnOK
etbtnCancel
, respectivement.
- définissez la propriété Text sur
- Pour Label1, Label2 et Label3 : définissez les propriétés Text sur
Il est recommandé d'organiser les contrôles du volet maître de la manière suivante :
Extraction de la liste de contacts
Cette section explique comment récupérer la liste des contacts depuis la source par défaut dans le Carnet d'adresses du périphérique.
Dans votre application, définissez les méthodes privées suivantes :
FillContactsList
: obtient la liste des contacts de la source par défaut dans le Carnet d'adresses du périphérique ;AddListBoxItem
: ajoute un nouvel élément à ListBox.
Faites les modifications suivantes à la section private du code de votre application :
private
{ Private declarations }
procedure FillContactList;
procedure AddListBoxItem(Contact: TAddressBookContact);
private: // User declarations
void __fastcall FillContactsList();
void __fastcall AddListBoxItem(TAddressBookContact *Contact);
Implémentez les méthodes FillContactslist
et AddListBoxItem
comme suit :
// Fill the contact list
procedure TForm1.FillContactList;
var
I: Integer;
Contacts: TAddressBookContacts;
begin
Contacts := TAddressBookContacts.Create;
try
AddressBook1.AllContacts(AddressBook1.DefaultSource, Contacts);
ListBox1.BeginUpdate;
try
ListBox1.Clear;
for I := 0 to Contacts.Count - 1 do
AddListBoxItem(Contacts.Items[I]);
finally
ListBox1.EndUpdate;
end;
finally
Contacts.Free;
end;
end;
// --------------------------------------------------------------------
// Add a new contact to List box
procedure TForm1.AddListBoxItem(Contact: TAddressBookContact);
var
ListBoxItem: TListBoxItem;
begin
try
ListBoxItem := TListBoxItem.Create(nil);
ListBoxItem.Text := Contact.DisplayName;
ListBoxItem.Tag := Contact.ID;
ListBox1.AddObject(ListBoxItem);
finally
ListBoxItem.Free;
end;
end;
// Fill the List box with existed contact display names.
void __fastcall TForm1::FillContactsList() {
int i;
TAddressBookContacts *Contacts = new TAddressBookContacts();
__try {
AddressBook1->AllContacts(AddressBook1->DefaultSource(), Contacts);
__try {
ListBox1->BeginUpdate();
ListBox1->Clear();
for (i = 0; i < Contacts->Count; i++)
AddListBoxItem(Contacts->Items[i]);
}
__finally {
ListBox1->EndUpdate();
}
}
__finally {
Contacts->Free();
}
}
// ---------------------------------------------------------------------------
// Add a new contact to List box
void __fastcall TForm1::AddListBoxItem(TAddressBookContact *Contact) {
TListBoxItem *ListBoxItem = new TListBoxItem(ListBox1);
__try {
ListBoxItem->Text = Contact->DisplayName;
ListBoxItem->Tag = Contact->ID;
ListBox1->AddObject(ListBoxItem);
}
__finally {
ListBoxItem->Free();
}
}
Implémentation de la fonctionnalité des éléments contrôles
Pour terminer le développement de l'application, vous devez implémenter les gestionnaires d'événement pour tous les éléments contrôles que vous avez déposés sur la fiche de l'application.
Pour implémenter les gestionnaires d'événement OnClick pour les turboboutons :
- Sur le Concepteur de fiches, faites un double clic sur un turbobouton (btnRefresh ou btnRemove).
- Dans l'éditeur de code, spécifiez les gestionnaires d'événement suivants pour chaque bouton :
//-------------------For Remove button -----------------------------------------
procedure TForm1.btnRemoveClick(Sender: TObject);
var
ContactIndex, ContactID: Integer;
Contact: TAddressBookContact;
begin
ContactIndex := ListBox1.ItemIndex;
if (ContactIndex > -1) Then
begin
ContactID := ListBox1.ListItems[ContactIndex].Tag;
Contact := AddressBook1.ContactByID(ContactID);
if Contact <> nil then
try
AddressBook1.RemoveContact(Contact);
ListBox1.BeginUpdate;
ListBox1.Items.Delete(ContactIndex);
finally
ListBox1.EndUpdate;
Contact.Free;
end;
end;
end;
// -------------------For Refresh button---------------------------------------
procedure TForm1.btnRefreshClick(Sender: TObject);
begin
FillContactsList;
end;
//-------------------For Remove button -----------------------------------------
// Remove the contact currently selected from the List box
void __fastcall TForm1::btnRemoveClick(TObject *Sender) {
int ContactIndex = ListBox1->ItemIndex;
if (ContactIndex > -1) {
int ContactID = ListBox1->ListItems[ContactIndex]->Tag;
TAddressBookContact *Contact = AddressBook1->ContactByID(ContactID);
if (Contact != NULL) {
__try {
AddressBook1->RemoveContact(Contact);
ListBox1->BeginUpdate();
ListBox1->Items->Delete(ContactIndex);
}
__finally {
ListBox1->EndUpdate();
Contact->Free();
}
}
}
}
// --------------------------For Refresh button-------------------------------------
void __fastcall TForm1::btnRefreshClick(TObject *Sender) {
FillContactsList();
}
Pour implémenter le gestionnaire d'événement OnClick pour les boutons du volet maître :
- Dans la vue Structure, sélectionnez MultiView1.
- Dans l'inspecteur d'objets, définissez la propriété Visible sur
True
.
Cela rend visible le volet maître. - Sur le volet maître, faites un double clic sur le bouton Ajouter, puis implémentez le gestionnaire d'événement suivant :
- Pour Delphi :
// -------------------------------------------------------------------- // Add a newly created contact to Address Book procedure TForm1.btnOKClick(Sender: TObject); var Contact: TAddressBookContact; eMails: TContactEmails; Addresses: TContactAddresses; begin Contact := AddressBook1.CreateContact(AddressBook1.DefaultSource); try Contact.FirstName := edtFirstName.Text; Contact.LastName := edtLastName.Text; // Add the work mail eMails := TContactEmails.Create; try eMails.AddEmail(TContactEmail.TLabelKind.Work, edtWorkMail.Text); Contact.eMails := eMails; finally eMails.Free; end; AddressBook1.SaveContact(Contact); try ListBox1.BeginUpdate; AddListBoxItem(Contact); finally ListBox1.EndUpdate; end; finally Contact.Free; end; MultiView1.HideMaster; end;
- Pour C++ :
// Add a newly created contact to Address Book void __fastcall TForm1::btnOKClick(TObject *Sender) { TContactEmails *eMails; TAddressBookContact *Contact = AddressBook1->CreateContact(AddressBook1->DefaultSource()); __try { Contact->FirstName = edtFirstName->Text; Contact->LastName = edtLastName->Text; // Add the work mail eMails = new TContactEmails(); __try { eMails->AddEmail(TContactEmail::TLabelKind::Work, edtWorkMail->Text); Contact->EMails = eMails; } __finally { eMails->Free(); } AddressBook1->SaveContact(Contact); __try { ListBox1->BeginUpdate(); AddListBoxItem(Contact); } __finally { ListBox1->EndUpdate(); } } __finally { Contact->Free(); } MultiView1->HideMaster(); }
- Sur le volet maître, faites un double clic sur le bouton Annuler, puis implémentez le gestionnaire d'événement suivant :
- Pour Delphi :
// Clear and close the Add New Contact form procedure TForm1.btnCancelClick(Sender: TObject); begin edtFirstName.Text := ''; edtLastName.Text := ''; edtWorkMail.Text := ''; MultiView1.HideMaster; end;
- Pour C++ :
// Clear and close the Add New Contact form void __fastcall TForm1::btnCancelClick(TObject *Sender) { edtFirstName->Text = ""; edtLastName->Text = ""; edtWorkMail->Text = ""; MultiView1->HideMaster(); }
Garder le Carnet d'adresses en synchronisation
Il est possible que certains outils tiers apportent des changements au Carnet d'adresses d'un périphérique durant l'exécution de votre application. Dans cette éventualité, il est important de conserver la synchronisation des informations entre le Carnet d'adresses du périphérique et l'instance du Carnet d'adresses avec laquelle votre application travaille directement. Dans ce but, FireMonkey fournit la méthode TAddressBook.RevertCurrentChangesAndUpdate.
Pour conserver le Carnet d'adresses en synchronisation
- Dans l'inspecteur d'objets, sélectionnez AddressBook1, puis ouvrez l'onglet Evénements.
- Faites un double clic à côté de OnExternalChange, et implémentez ensuite le gestionnaire d'événement suivant :
- Pour Delphi :
procedure TForm1.AddressBook1ExternalChange(ASender: TObject); begin AddressBook1.RevertCurrentChangesAndUpdate; FillContactsList; end;
- Pour C++ :
void __fastcall TForm1::AddressBook1ExternalChange(TObject *ASender) { AddressBook1->RevertCurrentChangesAndUpdate(); FillContactsList(); }
Configuration de l'accès au Carnet d'adresses
Avant d'utiliser TAddressBook, votre application doit demander la permission d'accéder au Carnet d'adresses sur un périphérique mobile cible.
Cette section donne les étapes de la configuration de vos applications Android et iOS pour accéder au Carnet d'adresses sur les périphériques mobiles cible.
Pour demander la permission d'accéder au Carnet d'adresses :
- Dans l'inspecteur d'objets, sélectionnez Form1, puis ouvrez l'onglet Evénements.
- Faites un double clic à côté de onShow, puis implémentez le gestionnaire d'événement suivant :
- Pour Delphi :
procedure TForm1.FormShow(Sender: TObject); begin // Display this information box while loading the contacts if AddressBook1.Supported then begin TDialogService.ShowMessage('Loading contacts...'); AddressBook1.RequestPermission; end else ShowMessage('This platform does not support the Address Book service'); end;
- Pour C++ :
void __fastcall TForm1::FormShow(TObject *Sender) { if (AddressBook1->Supported()) { // Display this information box while loading the contacts TDialogService::ShowMessage("Loading contacts..."); AddressBook1->RequestPermission(); } else { TDialogService::ShowMessage ("This platform does not support the Address Book service."); } }
Remarque : Pour utiliser la méthode TDialogService.ShowMessage, assurez-vous que votre code inclut les instructions suivantes :
Delphi :uses FMX.DialogService;
C++ :
#include <FMX.DialogService.hpp>
- Dans l'inspecteur d'objets, sélectionnez AddressBook1, puis ouvrez l'onglet Evénements.
- Faites un double clic à côté de OnPermissionRequest, puis implémentez le gestionnaire d'événement suivant :
- Pour Delphi :
procedure TForm1.AddressBook1PermissionRequest(ASender: TObject; const AMessage: string; const AAccessGranted: Boolean); begin if AAccessGranted then Begin FillContactlist; End else ShowMessage('You cannot access Address Book. Reason: ' + AMessage); end;
- Pour C++ :
void __fastcall TForm1::AddressBook1PermissionRequest(TObject *ASender, const UnicodeString AMessage, const bool AAccessGranted) { if (AAccessGranted) { FillContactsList(); } else { ShowMessage("You cannot access Address Book. Reason: " + AMessage); } }
Configuration d'applications Android pour accéder au Carnet d'adresses
Avant d'exécuter des applications Android utilisant le composant TAddressBook, vous devez configurer certaines permissions d'utilisation pour votre projet.
Pour configurer les permissions d'utilisation :
- Dans l'EDI de RAD Studio, ouvrez Projet > Options > Permissions d'utilisation.
-
Activez les permissions suivantes :
- Obtenir les comptes
- Lire les contacts
- Ecrire les contacts
Exécution de l'application exemple
Pour exécuter cette application, procédez comme suit :
- Dans le Gestionnaire de projets, sélectionnez la plate-forme cible (plates-formes prises en charge : Android ou iOS).
Important : Avant d'exécuter cette application sur des périphériques Android, assurez-vous d'avoir suivi les étapes de Configuration des applications Android pour accéder au carnet d'adresses.
- Appuyez sur
Maj+Ctrl+F9
pour exécuter l'application sans débogage.
Pour tester votre application, vous pouvez utiliser les scénarios suivants :
Pour ajouter un nouveau contact au carnet d'adresses :
- Sur la barre d'outils de l'application, touchez
.
Cela ouvre le volet maître. -
Dans le volet maître, entrez les informations appropriées dans les zones de texte First name, Last name et Work email. Lorsque vous avez fini, tapez sur Ajouter afin d'ajouter le contact nouvellement créé au Carnet d'adresses.
Pour supprimer un contact
- Dans la liste des contacts, tapez sur le contact pour le supprimer.
- Sur la barre d'outils de l'application, tapez
Attention ! Ceci retire le contact du Carnet d'adresses sans afficher de message de confirmation !
Voir aussi
- TAddressBook
- Tutoriel mobile : Utilisation d'un composant Vue multiple pour afficher d'autres vues d'informations (iOS et Android)
- Tutoriel mobile : Utilisation des composants Zone de liste pour afficher une vue table (iOS et Android)
Exemples de code
- Exemple Birthday Reminder