Carbon


NewServiceWindow

Header: TextServices.h Carbon status: Unsupported

Opens a floating utility window in the floating window service layer, in front of the current application. The text service component may use the window for interaction with the user or other purposes.

OSErr NewServiceWindow (
    void *wStorage, 
    const Rect *boundsRect, 
    ConstStr255Param title, 
    Boolean visible, 
    SInt16 theProc, 
    WindowRef behind, 
    Boolean goAwayFlag, 
    ComponentInstance ts, 
    WindowRef *window
);
Parameter descriptions
wStorage

A pointer to the location in memory of the window structure. Do not allocate the window structure on the stack. Always be sure to allocate the window in the heap, or else pass NULL for this parameter.

boundsRect

A pointer to a rectangle, given in global coordinates, that determines the size and location of the new floating window. This rectangle becomes the portRect field of the graphics port structure (defined by the QuickDraw GrafPort data type) for this window.

title

A Pascal string that contains the title of the window.

visible

A Boolean value to determine whether the window is to be drawn. If TRUE, NewServiceWindow draws the window. First it calls the window definition function defined in the theProc parameter to draw the window frame. Then it generates an update event for the entire window contents.

theProc

The window definition function for the floating window.

behind

A window pointer (defined by the Window Manager WindowPtr data type) that determines the plane of the floating window. NewServiceWindow inserts the new window behind the window pointed to by this parameter. To put the new window behind all other windows, use behind = NULL. To place it in front of all other windows, use behind = POINTER(-1).

goAwayFlag

A Boolean value that determines whether the go-away region should be drawn in the window. If this parameter is TRUE and the window is frontmost (as specified by the behind parameter), NewServiceWindow draws a go-away region in the frame.

ts

A component instance returned by a prior call to the Component Manager OpenComponent function. This value is stored in the refcon field of the window structure; text service components should not change the value of the window’s refcon field.

If you are a client application making this call, pass the Process Manager constant kCurrentProcess in this parameter so that events in the new window will be forwarded to you. After you have created the window, you can use its refcon field for private storage as usual.

window

A pointer to the newly allocated floating window.

function result

A result code. This function calls the Window Manager NewWindow function. If a floating window is successfully allocated, NewServiceWindow returns a pointer to that window as the function result. Otherwise, it returns NULL.

DISCUSSION

In conjunction with the Process Manager, the Text Services Manager maintains the floating window service, whose windows occupy a special layer called the floating window service layer. The Text Services Manager uses the floating window service to provide a standard floating input window when needed.

A text service component can open multiple windows in this layer. When a text service component receives an event, it determines whether the event belongs to one of its text service component windows by calling FindServiceWindow.

These calls may be made by client applications also. If you are an application that uses NewServiceWindow to open a floating window, be sure to hide the floating window when you are switched out; that is, when another application’s windows become active.

If you are writing a text service component and want the service window to have custom Balloon Help, place an 'hwin' resource (with references to 'hcrt' and 'STR#' resources) in your component resource fork, with a name equal to the window title. The Text Services Manager will then open the resources automatically when needed. If you are writing a client application, you need not follow anything other than normal functions to have Balloon Help.

AVAILABILITY

Not supported in Carbon. Not available in Carbon.

CARBON NOTES

Replace calls to NewServiceWindow in your component with calls to Mac OS 8.5 Window Manager creation functions, such as CreateNewWindow, which offer more complete support for floating windows.


© 2000 Apple Computer, Inc. (Last Updated 6/30/2000)