english
version "1.0"
identify "wxyz"

# Copyright (c) 1998-1999 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_frame

#: This module implements SWIT frames.


#: {frame} procedures:

procedure application_frame_create@frame
    takes
	clone clone
	uid unsigned
    returns frame

    #: This procedure will create and return an application level
    #, {frame} object for {clone} with a uniquie identifier of {uid}.


procedure button_create@frame
    routine_types
	procedure button_call_back
	    takes button
	    returns_nothing
    takes
	parent frame
	text string
	button_call_back button_call_back
    returns button

    #: This procedure will create and return a {button} object with a
    #, parent frame of {parent}.  The text in the button will
    #, be {text}.


procedure canvas_create@frame
    takes
	parent frame
    returns canvas

    #: This procedure will create and return a {canvas} object 
    #, with a parent frame of {parent}.


procedure children_increment@frame
    takes
	frame frame
    returns_nothing

    #: This procedure will increment the modification count of each
    #, widget in {frame}.


procedure clone@frame
    takes
	master_frame frame
	parent frame
    returns frame

    #: This procedure will create and return a clone of {master_frame}
    #, using {parent} as the parent frame.


procedure create@frame
    takes
	parent frame
	kind frame_kind
	uid unsigned
	clone clone
    returns frame

    #: This procedure will create and return a frame with a unique identifier
    #, of {uid} and a parent frame of {parent}.


procedure destroy@frame
    takes
	frame frame
    returns_nothing

    #: This procedure will destroy {frame}.

    #, exist.  Thus, we will only destroy a frame if it has a parent.

procedure drop@frame
    takes
	frame frame
    returns_nothing

    #: This procedure will cause {frame} to go away.

    #, exist.  Thus, we will only destroy a frame if it has a parent.

procedure entry_create@frame
    takes
	parent frame
    returns entry

    #: This procedure will create and return a {canvas} object with a
    #, parent frame of {parent}.


procedure grid_column_next@frame
    takes
	frame frame
    returns_nothing

    #: This procedure will cause the grid layout manager for {frame} to
    #, be bumped to the next column.
    #, for frame.


procedure grid_column_weight_get@frame
    takes
	frame frame
	column unsigned
    returns unsigned

    #: This procedure will return the weight for the {column}'th column
    #, in frame.


procedure grid_column_weight_set@frame
    takes
	frame frame
	column unsigned
	weight unsigned
    returns_nothing

    #: This procedure will set the {column}'th column weight in {frame}
    #, to {weight}.


procedure grid_increment@frame
    takes
	frame frame
    returns_nothing

    #: This procedure will increment the grid modification count for
    #, {frame}.


procedure grid_row_column_get@frame
    takes
	frame frame
    returns unsigned, unsigned

    #: This procedure will set the row and column for {frame} to {row}
    #, and {column} respectively.


procedure grid_row_column_set@frame
    takes
	frame frame
	row unsigned
	column unsigned
    returns_nothing

    #: This procedure will set the row and column for {frame} to {row}
    #, and {column} respectively.


procedure grid_row_new@frame
    takes
	frame frame
    returns_nothing

    #: This procedure will cause a new row to be started for {frame}.


procedure grid_row_next@frame
    takes
	frame frame
    returns_nothing

    #: This procedure will return the next grid row and column, respectively,
    #, for frame.


procedure grid_row_weight_get@frame
    takes
	frame frame
	row unsigned
    returns unsigned

    #: This procedure will return the weight for the {row}'th row
    #, in frame.


procedure grid_row_weight_set@frame
    takes
	frame frame
	row unsigned
	weight unsigned
    returns_nothing

    #: This procedure will set the {row}'th row weight in {frame}
    #, to {weight}.


procedure grid_weights_update@frame
    takes
	master_frame frame
	clone_frame frame
	is_row logical
    returns_nothing

    #: This procedure will update the grid weights in {clone_frame}
    #, to be the same as {master_frame}.  If {is_row}, the rows are
    #, update; otherwise, the columns are updated.


