TweetFollow Us on Twitter

OLE In-Place Activation
Volume Number:11
Issue Number:1
Column Tag:Microsoft Technology

In-Place Activation with OLE

Select, modify, and manipulate, all without leaving the application.

by Michael Fanning, Microsoft

Note: Source code files accompanying article are located on MacTech CD-ROM or source code disks.

This article is the second in a series describing the evolution of a simple OLE2 object server and will show you how to implement the Visual Editing feature of OLE for the Macintosh. A general familiarity with OLE and its underlying architecture (the Common Object Model, or COM) is assumed, a passing familiarity with the OLE interfaces for embedding OLE objects would be helpful. At a minimum, I’d suggest reading the first article which examines a simple (non-in-place) object server and also has a nifty glossary of essential OLE terms and concepts. If you haven’t read it, don’t have a copy, are uncertain of what OLE is and/or have used the word more often at bullfights than in technical discussions, don’t worry; we’ve included it on a CD that’s bound into this magazine. In fact, the CD holds the entire OLE for the Macintosh Software Developer’s Kit in its final form, for both 68K and Power Macintosh. The only thing that could possibly make it easier to implement Visual Editing in your own code would be a roadmap in the form of commented pseudo-code drawn from a working in-place server.


Back in the August issue, the editorial page predicted readers would find the piece “ more pleasant than dissecting a frog” - I thought this was generous, ‘equally pleasant’ was probably sufficient - “and at least as instructional”. I sincerely hope this last goal was met, dissection can set a high standard on information returned weighed against effort put forward. I’d be more comfortable if there was more life in the imagery, realistically the comparison turns to vivisection at that point, so let’s stick with the dissection metaphor and sharpen up the code scalpels.

OK, onwards.


Visual Editing, also known as in-place activation, is the feature of OLE that customers care about the most. It’s what allows them to edit any kind of data in any kind of document; to them, that’s what OLE is. Dissecting the implementation of an in-place server doesn’t spark much interest, that’s best left to people my younger sister always describes to me as ‘kinda geeky, like you’. Visual Editing is without question the most important user interface feature that’s defined by the OLE specification.

In-Place, Defined

In-place activation is a user interface standard by which an object can be selected, modified, and generally manipulated by the user, all while appearing to remain within the application which contains it. The object provides the functionality, the container provides the visual context. The editable state of the object is evident in certain user interface (UI) clues: a composite menu bar that contains both server and container menus, server toolbars or floating windows that appear on activation, and a shaded or hatched border which surrounds an in-place active object, grow handles optional. The net UI illusion is that an embedded object’s data is modified without (apparently) leaving the container application. Instead, the server’s functionality is brought into the container’s context, reinforcing a notion that the user’s document is central and that each kind of data in the document should be seamlessly editable without the user needing to worry about which application to invoke.

One of the Macintosh OLE developers compares the process to implementing a kind of “well-defined” dialog. The container provides a context which it describes to the server. The server provides a service, or feature, including the UI. Cooperative communication between the apps according to a protocol defined in OLE allows the server’s UI and feature to blend seamlessly into the container’s context.

Com, Redux, Revisited, In Short, Re-revealed

Before continuing I’d like to review the basic ideas which comprise the Common Object Model, and therefore OLE itself. If you haven’t grabbed the first article from the CD for a read-through, you should. It’s one of those, grab-your-nose, it’s-got-to-go-down-at-some-point and it-may-as-well-be-sooner-rather-than-later, cod-liver oil kind of articles. Anyone who’s inclined to skip past a COM/OLE recapitulation can look ahead for the next reference to in-place in bold caps.

OLE0 - a set of interfaces which define essential protocols for interoperability.

Interface 0 - a table (or vtable) of function pointers to constituent routines, commonly known as methods.

Method 0 - a member function of an interface.

There are specific interfaces for each of the general areas of functionality OLE defines; they include Uniform Data Transfer, Linking (Naming and Binding), Embedded Objects (Compound Document Management), Drag and Drop, Visual Editing, Automation (Programmability), and Structured Storage (disk- and memory-based persistent storage). Inter-object communication is facilitated by notification and concurrency-related interfaces.

OLE is the protocol, COM is the means

COM itself can be reduced to a small set of simple and powerful concepts which are the quantum building blocks of OLE. Essentially, the Common Object Model defines how objects should interact, both in the context of a single application (as an in-process server or object handler on Power Macintosh) and across application boundaries. While OLE defines specific protocols of communication, COM provides the means and supporting mechanism which allows transparent communication between applications.

What this means is that a user of an object (i.e., the one calling an interface method) doesn’t need to know where the code that’s called exists. It might be in-process, or in a separate background application. In the near future, it might reside across the network or be running in a different operating system altogether. The client is completely insulated from any concerns related to how the call makes it to the server and how the result makes it back.

COM Concerns

The basic contract for a COM object or its client is not particularly demanding. 1) COM applications follow a convention for retrieving and/or providing pointers to their supported objects known as interface negotiation, a simple idea which yields powerful returns. 2) COM defines a set of rules and methods which guarantee the lifetime of an object while it is in use by any COM client.

Interfaces and their Negotiation - Strictly speaking, interfaces are nothing more than abstract base classes comprised of pure virtual member functions. This basically means that the member functions are defined by OLE without providing any implementation. COM objects derive from the supported interface and implement all its methods, without exception.

