Export (0) Print
Expand All

IOleInPlaceSiteWindowless interface

Extends the IOleInPlaceSiteEx interface. IOleInPlaceSiteWindowless works with IOleInPlaceObjectWindowless which is implemented on the windowless object. Together, these two interfaces provide services to a windowless object from its container allowing the windowless object to:

  • Process window messages
  • Participate in drag and drop operations
  • Perform drawing operations

Having a window can place unnecessary burdens on small objects, such as controls. It prevents an object from being non-rectangular. It prevents windows from being transparent. It prevents the small instance size needed by many small controls.

A windowless object can enter the in-place active state without requiring a window or the resources associated with a window. Instead, the object's container provides the object with many of the services associated with having a window.

When to implement

Implement this interface on the container's site object to support windowless objects.

When to use

The windowless object calls the methods in this interface to process window messages, to participate in drag and drop operations, and to perform drawing operations.

Members

The IOleInPlaceSiteWindowless interface inherits from IOleInPlaceSiteEx. IOleInPlaceSiteWindowless also has these types of members:

Methods

The IOleInPlaceSiteWindowless interface has these methods.

MethodDescription
AdjustRect

Adjusts a specified rectangle if it is entirely or partially covered by overlapping, opaque objects.

CanWindowlessActivate

Informs an object if its container can support it as a windowless object that can be in-place activated.

GetCapture

Called by an in-place active, windowless object to determine whether it still has the mouse capture.

GetDC

Provides an object with a handle to a device context for a screen or compatible device from its container.

GetFocus

Called by an in-place active, windowless object to determine whether it still has the keyboard focus.

InvalidateRect

Enables an object to invalidate a specified rectangle of its in-place image on the screen.

InvalidateRgn

Enables an object to invalidate a specified region of its in-place image on the screen.

OnDefWindowMessage

Invokes the default processing for all messages passed to an object.

ReleaseDC

Releases the device context previously obtained by a call to IOleInPlaceSiteWindowless::GetDC.

ScrollRect

Enables an object to scroll an area within its in-place active image on the screen.

SetCapture

Enables an in-place active, windowless object to capture all mouse messages.

SetFocus

Sets the keyboard focus for a UI-active, windowless object.

 

Windowless Object Model

Windowless objects are an extension of normal compound document objects. They follow the same in-place activation model and share the same definitions for the various OLE states, with the difference that they do not consume a window when they enter the in-place and UI active states. They are required to comply with the OLE compound document specification, including in-place and UI activation.

Windowless objects require special support from their container. In other words, the container has to be specifically written to support this new kind of object. However, windowless objects are backward compatible with down level containers. In such containers, they simply create a window when active and behave as a normal compound document object.

As with other compound document objects, windowless objects need to be in-place active to get mouse and keyboard messages. In fact, since an object needs to have the keyboard focus to receive keyboard messages, and having the keyboard focus implies being UI active for an object, only UI active objects will actually get keyboard messages. Non-active objects can still process keyboard mnemonics.

Since windowless objects do not have a window, they rely on their container to receive window messages for them. The container dispatches its own window messages to the appropriate embedded, windowless object through calls to the IOleInPlaceObjectWindowless methods. Similarly, windowless objects can obtain services from their container such as capturing the mouse, setting the focus, getting a device context in which to paint, and so on. The control calls IOleInPlaceSiteWindowless methods. In addition, the container is responsible for drawing any border hatching as well as the grab handles for the control.

These two interfaces are derived from existing interfaces. By extending existing interfaces rather than creating new ones, no new VTable pointer is added to the object instance, helping to keep the instance size small.

Client and Server Negotiations with Windowless Objects

When a windowless object gets in-place activated, it should query its site for the IOleInPlaceSiteWindowless interface. If this interface is supported, the object calls IOleInPlaceSiteWindowless::CanWindowlessActivate to determine if it can proceed and in-place activate without a window.

If the container does not support IOleInPlaceSiteWindowless or if the IOleInPlaceSiteWindowless::CanWindowlessActivate method returns S_FALSE, the windowless object should behave like a normal compound document object and create a window.

The container can get the window handle for an embedded object by calling IOleWindow::GetWindow. This method should fail (return E_FAIL) for a windowless object. However, a container cannot be sure that the object is windowless by calling this method. The object may have a window but may not have created it yet. Many existing objects only create their window after calling the OnInPlaceActivate method on their site object.

Consequently, a windowless object must call the new IOleInPlaceSiteEx::OnInPlaceActivateEx method on its site object, instead of OnInPlaceActivate. The dwFlags parameter for this new method contains additional information in the ACTIVATEFLAGS enumeration. The ACTIVATE_WINDOWLESS enumeration value indicates that the object is activated without a window. Containers can cache this value instead of calling the GetWindow method on the IOleWindow interface repeatedly.

Message Dispatching

Windowless objects rely on their containers to dispatch window messages to them, capture the mouse, and get the keyboard focus. The container calls IOleInPlaceObject::OnWindowMessage to dispatch a window message to a windowless object. This method is similar to the SendMessage function except that it does not require an HWND parameter and it returns both an HRESULT and a LRESULT value.

