@database ShellScr.guide @author Kyzer/CSG @$VER: ShellScr.guide 1.5 (02.09.98) @remark you can read this in a text viewer, if you need to. @node main "ShellScr v1.5 documentation" @{u}ShellScr v1.5@{uu} @{" " link intro} Introduction @{" " link usage} General usage @{" " link options} ShellScr options @{" " link history} ShellScr history @{" " link glossary} Glossary of important terms @{" " link credits} Credits ShellScr is a program to open a full-sized shell on its own public screen. Copyright (C) 1997-1998 Kyzer/CSG This program is free software; you can redistribute it and/or modify it under the terms of the GNU General Public License as published by the Free Software Foundation; either version 2 of the License, or (at your option) any later version. This program is distributed in the hope that it will be useful, but WITHOUT ANY WARRANTY; without even the implied warranty of MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the GNU General Public License for more details. You should have received a copy of the GNU General Public License along with this program; if not, write to the Free Software Foundation, Inc., 59 Temple Place - Suite 330, Boston, MA 02111-1307, USA. @{"Contacting the author" link credits} @endnode @node intro "Introduction" Instead of using the shell in a window and risk clutter on your Workbench, why not let a shell have its own screen? ShellScr is a tool which opens a new public screen and opens a fullscreen sized shell on it. After all the windows on the public screen close, including the shell itself, the screen closes. ShellScr can also start the shell using a different file from the usual S:Shell-Startup, so in a way it can be used as an alternative to IconX. @{"How to use ShellScr." link usage} @endnode @node usage "Using ShellScr" @{b}Requirements:@{ub} @{b}-------------@{ub} ShellScr requires Workbench 2 (v37) or better to run. To use fonts other than topaz, you need diskfont.library available. The optional ASL requesters which can be used to select fonts and screenmodes both require at least the Workbench 2.1 version of asl.library (v38) or a replacement/patch, such as ReqTools and ReqPatch. @{b}Distribution:@{ub} @{b}-------------@{ub} Please give people the entire archive as you recieved it, with the source code, example icons and this guide. Thanks. @{b}Installation:@{ub} @{b}-------------@{ub} Simply copy the ShellScr program to wherever you want, for example your 'C:' directory, or 'Workbench:Utilities' drawer. You should also copy this guide somewhere safe for reference. The provided example icons are just for demonstration, if you actually want to use them yourself then you should adjust the 'default tool' of these icons to reflect where you installed ShellScr (change them from '/ShellScr' to 'C:ShellScr', or just 'ShellScr' if you have Workbench 3.) The 'src' directory contains the Amiga E source of ShellScr. This is not needed to run ShellScr. Programmers should read the @{"source notes" link sources}. @{b}Starting ShellScr:@{ub} @{b}------------------@{ub} You can launch as many copies of ShellScr as you want. It is pure and can be made resident. To start ShellScr, simply double-click on its icon, or type "ShellScr" at an already opened shell. You will then get a new shell on its own screen. This screen is now the default screen, and many programs will open their windows on this screen rather than the Workbench. If you shift-select a file or directory from the Workbench, then run ShellScr, you will start the shell in that directory. This will also work if you select a file or directory, and start ShellScr on this directory with a "ToolsDaemon" or "ToolManager"-like 'dock' program. The shell can be closed at any time, by pressing CTRL-\\, or typing EndShell at the shell prompt. However, the screen will only close when all the windows on it are closed. Usually the shell is the only window, so the screen goes away when the shell does. See @{"ShellScr options" link options} for how to customize your screen and shell. @endnode @node options "ShellScr options" You may change how ShellScr operates using the following options. You may set them from the shell, from tooltypes of the ShellScr program, from the tooltypes of an icon whose default tool is ShellScr, from the tooltypes of an icon or drawer that is multi-selected when starting ShellScr, or from the tooltypes of an icon which is selected while starting ShellScr as a WB command of ToolsDaemon or ToolManager, or another such 'dock' program. Screen options @{" " link PUBNAME} PUBNAME @{" " link MODEID} MODEID @{" " link DEPTH} DEPTH @{" " link FONT} FONT @{" " link AUTOSCROLL} AUTOSCROLL @{" " link SHANGHAI} SHANGHAI @{" " link TITLE} TITLE @{" " link NOTITLE} NOTITLE Shell options @{" " link CONSPEC} CONSPEC (WINDOW) @{" " link COMMANDFILE} COMMANDFILE (FROM) @{" " link STACKSIZE} STACKSIZE @endnode @node PUBNAME "PUBNAME option" WB: PUBNAME Shell: PUBNAME=NAME This is the public name that ShellScr will give to the screen it creates. The standard public name is SHELL_XXXX, where XXXX is a unique ID code for that particular shell. You are advised _not_ to use this option unless necessary, as when you open one shell with a name, you cannot open another shell with that name at the same time. Please take a look at the program MultiCX, which has options to create a 'magic' public screen name for the frontmost screen, whatever it may be. If you want to set the text on the screen's titlebar, please use the @{"TITLE" link TITLE} option. @endnode @node MODEID "MODEID option" WB: MODEID Shell: MODEID=ID This is the ModeID for the screenmode you want the screen to be. It specifies what monitor and resolution ShellScr's screen should use. You may specify the screenmode in any of the following ways: - as a decimal number (compatible with previous ShellScr modeids) - as a hexadecimal number, starting with a '$' or '0x', eg "0x29004" - as the real name of a screenmode, eg "PAL:High Res Laced". - as a question mark, "?", or blank string, "", in which case an ASL screenmode requester will open and allow you to choose a screenmode. You can get a list of "real names" from the Screenmode preferences editor, or the ASL screenmode requester. The check of real names is case-sensitive, so "PAL:High Res" is correct, but "pal:high res" will not be accepted. If you do not specify a ModeID, or you specify an invalid one, the default is to use the same screenmode as the default screen (usually Workbench). Also see the @{"DEPTH" link DEPTH} option, for setting the number of colours on the screen. @endnode @node DEPTH "DEPTH option" WB: DEPTH Shell: DEPTH/N This is a decimal number of how many bitplanes you want for the screen, between 1 and 4, or between 1 and 8 on machines with the AGA chipset or similar enhanced graphics card. If you have a modern graphics card, you may be able to select 16 bitplanes (hicolour) and 24 bitplanes (truecolour). The more bitplanes used, the more memory the screen uses. The default is always 2 planes (4 colours). MagicWB users may want a 3 bitplane screen for their 8 MWB colours, but most people will just use the normal 2 bitplanes for a shell! If you ask for a screenmode requester with the @{"MODEID" link MODEID} parameter, you can also set the screen depth from there. The actual colours on the screen themselves will be inherited from the default screen. @endnode @node FONT "FONT option" WB: FONT Shell: FONT/K This allows you to choose a fixed-width font for the screen. Just simply say the font name and the size, "XEN/9" or such. If you want to use an 8 point font, you don't even need the size, just write "XEN" or such. If you specify "" or "?" for the font, you will get an ASL font requester, from which you can choose a font and size. Shell windows normally only 'inherit' a fixed-width font from the screen they are on. There is no reason to forcibly prevent you, but ShellScr will warn you if you request a proportional font, and you will probably find that the shell does not use it, only the screen title. ShellScr is clever about picking a default font. If the default screen uses a fixed-width font, it will use that one. Otherwise, it will use the system default font, which is chosen with the Font preferences editor. @endnode @node AUTOSCROLL "AUTOSCROLL option" WB: AUTOSCROLL Shell: AUTOSCROLL/S Setting this option enables autoscroll for the screen. That means that if you drag the screen off the display, you can scroll it back onto the display just by moving the mouse. @endnode @node SHANGHAI "SHANGHAI option" WB: SHANGHAI Shell: SHANGHAI/S Before Workbench 2 arrived for the Amiga, a program had two options when opening a window. It could open on its own custom screen, or it could open on the Workbench screen. Now with Workbench 2, windows open on the default screen - but for compatibility, old programs still open on the Workbench screen. The Amiga has a special global option for public screens called "Shanghai mode". When this is enabled, old programs open on the default screen like their modern counterparts. Simply set this option to enable Shanghai mode. @endnode @node TITLE "TITLE option" WB: TITLE Shell: SCREENTITLE=TITLE This is the text that will go in the titlebar of the screen. This option is here, as the shell you open will not have a titlebar of it's own. The default text in the titlebar is 'AmigaShell'. To remove the titlebar altogether, see the @{"NOTITLE" link NOTITLE} option. @endnode @node NOTITLE "NOTITLE option" WB: NOTITLE Shell: NOTITLE=HIDETITLE/S This specifies that the screen should have no titlebar whatsoever, so you get the entire screen. @{"Window-size calculation" link sizing} takes this into account. Note that the normal CON: window looks very ugly with this option! It is best reserved for a handler like VNC: that really will use the full screen. @endnode @node CONSPEC "CONSPEC (WINDOW) option" WB: CONSPEC Shell: CONSPEC=WINDOW This is by far the most technical setting of ShellScr. You don't have to use this option if you don't want to! This is the specification of the console window to open on the public screen. It should contain two "%s" signs which will be replaced by ShellScr for certain values. The first "%s" will be changed to the coordinates and size of the window, in the format "l/t/w/h", eg "0/3/640/253" on a 640x256 screen. The second "%s" will be changed into the name of the public screen we are using. The window should be a backdrop borderless gadgetless window with no title. For example, the default is "CON:%s//BACKDROP/NOBORDER/ SCREEN%s". If you use the ViNCEd package, a good setting is the following: VNC:%s//SCREEN%s/BACKDROP/NOBORDER/NOCLOSE/NOSIZE/NODRAG/NODEPTH/ NOPROPX/NOPROPY/NOBUTTONS/NOICONIFY/SHELL/MENU You may want to read the information about @{"window-size calculation" link sizing}. @endnode @node COMMANDFILE "COMMANDFILE (FROM) option" WB: COMMANDFILE Shell: COMMANDFILE=FROM This basically allows you set a script to be run by ShellScr on startup. The shell normally runs S:Shell-Startup, but this option lets you set which script is run on startup. Just like NewShell's 'FROM' parameter (indeed, this is exactly how it is done). Apart from a few minor differences, this is also exactly what IconX does. So, many jolly japes available with this option, as demonstrated by the given example. @endnode @node STACKSIZE "STACKSIZE option" WB: STACKSIZE Shell: STACKSIZE=STACK/N Normally, the new shell inherits its stack size from ShellScr (by default - we will ignore the obvious 'Stack' command in the Amiga shell which you can put in your S:shell-startup to easily increase the stack size). So, to get a large stack in the shell, you have to give a large stack to ShellScr which only needs 1kb? Not so - you can now use this option, and give a small stack to ShellScr while at the same time giving a bigger stack to the shell. You specify the stack size of the new shell in bytes, which are rounded up to the nearest 4 bytes. The minimum size you can give the shell is a 1600 byte (1.5kb) stack, the maximum is limited only by available memory. The default stack size for the new shell is 4096 bytes (4kb). @endnode @node history "ShellScr history" 1.0: First release 1.1: Added options @{"PUBNAME" link PUBNAME}, @{"MODEID" link MODEID}, @{"DEPTH" link DEPTH}, @{"TITLE" link TITLE} and @{"CONSPEC" link CONSPEC}. Use System() instead of Execute(). Tidied up source a bit. 1.2: Made a few more checks on stuff. Added @{"NOTITLE" link NOTITLE} option. Better @{"windowsize calculation" link sizing} Now sets currentdir and paths properly from Workbench. 1.3: Now parses icon tooltypes. Now uses default screen's colours. Tidied up documentation. 1.4: Screenmode and font requesters. Added @{"FONT" link FONT} option. Added @{"COMMANDFILE" link COMMANDFILE} option. Fixed default conspec to act properly. Now explains errors a lot better, especially "can't open screen". Fixed args parsing. Basically, directories and iconless icons caused crashes/lockups/trashed mem/etc... not anymore. You can now make ShellScr resident. Popup 'Screen Closing' requester if ShellScr can't close its screen immediately. 1.4b: Attempted bugfixes. Certainly fixed args.m from causing Enforcer hits. Removed the false calls if asl.library _didn't_ open. Fixed screen and font parsing a little. 1.5: Added @{"STACKSIZE" link STACKSIZE}, @{"AUTOSCROLL" link AUTOSCROLL} and @{"SHANGHAI" link SHANGHAI} options. Set depth/autoscroll from the screenmode requester. Cancelling the screenmode requester now aborts running the program. 'Screen Closing' requester now has 'Cancel' option. Now sets itself as the default public screen on opening. Added 'real name' screenmode recognition. Removed the 'hangup' that occurs the NewShell command fails. Error message when NewShell command fails. Fixed bugs with font selection. Numerous tweaks, rehashes and things I have forgotton. @{" Future development " link future} @endnode @node future "Future prospects for ShellScr" Things I could do include: - Font specified in 'myfont.24' format as well as 'myfont/24' format. - Localization If you think 'Yeah! I want that!' about any of these, please tell me. If noone asks for them, I'll assume they're not too essential. If you think strongly so, I'll remove features you don't like, want or need. Good old scrsh used to be just over 1k, you know. (not forgetting 'bugridden and hardcoded' -Ed.) Any further suggestions from you are _also_ welcome. @{"Send them to me." link credits} @endnode @node sources "Source notes" The makefile is designed to only run from my machine, and it will not build ShellScr. As all compiled modules are there, this should not be a problem; just type 'ec opti ShellScr.e'. All modules and their sources are provided. These are all available from my archive on Aminet, 'dev/e/kyz.lha'. Basically, you can use any of the modules yourself whole or changed provided you give me a mention. The assembler modules make use of E globals, thanks to the include file generated by eglobs.e I don't free all strings and lists I create, I leave that to the startup code. It makes the output code smaller and source simpler, and almost make up for the memory wasted while the program is running. OK. I'll admit it. I was wrong about the scope of the Font pointer in the Screen structure. When the default screen we copied from closed, the pointer was lost and bye-bye font data. I now make a proper copy of the structure when copying it. I also now remember to _copy_ the name part from the ASL font requester, rather than take a pointer to it just before freeing it. Oops. Still - two less bugs, eh readers? @endnode @node sizing "Window-size calculation" The window size calculation for ShellScr is as follows: First, the width of the window is always the entire width of the screen. Now, if you are happy with the default CON: window, and do not specify an alternative @{"CONSPEC" link CONSPEC}, then the vertical height of the window will be height_of_the_screen - 3, due to the fact that CON: looks best with this setting, its unusable titlebar is covered by the screen titlebar. If you use a custom @{"CONSPEC" link CONSPEC}, ShellScr makes no such assumptions and uses height_of_the_screen - height_of_the_titlebar as the vertical size, if you use the @{"NOTITLE" link NOTITLE} option then there is no titlebar and you get the whole screen for the shell. @endnode @node glossary "Glossary of important terms" @{b}Display@{ub} The picture shown by your Amiga on your TV or monitor. @{b}Screen@{ub} A graphical area that is shown on the display. Screens can be dragged on and off the display, arranged in front of or behind one another. You can have as many screens open as you have the memory for. @{b}Workbench Screen@{ub} This is a fundamental screen of the Amiga. It is the first screen that the user sees when booting up, and usually remains the screen that applications use when they do not use their own custom screen. The Workbench Screen is a public screen, and from bootup is the default screen. @{b}Custom screen@{ub} This is a screen that an application creates for itself. No other application may (legally) open a window on it. @{b}Public screen@{ub} A screen that any application may visit. A public screen has a name (the Workbench's public name is 'Workbench') and applications can reference the screen by stating the exact name when they open their window. If they do not state a name, the screen they open on will be the default screen. @{b}Default screen@{ub} This is usually the Workbench screen, but this can be changed by applications, or by the user with appropriate software. Any public screen can become the default screen. The default screen is used for opening windows on when no other screen is specified by the application. There is an exception to this rule - for compatibility purposes only, old software will always open on the Workbench Screen. This compatibility can be switched off with @{"Shanghai mode" link SHANGHAI}. @{b}Stack@{ub} An area of memory that every application recieves to hold transient data. UNIX applications are notorious for using large amounts of stack. @endnode @node credits "Credits" ShellScr was adapted from the assembler program 'scrsh' by Kyzer/CSG. ShellScr was written by Kyzer/CSG in Amiga E 3.3a, based on the source scrsh.asm by Kyzer/CSG, the RKM source clonescreen.c, and the source to dospath.library by Stefan Becker. It no longer bears any resemblance to any of them. @{b}Best wishes to the following people:@{ub} (DE) Walter Haidinger and deJoker who asked for the @{"COMMANDFILE" link COMMANDFILE} option. (AU) Frank Bunton, who asked for better colours. (DE) Thomas Richter, for 'fixing' WBLoad, and for ViNCEd! (NL) Wouter van Oortmerssen, for the E language. (DE) Frank Wille, for PhxAss. (US) Free Software Foundation, for the GNU license and GNU make. @{b}Acknowledgements:@{ub} IconX is © Amiga International (it says here...) MultiCX is © Martin Berndt. PubChange is © Steve Koren. ReqTools and ReqPatch are © Nico François, Magnus Holmgren and Dave Jones. ToolManager is © Stefan Becker ToolsDaemon is © Nico François ViNCEd and VNC: are © Thomas Richter. XEN is © Martin Huttenloher @{b}Contact:@{ub} Kyzer/CSG, 49 Fairview Road, AB22 8ZG, Scotland. or email: kyzer@4u.net http://www.abdn.ac.uk/~u13sac/ @endnode