The documentation to FORM.PLG 1.2 September 16, 1998 by Alexander Clauss Reuterallee 39 64297 Darmstadt aclauss@hrzpub.tu-darmstadt.de (English Translation by Mark Wherry) Contents ======== 1 Introduction 2 Legal 3 Installation 4 Requirements 5 Features 6 Functions of the Plugins 6.1 Form.New 6.2 Form.Add 6.3 Form.Do 6.4 Form.Get 6.5 Form.Delete 6.6 Form.Input 6.7 Form.Note 7 An Example 8 Future versions 9 History 10 TransAction 1 Introduction *************** FORM.PLG is a plug-in for Scripter from ASH (or Simple Script) which makes the creation and handling of simple dialog boxes (or forms) possible. The empahsis here lies on the word simple, because it should also make adding dialogs to scripts very easy for the programmer. 2 Legal ******** This plugin is freeware, and may be enclosed with any script that you write, on condition that these instructions (FORM_PLG.TXT or FORM_PLG.HYP) are always included. FORM.PLG was written by Alexander Clauss, Reuterallee 39, 64297 Darmstadt. Email: Alexander_Clauss@OF2.maus.de 3 Installation *************** Simply copy the file FORM.PLG into the Scripter (or Simple Script) PLUGIN folder. There is nothing else to do! 4 Requirements *************** This Plugin requires either a current version of WDIALOG.PRG or the MagiC Operating System (version 4+), and naturally a copy of ASH- Scripter, or Simple Script. 5 Features *********** ù Dialogs in windows. ù Any number of running scripts can create dialogs simultaneously. ù Keyboard shortcuts are automatically assigned. ù Very simple handling of the dialog boxes. ù Because MagiC/WDialog features are used, memory requirements are low. ù The operating elements (maximum of about 100 per dialog) can be freely placed. 6 Functions of the Plugins *************************** This plug-in extends Scripter (or Simple Script) with the following commands: 6.1 Form.New ============= id = Form.New(title,buttons,width,height); This function generates a new dialog, which will not yet be visable. title The title of the dialog/form (String). buttons The exit buttons of the dialog (String). The parameter is set up like this: "button1|button2|button3|...". If the first character of the button name is '@', this button will be used as the default button. width The width of the dialog in characters (integer). height The height of the dialog in characters (integer). id This call will return the handle of the dialog that has been created. You will need to use this handle with all of the following functions, as it allows each dialog to be uniquely identified (long). 6.2 Form.Add ============= obj = Form.Add(id,Type,x,y,label,...); With this function you can add further objects to the dialog, like check boxes, radio buttons, and so on... id The handle of the dialog (long). Type The type of object you wish to add (String). The use of small (initial) letters, as in previous versions, has been abandoned. Available Types: "GroupBox" (or "Group"), "CheckBox" (or "Check"), "RadioButton" (or "Radio"), "Text", "Edit", or "Button". If the user clicks on an object which is of the type "button", the dialog exits. x,y The position of the object in characters (integer). label The name of the object (String). With radio buttons, the names of each button are included together and separated by the '|' character. If the button name starts with a preceding '@' character, this will be the radio button that os selected by default when the dialog is opened. With edit fields, the string specified will be the preset contents of the input field. ... Further parameters used in this call will depend on which type of object you are adding. GroupBox width Width of the box in characters (integer). height Height of the box in characters (integer). CheckBox state Initial state of the box. The following values will indicate that the check box will be selected: 1, "true", "selected", "checked". Anything else will mean that the check box will not be selected when the dialog is displayed. Edit length The length of the input field in characters (integer). allowed Defines character by character, the format that is valid in the input field. If there is an error with this paramter, "X" is assumed by default. "9" Allow only numbers/digits. "A" Allow only wild characters/spaces. "a" Allow only characters/spaces. "N" Wild characters, digits, space characters. "n" Characters, digits, space characters. "F" Characters in filenames are allowed. "P" Characters in path names are allowed. "p" Characters in path names, but without "*" and "?". "m" Characters in long filenames are allowed. "X" Allow all characters. obj A handle for the object, which is used in order to inquire about it's state, or to evaluate it's contents (integer). 6.3 Form.Do ============ exitBut = Form.Do(id); The dialog is displayed. The script only continues when the dialog box has been closed. The return value will hold the name of the button that the user clicked on to end the dialog. 6.4 Form.Get ============= value = Form.Get(id,obj); Ascertains information from the object obj in the dialog with the handle id. The result differs depending on the type of the object: CheckBox If the check box is selected, value will contain "Selected", otherwise if the check box was not selected, nothing will be returned. RadioButton The text of the selected button. Edit The text that was entered. Anything else The value or name of the object. 6.5 Form.Delete ================ Form.Delete(id); Deletes the dialogue from memory. No more data can be retrieved from this dialog. 6.6 Form.Input =============== RetValue = Form.Input(Prompt,Default_Text); Displays a simple dialog in which a single text field is provided. The dialog is made up of a text line, a text input and the OK and Cancel buttons. Prompt Displays a message which should contain instructions guiding the user with what they have to enter. Default_Text This is the text that will be displayed in the input text field when the dialog is first opened. RetValue The value returned by this function is passed in two parts. RetValue[0] contains 'OK' or 'Cancel', depending on which button the user clicked to close the dialog. RetValue[1] contains the text that was entered by the user. 6.7 Form.Note ============== exitBut = Form.Note(Title,text,buttons); Opens a reference dialog which displays the specified text, and any number of exit buttons. title The title of the box is displayed in the title line of the windowed dialog. Text The text that is displayed in the dialog box. This text can be almost as long as you like! The '|' character indicates a line break, and the following text will be displayed on a new line. You should not use more than approximately 18 lines, as with this number, the dialog can still be displayed on a SM124 montor. buttons The exit buttons of the dialog. Different buttons are separated with the '|' character. If the '@' character is the first character of the button name, this button will be used as the default button. If there is an error with this parameter, only an OK button will be provided. exitBut The text of the button that was clicked on. 7 An Example ************* // Create a dialog with space for 37x7 characters. id = Form.New("Test-Dialogue", "@OK|cancel", 37, 7); // Place groups group1 = Form.Add(id,"Group",0,0," Group 1 ",18,5); group2 = Form.Add(id,"Group",19,0," Group 2 ",18,5); // Add a few check boxes to the dialog. check1 = Form.Add(id,"Check",1,1,"Choice 1","selected"); check2 = Form.Add(id,"Check",1,2,"Choice 2"); check3 = Form.Add(id,"Check",1,3,"Choice 3"); // Add a few radio buttons, of which only one can be selected at a time. radio = Form.Add(id,"Radio",20,1,"Radio 1|@Radio 2|Radio 3"); // A field for any text input. edit = Form.Add(id,"Edit",1,6,"Default-Text",35); // Display the dialog. Form.Do returns the exit value as soon as a button // has been clicked on. exit = form.Do(id); // Now we can can evaluate the contents and state of the objects. print("Dialog was exited by the user clicking [",exit,"]"); print(); print("Text from Groupbox 1 : ",Form.Get(id,group1)); print("Text from Groupbox 2 : ",Form.Get(id,group2)); print("Value from Checkbox 1 : ",Form.Get(id,check1)); print("Value from Checkbox 2 : ",Form.Get(id,check2)); print("Value from Checkbox 3 : ",Form.Get(id,check3)); print("Selected Radio Button : ",Form.Get(id,radio)); print("Text in the edit field : ",Form.Get(id,edit)); // Now delete the dialog from memory. Form.Delete(id); // Finished! 8 Future versions ****************** In future versions popups, list boxes and special fields to handle the choice from file selectors, characters or colours will be implemented. Further objects may also be added. If and when the plug-in is extended, I would like to know what you think of the new features, and if there is anything else you would like me to add. I am always interested in your ideas and particularly in feedback from users or script programmers. 9 History ********** V1.0: First version V1.1: New functions: Form.Input and Form.Note. This adds both of the functions from the dialog plug-in. Using both the form and dialog plugins is therefore no longer necessary. V1.2: Bugfix: If no input was made in the input field created with Form.Input, errors occurred. 10 TransAction *************** TransAction is the world's first translation crew! We reckoned since demo coders get together in crews so could we. We take the best software around and work with the authors to bring you English releases. We've all been translating software for years so we decided it was time to pool our efforts. Currently we only translate German and French software into English but if you want to extend the crew get in touch! The TransAction crew are: ù [JC:] Joe "InterActive" Connor: jconnor@cix.co.uk ù [ML:] Mick Lock: mlocka@cix.co.uk ù [PW:] Peter West: xlator@cix.co.uk ù [CW:] Colin Watson: cwatsonb@cix.co.uk ù [MW:] Mark Wherry: mark_wherry@cix.co.uk ù [TransAction:] 12 Portal Road, Aylesbury, Bucks HP22 5PR ù [Telephone:] +44 (0)1296 622400 leave us a message on the answerphone! ù [Email:] m.lock@zetnet.co.uk or mlocka@cix.co.uk ù [Home page:] http://www.users.zetnet.co.uk/micklock/transact/index.htm