13.2 Band Object Interfaces

only for RuBoard - do not distribute or recompile

Band objects are required to implement IDeskband and IObjectWithSite . The Platform SDK says that they must also implement IPersist and IPersistStream , but this is not the case. Optionally, if the band accepts user input, it needs to implement IInputObject . Bands can also provide context menus by implementing IContextMenu . We have already discussed IObjectWithSite and IContextMenu , so basically all we need to do is get up to speed with IDeskband and IInputObject . So, let's get to it.

13.2.1 IDeskband

IDeskband , the primary interface of the band object, is derived from IDockingWindow , which, in turn , is derived from IOleWindow .

IDeskband contains only one native method: GetBandInfo . There are three methods that are inherited from IDockingWindow , and two that have been inherited from IOleWindow . We have already seen IOleWindow while discussing IShellBrowser in Chapter 11, so we will forego another discussion. Table 13.1 describes all the methods of the IDeskband interface. The methods that have been marked with an asterisk do not have to be implemented.

Table13.1. IDeskband Methods

IOleWindow
`GetWindow`	Returns the window handle to one of the windows participating in in-place activation (frame, document, parent, or in-place object window).
`ContextSensitiveHelp` *	Determines whether context-sensitive help mode should be entered during an in-place activation session.
IDockingWindow
`ShowDW`	Called when the docking window is supposed to be shown or hidden.
`CloseDW`	Called when the docking window is about to be closed.
`ResizeBorderDW` *	Notifies the docking window object that the frame's border space has changed. This method is never called for any band object.
IDeskband
`GetBandInfo`	Gets information for a band object.

13.2.1.1 ShowDW

Tells the band object to show or hide itself. Its syntax is:

 HRESULT ShowDW(BOOL bShow);

Its single parameter is:

bShow: [in] If this value is 0, the band object should be hidden; otherwise , it should be displayed.

13.2.1.2 CloseDW

Called when the band object is about to be closed. The band object should use this method to save persistent information (if necessary). Its syntax is:

 HRESULT CloseDW(DWORD dwReserved);

Its single parameter is:

dwReserved: [in] This is reserved and should always be zero.

13.2.1.3 GetBandInfo

This method retrieves band object information that includes the view mode and size of the band. Its syntax is:

 HRESULT GetBandInfo(DWORD   dwBandID   , DWORD   dwViewMode   , DESKBANDINFO*   pdbi   );

with the following parameters:

dwBandID

[in] The identifier of the band. This value is assigned by the shell.

dwViewMode

[in] The view mode of the band object, which is one of the following values:

DBIF_VIEWMODE_NORMAL: The band is being displayed horizontally.
DBIF_VIEWMODE_VERTICAL: The band is being displayed vertically.
DBIF_VIEWMODE_FLOATING: The band is floating.
DBIF_VIEWMODE_TRANSPARENT: The band is being displayed transparently .

pdbi

[in] This is a pointer to a DESKBANDINFO structure. This structure contains everything a band object will need to display itself. Its definition is:

 typedef struct {     DWORD dwMask;     POINTL ptMinSize;     POINTL ptMaxSize;     POINTL ptIntegral;     POINTL ptActual;     WCHAR wszTitle[256];     DWORD dwModeFlags;     COLORREF crBkgnd; } DESKBANDINFO;

dwMask

Contains flags that determine which members of the structure are being requested . This can be one or more of the following values:

DBIM_MINSIZE: ptMinSize is being requested.
DBIM_MAXSIZE: ptMaxSize is being requested.
DBIM_INTEGRAL: ptIntegral is being requested.
DBIM_ACTUAL: ptActual is being requested.
DBIM_TITLE: wszTitle is being requested.
DBIM_MODEFLAGS: dwModeFlags is being requested.
DBIM_BKCOLOR: crBkgnd is being requested.

ptMinSize

This is a POINTL structure (same as POINTAPI with Long members) containing the minimum size of the band object.

ptMaxSize

This is the maximum size of the band object. Like ptMinSize , this is also a POINTL structure. If there is no limit for either the x or y values, -1& should be used.

ptIntegral

This is a POINTL structure containing the sizing step of the band object. This member is only valid if dwModeFlags contains DBIMF_VARIABLEHEIGHT .

ptActual

This is a POINTL structure that contains the ideal size of the band object. This size is not guaranteed .

