Programming Reference: ODScriptExtension

# Programming Reference

## ODScriptExtension

Class Definition File | ScrExten.idl
Class C++ Binding | ScrExten.xh

Class Hierarchy

    SOMObject
       ODObject
         ODExtension
           ODScriptExtension

Description

This class is the base class for any Part-specific script extension classes.

Within a part-specific script extension class, the following modifications will normally be made:

somInit | Ensure that the ReqFlags and ReqFlagsMask are set to reflect the set of scripting component capabilities that are required for scripting that part.
Register | Override to ensure that the proper class and instance objects are registered to support the part. The default may be acceptable for simple, non-container parts. For container parts logic must be added to ensure that any contained scriptable parts are registered.
DeRegister | Override to ensure that the same objects registered are deregistered. For container parts, the overriding logic should ensure that any contained scriptable parts are deregistered.
AddContainedPart | This needs to be overridden for container parts and must provide proper registration of a single new part that has been added to this container.

Methods

The methods defined by the ODScriptExtension class include:

- AddContainedPart
- CheckComponent
- DeRegister
- DoDeRegisterContainedPart
- DoDeRegisterExtension
- DoDeRegisterObject
- DoRegisterClass
- DoRegisterContainedPart
- DoRegisterObject
- DoRegisterObjToComp
- DropContainedPart
- EndScripting
- ExternalizeComponentData
- getContainingExt
- getExtName
- getScrComp
- GetScriptComponent
- InitScriptEditor
- InitScriptExtension
- InitScriptFromStorage
- MarkChanged
- PutComponentData
- Register
- RetrieveComponentData
- ScriptExternalize
- setExtName
- SetContainingExtension

Overridden Methods | There are no methods overridden by the ODScriptExtension class.

### AddContainedPart

This method adds a new part.

Signature

    ODScrRegRet AddContainedPart (ODPart part)

Parameters

part (ODPart) - input

  The ODPart that has been added to the current object or an object contained within the current object.

Returns

rv (ODScrRegRet) - returns

  An ODScrRegRet value.

Remarks

This method is to be called when the part, a container, has a new part added to it. If the current part is scripted or has a containing part that is scripted, this call will register the new part for access by the script component.

Example Code

    SOM_Scope ODScrRegRet SOMLINK ODScrExt_AddContainedPart(
                                         ODScriptExtension *somSelf,
                                         Environment *ev,
                                         ODPart *thePart)
    {
    string assignedName;
    ODScrRegRet RetVal = ODScrRegOver ; // default code is not complete
                                        // always return error

    ODScriptExtensionData *somThis = ODScriptExtensionGetData(somSelf);
    ODScriptExtensionMethodDebug("ODScriptExtension",
                                 "ODScriptExtensionScriptExternalize");

    RetVal = _DoRegisterContainedPart (ev,
                         thePart,
                         itsName,            // needs to be supplied
                         "", somSelf,        // use these values here
                         &assignedName,      // location for returned
                                             //   name actually assigned
                         kODTrue);           // False if code here will
                                             //   handle name collisions

    if (RetVal == ODScrRegOK);
    //   add logic to properly associate the returned name with the part
    //   registered. This association must be persistent so the same name
    //   will be assigned (via Register) when we reconstruct the running
    //   object set in InitFromStorage.

    SOMFree(assignedName);    // The string returned needs to be freed.
                              // If it has been preserved, SOMFree may
                              // not be required here, but will be needed
                              // when the preserved reference is released.
    return RetVal;
    }

### CheckComponent

This method checks a component for extension support.

Signature

    ODBoolean CheckComponent (ODScriptExtension scope)

Parameters

scope (ODScriptExtension) - input

  The extension object, the scope, which is to be checked against the current scope's script component.

Returns

rv (ODBoolean) - returns

  Returns kODTrue if the script component associated with the current extension can support the requirements, as indicated by its ReqFlags and ReqFlagsMask, of the specified extension object; otherwise, kODFalse.

Remarks

If the current script component is null or its flags are not compatible with those of the indicated extension object, this method returns kODFalse. If all is compatible, returns kODTrue.

