TEGL WINDOWS

The high-level windows in the TEGL WINDOWS TOOLKIT provide a consistent
graphical interface for your application. Many routines are provided
that are associated with a window or are window relative. A number of
devices are provided that would require a fair bit of coding using the
lower levels of the toolkit.

       * Header
       * Local menus
       * Minimize & Maximise buttons
       * Resizers
       * Sliders
       * Dialog management
       * World Coordinates

A drawback to the high-level windows is the necessity of coding a
redraw event for windows that are resizeable.

Here is a simple window:

BEGINFILE> twwin1.pas
{-- twwin1.pas}
USES teglmain, twcommon, twkernel;

VAR wf : WinFramePtr;

BEGIN
  twEasyStart;

  twInit(wf,100,50,300,150);
  twSetHeader(wf,'A Simple Window');
  twDrawWindowFrame(wf);

  TeglSupervisor;
END.

ENDFILE>

When you compile and run this program you'll get a window with a header
and resize areas.

Lets examine what each step in this programs does.

The first call to twEasyStart does the graphics system and window
manager initialization including autodetection of the graphics
hardware and clearing the screen. Additionally it places an exit
button in the lower right corner of the screen so you can always exit
your program.

twInit creates a window frame (the first parameter wf is a VAR
WinFramePtr) memory block, the numbers indicate the screen area
that the window should occupy (x1, y1, x2, y2). twInit must always
be called before an other routines that have a WinFramePtr as their
first argument.

twSetHeader says this window will have a header displayed (default
is no header) and what is displayed in it.

twDrawWindowFrame actually draws the window on the screen. This is
always called after all the conditions for a window have been set.

TeglSupervisor is the event-supervisor. It will poll for events
(key-presses and mouse clicks) and call up the appropriate event-handler
as required.

The high-level windows have a number of pre-defined event-handlers
that are automatically installed. There is the resizing events which
look after the borders of the window so that a mouse click can stretch
or shrink the window. Also there is the minimize and maximize buttons.
The minimize button will shrink a window to an icon while the maximize
button expands it to fill the entire screen.

CONTROL FUNCTIONS

FindWinFrame(frame : ImageStkPtr): WinFramePtr;

This function is used to locate a WinFramePtr that is associated with
a frame (ImageStkPtr). It is called on entry to an event-handler to
determine what window invoked it.

twSelect(wf: WinFramePtr);

This function will select the window. This should be called on entry
to any event-handler that uses a window, it does internal checks and
sets the viewport to the working area.

GLOBAL WINDOW SETUP

twSetGlobalButtonSize(width, height: byte);

Set the size of the buttons on the window. Generally if the defaults
are not satisfactory then this can be changed but should be done at
start up before any windows are drawn. This affects all windows.

twSetGlobalSliderSize(UpDown, LeftRight: Byte);

Sets the size of the slider thumb (the button that slides). This only
affects on dimension of the slider thumbs, the other is set to conform
to the button sizes.

twSetGlobResizeArea(Width, Height: Byte);

Sets the size of the resize corner areas of the window border.
Width is the x distance (in pixels) and Height is the y distance.
The thickness of the border is used to complete the resize areas, this
defaults to 4 pixels and can be changed on individual windows.

twSetHeaderFont(Font : Pointer);

Sets the font that all subsequent windows will use for headers and
menus.

This example sets these global items to illustrate how the window
style is affected. The best use of these items is to control the
window look on different video displays and would best be set at
the start of a program and left alone during the run.

BEGINFILE> twwin2.pas
{-- twwin2.pas}

USES teglfont,moreicon,tgraph,
     teglunit,teglmain,
     twcommon, twkernel;

{$F+}
VAR wf : WinFramePtr;



BEGIN
  twEasyStart;

  twSetGlobalButtonSize(24,12);
  twSetGlobalSliderSize(36,8);
  twSetGlobalResizeArea(50,20);
  twSetHeaderFont(@f8x12bol);
  twInit(wf,100,50,300,170);
    twSetHeader(wf,'Common Window characteristics');
    twSetWindowStyle(wf,stdbox);
    twSetUpDownSlider(wf,TRUE);
    twSetLeftRightSlider(wf,TRUE);
  twDrawWindowFrame(wf);

  TeglSupervisor;
END.

ENDFILE>

WINDOW FEATURES

The following functions set features on a window that affect only that
window. Note that each one requires a WinFramePtr at the first
argument.

twSetBorderColor(wf: WinFramePtr; color: Byte);

