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: |
Methods | The methods defined by the ODScriptExtension class include:
|
Overridden Methods | There are no methods overridden by the ODScriptExtension class. |
This method adds a new part.
Signature
ODScrRegRet AddContainedPart (ODPart part) |
Parameters
Returns
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;
}
This method checks a component for extension support.
Signature
ODBoolean CheckComponent (ODScriptExtension scope) |
Parameters
Returns
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.
This method deregisters any objects registered for this extension.
Signature
void DeRegister (ODScriptExtension extScope,
ODBoolean doContScopes)
|
Parameters
| 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;
}
This method removes a part from the scripting environment.
Signature
void DoDeRegisterContainedPart (ODPart part,
ODScriptExtension extScope,
ODBoolean doContScopes)
|
Parameters
| 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.
This method removes an extension object from the scripting environment.
Signature
void DoDeRegisterExtension (ODScriptExtension ext,
ODBoolean doContScopes)
|
Parameters
| 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.
This method removes an object from the scripting environment.
Signature
void DoDeRegisterObject (SOMObject object,
ODScriptExtension scope,
ODBoolean doContScopes)
|
Parameters
| 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.
This method registers a class with the script component.
Signature
ODScrRegRet DoRegisterClass (string class) |
Parameters
Returns
Remarks
This method registers the specified class with the current script component. This method is usually called from Register or from 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
| kODTrue | Can add digits. |
| kODFalse | Cannot add digits. |
Returns
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.
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
| kODTrue | Can add digits. |
| kODFalse | Cannot add digits. |
Returns
Remarks
This method uses DoRegisterObjToComp to ensure that each part is registered in all containing scopes.
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
| 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.
| kODTrue | An object is to be registered. |
| kODFalse | A script extension is to be registered. |
Returns
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.
This method removes a contained part from the scripting interface.
Signature
void DropContainedPart (ODPart part) |
Parameters
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.
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.
This method writes the component's binary data to a storage unit.
Signature
void ExternalizeComponentData (long bufferSZ,
octet *buffer,
ODStorageUnit storage)
|
Parameters
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.
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.
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.
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.
This method creates the component manager object for a part.
Signature
ODBoolean GetScriptComponent (ODULong subType) |
Parameters
Returns
| 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.
This method initializes the development environment for a part.
Signature
ODBoolean InitScriptEditor () |
Parameters
None.
Returns
| 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.
This method initializes script information.
Signature
void InitScriptExtension (ODPart owner) |
Parameters
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.
This method initializes script information form persistent storage.
Signature
ODBoolean InitScriptFromStorage (ODPart owner,
ODStorageUnit storage)
|
Parameters
Returns
| 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.
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.
This method writes data to the storage unit.
Signature
ODBoolean PutComponentData (long bufferSZ,
octet *buffer)
|
Parameters
Returns
| 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.
This method registers the base part and all contained parts.
Signature
ODScrRegRet Register (ODScriptExtension regScope
string prefix)
|
Parameters
Returns
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;
This method returns component data.
Signature
ODBoolean RetrieveComponentData (long *pBufferSize,
void *pBuffer)
|
Parameters
Returns
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.
This method stores scripting information in a storage unit.
Signature
void ScriptExternalize (ODStorageUnit storage) |
Parameters
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.
This method stores the extension name.
Signature
void setExtName (string name) |
Parameters
Returns
None.
Remarks
This method frees the storage associated with any earlier name and takes ownership of the string passed.
This method sets the containing extension of an object.
Signature
void SetContainingExtension (ODScriptExtension contExt) |
Parameters
Returns
None.
Remarks
This method provides the interface to allow a containing extension object to be identified for this object.