ActiveX in Obsydian - Tips and Techniques

Introduction

This document is intended to help developers make better use of ActiveX controls in Obsydian developed applications.
The basis for this comes from work done with the new Obsydian Pattern Libraries.
All of the ActiveX controls discussed are used by the Microsoft Windows operating system or Microsoft Office 97 and so are freely available without additional licenses.

Installation

The ActiveX controls used must be correctly installed and registered for the generated applications to function correctly. Correct installation can be verified by attempting to add the control to an Obsydian panel and using it in test mode. If the control cannot be selected from the presented list, or the control cannot be loaded correctly, the test mode panel will display an error. Review your installation documentation to correctly load and register any control with this problem.

Function structure

Each ActiveX in the Pattern library is wrappered by a function. This function has a panel to which the control is added and any default properties set. The function also scopes a function called 'Scripts'. This serves no other purpose than to make a better presentation of the wrapper function on the Object Browser.

As its name suggests, the 'Scripts' function scopes all of the scripts (Source code objects) required to support the ActiveX control.

These scripts are named to indicate the control they are designed to operate on. For instance 'TreeView1_AboutBox' executes the 'AboutBox' method for the 'TreeView1' control. The name of the control is one of the properties stored in the Panel.

Certain ActiveX wrapper functions inherit from others where they need to use another control to operate correctly. The most common case is when control use images. To make the process more efficient, there is a special control called 'ImageList' which loads images into memory and supplies them to other controls on demand. Any number of controls on a panel can call on the services of a common ImageList.

 

Any ActiveX control that uses an ImageList has a property to identify which one it will get its images from. This is a property visible when you are editing the panel but it cannot be set there. You have to set the ImageList property using script in a source code object.

 

ActiveX scripts

All the scripts in the Pattern libraries are written in VB Script. This was chosen because Microsoft supplies all of the controls that have been wrappered. It also allows the controls to be tested in a Visual Basic project, the VB code can then be cut & pasted directly into an Obsydian Source code object.

Events

Events triggered by an ActiveX control can be associated with logical events defined in the panel. This approach is fine for events that do not return values. For any event that returns a value, the parameters can to be obtained using a set of source code API's, but is much easier to use a script.

The pattern libraries handle all events through scripts in the following way:
  • No ActiveX event is attached to a logical event in the panel although the logical events are created.
  • A script called 'Control_Events' is created and called during the initialization of the function. This script contains code to set the control's image list property if required and then subroutines for each event to be handled. The script has parameters for each value returned by an event that has to be accessible in the action diagram code.
  • The script triggers the action diagram event at the end if there is any action diagram processing associated with the event.

A typical source code script would look something like:

This code sets the image list property in the first line and then sets up the sub routine to handle the user clicking on a node in the tree control.
When this event occurs, the code in the subroutine sets the two action diagram fields and then passes control to the action diagram event handler.
Scripts of this type can contain as many subroutines as necessary to handle all the events.

In general, don't attach the ActiveX events in the panel, use sub routine processing to trigger the action diagram, if required.

 

It is possible to directly set action diagram fields from within fields without having them as parameters. The pattern libraries use parameters because it is easier to see which fields are set by any given script and these can also easily be overridden in the action diagram without having to edit the script.

 

Known limitations and "Gotcha's"
    1. 'Visible' property

      2. For technical reasons, setting the visible property of any ActiveX control during execution has no effect. The only way to make a control change its visibility is to use a panel wide control state.

    2. Integer parameter

      3. Certain methods accept numeric parameters. Most of the time, substituting the action diagram field into the parameter position will work. In one case it is necessary to convert the action diagram field value to one the method will accept. The CInt function does the conversion. One common example of this is where the method needs a reference to an image stored in an Image list control. Passing in a number field from the action diagram to access an image does not work. The action diagram field has to be converted first:

       

      This example shows the code to add a parent node to a TreeView control. The images associated with the node are passed into the script in the Image and SelectedImage fields. These have to be converted using the CInt function before the Add method will accept them.

    3. Drag and Drop

      4. Implementing drag and drop has revealed an apparent inconsistency with at least one control.

      Dropping a dragged object onto the TreeView control triggers the OLEDragDrop event. This event returns a x and y coordinate of where the drop took place. A method of the control 'HitTest' converts the coordinates into a reference to a node, which can then be used to access the node's properties. During testing, the x and y coordinates returned by the event do not result in an object reference being returned by the HitTest. A factor has to be applied to the coordinates before calling the HitTest method, and this factor seems to be screen resolution dependent. The following table has the screen resolutions tested, along with the factor that works.

    Screen resolution (pixels)

    X factor

    Y factor

    640 x 480

    		 Not tested Not tested

    800 x 600

    		 Not tested Not tested

    1024 x 768

    		 Not tested Not tested

    1152 x 864

    15

    -15

    1280 x 1024

    		 Not tested Not tested
    1. Event triggering

    If an event is handled by a script subroutine and is also attached to a logical event in the panel, the action diagram event processing is executed first. This can mean that values set by the script subroutine will not be set correctly when the action diagram event is processed. In general, use the set up described above for events that return values.

     

    Wrappered functions

    The following functions have been wrappered in the pattern libraries and will be generally available in a 1998 release of Obsydian.
    To allow current users of Version 3 to see examples of implementing ActiveX as well as letting all users see what is coming in the Pattern Libraries, links to the function details and scripts are included below.
    The scripts are in a form that can be directly copied into source code objects with the appropriate parameters with the actual code in blue.