共用方式為


IAccessible::accNavigate 方法 (oleacc.h)

IAccessible::accNavigate 方法會周遊至容器內的另一個 UI 元素,並擷取 物件。 這個方法是一個選擇項目。

注意accNavigate 方法已被取代,不應使用。 客戶端應該使用其他方法和屬性,例如 AccessibleChildrenget_accChildget_accParentIEnumVARIANT
 

語法

HRESULT accNavigate(
  [in]          long    navDir,
  [in]          VARIANT varStart,
  [out, retval] VARIANT *pvarEndUpAt
);

參數

[in] navDir

類型: long

指定要巡覽的方向。 這個方向是 空間 順序,例如左或右,或 邏輯 順序,例如下一個或上一個。 這個值是其中一個 導覽常數

[in] varStart

類型: VARIANT

指定巡覽的起始對像是物件本身還是其中一個物件的子系。 此參數CHILDID_SELF (从对象) 或子標識碼 (從其中一個物件的子元素) 開始。 如需初始化 VARIANT 的詳細資訊,請參閱 如何在參數中使用子標識碼

[out, retval] pvarEndUpAt

類型: VARIANT*

[out, retval]接收目的地對象相關信息的 VARIANT 結構位址。 下表描述 pvarEnd 中傳回的資訊。

vt 成員 值成員
VT_EMPTY
無。 指定的方向沒有UI元素。
VT_I4
lVal 包含 UI 元素的子標識碼。
VT_DISPATCH
pdispVal 包含 UI 元素 IDispatch 的位址。

傳回值

類型: HRESULT

如果成功,則傳回 S_OK。

如果未成功,則會傳回下表中的其中一個值,或另一個標準 COM 錯誤碼。 伺服器會傳回這些值,但客戶端必須一律檢查輸出參數,以確保它們包含有效的值。 如需詳細資訊,請參閱 檢查 IAccessible 傳回值 和傳回值。

錯誤 Description
S_FALSE
在指定的方向中找不到任何畫面元素。
DISP_E_MEMBERNOTFOUND
物件不支援這個方法。
E_INVALIDARG
引數無效。

備註

瀏覽和邏輯一律受限於容器內的UI元素。 透過空間流覽,用戶端只會流覽至起始物件的同層級, (varStart) 。 根據與邏輯導覽搭配使用的導覽旗標,用戶端會巡覽至子系或起始物件的同層級。

accNavigate 方法會擷取具有已定義螢幕位置的 UI 元素,以及沒有已定義螢幕位置的不可見物件。

這個方法不會變更選取範圍或焦點。 若要變更焦點或選取物件,請使用 IAccessible::accSelect

若要避免在周遊螢幕元素時迴圈, accNavigate 會在您在最後一個專案上指定 NAVDIR_NEXT 或第一個元素上的 NAVDIR_PREVIOUS 時傳回S_FALSE VT_EMPTY。

如同其他 IAccessible 方法和函式,用戶端可能會因為用戶動作而收到 IAccessible 介面指標的錯誤。 如需詳細資訊,請參閱 接收 IAccessible 介面指標的錯誤

某些系統定義的UI元素,例如功能表、功能表項和快捷功能表,允許流覽至不可見的物件。 不過,其他系統定義的UI元素不支援此功能。 伺服器可以選擇是否支援巡覽至不可見的物件,也可以略過或公開它們。

用戶端應用程式在使用 accNavigate 在對象之間巡覽時,必須傳回進程後傳回值。 後續處理步驟的目標是要為用戶端提供 IAccessible 介面指標和子標識碼,讓他們可以使用 UI 元素的 IAccessible 方法和屬性。

下表根據下列準則描述 IAccessible::accNavigate 的可能案例:

  • 定義起點 (您從完整物件或簡單元素開始)
  • 傳回的結果 (IDispatch 或VT_I4子標識碼)
  • 用戶端應用程式必須執行的後置處理,才能有 IAccessible 介面指標和子標識碼
針對這些數據表,假設 startIDendID 是VT_I4子標識碼, (簡單元素) ,而 pStartAccpEndAcc 則VT_I4 CHILDID_SELF (完整对象) 。

下表描述下列NAVDIR_旗標:NEXT、PREVIOUS、LEFT、RIGHT、UP 和 DOWN。 如需導覽旗標的詳細資訊,請參閱 導覽常數

