Funzioni globali di controllo composito

  • Articolo

Queste funzioni forniscono il supporto per la creazione di finestre di dialogo e per la creazione, l'hosting e la gestione delle licenze di controlli ActiveX.

Importante

Le funzioni elencate nella tabella seguente non possono essere usate nelle applicazioni eseguite in Windows Runtime.

Funzione Descrizione
AtlAxDialogBox Crea una finestra di dialogo modale da un modello di finestra di dialogo fornito dall'utente. La finestra di dialogo risultante può contenere controlli ActiveX.
AtlAxCreateDialog Crea una finestra di dialogo non modale da un modello di finestra di dialogo fornito dall'utente. La finestra di dialogo risultante può contenere controlli ActiveX.
AtlAxCreateControl Crea un controllo ActiveX, lo inizializza e lo ospita nella finestra specificata.
AtlAxCreateControlEx Crea un controllo ActiveX, lo inizializza, lo ospita nella finestra specificata e recupera un puntatore di interfaccia (o puntatori) dal controllo.
AtlAxCreateControlLic Crea un controllo ActiveX con licenza, lo inizializza e lo ospita nella finestra specificata.
AtlAxCreateControlLicEx Crea un controllo ActiveX concesso in licenza, lo inizializza, lo ospita nella finestra specificata e recupera un puntatore di interfaccia (o puntatori) dal controllo.
AtlAxAttachControl Associa un controllo creato in precedenza alla finestra specificata.
AtlAxGetHost Usato per ottenere un puntatore diretto all'interfaccia al contenitore per una finestra specificata (se presente), dato il relativo handle.
AtlAxGetControl Utilizzato per ottenere un puntatore diretto all'interfaccia al controllo contenuto all'interno di una finestra specificata (se presente), dato il relativo handle.
AtlSetChildSite Inizializza l'oggetto IUnknown del sito figlio.
AtlAxWinInit Inizializza il codice di hosting per gli oggetti AxWin.
AtlAxWinTerm Annulla l'inizializzazione del codice di hosting per gli oggetti AxWin.
AtlGetObjectSourceInterface Restituisce informazioni sull'interfaccia di origine predefinita di un oggetto .

Requisiti

Intestazione: atlhost.h

AtlAxDialogBox

Crea una finestra di dialogo modale da un modello di finestra di dialogo fornito dall'utente.

ATLAPI_(int) AtlAxDialogBox(
    HINSTANCE hInstance,
    LPCWSTR lpTemplateName,
    HWND hWndParent,
    DLGPROC lpDialogProc,
    LPARAM dwInitParam);

Parametri

hInstance
[in] Identifica un'istanza del modulo il cui file eseguibile contiene il modello della finestra di dialogo.

lpTemplateName
[in] Identifica il modello della finestra di dialogo. Questo parametro è il puntatore a una stringa di caratteri con terminazione Null che specifica il nome del modello di finestra di dialogo o un valore intero che specifica l'identificatore della risorsa del modello di finestra di dialogo. Se il parametro specifica un identificatore di risorsa, la parola dell'ordine elevato deve essere zero e la parola con ordine minimo deve contenere l'identificatore. È possibile utilizzare la macro MAKEINTRESOURCE per creare questo valore.

hWndParent
[in] Identifica la finestra proprietaria della finestra di dialogo.

lpDialogProc
[in] Punta alla routine della finestra di dialogo. Per altre informazioni sulla procedura della finestra di dialogo, vedere DialogProc.

dwInitParam
[in] Specifica il valore da passare alla finestra di dialogo nel parametro lParam del messaggio WM_INITDIALOG.

Valore restituito

Uno dei valori HRESULT standard.

Osservazioni:

Per usare AtlAxDialogBox con un modello di finestra di dialogo che contiene un controllo ActiveX, specificare una stringa CLSID, APPID o URL valida come campo di testo della sezione CONTROL della risorsa della finestra di dialogo, insieme a "AtlAxWin80" come campo del nome della classe nella stessa sezione. Di seguito viene illustrato l'aspetto di una sezione CONTROL valida:

