Partager via

Fonctions globales de contrôle composite

  • Article

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 nettoyer 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

Fonctions
Macros de contrôle composite