起點 傳回的結果 傳回值的後續處理
pStartAcc, startID VT_I4 endID pStartAcc 上呼叫 get_accChild passing endID。 遵循 get_accChild中所述的一般程式。
pStartAcc, startID VT_DISPATCH pEndAcc 使用標準程式,將 IDispatch 介面指標轉換成 pEndAccIAccessible 介面指標。
pStartAcc,CHILDID_SELF VT_I4 endID pStartAcc 上呼叫 get_accParent,傳遞 CHILDID_SELF 以取得 endID 父代的 IAccessible 介面指標。 然後,在該 IAccessible 介面指標上呼叫get_accChild,並傳遞 endID。 遵循 get_accChild中所述的一般程式。
pStartAcc,CHILDID_SELF VT_DISPATCH pEndAcc 使用標準程式,將 IDispatch 介面指標轉換成 pEndAccIAccessible 介面指標。
 

下表說明導覽旗標 NAVDIR_FIRSTCHILDNAVDIR_LASTCHILD。 當起點是簡單元素時,它不包含流覽至第一個或最後一個子系的專案,因為簡單元素不能有子系。

起點 傳回的結果 傳回值的後續處理
pStartAcc,CHILDID_SELF VT_I4 endID pStartAcc 上呼叫 get_accChild,並傳遞 endID。 遵循 get_accChild中所述的一般程式。
pStartAcc,CHILDID_SELF VT_DISPATCH pEndAcc 使用標準程式,將 IDispatch 介面指標轉換成 pEndAccIAccessible 介面指標。
 

如需詳細資訊,請參閱 對象導覽屬性和方法

伺服器範例

下列範例顯示自定義清單框方法的可能實作,其清單專案為子專案。

// m_pControl is the control that returns this accessible object. 
// m_pStdAccessibleObject is the standard accessible object for the window 
//    that contains the control. 

HRESULT STDMETHODCALLTYPE AccServer::accNavigate( 
    long navDir,
    VARIANT varStart,
    VARIANT *pvarEndUpAt)
{
    // Default value. 
    pvarEndUpAt->vt = VT_EMPTY;

    if (varStart.vt != VT_I4)
    {
        return E_INVALIDARG;
    }

    switch (navDir)
    {
    case NAVDIR_FIRSTCHILD:
        if (varStart.lVal == CHILDID_SELF)
        {
            pvarEndUpAt->vt = VT_I4;
            pvarEndUpAt->lVal = 1;
        }
        else  // Starting with child. 
        {
            return S_FALSE;
        }
        break;

    case NAVDIR_LASTCHILD:
        if (varStart.lVal == CHILDID_SELF)
        {
            pvarEndUpAt->vt = VT_I4;
            pvarEndUpAt->lVal = m_pControl->GetCount();
        }
        else  // Starting with child.           
        {
            return S_FALSE;
        }
        break;

    case NAVDIR_NEXT:   
    case NAVDIR_DOWN:
        if (varStart.lVal != CHILDID_SELF)
        {
            pvarEndUpAt->vt = VT_I4;
            pvarEndUpAt->lVal = varStart.lVal + 1;
            // Out of range. 
            if (pvarEndUpAt->lVal > m_pControl->GetCount())
            {
                pvarEndUpAt->vt = VT_EMPTY;
                return S_FALSE;
            }
        }
        else  // Call through to method on standard object. 
        {
            return m_pStdAccessibleObject->accNavigate(navDir, varStart, pvarEndUpAt);
        }
        break;

    case NAVDIR_PREVIOUS:
    case NAVDIR_UP:
        if (varStart.lVal != CHILDID_SELF)
        {
            pvarEndUpAt->vt = VT_I4;
            pvarEndUpAt->lVal = varStart.lVal - 1;
            // Out of range. 
            if (pvarEndUpAt->lVal <1)
            {
                pvarEndUpAt->vt = VT_EMPTY;
                return S_FALSE;
            }
        }
        else  // Call through to method on standard object. 
        {
            return m_pStdAccessibleObject->accNavigate(navDir, varStart, pvarEndUpAt);
        }
        break;

     // Unsupported directions. 
    case NAVDIR_LEFT:
    case NAVDIR_RIGHT:
        if (varStart.lVal == CHILDID_SELF)
        {
            return m_pStdAccessibleObject->accNavigate(navDir, varStart, pvarEndUpAt);
        }
        else 
        {
            pvarEndUpAt->vt = VT_EMPTY;
            return S_FALSE;
        }
        break;
    }
    return S_OK;
};


規格需求

需求
最低支援的用戶端 Windows 2000 專業版 [僅限傳統型應用程式]
最低支援的伺服器 Windows Server 2003 [僅限傳統型應用程式]
目標平台 Windows
標頭 oleacc.h
程式庫 Oleacc.lib
Dll Oleacc.dll
可轉散發套件 sp6 和更新版本和 Windows 95 Windows NT 4.0 上的 Active Accessibility 1.3 RDK

另請參閱

IAccessible

IAccessible::accSelect

IDispatch

對象導覽屬性和方法

變異