SH-TK(1)                                                 SH-TK(1)

     NAME
          tk, chan, send, recv, alt - loadable tk module for sh.

     SYNOPSIS
          load tk

          chan name...
          send chan value
          tk window title [ args... ]
          tk winctl winid cmd
          tk wintitle winid title
          tk namechan chan [ name ]
          tk del name
          tk winid tkcmd
          ${tk window title [ args... ] }
          ${tk onscreen winid [ how ] }
          ${tk winid tkcmd }
          ${recv chan }
          ${alt chan  ...  }

     DESCRIPTION
          Tk is a loadable module for sh(1) that provides access to
          Inferno Tk graphics and string channels.  Most of the buil-
          tin commands that it defines map closely to primitives
          within wmlib(2) and tk(2). Unless otherwise stated, if a
          command requires a winid argument, if no window with that id
          is found, a bad win exception is raised. Similarly, a refer-
          ence to an unknown channel name will raise a bad chan excep-
          tion.  There is no requirement that this module be used in a
          windowing context: although window creation will fail if
          there is no context, the channel communication primitives
          will work regardless.

          chan      For each name in turn, chan creates a new channel
                    called name within the tk module. Name henceforth
                    represents a Limbo chan of string and can be used
                    to send string values between sh processes running
                    in parallel. A chan is also used to receive events
                    arriving from the window manager. It is illegal to
                    create a channel whose name consists entirely of
                    numeric digits.

          send      Send sends its argument value down the channel
                    chan, blocking until a corresponding receive oper-
                    ation takes place on the channel.

          tk window Tk window creates a new top-level window with the
                    text of title in the titlebar at the top. Each
                    window created by the tk module is assigned a
                    unique numeric id. This id is printed by this

     SH-TK(1)                                                 SH-TK(1)

                    command; to get access to the value of the winid
                    in a script, use ${tk window}.  All the remaining
                    arguments are joined together by spaces and passed
                    as the tk options for the window.  When a window
                    is created, a corresponding channel of the same
                    name is created. Events from the window manager
                    arrive on this channel, and should be responded to
                    appropriately using tk winctl.

          tk onscreen
                    Tk onscreen must be called to make window winid
                    visible for the first time, the same as onscreen
                    in tkclient(2). How is the same as for that call -
                    if given, it must be one of place, onscreen or
                    exact.

          tk winctl Tk winctl is used to communicate requests to the
                    window manager.  (see winctl() in wmlib(2)). If an
                    event arriving on a window's channel is passed to
                    tk winctl, a suitable default action will take
                    place.  The set of possible actions include:

                    exit A request to close the window.

                    size A request to resize the window.

                    task A request to miniaturise the window.

                    move A request to move the window.

          tk wintitle
                    Tk wintitle changes the title of the window winid
                    to title.

          tk del    Tk del deletes a channel or a window. If name is
                    the winid of an existing window, then both the
                    window and its associated channel are destroyed.
                    A del of a non-existent channel or window is
                    ignored.

          tk namechan
                    Tk namechan invokes the Tk module's namechan()
                    function to give a tk name to a channel within the
                    tk module.  If name is omitted, then the tk name
                    given will be the same as chan.

          tk winid  If winid is the id of an existing window, the rest
                    of the arguments joined together by spaces and
                    sent as a tk command to be interpreted in that
                    window. If the shell is in interactive mode, then
                    the string returned by tk will be printed.  The
                    exit status of tk is false if the string returned

     SH-TK(1)                                                 SH-TK(1)

                    by tk begins with a bang (!)  character.

          ${tk window}
                    Tk window is the same as its command counterpart,
                    except that it yields the winid of the newly cre-
                    ated window rather than printing it.

          ${tk winid}
                    This command is the same as its command counter-
                    part, except that it yields the return value from
                    the Tk command as its result.

          ${recv}   Recv receives a string value from chan and yields
                    that value. It will block until a corresponding
                    send operation takes place on the channel.

          ${alt}    Alt waits until a value is available on any of the
                    named chans. It yields a list containing two ele-
                    ments, the name of the channel from which the
                    value was received, and the actual value received.

     EXAMPLE
          The following code creates a window and allows normal window
          manager operations on it. Another shell in a new process
          group is created in order to prevent the shell window from
          disappearing when the tk window is deleted.

               sh
               load std tk
               pctl newpgrp
               wid=${tk window 'My window'}
               tk onscreen $wid
               tk $wid update
               while {} {tk winctl $wid ${recv $wid}} &

     SOURCE
          /appl/cmd/sh/tk.b

     SEE ALSO
          sh(1), sh-std(1), sh-expr(1), tkcmd(1), tk(2), tkclient(2),
          wmlib(2), ``The Tk Reference Manual''