This method is used internally by script extension and is not generally used by others.

### DeRegister

This method deregisters any objects registered for this extension.

Signature

    void DeRegister (ODScriptExtension extScope,
                     ODBoolean doContScopes)

Parameters

extScope (ODScriptExtension) - input

  The ODScriptExtension that represents the scope at which deregistration is to occur; normally where the DropContainedPart is invoked.

doContScopes (ODBoolean) - input

  Indicates whether the objects should be deregistered in scopes that contain the scope specified by the extension scope contained scopes should be deregistered.

  kODTrue | Deregister in containing scopes; call from DropContainedPart.
  kODFalse | Do not deregister in containing scopes; call from EndScripting.

Returns

None.

Remarks

This method is commonly overridden for a part-specific script extension. The overriding code should ensure that the same set of objects registered are appropriately deregistered. Container parts should provide logic to ensure that any contained parts are deregistered.

Note:

> Normally overriding code would not invoke the parent class version of this code.

Example Code

    SOM_Scope void SOMLINK ODScrExt_DeRegister(
                                ODScriptExtension *somSelf,
                                Environment *ev,
                                ODScriptExtension *extScope,
                                ODBoolean doContScopes)
    {
      ODObject *basePart;

      ODScriptExtensionData *somThis = ODScriptExtensionGetData(somSelf);
      ODScriptExtensionMethodDebug("ODScriptExtension",
                                   "ODScriptExtensionDeRegister");

      // Add container part logic here to scan the list of
      // contained parts and request that they deregister with the
      // component.
      //
      // for (part=firstContainedPart, part, part=NextContainedPart)
      // {
      //   somSelf->doDeRegisterContainedPart (ev, part,
      //                                       extScope, doContScopes)
      // }

      // Deregister the current part (or if some other object was actually
      // registered to represent this part, then that part should be
      // deregistered.

      basePart = somSelf->GetBase(ev);    // get the real part object
      ExtScope->DoDeRegisterObject (ev, basePart, somSelf, doContScopes);
    return;
    }

### DoDeRegisterContainedPart

This method removes a part from the scripting environment.

Signature

    void DoDeRegisterContainedPart (ODPart part,
                                    ODScriptExtension extScope,
                                    ODBoolean doContScopes)

Parameters

part (ODPart) - input

  The part to be deregistered.

extScope (ODScriptExtension) - input

  The scope where deregistration is to begin.

doContScopes (ODBoolean) - input

  Indicates whether contained scopes should be deregistered.

  kODTrue | Deregister containing scopes.
  kODFalse | Do not deregister containing scopes.

Returns

None.

Remarks

This method provides the logic to ensure that when an object is removed from the scripting environment, it is removed from all containing scopes. This method is usually invoked from the part-specific overriding code for DeRegister.

### DoDeRegisterExtension

This method removes an extension object from the scripting environment.

Signature

    void DoDeRegisterExtension (ODScriptExtension ext,
                                ODBoolean doContScopes)

Parameters

ext (ODScriptExtension) - input

  The extension object to be deregistered at this scope.

doContScopes (ODBoolean) - input

  Indicates whether contained scopes should be deregistered.

  kODTrue | Deregister containing scopes.
  kODFalse | Do not deregister containing scopes.

Returns

None.

Remarks

This method deregisters an extension object within the current script component and ensures that any containing script components are notified. This method is normally invoked from DoDeRegisterContainedPart.

### DoDeRegisterObject

This method removes an object from the scripting environment.

Signature

    void DoDeRegisterObject (SOMObject object,
                             ODScriptExtension scope,
                             ODBoolean doContScopes)

Parameters

object (SOMObject) - input

  The object to be deregistered at this scope.

scope (ODScriptExtension) - input

  The extension object that is the level where the object is defined.

doContScopes (ODBoolean) - input

  Indicates whether the object should be deregistered in any containing scopes.

  kODTrue | Deregister containing scopes.
  kODFalse | Do not deregister containing scopes, method called from the EndScripting method.

Returns

None.

Remarks

This method provides the logic to ensure that when an object is removed from the scripting environment, it is removed from all containing This method is usually invoked from the part-specific overriding code for DeRegister.