CONTROL    "{04FE35E9-ADBC-4f1d-83FE-8FA4D1F71C7F}", IDC_TEST,
    "AtlAxWin80", WS_GROUP | WS_TABSTOP, 0, 0, 100, 100

Per altre informazioni sulla modifica degli script delle risorse, vedere Procedura: Creare risorse. Per altre informazioni sulle istruzioni di definizione delle risorse di controllo, vedere Parametri di controllo comuni in Windows SDK: Strumenti SDK.

Per altre informazioni sulle finestre di dialogo in generale, vedere DialogBox e CreateDialogParam in Windows SDK.

AtlAxCreateDialog

Crea una finestra di dialogo non modale da un modello di finestra di dialogo fornito dall'utente.

ATLAPI_(HWND) AtlAxCreateDialog(
    HINSTANCE hInstance,
    LPCWSTR lpTemplateName,
    HWND hWndParent,
    DLGPROC lpDialogProc,
    LPARAM dwInitParam);

Parametri

hInstance
[in] Identifica un'istanza del modulo il cui file eseguibile contiene il modello della finestra di dialogo.

lpTemplateName
[in] Identifica il modello della finestra di dialogo. Questo parametro è il puntatore a una stringa di caratteri con terminazione Null che specifica il nome del modello di finestra di dialogo o un valore intero che specifica l'identificatore della risorsa del modello di finestra di dialogo. Se il parametro specifica un identificatore di risorsa, la parola dell'ordine elevato deve essere zero e la parola con ordine minimo deve contenere l'identificatore. È possibile utilizzare la macro MAKEINTRESOURCE per creare questo valore.

hWndParent
[in] Identifica la finestra proprietaria della finestra di dialogo.

lpDialogProc
[in] Punta alla routine della finestra di dialogo. Per altre informazioni sulla procedura della finestra di dialogo, vedere DialogProc.

dwInitParam
[in] Specifica il valore da passare alla finestra di dialogo nel parametro lParam del messaggio WM_INITDIALOG.

Valore restituito

Uno dei valori HRESULT standard.

Osservazioni:

La finestra di dialogo risultante può contenere controlli ActiveX.

Vedere CreateDialog e CreateDialogParam in Windows SDK.

AtlAxCreateControl

Crea un controllo ActiveX, lo inizializza e lo ospita nella finestra specificata.

ATLAPI AtlAxCreateControl(
    LPCOLESTR lpszName,
    HWND hWnd,
    IStream* pStream,
    IUnknown** ppUnkContainer);

Parametri

lpszName
Puntatore a una stringa da passare al controllo. Deve essere formattato in uno dei modi seguenti:

  • ProgID, ad esempio "MSCAL.Calendar.7"

  • CLSID, ad esempio "{8E27C92B-1264-101C-8A2F-040224009C02}"

  • URL, ad esempio "<https://www.microsoft.com>"

  • Riferimento a un documento attivo, ad esempio "file://\\\Documents\MyDoc.doc"

  • Frammento di codice HTML, ad esempio "MSHTML:\<HTML>\<BODY>This is a line of text\</BODY>\</HTML>"

    Nota

    "MSHTML:" deve precedere il frammento HTML in modo che sia designato come flusso MSHTML.

hWnd
[in] Handle per la finestra a cui verrà collegato il controllo.

pStream
[in] Puntatore a un flusso utilizzato per inizializzare le proprietà del controllo. Può essere NULL.

ppUnkContainer
[out] Indirizzo di un puntatore che riceverà l'oggetto IUnknown del contenitore. Può essere NULL.

Valore restituito

Uno dei valori HRESULT standard.

Osservazioni:

Questa funzione globale offre lo stesso risultato della chiamata ad AtlAxCreateControlEx(lpszName, hWnd, pStream, NULL, NULL, NULL);

Per creare un controllo ActiveX concesso in licenza, vedere AtlAxCreateControlLic.

AtlAxCreateControlEx

Crea un controllo ActiveX, lo inizializza e lo ospita nella finestra specificata. È possibile creare anche un puntatore a interfaccia e un sink di evento per il nuovo controllo.