A windowless object must not call the DefWindowProc function directly. Instead, it calls IOleInPlaceSiteWindowless::OnDefWindowMessage to invoke the default action, for example with WM_SETCURSOR or WM_HELP that should be propagated back up to the container. Thus, the container has a chance to handle the message before the object processes it.

For mouse messages, the object calls IOleInPlaceSiteWindowless::SetCapture to obtain the mouse capture and IOleInPlaceSiteWindowless::SetFocus to get the keyboard focus.

A windowless object handles accelerators and mnemonics as follows:

Accelerators

The UI active object checks for its own accelerators in IOleInPlaceActiveObject::TranslateAccelerator. A windowless object does the same. However, a windowless object cannot send a WM_COMMAND message to itself, as a windowed object would do. Therefore, instead of translating the key to a command, a windowless object should simply process the key right away.

Except for that one difference, windowless objects should implement the IOleInPlaceActiveObject::TranslateAccelerator method as defined in the OLE specifications. In particular, a windowless object should pass the accelerator message up to its site object if it does not wish to handle it. The windowless object and returns S_OK if the message got translated and S_FALSE if not. In the case of a windowless object, the message is processed instead of translated. Non translated messages will come back to the object through the IOleInPlaceObjectWindowless::OnWindowMessage method.

Note that because the container's window gets all keyboard input, a UI active object should look for messages sent to that window to find those it needs to process in its IOleInPlaceActiveObject::TranslateAccelerator method. An object can get its container's window by calling IOleWindow::GetWindow.

Note that because the container's window gets all keyboard input, a UI active object should look for messages sent to that window to find those it needs to process in its IOleInPlaceActiveObject::TranslateAccelerator method. An object can get its container's window by calling IOleWindow::GetWindow.

Mnemonics

Control mnemonics are handled the same way whether the control is windowless or not. The container gets the control mnemonic table by calling IOleControl::GetControlInfo and then calls IOleControl::OnMnemonic when it receives a key combination that matches a control mnemonic.

Drag and Drop Onto Windowless Objects

Since a windowless object does not have a window when it is active, it cannot register its own IDropTarget interface with the RegisterDragDrop function. However, to participate in drag and drop operations, a windowless object still must implement this interface. The object supplies its container with a pointer to its IDropTarget interface through IOleInPlaceObjectWindowless::GetDropTarget instead of having the container call QueryInterface for it. See IOleInPlaceObjectWindowless::GetDropTarget for more information on drag and drop operations involving windowless objects.

In-place Drawing for Windowless Objects

With windowed objects, the container is only responsible for drawing the object when it is inactive. Windowed objects have their own window when they are active and can draw themselves independently of their container.

A windowless object, however, needs services from its container to redraw itself even when it is active. The container must provide the object with information about its surrounding environment, such as the clipping region, the background, overlapping objects in front of the object being redrawn, and a device context in which to draw.

The IOleInPlaceSiteWindowless interface on the container's site object provides these services: drawing the object, obtaining and releasing the device context, invalidating the object's on-screen display, scrolling the object, or showing a caret when the object is active.

Note  All methods of IOleInPlaceSiteWindowless take position information in client coordinates of the containing window, that is, the window in which the object is being drawn.

Drawing Windowless Objects

To maintain compatibility with windowed objects, the container still uses IViewObject::Draw to redraw the in-place active, windowless object.

Obtaining and Releasing a Device Context

To draw on its own when in-place active, a windowless object must call its site's IOleInPlaceSiteWindowless::GetDC method to get a device context in which to draw. Then, it draws into the device context and releases it by calling IOleInPlaceSiteWindowless::ReleaseDC.

Display Invalidation

In-place windowless objects may need to invalidate regions of their on-screen image. Even though the notification methods in IAdviseSinkEx can be used for that purpose, they are not ideal for in-place active objects because they take HIMETRIC coordinates. In order to simplify and speed up in-place drawing, the InvalidateRect and InvalidateRgn methods in the IOleInPlaceSiteWindowless interface provide the same functionality.

An object cannot call the Windows API functions InvalidateRect and InvalidateRgn directly on the window handle it gets from calling IOleInPlaceSiteWindowless::GetWindow on its site.

Scrolling

In-place active windowless objects may need to scroll a given rectangle of their on-screen image, for example, with a multi-line text control. Because of transparent and overlapping objects, the Windows API functions ScrollWindow and ScrollDC cannot be used. Instead, the IOleInPlaceSiteWindowless::ScrollRect method enables objects to perform scrolling.

Caret Support

A windowless object cannot safely show a caret without first checking whether the caret is partially or totally hidden by overlapping objects. To make that possible, an object can submit a rectangle to its site object when it calls the site's IOleInPlaceSiteWindowless::AdjustRect method to get a specified rectangle adjusted (usually, reduced) to ensure the rectangle fits in the clipping region.

Requirements

Minimum supported client

Windows 2000 Professional [desktop apps only]

Minimum supported server

Windows 2000 Server [desktop apps only]

Header

OCIdl.h

IDL

OCIdl.idl

IID

IID_IOleInPlaceSiteWindowless is defined as 922EADA0-3424-11CF-B670-00AA004CD6D8

See also

IAdviseSinkEx
IOleControl
IOleInPlaceActiveObject::TranslateAccelerator
IOleInPlaceObjectWindowless

 

 

Community Additions

ADD
Show:
© 2014 Microsoft