english
version "1.0"
identify "wxyz"

# Copyright (c) 1998 by Wayne C. Gramlich.
# All rights reserved.
#
# Permission to use, copy, modify, distribute, and sell this software
# for any purpose is hereby granted without fee provided that the above
# copyright notice and this permission are retained.  The author makes
# no representations about the suitability of this software for any purpose.
# It is provided "as is" without express or implied warranty.

module swit

#: This module implements SWIT (STIPPLE Window Interface Toolkit)


#: {application} routines:

procedure server_start@application
    takes
	application application
    returns_nothing

    #: This procedure will attempt to start the SWIT server.



#: {event_handler} procedures:

procedure create@event_handler
    takes
	widget widget
	event_number unsigned
    returns event_handler

    #: This procedure will create and return an {event_handler} object
    #, containing {widget} and {event_number}.


#: {event_name} procedures:

procedure string_convert@event_name
    takes
	event_name event_name
    returns string

    #: This procedure will return Tcl/Tk event name for {event_name}.


#: {relief} procedures:

procedure string_convert@relief
    takes
	relief relief
    returns string

    #: This procedure will convert {relief} into a string and return it.


procedure relief_append@relief
    takes
	relief relief
	tcl_command tcl_command
    returns_nothing

    #: This procedure will append {relief} to {tcl_command}.


#: {sticky} procedures:

procedure logical_assemble@sticky
    takes
	north logical
	east logical
	west logical
	south logical
    returns sticky

    #: This procedure will return the {stick} object that corresponds
    #, to the values of {north}, {east}, {south}, and {west}.


procedure logical_extract@sticky
    takes
	sticky sticky
    returns logical, logical, logical, logical

    #, west components of {sticky}.


procedure string_parse@sticky
    takes
	text string
    returns sticky

    #: This procedure will convert {text} into a {sticky}.


procedure string_convert@sticky
    takes
	sticky sticky
    returns string

    #: This procedure will covnert {sticky} into a {string}.


#: {swit} procedures:

procedure application@swit
    routine_types
	procedure initialize_call_back
	    takes application
	    returns_nothing
    takes
	system system
	name string
	initialize_call_back initialize_call_back
    returns unsigned

    #: This procedure will fire up SWIT and its event loop processor.
    #, If necessary, this starts a local SWIT server.  After the
    #, initial connection to the SWIT server has been established,
    #, {initialize_call_back} is invoked with an {application} named
    #, {name} as its only argument.  The call back procedure is used
    #, initialize any top level windows in the application.


procedure application_no_local@swit
    routine_types
	procedure initialize_call_back
	    takes application
	    returns_nothing
    takes
	system system
	name string
	initialize_call_back initialize_call_back
    returns unsigned

    #: This procedure will fire up SWIT and its event loop processor.
    #, If necessary, this starts a local SWIT server.  After the
    #, initial connection to the SWIT server has been established,
    #, {initialize_call_back} is invoked with an {application} named
    #, {name} as its only argument.  The call back procedure is used
    #, initialize any top level windows in the application.


procedure application_create@swit
    routine_types
	procedure initialization_call_back
	    takes application
	    returns_nothing
    takes
	swit swit
	name string
	initialization_call_back initialization_call_back
    returns application

    #: This procedure will create and return an {application} object.


procedure create@swit
    takes
	system system
    returns swit

    #: This procedure will create and return a new {swit} object
    #, ready for building graphical user interfaces.  This procedure
    #, only needs to be called once.


procedure event_loop@swit
    takes
	swit swit
    returns unsigned

    #: This procedure will cause {swit} to start processing events.
    #, A call to {exit}@{swit}() will cause this loop to be exit with
    #, a value that is passed into {exit}.


procedure exit@swit
    takes
	swit swit
	exit_value unsigned
    returns_nothing

    #: This procedure will cause the {event_loop}@{swit} to return with
    #, {exit_value}.


procedure server_start_read_call_back@swit
    takes
	read_channel read_channel[clone]
    returns_nothing

    #: This procedure is called when there is information available from
    #, the SWIT server.


procedure server_start_write_call_back@swit
    takes
	write_channel write_channel[clone]
    returns_nothing

    #: This procedure is called when there is information available from
    #, the SWIT server.


procedure server_code_write@swit
    takes
	swit swit
    returns logical

    #: This procedure will write the SWIT server code out to the file
    #, named {swit_server_executable} with {wish_executable} as
    #, the window shell interpretor to use.  If problems are encounterd,
    #, {false}@{logical} is returned; otherwise, {true} is returned.