Tutoriel mobile : Utilisation d'un composant carnet d'adresses (iOS et Android)

De RAD Studio
Aller à : navigation, rechercher

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 :

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

AddressBook Apps.png
iPhone 5

AddressBook Android.png

Android (LG - E612)


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

  1. 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
  2. Dans le Gestionnaire de projets, définissez la plate-forme cible sur Android ou iOS.
  3. Dans la palette d'outils, sélectionnez les composants TToolBar, TAddressBook et TListBox et déposez-les sur le Concepteur de fiches.
  4. Dans l'inspecteur d'objets, définissez la propriété Align du TListBox sur Client.
  5. 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.
  6. 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 :
    • Addre Trash.png : supprime du Carnet d'adresses le contact sélectionné.
    • Addr Refresh.png: actualise la liste de contacts en cours.
    • Addr Add.png: ouvre le volet maître afin d'ajouter un nouveau contact au Carnet d'adresses.
  • 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 :

  1. Sur la barre d'outils supérieure, déposez trois composants TSpeedButton.
  2. Dans le Concepteur de fiches, procédez comme suit :
    • Sélectionnez SpeedButton1, et définissez les propriétés Name et StyleLookup sur btnRemove et trashtoolbuttonordered respectivement.
    • Sélectionnez SpeedButton2 et définissez les propriétés Name et StyleLookup sur btnRefresh et refreshtoolbuttonordered respectivement.
    • Sélectionnez SpeedButton3 et définissez les propriétés Name et StyleLookup sur btnAdd et addtoolbuttonordered respectivement.

Après avoir suivi les étapes ci-dessus, votre Concepteur de fiches sera similaire à l'écran suivant :AddressBook toolbar.png

Pour concevoir le volet maître :

  1. 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.
  2. Dans la palette d'outils, sélectionnez trois composants TLabel, trois composants TEdit et deux composants TButton, et déposez-les sur Multiview1.
  3. 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 et Work Mail respectivement.
    • Pour Edit1, Edit2 et Edit3 :
      • définissez la propriété Name sur edtFirstName, edtLastName et edtWorkMail, respectivement.
      • définissez la propriété KillFocusByReturn sur true
      • définissez la propriété ReturnKeyType sur Go.
    • Pour Button1 et Button2 :
      • définissez la propriété Text sur Add et Cancel
      • définissez la propriété Name sur btnOK et btnCancel, respectivement.

Il est recommandé d'organiser les contrôles du volet maître de la manière suivante :

AddressBook Drawer.png

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 :

Delphi :
private
    { Private declarations }
    procedure FillContactList;
    procedure AddListBoxItem(Contact: TAddressBookContact);
C++Builder :
private:	// User declarations
	void __fastcall FillContactsList();
        void __fastcall AddListBoxItem(TAddressBookContact *Contact);

Implémentez les méthodes FillContactslist et AddListBoxItem comme suit :

Delphi :
// 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;
C++Builder :
// 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 :

  1. Sur le Concepteur de fiches, faites un double clic sur un turbobouton (btnRefresh ou btnRemove).
  2. Dans l'éditeur de code, spécifiez les gestionnaires d'événement suivants pour chaque bouton :
Delphi :
//-------------------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;
C++Builder :
//-------------------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 :

  1. Dans la vue Structure, sélectionnez MultiView1.
  2. Dans l'inspecteur d'objets, définissez la propriété Visible sur True.
    Cela rend visible le volet maître.
  3. 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();	
    }
    
  4. 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

  1. Dans l'inspecteur d'objets, sélectionnez AddressBook1, puis ouvrez l'onglet Evénements.
  2. 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 :

  1. Dans l'inspecteur d'objets, sélectionnez Form1, puis ouvrez l'onglet Evénements.
  2. 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>
    
  3. Dans l'inspecteur d'objets, sélectionnez AddressBook1, puis ouvrez l'onglet Evénements.
  4. 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 :

  1. Dans l'EDI de RAD Studio, ouvrez Projet > Options > Permissions d'utilisation.
  2. 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 :

  1. 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.

  2. 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 :

  1. Sur la barre d'outils de l'application, touchez Addr Add.png.
    Cela ouvre le volet maître.
  2. 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.

    Add Contact iOS.png



Pour supprimer un contact

  1. Dans la liste des contacts, tapez sur le contact pour le supprimer.
  2. Sur la barre d'outils de l'application, tapez Addre Trash.png
    Attention ! Ceci retire le contact du Carnet d'adresses sans afficher de message de confirmation !

    Remove Contact iOS.png

Voir aussi

Exemples de code