Controllo applicazione

Articolo
10/12/2023

OLE richiede un controllo sostanziale sulle applicazioni e sui relativi oggetti. Le DLL di sistema OLE devono essere in grado di avviare e rilasciare automaticamente applicazioni, coordinare la produzione e la modifica degli oggetti e così via. Le funzioni di questo argomento soddisfano tali requisiti. Oltre a essere chiamato dalle DLL di sistema OLE, queste funzioni devono talvolta essere chiamate anche dalle applicazioni.

Controllo applicazione

Nome	Descrizione
AfxOleCanExitApp	Indica se l'applicazione può terminare.
AfxOleGetMessageFilter	Recupera il filtro messaggi corrente dell'applicazione.
AfxOleGetUserCtrl	Recupera il flag corrente del controllo utente.
AfxOleSetUserCtrl	Imposta o cancella il flag di controllo utente.
AfxOleLockApp	Incrementa il conteggio globale del framework del numero di oggetti attivi in un'applicazione.
AfxOleLockControl	Blocca la class factory del controllo specificato.
AfxOleUnlockApp	Decrementa il conteggio del framework del numero di oggetti attivi in un'applicazione.
AfxOleUnlockControl	Sblocca la class factory del controllo specificato.
AfxOleRegisterServerClass	Registra un server nel Registro di sistema OLE.
AfxOleSetEditMenu	Implementa l'interfaccia utente per il comando typename Object.

AfxOleCanExitApp

Indica se l'applicazione può terminare.

BOOL AFXAPI AfxOleCanExitApp();

Valore restituito

Diverso da zero se l'applicazione può essere chiusa; in caso contrario, 0.

Osservazioni:

Un'applicazione non deve terminare se sono presenti riferimenti a oggetti in attesa. Le funzioni globali AfxOleLockApp e AfxOleUnlockApp rispettivamente incrementano e decrementano un contatore di riferimenti agli oggetti dell'applicazione. L'applicazione non deve terminare quando questo contatore è diverso da zero. Se il contatore è diverso da zero, quando l'utente sceglie Chiudi dal menu di sistema o Esci dal menu File la finestra principale dell'applicazione viene nascosta (non eliminata definitivamente). Il framework chiama questa funzione in CFrameWnd::OnClose.

Esempio

// Helper exit function for automation server
BOOL CMainFrame::CanExit()
{
   if (AfxOleCanExitApp())
   {
      // No outstanding object counts - go ahead and exit
      return TRUE;
   }
   else
   {
      // There are outstanding OLE object counts...
      // hide app to give user impression that application has exited.
      ShowWindow(SW_HIDE);
      // take user out of control of the app
      AfxOleSetUserCtrl(FALSE);
      return FALSE;
   }
}

Requisiti

Intestazione: afxdisp.h

AfxOleGetMessageFilter

Recupera il filtro messaggi corrente dell'applicazione.

COleMessageFilter* AFXAPI AfxOleGetMessageFilter();

Valore restituito

Puntatore al filtro messaggi corrente.

Osservazioni:

Chiamare questa funzione per accedere all'oggetto derivato da COleMessageFilter corrente, in modo analogo a come si utilizza AfxGetApp per accedere all'oggetto applicazione corrente.

Esempio

COleMessageFilter *pFilter = AfxOleGetMessageFilter();
ASSERT_VALID(pFilter);
pFilter->BeginBusyState();
// do things requiring a busy state
pFilter->EndBusyState();

// Another example
//CWinApp-derived class
BOOL CCMFCAutomationApp::InitInstance()
{
   CWinApp::InitInstance();

   // Initialize OLE libraries
   if (!AfxOleInit())
   {
      AfxMessageBox(IDP_OLE_INIT_FAILED);
      return FALSE;
   }

   CWinThread *pThread = AfxGetThread();
   if (pThread != NULL)
   {
      // Destroy message filter, thereby unregistering it.
      delete pThread->m_pMessageFilter;
      pThread->m_pMessageFilter = NULL;

      // Create the new message filter object.
      //CMyMessageFilter is derived from COleMessageFilter
      pThread->m_pMessageFilter = new CMyMessageFilter;
      ASSERT(AfxOleGetMessageFilter() != NULL);

      // Register the new message filter object.
      AfxOleGetMessageFilter()->Register();
   }
   //...
   //...
   //...
}

Requisiti

Intestazione: afxwin.h

AfxOleGetUserCtrl

Recupera il flag corrente del controllo utente.

BOOL AFXAPI AfxOleGetUserCtrl();

Valore restituito

Diverso da zero se l'utente controlla l'applicazione; in caso contrario, 0.

Osservazioni:

L'utente controlla l'applicazione quando apre o crea in modo esplicito un nuovo documento. L'utente controlla inoltre l'applicazione se l'applicazione non è stata avviata dalle DLL del sistema OL, in altre parole se l'utente ha avviato l'applicazione con la shell di sistema.

Requisiti

Intestazione: afxdisp.h

AfxOleSetUserCtrl