Sets the color of the window border. The border is the one pixel outline.

twSetCloseEvent(wf: WinFramePtr; CloseEvent: CallProc);

Sets the event to call when a window is disposed of. The CloseEvent does
not have to be set (a default one is in place).

twSetDisplayFont(wf: WinFramePtr; font: pointer);

Sets the font to use with the window. This affects the header and menus.

twSetMaximize(wf: WinFramePtr; tf: Boolean);

Sets whether a window is minimize/maximizeable. If TRUE then the
window will have the minimize/maximize buttons. Only has an effect on
windows with a header.

twSetRedraw(wf: WinFramePtr; Redraw: CallProc);

Sets the redrawing function for a window. The redrawing function is
an event-handler. This function is called after the kernel draws the
window (border, buttons, menu etc.) when first created and any time the
window must be redraw, like after it has been re-sized.

twSetHeader(wf: WinFramePtr; s : String);

Sets the window header to s. Window header must be set to enable the
minimize/maximize buttons.

twSetThickness(wf: WinFramePtr; Thickness: Byte);

Sets the thickness of the window border. Thickness cannot be less than
one. The thickness affects the size of the resize areas (if resizing is
enabled for the window).

twSetWinFrameColors(wf: WinFramePtr; Color1, Color2: Byte);

Sets the colors to use on the upper left and lower right of the window.

twSetWindowStyle(wf: WinFramePtr; Style: FrameDrawFunc);

Sets the drawing function to draw the border of the window frame.
Currently there are two drawing functions, stdbox and bevbox.

------------------------------------------------------------------

This example uses many of window features, you don't need to set them
all, the defaults are usually fine, but by changing them around you
can see the effects.

BEGINFILE> twwin3.pas
{-- twwin3.pas}
USES moreicon,tgraph,
     teglunit,teglmain,
     twcommon, twkernel;

{$F+}
VAR wf : WinFramePtr;



{-- RedrawIt is a standard event-handler. It is called after }
{-- the window standard items have been drawn. }

Function RedrawIt(ifs: ImageStkPtr; ms: MsClickPtr): Word;
  VAR wf: WinFramePtr;
  BEGIN
    wf := findWinFrame(ifs);
    twPutPict(wf,1,1,@IMAGESYSTEM,BLACK);
  END;

{-- this is the close event for the window. }

Function CloseIt(ifs: ImageStkPtr; ms: MsClickPtr): Word;
  VAR wf: WinFramePtr;
      i : Integer;
      color : Integer;
  BEGIN
    wf := findWinFrame(ifs);
    prepareforupdate(ifs);
    {-- prove that we are going through here }
    color := 0;
    for i := 0 to 100 do
      BEGIN
        twSetFillcolor(wf,color);
        twClear(wf);
        inc(color);
        if color > 15 then color := 0;
      END;
    commitupdate;
    {-- then call close to actually dispose of the window }
    twClose(wf);
  END;


BEGIN
  twEasyStart;

  twInit(wf,100,50,300,170);
    twSetHeader(wf,'Window characteristics');
    twSetThickness(wf,6);
    twSetFillColor(wf,GREEN);
    twSetBorderColor(wf,BLACK);
    twSetWinFrameColors(wf,cyan,Magenta);
    twSetMaximize(wf,FALSE);    {-- no minimize/maximize}
    twSetWindowStyle(wf,BevBox);
    twSetRedraw(wf,RedrawIt);
    twSetCloseEvent(wf,CloseIt);
  twDrawWindowFrame(wf);

  TeglSupervisor;
END.

ENDFILE>

WINDOW FUNCTIONS

twClear(wf: WinFramePtr);

Clears the window to the color set by twSetFillColor.

twScrollDown(wf: WinFramePtr; Num: Integer);
twScrollUp(wf: WinFramePtr; Num: Integer);

These functions will scroll the working area of the window up or down
by Num pixels. The area cleared is filled using the current fillcolor
set by twSetFillColor.

Sliders -

twSetUpDownSlider(wf: WinFramePtr; Active: Boolean);
twSetLeftRightSlider(wf: WinFramePtr; Active: Boolean);

These enable (or disable) the sliders from being attacted to a
window. TRUE turns sliders on, FALSE turns them off. If the slider
is changed after the window is displayed then it must be redrawn for
it to take effect.

Sliders won't be displayed if a window becomes too small.

twSetLeftRightEvent(wf: WinFramePtr; Event: CallProc);
twSetUpDownEvent(wf: WinFramePtr; Event: CallProc);