After retrieving the initial pointer to an object (which is really just a pointer to one of the interfaces the object implements), pointers to different interfaces (representing different functionality) also implemented by the object can be retrieved through interface negotiation (IUnknown::QueryInterface).

Object Lifetime - COM defines a method for incrementing an object’s reference count (IUnknown::AddRef) and a method for decrementing it (IUnknown::Release). All objects ultimately derive from IUnknown and therefore must implement these two methods. An object increments its own reference count whenever it hands out a pointer to one of its interfaces (usually in response to QueryInterface). When the code that requested the interface is done with it, it calls the object’s Release method which decrements the object’s reference count. If the reference count drops to zero, that indicates that no one is using the object and it can safely delete itself. This simple set of rules allows an object to track how long it needs to exist since it always knows how many clients still have a reference to one of its interfaces.

Interface negotiation and reference counting are provided through a single interface, IUnknown, which serves as the base class for all COM objects. These two concepts are basic to COM and a good place to start gaining a general understanding.

COM addresses other subjects that are beyond the scope of this article:

• Identification (Globally Unique Identifiers)

• Memory Allocation/Deallocation

• Error and Status reporting

• Location/Dynamic Loading/Reuse of Object Code

• Security/Encapsulation

• Remoting

The glossary in the August MacTech article covers some of these topics in greater detail.

Hold On, I Know There’s Something About
In-Place In Here Somewhere

Subsequent sections of this article will cover the following, in order:

1. The OLE Interfaces specific to in-place capable servers

2. The series of calls between a container and server which result in an embedded object

3. The basic sequence of steps for activating an object in-place

4. A list of possible OLE object states and definitions

5. A pointer to the activation logic used by SimpleIPServer, in pseudo-code

6. Exit

Item #5 (and the SimpleIPServer source) is payoff for anyone looking for a leg up implementing visual editing in an object server. The logic in this pseudo-code is a clear roadmap for activating objects in-place on the Macintosh. I’ll upload a similar file detailing deactivation/close logic to the MS BBS on AppleLink and to the Macintosh library (lib 12) of the MS OLE forum on CompuServe (GO WINOBJ) in the not too distant future.

Visual Editing in Two Easy Interfaces + Assorted Logic

The server-side of in-place editing is limited to two interfaces, IOleInPlaceObject and IOleInPlaceActiveObject, which define 4 and 5 unique methods, respectively. Both interfaces derive (as all in-place interfaces do) from IOleWindow, which itself has only two methods (GetWindow and ContextSensitiveHelp).

This doesn’t sound like much work and in fact, you can get an in-place server up and running with most in-place related methods stubbed out. A more advanced in-place server will have code related to toolbar negotiation, menu merging, context-sensitive help and undo support, which will flesh out the in-place interfaces. The fundamental work of an in-place server, however, lies in its activation and deactivation logic.

The following section describes the negotiation and necessary steps to activate an embedded object for visual editing, beginning with a container’s call to IOleObject::DoVerb.


As you may recall from the first article, a container fully instantiates an embedded OLE object before requesting that the server execute its primary verb, the step that actually brings the object to the foreground and makes it visible. On inserting a SimpleIPServer object in the SimpleIPContainer sample app, the sequence of calls leading up to DoVerb is identical with their non-inplace counterparts from the August article. (You can view the LRPC communication between OLE applications by running LRPCSpy, an OLE SDK utility I find extremely effective for monitoring and debugging OLE applications. I’ve spent some time developing SimpleIPServer’s debug output to take even better advantage of the tool, most of the code for which is located in debug.cp).

The following few paragraphs and LRPCSpy output tracks creation of an embedded SimpleIPServer object:

Before LRPC communication can begin between an OLE container and server, there must be one of each in memory. The typical means to get there is to display a dialog and let the user choose from a list of available objects. As it happens, we get this for free by calling a routine from the OLE User Interface library. The UI Library contains helper functions for a variety of OLE tasks, all of which already conform to the OLE User Interface guidelines. The routine which invokes the standard Insert Object dialog is OLEUIInsertObject.

Once the user chooses an object type, the Insert Object dialog returns the CLSID (class identifier) associated with that type of object. The container then calls OleCreate, passing in the CLSID of the object and the ID of an interface to query the object for (this is usually IID_IOleObject). OLE uses the Registration Database to locate the server associated with this CLSID, then launches the server and sends it a specific AppleEvent to tell it that it’s being launched to service an OLE object. The server creates its Class Factory and registers it with OLE, at which point OLE calls CreateInstance and passes in the desired interface ID. It’s at this point that COM really starts to strut its stuff. In returning the interface pointer to the container, COM does a little magic and creates a connection between the two apps so that when the container calls a method on the interface, the corresponding code in the server gets executed. Remember, to the container, this interface acts just like a normal C++ object.

OLE has now accomplished a fundamental task in object interoperability: it has delivered a pointer to a server object to an OLE client. Tips are greatly appreciated, a gratuity of 15% will be charged for parties of 6 objects or more.

In the output below, distilled from LRPCSpy, ‘sIPs’ refers to the SimpleIPServer, ‘OTIC’ is OutlineInplaceContainer, a C-based in-place sample from the OLE SDK:

// [Caller > Callee]   [Interface ID]          [Method]       [Arguments]
 1) OTIC > sIPs: IID_IClassFactory   CreateInstance  
 2) OTIC > sIPs: IID_IStubManager    QueryInterface  (IID_IPersistStorage)
 3) OTIC > sIPs: IID_IPersistStorage InitNew         
 4) OTIC > sIPs: IID_IStubManager    QueryInterface  (IID_IDataObject)
 5) OTIC > sIPs: IID_IStubManager    QueryInterface  (IID_IOleObject)
 6) OTIC > sIPs: IID_IOleObject      SetClientSite   
 7) OTIC > sIPs: IID_IOleObject      Advise          
 8) OTIC > sIPs: IID_IDataObject     QueryGetData 
 9) OTIC > sIPs: IID_IDataObject     Advise          
10) sIPs > OTIC: IID_IAdviseSink     OnDataChange    
11) OTIC > sIPs: IID_IOleObject      SetHostNames    
                                      ("OutlineInPlaceContainer", "Object 
12) OTIC > sIPs: IID_IStubManager    LockConnection  (FALSE, FALSE)
13) OTIC > sIPs: IID_IOleObject      GetExtent       
14) OTIC > sIPs: IIDIOleObject       DoVerb          (OLEIVERB_SHOW, 
                                            iface*, -1, WindowPtr{"untitled")

In the above, OLE calls SimpleIPServer’s CreateInstance method (item 1, above) in response to a request from OutlineInplaceContainer (i.e., OTIC has called OleCreate, passing SimpleIPServer’s CLSID). OTIC QI’s for IPersistStorage (2) and calls InitNew (3), passing a pointer to the storage it has created to hold the SimpleIPServer object. The container retrieves interfaces for data transfer (4) and basic object communication (5) with the embedded object (IDataObject and IOleObject). OTIC calls IOleObject::SetClientSite (6), which provides the server with a reference to the container’s IOleClientSite interface, then sets advises on IOleObject and IViewObject (which shows up on the server side as an advisory connection on its IDataObject interface). When creating each advisory connection, the container passes a reference to its IAdviseSink interface to the method call. Both OLE and the server hold a reference to this interface and each of them notifies the container of specific events (such as when the object is closing, or the object’s presentation has changed and should be redrawn). The object is queried for support of PICT representation (8) and another advise is set, this time on IDataObject in order to receive word of any change in the object’s data (9). sIPs sends a notification of data change resulting from initialization (10). The container passes the container and object names as strings (11). OLE calls an internal function in the code that’s managing the connection on the server side to ensure that it stays active for the lifetime of the conversation (12). A call to GetExtent returns the size of the server object (13). Finally, OTIC calls DoVerb() with the verb OLEIVERB_SHOW, thus passing the reins to the server and instructing that it proceed with the process of showing itself.

In Situ, Bruté?

There hasn’t been a single in-place call up to now, and there won’t be unless the server decides to initiate a discussion on the topic in DoVerb. The basic steps in negotiating an in-place session look something like this:

1) The server QI’s for IOleInPlaceSite.

2) The container agrees to activate in-place and provides context details.

3) The server creates a menubar to hold menus from both applications and passes it to the container to let it insert any menus it will use during visual editing.

4) The server negotiates for any additional screen territory required for toolbars, etc.

5) The server moves its window into place and makes itself the foreground app.

6) On coming frontmost, the server installs its UI component (menu, toolbars, etc.) and makes itself visible.

It’s fairly apparent from this description that the server is the active agent throughout the procedure. After instantiating an object and calling DoVerb on it, the container remains more or less passive during activation, i.e., its interface implementations will be called by OLE when its participation is required. OLE itself is calling the container as the direct or indirect result of the server’s activation logic. The server is busily steering a course for activation, determining the container’s capabilities, and putting together special UI components to use while visual editing.

if (m_pAuthor->m_pMind->m_fIsLosingKeenEdge)
 hresult = (IDissectOLETopic)m_pTemp->StopCuttingStartStepping();

That’s all for now. All that’s left is to step through the SimpleIPServer code. To assist in this, I’ve made some modifications to SimpleIPServer’s trace functionality. The sample builds a debug version by default which has two menus absent from the non-debug build, Debug and Trace. The Debug menu contains options to continuously display global data tracking object state, redirecting debug information to various outputs (the LRPCSpy utility, MacsBug, a logfile), setting a ‘verbose’ debug mode, and rejecting incoming LRPC messages (a standard test app functionality allowing observation of container behavior in scenarios where a server is not responding to outside calls).

The Trace menu has several options for tracking progress of the inplace code through trace output. The nature of inplace activation makes source-level debugging problematic for some server-container-debugger combinations. Debuggers like to pull themselves to the foreground, and for obvious reasons this can disrupt the inplace relationship of a server and container in mid-negotiation. One workaround is to use a low-level debugger such as MacsBug or The Debugger while debugging your inplace code. Neither of these debuggers causes a context switch when activated so they don’t interfere with inplace negotiation.

If you plan to use the THINK Debugger, you should install a special version of the OLE Libraries which resolves a compatibility problem that appears when debugging an OLE application with this debugger. The OLE Libraries patch LoadSeg in the application’s trap table so that they’re able to load additional segments while running in the application’s context. In order for this to work OLE needs to intercept certain LoadSeg calls and not pass them along (this only happens if it’s a segment in the OLE Library). It turns out that the THINK Debugger patches both the LoadSeg trap as well as the trap dispatcher itself. By patching the trap dispatcher, it’s able to detect that a LoadSeg call is about to execute and prepare itself internally for the pending LoadSeg call. When OLE intercepts a LoadSeg call and doesn’t pass it along, the THINK Debugger is left in an unstable state and bad things start to happen.

