Learn Shen
OS Kernel
OS Library
Shen Professional

More Help

Standard Extension

Programming SP Graphics  


1. Talking to TCL/tk

SP links directly to TCL/tk and all graphics commands are interpreted by TCL/tk.   

The lowest level form of communication is through the talk and tk functions.  tk is a zero-place function that invokes the TCL/tk stream.   talk is a 2-place function that directs a string output to a stream.  The format for the most basic form of communication to TCL/tk is

(talk <string> (tk))

where <string> is taken up by a TCL/tk command.

If you want to talk to TCL and receive a response then

(talk-and-listen-and-wait <string>)

will send a TCL/tk command in a string to TCL/tk and wait for a response. The response will be returned as a string.

Higher-level forms of communication are possible using Shen syntax and many of these commands are present from inception in your SP image.  They need not be loaded from the web because they are used in the SP IDE.   The type theory is loaded from the cloud under the package Tk Types because it is fairly large (TCL/tk is a big language) and is under continuous development. 

Note that the echo check box in the SP IDE root window will echo back error messages from TCL/Tk if this box is checked. By default it is unchecked.

2. The widget Command

The process of creating graphics is a two stage process.

  1. Creating the widgets.
  2. Placing them in a window.
1. Talking to TCL/tk

2. The Widget Command

2.1 Windows
2.2 Buttons
2.3 Labels
2.4 Entries
2.5 Check Buttons
2.6 Radio Buttons
2.7 Canvases
2.8 Menus
2.9 Text Boxes

3. The Attribute-Value Model: putw and getw

4. Placing Widgets

4.1 pack
4.2 analog-grid
4.3 frame

5. Fonts

6. Images

7. Dialog Windows

8. Types

9. Learning More About Widgets and Management

10. Stuff to Watch Out For

The most important command is widget which creates a widget.  widget has the form

(widget <widget name> <widget-type> <options>)

A widget name begins with a dot followed by a symbol S. If S contains no dots then the widget is interpreted relative to the root window (the GUI window that appears when starting SP) and the widget will appear in that window.  A <widget type> can be any of the following.

label button checkbox radiobutton menubutton frame window entry textbox canvas

Options are multitudinous and consist of a series of attribute-value elements.  An attribute has the form -<symbol>.  The available options are taken from TCL/tk. and the symbols are taken from TCL/tk.  For example

(widget .clickme button -text "Click me" -command (freeze (print howdy)))

creates a button called .clickme whose text reads "Click me" and which causes howdy to be printed in the command window.

Here is a brief inventory of the widgets recognised by the widget function.

button A button is an active area of the window that can be clicked to enable commands to be performed.   It can have text written on it.
label A label is exactly like a button except it does not support commands and cannot be clicked.
checkbutton A checkbutton is a button that exists in either a checked or a non-checked state.  It is displayed as a square box with or without a tick and toggles on/off in response to being clicked.
radiobutton A radiobutton is a button that exists in either a checked or a non-checked state.  It is displayed as a circle with or without a dot and toggles on/off in response to being clicked.
menubutton A menubutton is a button that calls up a menu.
entry An entry is a place where a user can type in a line of text.
textbox A textbox is a place where a user can type in multiple lines of text.
canvas A canvas is a place where a user can draw shapes.
window A window exists to support the display of widgets.  Unless specified the window used by default is the root window (the one that pops up when SP is activated).
frame A frame is an invisible box in which widgets can be grouped together into a whole.  The entire group of widgets behaves like a single complex widget and can be placed in a window.

The next sections give examples 

2.1 Windows

(widget .mywin window)creates a window. All widgets are created realtive to that window by making .mywin a prefix of the name that is given to them. Note that if no such prfix is given then widget names are of the form .<name> where <ame> is a dot free symbol. In such a case the widgets would be created in the root window of the SP IDE.

2.2 Buttons

Here is a medley of buttons placed in a window called mywindow.  The final command pack packs all the widgets

(widget .mywin window)

(widget .mywin.b1 button)

(widget .mywin.b2 button -text "Button 2")

(widget  .mywin.b3  button -text "Button 3" -background  "green")

(widget  .mywin.b4  button -text "Button 4" -foreground  "blue")