### DoRegisterClass

This method registers a class with the script component.

Signature

    ODScrRegRet DoRegisterClass (string class)

Parameters

class (string) - input

  The string that specifies the name of the class to register.

Returns

rv (ODScrRegRet) - input

  An ODScrRegRet value.

Remarks

This method registers the specified class with the current script component. This method is usually called from Register or from DoRegisterContainedPart.

### DoRegisterContainedPart

This method registers a part with the script component.

Signature

    ODScrRegRet DoRegisterContainedPart (ODPart part,
                                         string name,
                                         string prefix,
                                         ODScriptExtension regScope,
                                         string nameUsed,
                                         ODBoolean mayAddDigits)

Parameters

part (ODPart) - input

  A reference to the part contained in the base part of this extension.

name (string) - input

  The name of the part to register.

prefix (string) - input

  The prefix applied to the name in this scope.

regScope (ODScriptExtension) - input

  The scope where registration is to begin.

nameUsed (string) - output

  A string pointer that holds the registration name. The receiver must use SOMFree to release. This parameter is not valid if registration fails.

mayAddDigits (ODBoolean) - input

  Indicates whether digits can be added if a name conflict is detected.

  kODTrue | Can add digits.
  kODFalse | Cannot add digits.

Returns

rv (ODScrRegRet) - input

  An ODScrRegRet value.

Remarks

This method establishes the current scope as the containing scope of the referenced part and requests the script component to validate that the name is unique. This method is usually called from AddContainedPart or Register.

### DoRegisterObject

This method registers an object with the script component.

Signature

    ODScrRegRet DoRegisterObject (SOMObject object,
                                  string class,
                                  string defaultName,
                                  string prefix,
                                  string nameUsed,
                                  ODScriptExtension scope,
                                  ODBoolean mayAddDigits)

Parameters

object (SOMObject) - input

  The object to be registered for scripting.

class (string) - input

  The class name of the object to register.

defaultName (string) - input

  The name to be assigned to the object.

prefix (string) - input

  The prefix applied to the name in this scope.

nameUsed (string) - output

  A pointer to the address that holds the registration name. The receiver must use SOMFree to release. This parameter is not valid if registration fails.

scope (ODScriptExtension) - input

  The extension where this object is declared.

mayAddDigits (ODBoolean) - input

  Indicates whether digits can be added if a name conflict is detected.

  kODTrue | Can add digits.
  kODFalse | Cannot add digits.

Returns

rv (ODScrRegRet) - input

  An ODScrRegRet value.

Remarks

This method uses DoRegisterObjToComp to ensure that each part is registered in all containing scopes.

### DoRegisterObjToComp

This method registers an object with the scripting environment.

Signature

    ODScrRegRet DoRegisterObjToComp (SOMObject object,
                                     string class,
                                     string defaultName,
                                     string prefix,
                                     string nameUsed,
                                     ODScriptExtension scope,
                                     ODBoolean mayAddDigits,
                                     ODBoolean registeringObject)

Parameters

object (SOMObject) - input

  The object to be registered for scripting.

class (string) - input

  The class name of the object to register.

defaultName (string) - input

  The name to be assigned to the object.

prefix (string) - input

  The prefix applied to the name in this scope.

nameUsed (string) - output

  The returned name used for this object. The receiver must use SOMFree to release. This parameter is not valid if registration fails.

scope (ODScriptExtension) - input

  The extension where this object is declared.

mayAddDigits (ODBoolean) - input

  Indicates whether digits can be added if a name conflict is detected.

  kODTrue | Can add digits.
  kODFalse | Cannot add digits.

  This method provides a service that, if the script component reports the registered name is a duplicated, will add a digit string to the end of the name until a non-duplicate name is produced.

registeringObject (ODBoolean) - input

  Indicates whether the object to be registered is an object or a script extension.

  kODTrue | An object is to be registered.
  kODFalse | A script extension is to be registered.

Returns

rv (ODScrRegRet) - input

  An ODScrRegRet value.

Remarks

