This project contains an example program which demonstrates the use of the OLE-Server library to create a graphical object that can be embedded in compound documents.
The OLE-Server library is documented in the Functional Developer "OLE, COM, ActiveX and DBMS" reference manual.
This example provides the same functionality as the C++ program in directory "\MSTOOLS\samples\ole\simpsvr\" from the Microsoft Win32 SDK of July 1995. The "README.TXT" file there describes it as:
This sample is the simplest OLE 2.0 object that can be written and still support the visual editing feature. The object that this server supports is a colored square with a black border.
The direct translation of the C++ program into Dylan is available as the example called sample-ole-server under the "Low-level OLE" examples. The version in this project is written in a more natural Dylan style than sample-ole-server and uses the server framework provided by the OLE-server library to greatly simplify the program.
This project can be built in either of two configurations. It can be built as an EXE file which can then be used as a local server, or it can be built as a DLL file which can then be used as an in-process server. The default is to build an EXE file. Use the "Target file" entry in the "Link" tab of the "Project > Settings..." dialog to switch between these two options.
In either case, in order for the server to work when invoked from a client program, all of the libraries used by your server need to either be in the same directory as the server file, or else in a directory which is in the system PATH (not the individual user's PATH on NT). The simplest way to accomplish this is to use the "Project > Build Release" command to create a release directory. If you wish, you can move that directory to any location you want, but you must do so before you attempt to register the server.
After the project has been built, you will have a program which you can execute. By itself, it doesn't do much very interesting -- just draws a square whose color you can select from a menu.
The really interesting thing is using the program as an embedded object. To do that, you must first register it with the operating system. You can do this by running the program (from the release directory) from a DOS command prompt like this:
win32-ole-server.exe /regserver
This will create the necessary entries in the Windows System Registry and then terminate without creating any windows. The full pathname of the server is recorded, so you must unregister the server before you move or delete it. You can unregister it by doing:
sample-automation-server.exe /unregserver
The server is registered with the title "Dylan simple local OLE
Server" which comes from from the call to
register-ole-server
in appexe.dylan.
To register an in-process server, use the regsvr32
command line
utility like this:
regsvr32 win32-ole-server.dll
(The complete pathname will need to be given if the file is in a
different directory that is not in the PATH.) This will cause the
appropriate entries to be made in the Windows System Registry. (For
use in a batch script, the "/s
" option may be used to suppress the
dialog box reporting completion.) The full pathname of the server
is recorded, so you must unregister the server before you move or delete it.
You can unregister it by doing:
regsvr32 /u win32-ole-server.dll
This invokes the server to unregister itself, so won't work if the server has been deleted first.
The server is registered with the title "Dylan simple in-process OLE
Server" which comes from from the call to
initialize-ole-server
in appdll.dylan. The EXE and DLL
versions have different class ID numbers so that they can both be
installed at the same time.
You can use any OLE container program, such as Microsoft Word or
WordPad, or the sample container application simpcntr
in
the SDK (or its Dylan equivalent in the
sample-ole-container
example), to choose the server from
the "Insert Object" command of the "Edit" menu or, for Word or
WordPad, the "Object..." command of the "Insert" menu. The program
will then be invoked to draw its picture which will then appear in the
compound document.
Most containers use in-place activation, in which the picture is drawn directly in the window of the container program, and the menu for changing the color is added to the container's menu bar. Clicking once outside the picture de-activates it, and double-clicking on the picture re-activates it.
A local server can also be activated out-of-place, running in its own top-level window while active, and the picture will be copied into the document when the window is closed. To do this from Word or WordPad, select the drawing (by clicking once while not active) and then invoke the menu item "Edit" > "Dylan OLE Server Object" > "Open".
The program consists of the following files:
<simple-server-app>
and
application methods. This manages the application and document windows.
<simple-server>
and OLE
server methods. This implements the OLE-specific functionality. The
actual drawing of the picture is done by
ole-part-draw
. Persistence is implemented by
ole-part-save-to-storage
and
ole-part-load-from-storage
. Server menu installation is done
in ole-part-insert-menus
.
initialize-ole-server
is used to declare the information needed for registering the
server and automatically creating a class factory when requested by a
client. There is no event loop in this case because that will be provided
by the client (container) program. The main window is created in the
server's initialize
method, which will be called when/if
server creation is requested by the container.
main-program
is
invoked to start the program. If invoked in the in-process case, it does
nothing, as explained above. If invoked for self-registration, it
registers and returns. If invoked as a server, it creates a class factory
object, which the container application will use to request creation of
server objects. The program then enters a Windows event loop.