(widget .mywin.b5 button -text "Button 5" -font "Impact")

(widget .mywin.b6 button -text "Button 6" -relief sunken)

(widget .mywin.b7 button -text "Button 7" -highlightthickness 10)

(widget .mywin.b8 button -text "Button 8" -underline 6)

(widget .mywin.b9 button -text "Button 9" -padx 30 -pady 10)

(widget  .mywin.b10 button 
-text "A very long line of text for a button"
         -justify right -wraplength 50)

(widget  .mywin.b11 button  
-text "A very long line of text for a button"  
 -justify left -wraplength 50)

(widget  .mywin.b12 button  
-text "A very long line of text for a button"  
-justify center -wraplength 50)

(pack [.mywin.b1 .mywin.b2 .mywin.b3 .mywin.b4 .mywin.b5 .mywin.b6
.mywin.b7 .mywin.b8 .mywin.b9 .mywin.b10 .mywin.b11 .mywin.b12])

2.3 Labels

Labels are like buttons and sustain almost the same options, but simply present information and do not sustain the -command attribute.

2.4 Entries

Here is an entry form for a database system using labels and entries. Entries are active areas of text where the user can type his or her input.  This example shows a program that builds a grid of five labels and five entries.  (We will cover the analog-grid function in the section on widget management). 

(widget .mydb window)

(widget label -text "Name")
(widget .mydb.street label -text "Street Number")
(widget label -text "City")
(widget .mydb.state label -text "State/County")
(widget label -text "Country")

(widget  .mydb.namee entry -width 20)
(widget  .mydb.streete entry -width 20)
(widget  .mydb.citye entry -width 20)
(widget  .mydb.statee entry  -width 20)
(widget  .mydb.countrye entry  -width 20)
(putw .mydb.countrye -text "USA")

(analog-grid [[  .mydb.namee]   [.mydb.street .mydb.streete][ .mydb.citye]                  [.mydb.state .mydb.statee] [ .mydb.countrye]]   -padx 10 -pady 10)

 Suppose I type my name into the entry. The expression (getw -text) now returns "Mark Tarver".

2.5 Check Buttons

A check button is similar to an ordinary button except that it carries around with it a binary internal state which toggles on/off according to whether the user has clicked on it.   The default (pre-clicked) state is off.  The check button appears as a small box which carries a tick when it  is in the 'on' state. The following program creates three check buttons.  

 (widget .mywin window)

(widget .mywin.cb1 checkbutton
-command (freeze (toggle .mywin.cb1))) 

(widget .mywin.cb2 checkbutton
-command (freeze (toggle .mywin.cb2))) 

(widget .mywin.cb3 checkbutton
-command (freeze (toggle .mywin.cb3) -text "hi"))

(set *cb1* false)
(set *cb2* false)
(set *cb3* false)

 (define toggle
.mywin.cb1 -> (set *cb1* (not (value *cb1*)))
.mywin.cb2 -> (set *cb2* (not (value *cb2*)))
.mywin.cb3  -> (set *cb3* (not (value *cb3*))))

   (pack [.mywin.cb1 .mywin.cb2 .mywin.cb3])

 Loading the program  allows us to change the value of a global.  

(4-) (value *cb2*)
false : boolean 

(5-) \\Here we first click on .cb2 as shown in picture and then type …
(value *cb2*)
true : boolean

2.6 Radio Buttons 

If we want to use radiobuttons instead of checkbuttons, we use radiobutton instead of checkbutton in the program above.

(widget .mywin window)

(widget .mywin.rb1 radiobutton)
(widget .mywin.rb2 radiobutton)
(widget .mywin.rb3 radiobutton -text "hi")

(pack [.mywin.rb1 .mywin.rb2 .mywin.rb3])

2.7 Canvases

A canvas is a widget on which shapes can be drawn.  A canvas is created by the canvas option.  

(widget .mywin window)
(widget .mywin.canvas canvas)

(pack [.mywin.canvas])

The basic canvas command is draw which has the format

(draw <canvas name> <shape> <coordinates> <options>)

Admissible values for <shape> are line, arc, rectangle, oval, polygon.  Coordinates are given by an even numbered list of 4 or more items.  Lines require at least 4 coordinates.  Here is an example with 6.

 (draw .mywin.canvas  line  [0 0 100 100 125 150])

 The origin of the line begins at the top left hand corner of the canvas and the line extends downwards.  


