@database "WindowHandle"
@master "Work:src/Oberon/PortHandle/doc/WindowHandle.doc"

@Node Main "WindowHandle.doc"
    @{" --interface--() " Link "--interface--()"}
    @{" Init() " Link "Init()"}
    @{" WinHandle.Handle() " Link "WinHandle.Handle()"}
    @{" WinHandle.Uninit() " Link "WinHandle.Uninit()"}
@EndNode

@Node "--interface--()" "WindowHandle/--interface--"

DEFINITION WindowHandle;

IMPORT
  BT := BasicTypes,
  I := Intuition,
  idcmp := IDCMPort;

TYPE
  WinHandlePtr = POINTER TO WinHandle;
  WinHandle = RECORD (BT.ANYDesc) 
@{b}    port : idcmp.IDCMPortPtr;@{ub}
@{b}    win : I.WindowPtr;@{ub}
@{b}    action : INTEGER;@{ub}
@{b}    PROCEDURE (VAR wh:WinHandle) Uninit();@{ub}
@{b}    PROCEDURE (VAR wh:WinHandle) Handle();@{ub}
  END;

CONST
  cancel = 0;

PROCEDURE Init(VAR wh: WinHandle; win: I.WindowPtr; port: idcmp.IDCMPortPtr);


END WindowHandle.

@EndNode

@Node "Init()" "WindowHandle/Init"

@{b}   NAME@{ub}
       Init -- initialize WindowHandle

@{b}   SYNOPSIS@{ub}
       Init (VAR wh: WinHandle; win: I.WindowPtr; port: idcmp.IDCMPortPtr);

@{b}   FUNCTION@{ub}
       Stores win and port in wh's according fields.

       The windows userData field will be set to point to wh, this
       is quite useful for the IDCMP message handle methods (see
       IDCMPort/--abstract_handle_methods--).

       win.userPort MUST be port.port, so you have either to shanghai
       the windows port (see example below) or attach the window to
       an already existing port (see example in
       IDCMPort/AttachWindow()).

@{b}   INPUTS@{ub}
       wh   - WinHandle to be initialized
       win  - already opened @{"Window" Link "TEXT_INCLUDE:intuition/intuition.h/Main" 797} to be handled with wh
       port - pointer to a valid IDCMPort

@{b}   EXAMPLE@{ub}
       NEW(port);
       win := Intuition.OpenWindow(...);
       IF win # NIL THEN
         Ports.ShanghaiPort(port, win.userPort);
         WindowHandle.Init(wh,win);
         wh.Handle;
         (* port must not be Uninit()ed 'cause of ShanghaiPort() *)
         wh.Uninit;
         Intuition.CloseWindow(win);
       END;

@{b}   SEE ALSO@{ub}
       @{"WinHandle.Uninit()" Link "WinHandle.Uninit()"}, @{"WinHandle.Handle()" Link "WinHandle.Handle()"}, IDCMPort/AttachWindow(),
       IDCMPort/--interface--, IDCMPort/--abstract_handle_methods--,
       @{"Intuition/OpenWindow()" Link "intuition/OpenWindow()"}, @{"Intuition/CloseWindow()" Link "intuition/CloseWindow()"}

@EndNode

@Node "WinHandle.Handle()" "WindowHandle/WinHandle.Handle"

@{b}   NAME@{ub}
       WindHandle.Handle -- handle message dispatching (method)

@{b}   SYNOPSIS@{ub}
       (VAR wh: WinHandle) Handle ();

@{b}   FUNCTION@{ub}
       Waits for the arrival of messages at the WinHandles port and
       handles them by calling the ports Handle() method.

       This will loop until wh.port.quit is TRUE

       At all this is a complete event loop (see RKM Libraries
       p. 251f) for programs only communicating with one window.

@{b}   EXAMPLE@{ub}
       see @{"Init()" Link "Init()"}

@{b}   SEE ALSO@{ub}
       IDCMPort.Handle()

@EndNode

@Node "WinHandle.Uninit()" "WindowHandle/WinHandle.Uninit"

@{b}   NAME@{ub}
       WinHandle.Uninit -- uninitialize WindowHandle

@{b}   SYNOPSIS@{ub}
       (VAR wh: WinHandle) Uninit ();

@{b}   FUNCTION@{ub}
       Clears wh's internal fields.

@{b}   SEE ALSO@{ub}
       @{"WindowHandle/Init()" Link "Init()"},

@EndNode