Fonctions globales de contrôle composite
Ces fonctions prennent en charge la création de boîtes de dialogue et la création, l’hébergement et la gestion des licences des contrôles ActiveX.
Important
Les fonctions répertoriées dans le tableau suivant ne peuvent pas être utilisées dans les applications qui s’exécutent dans Windows Runtime.
| Fonction | Description |
|---|---|
| AtlAxDialogBox | Crée une boîte de dialogue modale à partir d'un modèle de boîte de dialogue fourni par l'utilisateur. La boîte de dialogue résultante peut contenir des contrôles ActiveX. |
| AtlAxCreateDialog | Crée une boîte de dialogue non modale à partir d'un modèle de boîte de dialogue fourni par l'utilisateur. La boîte de dialogue résultante peut contenir des contrôles ActiveX. |
| AtlAxCreateControl | Crée un contrôle ActiveX, puis initialise et héberge ce dernier dans la fenêtre spécifiée. |
| AtlAxCreateControlEx | Crée un contrôle ActiveX, l’initialise, l’héberge dans la fenêtre spécifiée et récupère un pointeur d’interface (ou des pointeurs) à partir du contrôle. |
| AtlAxCreateControlLic | Crée un contrôle ActiveX sous licence, puis initialise et héberge ce dernier dans la fenêtre spécifiée. |
| AtlAxCreateControlLicEx | Crée un contrôle ActiveX sous licence, l’initialise, l’héberge dans la fenêtre spécifiée et récupère un pointeur d’interface (ou des pointeurs) à partir du contrôle. |
| AtlAxAttachControl | Joint un contrôle précédemment créé à la fenêtre spécifiée. |
| AtlAxGetHost | Permet d’obtenir un pointeur d’interface direct vers le conteneur pour une fenêtre spécifiée (le cas échéant), en fonction de son handle. |
| AtlAxGetControl | Permet d’obtenir un pointeur d’interface direct vers le contrôle contenu dans une fenêtre spécifiée (le cas échéant), en fonction de son handle. |
| AtlSetChildSite | Initialise le IUnknown site enfant. |
| AtlAxWinInit | Initialise le code d’hébergement pour les objets AxWin. |
| AtlAxWinTerm | Annule l’initialisation du code d’hébergement pour les objets AxWin. |
| AtlGetObjectSourceInterface | Retourne des informations sur l’interface source par défaut d’un objet. |
Spécifications
En-tête : atlhost.h
AtlAxDialogBox
Crée une boîte de dialogue modale à partir d'un modèle de boîte de dialogue fourni par l'utilisateur.
ATLAPI_(int) AtlAxDialogBox(
HINSTANCE hInstance,
LPCWSTR lpTemplateName,
HWND hWndParent,
DLGPROC lpDialogProc,
LPARAM dwInitParam);
Paramètres
hInstance
[in] Identifie une instance du module dont le fichier exécutable contient le modèle de boîte de dialogue.
lpTemplateName
[in] Identifie le modèle de boîte de dialogue. Ce paramètre est soit le pointeur vers une chaîne de caractères terminée par null qui spécifie le nom du modèle de boîte de dialogue, soit une valeur entière qui spécifie l’identificateur de ressource du modèle de boîte de dialogue. Si le paramètre spécifie un identificateur de ressource, son mot de classement élevé doit être égal à zéro et son mot de bas ordre doit contenir l’identificateur. Vous pouvez utiliser la macro MAKEINTRESOURCE pour créer cette valeur.
hWndParent
[in] Identifie la fenêtre propriétaire de la boîte de dialogue.
lpDialogProc
[in] Pointe vers la procédure de boîte de dialogue. Pour plus d’informations sur la procédure de boîte de dialogue, consultez DialogProc.
dwInitParam
[in] Spécifie la valeur à passer à la boîte de dialogue dans le paramètre lParam du message WM_INITDIALOG.
Valeur de retour
Une des valeurs HRESULT standard.
Notes
Pour utiliser AtlAxDialogBox un modèle de boîte de dialogue qui contient un contrôle ActiveX, spécifiez une chaîne CLSID, APPID ou URL valide comme champ de texte de la section CONTROL de la ressource de dialogue, ainsi que « AtlAxWin80 » comme champ de nom de classe sous la même section. Les éléments suivants illustrent l’apparence d’une section CONTROL valide :
CONTROL "{04FE35E9-ADBC-4f1d-83FE-8FA4D1F71C7F}", IDC_TEST,
"AtlAxWin80", WS_GROUP | WS_TABSTOP, 0, 0, 100, 100
Pour plus d’informations sur la modification de scripts de ressources, consultez Guide pratique pour créer des ressources. Pour plus d’informations sur les instructions de définition de ressource de contrôle, consultez Paramètres de contrôle communs sous Kit de développement logiciel (SDK) Windows : Outils sdk.
Pour plus d’informations sur les boîtes de dialogue en général, reportez-vous à DialogBox et CreateDialogParam dans le Kit de développement logiciel (SDK) Windows.
AtlAxCreateDialog
Crée une boîte de dialogue non modale à partir d'un modèle de boîte de dialogue fourni par l'utilisateur.
ATLAPI_(HWND) AtlAxCreateDialog(
HINSTANCE hInstance,
LPCWSTR lpTemplateName,
HWND hWndParent,
DLGPROC lpDialogProc,
LPARAM dwInitParam);
Paramètres
hInstance
[in] Identifie une instance du module dont le fichier exécutable contient le modèle de boîte de dialogue.
lpTemplateName
[in] Identifie le modèle de boîte de dialogue. Ce paramètre est soit le pointeur vers une chaîne de caractères terminée par null qui spécifie le nom du modèle de boîte de dialogue, soit une valeur entière qui spécifie l’identificateur de ressource du modèle de boîte de dialogue. Si le paramètre spécifie un identificateur de ressource, son mot de classement élevé doit être égal à zéro et son mot de bas ordre doit contenir l’identificateur. Vous pouvez utiliser la macro MAKEINTRESOURCE pour créer cette valeur.
hWndParent
[in] Identifie la fenêtre propriétaire de la boîte de dialogue.
lpDialogProc
[in] Pointe vers la procédure de boîte de dialogue. Pour plus d’informations sur la procédure de boîte de dialogue, consultez DialogProc.
dwInitParam
[in] Spécifie la valeur à passer à la boîte de dialogue dans le paramètre lParam du message WM_INITDIALOG.
Valeur de retour
Une des valeurs HRESULT standard.
Notes
La boîte de dialogue résultante peut contenir des contrôles ActiveX.
Consultez CreateDialog et CreateDialogParam dans le Kit de développement logiciel (SDK) Windows.
AtlAxCreateControl
Crée un contrôle ActiveX, puis initialise et héberge ce dernier dans la fenêtre spécifiée.
ATLAPI AtlAxCreateControl(
LPCOLESTR lpszName,
HWND hWnd,
IStream* pStream,
IUnknown** ppUnkContainer);
Paramètres
lpszName
Pointeur vers une chaîne à passer au contrôle. Doit être mis en forme de l’une des manières suivantes :
Un ProgID tel que
"MSCAL.Calendar.7"Un CLSID tel que
"{8E27C92B-1264-101C-8A2F-040224009C02}"URL telle que
"<https://www.microsoft.com>"Référence à un document actif tel que
"file://\\\Documents\MyDoc.doc"Fragment de HTML tel que
"MSHTML:\<HTML>\<BODY>This is a line of text\</BODY>\</HTML>"Remarque
"MSHTML:"doit précéder le fragment HTML afin qu’il soit désigné comme étant un flux MSHTML.
hWnd
[in] Gérez la fenêtre à laquelle le contrôle sera attaché.
pStream
[in] Pointeur vers un flux utilisé pour initialiser les propriétés du contrôle. Sa valeur peut être NULL.
ppUnkContainer
[out] Adresse d’un pointeur qui recevra le IUnknown conteneur. Sa valeur peut être NULL.
Valeur de retour
Une des valeurs HRESULT standard.
Notes
Cette fonction globale vous donne le même résultat que l’appel d’AtlAxCreateControlEx(lpszName, hWnd, pStream, NULL, NULL, NULL, NULL) ;
Pour créer un contrôle ActiveX sous licence, consultez AtlAxCreateControlLic.
AtlAxCreateControlEx
Crée un contrôle ActiveX, puis initialise et héberge ce dernier dans la fenêtre spécifiée. Un pointeur d'interface et un récepteur d'événements du nouveau contrôle peuvent également être créés.
ATLAPI AtlAxCreateControlEx(
LPCOLESTR lpszName,
HWND hWnd,
IStream* pStream,
IUnknown** ppUnkContainer,
IUnknown** ppUnkControl,
REFIID iidSink = IID_NULL,
IUnknown* punkSink = NULL);
Paramètres
lpszName
Pointeur vers une chaîne à passer au contrôle. Doit être mis en forme de l’une des manières suivantes :
Un ProgID tel que
"MSCAL.Calendar.7"Un CLSID tel que
"{8E27C92B-1264-101C-8A2F-040224009C02}"URL telle que
"<https://www.microsoft.com>"Référence à un document actif tel que
"file://\\\Documents\MyDoc.doc"Fragment de HTML tel que
"MSHTML:\<HTML>\<BODY>This is a line of text\</BODY>\</HTML>"Remarque
"MSHTML:"doit précéder le fragment HTML afin qu’il soit désigné comme étant un flux MSHTML.
hWnd
[in] Gérez la fenêtre à laquelle le contrôle sera attaché.
pStream
[in] Pointeur vers un flux utilisé pour initialiser les propriétés du contrôle. Sa valeur peut être NULL.
ppUnkContainer
[out] Adresse d’un pointeur qui recevra le IUnknown conteneur. Sa valeur peut être NULL.
ppUnkControl
[out] Adresse d’un pointeur qui recevra le IUnknown contrôle créé. Sa valeur peut être NULL.
iidSink
Identificateur d’interface d’une interface sortante sur l’objet contenu.
punkSink
Pointeur vers l’interface IUnknown de l’objet récepteur à connecter au point de connexion spécifié par iidSink sur l’objet contenu après la création de l’objet contenu.
Valeur de retour
Une des valeurs HRESULT standard.
Notes
AtlAxCreateControlEx est similaire à AtlAxCreateControl , mais vous permet également de recevoir un pointeur d’interface vers le contrôle nouvellement créé et de configurer un récepteur d’événements pour recevoir les événements déclenchés par le contrôle.
Pour créer un contrôle ActiveX sous licence, consultez AtlAxCreateControlLicEx.
AtlAxCreateControlLic
Crée un contrôle ActiveX sous licence, puis initialise et héberge ce dernier dans la fenêtre spécifiée.
ATLAPI AtlAxCreateControlLic(
LPCOLESTR lpszName,
HWND hWnd,
IStream* pStream,
IUnknown** ppUnkContainer,
BSTR bstrLic = NULL);
Paramètres
lpszName
Pointeur vers une chaîne à passer au contrôle. Doit être mis en forme de l’une des manières suivantes :
Un ProgID tel que
"MSCAL.Calendar.7"Un CLSID tel que
"{8E27C92B-1264-101C-8A2F-040224009C02}"URL telle que
"<https://www.microsoft.com>"Référence à un document actif tel que
"file://\\\Documents\MyDoc.doc"Fragment de HTML tel que
"MSHTML:\<HTML>\<BODY>This is a line of text\</BODY>\</HTML>"Remarque
"MSHTML:"doit précéder le fragment HTML afin qu’il soit désigné comme étant un flux MSHTML.
hWnd
Gérez la fenêtre à laquelle le contrôle sera attaché.
pStream
Pointeur vers un flux utilisé pour initialiser les propriétés du contrôle. Sa valeur peut être NULL.
ppUnkContainer
Adresse d’un pointeur qui recevra le IUnknown conteneur. Sa valeur peut être NULL.
bstrLic
BSTR contenant la licence du contrôle.
Valeur de retour
Une des valeurs HRESULT standard.
Exemple
Consultez l’hébergement de contrôles ActiveX à l’aide d’ATL AXHost pour obtenir un exemple d’utilisation AtlAxCreateControlLic.
AtlAxCreateControlLicEx
Crée un contrôle ActiveX sous licence, puis initialise et héberge ce dernier dans la fenêtre spécifiée. Un pointeur d'interface et un récepteur d'événements du nouveau contrôle peuvent également être créés.
ATLAPI AtlAxCreateControlLicEx(
LPCOLESTR lpszName,
HWND hWnd,
IStream* pStream,
IUnknown** ppUnkContainer,
IUnknown** ppUnkControl,
REFIID iidSink = IID_NULL,
IUnknown* punkSink = NULL,
BSTR bstrLic = NULL);
Paramètres
lpszName
Pointeur vers une chaîne à passer au contrôle. Doit être mis en forme de l’une des manières suivantes :
Un ProgID tel que
"MSCAL.Calendar.7"Un CLSID tel que
"{8E27C92B-1264-101C-8A2F-040224009C02}"URL telle que
"<https://www.microsoft.com>"Référence à un document actif tel que
"file://\\\Documents\MyDoc.doc"Fragment de HTML tel que
"MSHTML:\<HTML>\<BODY>This is a line of text\</BODY>\</HTML>"Remarque
"MSHTML:"doit précéder le fragment HTML afin qu’il soit désigné comme étant un flux MSHTML.
hWnd
Gérez la fenêtre à laquelle le contrôle sera attaché.
pStream
Pointeur vers un flux utilisé pour initialiser les propriétés du contrôle. Sa valeur peut être NULL.
ppUnkContainer
Adresse d’un pointeur qui recevra le IUnknown conteneur. Sa valeur peut être NULL.
ppUnkControl
[out] Adresse d’un pointeur qui recevra le IUnknown contrôle créé. Sa valeur peut être NULL.
iidSink
Identificateur d’interface d’une interface sortante sur l’objet contenu.
punkSink
Pointeur vers l’interface IUnknown de l’objet récepteur à connecter au point de connexion spécifié par iidSink sur l’objet contenu après la création de l’objet contenu.
bstrLic
BSTR contenant la licence du contrôle.
Valeur de retour
Une des valeurs HRESULT standard.
Notes
AtlAxCreateControlLicEx est similaire à AtlAxCreateControlLic , mais vous permet également de recevoir un pointeur d’interface vers le contrôle nouvellement créé et de configurer un récepteur d’événements pour recevoir les événements déclenchés par le contrôle.
Exemple
Consultez l’hébergement de contrôles ActiveX à l’aide d’ATL AXHost pour obtenir un exemple d’utilisation AtlAxCreateControlLicEx.
AtlAxAttachControl
Joint un contrôle précédemment créé à la fenêtre spécifiée.
ATLAPI AtlAxAttachControl(
IUnknown* pControl,
HWND hWnd,
IUnknown** ppUnkContainer);
Paramètres
pControl
[in] Pointeur vers le IUnknown contrôle.
hWnd
[in] Gérez la fenêtre qui hébergera le contrôle.
ppUnkContainer
[out] Pointeur vers un pointeur vers l’objet IUnknown conteneur.
Valeur de retour
Une des valeurs HRESULT standard.
Notes
Utilisez AtlAxCreateControlEx et AtlAxCreateControl pour créer et attacher simultanément un contrôle.
Remarque
L’objet de contrôle attaché doit être correctement initialisé avant d’appeler AtlAxAttachControl.
AtlAxGetHost
Obtient un pointeur d'interface direct vers le conteneur d'une fenêtre spécifique (le cas échéant), en fonction de son handle.
ATLAPI AtlAxGetHost(HWND h, IUnknown** pp);
Paramètres
h
[in] Handle vers la fenêtre qui héberge le contrôle.
Pp
[out] Conteneur IUnknown du contrôle.
Valeur de retour
Une des valeurs HRESULT standard.
AtlAxGetControl
Obtient un pointeur d'interface direct vers le contrôle contenu dans une fenêtre spécifique en fonction de son handle.
ATLAPI AtlAxGetControl(HWND h, IUnknown** pp);
Paramètres
h
[in] Handle vers la fenêtre qui héberge le contrôle.
Pp
[out] Contrôle IUnknown hébergé.
Valeur de retour
Une des valeurs HRESULT standard.
AtlSetChildSite
Appelez cette fonction pour définir le site de l’objet enfant sur l’objet IUnknown parent.
HRESULT AtlSetChildSite(IUnknown* punkChild, IUnknown* punkParent);
Paramètres
punkChild
[in] Pointeur vers l’interface IUnknown de l’enfant.
punkParent
[in] Pointeur vers l’interface IUnknown du parent.
Valeur de retour
Valeur HRESULT standard.
AtlAxWinInit
Cette fonction initialise le code d’hébergement de contrôle ATL en inscrivant les classes de fenêtre « AtlAxWin80 » et « AtlAxWinLic80 », ainsi qu’un couple de messages de fenêtre personnalisés.
ATLAPI_(BOOL) AtlAxWinInit();
Valeur de retour
Différent de zéro si l’initialisation du code d’hébergement du contrôle a réussi ; sinon FALSE.
Notes
Cette fonction doit être appelée avant d’utiliser l’API d’hébergement du contrôle ATL. Après un appel à cette fonction, la classe de fenêtre « AtlAxWin » peut être utilisée dans les appels à CreateWindow ou CreateWindowEx, comme décrit dans le Kit de développement logiciel (SDK) Windows.
AtlAxWinTerm
Cette fonction ne initialise pas le code d’hébergement du contrôle ATL en annulant l’inscription des classes de fenêtre « AtlAxWin80 » et « AtlAxWinLic80 ».
inline BOOL AtlAxWinTerm();
Valeur de retour
Retourne toujours TRUE.
Notes
Cette fonction appelle simplement UnregisterClass , comme décrit dans le Kit de développement logiciel (SDK) Windows.
Appelez cette fonction pour propre une fois que toutes les fenêtres hôtes existantes ont été détruites si vous avez appelé AtlAxWinInit et que vous n’avez plus besoin de créer des fenêtres hôtes. Si vous n’appelez pas cette fonction, la classe de fenêtre est annulée automatiquement lorsque le processus se termine.
AtlGetObjectSourceInterface
Appelez cette fonction pour récupérer des informations sur l'interface source par défaut d'un objet.
ATLAPI AtlGetObjectSourceInterface(
IUnknown* punkObj,
GUID* plibid,
IID* piid,
unsigned short* pdwMajor,
unsigned short* pdwMinor);
Paramètres
punkObj
[in] Pointeur vers l’objet pour lequel les informations doivent être retournées.
plibid
[out] Pointeur vers le LIBID de la bibliothèque de types contenant la définition de l’interface source.
piid
[out] Pointeur vers l’ID d’interface de l’interface source par défaut de l’objet.
pdwMajor
[out] Pointeur vers le numéro de version principal de la bibliothèque de types contenant la définition de l’interface source.
pdwMinor
[out] Pointeur vers le numéro de version secondaire de la bibliothèque de types contenant la définition de l’interface source.
Valeur de retour
Valeur HRESULT standard.
Notes
AtlGetObjectSourceInterface peut vous fournir l’ID d’interface de l’interface source par défaut, ainsi que les numéros de version principale et mineure de la bibliothèque de types décrivant cette interface.
Remarque
Pour que cette fonction récupère correctement les informations demandées, l’objet représenté par punkObj doit implémenter IDispatch (et retourner des informations de type via IDispatch::GetTypeInfo) plus il doit également implémenter soit IProvideClassInfo2 soit IPersist. Les informations de type pour l’interface source doivent se trouver dans la même bibliothèque de types que les informations de type pour IDispatch.
Exemple
L’exemple ci-dessous montre comment vous pouvez définir une classe récepteur d’événements, CEasySinkce qui réduit le nombre d’arguments de modèle que vous pouvez passer aux IDispEventImpl éléments essentiels. EasyAdvise et EasyUnadvise permet AtlGetObjectSourceInterface d’initialiser les membres IDispEventImpl avant d’appeler DispEventAdvise ou DispEventUnadvise.
template <UINT nID, class T>
class CEasySink : public IDispEventImpl<nID, T>
{
public:
HRESULT EasyAdvise(IUnknown* pUnk)
{
AtlGetObjectSourceInterface(pUnk,
&m_libid, &m_iid, &m_wMajorVerNum, &m_wMinorVerNum);
return DispEventAdvise(pUnk, &m_iid);
}
HRESULT EasyUnadvise(IUnknown* pUnk)
{
AtlGetObjectSourceInterface(pUnk,
&m_libid, &m_iid, &m_wMajorVerNum, &m_wMinorVerNum);
return DispEventUnadvise(pUnk, &m_iid);
}
};
Voir aussi
Commentaires
Prochainement : Tout au long de l'année 2024, nous supprimerons progressivement les GitHub Issues en tant que mécanisme de retour d'information pour le contenu et nous les remplacerons par un nouveau système de retour d'information. Pour plus d’informations, voir: https://aka.ms/ContentUserFeedback.
Soumettre et afficher des commentaires pour