The special version of the OLE Libraries is called “Microsoft OLE Extension.ThinkC” and can be found in “SDK:Think” on the OLE SDK CD. This version preloads all segments in the OLE library and thus ensures that it never needs to intercept a call to LoadSeg. It does require a larger partition since all the code is preloaded.

As mentioned before, in-place activation begins with a call from an OLE container to execute a server verb (i.e., an operation or action the object supports, defined by the system or by the object itself). The following pseudo code is a reliable path a typical server might follow in handling activation to support visual editing. If you plan to code an OLE server yourself, you should find it an extremely useful implementation guide.

We’ve placed a copy of this article, including the following pseudo-code and comments, at the root level of the SimpleIPServer folder. To get the most the remainder of this article, I’d suggest you take a moment to scan the release notes on the OLE CD. Go ahead and install the OLE libraries according to the instructions you’ll find there. The steps are few in number and extremely straightforward; after copying the OLE bits to the usual haunts in the System Folder, you’re actually be ready to run OLE applications.

One useful point regarding the MS OLE Extension is that it does not have to load at startup in order for OLE to work; every bit of OLE functionality aside from Visual Editing is present even after a shift-boot. Visual Editing does require the extension to be loaded in order to work, however, so go ahead and restart so you can play around with the compiled version of the SimpleServer.

Debugging Tip - At times, you might find it useful to guarantee that one particular build of the OLE libraries in in memory when testing an OLE application, this can also be useful when debugging situations where an OLE app launches and immediately quits again without indicating what accounted for the load failure. (One possible reason accounting for this might be an application set with a memory partition larger than the system can reasonably support. On startup, the app claims all available memory for itself without leaving room for the OLE code to load inside the system heap. Prelaunching the OLE library insures sufficient memory for it to load and the app is content with the amount that remains, a figure below its preferred, but well above its minimal partition size.)

To prelaunch a specific build of OLE, simply change the type of the library you’re interested in from ‘INIT’ to ‘APPL’ and double-click. Retail builds will load as faceless background apps that won’t be visible in the Mac application menu (you will see the standard UI signs of a launch within the Finder, however). Debug builds actually appear in the application menu and can be pulled to the foreground and quit from the File menu. This isn’t necessary when everything’s working properly; under these conditions, the OLE libraries will stay resident in memory as long as necessary to handle container-server communications, after which it unloads.

You may find that attempting to invoke OLE in the usual way after changing its Type is not successful (meaning the OLE libraries fail to load in response to an Insert Object dialog request, etc.) The likely cause here is that the extension is no longer named properly (or wasn’t named properly in the SDK to begin with, such as MS OLE Extension.Think), in the absence of an expected signature, the MS OLE Extension name itself is used to locate the file. You can either switch the type back to ‘INIT’ and try to call OLE again, prelaunch the build you want to test or work with, or rename the ‘APPL’ OLE extension to the original name which shipped with the first release of Mac OLE.

In any event, the easiest way to invoke the OLE libraries is to follow the instructions in the latest OLE docs, restart the Macintosh (to enable in-place) and double-click the OLE application. Take a second to do this and run SimpleIPServer and a few of the other applications which are already compiled on the CD. Be sure to launch LRPCSpy to watch SimpleIPServer’s trace output as it does nothing more than create and close windows, renders and deletes simple shapes, etc. Experiment with the various trace and debug options.

At some point, bring LRPCSpy forward and hit cmd-backspace to clear all output windows. Pull up the SimpleIPServer ReadMe document and look for a section titled ‘Tracing SimpleIPServer Execution With the Pseudocode from MacTech InPlace article, January ‘95’. This section will contain any last minute features I can squeeze in. If there’s a logical way to put it in place, I’d like to enable a specific trace option for tracking the server’s progress in context of the following section. This ReadMe will also contain information for building the sample in a number of different development environments, the end of the document has a brief section on SDK test tools, some debugging tips, and a list of the most common development obstacles (and solutions) that a developer new to OLE is likely to encounter.

When you’re ready to dive in, launch an OLE Visual Editing container application. Any OLE in-place capable container will do, a sample or test app from the CD, or any shipping OLE application which supports visual editing. Pull up the Insert Object dialog and scan the list of embeddable objects. SimpleIPServer registers on launch, so you should see an entry for a Simple InPlace Server Document in the insert object listbox. Select it, click OK, and get ready for your first look at the guts of an in-place application at work.

The next section contains SimpleIPServer’s activation logic in detailed and well-commented pseudo-code (InPlace Logic.sIPs, in the same folder as the ReadMe). You can use this file as a roadmap for stepping through the code sample, or as a guide in implementing your own visual editing server. There are similar documents in-progress for other aspects of in-place development which will be available on CompuServe, AppleLink, and in future versions of the OLE for Macintosh SDK.

Activation Logic - A Walkthru

As stated previously, the moment of truth for an In-place application comes with a call to IOleObject::DoVerb, a method which is exposed (i.e., implemented and made available to the container by means of a provided interface pointer) by an OLE served. A visual editing server first raises the subject of in-place activation with a container in this context. The following pseudo-code functions are logically arranged to follow the course an object might take in order to activate successfully. The breakdown of routines, the tasks completed in each, and the global data documented in their pseudo-implementation represents a viable schematic for an in-place app to follow. It’s not just playing a visual app on TV. Here’s hoping you find it instructional; pleasant can come along for the ride if there’s room, but will have to take a back seat.