This method ensures that each part registered is properly registered in all containing scopes. This logic is for both the DoRegisterObject and DoRegisterContainedPart with the appropriate component or containing extension routine being called respectively.

### DropContainedPart

This method removes a contained part from the scripting interface.

Signature

    void DropContainedPart (ODPart part)

Parameters

part (ODPart) - input

  The ODPart that has been removed from the current object or an object contained within the current object.

Returns

None.

Remarks

This method is called when the part, a container, has a contained part removed. If the current part is scripted or has a containing part that is scripted, the registration of the part is dropped from the scripting interface.

### EndScripting

This method removes scripting associated with a part.

Signature

    void EndScripting ()

Parameters

None.

Returns

None.

Remarks

This method is invoked when the user determines that the script associated with this part is to be removed. The method will deregister this part and all contained parts at this scope, remove any persistent information for this extension, and remove the script component associated with this extension.

### ExternalizeComponentData

This method writes the component's binary data to a storage unit.

Signature

    void ExternalizeComponentData (long bufferSZ,
                                   octet *buffer,
                                   ODStorageUnit storage)

Parameters

bufferSZ (long) - input

  The size of the component data block. If this value is 0, any existing data is removed. If this value is <0, the existing data is not modified. If this value is >0, any existing data is replaced with the data from the buffer.

buffer (octet *) - input

  The location of the component data block.

storage (ODStorageUnit) - input

  The storage unit to receive the data.

Returns

None.

Remarks

This method causes the data in the indicated buffer to be written to the storage unit as binary data. If the length is negative, the component's data has not changed since the last time it was retrieved and the storage unit should not be updated. If the length is zero, there is no data to be written and any prior value is to be purged. If the length is positive, the indicated data will be written to the storage unit. This routine is usually invoked from ScriptExternalize or PutComponentData method.

### getContainingExt

This method returns the containing extension of the object.

Signature

    ODScriptExtension getContainingExt ()

Parameters

None.

Returns

The ODScriptExtension representing the containing environment. The ODScriptExtension object associated with the part that contains the part associated with the script extension.

Remarks

This method returns the containing extension object.

### getExtName

This method returns the extension name.

Signature

    script getExtName ()

Parameters

None.

Returns

A pointer to the name assigned to this extension.

Remarks

This method returns the name of the extension. This name is persistent and can be used to reestablish the object name when it is reloaded.

### getScrComp

This method returns the script component of an extension.

Signature

    ODScriptComponent getScrComp ()

Parameters

None.

Returns

The ODScriptComponent associated with this extension.

Remarks

This method returns the script component of this extension.

### GetScriptComponent

This method creates the component manager object for a part.

Signature

    ODBoolean GetScriptComponent (ODULong subType)

Parameters

subType (ODULong) - input

  The subtype code for the required component. This value may be NULL if not known.

Returns

rv (ODBoolean) - returns

  Indicates whether the _ScrComp is set to a reference to an ODScriptComponent object.

  kODTrue | Reference set.
  kODFalse | Reference not set.

Remarks

This method uses the component manager to obtain an instance of an ODScriptComponent that supports the requirements of this part. If it is unable to obtain such an object, it will report an error and return kODFalse. This method is usually invoked from InitPartFromStorage or InitScriptEditor.

### InitScriptEditor

This method initializes the development environment for a part.

Signature

    ODBoolean InitScriptEditor ()

Parameters

None.

Returns

rv (ODBoolean) - returns

  Indicates whether the environment was initialized.

  kODTrue | Initialization successful.
  kODFalse | Initialization unsuccessful.

Remarks

This method initializes the development environment for the current part. The class of the current part, the class of any contained parts, the current part and the contained parts will be registered with the script component.

### InitScriptExtension

This method initializes script information.

Signature

    void InitScriptExtension (ODPart owner)

Parameters

owner (ODPart) - input

  The base ODPart that is the owner of this extension part.

Returns

None.

Remarks

This method provides initialization when there is no persistent form of the script information.

Note:

> This method should only be called once when the object is initialized.

### InitScriptFromStorage

This method initializes script information form persistent storage.

Signature

    ODBoolean InitScriptFromStorage (ODPart owner,
                                     ODStorageUnit storage)