Imposta o cancella il flag di controllo utente, illustrato nel riferimento per AfxOleGetUserCtrl.

void AFXAPI AfxOleSetUserCtrl(BOOL bUserCtrl);

Parametri

bUserCtrl
Specifica se il flag di controllo utente deve essere impostato o cancellato.

Osservazioni:

Il framework chiama questa funzione quando l'utente crea o carica un documento, ma non quando un documento viene caricato o creato tramite un'azione indiretta, ad esempio il caricamento di un oggetto incorporato da un'applicazione contenitore.

Chiamare questa funzione se altre azioni nell'applicazione devono mettere l'utente sotto controllo dell'applicazione.

Requisiti

Intestazione: afxdisp.h

AfxOleLockApp

Incrementa il conteggio globale del framework del numero di oggetti attivi nell'applicazione.

void AFXAPI AfxOleLockApp();

Osservazioni:

Il framework mantiene un conteggio del numero di oggetti attivi in un'applicazione. Le AfxOleLockApp funzioni e AfxOleUnlockApp , rispettivamente, incrementa e decrementa questo conteggio.

Quando l'utente tenta di chiudere un'applicazione con oggetti attivi, un'applicazione per cui il conteggio degli oggetti attivi è diverso da zero, il framework nasconde l'applicazione dalla visualizzazione dell'utente anziché chiuderla completamente. La AfxOleCanExitApp funzione indica se l'applicazione può terminare.

Chiamare AfxOleLockApp da qualsiasi oggetto che espone le interfacce OLE, se sarebbe indesiderato che tale oggetto venga eliminato definitivamente mentre è ancora in uso da un'applicazione client. Chiamare AfxOleUnlockApp anche nel distruttore di qualsiasi oggetto che chiama AfxOleLockApp nel costruttore. Per impostazione predefinita, COleDocument (e le classi derivate) bloccano e sbloccano automaticamente l'applicazione.

Esempio

// Below is a code sample from an  Application Wizard-generated SDI
// Application with Automation support. The Application Wizard adds a
// dispatch interface to the document class. AfxOleLockApp() and
// AfxOleUnlockApp() respectively increment and decrement the
// application's object count. When the object count is equal to
// zero and if the user has not taken control of the application,
// the server is terminated.

CCMFCAutomationDoc::CCMFCAutomationDoc()
{
   EnableAutomation();
   AfxOleLockApp();
}

CCMFCAutomationDoc::~CCMFCAutomationDoc()
{
   AfxOleUnlockApp();
}

Requisiti

Intestazione: afxdisp.h

AfxOleUnlockApp

Decrementa il numero di oggetti attivi del framework nell'applicazione.

void AFXAPI AfxOleUnlockApp();

Osservazioni:

Per altre informazioni, vedere AfxOleLockApp .

Quando il numero di oggetti attivi raggiunge zero, AfxOleOnReleaseAllObjects viene chiamato .

Esempio

Vedere l'esempio per AfxOleLockApp.

Requisiti

Intestazione: afxdisp.h

AfxOleLockControl

Blocca la class factory del controllo specificato in modo che i dati creati dinamicamente associati al controllo rimangano in memoria.

Sintassi

BOOL AFXAPI AfxOleLockControl(  REFCLSID clsid  );
BOOL AFXAPI AfxOleLockControl( LPCTSTR lpszProgID );

Parametri

clsid
ID univoco della classe del controllo.

lpszProgID
ID univoco del programma del controllo.

Valore restituito

Diverso da zero se la class factory del controllo è stata bloccata con successo; in caso contrario, 0.

Osservazioni:

Ciò può accelerare notevolmente la visualizzazione dei comandi. Ad esempio, una volta creato un controllo in una finestra di dialogo e bloccato il controllo con AfxOleLockControl, non è necessario crearlo e interromperne l'esecuzione ogni volta che la finestra di dialogo viene visualizzata o viene terminata in modo permanente. Se l'utente apre e chiude una finestra di dialogo ripetutamente, il blocco dei controlli può migliorare significativamente le prestazioni. Quando si è pronti per eliminare il controllo in modo permanente, chiamare AfxOleUnlockControl.

Esempio

// Starts and locks control's (Microsoft Calendar) class factory.
// Control will remain in memory for lifetime of
// application or until AfxOleUnlockControl() is called.

AfxOleLockControl(_T("MSCAL.Calendar"));

Requisiti

Intestazione: afxwin.h

AfxOleRegisterServerClass

Questa funzione consente di registrare il server nel Registro di sistema OLE.

BOOL AFXAPI AfxOleRegisterServerClass(
    REFCLSID clsid,
    LPCTSTR lpszClassName,
    LPCTSTR lpszShortTypeName,
    LPCTSTR lpszLongTypeName,
    OLE_APPTYPE nAppType = OAT_SERVER,
    LPCTSTR* rglpszRegister = NULL,
    LPCTSTR* rglpszOverwrite = NULL);

Parametri

clsid
Riferimento all'ID classe OLE del server.

