This is XModule.h in view mode; [Download] [Up]
/* ----------------------------------------------------------------------
$Id: XModule.h,v 1.2 1993/07/19 15:25:43 doug Exp $
Description:
The XModule class serves as an abstract superclass for all External
Modules developed for use with HyperSense. It provides the basic
interface to HyperSense for such external modules.
The methods defined by the XModule class may be divided into two
major groups:
1. those which HyperSense will call to obtain information
about the XModule and to ask the XModule to provide the
services that it offers; and
2. those which provide the XModule with a way of accessing
the features of HyperSense
----- Methods Called By HyperSense -----
There are only five methods which are ever called by HyperSense.
Each subclass of XModule must override two of these methods. The
other three methods may be overridden if desired.
The two methods which every subclass of XModule must implement are:
+xCmdsAndFcns
This is a class method which advertises to HyperSense the
names of the commands and functions offered by the XModule.
-executeHandler:
This is the method called by HyperSense to ask the XModule
to perform its duties, when one of the advertised commands
or functions is called from within a SenseTalk script.
----- Methods Called By the XModule -----
The methods in this group are much more numerous, and represent all
of the "callbacks" which the external module may need to use to make
requests of HyperSense. Some of these methods request information
from HyperSense about the current document or its environment;
others request HyperSense to take some action, such as sending a
SenseTalk message, or creating an element on a page.
Many of these methods rely on a group of "proxy" objects which
represent various types of entities within the HyperSense
environment. The header file Value.h defines a set of methods which
provide a common interface to all of these objects (an "informal
protocol").
Some of the objects responding to the Value message protocol are
"containers". These objects can store almost any type of value
(string, integer, etc.), and can perform data conversion between
different types. They also provide methods for determining whether
the data stored can be converted to a particular type.
Other objects responding to the Value protocol represent various
parts of a HyperSense document. Most of these will generate error
messages if you attempt to store into them. They are used mainly to
pass the identity of a HyperSense object to another method.
Some "Value" objects are both "containers" that can be stored into,
and also represent objects within HyperSense -- namely, Fields.
----------------------------------------------------------------------
*/
#import <objc/Object.h>
#import <objc/HashTable.h>
#import <appkit/NXImage.h>
@interface XModule : Object
{
id bogusVariable;
}
+ initialize;
/*
* Methods called by HyperSense to Access and Invoke the External
* Commands & Functions
*/
+ (const char *)moduleName;
// Returns the name of this module. Can be different from the
// class/file name. If none is specified, the XModule's Class name
// is used. The name returned here will appear in the Browser in
// HyperSense.
+ (const char **) xCmdsAndFcns;
// Returns a NULL-terminated list of the names of the external
// commands and functions implemented in the module. Command names
// are all lowercase, FUNCTION names are all UPPERCASE.
+ new;
// Returns an instance of the XModule subclass. This is called by
// HyperSense only once for each subclass of XModule, to get a
// single instance of the class, to which the executeHandler:
// message will be sent.
// The default implementation simply returns [[self alloc] init]
// which should be ok in most cases.
- prepareToExecuteHandlers;
// Called before executeHandler: is called for the first time.
// The default implementation does nothing. Your subclass may
// override this behavior if additional initialization is needed
// before handling messages.
- executeHandler:(NXAtom)handlerName;
// This method is called by HyperSense each time a SenseTalk command
// or function implemented by this XModule is called from within a
// script. handlerName will be the name of the command (lowercase)
// or function (uppercase).
// Should return self or a return Value if the message is handled,
// or nil if handlerName is not recognized. If a Value object is
// returned from a command, it may be accessed as "the result" from
// within the SenseTalk script. A Value returned from a function is
// simply treated as the value of the function.
/* * * * * * * * INTERFACE METHODS PROVIDED FOR SUBCLASS USE * * * * * * */
// Note: The xstatus global indicates the status of the last interface
// method called. It is set by each interface method. (xstatus == NULL)
// means "ok". When xstatus is not NULL, it points to a string indicating
// the type of problem that occurred. This is primarily useful for debugging
// your code -- a printf call may be used to print the status string to the
// console, for example.
extern const char *xstatus;
/* Parameter Methods */
- (int)paramCount; // the number of parameters passed to the cmd or fcn
- getParam:(int)index; // get a particular parameter by number
/* Extra Container Methods */
- getEmptyContainer;
// Returns a "container" Value object. To set the return value from
// a function handler, you should obtain an empty container by
// calling this method, then store a value into it and return the
// container object as the return value from the executeHandler:
// method.
- freeContainer:container;
// If you obtain additional containers for internal use, you may
// release them by passing them to this method. This is not
// necessary, however, as HyperSense keeps track of all containers
// obtained by the XModule and frees them automatically when the
// executeHandler: method returns.
// Do not send a "free" message directly to a Value object.
/* INFORMATION REQUESTS */
// The following methods each return a special Value object which
// represents the requested object in the HyperSense document. If the
// requested object does not exist, nil is returned.
// When an enclosing object is requested, you may pass either a Value object
// representing the enclosing HyperSense object (returned by one of the
// other methods in this group), or nil. If nil is passed, HyperSense will
// follow its standard conventions for determining what the enclosing object
// must be (for example, if nil is passed as the Document when requesting a
// particular Stack, the current Document will be assumed).
- documentNamed:(const char *)name;
- stackNamed:(const char *)name inDocument:doc;
- windowFrameNamed:(const char *)name inDocument:doc;
- pageNamed:(const char *)name inStack:stack marked:(int)markFlag;
- pageNamed:(const char *)name withSharedLayer:sharedLayer
marked:(int)markFlag;
- sharedLayerNamed:(const char *)name inStack:stack;
- layerNamed:(const char *)name ofType:(int)layerType inPage:page;
- elementNamed:(const char *)name ofType:(int)elType inPageOrLayer:pgOrLyr;
- buttonNamed:(const char *)name inPageOrLayer:pgOrLyr;
- fieldNamed:(const char *)name inPageOrLayer:pgOrLyr;
- graphicNamed:(const char *)name inPageOrLayer:pgOrLyr;
- stackNumbered:(int)ordinal inDocument:doc;
- windowFrameNumbered:(int)ordinal inDocument:doc;
- pageNumbered:(int)ordinal inStack:stack marked:(int)markFlag;
- pageNumbered:(int)ordinal withSharedLayer:sharedLayer
marked:(int)markFlag;
- sharedLayerNumbered:(int)ordinal inStack:stack;
- layerNumbered:(int)ordinal ofType:(int)layerType inPage:page;
- elementNumbered:(int)ordinal ofType:(int)elType inPageOrLayer:pgOrLyr;
- buttonNumbered:(int)ordinal inPageOrLayer:pgOrLyr;
- fieldNumbered:(int)ordinal inPageOrLayer:pgOrLyr;
- graphicNumbered:(int)ordinal inPageOrLayer:pgOrLyr;
- stackID:(int)num inDocument:doc;
- windowFrameID:(int)num inDocument:doc;
- pageID:(int)num inStack:stack;
- sharedLayerID:(int)num inStack:stack;
- layerID:(int)num ofType:(int)layerType inPage:page;
- elementID:(int)num ofType:(int)elType inPageOrLayer:pgOrLyr;
- buttonID:(int)num inPageOrLayer:pgOrLyr;
- fieldID:(int)num inPageOrLayer:pgOrLyr;
- graphicID:(int)num inPageOrLayer:pgOrLyr;
/*
The following example of using these methods is equivalent to the
SenseTalk command:
put zero into field id 5 of layer 1 of page "Frank" of stack id 10425
fld = [fieldID:5
inPageOrLayer:[layerNumbered:1 ofType:XM_ANYDOMAIN
inPage:[pageNamed:"Frank"
inStack:[stackID:10425 inDocument:nil] marked:0]]];
[fld setInt:0];
*/
/* Property Methods */
- getProperty:(const char *)propName of:object inContext:page;
- setProperty:(const char *)propName of:objectOrList to:value
inContext:page;
- getGlobalProperty:(const char *)propName;
- setGlobalProperty:(const char *)propName to:value;
// The next two methods are a shortcut for obtaining an object's ID number
// and name from the Value object representing it. These are equivalent to:
// [[xmodule getProperty:"ID" of:object inContext:nil] intVal]
// [[xmodule getProperty:"NAME" of:object inContext:nil] stringVal]
- (int)objectIDOf:object;
- (const char *)nameOf:object;
// note: the pointer returned is valid until the next call to
// the nameOf: method
/* Owned Variables and Global Variables */
- getOwnedVariable:(const char *)varName of:object;
// Returns a Value object representing the requested named variable
// of object. Storing something in the Value object will make the
// variable permanent, if it is new.
- getGlobalVariable:(const char *)varName create:(BOOL)flag;
// Returns a Value object representing the requested global variable
// or nil if it doesn't exist and flag is NO.
// If flag is YES, global variable will be created if it doesn't
// exist.
/* ACTION REQUESTS */
/* Create, Delete, Select Objects */
- createDocument:(const char *)pathname fromPage:page;
// creates a normal document with 1 WindowFrame and 1 Stack, with
// shared layers copied from page
- createMinimalDocument:(const char *)pathname;
// creates a minimal document with no WindowFrames or Stacks
- createStackInDocument:doc;
- createWindowFrameInDocument:doc;
- createPageInStack:stack fromPage:oldPage;
- createSharedLayerInStack:stack;
- createUniqueLayerOnPage:page;
- createFieldInLayer:layer;
- createButtonInLayer:layer;
- createLabelInLayer:layer;
- createImageElementInLayer:layer;
- createStackViewerInLayer:layer;
- createRectangleInLayer:layer;
- createOvalInLayer:layer;
- createFreehandInLayer:layer;
- createLineInLayer:layer;
- createCopyOfElement:origElem inLayer:layer;
- addSharedLayer:layer toPage:page;
/* Sending Messages */
- (const char *)do:(const char *)format, ...;
// Equivalent to the DO command in SenseTalk. You may pass
// an actual statement (or list of statements), or create one
// by passing a printf-style format string and corresponding
// arguments.
// Returns NULL to signal success, or an error string.
- (const char *)send:(const char *)statement to:anObject;
// Equivalent to the SEND command in SenseTalk.
// Returns NULL to signal success, or an error string.
/* These sendMessage... methods return self, or nil if error.
*/
- sendMessage:(const char *)message;
// use this method to send message with no parameters
- sendMessage:(const char *)message withParameter:param;
// param is a Value object representing a single parameter
- sendMessage:(const char *)message withParameters:paramList;
// paramList is a List object containing Value parameters
/* These callFunction... methods return a Value or nil if error.
*/
- callFunction:(const char *)message;
// use this method to call a function with no parameters
- callFunction:(const char *)message withParameter:param;
// param is a Value object representing a single parameter
- callFunction:(const char *)message withParameters:paramList;
// paramList is a List object containing Value parameters
/* Resource Management */
/*
XModules allow you to store your own custom resource objects within a
Document. You specify the Resource Type, which is the category of
resource as it shows up in the Browser in HyperSense ( e.g. "Sounds",
"Images", "Widgets" -- this should be plural ). Each resource object
that is stored is assigned a HyperSense Resource ID, and an optional
Resource Name (which can be changed), which can be used to reference
the resource objects.
For all methods that take a document parameter, passing nil means the
default Document (the current or calling document).
NOTE: Do not FREE an object returned by a getResource:... call (or
resourceObjectsOfType:) as they are managed by the XModule/Document.
If you are through using a resource object, remove it from the Document
and it will be freed for you.
*/
- (const char **)resourceTypesInDocument:doc;
// Returns a NULL-terminated list of the publicly-available
// resource types in this document. Certain built-in type such
// as Stacks and WindowFrames are not publicly available.
// Caller should NOT free the returned list, as it is kept
// statically and is overwritten each time this method is called.
- resourcesOfType:(const char *)resType inDocument:doc;
// Returns HashTable of all the resources of type resType stored
// in doc, with resource ID as key, and resource name as value.
// Caller must free returned HashTable.
- resourceObjectsOfType:(const char *)resType inDocument:doc;
// Returns List object of the actual objects of type resType
// stored in doc.
// Caller must free returned List.
- getResource:(const char *)resType number:(int)resID
fromDocument:doc localOnly:(BOOL)flag;
- getResource:(const char *)resType named:(const char *)resName
fromDocument:doc localOnly:(BOOL)flag;
// Returns the actual resource object of type resType. The
// localOnly flag specifies whether to search other Documents
// in the resource path; if it is YES, then the search will
// be limited to doc. Otherwise, all documents in the resource
// path will be searched.
- (int)storeResource:anObject ofType:(const char *)resType inDocument:doc
asID:(int)resID andName:(const char *)resName;
// Stores a new resource object of type resType. If that resource
// type does not currently exist, it is created. If resID is 0,
// the object will be assigned a new unique ID.
- (const char *)nameOfResource:(const char *)resType number:(int)resID
inDocument:doc;
// Returns the name of the resource object identified by resID.
// If the object has not been given a name, returns NULL.
- (int)numberOfResource:(const char *)resType named:(const char *)resName
inDocument:doc;
// Returns the resource ID for the object identified by resName.
// If no matching object is found, returns 0.
- renameResource:(const char *)resType number:(int)resID
inDocument:doc to:(const char *)newName;
// Rename the resource to newName.
- removeResource:(const char *)resType number:(int)resID
fromDocument:doc;
// Remove the resource object. The object is not freed until
// the document is closed.
- removeResourceType:(const char *)resType fromDocument:doc;
// Remove all resource objects of type resType, and remove
// the resource type itself
/* Utility Methods */
// runAlertPanel is a cover for NXRunAlertPanel(). It displays an
// alert panel with the title and text you specify, and a single Ok button.
// The text parameter is a format string as used in printf().
// additional parameters follow the format string. For example:
//
// [xmodule runAlertPanel:"Error" text:"XModule Error: %s", xstatus ];
//
// will display the xstatus error string.
- runAlertPanel:(const char *)title text:(const char *)fmt, ...;
- abortScript;
@end
These are the contents of the former NiCE NeXT User Group NeXTSTEP/OpenStep software archive, currently hosted by Netfuture.ch.