Contrôles ActiveX MFC : Ajout de propriétés personnalisées
Les propriétés personnalisées sont différentes des propriétés de stockage dans la mesure où les propriétés personnalisées ne sont pas déjà implémentée par la classe COleControl. Une propriété personnalisée est utilisée pour exposer un certain état ou apparence d'un contrôle ActiveX à un programmeur grâce à son contrôle.
Cet article explique comment ajouter une propriété personnalisée au contrôle ActiveX à l'aide de l'Assistant Ajout de Propriétés et explique les modifications du code résultantes. Les rubriques traitées ici sont les suivantes :
Utilisation de l'Assistant d'Ajout de Propriétés pour ajouter une propriété personnalisée
L'Assistant Ajout de Propriétés change pour les propriétés personnalisées
Les propriétés personnalisées se manifestent sous quatre types d'implémentation : variable membre, variable membre avec notification, méthodes Get/SET, et paramétré.
Implémentation d'attribut
Cette implémentation représente l'état de la propriété comme un attribut dans la classe de contrôle. Utilisez l'implémentation de variable membre lorsqu'il n'est pas important de savoir quand la valeur de la propriété change. De ces trois types, cette implémentation crée le moins de code pour la prise en charge de la propriété. La macro d'entrée du tableau associatif (map) de dispatch pour l'implémentation d'attribut est DISP_PROPERTY.
Attribut avec implémentation de notifications
Cette implémentation se compose d'un attribut et d'une fonction de notification créée par l'Assistant d'Ajout de Propriétés. La fonction de notification est appelée automatiquement par le .NET framework lorsque la valeur de la propriété change. Utilisez l'attribut avec l'implémentation de notification lorsque vous avez besoin d'être informé que la valeur d'une propriété a été changée. Cette implémentation nécessite plus de temps car elle nécessite un appel de fonction. La macro d'entrée du tableau associatif (map) de dispatch pour cette implémentation est DISP_PROPERTY_NOTIFY.
Implémentation des méthodes Get/SET
Cette implémentation se compose d'une paire de méthodes de la classe de contrôle. L'implémentation des méthodes Get/Set appelle automatiquement la fonction membre Get lorsqu'un utilisateur demande la valeur actuelle de la propriété et la fonction membre Set lorsqu'un utilisateur demande à ce que la propriété soit modifiée. Utilisez cette implémentation lorsque vous devez calculer la valeur d'une propriété au moment de l'exécution, valider une valeur donnée par l'utilisateur avant de modifier la propriété réelle, ou implémenter un type de propriété en lecture - ou écriture - seule. La macro d'entrée du tableau associatif (map) de dispatch pour cette implémentation est DISP_PROPERTY_EX. La section suivante, Utilisation de l'Assistant Ajout de Propriétés pour ajouter une propriété personnalisée, utilise la propriété personnalisée CircleOffset pour illustrer cette implémentation.
Implémentation paramétrée
L'implémentation paramétrée est prise en charge par l'Assistant Ajout de Propriétés Une propriété paramétrée (parfois appelée tableau de propriétés) peut être utilisée pour accéder à un ensemble de valeurs via une seule propriété que vous contrôlez. La macro d'entrée du tableau associatif (map) de dispatch pour cette implémentation est DISP_PROPERTY_PARAM. Pour plus d'informations concernant l'implémentation de ce type, consultez Implémentation d'une propriété paramétrable dans l'article Contrôles ActiveX: Rubriques avancées.
Utilisation de l'Assistant Ajout de Propriétés pour ajouter une propriété personnalisée
La procédure suivante montre l'ajout d'une propriété personnalisée, CircleOffset, qui utilise l'implémentation des méthodes Get/Set. La propriété personnalisée CircleOffset permet à l'utilisateur de décaler le cercle à partir du centre du rectangle englobant. La procédure pour ajouter des propriétés personnalisées avec une implémentation autre que les méthodes Get/Set est très similaire.
Cette procédure peut également être utilisée pour ajouter d'autres propriétés personnalisées que vous souhaitez. Remplacez le nom de la propriété et les paramètres de CircleOffset par votre nom de propriété personnalisé.
Pour ajouter la propriété personnalisée de CircleOffset à l'aide de l'Assistant d'Ajout de Propriétés
Chargez votre projet de contrôle.
Sous Class View, développez l'arborescence de votre librairie.
Cliquez avec le bouton droit sur le nœud de votre interface (le deuxième nœud de l'arborescence de la librairie) pour ouvrir le menu contextuel.
Dans le menu contextuel, cliquez sur Ajouter puis sur Ajouter une propriété.
Cela ouvre l' Assistant d'Ajout de Propriétés.
Dans la zone Nom de la Propriété, tapez CircleOffset.
Dans Type d'implémentation, cliquez sur Méthodes Get/Set.
Dans la zone Type de propriété, sélectionnez courte.
Tapez les noms que vous souhaitez pour les méthodes Get et Set, ou acceptez les noms par défaut.
Cliquez sur Terminer.
Modifications dans l'Assistant Ajout de Propriétés pour les propriétés personnalisées
Lorsque vous ajoutez la propriété personnalisée CircleOffset, l'Assistant Ajout de Propriétés apporte des modifications à l'en-tête (. H) et aux fichiers (.CPP) d'implémentation de la classe de contrôle.
Les lignes suivantes sont ajoutées au fichier .H pour déclarer deux fonctions appelées GetCircleOffset et SetCircleOffset:
SHORT GetCircleOffset(void);
void SetCircleOffset(SHORT newVal);
La ligne suivante est ajoutée à votre fichier .IDL :
[id(2), helpstring("property CircleOffset")] SHORT CircleOffset;
[id(3), helpstring("property MyProperty")] SHORT MyProperty;
Cette ligne affecte un ID spécifique à la propriété CircleOffset, tiré de la position de la méthode dans la liste des méthodes et propriétés de l'Assistant d'Ajout de Propriétés.
En outre, la ligne suivante est ajoutée à la table de dispatch (dans le fichier .cpp de la classe de contrôle) pour mapper la propriété CircleOffset aux deux fonctions du gestionnaire :
DISP_PROPERTY_EX_ID(CMyAxUICtrl, "CircleOffset", dispidCircleOffset, GetCircleOffset, SetCircleOffset, VT_I2)
Enfin, les implémentations des fonctions GetCircleOffset et SetCircleOffset sont ajoutées à la fin du fichier .cpp. Dans la plupart des cas, vous modifierez la fonction Get pour retourner la valeur de la propriété. La fonction Set contiendra généralement du code qui doit être exécuté soit avant soit après que la propriété ne change.
void CMyAxUICtrl::SetCircleOffset(SHORT /*newVal*/)
{
AFX_MANAGE_STATE(AfxGetStaticModuleState());
// TODO: Add your property handler code here
SetModifiedFlag();
}
Notez que l'Assistant d'Ajout de Propriété ajoute automatiquement un appel à SetModifiedFlag, au corps de la fonction Set. L'appel de cette fonction marque le contrôle comme modifié. Si un contrôle a été modifié, le nouvel état est sauvegardé lorsque le conteneur est enregistré. Cette fonction doit être appelée chaque fois qu'une propriété, stockée comme une partie de l'état de contrôle permanent, change de valeur.