Simtel MSDOS 1992 June/SIMTEL_0692.cdr/msdos/desqview/dvglu101.arc/-README.101

Text File | 1988-08-14 | 5.9 KB | 117 lines

                        DV-GLUE v1.01 upgrade kit
                        -------------------------

Unpack this archive in the directory containing DV-GLUE 1.00, then type

        UPDATE

to install the updated object modules into TVAPIS.LIB.

        Ralf Brown
        August 13, 1988
---------------------------------
Known bugs:
        1.00 TVapp_new() crashes when loading a new program if any other
                windows are open
        1.01 TVapp_new() does wierd things when closing the new program.
                I'm still trying to figure out how to get rid of this,
                but it no longer locks up the system (at least not
                immediately; it does put the current process into a somewhat
                unstable state.)

---------------------------------
Updated function descriptions:

OBJECT TVtask_new(OBJECT parent,char *title,int row,int col,int rows,int cols,
                  char far *stack,int stacksize,void far (*startaddr)(int),
                  int switch_menu)
        create a new thread as a child of "parent", whose window has title
        "title" (or the title of the parent, if title == NULL).  The window
        will be at (row,col) and will be "rows" lines high by "cols" columns
        wide.  If stack == NULL, a stack of size "stacksize" will be malloc'd,
        otherwise the given stack will be used by the new task.  The task will
        begin by executing the function "startaddr", passing in the segment of
        its parent task's handle.

        If "rows" is negative, then the window will have the same number of
        rows as the parent window; similarly for "cols".  If both "rows"
        and "cols" are zero, no new window will be created.

        If "switch_menu" is TRUE, the new task will be placed on the Switch
        Windows menu.

OBJECT TVapp_new(OBJECT win,int row,int col,int rows,int cols,int switch_menu,
                 char *program, char *argv0, char *argv1, ..., NULL )
        Start a new application as a child of the task owning "win".  The
        new window will be at (row,col) and will be rows by cols in size.
        Load "program", and start it executing with the remaining arguments as
        command line.  If "switch_menu" is TRUE, the program will be listed
        on the Switch Windows menu.

        Returns the new application's handle, or NIL on error.  The external
        int _doserrno is set if the error was encountered while loading the
        program.  If it is 0 but the return value is NIL, then a new task
        for the program could not be started.

int TVwin_async(OBJECT win,void far (*func)(void),int stacksize)
        Defines a notification handler for the window "win".  You may share a
        handler among multiple windows, as the events which apply to a single
        window identify which window was affected.

        "stacksize" specifies how many bytes to allocate from the heap for a
        local stack which will be used inside the handler.  If "stacksize"
        is zero, the default of 512 bytes will be used.

        Returns 0 on success, EOF on failure.

        This function will not work in huge model at present.  A supporting
        function would have to be recoded entirely in assembler to get around
        the huge model function entry code.

        You may do pretty much anything inside the handler, except call
        TVustack() or TVostack() [which will cause a crash] or call malloc()
        and friends [which simply won't work].  Also to be avoided is
        TVwin_async(our_window,NULL,n), as that does a free() on the stack
        your code is executing on!

The last function (for now), is a higher-level version of TVwin_async(),
which allows a separate handler for each possible event which DESQview can
notify a program of.

void (*UIsignal(int signal,OBJECT win,void (*handler)(),
                int stacksize))(NOTIFY_MSG *)
        Installs a handler for the specified event notification (the valid
        signals are the same as for TVwin_notify() and TVwin_cancel()), and
        returns a pointer to the previous handler, or SIGNAL_ERROR if it was
        unable to install the handler.  The handler takes a single argument,
        which is a pointer to the notification message provided by DESQview,
        with one exception.  The exception is that the first byte has already
        had the MS_NOTIFY offset subtracted from it, so the handler can
        directly compare the first byte to the event numbers (for those
        handlers that take care of multiple events).

        "stacksize" specifies the size of the local stack which will be
        allocated from the heap.  If "stacksize" is zero, the default of 512
        bytes will be used, of which about 470 will be available to your
        function.

        The specified event is enabled when "handler" is non-NULL, but not
        automatically disabled when "handler" is NULL.  This is because of the
        assumption that you want any event you are trapping to actually occur,
        but don't necessarily want to disable the action when you are no
        longer interested in trapping the event (such as moving the window).
        If you want the action disabled when you remove the handler, you must
        explicitly call TVwin_disallow().

        As with TVwin_async(), you may do pretty much anything inside the
        handler, except call TVustack(), TVostack(), and the various malloc()
        functions.  The first two will cause a crash, the latter simply won't
        work.

        You may define a handler for the same signal for multiple windows, but
        only the last-used handler for a given signal is actually called,
        regardless of which window gets the notification.  BEWARE!

        DO NOT mix this function with the TVwin_async() function, as that
        will cause unpredictable results.