Legacy Document

Inside Macintosh: Text /

Chapter 7 - Text Services Manager / Text Services Manager Reference

Text Services Manager Routines for Components / Opening Floating Utility Windows

NewServiceWindow

The NewServiceWindow function 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.

FUNCTION NewServiceWindow (wStorage: Ptr; boundsRect: Rect; 
                           title: Str255; visible: Boolean; 
                           theProc: Integer; behind: WindowPtr; 
                           goAwayFlag: Boolean; 
                           ts: ComponentInstance; 
                           VAR window: WindowPtr): OSErr;

wStorage

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

boundsRect

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 record (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 procedure 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 procedure 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 = NIL. 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 record; text service components should not change the value of the window's refcon field.

Client applications

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.

DESCRIPTION

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 NIL.

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.

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.

Balloon Help

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 procedures to have Balloon Help.

RESULT CODES

noErr	No error
memFullErr	Insufficient memory to open the window

SEE ALSO

Window definition procedures and the NewWindow function are described in the Window Manager chapter of Inside Macintosh: Macintosh Toolbox Essentials.

Balloon Help is described in the Help Manager chapter of Inside Macintosh: More Macintosh Toolbox.