應用程式控制

發行項
10/12/2023

OLE 需要對應用程式和其物件進行實質性的控制。 OLE 系統 DLL 必須能夠自動啟動和釋放應用程式、協調其生產和修改物件等等。本主題中的函式符合這些需求。除了由 OLE 系統 DLL 呼叫之外，這些函式有時也必須由應用程式呼叫。

應用程式控制

名稱	描述
AfxOleCanExitApp	指示應用程式是否可以結束。
AfxOleGetMessageFilter	擷取應用程式的目前訊息篩選器。
AfxOleGetUserCtrl	擷取目前使用者控制旗標。
AfxOleSetUserCtrl	設定或清除使用者控制項旗標。
AfxOleLockApp	遞增架構在應用程式中使用中物件的全域計數。
AfxOleLockControl	鎖定指定控制項的類別處理站。
AfxOleUnlockApp	遞減架構在應用程式中使用中物件的計數。
AfxOleUnlockControl	解除鎖定指定控制項的類別處理站。
AfxOleRegisterServerClass	在 OLE 系統登錄中註冊伺服器。
AfxOleSetEditMenu	實作 typename Object 命令的使用者介面。

AfxOleCanExitApp

指示應用程式是否可以結束。

BOOL AFXAPI AfxOleCanExitApp();

傳回值

如果應用程式可結束則非零，否則為 0。

備註

如果對應用程式物件有未完成的參考，則不應該結束。全域函式 AfxOleLockApp 和 AfxOleUnlockApp 分別會遞增和遞減應用程式物件的參考計數。這個計數器為非零值時，應用程式不應該結束。如果計數器是非零值，當使用者從 [系統] 功能表選擇 [關閉]，或從 [檔案] 功能表選擇 [結束] 時，應用程式的主視窗將會隱藏 (不會終結)。架構會在中 CFrameWnd::OnClose 呼叫此函式。

範例

// 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;
   }
}

需求

標頭： afxdisp.h

AfxOleGetMessageFilter

擷取應用程式的目前訊息篩選器。

COleMessageFilter* AFXAPI AfxOleGetMessageFilter();

傳回值

指向目前訊息篩選器的指標。

備註

就像您會呼叫 COleMessageFilter 來存取目前應用程式物件一般，請呼叫這個函式來存取目前的 AfxGetApp 衍生物件。

範例

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();
   }
   //...
   //...
   //...
}

需求

標題: afxwin.h

AfxOleGetUserCtrl

擷取目前使用者控制旗標。

BOOL AFXAPI AfxOleGetUserCtrl();

傳回值

如果使用者在控制應用程式則為非零；否則為 0。

備註

當使用者具有已明確開啟或建立的新文件時，應用程式是在使用者的控制之下。如果應用程式不是由 OLE 系統 DLL 啟動，也就是說如果使用者是使用系統殼層啟動應用程式，表示仍然在使用者的控制之下。

需求

標頭： afxdisp.h

AfxOleSetUserCtrl

會設定或清除使用者控制項旗標，其會在的 AfxOleGetUserCtrl 參考中說明。

void AFXAPI AfxOleSetUserCtrl(BOOL bUserCtrl);

參數

bUserCtrl
指定要設定或清除使用者控制項旗標。

備註

當使用者建立或載入檔時，架構會呼叫此函式，但不是透過間接動作載入或建立檔時，例如從容器應用程式載入内嵌物件。

如果您的應用程式中的其他動作應該讓使用者控制應用程式，請呼叫此函式。

需求

標頭： afxdisp.h

AfxOleLockApp

遞增架構在應用程式中使用中物件的全域計數。

void AFXAPI AfxOleLockApp();

備註

架構會保留應用程式中使用中物件的計數。和 AfxOleUnlockApp 函 AfxOleLockApp 式分別遞增和遞減此計數。

當使用者嘗試關閉具有作用中物件的應用程式時，此應用程式是非零的作用中物件計數，架構會隱藏使用者檢視中的應用程式，而不是完全關閉應用程式。函 AfxOleCanExitApp 式指出應用程式是否可以終止。

從公開 OLE 介面的任何物件呼叫 AfxOleLockApp ，如果用戶端應用程式仍在使用時，該物件將會遭到終結，則為。也會在 AfxOleUnlockApp 建構函式中呼叫之任何物件的解構函式中呼叫 AfxOleLockApp 。根據預設， COleDocument （和衍生類別）會自動鎖定和解除鎖定應用程式。

範例

// 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();
}

需求

標頭： afxdisp.h

AfxOleUnlockApp

遞減應用程式中使用中物件的架構計數。

void AFXAPI AfxOleUnlockApp();

備註

如需詳細資訊，請參閱 AfxOleLockApp 。

當使用中物件的數目達到零時， AfxOleOnReleaseAllObjects 就會呼叫。

範例

