Celestin Apprentice 2/Apprentice-Release2.iso/Source Code/C/System/appe Windows/About appe Windows

Text File | 1994-05-23 | 5.6 KB | 144 lines | [TEXT/R*ch]

appe Windows

If you have seen the new Speech Manager, then you know that a background
only application can put a window onto the screen (contrary to popular
belief). The new Text Services Manager in System 7.1 offers documented
hooks for creating, disposing, and handling floating windows. These
windows are layer independent (they are floating above all programs
and windows), and work without patching traps (well, a quick jGNEFilter,
but no traps).

This program demonstrates a shell application that puts a TSM window
onto the screen, and intercepts update, click, and key events. Filling
in the handler functions is the easiest way to put up your own floater.
Wrapper functions restore global context, current resource file, GrafPort,
and heap zone, to make standard handling routines much easier to write.

Of course the program is background only, so it is typically launched
from the Extensions Folder at startup. I like the close box on floater
windows, because its an easy way to quit the program without relying
on a quit Apple Event. I have added support for hiding all windows
with Cmd-Escape, and to respond to screen savers and programs that
take over the screen (hide the menu bar).


Legal Stuff

Its yours if you like it. This shell is free for you to modify and
expand upon. I would like that you tell me if you use this, but you
are under no obligation. Likewise, this library is provided as is --
I fixed up all the bugs I could find/create, so I could use it myself --
but that doesnt necessarily mean its fit for wiping the toilet seat. :)


Using the library

In scanning the source for the program, there are several key areas
that you should recognize. These gotchas are important things to
remember when modifying or adding to the source.

main.c

    Creating and using Text Service windows requires additional
    stack space. I found that 16k of additional stack seems to
    work. BTW, keep the memory footprint down (cuz people dont like
    memory hogs) but not too small or you will have heap space
    problems. I had to fine tune my demo apps to work well in
    limited memory space.

    The only Toolbox initialization call that you should make
    is InitGraf() to setup the QD globals. InitWindows() plays
    with the layer manager in a bad way, and should be avoided.

    I use Gestalt() to check my environment, and exit gracefully
    with a Notification Mgr dialog.

windows.c

    The current TSM does not create a Color Window for us, so there
    is a #define in "main.h" that gives you the option to patch
    traps. Although this violates our promise of Patch-Free operation,
    it gives us color -- so lose or leave it at your whim.

    Hooks are set up for you to implement the following window
    functions: Update, Click, Keydowns, Zoom, Reveal (on show
    and hide), and Idle time.

    Key events can be intercepted or passed through at your
    discretion. By default, only Cmd-Escape is applicable and
    it is passed through so that other floaters can see it.
    (This would be a useful feature for all similar apps to
    implement, please?)

    Controls like scroll bars or other window-activation
    sensitive elements should always be active in floaters,
    since all floaters are considered active regardless of
    position in window list.

event filter.c

    The jGNEFilter is the best way to intercept the events
    directed at our window. We check mouse and key events
    for relevance, and then convert them to null events
    if directed at our window.

    Note: for some reason, we miss occasional mouse-downs.
    I think it may be a bug in the TSM.

    Our floaters dont get update events either, so we manually
    check the update region of our window and call the update
    routine. We have to check every event because update events
    aren't necessarily posted when just our window needs
    drawing.

    Contexts are the mechanism we use for setting up and cleaning
    up relevant variables and registers. A context struct
    defines some major elements that I need. Be sure that code
    you add is not dependent on other lo-mem globals without the
    right save and restore context wrappers. Also, since a
    context plays with A5 and your app globals, you have to
    be careful about globally stored contexts.

    To get information about the front application, you may need
    to restore its context (to get heap info or access private
    globals off A5). Be sure to carefully manage when you are
    using your apps context and someone elses.

Other notes

    In "main.h" I define a Hot Application, which lets you tie
    your floater to an particular application creator type. If
    you change this value, your floaters will only be visible
    when that application is the front program. This is a great
    way to give specialized information about a particular
    program without modifying it.

    Perhaps it would be better to handle events within my own
    event loop, but since there is no easy way to PostEvent()
    from one apps context to another this is not done. If you
    have a suggestion to help me, I would like to make this
    change.

Anticipated Improvements:

    Adding basic menu support for Quit and Show/Hide so that
    the "Background Only" bit can be toggled. It was suggested
    that this may be a useful thing for those who want to
    launch or quit the app several times.

    Making a small LaunchMe and QuitMe drag/drop utils that
    do no File Type checking for our convenience.

    Handle window events inside my own event loop by grabbing them
    and putting them into my own Event Queue.

    Anything else you can think of?

Finally, I want this to be a stable mechanism for something that you
shouldn't be able to do. Despite the interface guidelines, there may
be a use for doing this. Please send me bug reports and suggestions
for improving this tool.

Matt Slot
[e-mail]