BTOC(3R)

NAME
btoc: setjwin, P->btoc, P->ctob - specify rows and columns and default outline

SYNOPSIS
#include <dmd.h>

void setjwin (cols, rows)
int cols, rows;

Point (*P->btoc)(x, y, p)
int x,y;
struct Proc *p;

Point (*P->ctob)(x, y, p)
int x,y;
struct Proc *p;

DESCRIPTION
The purpose of the setjwin and btoc functions is to report the number of character rows and columns available in an application's window. These routines are intended to be used by terminal emulator applications executing in the 630 MTG. If the application is running in a layers window, the character rows and columns information is sent to the host. This information is then made available to application programs running on the host through an ioctl() call to the xt device driver with the request argument of JWINSIZE. The windowing utilities jwin program is a simple host application which uses this facility to print rows and columns on its standard output. Other host applications, such as the vi editor, also use this facility to determine available rows and columns.

The setjwin function is called directly from an application program when the application begins execution, either after being downloaded or started from the application cache. The parameters cols and rows correspond to character columns and character rows respectively.

Btoc is called indirectly by the 630 MTG system control process whenever the application's window is reshaped. P->btoc is a pointer stored in the application's process table. The application's process table is simply a structure of type Proc that contains system information about the application program and is maintained and used by the 630 MTG's system processes. P->btoc points to a function named, for example, bits_to_char(), which returns a Point structure. The function bits_to_char() must be specified in the application program and the P->btoc pointer must be set in the application's initialization routine to point to these functions. The bits_to_char() function will then be called by the 630 MTG's system control process whenever the application's window is reshaped.

The parameters passed to the btoc() function are:
    x = the width of the application's window in pixels
    y = the height of the application's window in pixels
    p = a pointer to the application's process table.

The two integers x and y (returned in the Point structure) are the character rows and columns, respectively.

Setjwin and the btoc() functions serve similar purposes, but both functions are necessary for the following reasons. Setjwin is used to inform the host of character rows and columns when an application boots. The btoc() function cannot be used in this situation because the application has not yet executed, and therefore P->btoc has not been initialized. On the other hand, the btoc() function is used to inform the host of character rows and columns when an application's window is reshaped. The 630 MTG system control process needs to send a message specifying current window size to the host xt driver when a window is reshaped, and it is not possible to wait for the application to call setjwin. This makes the btoc() function necessary.

If an application does not use the setjwin and btoc facilities, the host will be told the character row and columns which would be available if Windowproc was running in a window the size of the application's window.

The purpose of a ctob() function is to specify a default outline for a window being reshaped based on the Host default rows and columns settings specified during the 630 MTG Setup procedure. See the 630 MTG Terminal User's Guide for more information about Setup and Host default rows and columns settings.

Initialization of P->ctob is identical to initialization of P->btoc as described above. P->ctob is set to point to a function named, for example, char_to_bits(). The char_to_bits() function is called by the 630 MTG system control process before an application's window is reshaped to determine the default window outline to display for the application during the reshape procedure.

The parameters passed to ctob() are, in order, x and y (the Host default rows and columns, respectively), specified for a window in Setup; and p, a pointer to the application's process table. The two integers x and y (returned by ctob() in the Point structure) are the width and height, respectively, in pixels, of the window outline to be displayed.

Note that ctob could disregard the parameters x and y and always return a predetermined outline. This is commonly done by non-terminal emulator applications that want to display a default outline which is not necessarily based upon Setup options.

If a ctob function is not specified, a sweep cursor will appear without a default outline when the application program is reshaped.

The cache(3L) function calls ctob to determine the default outline for applications which are invoked from the More menu.

EXAMPLE
A simple example of a bits_to_char() and a char_to_bits() function is shown below.

    #include <dmd.h>
    #include <font.h>
    Point bits_to_char();
    Point char_to_bits();
    main()
    {
         .
         .
       P->btoc = bits_to_char;
       P->ctob = char_to_bits;
         .
         .
    }
    Point
    bits_to_char(x,y,p)
    int x,y;
    struct Proc *p;
    {
       Point q;
       /* INSET is a constant equal to the pixel width of */
       /* the 630 window border. It is defined in dmdproc.h. */
       /* Dmdproc.h is included by dmd.h. */
       q.x = (x - 2*INSET) / FONTWIDTH(largefont);
       q.y = (y - 2*INSET) / FONTHEIGHT(largefont);
       return q;
    }
    Point
    char_to_bits(x,y,p)
    int x,y;
    struct Proc *p;
    {
       Point q;
       q.x = FONTWIDTH(largefont) * x + 2*INSET;
       q.y = FONTHEIGHT(largefont) * y + 2*INSET;
       return q;
    }

SEE ALSO
cache(3L), globals (3R), structures(3R).
630 MTG Terminal User's Guide.
jwin(1), vi(1) in the UNIX System V Release 3 User's Reference Manual.
ioctl(2) in the UNIX System V Programmer Reference Manual.
xt(7) in the UNIX System V Release 3 System Administrator's Reference Manual.

WARNINGS
Since btoc() and ctob() are called from the terminal's control process, the variable P should not be referenced within these routines. Instead, the parameter p should be used to reference the application's process table.

The two integers x and y returned by ctob in the point structure must be less than or equal to XMAX and YMAX, respectively.