IDesignerToolboxSite::GetData

Returns a pointer to the currently selected item in the toolbox.

HRESULT GetData (
   IDataObject **ppdo
);

Parameter

ppdo

[in] Pointer to the data object.

Return Values

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

Comments

A designer calls the site's GetData method to find out which item in the toolbox is currently selected. In pdo, the site returns either a pointer to the item or NULL if no item is selected. GetData returns data about any ActiveX control or any other item an ActiveX designer places in the toolbox.

Designers must call methods of the IDataObject interface to parse the returned data object. (See the COM Programmer’s Reference in the Platform Software Development Kit (SDK) for more information on this interface.) The format of the object depends on the type of the corresponding toolbox object.

For toolbox items supplied by a designer, the format is CF_DESIGNERTOOLBOXITEM, which has the clipboard format name "DesignerToolboxItem". The data consists of a zero-terminated ANSI string (stored as TYMED_GLOBAL) in the following form:

Designer-class-name.toolbox-item-id

For example, MyClass.1 represents toolbox item number 1 in the MyClass designer. Toolbox item numbers begin with zero.

For an ActiveX control, the data object supports the CF_CLSID and CF_CLSIDCLASSNAME format. The CF_CLSID format consists of the object's CLSID, represented as a zero-terminated ANSI string and stored as TYMED_GLOBAL. The clipboard format string for CF_CLSID is "CLSID". The CF_CLSIDCLASSNAME format consists of the programmatic name of the control's class, such as "Button" or "Rich Text". The class name is represented as a zero-terminated ANSI string and stored as TYMED_GLOBAL. The clipboard format string for CF_CLSIDCLASSNAME is "ClsIdClassName".

Example

The following code fragment is part of a larger routine that handles designer interactions with the host's toolbox. The fragment calls the site's GetData method to get a pointer to a data object. If the call fails or the returned data object is NULL, the fragment returns the current ToolPointer (locally defined). If GetData returns a valid data object, the fragment calls another local routine (ToolFromDataObject), which parses the returned data object and returns the new ToolPointer.

   hr = m_pDesignerToolboxSite->GetData(&pdo);
   if (FAILED(hr))
      return ToolPointer;
   if (!pdo)
      return ToolPointer;
   ToolPointer = ToolFromDataObject(pdo);