WINE Ole Control Containment User's Guide

Last modified: $Date: 2005/02/02 11:51:43 $


Table of Contents

1. Overview
2. Enabling OLE Control Containment in GRAPE application
3. Creating an OLE Control wrapper class using Visual Autogen
4. The wrapper class file
5. Inserting a Control into a Control Container Application
6. Handling Events from an OLE Control
7. Programming OLE Controls in an OLE Control Container

1. Overview

This document is concerned with Ole Control Containment (OCC) in GRAPE Applications, named Ole Control Containers. An OLE control container is a container that fully supports OLE controls and can incorporate them into its own windows or dialogs. An OLE control is a reusable software element that you can use in many development projects. Controls allow your application's user to access databases, monitor data, and make various selections within your applications. The OLE control container interacts with the control via exposed methods and properties. These methods and properties, which can be accessed and modified by the control container, are accessed through a wrapper class in the OLE control container project. The embedded OLE control can also interact with the container by firing events to notify the container that an action has occurred. The control container can choose to act upon these notifications or not.

Additional articles discuss several topics, from creating an OLE control container project to basic implementation issues related to OLE control containers built with Visual Eiffel. Basically, you will follow these steps:

  1. Enabling OLE Control Containment in GRAPE Application.
  2. Creating an OLE Control wrapper class using Visual Autogen.
  3. Inserting a Control into a Control Container Application.
  4. Handling Events from an OLE Control.
  5. Programming OLE Controls in an OLE Control Container.

For this discussion, the VideoPlay sample control will be added to the resulting project.

2. Enabling OLE Control Containment in GRAPE application

To add OLE Control Containment feature to GRAPE application, you should inherit your own application class from EOLE_OCC_APPLICATION rather then APPLICATION. The functionality of this two classes absolutely the same except some extra initialization, performed by instance of EOLE_OCC_APPLICATION class during sturtup. Second important thing is you have to add instances of the OLE Control wrapper classes to EOLE_OCC_WINDOW only.

3. Creating an OLE Control wrapper class using Visual Autogen

Before you can access an OLE control from an OLE container application, you must use Visual Autogen to create the OLE control wrapper class and add it to the container application.

To add an OLE control to the OLE container project

  1. Run Visual Autogen application. You will see something like this:

    Selecting OLE control

    The contents of the 'Available controls:' listbox depends of the OLE Controls, installed in Your system and may be different.

  2. Select the control you want by clicking the corresponding listbox string.
  3. Click the Generate Code! button.
  4. The Save As dialog box appears. This dialog box lists the wrapper class implementation file and folder to save.

    Save as dialog
  5. Click the Save button to accept the class generated by Autogen.
  6. Click the Close button to close Visual Autogen.

Once you complete this procedure, the class generated by Visual Autogen, referred to as a wrapper class, is added to your project. This class (in this example, EOLE_VIDEO) is used as an interface between the control container, Container, and the embedded control, VideoPlay.

4. The wrapper class file

To get and set properties (and invoke methods) for the VideoPlay control, the EOLE_VIDEO wrapper class provides a declaration of all exposed methods and properties. In the example, these declarations are found in Video.e. The following sample is the portion of class EOLE_VIDEO that defines the exposed interfaces of the OLE control:

class EOLE_VIDEO
 
inherit
 
   EOLE_OCC
      end
 
   ...
 
creation
 
   make
 
feature
 
   get_class_id: STRING is
      once
         Result := "{76848C20-D175-11CE-82AB-00AA00A757FC}"
      end
 
feature -- Attributes
 
   get_Filename: STRING is
      do
      end
 
   set_Filename (propertyValue: STRING) is
      do
      end
 
   get_Loop: BOOLEAN is
      do
      end
 
   set_Loop (propertyValue: BOOLEAN) is
      do
      end
 
   ...
 
feature -- Operations
 
   Stop: INTEGER is
      do
      end
 
   Pause: INTEGER is
      do
      end
 
   Play (optParams: ARRAY [ANY]): INTEGER is
      do
      end
 
   AboutBox is
      do
      end
 
end -- class EOLE_VIDEO

These functions can then be called from other of the application's procedures using normal Eiffel syntax. For more information on using this member function set to access the control's methods and properties, see the section Programming OLE Controls in an OLE Control Container.

Once the VideoPlay control is inserted into the project, insert an instance of the EOLE_VIDEO control into the application's DESKTOP_ELEMENT.

5. Inserting a Control into a Control Container Application

In this section we describe in detailes how to add any OLE Control to your Container aplication using machine-generated wrapper class. From GRAPE's point of view, any OLE Control is a TILE object, therefore OLE Control creation absolutely the same as a TILE creation, except that OLE Control can be 'added' only to the EOLE_OCC_WINDOW rather than any GROUP.

Typical piece of code, performing physical OLE Control creation, looks like following:

...
local
   de    : DESKTOP_ELEMENT;
   r     : RECT;
   occWnd: EOLE_OCC_WINDOW;
   video : EOLE_VIDEO   
do
   !!de.make ("Media Architects VideoPlay/OCX")
   desktop.add (de)
   !!r.make (0, 0, 1, 1)
   !!occWnd.make ("", r)
   de.add (occWnd)
   !!video.make ("", r, IDC_VIDEO)
   occwnd.add (video)
end
...
IDC_VIDEO: INTEGER is unique

The IDC_VIDEO value specifies the control ID - an integer value that an application uses to uniquely identify a child control. This ID is used in parent's on_event callback, which is invoked when events, such as input from the user, occur in the control.)and can be used by the container to refer to the control.

