JavaPart Enhancements

The JavaPart has been improved in this release so that it will support both Java 1.1 applets and JavaBeans. NOTE: The JavaPart is distributed only as sample source code (we do not distribute an install package) so it will be necessary to build the part on your system. Please see the readme file that is in the source directory for the JavaPart (%ODBASE%\samples\src\javapart\readme.txt) for build procedures and runtime requirement.

This release of OpenDoc includes a number of changes to scripting support from OpenDoc 1.1. This document provides informal documentation on these changes. In addition, the section Notes for Part Developers addresses questions asked since OpenDoc 1.1. Some of this information will be included in future documentation.

• Non-visual Parts supported. Your scripts can now create instances of classes that are not part of your document but that can provide useful functions for your scripts, for example, the 'Timer' part in this release. To use the Timer part your script code should include the statement:

       USELsx "SOM:ODS_Timer"
  

  in the global declarations section. This statement allows the Lotus Script Interpreter to get the descriptive information for the ODS_Timer class. Your script code can then use the 'new' operation to create an instance of that class, set its interval, attach a routine to the TimerEvent using the 'ON EVENT' statement, and start the timer. (See ODS_Timer class for details of this class.) Non-visual parts of this sort can provide any number of utility functions that can be useful to your scripts. Functions could include communications, file system operations, data base access, and so forth.

  A class which provides such an interface can be coded and packaged like any other OpenDoc part. Note that since the Timer part is not an OpenDoc 'Part' it is not included in the OpenDoc Part registry. In the package makefile, the variable 'RegKind = *NoReg' will properly control the installation of the part.

• Part names can be modified.Script developers can assign a name of their choice to your part, if your part supports the View-Properties menu option. The name set in the property window is applied to the part within the script environment. Although the name of the object is modified, any references in the script code to the old name are not modified and need to be corrected in the script window. Thus, if possible, set the names for the parts included in the application before coding references to those objects by name.
• New ScriptableGraph Part. There is a new sample part that is a scriptable version of the Graph part. This part presents a range of functions that allow the script writer to create simple graphic presentations within an OpenDoc application. See Scriptable Graph Part for a brief description of the functions provided.

• Script Interface Registration. The process of registering classes and parts with the Script Component has raised a number of questions from part developers. See Registration for additional information, rationale and examples.
• Requirements for ODConnection. If your part supports events, you may find it necessary to provide initialization logic in 'somDefaultInit' rather than 'somInit'. The ODDSConnection class uses the newer 'somDefaultInit' model. If your part uses the older 'somInit' model, the ODDSConnection intialization may not perform properly.

The Scriptable Graph Part sample part is an extension of the Graph part that provides a number of scripting methods and properties that can be used to produce graphic presentations in your document.

Common parameters

In the set of available scripting methods, there are parameters that are used similarly on several functions.

• Coordinates
  x,y or x1,y1 are generally coordinates that specify corners or endpoints for the graphic part accessed by the method.

• Handles
  A handle is a long integer that is an identifier of the object. Functions that take a handle for input, will use that handle to locate the object. In some cases, if the handle cannot be located, the function will access the containing graph part instead of a particular graphic object. Several functions take or return a handle for a graphic object.

• Color specifications
  Colors are a long integer that specify the red, green and blue components of the color. Each component can range from 0 to 255, and the three components are combined by using the following expression or an equivalent:

       ColorValue = RedVal + 256&* ( GreenVal + 256& * BlueVal)
  

  The 256& notation causes the value to be a long integer and avoids some integer overflow errors.

• Sequence
  Several methods update a 'Longsomcollection' that is a set of values that is accessed using the 'forall' statement. In all cases, the collection must be created using

       Dim Mycollection as new Longsomcollection
         OR
       Mycollection = new Longsomcollection
  

  before calling the method that takes the collection as a parameter.

• Integer Return Values
  Methods that return an integer are returning a true or false indication. True is indicated by a non-zero value. False is indicated by a zero value.

Methods

The following list of methods are available for use in scripts. The syntax is the Lotus function declarations syntax.

• Addline
  Creates a new line segment item and returns its handle.

  Addline (Byval x1 as long, Byval y1 as long,
           Byval x2 as long, Byval y2 as long,
           Byval Rgbvalue as long) as long
  

• Addpoint
  Creates a new point item and returns its handle.

  Addpoint (Byval x as long, Byval y as long,
            Rgbvalue as long) as long
  

• AddRectangle
  Creates a new rectangle item and returns its handle.

  AddRectangle (Byval x1 as long, Byval y1 as long,
                Byval x2 as long, Byval y2 as long,
                Byval Rgbvalue as long) as long
  

• Addtext
  Creates a new text item and returns its handle.

  Addtext (Byval x1 as long, Byval y1 as long,
           Byval x2 as long, Byval y2 as long,
           Byval Text as string) as long
  

