home *** CD-ROM | disk | FTP | other *** search
Text File | 1996-03-29 | 51.1 KB | 1,419 lines
% (c) C.T.Stretch 1996 \documentstyle[12pt,a4wide]{report} \title{Writing RiscOS Applications using Tcl and w} \author{C.T.Stretch} \date{March 29,1996\\ For w version 1.2} \begin{document} \pagestyle{headings} \maketitle \begin{titlepage} \begin{center} {\Large Introduction to Tcl and w} \end{center} This manual describes the use of the w extensions of Tcl to write desktop application for machines running RiscOS. Tcl (pronounced tickle ) is a simple interpreted scripting language. It is extensible in that it is easy to add commmands to Tcl, and embeddable in that it can be included in other applications. Tcl was invented and implemented by John K.Ousterhout, originally for unix systems. It is usually used with an extension to the x windowing system called Tk, either embedded in applications, or using a general purpose Tcl/Tk program called wish. Tcl can also be used from the command line using another program called tclsh. Unix Tcl is split into a generic part and a POSIX extension, containing the unix-specific operations such as file handling. The w extensions provide simple interfaces to the RiscOS desktop in Tcl. they do not attempt to be compatible with, or as comprehensive as Tk. They provide an iconbar icon, menus, simple dialog boxes, scrolling windows for text display, and windows for draw type graphics. They can run command line tasks using the taskwindow system. The w extensions are usually run from program called shade. They could also be embedded in RiscOS applications in c. Tasks running w can communicate with each other. The RiscOS extensions provide equivalent functions to most of the POSIX extensions that are appropriate for RiscOS. This manual covers wimp programming using w. It also contains a brief description of the RiscOS extensions and a list of Tcl commands. The manual does not attempt to teach Tcl programming. You will need to be familiar with this before attempting to use w. Possible sources of Tcl documentation include \begin{enumerate} \item The book "Tcl and the Tk Toolkit" by J.K.Ousterhout (Addison Wesley 1994) ISBN 0-201-63337-X. \item The online documentation. \item A manual in html format avaliable by ftp as \verb|ftp://ftp.bdt.com/home/elf/pub/tcltk-man-html6.tar.gz| \end{enumerate} A RiscOS application using shade will need to be provided with the usual application directory and files. The !Run file should call shade with argument a Tcl script file. The TclNew application will create a basic version of these. \end{titlepage} \tableofcontents \sloppy \chapter{Basics} \section{Introduction} The w commands operate by installing a selection of scripts that are called when various wimp events such as mouse clicks occur. \subsubsection{Example} \begin{verbatim} w_init myprog w_bar -click {clickproc} proc clickproc {}\ { set res [w_error "Someone has clicked on my icon" -ok -cancel] if {res==0} exit } \end{verbatim} The \verb|w_init| command starts up the wimp. The application will have name ``myprog'' in the task display list. \verb|w_bar| puts an wimp sprite called !myprog on the iconbar. If it is clicked on the script ``clickproc'' is interpreted. The clickproc script opens a wimp error window with ``OK'' and ``Cancel'' icons. If the cancel icon is clicked \verb|res| is set to zero and the application exits. \subsection{Percent substitution} Before the scripts are interpreted \%-substitution takes place in order to pass any necessary arguments to the script. The script is scanned for \% characters. If the \% is followed by a lower case letter the percent and letter are replaced by a string, otherwise the \% but not the character is dropped. The avaliable substitution letters depend on the event concerned and are summarized below. Fuller details can be found in later chapters. \begin{center} \begin{tabular}{|c|c|l|} \hline letter&Event&value\\ \hline \verb|%b|&Mouse button events&\verb"a|s[S][C]"\\ \verb|%x|&Mouse clicks in draw diagrams&x--coordinate\\ \verb|%y|&Mouse clicks in draw diagrams&y--coordinate\\ \verb|%d|&Dialog box actions&\verb|<tag>|\\ \verb|%t|&Save and load requests&filetype\\ \verb|%w|&Window and menu events&identifier\\ \verb|%o|&Taskwindow output&the output\\ \verb|%n|&Taskwindow output or quit&task identifier\\ \hline \end{tabular} \end{center} Using other letters can have unpredictable results. \subsection{Error handling} If an uncaught error occurs while interpreting these scripts, or while interpreting the source file after \verb|w_init| has been called two things happen \begin{enumerate} \item The global variable \verb|w_where| is set to a string indicating which script the error occured in, for example ``iconbar click'' if the error occurs when interpreting a script after the iconbar icon is clicked. \item The contents of global variable \verb|w_debug| are interpreted. \end{enumerate} \verb|w_init| sets \verb|w_debug| to \begin{verbatim} "if {![w_error \"Error in $w_where :- $errorInfo\" -ok -cancel]} exit" \end{verbatim} This puts up a wimp error box indicating the place and nature of the error. If you click on ``Cancel'' the program exits, on ``OK'' and it continues, abandoning the script. {\bf Note:} If an error occurs before a call to \verb|w_bar| and you continue you will not have an iconbar icon and must quit from the task display. The file \verb|!Tcl.library.debug| contains a slightly more sophisticated debugging system. To use it put the line \begin{verbatim} source {<tcl$Dir>.library.debug} \end{verbatim} in your code {\em after} the call to \verb|w_init|. \subsection{Return values from event scripts} An event script normally returns the result of its last command. The \verb|return| command can be used to return at any stage with an optional result. Some event handlers make use of the returned values, for example if a script is run in response to a click on an action button in a dialog box the box will be closed if the script returns zero. Such scripts return small integer values. String constants are provided as an alternative to the numbers to make scripts more readable. \begin{center} \begin{tabular}{|c|c|c|c|c|} \hline Number&Saving&Action buttons&Close window&Options\\ \hline 0&close&close&close&off\\ 1&show&show&show&on\\ 2&failclose&&hide&\\ 3&failshow&&&\\ \hline \end{tabular} \end{center} An empty string is considered equivalent to zero. Details of the response to these values are given below. \section{Command descriptions} The descriptions of commands and data in this manual use the following conventions \begin{center} \begin{tabular}{|c|c|c|} \hline &Example&Meaning \\ \hline Angle brackets&\verb|<taskname>|&Substitute an object of the required type\\ Brackets&\verb|[-ok]|&Optional.\\ Braces&\verb|{<component>}|&One or more of.\\ Quotes&\verb|'<'|&Include the text literally.\\ \hline \end{tabular} \end{center} Command syntax descriptions may not be complete. Information such as which options can go together or whether a specific order is required is given in the following text. \section{Commands} \begin{center} \begin{tabular}{|l|} \hline \verb|w_init <taskname> [<spritefilename>]|\\ \hline \verb|w_bar [-menu <menudescription>] [-click <script>] [-drag <script>]|\\ \hline \verb|w_error <string> [-ok] [-cancel]|\\ \hline \verb|w_info <name>|\\ \hline \end{tabular} \end{center} The \verb|w_init| command initializes the w extensions and registers the task as a wimp application. It must be called before any of the other w commands. It can be called once only. \verb|<taskname>| has a maximum of eight characters, it is used for the program name in the task display. It is also used as a default window title and as a prefix for taskwindow tasknames. If the application puts an icon on the iconbar using the \verb|w_bar| command the sprite used will be called \verb|!<taskname>|. If the optional \verb|<spritefile>| is given, a user sprite area is set up and the sprite file \verb|<<taskname>$Dir>.<spritefile>| is loaded. These sprites can be used in draw diagrams and dialog boxes. The \verb|w_bar| command puts an icon called \verb|!<taskname>| from the wimp sprite area on the iconbar. (You should include such an icon in your application's \verb|!Sprites| and \verb|!Sprites22| files if you want to use \verb|w_bar|). You can attach a menu, a script to be called when the icon is clicked on, and a script to be called when an icon is dropped on your icon. Before the click script is run the \%b substitution is set to a string representing the mouse button used and the modifier keys held down. The string consists of ``a'' for alter or ``s'' for select, followed by ``S'' if the shift key is down then folowed by ``C'' for the control key. Before the drag script is run the global variable \verb|w_file| is set to the filename and the \%t substitution to the file type. The \verb|w_error| command displays a wimp error box containing \verb|<string>| truncated to 200 characters. The options give the box ``OK'' and ``Cancel'' buttons. If neither are given an ``OK'' button is provided. The command returns 1 if the ``OK'' button was used and 0 for ``Cancel''. The \verb|w_info| command returns information on the state of the w system. The possible name parameters are detailed in the chapters below. \section{Common parameters} \subsection{Lengths} Lengths in w commands are given by a (possibly floating point) number possibly followed immediately by a single letter unit. If no unit letter is given the length is in OS units. The unit letters are \begin{center} \begin{tabular}{|cl|} \hline \verb|<letter>|&Unit\\ \hline i &inches\\ m &millimeters\\ c ¢imeters\\ p &points\\ d &draw units\\ \hline \end{tabular} \end{center} \subsubsection{Example} \begin{verbatim} w_text mywind create -width 6.5i \end{verbatim} Creates a text window 6.5 inches wide. \subsection{Fonts} Fonts can be specified in w in two ways \begin{center} \begin{tabular}{|lcl|} \hline \verb|<font>|&$=$&\verb|f<name>[@<length>]|\\ \verb|<font>|&$=$&\verb|F<fontname>[@<length>]|\\ \hline \end{tabular} \end{center} The second form takes a pathname in a font directory. The first looks up \verb|fonts(<name>)| in the global array \verb|fonts| to obtain a fontname. The array ``font'' is usually set up with standard names of font types, allowing users to specify their preferences. \begin{center} \begin{tabular}{|ll|} \hline \verb|<name>|&Use\\ \hline n & normal font\\ i & italic font\\ b & bold font\\ t & typewriter (monospaced) font\\ a & alternative font\\ & (e.g. sans-serif if the others have serifs)\\ \hline \end{tabular} \end{center} \subsubsection{Example} \begin{verbatim} set fonts(n) Trinity.Medium set fonts(i) Trinity.Italic set fonts(b) Trinity.Bold w_text mytext write "This is |fi|italic, |fn| this is |fb|bold" w_draw mydiagram text (1,1) "This is big and bold" -FTrinity.Bold@40p \end{verbatim} The first three lines set suitable values in the fonts array. The next two put text in a text document and a draw diagram. \subsection{Colours} Colours can be specified in w in two ways \begin{center} \begin{tabular}{|lcl|} \hline \verb|<colour>|&$=$&\verb|<number>:<number>:<number>|\\ \verb|<colour>|&$=$&\verb|<name>|\\ \hline \end{tabular} \end{center} In the first form they are given by three numbers in the range 0 to 255 representing the red, green and blue components separated by colons. Alternatively if a name, not beginning with a digit, is given it is looked up as \verb|colours(<name>)| in the global array \verb|colours| to obtain a number sequence of the above form. The name \verb"none" gives a transparent ``colour'' for draw path objects. \subsubsection{Example} \begin{verbatim} set colours(red) 255:0:0 w_text mytext create -fg red -bg 200:200:255 \end{verbatim} This creates a text window with red text on a pale blue background. \subsection{Identifiers} Several w commands such as the \verb|w_text| command for creating text documents take an \verb|<identifier>| parameter. The identifier can be any Tcl string, usually a name. This is passed to the object when it is created, and used to identify the object in other calls. Two objects of the same type must be given different identifiers. \subsubsection{Example} \begin{verbatim} w_text output create w_text output print "Hello World" w_text output open \end{verbatim} This creates a scrolling text document with identifier ``output'', puts some text in it and then opens a window on it. \subsection{File types} File types can be specified for some commands. They can be a number in decimal octal or hexadecimal, or a name. Special names are ``directory'' and ``application'', other names are looked up in system variables \verb|File$Type_<name>|. \subsubsection{Examples} \begin{verbatim} glob "$.*" Tcl glob "$.*" 0x12e w_box newbox create tclnew\ { vlist {save application outdir {savedrag $w_file }} {hlist {action Cancel} {default Save {saveclick }}} } \end{verbatim} The two \verb|glob| commands both give a list of all files of type Tcl in the root directory. The \verb|w_box| command creates a dalog box for saving applications. The \verb|save application ...| ensures that the save icon uses the correct sprite to save an application. \section{Variables used by w} \begin{center} \begin{tabular}{|lp{3in}|} \hline \verb|w_where|&Set after an uncaught error. Gives the name of the handler that called this script.\\ \hline \verb|w_debug|&Script to run after an uncaught error.\\ \hline \verb|w_file|&Filename for a save or load.\\ \hline \verb|w_version|&Returns the version of the w extensions to Tcl as a decimal.\\ \hline \end{tabular} \end{center} \chapter{Dialog boxes} \section{Introduction} Dialog boxes are constructed and opened in w using the \verb|w_box| command. Dialog box creation is a two stage process. First a dialog box {\em template} is created. This is a permanent structure that describes the appearance and function of a dialog box. Dialog boxes can be created from templates in two ways. A persitent dialog box can be opened, this remains on display until the user closes it. A dialog box template can be attached to a menu, a box is then opened automatically when the menu entry is traversed. It is closed when the menu is closed. Dialog boxes in w are created when they are displayed and destroyed when they are removed from display. The content of a dialog box is made up of one or more {\em components}. A component consists of a small number (possibly zero) of icons that contribute to a common purpose. Some components are {\em containers}, they serve to organize other components into lists or boxes. The contents of component icons are passed via global variables. The name of the variables are given in the templates. If more than one dialog box is used from the same template it may be necessary to separate the variables. To do this a dialog box can be {\em tagged}. If a box is tagged the variable name refers to a global array, and the {\em tag} to an element name within the array. Each dialog box template has an {\em identifier}. This is a name that is passed to the template during creation, and used to refer to it when a persistent box is opened and when a transient box is attached to a menu. \subsubsection{Example} \begin{verbatim} w_box filebox create "File Name"\ { vlist {write Filename fname } {default Set {return show}} } w_box filebox open \end{verbatim} The create command creates a dialog box template with identifier ``filebox''. This has one component, a vertical list. The list is a container with two components, a writable icon labelled ``Filename'' and and a default action item labelled ``Set''. The writable icon keeps its contents in variable ``fname''. The default action icon runs the script ``return show''. The second command opens a copy of ``filebox'' as a persistent dialog box. \section{Dialog box components} Each component is a single Tcl word, it is broken up into words, the first being the component type, and the remainder arguments depending on the type. \subsection{Action buttons} \begin{center} \begin{tabular}{|l|} \hline \verb|action <name> [script]|\\ \hline \verb|default <name> [script]|\\ \hline \end{tabular} \end{center} These give a action button icon with \verb|<name>| on it. A mouse click on the icon causes the following action: If there is no script the box is just closed. If there is a script the script is interpreted, and the result is examined. If the script returns ``close'' or ``0'' the box is closed. If it returns ``show'' or ``1'' it is not. If \verb|<name>| is ``Cancel'' the same action takes place if the escape key is pressed with the caret in the dialog box. A \verb|default| component is the same as \verb|action| component, except that the icon has a border, and its action takes place if the return key is pressed with the caret in the dialog box. Before any script is interpreted the \verb|%d| substitution is set to the dialog box tag and any variables associated with the dialog box are set. \subsection{Display fields} \begin{center} \begin{tabular}{|l|} \hline \verb|info <name> <text>|\\ \hline \verb|display <name> <variable> [<width>]|\\ \hline \verb|watch <name> <variable> [<width>]|\\ \hline \end{tabular} \end{center} These components display a label and a string. The label contains \verb|<name>| For the \verb|info| component the string is given as \verb|<text>| when the {\em template} is created. For the \verb|display| and \verb|watch| components it is read from \verb|<variable>| when a box is opened. In the case of \verb|watch| components it is also updated whenever the variable is altered while the box is open. \verb|display| and \verb|watch| components can be given a \verb|width| argument that gives the number of characters of the string that can be displayed. This defaults to 20. \subsection{Adjustable components} \begin{center} \begin{tabular}{|l|} \hline \verb|option <name> <variable>|\\ \hline \verb|radio <name> <variable>|\\ \hline \verb|write <name> <variable> [<width>] [<length>]|\\ \hline \end{tabular} \end{center} These components are adjustable by the user. They each take an initial value from a global variable. Before any script associated with the dialog box is interpreted the variables are {\em set}. This involves copying the values from the components back into the variables. Option component variables contain ``0'' if they are deselected and ``1'' if they are selected. Radio components are in the same group if they have the same variable. There can be a maximum of 15 different groups of radio components in one dialog box. This variable is set to \verb|<name>| for the selected component. \subsection{Decorative components} \begin{center} \begin{tabular}{|l|} \hline \verb|sprite <spritename>|\\ \hline \end{tabular} \end{center} The sprite component display a sprite. The sprite is looked for first in the user sprite area and then in the wimp sprite area. \subsection{Saving} \begin{center} \begin{tabular}{|l|} \hline \verb|save <filetype> <variable> <script>|\\ \hline \end{tabular} \end{center} This component consists of a draggable icon corresponding to the filetype and a writeable icon. When the icon is dragged it asks the task it is dropped on to save a file whose leafname is taken from the writeable icon. If the task responds the script is interpreted with the global variable \verb|w_file| set to the full filename required. Variables are set before the script is interpreted. The \verb|%d| substitution is set to the dialog box tag. The script should save to the required filename. The possible return values of the script are given by \begin{center} \begin{tabular}{|c|c|c|} \hline String&Number&Meaning\\ \hline \verb|close|&0&Save succeeded, close the dialog box\\ \verb|show|&1&Save succeeded, leave the dialog box open\\ \verb|failclose|&2&Save failed, close the dialog box\\ \verb|failshow|&3&Save failed, leave the dialog box open\\ \hline \end{tabular} \end{center} \subsection{Container components} \begin{center} \begin{tabular}{|l|} \hline \verb|box <name> <component>|\\ \hline \verb|vlist {<component>}|\\ \hline \verb|hlist {<component>}|\\ \hline \end{tabular} \end{center} \verb|box| draws a box round \verb|<component>| with \verb|<name>| written on it. \verb|vlist| and \verb|hlist| construct vertical and horizontal lists of components. \section{Commands} \begin{center} \begin{tabular}{|l|} \hline \verb|w_box <identifier> create <title> <component> [-tag]|\\ \hline \verb|w_box <identifier> open [<tag>]|\\ \hline \verb|w_info templates|\\ \hline \end{tabular} \end{center} The \verb|create| option creates a dialog box template with the given identifier and title. The contents of the box are \verb|<component>|. This will usually be a container component. The \verb|-tag| option determines if a {\em transient} box from this template is tagged. Such a box will be given the tag (if any) of the menu it is opened from. The \verb|open| option opens a persitent dialog box from the template. If required a name can be passed as a tag. \subsubsection{Example} \begin{verbatim} w_box mytemplate create "A silly dialog box"\ { vlist {info Info "text display" } {display Display displayvar} {watch Watch watchvar} {write Write writevar} {hlist {option Opt1 opt1 } {option Opt2 opt2 } {option Opt3 opt3 } } { box "A box" { hlist {radio Radio1 radiovar} {radio Radio2 radiovar} {radio Radio3 radiovar} } {sprite !tcl} {hlist {action Cancel {set boxisopen 0}} {action Show {showvars;return show}} {default " OK " {showvars;set boxisopen 0}} } } w_box mytemplate open box1 \end{verbatim} The \verb|create| option creates a template with a variety of components. The \verb|open| command opens a persistent box from this template. This box will use global variables \verb|displayvar(box1)|, \verb|watchvar(box1)|, \verb|writevar(box1)|, \verb|opt1(box1)|, \verb|opt2(box1)|, \verb|opt3(box1)| and \verb|radiovar(box1)|. If a transient box is opened from a menu using this template it will use global variables \verb|displayvar|, \verb|watchvar|, \verb|writevar|, \verb|opt1|, \verb|opt2|, \verb|opt3| and \verb|radiovar|, since no \verb|-tag| option was used when creating the template. The \verb|w_info templates| command returns a list of all template identifiers. \section{Dialog box layout} The layout of dialog boxes in w is not perfect. It attempts to design the box from the component descriptions without additional input from the programmer. It may not be possible to do this well. The component sizes are calculated according to the style guide assuming that characters are in the system font. This may not be correct for other fonts. Short strings of wide characters may not fit in their icons. This can be cured by adding spaces. \subsubsection{Example} \begin{verbatim} w_box mytemplate create "A small dialog box"\ { vlist {info Info "text display" } {hlist {action Cancel {set boxisopen 0}} {default " OK " {set boxisopen 1}} } } \end{verbatim} The OK should now fit in its icon. A row of similar components all of different sizes does not look good. w attempts to correct this by {\em equalizing}. If several components of the same type are consecutive in a vertical or horizontal box they are enlarged to the size of the largest. This does not apply to container components or sprites, these components are also ignored when checking for consecutives. If you have, say, a vertical list consisting of horizontal lists of one component type, these will only be equalised within the individual horizontal lists. You can force them all to the same size by padding with spaces. \subsubsection{Example} \begin{verbatim} w_box mytemplate create "Another box"\ { vlist {hlist {{radio " R1 " FMvar} {radio R2 FMvar}} hlist {{radio Local1 MWvar} {radio Local2 MWvar}} } } \end{verbatim} The padding around R1 will cause all four radio components to have the same size. When the sizes of the individual components have been decided they are locked together into lists. When locking a vertical list the narrower components are padded with space. The space is put equally at the ends and between any sub--components. In particular individual items are centered. A similar vertical padding occurs when locking a horizontal list. \chapter{Menus} \section{Introduction} w menus are created from textual menu descriptions. They can be attached to the iconbar, to draw diagrams and to text documents. They can have submenus and transient dialog boxes attached. Entries can be ticked or greyed out. \section{Menu descriptions} A menu description is a word that decomposes into a list. The first item of the list is the menu title, the remainder are menu item descriptions. There must be at least one of the latter. A menu item description is a word that decomposes into a list, the first item is the text that appears in the menu. Any remaining items are \begin{center} \begin{tabular}{|lp{3in}|} \hline \verb|-tag|&Tag the menu item by the window identifier or ``bar''\\ \hline \verb|-click <script>|&Run script if this item is selected\\ \hline \verb|-tick <variable>|&The item can be ticked or unticked by selecting it. The tick status (0 or 1) is stored in the variable. you can change it by writing to the variable you can monitor it with a trace on the variable.\\ \hline \verb|-grey <variable>|&Uses the variable to decide whether the item is greyed out. A value of 1 will grey out the entry, 0 will not.\\ \hline \verb|-sub <menudescription>|&Create a submenu.\\ \hline \verb|-dbox <identifier>|&Open a transient dialog box.\\ \hline \end{tabular} \end{center} \verb|-sub| and \verb|-dbox| cannot be used together. \verb|-click| and \verb|-tick| cannot be used together. \verb|-tag| must preceed any \verb|-tick|, \verb|-grey| or \verb|-dbox| options. The percent substitution \%w is set to the window identifier or ``bar'' for an iconbar menu when a menu is open. \subsubsection{Example} \begin{verbatim} w_bar -menu { wtest {Info -dbox progInfo} {Process -click process -grey notready} {Save -dbox saveBox -click {saveMclick %w}} {Quit -click exit} } \end{verbatim} This puts an icon with a menu on the iconbar. The process entry is greyed out if global variable \verb|notready| is 1. If the item description read \verb|{Process -tag -click process -grey notready}| the entry would be greyed out if global \verb|notready(bar)| was 1. Notice the Save entry has both a dialog box and a click script. \chapter{Text documents} \section{Introduction} Simple text document display can be handled using the \verb|w_text| command. A blank document can be created, the formatting options such as margins can be adjusted and text can be added to the document with or without wrapping and justification. One or more scrolling windows can be opened on the document. \subsection{Text processing} When text is entered into a document using the write or print commands a text processing option may be turned on or off. If it is off the text is included verbatim except that any control characters are replaced by spaces. The text is displayed in a font and colour specified when the document is created. If processing is on sequences starting with a bar (\verb"|") are interpreted as font or colour changes. \begin{center} \begin{tabular}{|ll|} \hline \verb"|<font>| "&Change font\\ \verb"|c<colour>|"&Change colour\\ \verb"||"&Display a \verb"|"\\ \hline \end{tabular} \end{center} \section{Commands} \begin{center} \begin{tabular}{|l|} \hline \verb|w_text <identifier> create {options}|\\ \hline \verb|w_text <identifier> options {options}|\\ \hline \verb|w_text <identifier> open|\\ \hline \verb|w_text <identifier> print {<strings>}|\\ \hline \verb|w_text <identifier> write {<strings>}|\\ \hline \verb|w_info documents|\\ \hline \end{tabular} \end{center} The \verb|create| command creates a document with the given identifier. Possible options are \begin{center} \begin{tabular}{|lp{3in}|} \hline \verb|-title <string>|& Sets the title for any windows on the document.\\ \hline \verb|-close <script>|&Runs the script when the user attempts to close the last window on the document. \%w is set to the document identifier. The script can return:- \begin{tabular}{|c|c|c|} \hline 0&close&Close window and diagram.\\ 1&show&Close neither.\\ 2&hide&Close window only.\\ \hline \end{tabular} If no \verb"-close" option is given the window and document are both closed.\\ \hline \verb|-fg <colour>|&Sets the main text colour. Default black.\\ \hline \verb|-bg <colour>|&Sets the background colour. Default white.\\ \hline \verb|-menu <menudescription>|&The menu is opened from any of the document's windows.\\ \hline \verb|-width <length>|&Sets the window width.(Default 800 os units)\\ \hline \verb|-size <length>|&Sets the main font size (Default 20p)\\ \hline \verb|-height <length>|&Sets the separation between lines. ( Default depends on main font size.)\\ \hline \end{tabular} \end{center} The options command sets some options that apply to text added by \verb|write| or \verb|print| after the \verb|options| command. The possible options are \begin{center} \begin{tabular}{|lp{3in}|} \hline \verb|-l<length>|&Left margin (from left of window).\\ \hline \verb|-i<length>|&Paragraph indent (write only) (from left of window).\\ \hline \verb|-r<length>|&Right margin (from right of window).\\ \hline \verb"-j[on|off]"&Justify (write only).\\ \hline \verb"-p[on|off]"&Process.\\ \hline \verb|-L|&Set left (print only).\\ \hline \verb|-C|&Center (print only).\\ \hline \verb|-R|&Set right (print only).\\ \hline \end{tabular} \end{center} The initial defaults are \verb|-l0 -i0 -r0 -joff -poff -L|. In justify or process ``off'' or ``on'' can be replaced by 0 or 1. The print and write commands concatenate their string arguments with space separators. Control characters are replaced with spaces. Processing takes place if it is turned on. The \verb|print| command displays the result as a single line, which may overflow the page if it is too long. Print sets the line left, right or centered as required. The \verb|write| command splits the text into lines. The first line is inset by the paragraph indent. If the justify option is on all except the last line will be justified to both margins. Both print and write scroll the most recently opened window (if any) to show the new text. The \verb|open| command opens a new window to display the document. The \verb|w_info documents| command returns a list of all document identifiers. \subsubsection{Example} \begin{verbatim} w_text mytext create -title "A text window"\ -fg blue\ -width 6i\ -height 30p\ -size 20p\ -close {expr 2}\ -menu $docmenu w_text mytext options -l0.5i -pon w_text mytext write "This is |fi|italic, |fn| this is |fb|bold" w_text mytext open \end{verbatim} \chapter{Draw diagrams} \section{Introduction} Draw diagrams can be created, displayed and saved in w. At present they support four types of object: text, paths, sprites and group objects. Font description objects are managed automatically to support fonts used in text objects. When an object is created a number is returned that can be used to identify the object if it needs to be removed later. Coordinates in diagrams are in user defined units with origin at the bottom left hand corner. \section{Object descriptions} There are four types of objects displayed in draw diagrams: text objects, path objects,sprites and group objects. \subsection{Text objects} \begin{center} \begin{tabular}{|l|} \hline \verb|<textobject> = text <point> <string> <options>|\\ \hline \verb|<point> = (<number>,<number>)|\\ \hline \end{tabular} \end{center} The possible options are \begin{center} \begin{tabular}{|lp{3in}|} \hline \verb|-<font>|&The font.\\ \hline \verb|-c<colour>|&Text colour.\\ \hline \verb|-b<colour>|&Background colour hint.\\ \hline \verb"-o[l|c|r][t|m|b]"&Determines which point in the text is placed at the given point. The first character is the x--position; l for left r for right c for center or nothing for the text baseline left. The second character is the y--position; t for top, m for middle, b for bottom or nothing for the text baseline. \\ \hline \end{tabular} \end{center} \subsubsection{Example} \begin{verbatim} w_draw mydiagram text (3,5) "Hello World" -ocm -cgreen \end{verbatim} Draws green text centered at $(3,5)$. \subsection{Path objects} \begin{center} \begin{tabular}{|l|} \hline \verb|<path object> = path <path sequence> <options>|\\ \hline \verb|<path sequence> = <point>{<gap><point>}[.]|\\ \hline \end{tabular} \end{center} A terminating full stop indicates that the path is closed. Gaps can be \begin{center} \begin{tabular}{|lp{3in}|} \hline nothing&Move between points.\\ \hline \verb|-|&Join points with line.\\ \hline \verb|'<'<point><point>'>'|&Draw a Bezier curve with the given control points\\ \hline \end{tabular} \end{center} Possible options are \begin{center} \begin{tabular}{|lp{3in}|} \hline \verb|-i<colour>|&Interior colour (default none).\\ \hline \verb|-c<colour>|&Path colour (default black).\\ \hline \verb|-t<length>|&Thickness (half width) (default thin).\\ \hline \verb|-r|&Round corners (default mitres).\\ \hline \end{tabular} \end{center} \subsubsection{Example} \begin{verbatim} set x 1 set y 1 set x1 2 set y1 2 w_draw mydiagram path ($x,$y)<($x,$y1)($x,$y1)>($x1,$y1). -cblue -t.1i w_draw mydiagram path ($x,$y)-($x1,$y)-($x1,$y1)-($x,$y1). -ired -cnone \end{verbatim} This draws a red square with no boundary and a thick blue line. \subsection{Sprite objects} \begin{center} \begin{tabular}{|l|} \hline \verb|<sprite object> = sprite <name> <point> [<point>]|\\ \hline \end{tabular} \end{center} \verb|name| is a name of a sprite in the user sprite area, its bottom left corner is placed at the first point. If the second point is provided it is the top right corner, otherwise the sprite is scaled to its natural mode independent size. At present sprites of 16 colours or less need to be provided with a palette, or they will appear in a peculiar set of colours. \subsection{Group objects} \begin{center} \begin{tabular}{|l|} \hline \verb|<group object> = group {<objects>}|\\ \hline \end{tabular} \end{center} \subsubsection{Example} \begin{verbatim} w_draw mydiagram group { text (1,2) "Some text"}\ { path (2,2)-(2,4)-(3,3).}\ { sprite mysprite (3,5)}\ { group {text (1,6) "Inner group"}\ {sprite othersprite (2,6) (3,7)}\ } \end{verbatim} \section{Commands} \begin{center} \begin{tabular}{|l|} \hline \verb|w_draw <identifier> create {options}|\\ \hline \verb|w_draw <identifier> save <filename>|\\ \hline \verb|w_draw <identifier> open|\\ \hline \verb|w_draw <identifier> [above <number>] <object>|\\ \hline \verb|w_draw <identifier> delete <number>|\\ \hline \verb|w_info diagrams|\\ \hline \end{tabular} \end{center} The \verb|create| command creates an empty draw diagram with the given identifier. Possible options are \begin{center} \begin{tabular}{|lp{3in}|} \hline \verb|-title <string>|&Sets the title for any windows on the diagram.\\ \hline \verb|-close <script>|&Runs the script when the user attempts to close the last window on the diagram. \%w is set to the window name. The script can return:- \begin{tabular}{|c|c|c|} \hline 0&close&Close window and diagram.\\ 1&show&Close neither.\\ 2&hide&Close window only.\\ \hline \end{tabular} If no \verb"-close" option is given the window and document are both closed.\\ \hline \verb|-click <script>|&Runs the script when the user clicks on the diagram. \%b is set to the button type. \%x and \%y are set to the position of the click in user coordinates. (Origin at bottom left)\\ \hline \verb|-page <pagesize>|&Sets the diagram size. This can be either \verb"A<number>[p|l]" or \verb|<length>x<length>|, p and l denote portrait (default) or landscape. Without this option the diagram defaults to A4p.\\ \hline \verb| -bg <colour>|&Sets the background colour.\\ \hline \verb|-xscale <length>|&Determine the scale used for describing\\ \verb|-yscale <length>|&objects, and for returning mouse clicks. Defaults 1i. \\ \hline \verb|-menu <menudescription>|&The menu is opened from any of the documents windows.\\ \hline \end{tabular} \end{center} The \verb|save| command saves the diagram as a draw file to the given filename. The \verb|open| command opens a new window on the diagram. The \verb|<object>| and \verb|above| commands add a new object to the diagram. They return an object identification number. The \verb|above| command places the object above the numbered object in the diagram. If the numbered object is not found (use -1 to force this) the object is placed at the front. If above is not used the object is placed at the back. The delete command deletes the numbered object. The \verb|w_info diagrams| command returns a list of all diagram identifiers. \chapter{Communication} \section{Introduction} One of the intended uses of w is to write desktop front ends for other programs. For this reason it has several methods for communicating with other applications. The \verb|system| command supplied with Tcl cannot be used from within desktop applications. When w is initialised it is replaced with a new version that calls \verb|Wimp_StartTask|. This allows w programs to start up any command line or desktop application, and is used when the started program does not need to communicate with w. The \verb|w_task| command implements the taskwindow protocol. The w program can start a command line task and pass data to and from the task. The \verb|w_send| command is for communication between w applications. One application can send a script to be interpreted by another application and receive the result. This gives a flexible scheme for communication between w applications, and is particularly useful for debugging. \section{Commands} \begin{center} \begin{tabular}{|l|} \hline \verb|system <string>|\\ \hline \verb|w_send <wimptask> <script>|\\ \hline \verb|w_task <identifier> create {<options>}|\\ \hline \verb|w_task <identifier> send <string>|\\ \hline \verb|w_task <identifier> kill|\\ \hline \verb|w_task <identifier> suspend|\\ \hline \verb|w_task <identifier> resume|\\ \hline \verb|w_info tasks|\\ \hline \verb|w_info wimptasks|\\ \hline \end{tabular} \end{center} The \verb|system| command passes the string to the RiscOS command interpreter using \verb|Wimp_StartTask|. This can be used to run command line or desktop applications. The \verb|w_send| command sends the script to a wimp task. The task is identified by its name in the taskmanager window. If the task is running w it will interpret the script and return the result as the result of \verb|wimp_task|. If an error occurs in sending the script (the taskname cannot be found or the task fails to respond) \verb|w_send| returns a standard Tcl error code of 1. If an error occurs in the remote script \verb|w_send| returns an error with the non--standard code of 5. If the script executes and returns its value succesfully \verb|w_send| returns the result with the result code of the remote script. \subsubsection{Example} \begin{verbatim} if {[catch {w_send wtest {info globals}} wvars]}\ { w_error "Send to wtest failed" return } \end{verbatim} This sends the command ``info globals'' to a wimp task called ``wtest''. This should return a list of its global variabls, which is placed in variable wvars. Notice the send command is enclosed in a catch. This should probably be the norm. The \verb|w_info wimptasks| command returns a list of all taskwindow task names. The \verb|w_task create| command starts up a taskwindow task with the given identifier. It can be followed by the following options \begin{center} \begin{tabular}{|lp{3in}|} \hline \verb|-receive <script>|&Runs the script when the task sends data sets \%o to the received data and \%n to the task identifier. Note the data may be broken into chunks that are not at line boundaries.\\ \hline \verb|-quit <script>|&Runs the script when the task closes down, sets \%n to the task identifier.\\ \hline \verb|-command <string>|&Passes the string to the RiscOS command line interpreter in the taskwindow. The string is truncated to 140 characters.\\ \hline \verb|-slot <number>|&Sets the task's initial wimpslot in kilobytes. Defaults to 128K.\\ \hline \end{tabular} \end{center} The \verb|w_task send| command sends a string to the taskwindow task. The \verb|kill|, \verb|suspend| and \verb|resume| commands kill, suspend and unsuspend the task. Killing the task will cause any \verb|-close| script to be interpreted. The \verb|w_info tasks| command returns a list of all task identifiers. \chapter{Null events} \section{Introduction} Most w scripts are interpreted in response to a user action, such as a mouse click or icon drag. The \verb|w_null| command allows scripts to be interpreted when nothing is happening, usually after a delay. \section{Commands} \begin{center} \begin{tabular}{|l|} \hline \verb|w_null <identifier> [<script>] [<delay>]|\\ \hline \verb"<delay>=<number>c|s|m|h|d"\\ \hline \end{tabular} \end{center} The \verb|w_null| command with a script argument installs the script on a null event handler. Any previous script with the same identifier is removed. The script will be called after the delay when the wimp is next not busy. The delay is a number followed by one of \begin{center} \begin{tabular}{|cl|} \hline \verb|<letter>|&Unit\\ \hline c ¢iseconds\\ s &seconds\\ m &minutes\\ h &hours\\ d &days\\ \hline \end{tabular} \end{center} If the script returns a delay it is reinstalled to be called again after the new delay, otherwise it is removed from the list. If \verb|w_null| is called without a script it just removes any script with the given identifier from the list. \subsubsection{Example} \begin{verbatim} w_init Clock w_box display create Clock { watch time tvar} w_box display open w_null update {set tvar [date];return 10s} 0s \end{verbatim} This is a complete desktop clock program! The \verb|w_null| command creates a null event handler called ``update''. This sets variable tvar to a string representing the current time and date. This is called at the first opportunity as its delay is \verb|0s|. It returns \verb|10s| so it is recalled every ten seconds or so. As \verb|tvar| is a watch variable in the dialog box the box is updated when the variable is written to. \chapter{RiscOS Tcl commands} \begin{center} \begin{tabular}{|lp{3in}|} \hline \verb|close <fileId>|&Close a file.\\ \hline \verb|date <format>|&Return time or date information. \verb|format| uses the same \%-substitutions as \verb|Sys$DateFormat|. It defaults to \verb"%24:%mi:%se %dy-%m3-%ce%yr" \\ \hline \verb|eof <fileId>|&Returns 1 for end of file 0 otherwise\\ \hline \verb|exit [<number>]|&Exits with the give return code (Default 0)\\ \hline \verb|flush <fileId>|&Flush buffered output to file.\\ \hline \verb|getenv <name>|&Returns the value of the named system variable or an empty string if it does not exist. \\ \hline \verb|gets <fileId>|&Returns a line from a file, discards any terminating newline\\ \hline \verb|gets <fileId> <variable>|&Reads a line from a file into the variable, discards any terminating newline. Returns the length of the string read, or -1 if no characters or newline are read.\\ \hline \verb|glob <filename> [<filetype>]|&Returns a list of files matching the filename. The filename can have wildcards \verb|*| or \verb|#| in the leaf name only. If a filetype is supplied only objects matching this type are returned. \\ \hline \verb|open <filename> [<access>]|&Opens a file and returns a fileId. \\ \hline \verb|puts [-nonewline] [<fileId>] <string>|&Writes string to a file (default stdout). Appends a newline unless \verb|-nonewline| is present. \\ \hline \verb|source <filename>|&Evaluate a file as a Tcl script.\\ \hline \verb|system <string>|&Call or chain another program.\\ \hline \end{tabular} \end{center} \begin{center} \begin{tabular}{|lp{3in}|} \hline \verb|file size <filename>|&Returns the file size in bytes. Gives an error if the file does not exist.\\ \hline \verb|file type <filename>|&Returns the file type as a decimal integer.\\ \hline \verb|file exists <filename>|&Returns 1 if the file exists, 0 otherwise.\\ \hline \verb|file access <filename>|&Returns access details as a string containing some of the characters from ``rwxlRWXL'' in that order. Lower case letters are for user access.\\ \hline \verb|file full <filename>|&Returns the canonicalized version of the file name. \\ \hline \end{tabular} \end{center} \section{Built in variables} \begin{center} \begin{tabular}{|lp{3in}|} \hline \verb|clock|&Returns the time in centiseconds since the program was started. \\ \hline \verb|rand|&Returns a random integer in the range 0 to 2147483647\\ \hline \verb|riscos_version|&Returns the version of the RiscOS extensions to Tcl as a decimal.\\ \hline \end{tabular} \end{center} \chapter{Tcl commands} Variable handling \begin{center} \begin{tabular}{|l|} \hline \verb|set <variable> [<string>]|\\ \hline \verb|global {<variable>}|\\ \hline \verb|incr <name> [<integer>]|\\ \hline \verb|trace variable <variable> [r][w][u] <command>|\\ \hline \verb|trace vdelete <variable> [r][w][u] <command>|\\ \hline \verb|trace vinfo <variable>|\\ \hline \verb|unset {<variable>}|\\ \hline \verb|uplevel [<level>] {<arg>}|\\ \hline \verb|upvar [<level>] {<variable> <variable>}|\\ \hline \end{tabular} \end{center} \begin{center} \begin{tabular}{|l|} \hline \verb|array anymore <name> <search>|\\ \hline \verb|array donesearch <name> <search>|\\ \hline \verb|array exists <name>|\\ \hline \verb|array names <name> [<pattern>]|\\ \hline \verb|array nextelement <name> <search>|\\ \hline \verb|array set <name> <list>|\\ \hline \verb|array size <name>|\\ \hline \verb|array startsearch <name>|\\ \hline \end{tabular} \end{center} Control flow commands \begin{center} \begin{tabular}{|l|} \hline \verb|break|\\ \hline \verb|case <string> [in] {<list> <body>}|\\ \hline \verb|case <string> [in] '{'{<list> <body>}'}'|\\ \hline \verb|continue|\\ \hline \verb|for <command> <expr> <command> <command>|\\ \hline \verb|foreach <variable> <list> <body>|\\ \hline \verb|if <expr> [then] <body> {elsif <expr> <body>} [else] [<body>]|\\ \hline \verb|return [-code <code>] [-errorinfo <string>] [-errorcode <code>] <string>|\\ \hline \verb|switch [<options>] <string> {<pattern> <body>}|\\ \hline \verb|switch [<options>] <string> '{'{<pattern> <body>}'}'|\\ \hline \verb|while <expr> <body>|\\ \hline \verb|proc <name> <args> <body>|\\ \hline \verb|catch <script> [<variable>]|\\ \hline \verb|error <message> [<info>] [<code>]|\\ \hline \end{tabular} \end{center} String handling \begin{center} \begin{tabular}{|l|} \hline \verb|regexp {<switches>} <expr> <string> <subspec> {<variable>}|\\ \hline \verb|regsub {<switches>} <expr> <string> <subspec> <variable>|\\ \hline \verb|split <string> [<string>]|\\ \hline \verb|scan <string> <format> {<variable>}|\\ \hline \verb|format <string> {<arg>}|\\ \hline \end{tabular} \end{center} \begin{center} \begin{tabular}{|l|} \hline \verb|string compare <string> <string>|\\ \hline \verb|string first <string> <string>|\\ \hline \verb|string index <string> <integer>|\\ \hline \verb|string last <string> <string>|\\ \hline \verb|string length <string>|\\ \hline \verb|string match <pattern> <string>|\\ \hline \verb|string range <string> <integer> <integer>|\\ \hline \verb|string tolower <string>|\\ \hline \verb|string toupper <string>|\\ \hline \verb|string trim <string> [<string>]|\\ \hline \verb|string trimleft <string> [<string>]|\\ \hline \verb|string trimright <string> [<string>]|\\ \hline \verb|string wordend <string> <integer>|\\ \hline \verb|string wordstart <string> <integer>|\\ \hline \end{tabular} \end{center} List commands \begin{center} \begin{tabular}{|l|} \hline \verb|append <variable> {<value>}|\\ \hline \verb|concat {<arg>}|\\ \hline \verb|join <list> [<string>]|\\ \hline \verb|lappend <variable> {<value>}|\\ \hline \verb|lindex <list> <index>|\\ \hline \verb|linsert <list> <index> {<element>}|\\ \hline \verb|list {<arg>}|\\ \hline \verb|lrange <list> <first> <last>|\\ \hline \verb|llength <list>|\\ \hline \verb|lreplace <list> <first> <last> {<element>}|\\ \hline \verb|lsearch [<mode>] <list> <pattern>|\\ \hline \verb|lsort {<switch>} <list>|\\ \hline \end{tabular} \end{center} Miscellaneous commands \begin{center} \begin{tabular}{|l|} \hline \verb|eval {<arg>}|\\ \hline \verb|exec {<switch>} {<arg>}|\\ \hline \verb|expr {<arg>}|\\ \hline \verb|rename <oldname> <newname>|\\ \hline \verb|subst [-nobackslashes] [-nocommands] [-novariables] <string>|\\ \hline \end{tabular} \end{center} \begin{center} \begin{tabular}{|l|} \hline \verb|info args <procname>|\\ \hline \verb|info body <procname>|\\ \hline \verb|info cmdcount|\\ \hline \verb|info commands [<pattern>]|\\ \hline \verb|info complete <command>|\\ \hline \verb|info default <procname> <arg> <varname>|\\ \hline \verb|info exists <varname>|\\ \hline \verb|info globals <pattern>|\\ \hline \verb|info level [<number>]|\\ \hline \verb|info library|\\ \hline \verb|info locals [<pattern>]|\\ \hline \verb|info patchlevel|\\ \hline \verb|info procs [<pattern>]|\\ \hline \verb|info script|\\ \hline \verb|info tclversion|\\ \hline \verb|info vars [<pattern>]|\\ \hline \end{tabular} \end{center} \end{document} 