These set the event to be called after a slider has been moved. This
means either the slider thumb or the end point buttons.

twSetLeftRightRange(wf: WinFramePtr; Range, Step: Integer);
twSetUpDownRange(wf: WinFramePtr; Range, Step: Integer);

The slider movement can be gauged by setting its range (from 0 to
range) and the step. Range is an arbitrary value that would reflect the
item that the slider is used to scroll. Step is the increment value to
use with the end point buttons.

Menus -

Two functions provide for a straight forward local menu facility. On both
the string parameter is the displayed menu selection. Active is to set
whether the menu item is to be active (clickable). If a menu item is
passed with tildes '~' around a character then that item is displayed
with an underscore and the appropriate keypress is trapped (if the
window is active).

twMenuItem(wf: WinFramePtr; s : String; Active: Boolean);

Add a local bar menu item to the window. After adding a bar menu item
the sub menu items must be delared immediately afterward using
twSubMenuItem.

twSubMenuItem(wf: WinFramePtr; s: String; Active: Boolean; Event: CallProc);

Add a submenu item to the local bar menu item most recently added.
Event is the event-handler to call when the sub menu item is selected.


An important consideration with windows that have local menus is the
ImageStkPtr that is passed to the event-handler. It is not the ImageStkPtr of
the Window but of the smaller frame that the menu is displayed in. This
is consistent in that an event-handler is always passed the frame that
the mouse click originated on. To determine what window this event-handler
is being called from use the related stack as in ifs^.related stack.

BEGINFILE> twwin4.pas
{-- twwin4.pas}
USES moreicon,tgraph,
     teglunit,teglmain,
     twcommon, twkernel;

{$F+}
VAR wf : WinFramePtr;



{-- RedrawIt is a standard event-handler. It is called after }
{-- the window standard items have been drawn. }

Function RedrawIt(ifs: ImageStkPtr; ms: MsClickPtr): Word;
  VAR wf: WinFramePtr;
  BEGIN
    wf := findWinFrame(ifs);
    twPutPict(wf,10,10,@IMAGESYSTEM,BLACK);
  END;

{-- this is the close event for the window. }

Function CloseIt(ifs: ImageStkPtr; ms: MsClickPtr): Word;
  VAR wf: WinFramePtr;
      i : Integer;
      color : Integer;
  BEGIN
    wf := findWinFrame(ifs);
    prepareforupdate(ifs);
    {-- prove that we are going through here }
    color := 0;
    for i := 0 to 100 do
      BEGIN
        twSetFillcolor(wf,color);
        twClear(wf);
        inc(color);
        if color > 15 then color := 0;
      END;
    commitupdate;
    {-- then call close to actually dispose of the window }
    twClose(wf);
  END;

{-- this event-handler just chains to CloseIt, the important }
{-- notation here is the use of the related stack for local }
{-- menu selections to determine the correct WinFramePtr }

Function MenuCloseIt(ifs: ImageStkPtr; ms: MsClickPtr): Word;
  BEGIN
    MenuCloseIt := CloseIt(ifs^.relatedStack,ms);
  END;


BEGIN
  twEasyStart;

  twInit(wf,100,50,300,190);
    twSetHeader(wf,'Window with a local menu');
    twSetMaximize(wf,FALSE);    {-- no minimize/maximize}
    twSetRedraw(wf,RedrawIt);
    twSetCloseEvent(wf,CloseIt);
    twMenuItem(wf,'~F~ile',TRUE);
      {-- NilUnitProc is just a dummy event-handler, use it }
      {-- as a place holder when you are just building an interface }
      twSubMenuItem(wf,'~O~pen',TRUE,NilUnitProc);
      twSubMenuItem(wf,'-',FALSE,NilUnitProc);
      twSubMenuItem(wf,'E~x~it',TRUE,MenuCloseIt);
    twMenuItem(wf,'~D~raw',TRUE);
      twSubMenuItem(wf,'~A~rc',FALSE,NilUnitProc);
      twSubMenuItem(wf,'~C~ircle',FALSE,NilUnitProc);
      twSubMenuItem(wf,'~E~llipse',FALSE,NilUnitProc);
      twSubMenuItem(wf,'~R~ectangle',FALSE,NilUnitProc);
  twDrawWindowFrame(wf);

  TeglSupervisor;
END.

ENDFILE>


Any of the example programs that start with a 'TW' are examples of
the high-level window interface.

-------------------------------------------------------------------
END TWQUICK.TXT