DOCUMENT:Q130728  02-FEB-2002  [foxpro]
TITLE   :OLE Controls Available in Visual FoxPro
PRODUCT :Microsoft FoxPro
PROD/VER::3.0
OPER/SYS:
KEYWORDS:kbcode kbvfp300

======================================================================
-------------------------------------------------------------------------------
The information in this article applies to:

 - Microsoft Visual FoxPro for Windows, version 3.0 
-------------------------------------------------------------------------------

SUMMARY
=======

The Professional Edition of Visual FoxPro has up to four OLE controls available
in .OCX files depending on which Windows platform is being use. This article
describes each of those controls and gives tips for using them. OLE controls
covered are:

  - MSCOMM32.OCX for communications
  - MSMAPI32.OCX for MAPI (Messaging Application Program Interface)
  - MSOUTL32.OCX for outlining
  - PICCLP32.OCX for picture clip

This article summarizes information available as many smaller help topics about
OLE controls in the Visual FoxPro Professional Reference Help file.

MORE INFORMATION
================

OLE Controls Overview
---------------------

The Visual FoxPro OLE Container control lets you add OLE controls (.OCX files) to
your applications. Depending on your Windows platform (Windows version 3.1,
Windows for Workgroups, Windows NT, or Windows 95) up to four OLE controls are
installed with Visual FoxPro in your WINDOWS\SYSTEM directory.

Event, Method, or Property May Apply to OLE Container (Form) or OLE Control
---------------------------------------------------------------------------

It's important to note that many events, methods, and properties that need to be
set for OLE controls apply to the OLE Container control in which the OLE control
is placed rather than directly to the OLE control itself. Others apply directly
to the control.

For example, the MAPI DownLoadMail property applies directly the MAPI OLE
control, but the MAPI DocumentFile property applies to the container that the
MAPI OLE object is in. Therefore, these properties for the MAPI OLE control are
referenced in this manner:

  SomeForm.DocumentFile
  SomeMAPIControl.DownLoadMail

Code Sample for OLE Control
---------------------------

The following code sample shows how an OLE container can be added to a form and
used to modify a Microsoft Excel file from Visual FoxPro:

   * The following example adds an OLE Container control to a form, and uses
   * the OleClass and DocumentFile properties to specify Microsoft Excel as
   * the OLE server and a Microsoft Excel worksheet as the file to edit.
   *
   * The DocumentFile property specifies a worksheet named BOOK1.XLS in
   * the EXCEL directory on drive C. This example will not work if
   * the file and directory specified in the DocumentFile property do not
   * exist; It may be necessary to modify the DocumentFile property to
   * specify an existing directory and worksheet file.
   *
   * The DoVerb method is used to activate the worksheet for editing.

   frmMyForm = CREATEOBJECT('Form')  && Create a Form
   frmMyForm.Closable = .F. && Disable the Control menu box

   frmMyForm.AddObject('cmdCommand1','cmdMyCmdBtn')  && Add command button
   frmMyForm.AddObject("oleObject","oleExcelObject")  && Add OLE object

   frmMyForm.cmdCommand1.Visible=.T. && Display the Quit command button

   frmMyForm.oleObject.Visible=.T. && Display the OLE control
   frmMyForm.oleObject.Height = 50  && Specify OLE control height

   frmMyForm.Show  && Display the Form

   frmMyForm.oleObject.DoVerb(-1)  && -1 for Edit

   READ EVENTS  && Start event processing

   DEFINE CLASS oleExcelObject as OLEControl
     OleClass ="Excel.Sheet"  && Server name
     DocumentFile = "C:\EXCEL\BOOK1.XLS"  && This file must exist
   ENDDEFINE

   DEFINE CLASS cmdMyCmdBtn AS CommandButton  && Create command button
     Caption = '\<Quit'  && Caption on the command button
     Cancel = .T. && Default Cancel command button (Esc)
     Left = 125  && Specify command button column
     Top = 210  && Specify command button row
     Height = 25  && Specify command button height

     PROCEDURE Click
       CLEAR EVENTS  && Stop event processing and close form

   ENDDEFINE

   * End of Sample Code for OLE Control.

Communications Control (MSCOMM32.OCX)
-------------------------------------

The Communications control, MSCOMM32.OCX, provides serial communications for your
application by allowing the transmission and reception of data through a serial
port. The Communications control is installed only if you are running Windows NT
or Windows 95.

   Syntax: MSComm