Parameters

owner (ODPart) - input

  The base ODPart that is the owner of this extension part.

storage (ODStorageUnit) - input

  The ODStorageUnit that contains the persistent form of the script information as produced by the ScriptExternalize method.

Returns

rv (ODBoolean) - returns

  Indication whether the method was successful.

  kODTrue | Successful completion.
  kODFalse | Unsuccessful completion.

Remarks

The method provides initialization when there is a persistent form of the script information. The kODPropAttachedScriptType property is used to store the following values attached to the script.

- kODDSExtensionNamesValue is a string holding the name assigned to the extension.

- kODDSComponentIdValue is a string holding the subtype code for the supporting component. This value is not present if no component is in use with the current extension object.

- kODDSComponentDataValue holds a binary large object that is the persistent data that the component needs to save. This value is not present if no component is in use with the current extension object.

### MarkChanged

This method marks the document as modified.

Signature

    void MarkChanged ()

Parameters

None.

Returns

None.

Remarks

This method should be invoked by the attached script component to indicate that the scripts have been modified.

### PutComponentData

This method writes data to the storage unit.

Signature

    ODBoolean PutComponentData (long bufferSZ,
                                octet *buffer)

Parameters

bufferSZ (long) - input

  The size of the component data block.

buffer (octet *) - input

  The location of the component data block.

Returns

rv (ODBoolean) - returns

  Indication whether the data was written to the storage unit.

  kODTrue | Successful completion.
  kODFalse | Unsuccessful completion.

Remarks

The method accesses the storage unit for this part and will cause the data supplied to be written to the component's data in the storage unit. If the length is less than or equal to zero, there is a special meaning. See ExternalizeComponentData

This method is intended to be called by the component when it identifies a need to save the current script data, generally in response to a user action.

### Register

This method registers the base part and all contained parts.

Signature

    ODScrRegRet Register (ODScriptExtension regScope
                          string prefix)

Parameters

regScope (ODScriptExtension) - input

  The script extension object that represents the context where registration is to begin. This will be the current extension object of some container of that object. Objects to be registered for this extension should be passed to the extension indicated by this argument for registration.

prefix (string) - input

  A string that hold the name prefix to be applied to all names at the current scope when registering to the extension specified by the regScope parameter.

Returns

rv (ODScrRegRet) - returns

  An ODScrRegRet values.

Remarks

This method is commonly overridden in the extension for a specific part. The overriding code can provide a different default name, add logic to register support classes and instances, and, for container parts, should include logic to initiate the registration of all contained scriptable parts.

Note:

> Normally, the overriding code for this method would not invoke the logic of the parent class.