procedure html_generate@frame
    takes
	frame frame
	html_stream out_stream
	indent unsigned
	delta unsigned
    returns_nothing

    #: This procedure will output {frame} to {html_stream} indented
    #, by {indent}.  New levels are indented by delta.


procedure icon_title_get@frame
    takes
	frame frame
    returns string

    #: This procedure will return the icon title for {frame}.


procedure icon_title_set@frame
    takes
	frame frame
	title string
    returns_nothing

    #: This procedure will return the icon title for {frame}.


procedure increment@frame
    takes
	frame frame
    returns_nothing

    #: This procedure will increment the modification count for {frame}.


procedure is_master_get@frame
    takes
	frame frame
    returns logical

    #: This procedure will return {true}@{logical} if {frame} is
    #, in the master clone and {false} otherwise.


procedure label_create@frame
    takes
	parent frame
	value string
    returns label

    #: This procedure will create and return a {canvas} object
    #, with a parent frame of {parent}.


procedure nested_frame_create@frame
    takes
	parent frame
    returns frame

    #: This procedure will create and return a nested frame that is nested
    #, inside of {parent}, which may be either a top level frame or another
    #, nested frame.


procedure normal_title_get@frame
    takes
	frame frame
    returns string

    #: This procedure will return the normal title for {frame}.


procedure normal_title_set@frame
    takes
	frame frame
	title string
    returns_nothing

    #: This procedure will return the normal title for {frame}.


procedure restore@frame
    takes
	restore restore
	parent frame
	application application
    returns frame

    #, {parent} frame.  If {parent} is ??@{frame}, the frame is
    #, restored into the top level appliation.  The created {frame}
    #, object is returned.


procedure save@frame
    takes
	frame frame
	save_stream out_stream
	supress_prefix string
    returns_nothing

    #: This procedure will save {frame} to {save_stream}.  It will supress
    #, writing out any widgets that have a name that start with
    #, {supress_prefix}.  If {supress_prefix} is ??@{string},
    #, no supression occurs.


procedure search@frame
    takes
	frame frame
	uid unsigned
    returns widget

    #: This procedure will recursively search through {frame} until
    #, it find a {widget} with a unique identifier of {uid} and returns
    #, the matching {widget}.  If no matching {widget} is found,
    #, ??@{widget} is returned.


procedure top_level_create@frame
    takes
	parent frame
    returns frame

    #: This procedure will create and return a top level frame named {name}
    #, and a parent frame of {parent}.


procedure uid_next@frame
    takes
	frame frame
    returns unsigned

    #: This procedure will allocate and return a uniquie identifier using
    #, {frame}.


procedure update@frame
    takes
	master_frame frame
	clone_frame frame
    returns_nothing

    #: This procedure will cause {master_frame} to be replicated
    #, into the {clone_frame}.


procedure widget_delete@frame
    takes
	frame frame
	old_widget widget
    returns_nothing

    #: This procedure will delete {old_widget} from {frame}'s widget list.
    #, This routine assumes that {increment}@{frame} has or will be
    #, invoked somehow.


procedure widget_find@frame
    takes
	frame frame
	uid unsigned
    returns widget

    #: This procedure will find and return the widget with a unique identifier
    #, of {uid} in {frame}.  ??@{frame} is returned if no widget named {name}
    #, can be found in {frame}.


procedure widget_insert@frame
    takes
	frame frame
	new_widget widget
    returns_nothing

    #: This procedure will insert {new_widget} into {frame}'s widget list.
    #, This routine assumes that {increment}@{frame} has or will be
    #, invoked somehow.

    #widgets_show@(frame, debug_stream)



procedure widgets_show@frame
    takes
	frame frame
	out_stream out_stream
    returns_nothing

    #: This procedure will output interesting information about {frame}'s
    #, widgets to {out_stream}.


procedure window_path_append@frame
    takes
	frame frame
	tcl_command tcl_command
    returns_nothing

    #: This procedure will append the window path of {frame} to {tcl_command}.


procedure window_path_create@frame
    takes
	frame frame
	uid unsigned
    returns string

    #: This procedure will return a the Tcl/Tk window path for a widget
    #, named ".w{uid}" in {frame}.