The Communications control provides the following two ways to handle
communications:

 - Use event-driven communications to handle serial port interactions. In many
   situations, you want to be notified the moment an event takes place, such as
   when a character arrives or a change occurs in the Carrier Detect (CD) or
   Request To Send (RTS) lines. In such cases, you can use the Communications
   control's OnComm event to trap and handle these communication events. The
   OnComm event also detects and handles communications errors.

   -or-

 - Poll for events and errors by checking the value of the CommEvent property
   after each critical function of your program. This may be the best method if
   your application is small and self-contained. For example, if you are writing
   a simple phone dialer, it may not make sense to generate an event after
   receiving every character, because the only characters you plan to receive
   are the OK response from the modem.

Each Communications control you use corresponds to one serial port. If you need
to access more than one serial port in your application, you must use more than
one Communications control. The port address and interrupt address can be
changed from the Windows Control Panel.

When you create and distribute applications that use the Communications control,
you should install MSCOMM32.OCX in the customer's WINDOWS\SYSTEM subdirectory.

The following example, from the Visual FoxPro Help file, shows how to perform
basic serial port communications:

      * Use COM1.
      Comm1.CommPort = 1
      * 9600 baud, no parity, 8 data, and 1 stop bit.
      Comm1.Settings = "9600,N,8,1"
      * Tell the control to read entire buffer when Input is used.
      Comm1.InputLen = 0
      * Open the port.
      Comm1.PortOpen = .T.
      * Send the attention command to the modem.
      Comm1.Output = "AT" + CHR(13)
      * Wait for data to come back to the serial port.
      DO WHILE Comm1.InBufferCount <= 2
        * Read the "OK" response data in the serial port.
        InString = Comm1.Input
      ENDDO
      * Close the serial port.
      Comm1.PortOpen = .F.

MAPI Control (MSMAPI32.OCX)
---------------------------

The messaging application program interface (MAPI) control, MSMAPI32.OCX, allows
you to create a mail-enabled Visual FoxPro application. The MAPI controls are
installed only if you are running Windows NT or Windows 95.

The MAPI controls are invisible at run time. In addition, there are no events for
the controls. To use them, you must specify the appropriate methods. For these
controls to work, MAPI services must be present. MAPI services are provided in
Microsoft Mail electronic mail system for Microsoft Windows, version 3.0 or
later.

MAPI Session and MAPI Messages OLE Controls
-------------------------------------------

There are two OLE controls (MAPI Session and MAPI Messages) you can create with
MSMAPI32.OCX. The MAPI Session control establishes a MAPI session, and the MAPI
Messages control allows the user to perform a variety of messaging system
functions.

MAPI Session Control
--------------------

The MAPI Session control signs on and establishes a MAPI session, and it signs
off from a MAPI session.

   Syntax: MapiSession

After a sign-on is successful, the SessionID property contains the handle to the
MAPI session. The session handle must then be passed to the MAPI Messages
control or an error results when using the MAPI Messages control. Be sure to use
the MAPI Session control to sign off from any messaging session you initiate
with a sign-on action.

MAPI Messages Control
---------------------

After a messaging session is established by using the MAPI Session control, the
MAPI Messages control performs a variety of messaging system functions.

   Syntax: MapiMessages

With the MAPI Messages control, you can:

 - Access messages currently in the inbox.

 - Compose a new message.

 - Add and delete message recipients and attachments.

 - Send messages, with or without a supporting user interface.

 - Save, copy, and delete messages.

 - Display the Address Book dialog box.

 - Display the Details dialog box.

 - Access attachments, including OLE automation attachments.

 - Resolve a recipient name during addressing.

 - Perform reply, reply-all, and forward actions on messages.

Most of the properties of the MAPI Messages control can be categorized into four
functional areas: address book, file attachment, message, and recipient
properties. The file attachment, message, and recipient properties are
controlled by the AttachmentIndex, MsgIndex, and RecipIndex properties,
respectively.

For example, as the index value changes in the MsgIndex property, all other
messages, file attachments, and recipient properties change to reflect the
characteristics of the specified message. The set of message and recipient
properties works the same way. The address book properties specify the
appearance of the Address Book dialog box.

When using the MAPI Messages control, you need to keep track of two buffers, the
read buffer and the compose buffer.

The read buffer is made up of an indexed set of messages fetched from a user's
inbox. The MsgIndex property is used to access individual messages within this
set, starting with a value of 0 for the first message and incrementing by one
for each message through the end of the set. The message set is built using the
Fetch method.