lpszClassName
Puntatore a una stringa contenente il nome della classe degli oggetti del server.

lpszShortTypeName
Puntatore a una stringa contenente il nome breve del tipo di oggetto del server, ad esempio "Chart".

lpszLongTypeName
Puntatore a una stringa contenente il nome lungo del tipo di oggetto del server, ad esempio "Grafico di Microsoft Excel 5.0".

nAppType
Valore, tratto dall'enumerazione OLE_APPTYPE, specificando il tipo di applicazione OLE. I valori possibili sono i seguenti:

OAT_INPLACE_SERVER Server ha un'interfaccia utente server completa.
OAT_SERVER Server supporta solo l'incorporamento.
OAT_CONTAINER Contenitore supporta i collegamenti agli incorporamenti.
IDispatchOAT_DISPATCH_OBJECT oggetto con supporto.

rglpszRegister
Matrice di puntatori a stringhe che rappresentano le chiavi e i valori da aggiungere al Registro di sistema OLE se non vengono trovati valori esistenti per le chiavi.

rglpszOverwrite
Matrice di puntatori a stringhe che rappresentano le chiavi e i valori da aggiungere al Registro di sistema OLE se il Registro di sistema contiene valori esistenti per le chiavi indicate.

Valore restituito

Diverso da zero se la classe server è stata registrata correttamente; in caso contrario, 0.

Osservazioni:

La maggior parte delle applicazioni può usare COleTemplateServer::Register per registrare i tipi di documento dell'applicazione. Se il formato del Registro di sistema dell'applicazione non rientra nel modello tipico, è possibile usare AfxOleRegisterServerClass per un maggiore controllo.

Il Registro di sistema è costituito da un set di chiavi e valori. Gli argomenti rglpszRegister e rglpszOverwrite sono matrici di puntatori alle stringhe, ognuno costituito da una chiave e da un valore separato da un carattere NULL ( '\0'). Ognuna di queste stringhe può avere parametri sostituibili le cui posizioni sono contrassegnate dalle sequenze di caratteri da %1 a %5.

I simboli vengono compilati nel modo seguente:

Simbolo	Valore
%1	ID classe, formattato come stringa
2%	Nome classe
%3	Percorso del file eseguibile
4%	Nome di tipo breve
%5	Nome tipo lungo

Requisiti

Intestazione: afxdisp.h

AfxOleSetEditMenu

Implementa l'interfaccia utente per il comando typename Object.

void AFXAPI AfxOleSetEditMenu(
    COleClientItem* pClient,
    CMenu* pMenu,
    UINT iMenuItem,
    UINT nIDVerbMin,
    UINT nIDVerbMax = 0,
    UINT nIDConvert = 0);

Parametri

pClient
Puntatore all'elemento OLE client.

pMenu
Puntatore all'oggetto menu da aggiornare.

iMenuItem
Indice della voce di menu da aggiornare.

nIDVerbMin
ID comando che corrisponde al verbo primario.

nIDVerbMax
ID comando corrispondente all'ultimo verbo.

nIDConvert
ID per la voce di menu Converti.

Osservazioni:

Se il server riconosce solo un verbo primario, la voce di menu diventa "verbo typename Object" e il comando nIDVerbMin viene inviato quando l'utente sceglie il comando. Se il server riconosce diversi verbi, la voce di menu diventa " typename Object" e un sottomenu che elenca tutti i verbi viene visualizzato quando l'utente sceglie il comando. Quando l'utente sceglie un verbo dal sottomenu, nIDVerbMin viene inviato se viene scelto il primo verbo, nIDVerbMin + 1 viene inviato se viene scelto il secondo verbo e così via. L'implementazione predefinita COleDocument gestisce automaticamente questa funzionalità.

È necessario disporre dell'istruzione seguente nello script di risorse dell'applicazione del client (. File RC):

<#include afxolecl.rc>

Requisiti

Intestazione: afxole.h

AfxOleUnlockControl

Sblocca la class factory del controllo specificato.

Sintassi

BOOL AFXAPI AfxOleUnlockControl( REFCLSID clsid );
BOOL AFXAPI AfxOleUnlockControl( LPCTSTR lpszProgID );

Parametri

clsid
ID univoco della classe del controllo.

lpszProgID
ID univoco del programma del controllo.

Valore restituito

Diverso da zero se la class factory del controllo è stata sbloccata correttamente; in caso contrario, 0.

Osservazioni:

Un controllo è bloccato con AfxOleLockControl, in modo che i dati creati dinamicamente associati al controllo rimangano in memoria. Ciò può velocizzare notevolmente la visualizzazione del controllo perché il controllo non deve essere creato e distrutto ogni volta che viene visualizzato. Quando si è pronti per eliminare il controllo in modo permanente, chiamare AfxOleUnlockControl.

Esempio

// Unlock control's (Microsoft Calendar Control) class factory.

AfxOleUnlockControl(_T("MSCAL.Calendar"));

Requisiti

Intestazione: afxwin.h

Vedi anche

Macro e globali

Condividi tramite

Controllo applicazione