(draw .mywin.canvas rectangle [50 50 100 150]) produces the canvas below.



2.8 Menus

Menus are created by creating menu buttons and attaching menus to them.

\\ create a window

(widget .mywin window)

\\ Create a menu button with text on it and give the menu it calls
(widget .mywin.mymenubutton menubutton -text "Just a Menu"

\\ create a popup tearoff menu called by the menu button
(widget menu)

\\ Place some menu items on the menu.
(menuitem add -label "Hello"
-command (freeze (print hello)))

(menuitem add -label "Goobye"
-command (freeze (print goodbye)))

\\ pack it!
(pack [.mywin.mymenubutton])

2.9 Text Boxes

Text boxes are similar to entries and allow user input, but sustain multi line input.

(widget .win window)

(widget .win.txt textbox)

(pack [.win.txt])

\\ put a line of text in - rather than just type it in

(putw .win.txt -text "Eight score years and ten ....")

\\ change ten to twenty by the keyboard
\\ and ask for the string value

(getw .win.txt -text)
"Eight score years and twenty ...."

3. The Attribute-Value Model: putw and getw

Widgets in SP are modelled using an attribute-value model. A button has various attributes like foreground color (-fg), command attached (-command) and the values of these attributes are the actual color and commands attached. These values can be retrieved and changed by the getw and putw functions.

(getw <widget name> <attribute>) takes a widget and returns the value of its attribute. (putw <widget name> <attribute> <value>) changes the value of that attribute. Thus (putw .mywin.b -fg "green") will make the text green. (getw .mywin.b -fg) will return "green". Note that only values that are set through SP either by being declared through widget or putw can be retrieved by getw.

4. Placing Widgets

The three essential commands needed to master the the placing of widgets are pack, analog-grid and frame.

4.1 pack

pack has the syntax

(pack <list of widgets> <options>)

By default, pack always packs vertically from top to bottom, separating the buttons by a fixed space.  We can change this.  Assume that we have

(widget .mywin window)

(widget .mywin.b1 button -text "one")
(widget .mywin.b2 button -text "two")
(widget .mywin.b3 button -text "three")
(widget .mywin.b4 button -text "four")
(widget .mywin.b5 button -text "five")

Then the expression below packs a line of buttons from left to right.

 (pack [.mywin.b1 .mywin.b2 .mywin.b3 .mywin.b4 .mywin.b5] -side left) 

The permissible values to –side are left, right, top and bottomtop stacks the successive buttons one on top of the other (the default).  bottom places them underneath each.

Suppose we want to space the buttons; the –padx option will do this, spacing buttons in the x-axis direction.  To create this effect we change the previous pack command to

(pack [.mywin.b1 .mywin.b2 .mywin.b3 .mywin.b4 .mywin.b5] -side left –padx 20) 

The spacing is measured in pixels. 


(pack [.mywin.b1 .mywin.b2 .mywin.b3 .mywin.b4 .mywin.b5] -side top -pady 20) gives the packing shown below.


There are two types of padding; internal and external.  External padding controls the space between the widgets.  Internal padding controls the space between the text on the widget and the edges of the widget.  The expression (pack [.mywin.b1 .mywin.b2 .mywin.b3 .mywin.b4 .mywin.b5] –ipady 25 -padx 50) packs the buttons vertically (the default) with a generous internal padding in the y axis.

We can tell the packer to pack the widgets so that they fill either the x axis or the y axis of the window or both.  The option –fill x/y/none/both does this.  This command packs five buttons so that they fill the x axis.

 (pack [.mywin.b1 .mywin.b2 .mywin.b3 .mywin.b4 .mywin.b5] -fill x)

4.2 analog-grid

A very useful SP command is analog-grid which can be used in place of pack and has much the same options.  The format is

(analog-grid <list of lists of widgets> <options>)

This enables the creation of lists of lists of text widgets where the list structure mirrors the layout of the widgets.  Thus suppose we want to create 4 buttons in a square; then instead of using pack we can write.

(analog-grid [[.mywin.b1 .mywin.b2] [.mywin.b3 .mywin.b4]] -padx 10 -pady 10)

The items in each list are displayed horizontally, left to right and stacked vertically with the required padding to produce this effect. 

4.3 frame

The frame widget command enables a set of widgets to be grouped into an object called a frame.  Once a frame has been created, it can be packed or placed like any other widget.  The effect of packing a frame is to place all its constituent widgets in the position determined by the packing command.

The power of frames is that they allow us to manipulate complex collections of widgets as if they were a single entity.  This is particularly useful when the GUI we want to build has many widgets laid out in different ways.  The widget layouts in SP work best when the layout follows a single format.  But when we want to mix formats then we need to use frames.

Here is a short program showing the use of frames.  We create two frames and four buttons.

(widget .mywin window)

(widget .mywin.f1 frame)
(widget .mywin.f2 frame)
(widget .mywin.f1.b1 button -text "inside frame f1")
(widget .mywin.f1.b2 button -text "also inside frame f1")
(widget .mywin.f2.b3 button -text "inside frame f2")
(widget .mywin.f2.b4 button -text "also inside frame f2")

The identifiers for the buttons, .mywin.f1.b1 .mywin.f1.b2 .mywin.f2.b3 .mywin.f2.b4, show that the first two buttons are embedded in the frame .mywin.f1 and the second two in the frame .mywin.f2.  The purpose of the dot is to isolate the name of the frame (thus neither .mywin.f1b2 or .mywinf1b2 would place the button in the .mywin.f1 frame).  The buttons are now created.

 To pack the buttons we

  1.  Pack them in their frames.
  2.  Pack the frames themselves.

The first two commands pack the buttons in the frames.

(pack [.mywin.f1.b1 .mywin.f1.b2] –side left)
(pack [.mywin.f2.b3 .mywin.f2.b4])

 The final command packs the frames

 (pack [.mywin.f1 .mywin.f2]) 

producing this result. 

(unpack [.mywin.f1 .mywin.f2]) will unpack the widgets.

5. Fonts

The font command creates fonts by giving them a name; the options are -size, -family. For example the largefancy font on the root window showing Professional is created by the following commands.

(font largefancy -size 20 -family "Mistral")
(widget label -text "Professional 10.2" -font largefancy)

6. Images

Labels and buttons can have images placed on them. The image in the root window is created by:

(image logo "logo.gif")
(widget .top.title.logo label -image logo)

(putw .win.b -image "")will remove an image from a widget. (rescale <image> <symbol> <x> <y>) will create a new image called <symbol> from the old image <image> scaled in the x and y axis by sampling pixels, destroying the old image. Thus (rescale mypic mysmallpic 2 2) will rescale the the image mysmallpic to be exactly half the size of mypic

7. Dialog Windows

Dialog windows are windows that pop up according to the flow of control within a program and disable the other GUIs until the user replies to them.  We start with a series of predefined dialog windows called convenience dialog windows. Dialog windows are windows that pop up according to the flow of control within an SP program and disable the other GUIs until the user replies to them.  The most important command for invoking a dialog window is messagebox.

The messagebox function takes a list of options and produces a message box.  Depending on the nature of the user interaction, a string is returned. Here are some examples. 


Message Box


 returns "ok"

(messagebox -message "File deleted")

returns "ok"


-message "Are you sure?"  
-title "Deleting vital file!" 
-type yesnocancel  
-icon warning)

