/*
 * !tpluslib.panes.h
 *
 * provides routines for easy maintenance of panes in toolbox windows
 *
 *  Tony Howat/Risc User 1997
 *
 * The TPlus library is *not* freeware and should not be distributed by
 * anyone other than Risc User. Those with an official copy of TPlus
 * (on a Risc User Magazine Disc, Special Disc, CD-ROM etc)
 * have an unlimited licence to link the library with their own progams.
 */

#include "toolbox.h"

/* -------------------------- pane_register ---------------------------
 *
 * Description:   Registers a pane and its host window with the pane library.
 *
 * Parameters:    ObjectId win    -- The host window
 *                ComponentId pos -- The component used to position the pane
 *                ObjectId pane   -- The pane
 * Returns:       ...any errors.
 * Other Info:    The host window (win) has been positioned and opened.
 *                pos contains the componentid of the gadget to use to
 *                position the pane.
 *
 *                pane is the objectid of the pane to put there.
 *                pane_register shows the pane in the appropriate position
 *                and registers handlers to win to deal with redraws etc.
 *                The pane is automatically hidden when the host
 *                window is closed.
 *
 *                "Host" Windows
 *                
 *                * Should have "Auto Open" unset
 *                * Should have either the default hidden event on, or a
 *                  user event set. If you use the event in your own
 *                  handler you should not claim it, so your handlers
 *                  should return zero.
 *                * Should not have scroll bars, size icons or toggle icons.
 *                
 *                Pane Windows
 *                
 *                * Should have "Moveable" unset and "Pane" set in the
 *                  "Other Properties" dialogue.
 *                * Should not have size or toggle size icons                
 *
 *                Finally you should also be calling alarm_event_poll instead
 *                of event_poll in your poll loop. The panes library uses
 *                alarm to deregister toolbox handlers (avoiding a known bug
 *                in the toolbox) and also uses it to reposition windows and
 *                panes on mode changes.
 */
 
extern _kernel_oserror *pane_register(ObjectId win, ComponentId pos, ObjectId pane);

/* ------------------------- pane_deregister --------------------------
 *
 * Description:   Forces the deregistration of the pane library routines
 *                for win concerning a pane.
 * Parameters:    ObjectId win    -- The host window
 *                ObjectId pane   -- The pane
 * Returns:       ...any errors.
 * Other Info:    The pane is hidden. Deregistration is usually done
 *                when the pane library picks up a close message from
 *                the host window.
 */

extern _kernel_oserror *pane_deregister(ObjectId win, ObjectId pane);

/* ---------------------------- pane_init ----------------------------
 *
 * Description:   Should be called in the initialisation of any program
 *                using the panes library.
 * Parameters:    void
 * Returns:       void
 * Other Info:    Just calls alarm_init();
 *
 */

extern void pane_init(void);
