Declared in: dpsclient/dpsNeXT.h
Synopsis:
void DPSAddFD(int fd, DPSFDProc handler, void *userData, int priority)
Description:
DPSAddFD registers the function handler to be called each time there is activity with the file
specified by file descriptor fd. The function is called provided the following are true:
open. There needn't be any data waiting to be read on fd.DPSAddTimedEntry for a further explanation.
void *handler(int fd, void *userData)
where fd is the file descriptor that prompted the function call and userData is the same pointer that was passed as the third argument to DPSAddFD. The userData pointer is provided as a convenience, allowing you to pass arbitrary data to handler.
Typically, DPSAddFD is used to listen to a socket or pipe; it's rarely used to monitor a common file.
See also:
DPSAddPort, DPSAddTimedEntry, DPSRemoveFD
Declared in: dpsclient/dpsNeXT.h
Synopsis:
void DPSAddNotifyPortProc(DPSPortProc handler, void *userData)
Description:
DPSAddNotifyPortProc registers handler as the function that's called when a message arrives
on the notify port, the unique port, created through the task_notify Mach function, on which
notifications (such as port death) are sent. You don't need to create the notify port yourself;
DPSAddNotifyPortProc creates it for you if it doesn't already exist.
DPSPortProc, handler's defined type, takes the form
void *handler(msg_header_t *msg, void *userData)
where msg is a pointer to the message that was received at the port and userData is the same pointer that was passed as the second argument to DPSAddNotifyPortProc. The userData pointer is provided as a convenience, allowing you to pass arbitrary data to handler.
The notify port can have only one handler at a time; adding a handler removes the current one. You can remove the port's handler without specifying a new one with the DPSRemoveNotifyPortProc function. The function's argument must match the notify port's current handler.
See also:
DPSAddPort, DPSAddTimedEntry, DPSRemoveNotifyPortProc
Declared in: dpsclient/dpsNeXT.h
Synopsis:
void DPSAddPort(port_t port, DPSPortProc handler, int maxMsgSize, void *userData, int priority)
Description:
DPSAddPort registers the function handler to be called each time your application asks for an
event or peeks at the event queue. The function is called provided the following are true:
DPSAddTimedEntry for a further explanation.
void *handler(msg_header_t *msg, void *userData)
where msg is a pointer to the message that was received at the port and userData is the same pointer that was passed as the fourth argument to DPSAddPort. The userData pointer is provided as a convenience, allowing you to pass arbitrary data to handler.
If, within handler, you want to call msg_receive to receive further messages at the port, you must first call DPSRemovePort to remove the port from the system's port set. (This is because your application can't receive messages from a port that's in a port set.) After your application is finished receiving messages directly from the port, it can call DPSAddPort to have the system continue to monitor the port.
The contents of the message buffer msg, as received by handler, are invalid after the function returns. If you need to save any of the information that you find.
The maxMsgSize argument is an integer that gives the size, in bytes, of the largest message you expect to receive.
See also:
DPSAddFD, DPSAddTimedEntry, DPSRemovePort
Declared in: dpsclient/dpsNeXT.h
Synopsis:
DPSTimedEntry DPSAddTimedEntry(double period, DPSTimedEntryProc handler, void *userData, int priority)
Description:
DPSAddTimedEntry registers handler as a "timed entry," a function that's called repeatedly at a
given time interval. period determines the number of seconds between calls to the timed entry.
Whenever an application based on the Application Kit attempts to retrieve events from the event
queue, it also checks (depending on priority) to determine whether any timed entries are due to be
called. userData is a pointer that you can use to pass some data to the timed entry.
The function registered as handler has the form:
void *handler(DPSTimedEntry tag, double now, void *userData)
where tag is the timed entry identifier returned by DPSAddTimedEntry, now is the number of seconds since some arbitrary point in the past, and userData is the pointer DPSAddTimedEntry received when this timed entry was installed.
An application's priority threshold can be set explicitly as an integer from 0 to 31 through a call to DPSGetEvent or DPSPeekEvent. It's against this threshold that priority is measured (note that priority can be no greater than 30-the additional threshold level, 31, is provided to disallow all inter-event function calls). However, if you're using the Application Kit, you should access the event queue through Application class methods such as getNextEvent:. Although some of these methods let you set the priority threshold explicitly, you typically invoke the methods that set it automatically. Such methods use only three priority levels:
Constant
| Meaning |
|---|---|
| NX_BASETHRESHOLD | Normal execution |
| NX_RUNMODALTHRESHOLD | An attention panel is being run |
| NX_MODALRESPTHRESHOLD | A modal event loop is being run |
When applicable, you should use these constants as the value for priority. For example, if you want handler to be called during normal execution, but not if an attention panel or a modal loop is running, then you would set priority to NX_BASETHRESHOLD.
Return:
DPSAddTimedEntry returns a number identifying the timed entry or -1 to indicate an error.
See also:
DPSRemoveTimedEntry
Declared in: dpsclient/dpsNeXT.h
Synopsis:
void DPSAsynchronousWaitContext(DPSContext context, DPSPingProc handler,
void *userData)
Description:
This function is similar to the more familiar DPSWaitContext functions, except that rather than
wait for all PostScript code to execute, it returns immediately, allowing your application to
proceed while the PostScript code is executed in the background. The DPSPingProc function
handler is called (with context and userData as its two arguments) when all the PostScript code
has been executed. The DPSPingProc function takes the form
void *handler(DPSContext context, void *userData);
Declared in: dpsclient/dpsNeXT.h
Synopsis:
DPSContext DPSCreateContext(const char *hostName, const char *serverName, DPSTextProc textProc, DPSErrorProc errorProc)
Description:
DPSCreateContext establishes a connection with the Window Server and creates a PostScript
execution context in it. The new context becomes the current context. The first argument,
hostName, identifies the machine that's running the Window Server; the second argument,
serverName, identifies the Window Server that's running on that machine. With these two
arguments and the help of the Mach network server nmserver, the Mach port for the Window
Server can be identified. If hostName is NULL, the network server on the local machine is queried
for the Window Server's port. If serverName is NULL, a default name for the Window Server is
used.
The last two arguments, textProc and errorProc, refer to call-back functions (defined in the Client Library specification) that handle text returned from the Window Server and errors generated on either side of the connection.
For an application that's based on the Application Kit, you could create an additional context by making this call:
DPSContext c;
c = DPSCreateContext(NXGetDefaultValue([NXApp appName], "NXHost"),
XGetDefaultValue([NXApp appName], "NXPSName"),
NULL,
NULL);
This example queries the application's default values for the identity of the host machine and the Window Server. By doing this, the new context is created in the correct Window Server even if that Server is not on the same machine as the application process.
The context that DPSCreateContext creates allocates memory from the default allocation zone. Also, when there's difficulty creating the context, DPSCreateContext waits up to 60 seconds before raising an exception. If you want to change either of these parameters, use DPSCreateContextWithTimeoutFromZone. Its two additional arguments let you specify the zone for the context to use when allocating context-specific data and a timeout value in milliseconds.
This function returns the newly created DPSContext structure.
Exceptions:
DPSCreateContext raises a dps_err_outOfMemory exception if it encounters difficulty
allocating ports or other resources for the new context. It raises a dps_err_cantConnect exception
if it can't return a context within the timeout period.
See also:
DPSCreateContextWithTimeoutFromZone, DPSCreateNonsecureContext,
DPSCreateStreamContext
Declared in: dpsclient/dpsNeXT.h
Synopsis:
DPSContext DPSCreateContextWithTimeoutFromZone(const char *hostName, const char *serverName, DPSTextProc textProc, DPSErrorProc errorProc, int timeout, NSZone *zone)
Description:
DPSCreateContextWithTimeoutFromZone is identical to DPSCreateContext except that it
accepts two additional arguments that let you specify the zone to use when allocating
context-specific data and a timeout value other than the default value of 60 seconds. Specify the
new timeout value in milliseconds,
This function returns the newly created DPSContext structure.
Exceptions:
DPSCreateContextWithTimeoutFromZone raises a dps_err_outOfMemory exception if it
encounters difficulty allocating ports or other resources for the new context. It raises a
dps_err_cantConnect exception if it can't return a context within the timeout period.
See also:
DPSCreateContext, DPSCreateNonsecureContext, DPSCreateStreamContext
Declared in: dpsclient/dpsNeXT.h
Synopsis:
DPSContext DPSCreateNonsecureContext(const char *hostName, const char *serverName, DPSTextProc textProc, DPSErrorProc errorProc, int timeout, NSZone *zone)
Description:
DPSCreateNonsecureContext creates a "nonsecure" context in which you can use PostScript
operators that are normally disallowed. The most significant of these are operators that let you
write files.
Few programmers will need to call this function directly: The Application Kit manages contexts for programs based on the Kit. For example, when an application is launched, its Application object calls DPSCreateContext to create a context in the Window Server. Similarly, to print a View the Kit calls DPSCreateStreamContext to temporarily redirect PostScript code from the View to a stream.
This function returns the newly created DPSContext structure.
See also:
DPSCreateContext, DPSCreateContextWithTimeoutFromZone, DPSCreateStreamContext
Declared in: dpsclient/dpsNeXT.h
Synopsis:
DPSContext DPSCreateStreamContext(NXStream *stream, int debugging, DPSProgramEncoding progEnc, DPSNameEncoding nameEnc, DPSErrorProc errorProc)
Description:
DPSCreateStreamContext is similar to DPSCreateContext, except that the new context is
actually a connection from the client application to a stream. This connection becomes the current
context. PostScript code that the application generates is sent to the stream rather than to the
Window Server. The first argument, stream, is a pointer to an NXStream structure, as created by
NXOpenFile or NXMapFile. The debugging argument is intended for debugging purposes but is
not currently implemented. progEnc and nameEnc specify the type of program and user-name
encodings to be used for output to the stream. The last argument, errorProc, identifies the
procedure that's called when errors are generated.
Few programmers will need to call this function directly: The Application Kit manages contexts for programs based on the Kit. For example, when an application is launched, its Application object calls DPSCreateContext to create a context in the Window Server. Similarly, to print a View the Kit calls DPSCreateStreamContext to temporarily redirect PostScript code from the View to a stream.
This function returns the newly created DPSContext structure.
See also:
DPSCreateContext, DPSCreateContextWithTimeoutFromZone,
DPSCreateNonsecureContext
Declared in: dpsclient/dpsNeXT.h
Synopsis:
int DPSDefineUserObject(int index)
Description:
DPSDefineUserObject associates index with the PostScript object that's on the top of the operand
stack, thereby creating a user object (as defined by the PostScript language). If index is 0, the
object is assigned the next available index number. The function returns the new index, which can
then be passed to a pswrap-generated function that takes a user object.
DPSDefineUserObject rather than the PostScript operator defineuserobject
or the single-operator functions DPSdefineuserobject and PSdefineuserobject.
Return:
DPSDefineUserObject, if successful in assigning an index, returns the index that the object was
assigned. If unsuccessful, it returns 0.
See also:
DPSUndefineUserObject
Declared in: dpsclient/dpsNeXT.h
Synopsis:
void DPSDiscardEvents(DPSContext context, int mask)
Description:
DPSDiscardEvents's two parameters, context and mask, are the same as those for DPSGetEvent
and DPSPeekEvent. DPSDiscardEvents removes from the application's event queue those
records whose event types match mask and whose context matches context.
Return:
DPSGetEvent and DPSPeekEvent return 1 if they are successful in accessing an event record and
0 if they aren't.
See also:
DPSGetEvent, DPSPeekEvent, DPSAddFD, DPSAddPort, DPSAddTimedEntry,
DPSPostEvent
Declared in: dpsclient/dpsNeXT.h
Synopsis:
void DPSDoUserPath(void *coords, int numCoords, DPSNumberFormat numType, unsigned char *ops, int numOps, void *bbox, int action)
Description:
DPSDoUserPath sends an encoded user path to the Window Server and then executes, upon that
path, the operator specified by action. The use of this function, rather than the analogous
step-by-step path construction, is encouraged; rendering an encoded path is much more efficient
than executing the individual PostScript operators that would otherwise be needed.
An encoded user path consists of an array of coordinate values, a sequence of PostScript operators, and a bounding box specification. The values in the coordinate array are used as operands to the operators; the operands are distributed to the operators in the order that they're given. The resulting path must fit within the bounding box.
The coordinates, operators, and bounding box are given by the function's first five arguments:
setbbox operator. (If you don't supply a setbbox as part of the ops sequence, one is inserted for you.)
Constant Meaning
dps_float single-precision floating-point number
dps_long 32-bit integer
dps_short 8-bit integer
You can also specify 16- and 32-bit fixed-point real numbers. For 16-bit fixed-point numbers, use dps_short plus the number of bits in the fractional portion. For 32-bit fixed-point numbers, use dps_long plus the number of bits in the fractional portion.
These constants are provided for ops:
dps_setbbox
dps_moveto
dps_rmoveto
dps_lineto
dps_rlineto
dps_curveto
dps_rcurveto
dps_arc
dps_arcn
dps_arct
dps_closepath
dps_ucache
Once the user path has been constructed, the operator specified by action is executed. The value of action is an index into Display PostScript's encoded system names; the following constants, provided as a convenience, represent the most commonly used actions:
dps_uappend
dps_ufill
dps_ueofill
dps_ustroke
dps_ustrokepath
dps_inufill
dps_inueofill
dps_inustroke
dps_def
dps_put
The following program fragment demonstrates the use of DPSDoUserPath as it creates and strokes a user path (an isosceles triangle) within a bounding rectangle whose lower left corner is located at (0, 0) and whose width and height are 200.
short coords[6] = {0, 0, 200, 0, 100, 200};
char ops[4] = {dps_moveto, dps_lineto,dps_lineto, dps_closepath};
short bbox[4] = {0, 0, 200, 200};
DPSDoUserPath(coords, 6, dps_short, ops, 4, bbox, dps_ustroke);
Note:
If an application calls DPSDoUserPath with large values (~10,000-20,000) of numCoords
and/or numOps, it may generate a Display PostScript error.
See also:
DPSDoUserPathWithMatrix
Declared in: dpsclient/dpsNeXT.h
Synopsis:
void DPSDoUserPathWithMatrix(void *coords, int numCoords, DPSNumberFormat numType, unsigned char *ops, int numOps, void *bbox, int action, float matrix[6])
Description:
DPSDoUserPathWithMatrix sends an encoded user path to the Window Server and then
executes, upon that path, the operator specified by action. The use of this function, rather than the
analogous step-by-step path construction, is encouraged; rendering an encoded path is much more
efficient than executing the individual PostScript operators that would otherwise be needed.
An encoded user path consists of an array of coordinate values, a sequence of PostScript operators, and a bounding box specification. The values in the coordinate array are used as operands to the operators; the operands are distributed to the operators in the order that they're given. The resulting path must fit within the bounding box.
The coordinates, operators, and bounding box are given by the function's first five arguments:
setbbox operator. (If you don't supply a setbbox as part of the ops sequence, one is inserted for you.)
Constant Meaning
dps_float single-precision floating-point number
dps_long 32-bit integer
dps_short 8-bit integer
You can also specify 16- and 32-bit fixed-point real numbers. For 16-bit fixed-point numbers, use dps_short plus the number of bits in the fractional portion. For 32-bit fixed-point numbers, use dps_long plus the number of bits in the fractional portion.
These constants are provided for ops:
dps_setbbox
dps_moveto
dps_rmoveto
dps_lineto
dps_rlineto
dps_curveto
dps_rcurveto
dps_arc
dps_arcn
dps_arct
dps_closepath
dps_ucache
Once the user path has been constructed, the operator specified by action is executed. The value of action is an index into Display PostScript's encoded system names; the following constants, provided as a convenience, represent the most commonly used actions:
dps_uappend
dps_ufill
dps_ueofill
dps_ustroke
dps_ustrokepath
dps_inufill
dps_inueofill
dps_inustroke
dps_def
dps_put
DPSDoUserPathWithMatrix's matrix argument represents the transformation matrix operand used by the ustroke, inustroke, and ustrokepath operators. If matrix is NULL, the argument is ignored.
See also:
DPSDoUserPath
Declared in: dpsclient/dpsNeXT.h
Synopsis:
void DPSFlush
Description:
DPSFlush flushes the application's output buffer, forcing any buffered PostScript code or data to
the Window Server.
See also:
DPSSendEOF
Declared in: dpsclient/dpsNeXT.h
Synopsis:
int DPSGetEvent(DPSContext context, NXEvent *anEvent, int mask, double timeout, int threshold)
Description:
DPSGetEvent and DPSPeekEvent are macros that access event records in an application's event
queue. These routines are provided primarily for programs that don't use the Application Kit. An
application based on the Kit should use the corresponding Application class methods (such as
getNextEvent: and peekNextEvent:into:) or the function NXGetOrPeekEvent so that it can be
journaled. DPSDiscardEvents removes all event records of a specified type from the queue.
DPSGetEvent and DPSPeekEvent differ only in how they treat the accessed event record. DPSGetEvent removes the record from the queue after making its data available to the application; DPSPeekEvent leaves the record in the queue.
DPSGetEvent and DPSPeekEvent take the same parameters. The first, context, represents a PostScript execution context within the Window Server. Virtually all applications have only one execution context, which can be returned using DPSGetCurrentContext. Applications having more than one execution context can use the constant DPS_ALLCONTEXTS to access events from all contexts belonging to them.
The second argument, anEvent, is a pointer to an event record. If DPSGetEvent or DPSPeekEvent is successful in accessing an event record, the record's data is copied into the storage referred to by anEvent.
mask determines the types of events sought. See the section "Types and Constants" for a list of the constants that represent the event type masks. To check for more than one type of event, you combine individual constants using the bitwise OR operator.
If an event matching the event mask isn't available in the queue, DPSGetEvent or DPSPeekEvent waits until one arrives or until timeout seconds have elapsed, whichever occurs first. The value of timeout can be in the range of 0.0 to NX_FOREVER. If timeout is 0.0, the routine returns an event only if one is waiting in the queue when the routine asks for it. If timeout is NX_ FOREVER, the routine waits until an appropriate event arrives before returning.
The last argument, threshold, is an integer in the range 0 through 31 that determines which other services may be provided during a call to DPSGetEvent or DPSPeekEvent.
Requests for services are registered by the functions DPSAddTimedEntry, DPSAddPort, and DPSAddFD. Each of these functions takes an argument specifying a priority level. If this level is equal to or greater than threshold, the service is provided before DPSGetEvent or DPSPeekEvent returns.
Return:
DPSGetEvent returns 1 if it is successful in accessing an event record and 0 if it isn't.
See also:
DPSPeekEvent, DPSDiscardEvents, DPSAddFD, DPSAddPort, DPSAddTimedEntry,
DPSPostEvent
Declared in: dpsclient/dpsNeXT.h
Synopsis:
const char *DPSNameFromTypeAndIndex(short type, int index)
Description:
DPSNameFromTypeAndIndex returns the text associated with index from the system or user
name table. If type is -1, the text is returned from the system name table; if type is 0, it's returned
from the user name table.
The name tables are used primarily by the Client Library and pswrap; few programmers will access them directly.
Return: This function returns a read-only character string.
Declared in: dpsclient/dpsNeXT.h
Synopsis:
int DPSPeekEvent(DPSContext context, NXEvent *anEvent, int mask, double timeout, int threshold)
Description:
DPSGetEvent and DPSPeekEvent are macros that access event records in an application's event
queue. These routines are provided primarily for programs that don't use the Application Kit. An
application based on the Kit should use the corresponding Application class methods (such as
getNextEvent: and peekNextEvent:into:) or the function NXGetOrPeekEvent so that it can be
journaled. DPSDiscardEvents removes all event records of a specified type from the queue.
DPSGetEvent and DPSPeekEvent differ only in how they treat the accessed event record. DPSGetEvent removes the record from the queue after making its data available to the application; DPSPeekEvent leaves the record in the queue.
DPSGetEvent and DPSPeekEvent take the same parameters. The first, context, represents a PostScript execution context within the Window Server. Virtually all applications have only one execution context, which can be returned using DPSGetCurrentContext. Applications having more than one execution context can use the constant DPS_ALLCONTEXTS to access events from all contexts belonging to them.
The second argument, anEvent, is a pointer to an event record. If DPSGetEvent or DPSPeekEvent is successful in accessing an event record, the record's data is copied into the storage referred to by anEvent.
mask determines the types of events sought. See the section "Types and Constants" for a list of the constants that represent the event type masks. To check for more than one type of event, you combine individual constants using the bitwise OR operator.
If an event matching the event mask isn't available in the queue, DPSGetEvent or DPSPeekEvent waits until one arrives or until timeout seconds have elapsed, whichever occurs first. The value of timeout can be in the range of 0.0 to NX_FOREVER. If timeout is 0.0, the routine returns an event only if one is waiting in the queue when the routine asks for it. If timeout is NX_ FOREVER, the routine waits until an appropriate event arrives before returning.
The last argument, threshold, is an integer in the range 0 through 31 that determines which other services may be provided during a call to DPSGetEvent or DPSPeekEvent.
Requests for services are registered by the functions DPSAddTimedEntry, DPSAddPort, and DPSAddFD. Each of these functions takes an argument specifying a priority level. If this level is equal to or greater than threshold, the service is provided before DPSGetEvent or DPSPeekEvent returns.
Return:
DPSPeekEvent returns 1 if it is successful in accessing an event record and 0 if it isn't.
See also:
DPSGetEvent, DPSDiscardEvents, DPSAddFD, DPSAddPort, DPSAddTimedEntry,
DPSPostEvent
Declared in: dpsclient/dpsNeXT.h
Synopsis:
int DPSPostEvent(NXEvent *anEvent, int atStart)
Description:
DPSPostEvent lets you add an event record to your application's event queue without involving
the Window Server. anEvent is a pointer to the event record to be added. atStart specifies where
the new record will be placed in relation to any other records in the queue. If atStart is TRUE, the
event is posted in front of all others and so will be the next one your application receives. If atStart
is FALSE, the event is posted behind all others and so won't be returned until events that precede
it are processed.
You can free, reuse, or otherwise mangle anEvent after you've posted it without fear of corrupting the posted record. DPSEvent copies the record it receives and posts the copy.
Note that event records you post using DPSPostEvent aren't filtered by an event filter function set with DPSSetEventFunc.
Return:
DPSPostEvent returns 0 if successful in posting the event record; it returns -1 if unsuccessful in
posting the record because the event queue is full.
See also:
DPSSetEventFunc
Declared in: dpsclient/dpsNeXT.h
Synopsis:
void DPSPrintError(FILE *fp, const DPSBinObjSeq error)
Description:
DPSPrintError and DPSPrintErrorToStream format and print error messages received from a
PostScript execution context in the Window Server. The error message is extracted from the binary
object sequence error. DPSPrintError prints the error message to the file identified by fp;
DPSPrintErrorToStream prints the error message to stream.
You rarely need to call this function directly. However, if you reset the error handler for a PostScript execution context, the new handler you install could use this function to process errors that it receives.
See also:
DPSPrintErrorToStream
Declared in: dpsclient/dpsNeXT.h
Synopsis:
void DPSPrintErrorToStream(NXStream *stream, const DPSBinObjSeq error)
Description:
DPSPrintError and DPSPrintErrorToStream format and print error messages received from a
PostScript execution context in the Window Server. The error message is extracted from the binary
object sequence error. DPSPrintError prints the error message to the file identified by fp;
DPSPrintErrorToStream prints the error message to stream.
You rarely need to call this function directly. However, if you reset the error handler for a PostScript execution context, the new handler you install could use this function to process errors that it receives.
See also:
DPSPrintError
Declared in: dpsclient/dpsNeXT.h
Synopsis:
void DPSRemoveFD(int fd)
Description:
DPSRemoveFD removes the specified file descriptor from the list of those that the application
will check.
See also:
DPSAddFD
Declared in: dpsclient/dpsNeXT.h
Synopsis:
void DPSRemoveNotifyPortProc(DPSPortProc handler)
Description: Removes the notify port's handler without specifying a new one. The handler argument must match the notify port's current handler.
See also:
DPSAddNotifyPortProc
Declared in: dpsclient/dpsNeXT.h
Synopsis:
void DPSRemovePort(port_t port)
Description:
DPSRemovePort removes the specified Mach port from the list of those that the application will
check.
See also:
DPSAddPort
Declared in: dpsclient/dpsNeXT.h
Synopsis:
void DPSRemoveTimedEntry(DPSTimedEntry tag)
Description:
DPSRemoveTimedEntry removes a previously registered timed entry.
See also:
DPSAddTimedEntry
Declared in: dpsclient/dpsNeXT.h
Synopsis:
void DPSSendEOF(DPSContext context)
Description:
DPSSendEOF sends a PostScript end-of-file marker to the given context. The connection to the
context isn't closed or disturbed in any way by this function.
See also:
DPSFlush
Declared in: dpsclient/dpsNeXT.h
Synopsis:
void DPSSetDeadKeysEnabled(DPSContext context, int flag)
Description:
DPSSetDeadKeysEnabled turns dead key processing on or off for context. If flag is 0, dead key
processing is turned off; otherwise, it's turned on (the default).
Dead key processing is a technique for extending the range of characters that can be entered from the keyboard. In NEXTSTEP, it provides one way for users to enter accented characters. For example, a user can type Alternate-e followed by the letter "e" to produce the letter "é". The first keyboard input, Alternate-e, seems to have no effect-it's the "dead key". However, it signals Client Library routines that it and the following character should be analyzed as a pair. If, within NEXTSTEP, the pair of characters has been associated with a third character, a keyboard event record representing the third character is placed in the application's event queue, and the first two event records are discarded. If there is no such association between the two characters, the two event records are added to the event queue.
<<commenting this out for now>>See the NeXT User's Reference manual for a listing of the keys that produce accent characters.
Declared in: dpsclient/dpsNeXT.h
Synopsis:
DPSEventFilterFunc DPSSetEventFunc(DPSContext context, DPSEventFilterFunc func)
Description:
DPSSetEventFunc establishes the function func as the function to be called when an event record
is returned from the PostScript context context in the Window Server. The registered function is
called before the event record is put in the event queue. If the registered function returns 0, the
record is discarded. If the registered function returns 1, the record is passed on for further
processing.
Only event records coming from the Window Server are filtered by the registered function. Records that you post to the event queue using DPSPostEvent aren't affected.
A DPSEventFilterFunc function takes the following form:
int *func(NXEvent *anEvent)
Return:
DPSSetEventFunc returns a pointer to the previously registered event function. This lets you
chain together the current and previous event functions.
See also:
DPSPostEvent
Declared in: dpsclient/dpsNeXT.h
Synopsis:
int DPSSetTracking(int flag)
Description:
DPSSetTracking turns mouse event-coalescing on or off for the current context. If flag is 0,
coalescing is turned off; otherwise, it's turned on (the default).
Event coalescing is an optimization that's useful when tracking the mouse. When the mouse is moved, numerous events flow into the event queue. To reduce the number of events awaiting removal by the application, adjacent mouse-moved events are replaced by the most recent event of the contiguous group. The same is done for left and right mouse-dragged events, with the addition that a mouse-up event replaces mouse-dragged events that come before it in the queue.
Return:
DPSSetTracking returns the previous state of the event-coalescing switch.
Declared in: dpsclient/dpsNeXT.h
Synopsis:
void DPSStartWaitCursorTimer
Description:
DPSStartWaitCursorTimer triggers the mechanism that displays a wait cursor when an
application is busy and can't respond to user input. In most cases, wait cursor support is automatic:
You'll only need to call this function if your application starts a time-consuming operation that's
not initiated by a user-generated event.
Client Library routines and the Window Server cooperate to display the wait cursor whenever more than a preset amount of time elapses between the time an application takes an event record from the event queue and the time the application is again ready to consume events. However, when an application starts an operation that isn't initiated by an event-such as one caused by receiving a Mach message or by processing data from a file (see DPSAddPort and DPSAddFD)-the wait cursor mechanism is bypassed. To ensure proper wait cursor behavior in these cases, call DPSStartWaitCursorTimer before beginning the time-consuming operation.
See also:
DPSAddFD, DPSAddPort
Declared in: dpsclient/dpsNeXT.h
Synopsis:
int DPSSynchronizeContext(DPSContext context, int flag)
Description:
DPSSynchronizeContext causes DPSWaitContext to be called after each pswrap function is
called, thus synchronizing the PostScript context with your application.
Declared in: dpsclient/dpsNeXT.h
Synopsis:
int DPSTraceContext(DPSContext context, int flag)
Description:
DPSTraceContext controls the tracing of data between a PostScript execution context (or
contexts) in the Window Server and an application process.
The first argument, context, specifies the context to be traced. An application's single context can be returned with DPSGetCurrentContext. Applications having more than one execution context can use the constant DPS_ALLCONTEXTS to trace all contexts belonging to them.
The second argument, flag, determines whether tracing is enabled. When data tracing is enabled, a copy of the PostScript code generated by an application and the values returned to it by the Window Server is sent to UNIX standard error. Values returned to the application are marked by the prepended string:
% value returned ==>
For applications based on the Application Kit, there are two preferable methods for turning on data tracing: You can use the NXShowPS command-line switch when you launch an application from Terminal. Alternatively, when you run the application under GDB, you can use the showps and shownops commands to control tracing output.
Only one tracing context can be created for the supplied context. If you attempt to create additional tracing contexts for a context that's already being traced, no new context is created and DPSTraceContext returns -1.
Return:
DPSTraceContext returns 0 if successful in creating a tracing context, or -1 if not.
See also:
DPSTraceEvents
Declared in: dpsclient/dpsNeXT.h
Synopsis:
void DPSTraceEvents(DPSContext context, int flag)
Description:
DPSTraceEvents controls the tracing of events between a PostScript execution context (or
contexts) in the Window Server and an application process.
The first argument, context, specifies the context to be traced. An application's single context can be returned with DPSGetCurrentContext. Applications having more than one execution context can use the constant DPS_ALLCONTEXTS to trace all contexts belonging to them.
The second argument, flag, determines whether tracing is enabled. When event tracing is enabled, information about each event that the application receives is sent to UNIX standard error. For example, for a left mouse-down event the listing might look like this:
Receiving: LMouseDown at: 343.0,69.0 time: 1271899
flags: 0x0 win: 6 ctxt: 76128 data: 1111,1
The listing displays the fields of the event record: type, location, time, flags, local window number, PostScript execution context, and data. The contents of the data field listing depends on the event type; for instance, in the preceding example the event number and the click count were displayed.
To enable event tracing, you can use the NXTraceEvents command-line switch when you launch an application from Terminal. Alternatively, when you run the application under GDB, you can use the traceevents and tracenoevents commands to control event-tracing output.
See also:
DPSTraceContext
Declared in: dpsclient/dpsNeXT.h
Synopsis:
void DPSUndefineUserObject(int index)
Description:
DPSUndefineUserObject removes the association between index and the PostScript object it
refers to, thus destroying the user object. By destroying a user object that's no longer needed, you
can let the garbage collector reclaim the previously associated PostScript object.
See also:
DPSDefineUserObject
Declared in: dpsclient/event.h
Synopsis:
int NX_EVENTCODEMASK(int type)
Description: This handy utility macro returns an event mask that corresponds to the given (single) event type.