returns "yes"/"no"/"cancel"

  opencolor activates a dialog window that enables the user to choose a color from a color palette.  The function returns an rgb value that represents the color selected.

 (2-) (opencolor)

opencolor returns "" if Cancel is chosen.

openfile and savefile both receive options and display the resident directory.   Selecting a file returns the path name of that file as a string.  savefile allows the user to create a new filename which is returned as a string.  "" is returned if Cancel is chosen.

 (3-) (openfile)
"C://Documents/Computer Science/Languages/Shen/Shen-tk 7.2/debug.txt"


8. Types

In May 2017, the graphics package received a type theory in the form of a plug-in Tk types avaiable through the plug-in button on SP. Since TCL/tk is an enormously large and complex system, the construction of this type theory is an ongoing project.

Tk types covers the material in this introduction and more. Here are the types of the basic functions.

(widget symbol widgetclass (options widget)) : widgetclass

(widget .b button ... <options> ...) returns .b : button. The function widget is thus dependently typed. The type of the object returned depends on the second argument typed to widget. The list of available widgets is button checkbutton radiobutton entry label window frame canvas menu. The symbol becomes an object of type widgetclass on execution; any object introduced by widget (button , label etc) is also of type widget.

(putw W Att V) : A

where V : A and W is a widget and Att is an attribute of the class of widget to which W belongs and A is the type associated with Att.