ATLAPI AtlAxCreateControlEx(
    LPCOLESTR lpszName,
    HWND hWnd,
    IStream* pStream,
    IUnknown** ppUnkContainer,
    IUnknown** ppUnkControl,
    REFIID iidSink = IID_NULL,
    IUnknown* punkSink = NULL);

Parametri

lpszName
Puntatore a una stringa da passare al controllo. Deve essere formattato in uno dei modi seguenti:

  • ProgID, ad esempio "MSCAL.Calendar.7"

  • CLSID, ad esempio "{8E27C92B-1264-101C-8A2F-040224009C02}"

  • URL, ad esempio "<https://www.microsoft.com>"

  • Riferimento a un documento attivo, ad esempio "file://\\\Documents\MyDoc.doc"

  • Frammento di codice HTML, ad esempio "MSHTML:\<HTML>\<BODY>This is a line of text\</BODY>\</HTML>"

    Nota

    "MSHTML:" deve precedere il frammento HTML in modo che sia designato come flusso MSHTML.

hWnd
[in] Handle per la finestra a cui verrà collegato il controllo.

pStream
[in] Puntatore a un flusso utilizzato per inizializzare le proprietà del controllo. Può essere NULL.

ppUnkContainer
[out] Indirizzo di un puntatore che riceverà l'oggetto IUnknown del contenitore. Può essere NULL.

ppUnkControl
[out] Indirizzo di un puntatore che riceverà l'oggetto IUnknown del controllo creato. Può essere NULL.

iidSink
Identificatore dell'interfaccia di un'interfaccia in uscita nell'oggetto contenuto.

punkSink
Puntatore all'interfaccia IUnknown dell'oggetto sink da connettere al punto di connessione specificato da iidSink sull'oggetto contenuto dopo la creazione dell'oggetto contenuto.

Valore restituito

Uno dei valori HRESULT standard.

Osservazioni:

AtlAxCreateControlEx è simile ad AtlAxCreateControl , ma consente anche di ricevere un puntatore di interfaccia al controllo appena creato e di configurare un sink di eventi per ricevere gli eventi generati dal controllo.

Per creare un controllo ActiveX concesso in licenza, vedere AtlAxCreateControlLicEx.

AtlAxCreateControlLic

Crea un controllo ActiveX con licenza, lo inizializza e lo ospita nella finestra specificata.

ATLAPI AtlAxCreateControlLic(
    LPCOLESTR lpszName,
    HWND hWnd,
    IStream* pStream,
    IUnknown** ppUnkContainer,
    BSTR bstrLic = NULL);

Parametri

lpszName
Puntatore a una stringa da passare al controllo. Deve essere formattato in uno dei modi seguenti:

  • ProgID, ad esempio "MSCAL.Calendar.7"

  • CLSID, ad esempio "{8E27C92B-1264-101C-8A2F-040224009C02}"

  • URL, ad esempio "<https://www.microsoft.com>"

  • Riferimento a un documento attivo, ad esempio "file://\\\Documents\MyDoc.doc"

  • Frammento di codice HTML, ad esempio "MSHTML:\<HTML>\<BODY>This is a line of text\</BODY>\</HTML>"

    Nota

    "MSHTML:" deve precedere il frammento HTML in modo che sia designato come flusso MSHTML.

hWnd
Handle per la finestra a cui verrà collegato il controllo.

pStream
Puntatore a un flusso utilizzato per inizializzare le proprietà del controllo. Può essere NULL.

ppUnkContainer
Indirizzo di un puntatore che riceverà l'oggetto IUnknown del contenitore. Può essere NULL.

bstrLic
BSTR contenente la licenza per il controllo.

Valore restituito

Uno dei valori HRESULT standard.

Esempio

Per un esempio di come usare , vedere Hosting di controlli ActiveX tramite ATL AXHost.AtlAxCreateControlLic

AtlAxCreateControlLicEx

