![[BACK]](/cvsweb/icons/back.gif){kind=icon}
Return to tn009.txt CVS log ![[TXT]](/cvsweb/icons/text.gif){kind=icon}
![[DIR]](/cvsweb/icons/dir.gif){kind=icon}
Up to [WindowsNT SDKs] / mstools / mfc / doc|
Return to tn009.txt CVS log | Up to [WindowsNT SDKs] / mstools / mfc / doc |
1.1 root 1: Microsoft Foundation Classes Microsoft Corporation
2: Technical Notes
3:
4: #9 : Writing an OLE Client Application
5:
6: This note describes the classes and steps involved in creating
7: an OLE client application.
8:
9: Please be sure to read the general MFC OLE overview first (TN008.TXT).
10:
11: =============================================================================
12: Features of an OLE Client Application
13: =====================================
14:
15: User Interface Features
16: -----------------------
17: The following list briefly describes some of the end-user features of a
18: typical OLE Client application. How the MFC OLE classes are used to provide
19: this support is described later.
20:
21: 1) Insert New Object dialog
22: The menu item "Insert &New Object" usually resides on the "Insert"
23: or "Edit" menu. This menu item will bring up a dialog showing all
24: the available class names (from the registered OLE Servers in the system).
25: The selected class name is used to create a new object of that type
26: and insert it into the client document.
27: The new object will start out in a blank state - which means
28: you must add data to it (by editing it in the server application)
29: before it becomes useable by the end user.
30:
31: 2) Paste, Paste Link menu items
32: The standard "Edit" menu will usually contain "Paste" and "Paste Link".
33: If the client app only supports embedding, there will be no "Paste Link".
34: These menu items will be enabled or disabled depending on the current
35: contents of the clipboard.
36:
37: 3) Object menu item
38: The bottom of the "Edit" menu will usually contain an "Object" menu item.
39: This is a dynamic menu item that changes depending on the current
40: selection. If more than one verb is possible it will change into
41: a popup menu listing all the verbs.
42:
43: 4) Links dialog
44: This is the standard dialog used to view, fix and otherwise manipulate
45: all the links in the current document.
46:
47: 5) Insitu features
48: The client document is reponsible for drawing the embedded/linked object
49: data in the appropriate location. Also supporting selection of items
50: and/or ranges of items as well as non-embedded document components.
51: Lastly double-clicking on an embedded/linked object should activate
52: that object.
53:
54: 6) OLE items as part of a document
55: The embedded/linked items are maintained as part of the document.
56: When the document is saved, so are the embedded items as well as the
57: links to the linked items. When the client document is loaded from disk
58: the reverse happens and the embedded/linked items are loaded as part of
59: the document.
60: If your current client application (or the one you are planning) does
61: not have documents, or "load" and "save" functionality - you may
62: want to implement an OLE server instead.
63:
64: Additional Features
65: -------------------
66: There are many other advanced features of an OLE Client than you can
67: implement on top of MFC OLE. These features are minimally supported in
68: the MFC OLE classes and are not well documented or illustrated in the
69: existing sample programs. These will be added into future versions of
70: MFC OLE.
71:
72: Additional information on these features can be found in the Windows 3.1
73: OLE documentation.
74:
75: Features not supported:
76: * Paste Special dialog (all the interfaces are there, but no canned
77: dialog to make this easy).
78: * Full support for UNDO (COleClientItem::CreateCloneFrom is provided,
79: but a client app must still do a lot of extra work).
80: * Full range of object creation options (for example creating from
81: template, or creating from file). Easy to add in your class derived
82: from COleClientItem if needed, but this functionality is
83: usually done with the MFC CFile and CArchive classes.
84: * Clients using the server data for more than pictures. In general
85: a client will create an embedded/linked object with the
86: standard draw option (olerender_draw). This means the
87: client will just draw the embedded/linked object in a
88: rectangle on the screen. Other render options are available.
89: * After loading a document which has manual links, the client app
90: should prompt the user to see if they want to update links now.
91:
92: =============================================================================
93: Tasks of an OLE Client Developer
94: ================================
95:
96: The Classes
97: ------------
98: As mentioned in the overview, the MFC OLE classes require that you
99: derive your own document and item classes from the MFC OLE base
100: classes.
101:
102: The document class defines the structure of how items are managed.
103: The item class defines the structure of how linked and/or embedded
104: OLE items fit into your application.
105:
106: Creating the document class
107: ---------------------------
108: Your client document will typically contain both OLE and non-OLE data.
109: Presumably you already have a class or two to manage non-OLE data in
110: your application (i.e. to store, display, hit detect the contents
111: of a Window's client area).
112: You must decide how OLE data will mix with the non-OLE data.
113: If your non-OLE data is stored as a CObject* collection, then there is
114: no extra work needed (since an OLE item is a CObject as well).
115: If not, you will have to extend your data structures so that they can
116: contain a client item wherever you want to mix OLE and non-OLE data.
117:
118: Class 'COleClientDoc' provides a base class that is used to contain
119: embedded items. You must derive your own document class from
120: 'COleClientDoc'. Be sure to override the member function 'GetNextItem'
121: to iterate over all the OLE items in the document (the interface is
122: very similar to MFC lists).
123:
124: You must register your client document when it is created (using 'Register').
125: Also there are specific notification routines that must be called:
126: NotifyRename - call after document has been renamed by user
127: NotifyRevert - call after document has been reverted to original
128: (i.e. re-opened ignoring recent changes)
129: NotifySaved - call after document has been saved to disk
130:
131: All of these steps are covered in the OCLIENT sample program.
132: The class CMainDocument is attached to CMainWnd and together they
133: serve as the main client document.
134:
135: Creating the item class
136: -----------------------
137: Your client item is the client-side view of the linked or embedded
138: OLE object. Class 'COleClientItem' provides a base class that is used
139: to keep extra application specific information about each linked/embedded
140: item. The position of the item in the client document is an example of
141: extra member data you can add to your class derived from COleClientItem.
142:
143: Since a COleClientItem must always be contained in a COleClientDoc, the
144: containing document must be passed as a parameter to the constructor.
145:
146: Your client item objects (derived from COleClientItem) will be created
147: in several end-user scenarios: (see below for how to implement these)
148: * with the InsertNewObject dialog
149: * when pasted from the clipboard (paste or paste-link)
150: * when loaded from an existing file
151:
152: You must override the member function 'OnChange' which is a callback
153: that notifies the client that the server has changed. There are three
154: reasons the client item may change: a linked item is changed (with
155: automatic notification turned on), the document edited on the server
156: is saved or the document edited on the server is closed.
157:
158: In general do not redraw the client item when you get the 'OnChange'
159: callback, but instead post an update message (or use InvalidateRect
160: for the window).
161:
162: All of these steps are covered in the OCLIENT sample program.
163: The class CEmbeddedItem is attached to CItemWnd and together they
164: provide both the data and user interface to the client item.
165:
166:
167: Checking errors and catching exceptions
168: ---------------------------------------
169: Abnormal conditions, like out of memory, or can't launch server will
170: result in a COleException being thrown. A COleException object
171: can be examined to see what OLESTATUS error code caused the problem.
172: If a set of conditions are expected, the MFC OLE member function will
173: return a BOOL. If the BOOL returns FALSE, a more detailed error
174: report can be determined by COleClientItem::GetLastStatus which
175: returns the OLESTATUS of the last OLE API function call.
176:
177: Asynchronous Requests
178: ---------------------
179: The member function COleClientItem::WaitForServer is used
180: to synchronize the client with the server. If a server request can't
181: be finished immediately, the client application will wait inside of
182: 'WaitForServer' until the operation is complete (successful or not).
183: The client code calling this just sees a simple synchronous call.
184:
185: While the client app is waiting it will continue to dispatch windows
186: messages. The static member function 'COleClientItem::InWaitForServer'
187: can be used to see if the client application is already nested in
188: a server request. See the OCLIENT sample app for an example of the
189: use of 'InWaitForServer'.
190:
191: Advanced users may wish to override 'WaitForServer' and customize
192: it's behavior as appropriate. See the OCLIENT sample app for an
193: example of how to turn on the hourglass when a client operation
194: is going to take too long as the result of a server not being ready.
195:
196: Implementing the UI features
197: ----------------------------
198: The following gives a brief overview of what you must do to implement
199: the major User Interface features of OLE for your client application.
200: See above for the list of 6 major UI features. See the OCLIENT sample
201: program for a working example of how to implement these features.
202:
203: 1) Insert New Object dialog
204: (a) call 'AfxOleInsertDialog' to prompt the user for class name
205: (b) create an object of your COleClientItem derived class using
206: 'COleClientItem::CreateNewObject'.
207: (c) insert it at the current document (eg: at the insertion point
208: if applicable to your application).
209:
210: 2) Paste, Paste Link menu items
211: (a) create menu items for "Paste" and, optionally, "Paste Link"
212: (b) override OnInitMenu or OnInitMenuPopup in your main frame window
213: (i) call 'COleClientItem::CanPaste' to determine if you
214: can paste or not and enable menu item accordinglly
215: (ii) call 'COleClientItem::CanPasteLink' to determine if you
216: can paste link or not and enable menu item accordinglly
217:
218: (c) when either is selected, use CreateFromClipboard or
219: CreateLinkFromClipboard to create the new object from clipboard.
220:
221: 3) Object menu item
222: This is a complicated UI which is provided for you in the standard
223: MFC OLE library.
224: (a) create menu items for "Object" with special ID value
225: (b) as with Paste, override OnInitMenu or OnInitMenuPopup in
226: your main frame window
227: (c) call 'AfxOleSetEditMenu' with the item, menu, and the position where
228: to store the 'Object' menu in the specific popup.
229:
230: 4) Links dialog
231: (a) add a "Links" menu item to the "Edit" menu popup
232: (b) when the user selects the "Links" menu item, call 'AfxOleLinksDialog'
233: (c) you can disable the menu item either if no linked items are
234: selected, or if the document does not contain linked items.
235: (by overriding OnInitMenu or OnInitMenuPopup in
236: your main frame window).
237:
238: 5) Insitu features
239: This is the most work.
240: (a) when your window gets an OnPaint request, it must draw the
241: COleClientItem by calling 'Draw'. This draw routine is passed
242: a DC and a bounds rectangle.
243: (b) depending on your model of selection - you probably want to support
244: selection of linked/embedded items
245: (c) perhaps support resizing of embedded items - call SetBounds to
246: change the size.
247: (d) lastly, when the user double-clicks on a client item, it should
248: be activated by calling 'Activate'. Overriding OnLButtonDblClk
249: in the appropriate window class.
250:
251: 6) Object as part of a document
252: (a) provide an implementation of Save/load that uses the CArchive
253: serialization mechanism.
254: (b) implement Serialize for your derived COleClientItem class, and
255: be sure to call the base class COleClientItem::Serialize, since
256: this will save the embedded/linked object information.
257:
258: =============================================================================
259: Other Issues:
260: =============
261:
262: Building
263: --------
264: Assuming you are already building a normal MFC windows application,
265: you must do the following additional steps:
266:
267: * include 'afxole.h' in those source files using MFC OLE (this will
268: include 'afxwin.h' if not included already).
269: * Link with the appropriate MFC library as usual.
270: * You will also need to link with two additional libraries:
271: OLECLI.LIB - interfaces to the client side OLE APIs
272: SHELL.LIB - interfaces to the registration API
273: COMMDLG.LIB - interfaces to the common dialog API
274: * you must include the standard client resources by including
275: 'afxoleUI.h' and 'afxoleUI.rc' in your client application's
276: RC file. This includes the dialog templates and standard
277: strings for the UI parts of the OLE support.
278:
279: * Warning: the OLE Links dialog may call COMMDLG to prompt
280: the user for a new filename. This requires a reasonable
281: amount of stack space (8K or more).
282:
283: Testing
284: -------
285: There are two test programs provided in source form in the MFC SAMPLE
286: directory.
287:
288: TESTCLNT - a test client (i.e. used to test servers)
289: TESTSERV - a test server (i.e. used to test clients)
290:
291: You will probably want to use 'TestServ' or some other OLE server
292: to test your application. See the contents of the sample source
293: directories for more details on these test programs.
294:
295: Debugging
296: ---------
297: See TN007.TXT for a description of the 'afxTraceFlags' options for
298: doing advanced debugging. The multi-application debugging option
299: (option 1) is extremely useful, especially if you are debugging a
300: client and a server at the same time.
301:
302: The main message pump reporting (option 2) is very useful when you
303: are trying to figure out which messages are being dispatched.
304:
305: Option 0x10 is provided specifically for OLE debugging, and
306: turns on some rather verbose reporting messages informing you what
307: is going on in the MFC OLE classes.
308:
309: Sample Code
310: -----------
311: In addition to the test programs, the OCLIENT sample provides a simple
312: sample of a OLE Client application. It exploits all of the user interfaces
313: provided by MFC OLE.
314: It is a good example since it is relatively simple.
315: It is a poor example since each embedded/linked items is stored in a
316: CWnd (a CItemWnd). In general embedded/linked items are normally
317: drawn as part of your client area.
318:
319: =============================================================================
This archive runs on limited infrastructure. Preserving old code on modern bandwidth. Automated agents are requested to crawl responsibly.