ISelectionContainer::GetObjects

Returns either all selectable objects or all selected objects, depending on the flag passed.

HRESULT GetObjects(
DWORD dwFlags,
ULONG cObjects,
IUnknown **apUnkObjects
);

Parameters

dwFlags

[in] Flag specifying which objects to return, either GETOBJS_ALL or GETOBJS_SELECTED.

cObjects

[in] Number of objects returned.

apUnkObjects

[out] Pointer to an array of returned objects.

Return Values

The return value obtained from HRESULT is one of the following:

Return Value	Meaning

S_OK	Success.
E_INVALIDARG	One or more of the arguments is invalid.

Comments

The ActiveX designer implements this method.

The GetObjects method returns either all selectable objects or all selected objects, depending on the flag passed. The returned array of objects is used as the basis for SelectObjects.

The designer should pass a pointer to its extended object, rather than to itself. The extended object includes the ambient properties supplied by the host, which the user may wish to browse. The extended object is available through the site. See the COM Programmer's Reference for more information.

Because the returned objects support IDispatch, the host can obtain information directly from them. For example, to get an object's name, the host can call IDispatch::Invoke (or ITypeInfo::Invoke) with a predefined dispatch identifier (DISPID) that signifies the name. The predeclared DISPIDs are negative to ensure that they don't conflict with user-defined identifiers. The table that follows describes some of this information and how it is obtained.

Item	How it is Obtained

The name of the object.	DISPID_NAME
The index of the object.	DISPID_OBJECT
The type of the object.	IProvideClassInfo::QueryInterface

Example

The following example implements GetObjects; the returned array is used by the SelectObjects method.

STDMETHODIMP CMySelectionContainer::GetObjects
(
    DWORD dwFlags,
    ULONG cObjects, 
    IUnknown **apUnkObjects
)
{
    // Initialize the array.
    for (ULONG i = 0; i < cObjects; i++) {
        apUnkObjects[i] = NULL;
    }        

    IUnknown * pUnkUs;
    HRESULT hr;
    BOOL bUsedUnkUs = FALSE;

    // Can't pass self as an object because the user won't be 
    // able to browse ambient properties, so need to pass
    // extender. Get it from site.   
    IDispatch * pDisp = NULL;
    hr = m_pControlSite->GetExtendedControl(&pDisp);
    if (SUCCEEDED(hr)) {
        hr = pDisp->QueryInterface(IID_IUnknown, (void**)&pUnkUs);
        pDisp->Release();
    }

    if (FAILED(hr)) {
        // Can't get the extender, so use self anyway.
        pUnkUs = (IUnknown*)(ISelectionContainer*)this;
        pUnkUs -> AddRef();
    }
    
    if (GETOBJS_ALL == dwFlags) {
        ULONG x = 0;
        for (int i = 0; i < MAXOBJECTS && x < (int) cObjects; i++) {
                If (m_state.rgObjects[i].bHaveIt) {
                apUnkObjects[x] = m_state.rgObjects[i].pObject;
                apUnkObjects[x]->AddRef();
                x++;
                }
        }
    if (x < (int) cObjects) {
        apUnkObjects[x] = pUnkUs;
        bUsedUnkUs = TRUE;
        }
    }
    else { 
    // Host requested all selected objects.
    if (cObjects > 0) {
        if (m_state.iSelectedObject != -1) {    
            apUnkObjects[0] =                 
                m_state.rgCircles[m_state.iSelectedObject].pObject;
            apUnkObjects[0]->AddRef();
                }
        else {
            apUnkObjects[0] = pUnkUs;
            bUsedUnkUs = TRUE;
                }
        }
    }
    if (!bUsedUnkUs) {
        pUnkUs->Release();
    }
    return S_OK;
}