(getw W Att) : A

where W is a widget and Att is an attribute of the class of widget to which W belongs and A is the type associated with Att.

(draw C S Ns (options S)) : (list A)

where C is a canvas, S is an object of type shape, Ns is a list of numbers and (options S) is a series of options for that shape. Permitted shapes are line arc oval rectangle polygon. This function is dependently typed.

In addition there are sundry functions

image symbol --> string --> image
analog-grid (list (list widget)) --> (options analog-grid) --> (list (list widget))
menuitem symbol --> (options menuitem) --> menuitem
pack (list widget) --> (options pack) --> list widget
font symbol --> (options font) --> font
analog-grid (list (list widget)) --> (options analog-grid) --> (list (list widget))
messagebox (options messagebox) --> string
url string --> string
openfile --> string
openstring --> string
unpack (list widget) --> (list widget)

The permitted combinations wrt to the parameterised options type are given in the following table.

Attribute Permitted Values Widgets/Commands
-command (lazy A) button checkbutton radiobutton
-fg color button checkbutton radiobutton entry label canvas window
-bg color button checkbutton radiobutton entry frame label canvas window
-foreground color button checkbutton radiobutton entry label
-background color button checkbutton radiobutton entry frame label canvas window
-image symbol button label window
-underline number button label
-padx number pack button analog-grid
-pady number pack button analog-grid
-ipadx number pack button analog-grid
-ipady number pack button analog-grid
-relief sunken/raised/flat button label
-justify right/flat/center button checkbutton radiobutton entry label window
-wraplength number button checkbutton radiobutton entry label window
-highlightthickness number button label
-height number button checkbutton radiobutton entry label window
-width number button checkbutton radiobutton entry label window
-text string button checkbutton radiobutton entry label
-font string button checkbutton radiobutton entry label window
-side left/right/top/bottom pack
-fill x/y/none/both pack
-size number font
-family family font
-message string messagebox
-type yes/no/cancel messagebox
-activebackground color button checkbutton radiobutton label
-highlightcolor color button label entry canvas frame window
-repeatdelay number button
-repeatinterval number button
-cursor cursor button checkbutton radiobutton entry window
-anchor n/ne/e/se/s/sw/w/nw/center button
-state normal/active/disabled button checkbutton radiobutton entry
-overrelief sunken/raised/flat button
-compound none/bottom/top/left/right/center button label
-insertofftime number entry canvas
-insertontime number entry canvas
-outline color option for draw ... arc/oval/polygon/rectangle
-color color option for draw ... line
-arrow both/first/last/none option for draw ... line
-start number option for draw ... arc
-extent number option for draw ... arc
-wrap none / char / word textbox
-spacing1 number textbox
-spacing2 number textbox
-spacing3 number textbox
-rmargin number textbox
-overstrike boolean textbox
-offset number textbox
-lmargin1 number textbox
-lmargin2 number textbox
-lmargincolor color textbox
-underlinefg color textbox

An object of type color is a string composed of a hexadecimal number "#xx*yy*zz*" where x, x*, y, y*, z, z*are drawn from 0 1 2 3 4 5 6 7 8 9 a b c d e f or a color is a string from one of the 765 preset colours (e.g. "blanched almond"). A family is a string drawn from the font family viz.