• Adjust
  Moves the object addressed by 'handle' to the new coordinates.

  Adjust (Byval handle as long,
          Byval x1 as long, Byval y1 as long,
          Byval x2 as long, Byval y2 as long) as integer
  

• Countover
  Returns a count of the number of graphic items which are 'over' the specified point.

  Countover (Byval x as long, Byval y as long) as long
  

• Firstover
  Returns the handle of the first graphic item that is 'over' the specified point.

  Firstover (Byval x as long, Byval y as long) as long
  

• Getallparts
  Modifies Theparts to be a collection of handles for all the graphic items in the current Graph Part.

  Getallparts (Theparts as Longsomcollection) as integer
  

• Getbounds
  Updates x1,y2, x2 and y2 with the coordinates of the item addressed by handle.

  Getbounds (Byval handle as long,
             x1 as long, y1 as long,
             x2 as long, y2 as long) as integer
  

• Getpointlist
  Updates Thepoints to be a sequence of pairs of longs Each pair is a coordinate for the item addressed by handle.

  Getpointlist (Byval handle as long,
                Thepoints as Longsomcollection) as integer
  

• Gettypecode
  Returns a code for the type of object addressed by handle.
  • 0 = unknown or not found
  • 1 = point item
  • 2 = line item
  • 3 = rectangle item
  • 4 = text item

  Gettypecode (Byval handle as long) as long
  

• Isover
  Returns true (non-zero) if the point is over the item specified by handle.

  Isover (Byval handle as long,
          Byval x as long, Byval y as long) as integer
  

• Refresh
  Causes the specifed item and all pending updated items to be redrawn.

  Refresh (Byval handle as long)
  

• Setcolor
  Changes the color of the specified graphic item to the indicated color.

  Setcolor (Byval handle as long,
            Rgbvalue as long)
  

• Setupfont
  Provides values for all the properties that are used when a text item is created.

  Setupfont (Byval Fontheight as long,
             Byval Fontangle as long,
             Byval FontColorrgb as long,
             Byval Fontflags as long,
             Byval Fontname as string)
  

• Shift
  Moves the specified item by the distance specified by the Deltax and Deltay parameters.

  Shift (Byval handle as long,
         Byval Deltax as long, Byval Deltay as long) as integer
  

The following properties are available to control the graphic items. Most of these properties affect new text items only.

• Fontangle
  Angle, in 10ths of a degree, by which the text should be rotated counter-clockwise.

• Fontcolor
  Color for the text.

• Fontflags
  Flags that affect text alignment and folding of text. These values can be combined to specify several options (for example use 4+32 to center text both horizontally and vertically.)

        1 = Left align text
        2 = Right align text
        4 = Center align text
        8 = Top align text
       16 = Bottom align text
       32 = Vertically center text
       64 = Text is single lint
      128 = Apply wordbreak to text (multi line)
  

• Fontheight
  Height for the text.

• Fontname
  Name of the font to be used.

Included with the source for this class (in ...\samples\src\scrgraph) are three files that provide an example of how the class can be scripted. The file c_howto.txt is a description of how to use the script code in the other two files.

• Interval
  This long integer value specifies the interval between events from the timer (in milliseconds). The value must be positive or zero (zero will cause the timer to be stopped).

• Start
  This method will start the timer. The interval should have been set before calling this method. The timer will begin issuing event calls at the intervals specified.

• Stop
  This method will stop the timer. No further event calls will be made until the time is started again using the Start method.

Events

• TimerEvent
  This event will occur when the timer interval has been reached. The timer will continue to raise events until the Stop method is used to turn it off.
  Timer sample code.

  The following code is extracted from the sample that is part of the Scriptable Graph part code. It shows some of the code needed to set up, and use a timer.

      Uselsx "SOM:ODS_Timer"       ' Make the class available
      ....
      Dim theTimer As ODS_Timer    ' define a global variable to reference the timer
      ....
      Set theTimer = New ODS_Timer ' create a new Timer object
      theTimer.interval = 1000     ' interval is 1 second
      On Event TimerEvent From thetimer Call Tick ' attach subroutine to be called
      theTimer.start               ' start the timer running.
  
  

The ODSciptExtension class requires that you, as a part developer, modify the Register method to control the set of classes and objects that are exposed to the ScriptComponent (Lotus Script). There are a number of different ways of packaging your part and its function which affect the set of classes and objects that need to be registered.

While the user thinks in terms of your OpenDoc part providing methods or properties, there is nothing that requires you to register your part to the ScriptComponent. You may find it useful to provide another object that works with your part to provide an interface for scripting This interface can be simpler or more restrictive than the methods provided by your part.

Any object that has a method, event, or property that needs to be accessed from the ScriptComponent needs to be registered along with the class that defines those interfaces. If your scriptable part has such methods, then its class and the part itself need to be registered using ODScriptExtension::DoRegisterClass and ODScriptExtension::DoRegisterObject. The class registration accesses the SOM Interface Repository and gets the names of all the exposed methods, properties, and events that the class supports. The object registration tells the ScriptComponent how to locate a particular instance of that class. It is possible for your part to have several objects associated with it that need to be registered with their classes. While the samples do not illustrate this, you may find it useful.