Example Code

    SOM_Scope ODScrRegRet SOMLINK ODScrExt_Register(ODScriptExtension *somSelf,
                                                    Environment *ev,
                                                    ODScriptExtension *regScope,
                                                    string Prefix);
    {
    ODScrRegRet RetVal = ODScrRegOK;
    ODObject* basepart;
    char*     classname;
    char*     nameAssigned;

    ODScriptExtensionData *somThis = ODScriptExtensionGetData(somSelf);
    ODScriptExtensionMethodDebug("ODScriptExtension","ODScriptExtensionRegister");

This default code will register the ODPart and its class as the part that supplies the scripting interface. The name used is the PartName property if that is defined or the class name. For a part that is not a container, there should never be a name conflict, however in the case of a container or a Part that registers several objects, it is possible that a name conflict could be identified by the scripting component. If that error is encountered, we generate a unique name by appending a number onto the name.

    basepart = somSelf ->GetBase(ev);

The class for each scriptable object needs to be registered with the script component.

    className = basepart->somGetClassName();
    RetVal = RegScope->DoRegisterClass(ev, className);
    if (RetVal !=ODScrRegOK)
    { return RetVal; }

DoRegisterObject can take care of most normal naming issues. It is called here with the option that will append a numeric string to that name if needed to make the name unique.

    RetVal = RegScope->DoRegisterObject(ev,
                      basepart,            // the object to be scriptable
                      className,           // the class name of that object
                      className,           // the default name to be used
                      Prefix,              // prefix that applies in the scope
                                           //   where registration begins
                      &nameAssigned,       // receives name actually assigned
                      somSelf,             // the scope/extension of the object
                      kODTrue);            // digits to be appended to make the
                                           // name unique, if needed

    if (RetVal == ODScrRegOK)              // if registration was successful, we
    { SOMFree(nameAssigned) ; }            //  should save name with the object
                                           //  so it can be preserved to the
                                           //  storage unit and restored for
                                           //  assignment after initialization.
                                           //  part for the default case, we
                                           //  skip that logic and assume that
                                           //  the name actually used will be
                                           //  the name we requested (i.e. the
                                           //  same as the class name) and that
                                           //  the same will happen on any
                                           //  registration after InitFromStorage.

If it is necessary or desirable for some part, additional classes or objects can be registered. This could include related, non-document parts, utilities, and so forth.

For container parts, logic should be added here to scan the list of contained parts, and request that they be registered. DoRegisterContainedPart will verify that the part is scriptable and if so will initiate the registration of that part.

The pseudo functions FirstContainedPart and NextContainedPart would have to be replaced with logic specific to the container part.

    // for (part=FirstContainedPart, part, part=NextContainedPart)
    // {
    //   RetVal =
    //     _DoRegisterContainedPart(part, partname, thePrefix, RegScope
    //                              &nameUsed, mayAddDigits);
    //   if (RetVal ...

If registration is successful, the name assigned needs to be properly associated with the object. That association must be persistent and should have been used to get the name for registration before the call to _DoRegisterContainedPart. At some point the string returned in nameUsed must be released using SOMFree.

     }

    return RetVal;

### RetrieveComponentData

This method returns component data.

Signature

    ODBoolean RetrieveComponentData (long *pBufferSize,
                                     void *pBuffer)

Parameters

pBufferSize (long *) - input

  A pointer to a long integer that holds the size of the buffer passed.

pBuffer (void *) - in/out

  A pointer to the buffer to receive the data read.

Returns

rv (ODScrRegRet) - returns

  Indicates whether the information was read from the buffer. BufferSize is set to reflect the size of the data for the component and buffer receives the data. If Buffer is not large enough for the data, no data is transferred and the return value is kODFalse.

Remarks

This method returns the binary large object that represents the component's persistent data. This function is designed to be called from the component. To get the required size for the binary object, the component calls this routine with a buffer and a size. If the buffer is large enough, it will be read into the buffer. In all cases, the size will be updated to reflect the size of the data.

If the data is read into the supplied buffer, the return value is kODTrue. If the buffer is not large enough or if there is no data to be read, the size will be updated, zero if there is no data, and the return value will be kODFalse.

### ScriptExternalize

This method stores scripting information in a storage unit.

Signature

    void ScriptExternalize (ODStorageUnit storage)

Parameters

storage (ODStorageUnit) - input

  The ODStorageUnit to contain the scripting information for the current part.

Returns

None.

Remarks

This method updates the script information in the storage unit.

The scripting information for the current part, and its contained parts, will be placed in the storage unit specified. This routine will place the kODPropAttachedScriptType property in the storage unit and will add the value entries for kODDSExtensionNamesValue to reflect the names assigned to the part. If there is a script component associated with the extension, the value of kODDSComponentIdValue will be added with a value of the supported component's subtype. If there is component data to be saved, the value of kODDSComponentDataValue will be added to contain the binary value.

### setExtName

This method stores the extension name.

Signature

    void setExtName (string name)

Parameters

name (string) - input

  A string pointer to the new name for this extension.

Returns

None.

Remarks

This method frees the storage associated with any earlier name and takes ownership of the string passed.

### SetContainingExtension

This method sets the containing extension of an object.

Signature

    void SetContainingExtension (ODScriptExtension contExt)

Parameters

contExt (ODScriptExtension) - input

  A pointer to the script extension for a containing part.

Returns

None.

Remarks

This method provides the interface to allow a containing extension object to be identified for this object.

[ Top | Previous | Next | Contents | Index | Documentation Homepage ]