.TH SH-TK 1.SH NAMEtk, chan, send, recv, alt \- loadable tk module for sh..SH SYNOPSIS.B load tk.B chan.IR name ....br.B send.I chan value.br.B tk window.I title[.I args...].br.B tk winctl.I winid cmd.br.B tk wintitle.I winid title.br.B tk namechan.I chan[.I name].br.B tk del.I name.br.B tk.I winid tkcmd.br.B ${tk window.I title[.I args...].B }.br.B ${tk onscreen.I winid[.I how].B }.br.B ${tk.I winid tkcmd.B }.br.B ${recv.I chan.B }.br.B ${alt.I chan\& ....B }.br.SH DESCRIPTION.B Tkis a loadable module for.IR sh (1)that provides access to Inferno Tk graphicsand string channels.Most of the builtin commands that it defines mapclosely to primitives within.IR wmlib (2)and.IR tk (2).Unless otherwise stated, if a command requiresa.I winidargument, if no window with that id is found, a.B bad winexception is raised. Similarly, a reference toan unknown channel name will raise a.B bad chanexception.There is no requirement that this module be used ina windowing context: although window creation willfail if there is no context, the channel communicationprimitives will work regardless..TP 10.B chanFor each.I namein turn,.B chancreates a new channel called.I namewithin the tk module. .I Namehenceforth represents a Limbo.B chan.B of.B stringand can be used to send string values between.I shprocesses running in parallel. A.I chanis also used to receive events arriving from the windowmanager. It is illegal to create a channel whose nameconsists entirely of numeric digits..TP.B send.B Sendsends its argument.I valuedown the channel.IR chan ,blocking until a corresponding receive operationtakes place on the channel..TP.B tk window.B Tk windowcreates a new top-level window with the text of.I titlein the titlebar at the top. Each window created by thetk module is assigned a unique numeric id. This idis printed by this command; to get access to the valueof the.I winidin a script, use.BR "${tk window}" .All the remaining arguments are joined togetherby spaces and passed as the tk options for the window.When a window is created, a correspondingchannel of the same name is created. Events fromthe window manager arrive on this channel, andshould be responded to appropriately using.BR "tk winctl" ..TP.B tk onscreen.B Tk onscreenmust be called to make window.I winidvisible for the first time, the same as.I onscreenin.IR tkclient (2)..I Howis the same as for that call - if given, it must be one of.BR place ,.BR onscreenor.BR exact ..BR .TP.B tk winctl.B Tk winctlis used to communicate requests to the window manager.(see.B winctl()in.IR wmlib (2)).If an event arriving on a window's channel is passedto.BR "tk winctl" ,a suitable default action will take place.The set of possible actions include:.RS.TP.B exitA request to close the window..TP.B sizeA request to resize the window..TP.B taskA request to miniaturise the window..TP.B moveA request to move the window..RE.TP.B tk wintitle.B Tk wintitlechanges the title of the window.I winidto.IR title ..TP.B tk del.B Tk deldeletes a channel or a window. If.I nameis the.I winidof an existing window, then both thewindow and its associated channel are destroyed.A.B delof a non-existent channel or window is ignored..TP.B tk namechan.B Tk namechaninvokes the Tk module's.B namechan()function to give a tk name to achannel within the tk module.If.I nameis omitted, then the tk name given will bethe same as.IR chan ..TP.BI tk \ winidIf.I winidis the id of an existing window, the rest of thearguments joined together by spacesand sent as a tk command to be interpretedin that window. If the shell is in interactive mode,then the string returned by tk will be printed.The exit status of.B tkis false if the string returned by tk begins witha bang.RB ( ! )character..TP.B ${tk window}.B Tk windowis the same as its command counterpart, exceptthat it yields the.I winidof the newly created window rather than printingit..TP.BI ${tk \ winid }This command is the same as its command counterpart,except that it yields the return value from theTk command as its result..TP.B ${recv}.B Recvreceives a string value from.I chanand yields that value. It will block until a correspondingsend operation takes place on the channel..TP.B ${alt}.B Altwaits until a value is available on any of thenamed.IR chan s.It yields a list containing two elements,the name of the channel from which the value wasreceived, and the actual value received..SH EXAMPLEThe following code creates a window and allowsnormal window manager operations on it. Anothershell in a new process group is created in order to preventthe shell window fromdisappearing when the tk window is deleted..IP.EXshload std tkpctl newpgrpwid=${tk window 'My window'}tk onscreen $widtk $wid updatewhile {} {tk winctl $wid ${recv $wid}} &.EE.SH SOURCE.B /appl/cmd/sh/tk.b.SH SEE ALSO.IR sh (1),.IR sh-std (1),.IR sh-expr (1),.IR tkcmd (1),.IR tk (2),.IR tkclient (2),.IR wmlib (2),``The Tk Reference Manual''
.TH SH-TK 1
.SH NAME
tk, chan, send, recv, alt \- loadable tk module for sh.
.SH SYNOPSIS
.B load tk
.B chan
.IR name ...
.br
.B send
.I chan value
.br
.B tk window
.I title
[
.I args...
]
.br
.B tk winctl
.I winid cmd
.br
.B tk wintitle
.I winid title
.br
.B tk namechan
.I chan
[
.I name
]
.br
.B tk del
.I name
.br
.B tk
.I winid tkcmd
.br
.B ${tk window
.I title
[
.I args...
]
.B }
.br
.B ${tk onscreen
.I winid
[
.I how
]
.B }
.br
.B ${tk
.I winid tkcmd
.B }
.br
.B ${recv
.I chan
.B }
.br
.B ${alt
.I chan
\& ...
.B }
.br
.SH DESCRIPTION
.B Tk
is a loadable module for
.IR sh (1)
that provides access to Inferno Tk graphics
and string channels.
Most of the builtin commands that it defines map
closely to primitives within
.IR wmlib (2)
and
.IR tk (2).
Unless otherwise stated, if a command requires
a
.I winid
argument, if no window with that id is found, a
.B bad win
exception is raised. Similarly, a reference to
an unknown channel name will raise a
.B bad chan
exception.
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.
.TP 10
.B chan
For each
.I name
in turn,
.B chan
creates a new channel called
.I name
within the tk module.
.I Name
henceforth represents a Limbo
.B chan
.B of
.B string
and can be used to send string values between
.I sh
processes running in parallel. A
.I 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.
.TP
.B send
.B Send
sends its argument
.I value
down the channel
.IR chan ,
blocking until a corresponding receive operation
takes place on the channel.
.TP
.B tk window
.B Tk window
creates a new top-level window with the text of
.I 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 command; to get access to the value
of the
.I winid
in a script, use
.BR "${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
.BR "tk winctl" .
.TP
.B tk onscreen
.B Tk onscreen
must be called to make window
.I winid
visible for the first time, the same as
.I onscreen
in
.IR tkclient (2).
.I How
is the same as for that call - if given, it must be one of
.BR place ,
.BR onscreen
or
.BR exact .
.BR
.TP
.B tk winctl
.B Tk winctl
is used to communicate requests to the window manager.
(see
.B winctl()
in
.IR wmlib (2)).
If an event arriving on a window's channel is passed
to
.BR "tk winctl" ,
a suitable default action will take place.
The set of possible actions include:
.RS
.TP
.B exit
A request to close the window.
.TP
.B size
A request to resize the window.
.TP
.B task
A request to miniaturise the window.
.TP
.B move
A request to move the window.
.RE
.TP
.B tk wintitle
.B Tk wintitle
changes the title of the window
.I winid
to
.IR title .
.TP
.B tk del
.B Tk del
deletes a channel or a window. If
.I name
is the
.I winid
of an existing window, then both the
window and its associated channel are destroyed.
A
.B del
of a non-existent channel or window is ignored.
.TP
.B tk namechan
.B Tk namechan
invokes the Tk module's
.B namechan()
function to give a tk name to a
channel within the tk module.
If
.I name
is omitted, then the tk name given will be
the same as
.IR chan .
.TP
.BI tk \ winid
If
.I 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
.B tk
is false if the string returned by tk begins with
a bang
.RB ( ! )
character.
.TP
.B ${tk window}
.B Tk window
is the same as its command counterpart, except
that it yields the
.I winid
of the newly created window rather than printing
it.
.TP
.BI ${tk \ winid }
This command is the same as its command counterpart,
except that it yields the return value from the
Tk command as its result.
.TP
.B ${recv}
.B Recv
receives a string value from
.I chan
and yields that value. It will block until a corresponding
send operation takes place on the channel.
.TP
.B ${alt}
.B Alt
waits until a value is available on any of the
named
.IR chan s.
It yields a list containing two elements,
the name of the channel from which the value was
received, and the actual value received.
.SH 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.
.IP
.EX
sh
load std tk
pctl newpgrp
wid=${tk window 'My window'}
tk onscreen $wid
tk $wid update
while {} {tk winctl $wid ${recv $wid}} &
.EE
.SH SOURCE
.B /appl/cmd/sh/tk.b
.SH SEE ALSO
.IR sh (1),
.IR sh-std (1),
.IR sh-expr (1),
.IR tkcmd (1),
.IR tk (2),
.IR tkclient (2),
.IR wmlib (2),
``The Tk Reference Manual''