To fully explore the logic and gain familiarity with the underlying negotiations, you’ll want to try embedding SimpleIPServer into a number of different containers, including OLE 1.0 client-containers, and OLE 2.05 containers which don’t support visual editing. Following the pseudo code while tracing other in-place servers in LRPCSpy is informative, too, revealing the many approaches that can be taken to accomplish a end in OLE ends as well as the common paths most travel.

We now join the activation in progress




[ a series of lprc calls documented above and in the August ]

[ article which fully instantiate and initialize an OLE object. ]

[ at this point, the container is ready to activate the object ]

[ and let it take focus. let’s see what happens next. ]



HRESULT DoVerb(long iVerb...)
/* The following verbs mean that we should go inplace active if we can, which we do, generally speaking. 
 Support for visual editing doesn’t carry any responsibility to go in-place, however, the process is entirely 
cooperative and can be abandoned at any step by either participant 

 if not IPActive    // IPActive == InPlaceActive state
 call DoIPActivate()// DoInPlaceActivate transition, etc., etc.
 else if not UIActive 
 call DoUIActivate(UIACTIVATE)// flag that says we
    // were already ipactive
    // if either of the above calls failed, fall through to the OLEIVERB_OPEN code

/* The UIActive state is the moment at which all negotiation is settled between a container and server when 
all UI components are ready to go but are still hidden.  This is the state an active object would go to on being 
sent to the background due to a mouse click in the Finder.  All that remains is to go UIVisible, which is accomplished 
by bringing the app to the foreground and showing the relevant ui components. */

 // this verb means to start open editing, even if we support inplace
 if iVerb is OLEIVERB_OPEN
 if IPActive
 DoIPDeactivate()// get completely out of inplace to open edit
    // continue into open edit mode

 if our window is visible and we’re not IPActive
 call DoUIActivate()

HRESULT DoIPActivate(void)
 // this function shouldn’t get called if we’re already ipactive
 if IPActive
 assert and return

 // confirm that our state is as follows:
 ASSERT(ipactive == false, uiactive == false, uivisible == false)

 // check if our window is already visible and fail inplace if so
    // (this means we’re already in open edit mode)
 if our window is visible
 return E_FAIL

 // if the container has never called SetExtent, store defaults
 if extent is 0,0
 extent = default size

 // on a failure we call DoIPDeactivate which only procedes if ipactive == true
 IPActive = true;

 // this is our first chance to see if the container supports inplace
 if (IOleClientSite->
 QueryInterface(request IOleInPlaceSite interface) 
 returns NULL)
 return E_FAIL

 // does the container want to allow inplace right now?
 if IOleInPlaceSite->CanInPlaceActivate() doesn’t return S_OK
 return E_FAIL

    // GetWindowContext returns references to the container’s IOleInPlaceUIWindow 
    // and IOleInPlaceFrame interfaces, the rect where we should put ourselves, a
    // pointer to the container’s window (that we’ll be inplace in), and three regions 
    // that we pass to OLE later (with the OleSetInPlaceRects call)

 // hOleMBar contains a list of the menus that the container wants inserted 
    // while inplace
 if stored hOleMBar is NULL

 // create new OleMBarHandle

 // let container insert its menus into this OleMBarHandle

 // notify container that we’re ipactive (still need to go uiactive and uivisible)

 // the IPACTIVATE flag indicates that we’re doing the inplace negotiation
    // from scratch
 call DoUIActivate(IPACTIVATE)