請參閱 AfxOleLockApp 的範例。

需求

標頭： afxdisp.h

AfxOleLockControl

鎖定指定控制項的 Class Factory，以便動態建立與記憶體中保留之控制項相關聯的資料。

語法

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

參數

Clsid
控制項的唯一類別 ID。

lpszProgID
控制項的唯一程式 ID。

傳回值

如果已順利鎖定控制項的 Class Factory 則為非零值；否則為 0。

備註

這可大幅提升控制項的顯示速度。例如，當您在對話方塊中建立控制項並使用 AfxOleLockControl 鎖定控制項時，就不需要每次在對話方塊顯示或終止時建立和刪除該控制項。如果使用者重複開啟和關閉對話方塊，鎖定您的控制項可以大幅提升效能。當您準備終結控制項時，請呼叫 AfxOleUnlockControl。

範例

// 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"));

需求

標題: afxwin.h

AfxOleRegisterServerClass

此函式可讓您在 OLE 系統登錄中註冊伺服器。

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

參數

Clsid
伺服器的 OLE 類別識別碼參考。

lpszClassName
字串的指標，其中包含伺服器物件的類別名稱。

lpszShortTypeName
字串的指標，其中包含伺服器物件類型的簡短名稱，例如「Chart」。

lpszLongTypeName
字串的指標，其中包含伺服器物件類型的長名稱，例如「Microsoft Excel 5.0 Chart」。

nAppType
值，取自OLE_APPTYPE列舉，指定 OLE 應用程式的型別。可能的值為下列各項：

OAT_INPLACE_SERVER Server 具有完整的伺服器使用者介面。
OAT_SERVER Server 僅支援內嵌。
OAT_CONTAINER Container 支援內嵌的連結。
IDispatchOAT_DISPATCH_OBJECT支援的物件。

rglpszRegister
字串的指標陣列，如果找不到索引鍵的現有值，表示要新增至 OLE 系統登錄的索引鍵和值。

rglpszOverwrite
字串的指標陣列，如果登錄包含指定機碼的現有值，則表示要加入至 OLE 系統登錄的索引鍵和值。

傳回值

如果伺服器類別成功註冊，則為非零;否則為 0。

備註

大部分的應用程式都可以使用 COleTemplateServer::Register 來註冊應用程式的檔案類型。如果您的應用程式的系統登錄格式不符合一般模式，您可以使用 AfxOleRegisterServerClass 來進行更多控制。

登錄包含一組機碼和值。 rglpszRegister 和 rglpszOverwrite 引數是字串指標的陣列，每個指標都是由索引鍵和以 Null 字元分隔的值 所組成。 '\0' 每個字串都可以有可取代的參數，其位置會以字元序列 %1 到 %5 標記。

符號會填入，如下所示：

符號	值
%1	類別識別碼，格式化為字串
2%	類別名稱
3%	可執行檔的路徑
4%	簡短類型名稱
5%	長型別名稱

需求

標頭： afxdisp.h

AfxOleSetEditMenu

實作 typename Object 命令的使用者介面。

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

參數

pClient
用戶端 OLE 專案的指標。

pMenu
要更新之功能表物件的指標。

iMenuItem
要更新之功能表項目的索引。

nIDVerbMin
對應至主要動詞命令的命令識別碼。

nIDVerbMax
對應至最後一個動詞命令的命令識別碼。

nIDConvert
[轉換] 功能表項目的識別碼。

備註

如果伺服器只辨識主要動詞，功能表項目會變成「verb typename Object」，當使用者 選擇命令時，就會傳送 nIDVerbMin 命令。如果伺服器辨識數個動詞，則功能表項目會變成「 typename Object」，而當使用者選擇命令時，就會顯示列出所有動詞的子功能表。當使用者從子功能表選擇動詞時， 如果選擇第一個動詞， 則會傳送 nIDVerbMin + 1，如果選擇第二個動詞動詞，則會傳送 nIDVerbMin + 1，依此類推。預設 COleDocument 實作會自動處理這項功能。

您必須在用戶端的應用程式資源腳本中具有下列語句。。RC）檔案：

<#include afxolecl.rc>

需求

標頭：afxole.h

AfxOleUnlockControl

解除鎖定指定控制項的類別處理站。

語法

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

參數

Clsid
控制項的唯一類別 ID。

lpszProgID
控制項的唯一程式 ID。

傳回值

如果控制項的類別處理站成功解除鎖定，則為非零;否則為 0。

備註

控制項會鎖定， AfxOleLockControl 讓與控制項相關聯的動態建立資料保留在記憶體中。這可以大幅加快控制項的顯示速度，因為每次顯示控制項時都不需要建立和終結。當您準備終結控制項時，請呼叫 AfxOleUnlockControl。

範例

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

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

需求

標題: afxwin.h

另請參閱

宏和全域

共用方式為

應用程式控制