The set includes all messages of type FetchMsgType and is sorted as specified by
the FetchSorted property. Previously read messages can be included or left out
of the message set with the FetchUnreadOnly property. Messages in the read
buffer can't be altered by the user, but can be copied to the compose buffer for
alteration.

Messages can be created or edited in the compose buffer. The compose buffer is
the active buffer when the MsgIndex property is set to - 1. Many of the
messaging actions are valid only within the compose buffer, such as sending
messages, sending messages with a dialog box, saving messages, or deleting
recipients and attachments.

Outline Control (MSOUTL32.OCX)
------------------------------

The Outline control, MSOUTL32.OCX, is a special type of list box that allows you
to display items in a list hierarchically. This is useful for showing
directories and files in a file system, which is the technique used by the
Windows File Manager.

   Syntax: Outline

Each item in the Outline control can have subordinate items, which are visually
represented by indentation levels. When an item is expanded, its subordinate
items are visible; when an item is collapsed, its subordinate items are hidden.
Items in the Outline control can also display graphical elements to provide
visual cues about the state of the item.

Visual Elements of Outline Control
----------------------------------

The Outline control can display graphics and text for each item in a list. For
examples that use plus/minus pictures and text or examples that use tree lines,
type pictures, and text, please see the Visual FoxPro Help file.

An item in an outline can have each of the following graphical elements:

 - Tree lines: Vertical and horizontal lines that link items with subordinate
   items. A tree line generates Expand and Collapse events.

 - Indentation: An item's level of subordination. Each level of indentation is a
   level of subordination you specify with the Indent property.

 - Plus/minus sign: Indicates whether subordinate items are visible or hidden.
   When the plus sign is clicked, subordinate items become visible and a minus
   sign replaces the plus sign. When the minus sign is clicked, the subordinate
   items are hidden and a plus sign replaces the minus sign.

 - Type pictures: Indicates the state of an item. Type pictures typically show
   whether an item with subordinate items can be expanded or collapsed. For
   example, a picture of a closed folder indicates that items in the folder can
   be expanded. The state of an item is user- defined. The type picture
   generates PictureClick and PictureDblClick events.

 - Text: The string displayed for an item. Each graphical element can be a
   hot-spot graphic. Clicking a hot spot triggers a special set of events. Use
   the Style property to display all, some, or none of the graphical elements
   for each item in the Outline control.

NOTE: You can't select an item by clicking a graphical element in the Outline
control. To select an item in an Outline Control, you must click or double-click
the text.

You can use the keyboard to select items in an Outline control's list. The
following table lists the keys and their actions.

Keyboard Key   Action
-------------------------------------------------------------------------

LEFT ARROW     Moves the focus to the parent item, if the current item is
               subordinate.

RIGHT ARROW    Moves the focus to the first subordinate item, if visible.

UP ARROW       Moves the focus to the previous item, if any.

DOWN ARROW     Moves the focus to the next item, if any.

HOME           Moves the focus to the first item in the list.

END            Moves the focus to the last item that is visible.

PAGE UP        Moves the focus back one page, or to the first item
               currently displayed.

PAGE DOWN      Moves the focus forward one page, or to the last item
               currently displayed.

PLUS (+)       Expand an item that has subordinate items.

MINUS (-)      Collapse an item that has subordinate items.

Step-by-Step Process to display Outline Control Properties Dialog Box
---------------------------------------------------------------------

1. Create a form or open an existing one in the Form Designer.

2. From the Form Controls toolbox, choose the OLE Container Control button and
   place an OLE container control on the form.

   The Insert Object dialog box appears.

3. In the Insert Object dialog box, choose Insert Control.

4. From the Control Type list, select Outline Control.

5. Choose OK.

   The Outline control appears on the form.

6. With the mouse, right-click the Outline control to display the shortcut menu.

7. From the shortcut menu, choose Properties.

   The Outline Control Properties dialog box appears.

Outline Control Properties Tabs
-------------------------------

Outline Control Properties tabs that specify style properties and general
characteristics of the Outline control are:

 - Pictures: Specifies picture properties for the Outline control.

 - Fonts: Specifies the font, font style, font size, and other properties for
   the Outline control.

 - Colors: Specifies background and foreground colors for the Outline control.

Picture Clip Control (PICCLP32.OCX)
-----------------------------------