HRESULT DoUIActivate(short wAction)
 // on entry to this function, wAction is one of:
    //  IPACTIVATE: starting inplace negotiation from scratch
    //  UIACTIVATE: starting inplace negotiation from ipactive state

    // this function shouldn’t get called if we’re already uiactive
 if UIActive
 assert and return

    // confirm that our state is as follows:
 ASSERT(ipactive == true, uiactive == false, uivisible == false)

 // on a failure we call DoUIDeactivate which only procedes if uiactive == true
 UIActive = true;

    // if uiactivating (was already ipactive), need to get parent window pointer
    // again in case we’re being activating in a different window
 if wAction == UIACTIVATE

    // give our IOleInPlaceActiveObject interface to IOleInPlaceFrame and 
    // IOleInPlaceUIWindow (when inplace has been nested several levels deep, 
    // the IOleInPlaceFrame interface is our channel of communication with the 
    // outer-most container, and the IOleInPlaceUIWindow allows us to communicate 
    // with the container we’re directly embedded in).
 SetActiveObject(our IOleInPlaceActiveObject interface)
 SetActiveObject(our IOleInPlaceActiveObject interface)

    // we don’t need any space on the document (UIWindow) so pass NULL

    // calculate how much space we want around the frame, request it, and if this
    // succeeds, set that much space and show our frame tools
    // NOTE: if we don’t have frame tools, simply pass NULL to SetBorderSpace again 

    // get the current bounds where frame tools might be placed
    IOleInPlaceFrame->GetBorder(pointer to BORDERWIDTHS)

    // calculate how much frame space we need
 FrameSpaceNeeded(pointer to BORDERWIDTHS)

 if IOleInPlaceFrame->RequestBorderSpace(pointer to 
 if IOleInPlaceFrame->SetBorderSpace(pointer to 
 enable our frame tools (show toolbars and status bar
   around frame)

    // if any of the above calls failed show frame tools as floating windows
    // NOTE: we might also jump to this block if FrameSpaceNeeded determined
    // that there wasn’t enough room to place our tools around the frame
 if any of the above calls failed
 show frame tools as floating windows

    // if uiactivating (was already ipactive) or if frame negotiation succeeded,
    // need to get current position again
 if wAction == UIACTIVATE or frame negotiation succeeded

    // move and size inplace window so it conforms to position retrieved from
    // GetWindowContext or GetObjectRects (if we wanted object adornments we 
    // would adjust the location of our window before calling MoveWindow and 
    // SizeWindow)
 MoveWindow(our inplace window)
 SizeWindow(our inplace window)

    // the following code calls OleSetInPlaceWindow until it either succeeds or our 
    // timeout expires.  when OleSetInPlaceWindow returns an error this means 
    // another app still has an inplace window set.  we give the other app time to finish 
    // getting out of inplace instead of just failing immediately (this timing problem can 
    // occur if the user is quickly switching between two inplace sessions)
 while true
 if OleSetInPlaceWindow() returns NOERROR
 break out of loop

 if exceed timeout
 assert and break out of loop

 WaitNextEvent() // yield so other apps can process

    // give OLE our current position (including any adjustments if we added
    // object adornments) and the regions from GetWindowContext

    // notify container that we’re uiactive (still need to go uivisible)
 if IOleInPlaceSite->OnUIActivate() returns OLE_E_NOT_FRONT_PROCESS

    // OLE_E_NOT_FRONT_PROCESS means the user switched to another app, 
    // unset the inplace window and exit without failing (leave ourselves uiactive)
 return NOERROR

    // call the document’s generic show routine which eventually calls
    // DoIPShowDocument (after showing the window, etc).  when ShowDocument
    // calls DoIPShowDocument it passes UIACTIVATE
 call ShowDocument()


HRESULT DoIPShowDocument(short wAction)
    // on entry to this function, wAction is one of:
    //   UIACTIVATE:  starting inplace negotiation from ipactive state
    //   DOCACTIVATE: starting inplace negotiation from uiactive state
    //           (OnFrameWindowActivate or OnDocWindowActivate call)

    // if we’re already uivisible, don’t bother proceeding
 if UIVisible

    // confirm that our state is as follows:
 ASSERT(ipactive == true, uiactive == true, uivisible == false)

    // on a failure we call DoIPHideDocument which only proceeds if uivisible == true
 UIVisible = true;

    // if we’re called from OnFrameWindowActivate or OnDocWindowActivate, the 
    // user has just switched apps or documents so that the inplace container 
    // document has been activated.
 if wAction == DOCACTIVATE

    // get our position in case it changed (this can happen if the container
    // window moved while we weren’t uivisible and consequently didn’t get
    // the SetObjectRects call)

    // move and size inplace window so it conforms to the new position
 MoveWindow(our inplace window)
 SizeWindow(our inplace window)

    // see code in DoUIActivate for explanation/elaboration of these two calls

    // give our IOleInPlaceActiveObject to IOleInPlaceFrame and 
    // IOleInPlaceUIWindow
  SetActiveObject(our IOleInPlaceActiveObject interface)
  SetActiveObject(our IOleInPlaceActiveObject interface)

    // clip all server windows so they appear to be behind the container
 OleClipWindows(first window in WindowList)

    // save the current menubar (gets restored when going uivisible(false)
 hSavedMBar = GetMenuBar()

    // delete any of our menus that shouldn’t be available while inplace
 DeleteMenu(id of File menu)// for instance, the File and
 DeleteMenu(id of Window menu)// ...Window menus

    // this call inserts the container’s menus into our menubar

    // force the the menubar to redraw

    // notify container that we’re uivisible (only needed if responding to either
    // OnFrameWindowActivate or OnDocWindowActivate)
 if wAction == DOCACTIVATE

    // show the inplace window and make sure it’s frontmost
 ShowWindow(our inplace window)
 SelectWindow(our inplace window)

    // the call to OleSetInFrontOf attempts to bring us the the foreground
 if OleSetInFrontOf() returns NOERROR

    // wait until we’ve come to the front (use GetCurrentProcess(),
    // GetFrontProcess(), and SameProcess() to detect when we’re frontmost)
    // NOTE: this call is implemented in SimpleIPServer’s CApp object

    // hilite the container’s window (got from GetWindowContext or
    // GetWindow).  this helps maintain the illusion that the container is
    // the frontmost app even though the server is in the foreground
 HiliteWindow(container’s window)


    // OleSetInFrontOf fails if the user clicked to another app during
    // inplace negotiation (it simply checks if the container is still the
    // frontmost app).  if we didn’t check for this condition and simply brought
    // ourselves to the foreground, another application would end up between
    // the container and the server and the illusion of inplace would be destroyed.
    // instead we leave ourselves in the uiactive state so that we’ll go uivisible
    // if the container’s inplace window is activated again.

In-Place At Last

There it is - the heart of activating an OLE object in-place. It’s a satisfying moment to see a server in development activate in-place for the first time. There’s something compelling about seeing your own code integrated with another application - surfacing in someone else’s context with a relevant toolbar and menu or two, then sinking back again on a mouse click in another window: it flat-out breaks through indifference and makes you go ‘wow’. After which, you can feel your thinking click forward a notch to the future.

Where to Go From Here

Bound into this issue of the magazine, you’ll find the Mac OLE 2.05 SDK CD. Feel free to play with it, to bang on it, to implement support for OLE in your Macintosh applications, and to ship those applications to your customers, all without charge or fee to Microsoft. Along the way, you can get technical support on CompuServe, by entering “Go WinObj” at the prompt, and looking for Section 12, where you’ll find lots of late-breaking information about Mac OLE. The library for this section usually has the most current OLE bits (right now it holds the 2.05 SDK broken into individual files which download as self-extracting archives). Keep an eye out for more sample code and supporting files over the next few weeks, including a simple link-server, linking container, etc.

On AppleLink, the OLE SDK is uploaded to the MSObjects topic located inside the Microsoft BBS. To get there, navigate through Third Parties:H-O:Microsoft and double-click the objects folder.

Again, the CD contains all the SDK files (and none of the download time) including Mac OLE help with all of the latest information in electronic form. If you prefer the heft and portability of a printed book, you can order the Macintosh OLE Programmer’s Reference by Barry Potter from M&T Books by calling 1-800-488-5233 (US) or 801-972-2221 (from outside of the US), entering 3 at the menu to reach Henry Holt Publishing, and asking for M&T Books, requesting information on the Macintosh OLE 2.0 Programmer’s Reference. Microsoft gets no money from M&T for the book; we supplied the content free as a service to the Macintosh development community, in order to keep the price as low as possible.

Once you’ve implemented support for OLE in your Macintosh application, we have a number of comarketing opportunities available to you. For more info, send email to

In the meantime, happy hacking - I mean, “dissecting”!


Community Search:
MacTech Search:

Software Updates via MacUpdate

Notion 2.1.3 - A unified workspace for m...
Notion is the unified workspace for modern teams. Features: Integration with Slack Documents Wikis Tasks More improvements to editing Browse through a page’s images from one place Choose a type... Read more
Cocktail 15.3.7 - General maintenance an...
Cocktail is a general purpose utility for macOS that lets you clean, repair and optimize your Mac. It is a powerful digital toolset that helps hundreds of thousands of Mac users around the world get... Read more
Dropbox 158.4.4564 - Cloud backup and sy...
Dropbox is a file hosting service that provides cloud storage, file synchronization, personal cloud, and client software. It is a modern workspace that allows you to get to all of your files, manage... Read more
WhatsApp 2.2236.10 - Desktop client for...
WhatsApp is the desktop client for WhatsApp Messenger, a cross-platform mobile messaging app which allows you to exchange messages without having to pay for SMS. WhatsApp Messenger is available for... Read more
VOX 3.5.2 - Music player that supports m...
VOX just sounds better! The beauty is in its simplicity, yet behind the minimal exterior lies a powerful music player with a ton of features and support for all audio formats you should ever need.... Read more
TeamViewer 15.34.4 - Establish remote co...
TeamViewer gives you remote control of any computer or Mac over the Internet within seconds, or can be used for online meetings. Find out why more than 200 million users trust TeamViewer! Free for... Read more
ClamXAV 3.5 - Virus checker based on Cla...
ClamXAV is a popular virus checker for OS X. Time to take control ClamXAV keeps threats at bay and puts you firmly in charge of your Mac’s security. Scan a specific file or your entire hard drive.... Read more
Ableton Live 11.2 - Record music using d...
Ableton Live lets you create and record music on your Mac. Use digital instruments, pre-recorded sounds, and sampled loops to arrange, produce, and perform your music like never before. Ableton Live... Read more
Viber 18.5.0 - Send messages and make fr...
Viber lets you send free messages and make free calls to other Viber users, on any device and network, in any country! Viber syncs your contacts, messages and call history with your mobile device, so... Read more
CrossOver 22.0.1 - Run Windows apps on y...
CrossOver can get your Windows productivity applications and PC games up and running on your Mac quickly and easily. CrossOver runs the Windows software that you need on Mac at home, in the office,... Read more

Latest Forum Discussions

See All

Death Road to Canada MANDIBLE and NERVE...
Earlier this year Rocketcat Games and Madgarden’s fantastic road trip zombie apocalypse simulator Death Road to Canada ($14.99) was updated on PC with the huge MANDIBLE update. This follows the LIVER update and more bringing in new special... | Read more »
TouchArcade Game of the Week: ‘Tallowmer...
With its pre-determined launch date of September 30th it didn’t quite make it in time for our weekly round-up of new game releases, but darn it, I just don’t care. I’m not letting that technicality keep me from picking Tallowmere 2 as our Game of... | Read more »
SwitchArcade Round-Up: Reviews Featuring...
Hello gentle readers, and welcome to the SwitchArcade Round-Up for September 30th, 2022. In today’s article, our pal Mikhail has another review for us. Gosh, that guy needs a day off! He’s taking a look at Let’s Build a Zoo, and it’s not exactly the... | Read more »
Seven Knights 2 recieves global update i...
Netmarble has announced the latest global update for mobile role-playing game Seven Knights 2. The update will bring brand new characters, some very rewarding events, and reworks to a few old favourite heroes. [Read more] | Read more »
‘GRIS+’ Is This Week’s New Apple Arcade...
Nomada Studio and Devolver Digital’s brilliant GRIS+ () has joined Apple Arcade today as an App Store Great. If you’ve not played it yet, GRIS debuted on PC and Nintendo Switch before seeing PS4 and mobile releases later on. I reviewed the iOS... | Read more »
SwitchArcade Round-Up: Reviews Featuring...
Hello gentle readers, and welcome to the SwitchArcade Round-Up for September 29th, 2022. In today’s article, we have a bunch of new releases to check out with the spearhead being The Elder Scrolls V: Skyrim Anniversary Edition. There’s a little here... | Read more »
‘Residual’ Controller Fix Update Release...
A few weeks back developer OrangePixel released their newest game on mobile called Residual. This is a roguelike survival game where you play as a pilot who crash lands on a procedurally generated planet, filled with all sorts of crazy creatures and... | Read more »
‘Queen’s Wish 2: The Tormentor’ Launchin...
We learned back in July that Spiderweb Software’s latest game Queen’s Wish 2: The Tormentor would be heading to desktop platforms in August, which is exactly what happened, and at that time we were guessing that the iOS version of the game would... | Read more »
‘Kingdom Rush Vengeance’ Primal Ravage U...
Ironhide Game Studio’s Kingdom Rush Vengeance ($4.99) has gotten quite a few updates over the years on iOS, Android, and PC. | Read more »
Interactive Film The Gallery screens at...
The FMV/interactive film hybrid video game genre has been around for a while but doesn’t seem to have that many games out there, but they just might get some more exposure as The Gallery has landed a spot in the Dinar Film Festival 2022. [Read... | Read more »

Price Scanner via

Apple has M1 Mac minis in stock again startin...
Apple has restocked a full line of M1-powered Mac minis available in their Certified Refurbished section starting at only $589 and up to $140 off MSRP. Each mini comes with Apple’s one-year warranty... Read more
13″ M1 MacBook Airs with 16GB of RAM availabl...
Apple has 13″ M1 MacBook Airs (8-Core CPU/7-Core GPU) in stock today with 16GB of RAM for $190 off MSRP, Certified Refurbished. Apple includes a standard one-year warranty with these models, each... Read more
Update: 13-inch Apple M2 MacBook Airs now on...
Amazon has 13″ MacBook Airs with M2 CPUs in stock today and on sale for $150 off MSRP. Shipping is free. Their prices are now $150 off Apple’s MSRP, and they are the lowest prices available for these... Read more
Save $240 on a 14″ 8-core CPU M1 Pro MacBook...
Apple has the 14″ M1 Pro MacBook Pro with 32GB of RAM and a 512GB SSD (Space Gray) in stock for $2159, Certified Refurbished. Regular price for this configuration is $2399, so their savings amounts... Read more
Save $170 on this 13″ M2 MacBook Pro with 16G...
Apple has 13″ M2 MacBook Pros with 16GB of RAM and 512GB SSDs in stock today for $170 off MSRP ($1529), Certified Refurbished. These are the cheapest 13″ M2 MacBook Pros with this configuration... Read more
This Apple retailer is offering a $350 discou...
Apple retailer Expercom is offering a $350 instant discount on select upgraded 16″ Apple MacBook Pros through October 4, 2022. Shipping is free. Their sale price applies to the following... Read more
Clearance 27″ 5K Apple iMacs are on sale star...
Other World Computing has dropped prices on Apple refurbished, factory-sealed, recently-discontinued 27″ 5K iMacs with models now on sale for up to $950 off Apple’s MSRP, starting at only $849. Their... Read more
Get a new Mac for up to $400 off MSRP at Appl...
Need a new Apple Mac for school? Whether you’re a student, teacher, or staff member, you can use your .edu email address when ordering at Apple Education to take up to $400 off the price of a new Mac... Read more
13-inch Apple MacBook Airs with M2 processors...
Amazon has 13″ MacBook Airs with M2 CPUs in stock today and on sale for $1099. Shipping is free. Their prices are $100 off Apple’s MSRP, and they are the lowest prices available for M2-powered Macs... Read more
AR Glasses That Work With Apple’s Hardware? T...
NEWS – Lenovo has created quite the spectacle(s) with its latest product. “Apple Glass” — the purported name of Apple’s forthcoming AR glasses — is not expected to be released until 2025 (at the... Read more

Jobs Board

*Apple* Electronic Repair Technician - PlanI...
…a highly motivated individual to join our Production Department as an Apple Electronic Repair Technician. The computer repair technician will diagnose, assemble, Read more
( *Apple* ) Production Designer/Artist - TEKs...
…Art Ops team supports production, asset management, quality control, and global publishing for Apple Media Products, like Apple Music. The Art Ops team is Read more
Operations Associate - *Apple* Blossom Mall...
Operations Associate - Apple Blossom Mall Location:Winchester, VA, United States ( - Apple Read more
Cashier - *Apple* Blossom Mall - JCPenney (...
Cashier - Apple Blossom Mall Location:Winchester, VA, United States ( - Apple Blossom Mall Read more
Sephora Beauty Advisor - *Apple* Blossom Ma...
Sephora Beauty Advisor - Apple Blossom Mall Location:Winchester, VA, United States ( - Apple Read more
All contents are Copyright 1984-2011 by Xplain Corporation. All rights reserved. Theme designed by Icreon.