Crea un controllo ActiveX con licenza, lo inizializza e lo ospita nella finestra specificata. È possibile creare anche un puntatore a interfaccia e un sink di evento per il nuovo controllo.

ATLAPI AtlAxCreateControlLicEx(
    LPCOLESTR lpszName,
    HWND hWnd,
    IStream* pStream,
    IUnknown** ppUnkContainer,
    IUnknown** ppUnkControl,
    REFIID iidSink = IID_NULL,
    IUnknown* punkSink = NULL,
    BSTR bstrLic = NULL);

Parametri

lpszName
Puntatore a una stringa da passare al controllo. Deve essere formattato in uno dei modi seguenti:

  • ProgID, ad esempio "MSCAL.Calendar.7"

  • CLSID, ad esempio "{8E27C92B-1264-101C-8A2F-040224009C02}"

  • URL, ad esempio "<https://www.microsoft.com>"

  • Riferimento a un documento attivo, ad esempio "file://\\\Documents\MyDoc.doc"

  • Frammento di codice HTML, ad esempio "MSHTML:\<HTML>\<BODY>This is a line of text\</BODY>\</HTML>"

    Nota

    "MSHTML:" deve precedere il frammento HTML in modo che sia designato come flusso MSHTML.

hWnd
Handle per la finestra a cui verrà collegato il controllo.

pStream
Puntatore a un flusso utilizzato per inizializzare le proprietà del controllo. Può essere NULL.

ppUnkContainer
Indirizzo di un puntatore che riceverà l'oggetto IUnknown del contenitore. Può essere NULL.

ppUnkControl
[out] Indirizzo di un puntatore che riceverà l'oggetto IUnknown del controllo creato. Può essere NULL.

iidSink
Identificatore dell'interfaccia di un'interfaccia in uscita nell'oggetto contenuto.

punkSink
Puntatore all'interfaccia IUnknown dell'oggetto sink da connettere al punto di connessione specificato da iidSink sull'oggetto contenuto dopo la creazione dell'oggetto contenuto.

bstrLic
BSTR contenente la licenza per il controllo.

Valore restituito

Uno dei valori HRESULT standard.

Osservazioni:

AtlAxCreateControlLicEx è simile ad AtlAxCreateControlLic , ma consente anche di ricevere un puntatore di interfaccia al controllo appena creato e di configurare un sink di eventi per ricevere gli eventi generati dal controllo.

Esempio

Per un esempio di come usare , vedere Hosting di controlli ActiveX tramite ATL AXHost.AtlAxCreateControlLicEx

AtlAxAttachControl

Associa un controllo creato in precedenza alla finestra specificata.

ATLAPI AtlAxAttachControl(
    IUnknown* pControl,
    HWND hWnd,
    IUnknown** ppUnkContainer);

Parametri

pControl
[in] Puntatore all'oggetto IUnknown del controllo .

hWnd
[in] Handle per la finestra che ospiterà il controllo .

ppUnkContainer
[out] Puntatore a un puntatore all'oggetto IUnknown dell'oggetto contenitore.

Valore restituito

Uno dei valori HRESULT standard.

Osservazioni:

Usare AtlAxCreateControlEx e AtlAxCreateControl per creare e collegare contemporaneamente un controllo.

Nota

L'oggetto di controllo associato deve essere inizializzato correttamente prima di chiamare AtlAxAttachControl.

AtlAxGetHost

Ottiene un puntatore a interfaccia diretto per il contenitore di una finestra specifica (se presente) in base al relativo handle.

ATLAPI AtlAxGetHost(HWND h, IUnknown** pp);

Parametri

h
[in] Handle per la finestra che ospita il controllo.

Pp
[out] Oggetto IUnknown del contenitore del controllo.

Valore restituito

Uno dei valori HRESULT standard.

AtlAxGetControl

Ottiene un puntatore a interfaccia diretto per il controllo contenuto all'interno di una finestra specifica in base al relativo handle.

ATLAPI AtlAxGetControl(HWND h, IUnknown** pp);

Parametri

h
[in] Handle per la finestra che ospita il controllo.

Pp
[out] Oggetto IUnknown del controllo ospitato.

