The Datafile PD-CD 4

home *** CD-ROM | disk | FTP | other *** search

/ The Datafile PD-CD 4 / DATAFILE_PDCD4.iso / languages / tcl / !Tcl / doc / W_Intro < prev next >

Wrap

Text File | 1996-01-28 | 23.4 KB | 548 lines

-- w -- wimp extensions for Tcl The w extensions provide 7 commands w_init .. initialize w_bar .. setup iconbar icon w_error .. show wimp error box w_box .. dialog box commands w_task .. taskwindow commands w_draw .. draw graphics window commands w_text .. scrolling text window commands They use three global variables w_where and w_debug and w_file. The w_init command must be called before any other w_ commands are called. It can only be called once. INTRODUCTION The w commands operate by installing a selection of scripts that are called when various wimp events such as mouse clicks occur. 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 detailed below. Using other letters can have unpredictable results. example w_init myprog w_bar -click {clickproc %b} proc clickproc {button} { if {$button=="sS"} exit} The w_init command starts up the wimp. The application will have taskname "myprog" in the task display list. w_bar puts an wimp sprite called !myprog on the iconbar. If it is clicked on the script {clickproc %b} is %-substituted and then run. %b gives a string of the form [a|s][S][C]. a for the alter button and s for select. S if the shift key is held down and C for the control key. So if you click select on the icon with only the shift key held down the script clickproc sS is interpreted and the program exits. If an uncaught error occurs while interpreting these scripts, or while interpreting the source file after w_init has been called two things happen 1) The global variable w_where is set to a string indicating which script the error occured in. e.g. "iconbar click" for the script in the example above. 2) The contents of global variable w_debug are interpreted. w_init sets w_debug to "if {![w_error \"Error in $w_where :- $errorInfo\" -ok -cancel]} exit" 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. NOTE: If an error occurs before a call to w_bar and you continue you will not have an iconbar icon and must quit from the task display. The file !Tcl.library.debug contains a slightly more sophisticated debugging system. To use it put the line source {<tcl$Dir>.library.debug} in your code AFTER the call to w_init. OBJECT IDENTIFIERS The procedures w_draw w_text w_task and w_box all take a <name> parameter. 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 names. example w_text output create w_text output print "Hello World" w_text output open This creates a scrolling text document called "output", puts some text in it and then opens a window on it. TAGS Some of the functions below return results from menu or dialog box actions in variables. If the same menu or dialog box description is used more than once it is necessary to separate the results. This is done by passing a tag to the construction. This causes the variable used to be <name>(<tag>) instead of just <name>. Items in menus opened from windows can be tagged with the name of the window, iconbar menu items can be tagged "bar". Transient dialog boxes can be tagged with the tag of their menu, persistent ones can be passed a tag when they are opened. example w_box filebox create "File Name" { vlist {write Filename fname } {default Set {list 1}} } w_box filebox open The create command creates a dialog box template called filebox, with a writable icon labelled "Filename" and and a default action item labelled "Set". The second command opens a copy of "filebox" as a persistent dialog box. Clicking on "Set" copies the contents of the writeable icon into the global variable "fname". If instead we open the box using w_box filebox open box1 clicking on set copies the icon contents into fname(box1). "box1" is called the tag. 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 -tag ... tag the menu item by the window name or "bar" -click <script> ... run script if this item is selected -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. -grey <variable> ... uses <variable> to decide whether the item is greyed out. 1=>grey 0=> don't grey. -sub <menudescription> ... creates a submenu -dbox <name> ... opens a transient dbox -sub and -dbox cannot be used together. -click and -tick cannot be used together. -tag must preceed -tick -grey or -dbox options The percent substitution %w is set to the window name (or "bar") when the click script or scripts associated with a transient dbox are interpreted. example w_bar -menu { MyProg { Info -dbox progInfo} { Submenu -sub { MyProg {I1 -tick ticked} {I2 -click {check %w}} } } { Quit -click exit} } This command puts an icon on the iconbar with a menu. The first item leads to a transient dialog box called progInfo The second leads to a submenu. The third causes the program to quit. The second item on the submenu runs the script "check bar". LENGTHS <length> = <number>?[i|m|c|p|d]? Lengths in w commands are given by a (possibly decimal) 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 i inches m millimeters c centimeters p points d draw units example w_text mywind create -width 6.5i Creates a text window 6.5 inches wide. COLOURS <colour> = <number>:<number>:<number> or <name> Colours in w commands are given by 3 numbers in the range 0-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 in the global array colours(<name>) to get a number sequence of the above form. The name "none" gives a transparent 'colour' for draw path objects. example set colours(red) 255:0:0 w_text mytext create -fg red -bg 200:200:255 gives a text window with red text on a pale blue background. FONTS <font> = f<name>?@<length>? or F<fontname>?@<length>? The second form takes a pathname in a font directory. The first looks up <name> in the global array fonts(<name>) to obtain a fontname. The array "fonts" is usually set up with standard names of font types, allowing users to specify their preferences. 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) example set fonts(n) Trinity.Medium set fonts(i) Trinity.Italic set fonts(b) Trinity.Bold w_text mytext options -pon w_text mytext write "This is |fi|italic, |fn| this is |fb|bold" w_text mytext print w_text mytext write "This is |FTrinity.Bold@40p|Big and Bold" The fourth line turns || processing on. The fifth writes "italic," in italic and "bold" in bold. The last writes "Big and Bold" in 40 point bold. Note that w_text documents use a constant line spacing. If you use large fonts for titles etc. you may need to add blank lines to avoid overlaps as in the penultimate line. TEXT FEATURES When the w_text commands add text to a document the following substitutions can be optionally made. |<font>| ... change font |<colour>| ... change colour || ... display a | DRAW OBJECTS There are four types of objects displayed in draw diagrams text objects, path objects,sprites and group objects. <textobject> = text <point> <string> <options> A point has the format (<number>,<number>) the numbers are diagram coordinates. Possible options are -<font> ... The font -c<colour> ... Text colour -b<colour> ... Background colour hint -o<origin> ... Determines which point in the text is placed at the given point. <origin> = ?[l|c|r]??[t|m|b]? x-position :- l=>left c=>center r=>right nothing=> text base left y-position :- t=>top m=>middle b=>bottom nothing=> text baseline <path object> = path <path sequence> <options> A path sequence is a string of the form <point><gap><point> .... <gap><point>?.? A terminating full stop indicates that the path is closed. Gaps can be nothing ... move between points - ... join points with line '<'<point><point>'>' ... Bezier curve with the given control points Possible options are -i<colour> ... interior colour (default none) -c<colour> ... path colour (default black) -t<length> ... thickness (half width) (default thin) -r ... round corners (default mitres) <sprite object> = sprite <name> <point> ?<point? name is a name of a sprite in the user sprite area the 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. <group object> = group <list of objects> examples w_draw mydiagram text (1,2) "Hello World" -ocm -cred w_draw mydiagram path (1,2)-(3,2)-(3,4)-(1,4). -iblue -cnone w_draw mydiagram sprite mysprite (1,1) (2,2) w_draw mydiagram group\ { text (5,5) "Hello again"} { path (4,5)<(4,6)(6,6)>(6,5) -t.05i } The first command puts red text centered at (1,2) The second draws a blue square with no boundary. The third plots mysprite scaled to a 1 unit square. The last put some text above a curve in a group object. DIALOG BOX COMPONENTS action <name> [<script>] ... action icon default <name> [<script>] ... default action icon If the icon is selected and there is no script the box is just closed. If there is a script first all the dialog box variables are set, then the script is interpreted. If the script returns "0" the box is closed. info <name> <text> ... static text display display <name> <variable> ?<width>? ... display of variable value <width> in characters default=20 option <name> <variable> ... option icon radio <name> <variable> ... radio button The contents of these icons are read from the variables when the box is opened, they are copied back when the variables are set. Option icon variables contain 0=>deselected 1=>selected. Radio icons are in the same group if they have the same variable. The variable is set to <name> for the selected button. write <name> <variable> ?<width>? ?<length>? ... writeable icon The contents of <variable> are placed in the icon when it is opened and copied back when variables are set. Width gives the number of characters displayed and length the size of the buffer. Defaults: width=20 length=256. save <hexfiletype> <variable> <script> ... save icon and filename icon This gives an icon corresponding to the filetype that can be 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 <script> is interpreted with global variable w_file set to the full filename required. Variables are set before the script is interpreted. The script should save to the required filename. It should return 0,1,2 or 3. 2 or 3 indicate failure to save correctly. 0 or 2 indicate that the dialog box should be closed. sprite <spritename> ... display a sprite The sprite is looked for first in the user sprite area and then in the wimp sprite area. box <name> <component> ... box round component hlist <list of components> ... horizontal list vlist <list of component> ... vertical list COMMANDS w_init <progname> ?<spritefile>? ... initialise the wimp system, register the program as a wimp task called <progname> progname is truncated to 8 characters. It is used to generate icon names, default window names and task names. The other w_commands cannot be called before w_init. w_init can only be called once. if spritefile is provided it is loaded from <<progname>$dir>.<spritefile> into the user sprite area. w_bar ... ... w_bar puts an icon called !progname on the icon bar. This should be in the wimp sprite area. It should probably be called once only. It can be followed by some of the following pairs -menu <menudescription> ... provides an iconbar menu -click <script> ... interpret <script> on an iconbar click sets %b to a button description string -drag <script> ... interpret <script> after something is dragged to the iconbar. sets global variable w_file to the filename and %t to the filetype in decimal. w_error <text> ?-ok? ?-cancel? ... display <text> in a wimp error box. <text> is truncated to 251 characters. -ok gives an OK button -cancel gives a CANCEL button. (default OK only) returns OK=>1 CANCEL=>0. w_box <name> create <title> <component> ?-tag? ... creates a dialog box template called <name> with title <title> containing <component>. If the "-tag" option is given variable use will be tagged. w_box <name> open ?<tag>? ... opens a persistent dialog box using a template called <name> previously created using w_box <name> create ... If <tag> is given and the -tag option was given during creation variable use will be tagged. w_task <name> create ... ... Creates a taskwindow task called <name>. It can be followed by some of the following pairs -receive <script> ... Runs <script> when the task sends data sets %o to the received data. Note the data may be broken into chunks not at line boundaries. -quit <script> ... Runs <script> when the task closes down. -command <string> ... Passes <string> to the CLI in the taskwindow <string> is truncated to 140 characters. -slot <number> ... Sets the task's initial wimpslot to <number>K. Defaults to 128K w_task <name> send <string> ... Sends <string> to the task. Not including a newline. w_task <name> kill ... Kill the task (this will run any "-quit" script). w_task <name> suspend ... Suspend the task. w_task <name> resume ... Resume after suspension. w_text <name> create ... ... Creates a document window. It can be followed by some of the following pairs -title <string> ... Sets the title for any windows on the document. -close <script> ... Runs script when the user attempts to close the last window on the document. %w is set to the window name. The script can return:- 0 => Close window and document. 1 => Close neither. anything else => Close window but not document. If no "-close" option is given the window and document are both closed. -fg <colour> Sets the main text colour. Default black. -bg <colour> Sets the background colour. Default white. -menu <menudescription> The menu is opened from any of the document's windows. -width <length> Sets the window width.(Default 800 os units) -size <length> ... Sets the main font size (Default 20p) -height <length> ... Sets the separation between lines. ( Default depends on main font size.) w_text <name> options ... Sets some text options. It can be followed by some of the following pairs -l<length> ... left margin (from left of window) -i<length> ... paragraph indent (write only) (from left of window) -r<length> ... right margin (from right of window) -j[on|of] ... justify (write only) -p[on|off] ... process -L ... set left (print only) -C ... center (print only) -R ... set right (print only) The options apply to any "write" or "print" commands after the option command defaults are -l0 -i0 -r0 -joff -poff -L w_text <name> print ... ... The following arguments are joined with space separators. If the "process" option is on they are scanned for || sequences. The result is printed in a single line. The most recently opened window (if any) is scrolled to show the text. w_text <name> write ... ... The following arguments are joined with space separators. If the "process" option is on they are scanned for || sequences. The result is split into lines and displayed as a paragraph. The first line is indented by the paragraph indent. If the "justify" option is on all but the last line will be justified to both margins. The most recently opened window (if any) is scrolled to show the text. w_text <name> open ... Open a window on the document. w_draw <name> create ... Creates a draw diagram. It can be followed by some of the following pairs -title <string> ... Sets the title for any windows on the diagram. -close <script> ... Runs <script> when the user attempts to close the last window on the diagram. %w is set to the window name. The script can return:- 0 => Close window and diagram. 1 => Close neither. anything else => Close window but not diagram. If no "-close" option is given the window and diagram are both closed. -click <script> ... Runs <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 diagram coordinates. (Origin at bottom left) -page <pagesize>...Sets the diagram size. This can be either A<number>?[p|l]? or <length>x<length> p and l denote portrait (default) or landscape. Without a -page option defaults to A4p. -bg <colour> ...Sets the background colour. -xscale <length> ..\ Determines the scale used for describing -yscale <length> ../ objects, and for returning mouse clicks. Defaults 1i. -menu <menudescription> The menu is opened from any of the documents windows. w_draw <name> open ... Open a window on the document. w_draw <name> save <filename> ... Save the diagram as a draw file w_draw <name> ?above <number>? <object> ... Adds an object to the diagram. Returns a number to identify the object within the diagram. If no "above" option is given the object is at the back of the diagram, otherwise it is in front of the <number> given. If <number> is not found (e.g. <number>=-1) it is placed at the front. w_draw <name> delete <number> ...Removes the numbered object from the diagram.