6. Handling Events from an OLE Control

Using the on_event callback method of EOLE_OCC_WINDOW class, you can handle an events that can occur in your OLE control container application. This event handler function is called when the any event is fired by the OLE control object an has the following prototype:

on_event (idCtrl: INTEGER; event: EOLE_EVENT) is
   do
   end

To handle mouseClick event in the inserted VideoPlay control, you should inherit from the EOLE_OCC_WINDOW and redefine this method as following:

on_event (idCtrl: INTEGER; event: EOLE_EVENT) is
   local
      msgInfo: MESSAGE_INFO
   do
      if idCtrl = IDC_VIDEO then
         inspect event.dispid
         when EOLE_DISPID_CLICK then
            !!msgInfo.make ("Mouse Click", "Info") 
         else
         end
      end
   end

The following standart DISPIDs declared in EOLE_DISPID class:

EOLE_DISPID_UNKNOWNEOLE_DISPID_KEYUP
EOLE_DISPID_VALUEEOLE_DISPID_MOUSEDOWN
EOLE_DISPID_PROPERTYPUTEOLE_DISPID_MOUSEMOVE
EOLE_DISPID_NEWENUMEOLE_DISPID_MOUSEUP
EOLE_DISPID_EVALUATEEOLE_DISPID_ERROREVENT
EOLE_DISPID_CONSTRUCTOREOLE_DISPID_AMBIENT_BACKCOLOR
EOLE_DISPID_DESTRUCTOREOLE_DISPID_AMBIENT_DISPLAYNAME
EOLE_DISPID_COLLECTEOLE_DISPID_AMBIENT_FONT
EOLE_DISPID_AUTOSIZEEOLE_DISPID_AMBIENT_FORECOLOR
EOLE_DISPID_BACKCOLOREOLE_DISPID_AMBIENT_LOCALEID
EOLE_DISPID_BACKSTYLEEOLE_DISPID_AMBIENT_MESSAGEREFLECT
EOLE_DISPID_BORDERCOLOREOLE_DISPID_AMBIENT_SCALEUNITS
EOLE_DISPID_BORDERSTYLEEOLE_DISPID_AMBIENT_TEXTALIGN
EOLE_DISPID_BORDERWIDTHEOLE_DISPID_AMBIENT_USERMODE
EOLE_DISPID_DRAWMODEEOLE_DISPID_AMBIENT_UIDEAD
EOLE_DISPID_DRAWSTYLEEOLE_DISPID_AMBIENT_SHOWGRABHANDLES
EOLE_DISPID_DRAWWIDTHEOLE_DISPID_AMBIENT_SHOWHATCHING
EOLE_DISPID_FILLCOLOREOLE_DISPID_AMBIENT_DISPLAYASDEFAULT
EOLE_DISPID_FILLSTYLEEOLE_DISPID_AMBIENT_SUPPORTSMNEMONICS
EOLE_DISPID_FONTEOLE_DISPID_AMBIENT_AUTOCLIP
EOLE_DISPID_FORECOLOREOLE_DISPID_AMBIENT_APPEARANCE
EOLE_DISPID_ENABLEDEOLE_DISPID_FONT_NAME
EOLE_DISPID_HWNDEOLE_DISPID_FONT_SIZE
EOLE_DISPID_TABSTOPEOLE_DISPID_FONT_BOLD
EOLE_DISPID_TEXTEOLE_DISPID_FONT_ITALIC
EOLE_DISPID_CAPTIONEOLE_DISPID_FONT_UNDER
EOLE_DISPID_BORDERVISIBLEEOLE_DISPID_FONT_STRIKE
EOLE_DISPID_APPEARANCEEOLE_DISPID_FONT_WEIGHT
EOLE_DISPID_REFRESHEOLE_DISPID_FONT_CHARSET
EOLE_DISPID_DOCLICKEOLE_DISPID_PICT_HANDLE
EOLE_DISPID_ABOUTBOXEOLE_DISPID_PICT_HPAL
EOLE_DISPID_CLICKEOLE_DISPID_PICT_TYPE
EOLE_DISPID_DBLCLICKEOLE_DISPID_PICT_WIDTH
EOLE_DISPID_KEYDOWNEOLE_DISPID_PICT_HEIGHT
EOLE_DISPID_KEYPRESSEOLE_DISPID_PICT_RENDER

7. Programming OLE Controls in an OLE Control Container

At this point, you have inserted the VideoPlay OLE control into your EOLE_OCC_WINDOW, which was added to standart GRAPE DESKTOP_ELEMENT. You can now use common Eiffel syntax to access the properties and methods of the embedded control.

As noted, the wrapper class for the VideoPlay OCX, in this case Video.e, contains a listing of member functions that you can use to get and set any exposed property value. Member functions for exposed methods are also available.

The following code example uses the 'video' member variable to play video 'Hakunama.avi':

video.set_Filename ("Hakunama.avi")
video.set_Loop (True)
video.Play (<<>>)

That's all you have to write to enjoy the pretty Disney's animation!

Note

Please, be sure that Video compression for the multimedia playback is installed on Your mashine! Without it you will be unable to play video. To install this component, please, go to the Control Panel and double click on the Add/Remove Programs icon. Then, select the "Windows Setup" tab in the tabbed dialog box and then select "Multimedia" string from the "Components" listbox.

Click "Details..." button. Check "Video compression" component from the "Components" listbox. Click "Ok" button. Click "Ok" button again and follow the setup program.