wszTitle

This is the title of the band object.

dwModeFlags

These flags determine the mode of operation for a band object. They can be one or more of the following values:

DBIMF_NORMAL: The band is normal and the other mode flags modify this flag.
DBIMF_VARIABLEHEIGHT: The height of the band object can be modified, and the ptIntegral member defines the increment by which the band object can be resized.
DBIMF_DEBOSSED: The band object is displayed with a sunken look.
DBIMF_BKCOLOR: The band will be displayed with the background color crBkgnd .

crBkgnd

This is the background color of the band object. This is only valid if dwModeFlags contains DBIMF_BKCOLOR .

Example 13.1 contains the IDL listing for IDeskband .

Example 13.1. IDeskband Interface

  typedef [public] long DESKBANDINFO;  [     uuid(eb0fe172-1a3a-11d0-89b3-00a0c90a90ac),     helpstring("IDeskband Interface"),     odl ] interface IDeskBand : IUnknown {     //IOleWindow     HRESULT GetWindow([out, retval] long *phWnd);     HRESULT ContextSensitiveHelp([in] boolean fEnterMode);     //IDockingWindow     HRESULT ShowDW([in] boolean fShow);     HRESULT CloseDW([in] long dwReserved);     HRESULT ResizeBorderDW([in] long prcBorder,                            [in] long punkToolbarSite,                            [in] boolean fReserved);     //IDeskBand     HRESULT GetBandInfo ([in] long dwBandID,                           [in] long dwViewMode,  [in] LPDESKBANDINFO pdbi  ); }

Notice that the DESKBANDINFO pointer in the GetBandInfo method has been redefined as a long. That's because the structure contains members that are not automation compatible. To access this parameter from VB when we implement this method, we'll have to use CopyMemory to get a local instance before we can do anything with the structure.

13.2.2 IInputObject

IInputObject is used to process accelerators and change UI activation for a band object. It contains three methods which are summarized in Table 13.2. Note that the methods marked with an asterisk more often than not do not need to be implemented.

Table13.2. IInputObject

Method	Description
`HasFocusIO` *	Determines if one of the object's windows has the keyboard focus.
`TranslateAcceleratorIO` *	Passes keyboard accelerators to the object.
`UIActivateIO`	Activates or deactivates the object.

13.2.2.1 HasFocusIO

The syntax of HasFocusIO is very simple:

 HRESULT HasFocusIO(  );

If the band object has keyboard focus this method should return S_OK ; otherwise, it should return S_FALSE .

13.2.2.2 TranslateAcceleratorIO

This method should return S_OK if the accelerator was translated; otherwise, it should return S_FALSE . Its syntax is:

 HRESULT TranslateAcceleratorIO(LPMSG   lpMsg   );

Its single parameter is:

lpMsg

[in] A pointer to a MSG structure, which is defined like so:

 typedef struct tagMSG {     HWND hwnd;     UINT message;     WPARAM wParam;     LPARAM lParam;     DWORD time;     POINT pt; } MSG;

This structure will contain the keyboard message that is being translated. Its members are defined like so:

hwnd: The handle of the window receiving the message.
message: The message number.
wParam and lParam: These parameters specify additional information about a message and are different depending on the message number.
time: The time the message was posted.
pt: A POINT structure containing the cursor position in screen coordinates at the time the message was posted.

13.2.2.3 UIActivateIO

This method is called when the band is being activated or deactivated. Its syntax is:

 HRESULT UIActivateIO(BOOL fActivate, LPMSG lpMsg);

Its parameters are:

fActivate: [in] This value is nonzero if the band is being activated; otherwise, it is zero.
lpMsg: [in] This is a pointer to a MSG structure that contains the message that caused the change in activation states.

The IDL for IInputObject is defined in Example 13.2.

Example 13.2. IInputObject Interface

 typedef [public] long LPMSG; [     uuid(68284faa-6a48-11d0-8c78-00c04fd918b4),     helpstring(("IInputObject Interface"),     odl ] interface IInputObject : IUnknown {     HRESULT UIActivateIO([in] boolean fActivate, [in] LPMSG lpMsg);     HRESULT HasFocusIO(  );     HRESULT TranslateAcceleratorIO([in] LPMSG lpMsg);

only for RuBoard - do not distribute or recompile