The Picture Clip control, PICCLP32.OCX, allows you to select an area of a source
bitmap, and then display the image of that area in a form. Picture Clip controls
are invisible at run time.

   Syntax: PictureClip

The Picture Clip control provides an efficient mechanism for storing multiple
picture resources. Instead of using multiple bitmaps or icons, create a source
bitmap that contains all the images required by OLE controls in your
application. When you need to access an individual image, use the Picture Clip
control to select the region in the source bitmap that contains that image.

For example, you could use this control to store all the images needed for your
application. It is much more efficient to store all of the images in a single
Picture Clip control than it is to store each image as a separate file. To do
this, you first need to create a source bitmap that contains all of the images.

The picture object reference the Picture Clip control creates from the source
bitmap can only be used by other OLE controls. For example, it can be used for
the PictureOpen and PictureClosed properties in the Outline control. Visual
FoxPro controls and objects cannot use the picture object reference the Picture
Clip control creates.

You can use the Random Access method or the Enumerated Access method to specify
the clipping region in the source bitmap as follows:

 - Use the Random Access method to select any portion of the source bitmap as
   the clipping region. Specify the upper-left corner of the clipping region by
   using the ClipX and ClipY properties. The ClipHeight and ClipWidth properties
   determine the area of the clipping region. This method is useful when you
   want to view a portion of a bitmap.

   -or-

 - Use the Enumerated Access method to divide the source bitmap into a specified
   number of rows and columns. The result is a uniform matrix of picture cells
   numbered 0, 1, 2, and so on. You can access individual cells by using the
   GraphicCell property. This method is useful when the source bitmap contains a
   palette of images that you want to access individually.

To load the source bitmap into the Picture Clip control, use the Picture
property. You can only load bitmap (.BMP) files into the Picture Clip control.

NOTE: When you create and distribute applications that use the Picture Clip
control, you should install PICCLP32.OCX in the user's Microsoft WINDOWS\SYSTEM
subdirectory.

PicClip Control Properties Dialog Box
-------------------------------------

The PicClip Control Properties dialog box specifies properties for the PicClip
control, which is an OLE container control that allows you to select an area of
a source bitmap and display that area in a form. To display the PicClip Control
Properties dialog box, follow these steps:

1. Create a form or class, or open an existing form or class in the Form
   Designer.

2. From the Form Controls toolbox, choose the OLE Container Control button and
   place an OLE container control on the form. The Insert Object dialog box
   appears.

3. In the Insert Object dialog box, choose Insert Control.

4. From the Control Type list, select PicClip Control.

5. Choose OK. The PicClip control appears on the form.

6. With the mouse, right-click the PicClip control to display the shortcut menu.

7. From the shortcut menu, choose Properties. The PicClip Control Properties
   dialog box appears.

PicClip Control Properties Tabs
-------------------------------

The PicClip Control Properties tabs are:

 - Rows/Cols: Specifies the number of rows and columns in the PicClip control.

 - Pictures: Specifies a picture for the PicClip control.

Additional query words: VFoxWin

======================================================================
Keywords          : kbcode kbvfp300 
Technology        : kbVFPsearch kbAudDeveloper kbVFP300
Version           : :3.0

=============================================================================

THE INFORMATION PROVIDED IN THE MICROSOFT KNOWLEDGE BASE IS
PROVIDED "AS IS" WITHOUT WARRANTY OF ANY KIND.  MICROSOFT DISCLAIMS
ALL WARRANTIES, EITHER EXPRESS OR IMPLIED, INCLUDING THE WARRANTIES
OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR PURPOSE.  IN NO
EVENT SHALL MICROSOFT CORPORATION OR ITS SUPPLIERS BE LIABLE FOR
ANY DAMAGES WHATSOEVER INCLUDING DIRECT, INDIRECT, INCIDENTAL,
CONSEQUENTIAL, LOSS OF BUSINESS PROFITS OR SPECIAL DAMAGES, EVEN IF
MICROSOFT CORPORATION OR ITS SUPPLIERS HAVE BEEN ADVISED OF THE
POSSIBILITY OF SUCH DAMAGES.  SOME STATES DO NOT ALLOW THE EXCLUSION
OR LIMITATION OF LIABILITY FOR CONSEQUENTIAL OR INCIDENTAL DAMAGES
SO THE FOREGOING LIMITATION MAY NOT APPLY.

Copyright Microsoft Corporation 2002.