If a part is contained within another part, then the ScriptExtension object itself will be registered as part of the process performed by AddContainedPart. This provides both the ScriptComponent and the ScriptExtensions with information needed to track containment relations, establish the structured names for the objects, and so forth.

In the following sections, we describe three ways to organize your part, its extension and perhaps some utility classes. In all cases, the same function is provided, but the code you, the part developer, produce will be different. The three variations are characterized by what object provides the scripting methods, properties, and/or events.

1. The part class provides the needed interfaces.
2. Some proxy class provides the needed interfaces.
3. The customized script extension class provides the needed interfaces.

• Part Class
  The part class is the easiest to understand and probably the easiest to develop. The sample part "ScriptableSimplePart1" (in ...\samples\src\scrsimp1) illustrates this model. If the needed interfaces for methods and properties do not already exist in your part, you need to introduce them as shown for 'setColor' and 'getColor' in the sample. To support the events (MouseDown) initialization, termination, and trigger logic must be added as well as adding ODDSConnection as an additional parent class for your part. The IDL for your class would be annotated by adding the appropriate modifiers: ODid for the exposed methods and ODevent for the events. Your customized ScriptExtension class will register and name your part (for this description we will ignore registration of contained parts).

  In the following diagram the shaded area identifies where the scripting API is defined.

  

• Proxy Class

  The proxy is probably the next easiest to understand. In this case, while the part probably provides the real function, the proxy object provides the interfaces that are exposed to the ScriptComponent. The sample part "ScriptableSimplePart2" (in ...\samples\src\scrsimp2) illustrates this model. The proxy class is defined to have the needed methods, properties, and events that you want to expose for your part's scripting interface. The implementation of those methods normally requires that one or more methods of the part be used to implement the function of the exposed method. For example, the proxy class implements SetColor by calling the part's SetColor routine.

  In addition, the part specific subclass of ODExtension needs to create the proxy, release it, and provide comunnication to and from the part class. For example, it must provide a means for the part class to invoke the "TriggerMouseDown" method of the Proxy. In this case it is the IDL of the proxy that needs to be annotated, and the ODScriptExtension needs to register the proxy class and the associated object with the ScriptComponent. In this model most of the scripting specific code is collected into the proxy class, but communication between the various objects is a little more complicated.

  

• Customized Script Extension Class

  Customization basically merges the proxy object with the subclass of ODScriptExtension. In this case (illustrated by the class "ScriptableSimplePart" in ...\samples\src\scrsimpl), the scripting methods, properties, and events are rolled into the class specific subclass of ODScriptExtension. The IDL for the ScriptExtension receives the annotation of exposed methods and events. The ScriptExtension object and the part object need to cooperate to provide the function. For example, SetColor in the Extension calls the part's SetColor, and the Part calls TriggerMouseDown in the Extension when appropriate.

  

The choice of one of the above models has an effect on how your part appears to the script developer. In particular the names that are used to reference the part will be different when your part is contained within another part.

In this last case, the ScriptExtension object is registered as Simple, and that same object provides the scripting interfaces for accessing the OpenDoc part. In the first two cases, the user can do little with the intermediate name but must retype it in all object references. This is the primary reason we recommend using this third form when your requirements allow it.

There is another side effect of the various styles that the scripting user can see: the set of classes that get registered will vary. When a class is registered with the ScriptComponent, all its parent classes are registered. Each of these three models results in a different set of classes being registered. The following figures show the set of classes that is registered when the document is just one of the variations of ScriptableSimplePart.

ScriptableSimplePart:

ScriptableSimplePart1

ScriptableSimplePart2:

OpenDoc 1.2 is compatible with SOM 3.0 on all platforms (Windows, OS/2, AIX).

The OpenDoc 1.2 product contains the SOM 2.1.4 toolkit in its install images (as did OpenDoc 1.1). However, OpenDoc 1.2 can still run using SOM 3.0. The 3.0 version of SOM must be installed after OpenDoc is installed, and must be installed over the top of the SOM 2.1.4 provided in the OpenDoc install images.

OpenDoc uses some SOMObjects that are available in SOM 2.1.4, but not in SOM 3.0. These objects still function using SOM 3.0, but are not distributed in the SOM 3.0 package. This is the reason that SOM 3.0 must be installed on top of the SOM 2.1.4 files supplied with OpenDoc.

Please refer to the following for more information:

• "OpenDoc: Programming Reference", the ODSettingsExtension class description.
• "OpenDoc: Programming Guide", the recipes for "ODSettingsExtension Programming" and "Creating an ODSettingsExtension" in the "User Interface" section of Appendix C.