Valore restituito

Uno dei valori HRESULT standard.

AtlSetChildSite

Chiamare questa funzione per impostare il sito dell'oggetto figlio sull'oggetto IUnknown padre.

HRESULT AtlSetChildSite(IUnknown* punkChild, IUnknown* punkParent);

Parametri

punkChild
[in] Puntatore all'interfaccia dell'elemento IUnknown figlio.

punkParent
[in] Puntatore all'interfaccia IUnknown dell'elemento padre.

Valore restituito

Valore HRESULT standard.

AtlAxWinInit

Questa funzione inizializza il codice di hosting del controllo ATL registrando le classi della finestra "AtlAxWin80" e "AtlAxWinLic80" più un paio di messaggi di finestra personalizzati.

ATLAPI_(BOOL) AtlAxWinInit();

Valore restituito

Diverso da zero se l'inizializzazione del codice host del controllo ha avuto esito positivo; in caso contrario FALSE.

Osservazioni:

Questa funzione deve essere chiamata prima di usare l'API di hosting del controllo ATL. Dopo una chiamata a questa funzione, la classe di finestra "AtlAxWin" può essere usata nelle chiamate a CreateWindow o CreateWindowEx, come descritto in Windows SDK.

AtlAxWinTerm

Questa funzione annulla l'inizializzazione del codice di hosting del controllo ATL annullando la registrazione delle classi della finestra "AtlAxWin80" e "AtlAxWinLic80".

inline BOOL AtlAxWinTerm();

Valore restituito

Restituisce sempre TRUE.

Osservazioni:

Questa funzione chiama semplicemente UnregisterClass come descritto in Windows SDK.

Chiamare questa funzione per eseguire la pulizia dopo che tutte le finestre host esistenti sono state eliminate se si chiama AtlAxWinInit e non è più necessario creare finestre host. Se non si chiama questa funzione, la classe window verrà annullata automaticamente al termine del processo.

AtlGetObjectSourceInterface

Chiamare questa funzione per recuperare le informazioni sull'interfaccia di origine predefinita di un oggetto.

ATLAPI AtlGetObjectSourceInterface(
    IUnknown* punkObj,
    GUID* plibid,
    IID* piid,
    unsigned short* pdwMajor,
    unsigned short* pdwMinor);

Parametri

punkObj
[in] Puntatore all'oggetto per cui devono essere restituite le informazioni.

plibid
[out] Puntatore al LIBID della libreria dei tipi contenente la definizione dell'interfaccia di origine.

piid
[out] Puntatore all'ID dell'interfaccia dell'interfaccia di origine predefinita dell'oggetto.

pdwMajor
[out] Puntatore al numero di versione principale della libreria dei tipi contenente la definizione dell'interfaccia di origine.

pdwMinor
[out] Puntatore al numero di versione secondaria della libreria dei tipi contenente la definizione dell'interfaccia di origine.

Valore restituito

Valore HRESULT standard.

Osservazioni:

AtlGetObjectSourceInterface può fornire l'ID interfaccia dell'interfaccia di origine predefinita, insieme ai numeri di versione LIBID e principali e secondari della libreria dei tipi che descrive tale interfaccia.

Nota

Affinché questa funzione recuperi correttamente le informazioni richieste, l'oggetto rappresentato da punkObj deve implementare IDispatch (e restituire informazioni sul tipo tramite IDispatch::GetTypeInfo) e deve implementare IProvideClassInfo2 anche o IPersist. Le informazioni sul tipo per l'interfaccia di origine devono trovarsi nella stessa libreria dei tipi delle informazioni sul tipo per IDispatch.

Esempio

L'esempio seguente illustra come definire una classe sink di evento, CEasySink, che riduce il numero di argomenti modello che è possibile passare alle IDispEventImpl informazioni di base di base. EasyAdvise e EasyUnadvise usare AtlGetObjectSourceInterface per inizializzare i membri IDispEventImpl prima di chiamare DispEventAdvise o 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);
   }
};

Vedi anche

Funzioni
Macro di controlli compositi