@database "MUInt.guide" @date 6-25-95 @NODE main @TITLE "Table of Contents" @{b} ------------ MUInt_dev_v1 -------------@{fg highlight}@{ub} MUInt version 7.7 - Links AmigaDOS to MUI@{fg fill} >>> FreeWare - Freely Distributable <<<@{fg highlight} >>> Developer's package <<< 25 June 1995 @{fg text} @{" Introduction " link over} An overview @{" Requirements " link requ} Necessary hardware and software @{" Quick Look " link look} Quick runthrough of the concept @{" Defining GUIs " link MUIN} Keywords and their usage @{" Example Programs " link exam} Learn by seeing real scripts @{" DOS Extensions " link exts} Some extensions written for MUInt @{" Style Guide " link conv} Naming conventions @{" Troubleshooting " link trou} What to do when it doesn't work @{" History " link hist} @{" Distribution " link dist} Legal stuff @{" License " link lice} More legal stuff @{" Credits " link cred} Who did all this work? @{" The Authors " link both} @{fg highlight} MUInt is ©1994, 1995 by BOTH Software @endnode @rem ================================================================== @rem INSTRUCTIONS SECTION @rem ================================================================== @node hist Pre-release: 01-02-95 First release. MUInt Version 6.0 01-03-95 Fixed bug in installer script 01-04-95 Added new IconX 01-06-95 Added Quick Installer script 01-09-95 Released version 6.1 of MUInt. Adds ENV:LV Released Version 2.4 of rtRequesters. 01-12-95 Released version 6.3. Fixed a bug in MUInt. Now allows a $string to be a source for LV. ENV:LV now generated if no selection is made. Released Version 2.4 of Advice. 01-18-95 Released version 2.5 of rtFontRequest. Now functional. 01-27-95 Released version 7.4 of MUInt. Added STRING and CYCLE. Repaired some Enforcer hits. 02-03-95 Repackaged all the files for distribution into this format: MUInt_dev_v.9 MUInt_user_v.9 MUInt_prgs_1-5 02-04-95 Released MUInt version 7.6 Public Release 06-23-95 Added NAME keyword and modified QUIT Version bumped to 7.7 Rewrote docs for first public release Repackaged MUInt_prgs into 4 files @endnode @node icon @{fg highlight} ICONX @{fg text} IconX will pop up it's annoying little window whenever a script tries to call an executable. You can get around this by adding RUN >NIL: before the call to an executable. Or, you can try the QUIET keyword. To resolve this, a new version (38.9) of IconX is included here. It will open a smaller window, in the upper left corner of the screen. The window title says MUInt. This window should pop up in a place somewhere other than on top of your GUI :-) The new IconX is located in the /C directory. We suggest you rename your old version before copying the new one to your own C: directory. If you get confused, the smaller window will report version 38.9. @endnode @node over @TITLE "An overview of the concept" In the past, every MUI GUI you saw or used was controlled by a C (or E) program. Anyone who wanted to write a program and use MUI to display the interface had to do the job with C. This limited the use of MUI to those advanced programmers who took the time to master both the C programming language and MUI. @{b} * MUInt removes that limit * MUI GUIs can now be generated and controlled by AmigaDOS. @{ub} DOS? The same old useless DOS we've all come to know and hate? Almost. To make MUInt useful we have added many extensions to DOS. These programs give DOS the ability to do some useful work without resorting to any of the more powerful UNIX/DOS shells available. MUInt is a C program - an executable. It accepts a Definition file that you write as a DOS script. The Definition file describes the look of the interface that MUInt puts on the screen. It also controls what happens when the user clicks on buttons. No knowledge of MUI is necessary to use MUInt. We feel that MUInt can be quickly mastered by a person who has a bit of experience with writing DOS scripts. MUInt was developed to allow non-C programmers to put up a MUI interface to control C programs written by others. This allows you to control a "CLI-ONLY" program with an interface. Of course, MUInt can control a series of DOS scripts that have nothing to do with C programs. You will find several examples of these three cases in the MUInt_prg archives. MUInt guis can be generated and used interactively with other languages. COMAL, ACE, AmigaBasic, Pascal, and others can call up a MUInt gui without the aid of a DOS Script. @endnode @NODE requ @title "System Requirements for MUInt" * MagicUserInterface (MUI) * muimaster.lib version 8 or greater * You must have the ReqTools.library installed. ReqTools.library is not included here. * You REALLY SHOULD have DOSReqTools installed or the demos will not run. * WorkBench 2.04 or up is required. * MUInt cannot be made resident. @endnode @node look You WILL need to read the docs to write MUInt GUIs. OK, nobody reads docs. Here's what you need to get started, but remember what I said about reading the docs :-) Here are the MUI objects you can use in the GUI: # Available Type KEYWORD(s) ENV:Variablename ----------------------------------------------------------------- 1 Listview LV=LISTVIEW LV @{"DEMO" system "execute guide/LV.def"} 3 PopASLs LEFT LEFT @{"DEMO" system "execute guide/LCR.def"} CENTER CENTERPATH RIGHT RIGHTNAME 1 Text window BODY @{"DEMO" system "execute guide/BODY.def"} Any number* Cycle Gadgets CYCLE CYCLE @{"DEMO" system "execute guide/CYCLE.def"} Any number* Radios RADIO RADIO @{"DEMO" system "execute guide/RADIO.def"} Any number* Checkboxes CHECKBOX CHECKBOX @{"DEMO" system "execute guide/CHECKBOX.def"} Any number String Windows STRING STRINGX @{"DEMO" system "execute guide/STRING.def"} NUMSTRING NUMSTRINGX NEWLINE Any number Buttons BUTTONS 1 Window Title TITLE * There @{u}ARE@{uu} limits. See WIDTH. @{fg highlight} MUInt file structure at a glance. @{fg text} MUInt, the executable, is called from within the DOS script called a DEFINITION FILE. The script writes as many as five files to RAM: that completely define how the GUI will look. After these files are written to RAM:, the script calls MUInt with one parameter. That parameter is the COMMAND LINE FILENAME. The COMMAND LINE FILE will be in RAM:. It tells MUInt where it can find the files that define the BUTTONs, RADIOs, STRINGs, and CHECKBOXes. MUInt then reads these files and generates a GUI according to the information contained in them. The DEFINITION FILE always has a ".def" suffix. This is the file you Execute. The COMMAND LINE FILE always has a ".cl" suffix. Here is a graphical representation of the relationship of the DEFINITION FILE, MUInt, and RAM:. +------------------------+ +----------+ | DEFINITION FILE | | RAM: | +------------------------+ +----------+ + +--BUTTONs------>>+ + + Generate these +--RADIOs------->>+ + + files to RAM: +--CHECKBOXs---->>+ + + +--CYCLEs------->>+ + + +--STRINGs------>>+ + + +--COMMAND LINE->>+ + +------------------------+ + + + + + + + Call MUInt with + + + + this filename +<<-COMMAND LINE--+ + + + + + +------------------------+ + + + + + + + MUInt reads these +<<----BUTTONs----+ + + files to make the +<<----RADIOs-----+ + + GUI +<<----CHECKBOXs--+ + + +<<----CYCLEs-----+ + + +<<----STRINGs----+ + + + + + +------------------------+ +----------+ A definition script (.def) defines any of the objects required. Buttons, Radios, Checkboxes and Strings are defined, one to a line, and sent to separate files in ram: so MUInt can find them. Here's an example: @{fg fill} ECHO >ram:EXP.buttons " UNARC;execute A.unarcL.scp" ECHO >>ram:EXP.buttons " EDIT LV ;emacs []" ECHO >>ram:EXP.buttons " QUIT " ECHO >ram:EXP.checkbox "LIST;-l" ECHO >>ram:EXP.checkbox "TEST;-t" ECHO >ram:EXP.radio "SIZE;FULL;-f|HALF;-1/2|QUARTER;-1/4" ECHO >>ram:EXP.radio "OUTFILE;GIF;-gif|BMP;-bmp|TARGA;-tar" ECHO >ram:EXP.cycle "FileReader;More;more|Less;less" ECHO >>ram:EXP.string "STRING0;Name:;100,25;Colin Thompson" ECHO >>ram:EXP.string "NUMSTRING0;Age: ;2;2;19" @{fg text} MUInt learns where to find these files by reading another file you write. This is the Command Line file. Here's an example: @{fg fill} ECHO >ram:EXP.cl: "BEGIN" ECHO >>ram:EXP.cl: "TITLE *"ARCer by BOTH Software*"" ECHO >>ram:EXP.cl: "BODY A.arcbody.txt" ECHO >>ram:EXP.cl: "LEFT "SOURCE;$source" ECHO >>ram:EXP.cl: "RIGHT "DESTINATION;$destination" ECHO >>ram:EXP.cl: "LISTVIEW ram:A.LocalDir SORT MULTI" ECHO >>ram:EXP.cl: "BUTTONS ram:EXP.buttons" ECHO >>ram:EXP.cl: "CHECKBOX ram:EXP.checkbox" ECHO >>ram:EXP.cl: "RADIO ram:EXP.radio" ECHO >>ram:EXP.cl: "CYCLE ram:EXP.cycle" ECHO >>ram:EXP.cl: "STRING ram:EXP.string" ECHO >>ram:EXP.cl: "WIDTH 80" ECHO >>ram:EXP.cl: "NAME ARCer" ECHO >>ram:EXP.cl: "DEBUG" ECHO >>ram:EXP.cl: "END" @{fg text} This file tells MUInt what it needs to know, in detail, about putting up the GUI. This is a worst case example. Most .def files will be less complicated. Finally, you call MUInt like this: MUInt ram:EXP.cl @{fg highlight} Here is some information you need to understand: @{fg text} 1. When the user clicks a button, the action associated with that button is performed. This action can be any DOS command, like EXECUTE or RUN. 2. When a button is clicked, MUInt writes to ENV, the current value of each of the objects. External scripts get needed information by referencing these variables. This is the way MUInt passes values to scripts. 3. The GUI stays on the screen until the QUIT button is clicked. 4. The Listview sends it's selections to an external script via substitution brackets []. Multiselection is supported. 5. From the user's point of view, the GUI looks like any other MUI GUI being controlled by a C program. 6. Arexx is NOT supported in MUInt. This means the ListView cannot be refreshed on the fly. There are ways around this. 7. One MUInt can call another MUInt, ad nauseum. 8. Many DOS extension have been provided in MUInt and DOSReqTools. You can write some pretty powerful scripts with these tools. Like any craftsman, you are only as good as your tools. If you have a great idea and find DOS can't do what you want, ask us for help. Will can write DOS extensions quicky. (He does this for relaxation, while taking a break from COMAL). A Note to help you get started: When you first start out, I suggest you make modifications to existing scripts. See what happens. When you get comfortable with the concept, go crazy. Have fun! @endnode @NODE "conv" @title "The Muint Style Guide" @{fg highlight} The Muint Style Guide @{fg text} While developing this system, I found that directories soon filled up with scripts, executables, textfiles, and others files. I had trouble remembering which file did what. To resolve this messy little problem, I imposed some system's discipline on myself. I worked out an filename naming convention that made sense to me. The system is pretty simple. It goes like this. All Definition files have the suffix of .def, and the main name is that of the primary executable it uses. XtoILBM.def is an example. All other scripts in the directory have a prefix that lets the files be alphabetically presented. For example, Writer uses WRI as a prefix for it's scripts. It's helpful to make the prefix of the scripts and the Def file start with the same letter. Scripts should have the suffix @{b}.scp@{ub} Text files should have the suffix @{b}.txt@{ub} Definition files should have the duffix @{b}.def@{ub} Scripts that operate on one MUI object should reference that object in the filename. If the script only operates on the ListView then LV should be in the filename. Example: XconvLV.scp. This convention allows you to read the filename as a script, belonging to XtoILBM, that converts filenames fed to it from the ListView. Left (L), Right (R), Center (C), would be the other objects that should be specified. Since multiple copies of MUInt can be running at the same time, you need to give Button files unique names. I've found these conventions work well: @{fg highlight} BUTTON, RADIO, CYCLE, CHECKBOX, STRING and DEFINITION FILES @{fg text} Add a unique suffix or prefix the the filename. Examples: ram:X.buttons ram:X.radio ram:X.cycle ram:X.checkbox ram:X.string Command Line files should have the suffix of .cl. The main name should be the name of the Definition File. ram:X.cl As the last entry in the .def script, just before QUIT, you should DELETE all of the files written by the script. This keeps ram: clean. @{fg fill} DELETE X.#? QUIET @{fg highlight} DIRECTORY ORGANIZATION @{fg text} Executables needed for the program should be included in the directory. This keeps your package neat and clean, ready for distribution. Ideally, your program should be able to be run from within it's own directory. If this is not possible, write a document to explain to the user which external files (libs, viewers, etc.) are required. @{fg highlight} HELP FILES @{fg text} There are several ways to present Help text to the user. The BODY object was included in MUInt to allow Help text to be presented at all times. BODY is scrollable, the the size of the file may be unlimited. Buttons can call scripts that present specific Help text with: * rtEZrequest - Short messages * Advice - Longer text, but less than a screenfull * Textwin - Unlimited length textfiles * Any common filereader Many of the MUInt programs included in MUInt_prgs_x are written to provide an interface for an existing executable. When applicable, I have provided two buttons to help the user understand the operation of the program. One button, titled DOCS, will bring up the original document file provided with the executable. The other button, HELP, tells the user how to use the MUInt program. This convention works well. We suggest you use it in your own programs. @{" IconX " link icon} can be a problem. We have included a solution. @ENDNODE @NODE LICE @TITLE "Licensing Agreements" This application uses @{b}MUI - MagicUserInterface@{ub} (c) Copyright 1993/94 by Stefan Stuntz MUI is a system to generate and maintain graphical user interfaces. With the aid of a preferences program, the user of an application has the ability to customize the outfit according to his personal taste. MUI is distributed as shareware. To obtain a complete package containing lots of examples and more information about registration please look for a file called "muiXXusr.lha" (XX means the latest version number) on your local bulletin boards or on public domain disks. If you want to register directly, feel free to send DM 30.- or US$ 20.- to Stefan Stuntz Eduard-Spranger-Strae 7 80935 Mnchen GERMANY @ENDNODE @NODE CRED @TITLE "We couldn't have done it without YOU" @{fg highlight} Our thanks go to: @{fg text} @{b}Stefan Stuntz@{ub} for his MagicUserInterface. This is our first project that uses MUI. Yes, the learning curve was steep, but the efforts have been worth it. We are incorporating MUI into several of our current projects. We highly recommend you register your copy of MUI. Good work should be rewarded. Many talented people have participated in the project. Their observa- tions, comments, and suggestions have breathed life into MUInt. Here are the people who turned a gimmick into an innovative programmer's toolbox: Adam Atkinson Anthony Horan Bill Ross Christopher Naas Cliff Wakefield Dan Stephans II Denny Atkins Geoff Seeley Gary Duncan Geoff Seeley Gerald Keegan Jason Compton Leif Johnson Len Trigg Michael Shea Niksa Franceschi Oliver Seiler Peter Bagnato Radek Chyra Richard Tew Tako Schotanus Terence Nichols Terry Carter Trefor S Yannick Koehler @ENDNODE @NODE BOTH @TITLE "Those guys? Again?" If you find any bugs or have any comments, please contact the Authors. Email messages will be answered immediately. @{fg highlight} C & UNIX Code Program Design, GUIs, Docs@{fg text} -------------------------- -------------------------- Will Bow Colin Thompson 1531 Corinth Unit 1 9606 Carroll Cyn. Rd. H9 West Los Angeles, CA 90025 San Diego, CA 92126 (310) 478-4913 (619) 695-2181 InterNet:wbow@crl.com InterNet: colin@connectnet.com -------------------------------------------------------------------- BOTH's ftp site: @{b}ftp.connectnet.com/pub/users/comal@{ub} -------------------------------------------------------------------- BOTH's URL addr: @{b}ftp://ftp.connectnet.com/pub/users/comal/index.html@{ub} -------------------------------------------------------------------- @endnode @NODE DIST @TITLE "Distribution and Copyright Notice" MUInt is copyright 1994,1995 by BOTH Software. It is @{b}GIFTWARE@{ub}. That means if you like it and use it, you may send us a Gift. A birthday card or email would be nice. We would really like to hear about how you've used the programs. MUInt is free to use and copy as you see fit. The Authors retain all rights to the programs. The Authors are not responsible for any damage the programs may cause. If you distribute this archive, you MUST distribute the entire package. MUInt may be included in any archive collection. Tested on a 4000, 3000, 2000, 1000, 500, 600, and 1200. OS 2, 3, 3.1 @ENDNODE @NODE ab @TITLE "Action Buttons" An Action Button is any button defined in the BUTTONS file. These buttons cause a program, script file, or DOS command to be executed. When an action button is clicked, MUInt collects all of the values from the Radios, Checkboxs, and File Requesters. These values are written to their respective ENV files so the values are available to your script. @ENDNODE @rem ================================================================== @rem ARGUMENTS SECTION @rem ================================================================== @NODE TI @TITLE "TITLE/K" @{fg highlight} TITLE/K @{fg text} This information appears in the top bar of the window. It should describe the function of the program. TITLE is defined in the Definition file like this: @{fg fill} echo >ram:X.cl "TITLE *"This is the window's title*"" @{fg text} @{b}NOTE: All text following the filename must be enclosed in double quotes. Also, the text that defines the TITLE's text must also be enclosed in double quote marks. To accomplish this trick, DOS must be informed that there are quote marks INSIDE the quoted area. You tell DOS about this by preceeding the INSIDE quote marks with an asterick.@{ub} To help clarify this confusing DOS requirement, let's look at three examples that WON'T WORK: echo >ram:X.def "TITLE "This is the window's title"" echo >ram:X.def "TITLE This is the window's title" echo >ram:X.def TITLE This is the window's title This WILL work: echo >ram:X.def "TITLE DOSMAN" This example has no spaces in the title's name. @ENDNODE @NODE db @TITLE "Debugging aide" @{fg highlight} DEBUG @{fg text} Normally, the ENVariables generated by MUInt are automatically deleted when MUInt is QUIT. This keeps RAM:ENV clean. When you write scripts, sometimes you would like to examine these variables, to help you debug your scripts. Include the Keywork DEBUG in the Command Line file (.cl) to prevent the variables, like $LEFT, from being deleted. MUInt automatically deletes them on startup. This way, you can examine them in real time. When DEBUG is invoked, all actions taken by MUInt will be echoed to the shell or the IconX window. You will be shown which scripts are being executed, which variables are being written to ENV and any error messages generated by DOS or MUInt. Remember to remove the call to DEBUG before distributing your program. @ENDNODE @NODE na @TITLE "NAME/K" @{fg highlight} NAME/K @{fg text} Since MUInt brings up a real MUI gui, you may Iconify the gui by clicking the smaller gadget in the upper right hand corner. This places an icon on the WorkBench. The name of the icon will be MUInt. The NAME Keyword will give the Icon a new name. Simply pick a name for your program and include it after the NAME keyword in the Command Line File. Ex: "NAME AmiRate" If you have a registered copy of MUI, you will be able to customize the appearance of each MUI application. By using the NAME keyword, your gui will be remembered by MUI. You can then set up the gui to take on any appearance you desire. Without the NAME Keyword, all MUInt guis will be named MUInt. @ENDNODE @NODE BU @TITLE "BUTTONS" @{fg highlight} BUTTONTEXT=BUTTONS/M @{fg text} MUInt allows you to define buttons and their text. When a button is clicked, an action it preformed. The actions are predefined in the Definition file. The actions can be: RUN a program EXECUTE a script EXECUTE a DOS Command MUInt takes the selected action and presents it to DOS as though it was typed into the shell. The definition of each button is stored in a button file that MUInt looks to for it's button data. This button definition file is created in the main Definition File. Here is an example: @{fg fill} ECHO >ram:ARC.buttons " UNARC ;execute AunarcL.scp" ECHO >>ram:ARC.buttons " ARC ;execute AarcL.scp" ECHO >>ram:ARC.buttons " COMPRESS LV ;execute AcompressLV.scp []" ECHO >>ram:ARC.buttons " EDIT LV ;emacs []" ECHO >>ram:ARC.buttons " QUIT " @{fg text} The first line opens a new file in ram: called ARCbuttons. The text following the filename MUST be enclosed in double quotes. Each button definition occupies a single line. In the example above, @{fg fill} " UNARC ; @{fg text} defines the ButtonText for the Top, Leftmost button. The text definition starts with the quote mark and ends with the semicolon. Space characters are significant and are used to make the button as wide as you like. Also see @{"WIDTH" link wi}. The text following the semicolon, and ending with a quote mark, defines the action that will take place when the button is clicked. This action must be a valid DOS command. In this case @{fg fill} execute AunarcL.scp" @{fg text} will cause DOS to EXECUTE the file AunarcL.scp MUInt will remain on the screen while the file is being EXECUTEed. If the action was to RUN >NIL: , the program will RUN asynchronously with MUInt. You may work on both of them at the same time. If the action was to EXECUTE a script, control of MUInt will return when the script hits a QUIT statement. Let's look at the second and suceeding lines: @{fg fill} ECHO >>ram:ARCbuttons " ARC ;execute AarcL.scp" @{fg text} Notice there are TWO output redirection marks >>. This causes the line to be appended to the file. THE QUIT BUTTON The last button defined will cause MUInt to stop. This button is, by definition, called QUIT. It will always be the lower rightmost button. The last button can have any button text you like, but QUIT is very clear and people expect to see a QUIT or CANCEL button on any GUI. When you press the QUIT button, the MUInt gui cancels itself, and the screen clears. If you have any commands in the .def file following the call to MUInt, these will be performed, then the script ends. You may include a Command to execute before the GUI is closed down. This command will be useful if you are running a MUInt gui from a compiled program, where the program resides in memory. See the docs about running MUInt from COMAL or ACE. MULTIPLE BUTTON FILES BUTTONTEXT=BUTTONS/M The /M qualifier means you can define more than one button file inside the Command Line file. Multiple button files are not recommended, but it is available to you. Here's a sample Definition file that takes button definitions from more that one file: @{fg fill} ECHO >ram:ARCbuttons " UNARC ;execute AunarcL.scp" ECHO >>ram:ARCbuttons " ARC ;execute AarcL.scp" ECHO >ram:ARCedit " READ FILE LV ;AmigaGuide []" ECHO >>ram:ARCedit " QUIT " ECHO >ram:ARC.cl: "BEGIN" ECHO >>ram:ARC.cl: "LISTVIEW ram:LocalDir SORT" ECHO >>ram:ARC.cl: "BUTTONS ram:ARCbuttons" ECHO >>ram:ARC.cl: "BUTTONS ram:ARCedit" ECHO >>ram:ARC.cl: "END" @{fg text} MUInt handles Multiple files by appending the second file to the first one. Make sure that the QUIT button is the last button in the last BUTTON file. SUBSTITUTION When the user selects something from the LV, and clicks a button that operates on that data, the data is routed to an external script or executable through substitution brackets []. MUInt does create an ENVariable for the LV, but it doest not contain the data. Look at this example from the Button file above: @{fg fill} ECHO >>ram:ARCbuttons " COMPRESS LV ;execute AcompressLV.scp []" @{fg text} This button allows the user to select a file from the LV. The filename is sent to the script AcompressLV.scp with the [] brackets. The script must begin with the DOS commands: @{fg fill} .KEY INFILE .BRA { .KET } @{fg text} At this point your script can refer to the filename passed to it as {INFILE}. A POINT TO CONSIDER The Listview is the only object that supports MULTISELECTION. More that one data item may be selected and sent to a script. @{fg fill} .KEY INFILE @{fg text} The /M qualifier allows multiple data items to be accepted. Use this when you invoke CONCAT, but not when you use MULTI. Also see: @{"MULTISELECT" link lv} @{"CONCAT" link lv} @{"LISTVIEW" link lv} For more detailed information on how to load the LV, see@{"ListView" link lv} @ENDNODE @NODE BY @TITLE "BODY/M" @{fg highlight} BODY/M @{fg text} By including the Keyword BODY, MUInt opens a text gadget in the window and loads it with text. The text can be of any length. It can come from a file or from "text" following the Keyword BODY. The BODY window appears below the File requesters and above the ListView. A scrolling gadget is provided. @ENDNODE @NODE fr @TITLE "The LEFT, CENTER, and RIGHT File Requesters" @{fg highlight} LEFT RIGHT CENTER @{fg text} Up to three PopASL file requesters may be defined. They appear at the top of the MUI window. You may add a TITLE for each of the requesters. The TITLE appears above the requester. You may preload each file requester with a directory or file. If you don't preload the requester, it will show The root directories of all of the devices on your system. @{fg highlight} SYNTAX FOR THE COMMAND LINE FILE @{fg FILL} "LEFT ;<path:file>" @{fg text} If TITLE has spaces, you must resort to a DOS trick to force double quotes around it liKE this: @{fg fill} "LEFT *"<TITLE WITH SPACES>*";<path:file>" @{fg text} TITLE and PATH must be separated by a semicolon. @{fg highlight} ENVariables CENTER, CENTERPATH, CENTERNAME @{fg text} When an action button is pressed, MUInt writes three ENVariables for each of the (defined) requesters. You may retrieve and use these variables from your script. The variables reflect the file/directory selected at the time an action button was pressed. As an example, let's assume that the LEFT requester shows Work:Graphics/Pix/DAX.GIF. Here is what the ENVariables would hold: ENV:LEFT = Work:Graphics/Pix/DAX.GIF ENV:LEFTPATH = Work:Graphics/Pix/ ENV:LEFTNAME = DAX.GIF As you can see, this division of the full path into three variables makes your work a lot easier. Simply refer to them as $LEFT, $LEFTPATH, or $LEFTNAME. CENTER and RIGHT work the same way. You can mix and match paths and filenames by using the DOS extension AddPart, which tacks on a filename to a path. @ENDNODE @NODE fl @TITLE "Defining Checkmark Boxes" @{fg highlight} CHECKBOX/K @{fg text} Defines CHECKBOXes, with labels. When an external script is executed, all of the values (flags) of the CHECKed boxes will be refelected in the ENVariable $CHECKBOX Checkmark boxes will appear in the GUI above the Buttons. If RADIO is also defined, the Checkmark boxes will appear to the right of the Radio buttons. SYNTAX CHECKBOX <LABEL>;<FLAG> <LABEL> is the text that appears to the left of the CHECKMARK box. <FLAG> is a typical flag issued to an executable to define an operation. Flags are usually a dash and letter like this: -t or -gray. @{b}NOTE: Place only ONE Checkbox definition on each line.@{ub} If the LABEL has a space in it, you must surround the entire LABEL/FLAG entry line with double quotes. Here is an example: @{fg highlight} DEFINING CHECKBOXes @{fg text} Inside the MUInt calling script (.def), and before the call to MUInt, include lines like this to write the file RAM:Xcheckbox. @{fg fill} echo >ram:Xcheckbox "CHECKBOX *"LIST OUTPUT;-lo*"" echo >>ram:Xcheckbox "CHECKBOX LIST;-lo" @{fg text} The first line opens the file RAM:Xcheckbox (or overwrites it if it exists). The second and succeeding lines append to RAM:Xcheckbox Also see @{"TestSwitch" link exts} @{fg highlight} How many Checkboxes can you use @{fg text} The first six checkboxes will be placed vertically on the right margin of the window. The next six appear the the left of the first six. You must take care to insure there is enough room in the window to place the checkboxes. If you have too many Radios, the checkboxes may not appear, or the GUI may not be generated. If you run out of room, shorten the names of the labels, and increase the WIDTH to 80. @ENDNODE @NODE ra @TITLE "Radio Button and Cycle Gadgets" @{fg highlight} RADIO/K CYCLE/K @{fg text} @{b} These two gadgets are defined in the same manner. This section will explain the use of RADIO buttons, but the information applies to CYCLE GADGETS as well. @{ub} Defines a Mutually Exclusive button bank, with a TITLE. Only the selected button is returned. The labels are listed from the top to bottom in the same order they were defined. There are no limits on the number of buttons, or number of RADIO gadgets. On execution of an external script the flags associated with the selected buttons will be reflected in the ENVariable $RADIO. @{fg highlight} DEFINING RADIO BUTTON BANKS AND CYCLE GADGETS @{fg text} Inside the MUInt calling script (.def), and before the call to MUInt, include lines like this to write the file RAM:XRADIO. @{fg fill} echo >ram:Xradio "COLOR;Grayscale;-gr|Color;-col" echo >>ram:Xradio "OUTFILE;GIF;-gif|BMP;-bmp|TARGA;-tar" echo >>ram:Xradio "SIZE;FULL;-f|HALF;-1/2|QUARTER;-1/4" @{fg text} The first line opens the file RAM:XRADIO (or overwrites it if it exists). The second and succeeding lines append to RAM:XRADIO Examine the first line. COLOR is the TITLE of the button bank. It is followed by a semicolon. The next entry is Grayscale. This is a LABEL. Following the LABEL is a semicolon. The next entry is -gr. This is the FLAG that will be sent to ENV:RADIO if the label "Grayscale" is selected. More LABEL/FLAG entries may follow, separated by a vertical bar. Be sure to close the line with a quote mark. @{fg highlight} SYNTAX @{fg text} <TITLE>;<LABEL1>;<FLAG>|LABEL2>;<FLAG> <TITLE> Is the text that appears above the Radio button bank. <LABEL> Is the text that appears to the right of the button. <FLAG > Is the value that will be written to ENV:RADIO. <|> Is the vertical bar character that separates LABEL/FLAG groups. @{b}NOTE: Place only ONE Radio or Cycle definition on each line.@{ub} See the example below for more clarification. @{fg highlight} SCRIPT EXAMPLES @{fg text} Assuming three Radio button banks were defined like this: +------------------------------------------------+----------- + @{b}COLOR OUTFILE SIZE@{ub} + + Grayscale @{fg fill}X@{fg text} GIF O FULL O + + Color O BMP @{fg fill}X@{fg text} HALF @{fg fill}X@{fg text} + + TARGA O QUARTER O + + EIGHTH O + +------------------------------------------------+----------- Grayscale, BMP, and HALF are selected. When an @{" action button " link ab} is pressed, ENV:RADIO will hold this data: -gr -bmp -1/2 To get this data into your script, use the variable $RADIO like this: @{fg fill} RUN >NIL: DJPEG $RADIO $SOURCEFILE $OUTFILE or RUN >NIL: DJPEG $CYCLE $SOURCEFILE $OUTFILE @{fg text} This would place the flags necessary to DJPEG in the proper place on the command line. You may use @{" $CHECKBOX " link fl} in the same way. @{b}NOTE:@{ub} <FLAG> is NOT required. If you want to present a choice to the user that will never be tested for, just include the <LABEL> and no <FLAG>. @{b}ALSO:@{ub} If the <TITLE> is truncated, add some spaces to the first <LABEL>. This will force MUI to add some space for the <TITLE>. @{fg highlight} POSITION @{fg text} Radio buttons appear on the left of the window. Cycle Gadgets appear in the center of the window. Checkmark boxes appear at the right side of the window. @{fg highli NUMBER OF GADGETS ALLOWED @{fg text} Radios are added from the left margin. The limit on how many you can use depends on how many Cycles and Checkboxes are displayed. The ultimate number allowed depends on the @{" WIDTH "link wi} keyword and the length of the label text for each gadget. Cycle gadgets form a vertical group in the center of the window. Four cycle gadgets will be stacked up before the next group is formed. Checkmark boxes are also a vertical group. Six Checkboxes will stack up before the next group is formed. MUInt will fail silently if you attempt to put too many objects in the window. If you have loaded up on these gadgets, it is advisable to add them one at a time to test the limits. You can squeeze in more gadgets if you increase the WIDTH to 80 and shorten the titles. Also see @{"TestSwitch" link exts} @ENDNODE @NODE wi @TITLE "" @{fg highlight} WIDTH/K/N @{fg text} This number defines the real width of one row of buttons. The default is 66. Minimum is 1. Maximum is 125. WIDTH is, in effect, a right margin for the button banks. The number refers to the total number of characters each row of buttons can display before a new row is added. WIDTH effects how many Radios and Checkboxes can be displayed. If you can't squeeze in as many as you want, increase the WIDTH to 80. @ENDNODE @node st @title "Using the STRING and NUMSTRING keywords" @{fg highlight} STRING, NUMSTRING @{fg text} These are two text windows you can open in a MUInt GUI. You can define as many of these windows as needed. NUMSTRING will allow numeric including Hex and Exponential notation. STRING will allow any ASCII characters. ^X will clear a window. The user does not have to press Return to enter data. Return will advance the cursor to the next string field. Tab will advance the cursor to the last field. @{fg highlight} POSITION @{fg text} The string gadgets appear above the Buttons, in a horizontal group. @{fg highlight} SYNTAX @{fg text} The definition file generates the file that MUInt needs to put the windows in the GUI. Put one window on each line. @{fg fill} ECHO >RAM:<filename> "STRING0;<label>;<size>;<length>;<preload>" ECHO >>RAM:<filename> "NUMSTRING5;<label>;<size>;<length>;<@{b}preload@{ub}>" @{fg text} The keywords STRING and NUMSTRING define which window MUInt will display. The number after the keyword makes each window unique. This will become the ENV: variable name you use to retrieve the data entered in that particular window. Each field is separated by a semicolon. <filename> should be preferenced with a unique string like X. or CAM. followed by string. Ex: ram:CFT.string. <type> specifies the kind of window. A unique identifier is added at the end so the data can be recalled later by a script. <label> is a text string that will appear to the LEFT of the window. <size> defines the width of the displayed window as a percentage of the largest window on the line. <size> is a difficult concept to describe. MUI displays objects in different sizes, depending on how streched the window becomes. Therefore we can't define how wide the text entry window will appear. The <size> value refers to a ratio of the size of THIS window in comparison to other windows on the same line. If you have two windows on a line and you want them to have the same size, give them both a <size> of 100. If you want one window to be half the size of the other, make the smaller one <50> and the larger one <100>. In all instances, the <size> value is compared to the largest window on the line. Allowable values for <size> are from 0-1000. You will have to experiment with these values <length> determines the maximum length of the string to be entered. <@{b}preload@{ub}> is a text string that appears in the window when displayed. THIS IS THE ONLY OPTIONAL FIELD. If you don't include <preload> then the line must end with <length>". @{fg highlight} NUMSTRING VALUES ALLOWED @{fg text} These characters are allowed: 0123456789abcdef.+-E @{fg highlight} WIDTH @{fg text} The WIDTH keyword, as defined in the Command Line File limits how many objects can be placed on a single line before wrapping to the next line. MUInt WILL NOT wrap to a new line when the space needed for your strings exceeds WIDTH. If this happens, the GUI will not appear. Simply remove the last string you added, or insert a NEWLINE. @{fg highlight} ORDER OF APPEARANCE @{fg text} The windows appear in the GUI in the same order they are defined in the string file. The first window appears on the left and following windows appear to the right and then wrap down to another line when forced by the NEWLINE keyword. @{fg highlight} FORMATTING: The NEWLINE Keyword @{fg text} You have limited control of how the windows appear by specifying the order of appearance. Further control can be gained by forcing the string to a new line. @{fg fill} ECHO >RAM:<filename> "STRING0;Name: ;100;32" ECHO >>RAM:<filename> "NUMSTRING0;Age: ;2;2" ECHO >>RAM:<filename> "NEWLINE" ECHO >>RAM:<filename> "NUMSTRING1;Phone: ;60;10" ECHO >>RAM:<filename> "STRING1;Email: ;100;64" @{fg text} Only one NEWLINE may be specified at a time. You can not do this: ECHO >>RAM:<filename> "NEWLINE" ECHO >>RAM:<filename> "NEWLINE" @{b} The NEWLINE keyword opens a new child for the next line. If you call two consecutive NEWLINES, the result will be very strange, as the new child has no children. @{ub}@{fg highlight} THE COMMAND LINE @{fg text} You must tell MUInt where to find the String file like this: @{fg fill} STRING <filename> @{fg highlight} GETTING DATA BACK TO YOUR SCRIPT @{fg text} When an action button is pressed, MUInt scans all of the windows and writes to ENV: varibles the data it finds. If a window is empty, an ENV: variable of zero length is generated. The names of the ENV: variables come from the <type> entry in the definition file. (see above). @{fg highlight} EXAMPLE @{fg text} Using the example listed above, these ENV: variables will be available to your script: $STRING0 (name) $STRING1 (email) $NUMSTRING0 (age) $NUMSTRING1 (phone) @endnode @NODE lv @TITLE "LISTVIEW" @{fg highlight} LISTVIEW=LV/M @{fg text} The Listview (LV) gadget is unique within the context of MUInt. The LV may be loaded with text data from a file. It can also be loaded with a directory. (With a little help from DOS). LV supports something called Substitution. The data item(s) selected from the LV can be sent directly to a script by including two square brackets at the end of the button definition. Here's what it looks like: echo >>ram:ARCbuttons " READ LV ;amigaguide []" echo >>ram:ARCbuttons " CONVERT LV ;execute myscript []" Two different examples are presented above. The first one allows the user to select a text file to be viewed by AmigaGuide. The filename is passed to AmigaGuide with the [] brackets. The second example calls myscript and passes the selected data item(s) to to the script. The script must be able to receive the data item with the .KEY .BRA .KET keywords. ENV VARIABLE (This section rewritten 1-12) This variable will not be written if an action button is clicked and the user has not made a selection from the ListView. If the user has made a selection, ENV:LV will be written. This allows you to test to see if a selection has been made. Make this test at the beginning of each script that depends upon data arriving via the substitution brackets: @{fg fill} .KEY data_in .BRA { .KET } IF NOT EXISTS $LV RTEZREQUEST "ERROR" "YOU MUST MAKE A SELECTION" QUIT ENDIF @{fg text} You cannot test for the existance of {data_in} without resorting to some very ugly DOS constructs. This makes the test easy. POSITION The ListView gadget appears in the window below BODY and above RADIO/CHECKBOX. LOADING THE LISTVIEW The LV can be loaded with two types of lists: A list of filenames from a directory(s) A list of data items stored in a file @{b}Loading a list of filenames@{ub} is fairly straightforward. The following example is from XtoILBM.def. It does a LIST LFORMAT of a directory. The directory can be called by its name or referenced as a predefined variable. @{fg fill} ;------------------------------------------ ; LOAD THE LISTVIEW FROM THIS DIRECTORY ;------------------------------------------ list >ram:XTLVdir $XTLV lformat "%F%N" ALL @{fg text} The directory has been defined as the ENV:VARIABLE $XTLV. Following this call, the file ram:LVdir will contain a list of filenames, including the full path. The LV call in the Command Line file looks like this: @{fg fill} echo >> ram:X2.cl "LV ram:XTLVdir SORT" @{fg text} This will cause the LV to be loaded with the contents of the file ram:LVdir. You may, of course, enter a real path instead of XTLV$. The LIST LFORMAT DOS command is one of the few joys of DOS. Use the exclusionarry form of ~(#?.info) or the inclusionary form of (#?.lha) to further restrict the files that appear in the listview. Many times it is better to not include the full path of the file in the listview. You can use %N to reflect the name only. @{b}Loading the LV with data@{ub} from a file is easier. First you must determine the file to be used. You could hard-code the name into the script, but that offers little flexibility. Normally you would offer the user a list of filenames with rtFileRequest. They would pick a file that has the data they want to work with. At this point, the filename would exist as an ENV:VARIABLE, for example ENV:LABEL. The call on the Command LIne would look like this: @{fg fill} echo >>ram:LAB.cl "LV $LABEL MULTISELECT SORT" @{fg text} MULTIPLE SOURCES LV can display text from many source files. From within the Command Line defination file, just call LV more than once. The files will be collected in the order they called and assembled into a single file that will be loaded in the LV. Here's an example: @{fg fill} ECHO >>ram:LAB.cl: "LISTVIEW DH1:label_list1" ECHO >>ram:LAB.cl: "LISTVIEW DH1:label_list2" ECHO >>ram:LAB.cl: "LISTVIEW DH1:label_list3" @{fg text} In this example, the three files will will be loaded into the LV. Label_list1 will be presented first, with the other two following. SORTing the LV @{fg highlight} SORT/K @{fg text} By adding the Keyword SORT to the end of the line, the data loaded into the LV will be SORTed. ASCENDing order is assumed unless you specify SORT DESCEND. If you are loading the LV with multiple files, you only need to specify SORT once. All of the files will be merged together and SORTed. @{fg fill} ECHO >ram:ARC.cl: "BEGIN" ECHO >>ram:ARC.cl: "LISTVIEW LabelList SORT DESCENDING" ECHO >>ram:ARC.cl: "BUTTONS ram:ARCbuttons" ECHO >>ram:ARC.cl: "END" @{fg highlight} MULTISELECT=MULTI/S @{fg text} Multiple entry selection is ENabled with this Keyword. MULTI has one qualifier, CONCAT. MULTI and CONCAT apply only to the ListView. @{fg fill} ECHO >>ram:ARC.cl: "LISTVIEW LabelList SORT MULTI" @{fg text} The LV's normal mode of operation allows single data items to be selected. When MULTI is specified, you can MULTISELECT items by holding down the SHIFT key and the LMB. These lines of data are sent out, through the [] brackets, one line at a time, just as they appeared in the LV. MUInt sends each line out and waits for the Script to end and then sends out the next line. This continues until all lines have been processed. Line one Line two Line three @{fg highlight} CONCAT/S @{fg text} @{fg fill} ECHO >>ram:ARC.cl: "LISTVIEW FileList MULTI CONCAT" @{fg text} When the CONCAT qualifier is used, the selected data items are concatonated, one after another, and the entire line of items are sent: Filename1 Filename2 Filename3 CONCAT would typically be used when selecting filenames from the LV. The resulting output would be sent to an executable that can accept multiple entries on it's command line. Lha or Join would be an example. CONCAT is valid only when MULTI is selected. @ENDNODE @rem ================================================================== @rem SCRIPT DESCRIPTION SECTION @rem ================================================================== @NODE MUIN @TITLE "MUInterface" @{fg highlight} DEFINING A MUI GUI Keywords used in the Definition file: @{fg text} TITLE/K,BUTTONTEXT=BUTTONS/M,LISTVIEW=LV/M,BODYTEXT=BODY/M, LEFT/K,CENTER/K,RIGHT/K,CHECKBOX/K,RADIO/K,SORT/K,CONCAT/S MULTISELECT=MULTI/S,WIDTH/K/N,PUBSCREEN/K,NAME/K,DEBUG/S NOTE: The above keywords are shown in the standard AmigaDos not- ation. However, the Keywords are never interpreted by DOS. They are only used to define a MUI from within a Definition file. MUIUnt uses it's own parsor to interpret the Keywords and their arguments. The Qualifiers - /K, /M, etc. are included here to help you understand their usage. Usage: These Keywords define the MUI. The Keywords are written as a text file that MUInt calls. Place one Keyword on each line, followed by any arguments necessary. All Keywords are optional. An example script is presented below to show typical usage. @{"TITLE " link ti} <text> - Title text for requester window. @{"BUTTONTEXT " link bu} <file> - Create Buttons and calls external scripts. >OR BUTTONS @{"BODYTEXT " link by} <file> - Create a window to display scrollable text. >or BODY @{"LISTVIEW " link lv} <file> - Create a Scrolling ListView >or LV @{"STRING " link st} <file> - Create text entry (string & numeric) windows. @{"LEFT " link fr} <addr> - Create a Filerequester on the Left. @{"CENTER " link fr} <addr> - Create a Filerequester in the Center. @{"RIGHT " link fr} <addr> - Create a Filerequester on the Right. @{"CHECKBOX " link fl} <file> - Create Checkmark boxes @{"RADIO " link ra} <file> - Create Radio buttons @{"NAME " link na} <name> - Give a Name to the Iconified Icon @{"CYCLE " link ra} <file> - Create Cycle Gadgets @{"SORT " link so} <type> - Sort the LV list. Permissible values are: ASCEND,DESCEND. Default is No Sort. @{"MULTISELECT" link lv} <name> - Allow Multiple entry selection. Default OFF. >or MULTI Applies to ListView only. @{"CONCAT " link lv} <name> - Concatonates all Multiselected LV items. Applies to ListView and MULTI only. @{"WIDTH " link wi} <num> - Total # of chars for one line of buttons. Default 66. Min 1. Max 125. @{"PUBSCREEN " link pu} <name> - Public Screen name to display the GUI @{"DEBUG " link db} - Don't delete ENVariables on shutdown. Why it was done like this: Normally a call to an executable is followed by a series of Keywords on the Command Line. MUInt gets it's Keywords from a file. We have departed from the convention for these reasons: * Reading the Keywords from a text file saves a lot of space on the Command line. * The text file that holds the Keywords can be quickly edited. Since the Keywords and Arguments are arranged vertically, you can scan the list quickly for typing errors and missing quote marks. @{fg highlight} The MUInt Command Line File @{FG text} Usage : MUInt <command_line_file.cl> On the first line enter the keyword BEGIN. MUInt scans the file looking for BEGIN. Then it takes in the keywords until it finds the word END. Everything following END is disregarded by the parsor. @{fg highlight} The following script generates a GUI that has all of the gadgets that MUInt is capable of generating. At first glance, it seems complicated. Most definition files will be very simple by comparison. Example script: @{FG FILL} ;================ EXAMPLE MUINT DEFINITION SCRIPT =================== STACK 8000 ; FILENAME: ARCer.def ; DATE: 01-23-94 ;============== SET UP SOME VARIABLES FOR THE POPASLS =============== SETENV SOURCE RAM: SETENV DESTINATION RAM:TEMP ;========== WRITE SIX FILES TO RAM: THAT DEFINE =============== ;========== BUTTONS, CHECKMARK BOXES, RADIO BUTTONS,=========== ;========== STRINGS, CYCLES, AND THE COMMAND LINE FILE ======== ECHO >ram:ARC.buttons " UNARC ;execute A.unarcL.scp" ECHO >>ram:ARC.buttons " ARC ;execute A.arcL.scp" ECHO >>ram:ARC.buttons " LISTARC ;execute A.listarcL.scp" ECHO >>ram:ARC.buttons " TESTARC ;execute A.testarcL.scp" ECHO >>ram:ARC.buttons " READ LV ;amigaguide []" ECHO >>ram:ARC.buttons " EDIT LV ;emacs []" ECHO >>ram:ARC.buttons " QUIT " ECHO >ram:ARC.checkbox "LIST;-l" ECHO >>ram:ARC.checkbox "TEST;-t" ECHO >ram:ARC.radio "SIZE;FULL;-f|HALF;-1/2|QUARTER;-1/4" ECHO >>ram:ARC.radio "OUTFILE;GIF;-gif|BMP;-bmp|TARGA;-tar" ECHO >ram:ARC.cycle "BUFFER SIZE;100K;-100|500K;-500|One MB;-1000" ECHO >ram:ARC.string "STRING0;JPEG Viewer Viewer;20;40;fjpeg" ;==== THESE COMMANDS ARE FED TO MUINT TO DEFINE THE GUI. ============= ;==== THEY MAY APPEAR IN ANY ORDER EXCEPT BEGIN AND END ============= ECHO >ram:ARC.cl: "BEGIN" ECHO >>ram:ARC.cl: "TITLE *"ARCER by BOTH Software*"" ECHO >>ram:ARC.cl: "BODY Aarcbody.txt" ECHO >>ram:ARC.cl: "LEFT *"SOURCE DIRECTORY;$source*"" ECHO >>ram:ARC.cl: "RIGHT "DESTINATION;$destination" ECHO >>ram:ARC.cl: "LISTVIEW ram:LocalDir SORT MULTI" ECHO >>ram:ARC.cl: "BUTTONS ram:ARC.buttons" ECHO >>ram:ARC.cl: "CHECKBOX ram:ARC.checkbox" ECHO >>ram:ARC.cl: "RADIO ram:ARC.radio" ECHO >>ram:ARC.cl: "CYCLE ram:ARC.cycle" ECHO >>ram:ARC.cl: "STRING ram:ARC.string" ECHO >>ram:ARC.cl: "NAME ARCer" ECHO >>ram:ARC.cl: "DEBUG" ECHO >>ram:ARC.cl: "END" ;======================= CALL MUINT ============================ MUInt ram:ARC.cl DELETE ram:ARC.#? QUIET QUIT ; ================ END OF MUINT DEFINITION SCRIPT ================= @{fg text} The file ram:ARC.cl holds the entire GUI Definition for MUInt. @ENDNODE @rem ================================================================== @rem DOS EXTENSIONS SECTION @rem ================================================================== @NODE EXTS @TITLE "DOS Extensions" These extensions are explained in this file: TestSwitch Tr @{b} IXEMUL.LIB is not needed for any of these programs @{ub} @{fg highlight} TestSwitch @{fg text} TestSwitch tests the $RADIO, $CYCLE, or $CHECKBOX variables to see if a certain switch (flag) has been specified. Since DOS lacks the CASE statement, you will have to call TestSwitch for each flag you want to test. Usage: @{fg fill} TestSwitch $RADIO "-gif" IF WARN ECHO "The GIF button was selected" ELSE ECHO "The GIF button was not selected" ENDIF @{fg text} As you can see from the example above, if the switch was present in the $RADIO variable, TestSwitch returns a WARN. Otherwise a ZERO is returned. @{fg highlight} Tr (Translate) @{fg text} Tr is a UNIX tool that examines a file and change characters within it. The version of TR included here is an Amiga port of the FreeBSD source. The Man page for Tr is included, but is very cryptic. Tr is included in the MUInt package so that you can remove or modify the flags returned in the $RADIO and $CHECKBOX variables. This way, you can intercept certain flags, remove them, and then pass $RADIO onto the executable that needs them. Tr can be used from the shell or from within a script. Redirection is supported. The following document is the man page from the original GNU source. @{" tr.man " system "run >nil: sys:utilities/amigaguide guide/tr.man"} @{fg highlight} General usage from within a DOS Script @{fg text} Tr performs three basic functions on text files: -d * Deletes unwanted characters -t * Changes characters (Translate from one to another) (default) -s * Removes repeated characters (Squeeze repeated characters) @{fg highlight} Format @{fg text} Tr can be used in backticks or have it's output redirected. Here are two examples: SETENV OUTFILE `tr "A-Z" "a-z" <infile` tr >outfile "A-Z" "a-z" <infile Both forms will take input from <infile> and convert all upper case letters to lower case. The result is written to <outfile>. The examples perform a TRANSLATE operation. The first string "A-Z" is what Tr is looking for in the infile. The second "a-z" is what will be substituted in the outfile. @{fg highlight} Examples of TRANSLATING characters @{fg text} The -t switch is not needed for translation. In the following example we will change all occurances of "K" to "C". SETENV OUTFILE `tr "K" "C" <infile` Special characters and punctuation may be specified by preceeding them with a backspace. Non printing characters may be specified. Here is a list of these characters: \a Control-G \b Control-H \f Control-L \n Control-J \r Control-M \t Control-I \v Control-K \ooo The character with the value given by ooo, which is 1 to 3 octal digits. \\ A backslash. To change newlines to carriage returns, use this form: SETENV OUTFILE `tr "/n" "/r" <infile` @{fg highlight} DELETING CHARACTERS @{fg text} The -d switch makes Tr remove selected characters from a file. The following example will remove all occurances of the letter "X" from a file: SETENV OUTFILE `tr -d "X" <infile` @{fg highlight} SQUEEZING OUT REPEATED CHARACTERS @{fg text} The -s switch causes Tr to delete repeated characters, leaving only one of the characters in it's place. To demonstrate this, assume the infile is this: "Thaaaaats All Folks!" To remove the extra a's use this form: SETENV OUTFILE `tr -s "a" <infile` ECHO $OUTFILE Thats All Folks! This is fine if you know there are extra a's in the file. If you want do a broad based squeeze, try this: SETENV OUTFILE `tr -s ":alpha:" <infile` This will squeeze out all repeated alpha characters. The :alpha: notation is a "character class". These classes are common groupings of character types. They save you a lot of typing. See the man page above for a listing of character classes. @{fg highlight} DELETING AND SQUEEZING CHARACTERS @{fg text} The -d and -s switches may be used together. Tr first deletes and then squeezes the result. @{fg highlight} COMPLEMENT (the NOT function) @{fg text} The -c switch replaces the characters specified with their compliment. An example: If you specify "A-Z" with the -c switch, everything BUT A-Z are specified. In Amiga terms, this is a NOT function. The following example uses the Compliment and Squeeze switches in combination. The line will clean up a typical UNIX man page, removing all tabs, non printing characters, escape codes, etc., leaving the file clean so it may be viewed properly. It does a Squeeze on all characters not specified. An easy way to look at this operation is to put all the characters you want unchanged inside the string, and then do a compliment on it. CLEANUP A MAN PAGE: SETENV OUTFILE `tr -c -s "a-z A-Z 0-9 /n /r /space /punct" <man.page` Once you have mastered the basics of Tr, refer to the man page above for more details. @ENDNODE @rem ================================================================== @rem TROUBLESHOOTING SECTION @rem ================================================================== @NODE TROU @{b}The GUI appears but some of the objects are missing: @{ub} Check the spelling of filenames for BUTTON and other files. Make sure the REMs (;) are removed from the .DEF file. Check for missing > characters in the lines that ECHO out button data to a file. Check the Command Line file for missing quote marks around data items that have spaces. @{b} ECHO Failed: @{ub} Missing quote mark. @{b} Textwin appears but the file it was to display is missing: @{ub} The filename is incorrect or the file does not exist. Check the path. @{b} Instead of a string, the $string name appears: @{ub} The string cannot be found. Make sure you have not used the string name as both a local and global name in the same script. Local always takes precedence. If the string refers to a file, the file is not found. @{b} MUInt fails to appear @{ub} The Command Line File was not found. Too many RADIOS, CYCLES, STRINGS, or CHECKBOXs were defined. MUI is not present on the system. Include the DEBUG keyword and try it again. @{b} Execute problems @{ub} Usually caused by incorrect use of substitution brackets when calling a script that takes in LV data. Remove the /A or /M after the keyword following .KEY. @ENDNODE @NODE exam @TITLE "Programming Examples" Most of us learn well from seeing examples of working programs. During the development of MUInt, I wrote dozens of MUInt scripts. The least bug-laden of these programs are distributed in four archives called: @{"MUInt_prgs_x" link archives} These programs solve just about any programming challenge you you can think of. They push MUInt to the limit and contain many advanced techniques. These four archives are assembled so they are about the same size: <200KB. If the idea of quickly generating a MUI GUI really grabs you, download the archives and take a look at how the scripts work. If you need to brush up on your DOS skills, download this file: util/wb/DosMan121.lha This is a MUInt program that displays "man" pages for all DOS commands from 1.3 through 3.0, written by Peter Bagnato. @{fg highlight} Using MUInt with other high level programming languages @{fg text} I have successfully integrated MUInt with ACE Basic and COMAL. There is no reason MUInt could not be used with Pascal and other languages. Here's a quick rundown on the methods to add a MUInt GUI to your program, regardless of the language you use: * Prototype your GUI in DOS first. Your program must make a test immediately: * Is this the first time I've been called? (no <args>) If, so * Write the buttons, etc. files to ram: * Copy the program from it's place on the drive to ram: * Call MUInt * STOP At this point your program is in RAM and is NOT RUNNING. The GUI is on the screen, waiting for a button to be pressed. When a button is pressed, "run ram:myprog <arg>" is issued to DOS. Your program will fire up, evaluate the <arg>, take the prescribed action, then STOP, waiting to be called again. When the QUIT button is pressed, you should delete all myprog files from ram:. I have included two simple examples in this archive. Look in MUInt_prgs/MAN. A COMAL and ACE version of MAN is included there. Take a look. When COMAL is released, (don't hold your breath) I will include an extensive tutorial on using MUInt. I will be happy to assist you when integrating MUInt into a program. Just Email me. Colin Thompson colin@connectnet.com @ENDNODE @NODE archives @TITLE "MUInt_prg Archive readmes" ARCHIVE FILENAME and SIZE ~~~~~~~~~~~~~~~~~~~~~~~~~ MUInt_prgs_1 172K PROGRAMS CONTAINED IN THIS ARCHIVE ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ DJPEG5.def CJPEG5.def These programs are GUIs for the CJPEG and DJPEG version 5 release. They will convert pictures to and from the JPEG format, with scaling. All programs, except a viewer, are included, including 020 versions of the executables. You will need a JPEG viewer. A preferences program to set your viewer prefs and other preferences is built in. ARCHIVE FILENAME and SIZE ~~~~~~~~~~~~~~~~~~~~~~~~~ MUInt_prgs_2 108K PROGRAMS CONTAINED IN THIS ARCHIVE ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ ARCER.def Multipurpose archiving utility Requires Lha, Zoo, Arc (not included) uuencode and compress included KIS.def Icon Viewer LABEL.def Label and COD tag printing utility PR.def Formats text sent to the printer ixemul.library required (not included) PC-FX85.def Send printer codes to an Epson FX85, 185 ixemul.library required (not included) PC-Star48.def Send printer codes to a StarJet48 inkjet ixemul.library required (not included) ARCHIVE FILENAME and SIZE ~~~~~~~~~~~~~~~~~~~~~~~~~ MUInt_prgs_3 181K PROGRAMS CONTAINED IN THIS ARCHIVE ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ FIGLET.def A new release of Figlet by BOTH. Allows redirection. It makes large letters like this: ___________.__ .__ __ \_ _____/|__| ____ | | _____/ |_ | __) | |/ ___\| | _/ __ \ __\ | \ | / /_/ > |_\ ___/| | \___ / |__\___ /|____/\___ >__| \/ /_____/ \/ 108 figlet "fonts" are included. This library of fonts represents all of the fonts available. A preferences program is built in. You should have a text editor to make the most use of FIGLET.def. If you are using v40 of AmigaGuide or MultiView, some of the fonts will not appear correctly due to a bug in the v40 release. (they can't display a backslash) ARCHIVE FILENAME and SIZE ~~~~~~~~~~~~~~~~~~~~~~~~~ MUInt_prgs_4 131K PROGRAMS CONTAINED IN THIS ARCHIVE ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ GPA.def GUI to set protection bits Indexer.def A list of useful programs on Aminet. Mosaic-NoNet Select a HTML document to read with MosaicNoNet NoNewLine.def Text manipulation tool to remove newlines from a text file. Yek.def A GUI for the popular filesplitter, with some extras. Prefs program is built in. ASCII.def A simple viewing program for ASCII text art. Several pieces of art are included. A viewer like More or PPmore can be used if you have it. Desert_Date.scp Sets the date on Amigas without a clock. Not a MUInt script. Requires some DOSReqTools files only. IconViewer.def A GUI to show icons, using the included datatype. You must have OS 3.0 or up and Multiview. You must install the datatype. X2ILBM.def Converts any picture file (by datatype) to ILBM. 3.0 only. Prefs program to set up frequently scanned directories, and viewer programs is built in. @ENDNODE