"System" "Terminal" "Fixedsys" "Roman" "Script" "Modern" "Small Fonts" "MS Serif" "WST_Czec" "WST_Engl" "WST_Fren" "WST_Germ" "WST_Ital" "WST_Span""WST_Swed" "Courier" "MS Sans Serif" "Marlett" "Arial" "Arial CE" "Arial CYR" "Arial Greek" "Arial TUR" "Arial Baltic" "Courier New" "Courier New CE" "Courier New CYR" "Courier New Greek" "Courier New TUR" "Courier New Baltic""Lucida Console" "Lucida Sans Unicode" "Times New Roman" "Times New Roman CE" "Times New Roman CYR" "Times New Roman Greek" "Times New Roman TUR" "Times New Roman Baltic" "Wingdings" "Symbol" "Verdana" "Arial Black" "Comic Sans MS" "Impact" "Georgia" "Franklin Gothic Medium" "Palatino Linotype" "Tahoma" "Trebuchet MS" "Webdings" "Estrangelo Edessa""Gautami" "Latha" "Mangal" "MV Boli" "Raavi" "Shruti" "Tunga" "Sylfaen" "Microsoft Sans Serif" "Agency FB" "Arial Narrow" "Arial Rounded MT Bold""Blackadder ITC" "Bodoni MT" "Bodoni MT Black" "Bodoni MT Condensed" "Book Antiqua" "Bookman Old Style" "Bradley Hand ITC" "Calisto MT" "Castellar" "Century Gothic" "Century Schoolbook" "Copperplate Gothic Bold" "Copperplate Gothic Light" "Curlz MT" "Edwardian Script ITC" "Elephant" "Engravers MT" "Eras Bold ITC" "Eras Demi ITC" "Eras Light ITC" "Eras Medium ITC" "Felix Titling" "Forte" "Franklin Gothic Book" "Franklin Gothic Demi" "Franklin Gothic Demi Cond" "Franklin Gothic Heavy" "Franklin Gothic Medium Cond" "French Script MT" "Garamond" "Gigi" "Gill Sans MT Ext Condensed Bold" "Gill Sans MT" "Gill Sans MT Condensed" "Gill Sans Ultra Bold" "Gill Sans Ultra Bold Condensed" "Gloucester MT Extra Condensed" "Goudy Old Style" "Goudy Stout" "Haettenschweiler" "Imprint MT Shadow" "Lucida Sans" "Lucida Sans Typewriter" "MS Outlook" "Maiandra GD" "Monotype Corsiva" "OCR A Extended" "Palace Script MT" "Papyrus" "Perpetua" "Perpetua Titling MT" "Pristina" "Rage Italic" "Rockwell" "Rockwell Condensed" "Rockwell Extra Bold" "Script MT Bold" "Tw Cen MT" "Tw Cen MT Condensed" "Wingdings 2" "Wingdings 3" "Bookshelf Symbol 7" "MS Reference Sans Serif" "MS Reference Specialty" "Tw Cen MT Condensed Extra Bold" "Berling Antiqua" "Bookdings" "Frutiger Linotype"

A cursor is a symbol drawn from the cursor list.

X_cursor arrow based_arrow_down based_arrow_up boat bogosity bottom_left_corner bottom_right_corner bottom_side bottom_tee box_spiral center_ptr circle clock coffee_mug cross cross_reverse crosshair diamond_cross dot dotbox double_arrow draft_large draft_small draped_box exchange fleur gobbler gumby hand1 hand2 heart icon iron_cross left_ptr left_side left_tee leftbutton ll_angle lr_angle man middlebutton
mouse pencil pirate plus question_arrow right_ptr right_side right_tee rightbutton rtl_logo sailboat sb_down_arrow sb_h_double_arrow sb_left_arrow sb_right_arrow sb_up_arrow sb_v_double_arrowshuttle sizing spider spraycan star target tcross top_left_arrow top_left_corner top_right_corner top_side top_tee trek ul_angle umbrella ur_angle watch xterm

9. Learning More about Widgets and Management

To read about the many options to widgets and their management in the TCL/tk documentation.

10. Stuff to Watch Out For

When a set of widgets is created and packed into a window then recreating the same widgets and packing them again into the same window is not a good idea. Experience has proved that this leads to the IDE freezing. Use unpack to unpack the widgets and putw to change their attributes.

After updating a window with widgets, there is sometimes a need to clear the buffer. This shows in the IDE not reponding to the initial window events but behaving properly thereafter. This can be countered by terminating the update with ( which sets the IDE to receive events.

The TCL/tk dot notation rather interferes with packaging. If you place your IDE in a package you need to make the widgets external to that package.