ASSEMBLING ISSUES WITH THE SOFTDISK PC VGA SHELL by Daniel Tobias This documentation file was last revised July 27, 1994, and is based on version 1.70 of SOFTDISK PC VGA Shell, using menu file format S8. REQUIRED FILES FOR SOFTDISK PC VGA SHELL: GO.EXE - Shell Starter Program (compiled from GO.PAS) VGASHELL.EXE - Main shell program (compiled from VGASHELL.PAS and various unit files, plus FastGraph) M-??????.SHL - Menu file in ASCII format. The syntax and command structure is described below. S-??????.SHL - Background screen file in .GIF format. See notes below about graphic specifications. I-??????.SHL - Icon graphics in .GIF format. These are the clickable icons and buttons as they are displayed on the main screen before the user clicks on one. They are stored on a full-screen GIF graphic in their proper screen positions. The on-screen text below the icons should also be here, with sufficient background around it to let it be grabbed in accordance with the coordinates in the menu file. The rest of the screen can be black (and should be for size efficiency). (Note: This file is optional, since icons can be placed on the main screen as described below.) A-??????.SHL - Animated icon graphics in .GIF format. These are the icons and buttons as they appear when they are clicked by the user, stored on a full-screen GIF graphic in their proper screen positions. (This file is optional, as animation can be disabled, as described below.) The question marks in the above filenames should be replaced with an issue identifier, like SD092. (Three digits in the issue number are used to carry the numbering system past #99 up through #999.) No other files are needed directly by the shell, but you will of course have specific program, text, and graphic files as part of the issue itself, referenced in the menu file. COMMAND LINE PARAMETERS: GO /V skips check for VGA adapter to fix incompatibility problem with certain monochrome VGA systems. GO /F skips fading and scrolling effects to save time. GO /NOMOUSE suppresses use of mouse. GO /NOEMS suppresses use of EMS memory. GO /NOXMS suppresses use of XMS memory. GO /PATH: Follow this with path of issue to run. GO /ISSUE: Follow this with identifier ("SD092") of issue to run, if you have multiple issues in the same directory. GO /MEM Undocumented parameter used in debugging; shows how much memory is available for program execution and for shell data storage. GRAPHIC FILE FORMAT: The graphic files, S-*.SHL, I-*.SHL, and A-*.SHL, are all GIF or PCX files in 16-color mode, 640 x 480, saved as a full-screen image suitable for VGA graphic mode #18. They should be saved with a consistent color palette within the palette limitations described below. The palette of the main screen file, S-*.SHL, is the one that is used for display purposes; the colors in the other .SHL files and any other graphics that are displayed in partial-screen mode need to be consistent, or they'll look funny. The MAINTYPE, ICONTYPE, and ANIMTYPE flags in the $DEFS section of the menu file should be used to set which file format (GIF or PCX) is used for the graphic files (default is GIF). For all except the MAINTYPE, "NONE" is an option, indicating that the file is not used at all. The main screen background is in S-*.SHL. This is a full-screen background onto which all other main-screen items are overlaid. The SDPC (or other) product logo should be present somewhere on this screen so it can be grabbed for use on the About box (see below in the menu file description for more on this). The animateable icons, etc., shouldn't be on this screen as they are taken from the two other graphic files, I-*.SHL and A-*.SHL. (Exception: If you use the ICONTYPE=NONE flag, the icons are assumed to be on the main screen, and if you use ANIMTYPE=NONE, no animation is done. Also, you can make exceptions for individual items using the "N", "NI", and "NA" flags as documented below.) The buttons/icons are in I-*.SHL, in the form that they are displayed on the main screen, and in their proper positions. See the menu file description below for information on how to tell the VGA Shell where to find and grab these buttons. Note that under shell file formats S7 and earlier, grabbed areas get rounded outward in the X-coordinate direction to a multiple of 8 pixels, to reach a byte boundary, so that if an icon starts or ends at a non-boundary pixel, there must be sufficient background surrounding it to allow seamless grabbing. The rest of the screen can be black. Effective with format S8, the left edge of grabbing is at the exact position given in the menu file, but the right edge is rounded up to make the total width equal a multiple of 8. This means that grabbed areas must still have a width equal to a multiple of 8, but need not begin on even multiples, which increases the flexibility. The old rounding method is still used on menu files of S7 or earlier for compatibility. The "animated" icons, as they display when you click on them, are in the A-*.SHL file, in the same format as the above icon file. COLOR PALETTES: In setting up graphics for the background and icon screens, follow these rules: All three graphic files should use the same palette settings. In general, we try to do the background using only colors 8 through 15 (and color 0 as black), leaving the lower-numbered colors free to change from month to month for the icons. It is not necessary that this scheme be followed, however. In all cases, the correct palette settings need to be placed in the S-*.SHL file each time. Since the graphics are in 16-color mode, you have palettes from 0 through 15 to set. In the obsolete file format S1, some of these are expected to be particular colors or are used for particular purposes. These remain the defaults in formats S2 and up, but may be overridden as described below. 0: Expected to be black. 1-5: Free to vary at will. 6: Shouldn't be used in icons, since it is used in opening sequence to show "Loading Data" dialog box while other colors are blanked. 7: Free to vary at will. 8: Color used in title bar of text or graphics; hence, it should be some dark color that is attractive in this use. It is dark purple on SDPC. 9: Free to vary at will. 10: Expected to be dark gray. 11: Expected to be light gray. 12: Color used to write "End of text" at the end of a text file. It should be some dark color that shows up against a white background. 13: Free to vary at will. 14: Free to vary at will. 15: Expected to be white. In addition, some parts of the VGA Shell change colors by "X-Or"-ing other colors, e.g., in showing the highlight bar on the pull-down menus, which results in other color palettes being used in particular places; be sure to check out how the shell functions in any changed palette set to see if unreadable color combinations result. The above colors were hardcoded in the S1 format, but in the S2 format, there is more variability permitted. In this format, the shell will automatically find the best matches, within the available palettes, for black, white, light gray, and dark gray, so these may be in any palette numbers. Also, the $DEFS section of the menu file (explained below) lets you change the defaults for color settings such as the number of the palette that is reserved for the "Loading" box, the color to make the title bar and "End Of Text" line, and the color to X-Or with the menus to show the currently highlighted item. This reduces the difficulty of setting up graphics for this shell, as you can use whatever palettes are convenient and configure your menu accordingly. Black (0) and white (15) are hard-coded and can't be changed. MENU FILE FORMAT: The main menu is in the ASCII-format file M-*.SHL. This file contains all the information needed to set up and run the items on a particular issue. A sample menu shell file is included in this source archive, and it is a good idea to look at it as you're reading this documentation, as it will make more sense if you see a sample of what the syntax is supposed to be. M-*.SHL is a standard ASCII file, with lines separated by CR and LF (characters 13 and 10). A logical line that extends across multiple physical lines can be "strung together" by placing a tilde (~) at the end of all but the last physical line of the logical line. Blank lines are ignored, but a line containing only a single period (.) will be parsed into a blank line, for times when you really want to include one. All characters to the right of an upright bar (|) are regarded as comments, and are ignored. The file contains the following information: (First, the basic information about the issue.) Line 1: Menu file version identifier (currently "S8") See description of versions in the README file. Line 2: Publication name ("Softdisk PC") Line 3: Issue number/name ("96") (may be a number or string value) Line 4: Issue version number ("1.00" for first release, higher numbers for remasters, etc.) Line 5: Issue revision number ("1" and up to distinguish versions created for internal testing purposes) (Next, several sub-sections, all starting with a "$" command line.) $DEFS = Some parameter definitions, such as colors. $ICON = Indicates the start of the Icon section. See below for the syntax of entries within this section. $MENU = Indicates the start of the Menu section. See below for the syntax of entries within this section. $ABOUT = Indicates the start of the About section. See below for the format of this section. DEFINITION SECTION The $DEFS section lets you set up some variable items. Use the syntax of "ITEM=value", with each definition on a separate line. (Supported only in menu file format S2 and later.) In menu formats S3 and later, you can also use negative numbers in color attribute settings to represent the color, in the current palette, that is closest to the default DOS color represented by the absolute value of the number. For instance, -4 represents red, or the closest equivalent. ANIMTYPE = Type of A-??????.SHL file: GIF, PCX, or NONE. (Default = GIF) BEGINABOUT: Takes no value. The presence of a "BEGINABOUT" line in the $DEFS section for menu versions S7 and up enables the automatic display of the About box on startup, as was the norm in versions up to S6, but which is otherwise disabled in S7 and up. If the "B" command is used in an icon or menu item, that item will be executed after the about box is shown, unless the user selects a different menu item from the about box. BOLDCOLOR = Palette number to use for highlighted text, between curly brackets. (Default = 8) [Menu versions S3 and up.] ENDCOLOR = Palette number, in your custom palette, to use for the "End of Text" message at the end of a text file. (Default = 12) FREECOLOR = Set the palette number that is left unused in the icon screens so that it is available for use in putting up the "Loading" box. This palette may be used on the main background screen. (Default = 6) HDRCOLOR = Palette number, in your custom palette, to use for title bars in text and graphic windows, etc. (Default = 8) ICONTYPE = Type of the I-??????.SHL file: GIF, PCX, or NONE. (Default = GIF) MAINTYPE = Type of the S-??????.SHL file: GIF or PCX. (Default = GIF) MKTSRC = Set the "marketing source code" displayable in any text file or in the about box as ~MS. The external file MKTSRC.SHL can alternately be used to hold this string, if it is needed to be automatically generatable in creating variant marketing versions of an issue. MSGCOLOR = Set the color that the "Loading" box is presented in; this is in the standard DOS palettes, as the custom palettes have not yet been loaded at this point. These color numbers are the same as in text mode. (Default = 11; light cyan.) STARTDELAY The number of seconds to delay before the "About" box times out when you start running an issue. (Default = 10) [Menu versions S3 and up.] TEXTCOLOR Palette number to use for regular text in text viewer and About box. (Default = 0) [Menu versions S3 and up.] TOOLCOLOR Color to use for titles displayed under a toolbox item when the mouse is moved there. (Default = 0 = black.) [Menu versions S8 and up.] XORCOLOR Number to exclusive-or with the screen colors when highlighting items on a pull-down menu. (Default = 15) ICON / MENU ENTRY SYNTAX The Icon and Menu sections have entries of pretty much the same syntax, with minor variations. An entry line is as follows, contained on one logical line, which may be spread over multiple physical lines using the "~" syntax as noted above. Name [,command [,command...]] There is always a Name field, followed optionally by one or more commands separated from one another and from the name field by commas. Because the comma is a separator, none of the fields may contain a comma (e.g., as part of the name). Leading and trailing spaces in a field are stripped in parsing, but there may be spaces elsewhere within a field, and any other printable character may be used in a field (subject to the below-noted command syntax). The Name field is used wherever the name of an item must be displayed within the VGA Shell, with the exception of the text below an icon, which is grabbed as a separate graphic (actually, an 'icon' without any action commands, which is placed on the screen but is not clickable). The name of an item is used as the header when displaying its text file or graphic (where applicable), as the menu item name in pull-down menus, and in the Copy Item list. If the name is to be used in a pull-down menu (this applies to all items in the Menu section, and to all items in the Icon section that include an "Optional Readable File" to be placed into the pull-down menus via the ~OPT macro), then one letter in its name must be surrounded by underscore characters (_) as the selectable letter, which must be unique within whatever menu it is to be placed in. A command is of the syntax: CMD[:arguments] where CMD is the command, usually one or two letters, and "arguments" is whatever follows the command if required, such as a filename or other argument. The command fields tell the VGA Shell what to do with a particular item, including what icon graphics to use, and what to do when the item is selected. In the Icon section, each entry must have X and Y coordinates to indicate where the icon is on the screen. In the Menu section, the entries must be grouped into top-level menus (which have no "action" command) and menu entries (following each top-level menu entry) which contain action commands. (See below the full list of commands for information on which are "action commands".) Within the menu section, a line with only a single dot (.) represents a "separator" line within a menu. A menu item can also have X and Y coordinates if it is an icon as well as a menu (e.g., for toolbox items). The commands are: A = About Box. Causes the "About" box to be displayed when selected. Takes no arguments. B = Beginning. Causes this icon or menu item to be executed on the startup of the issue. Use this if you'd like a text file or graphic to be viewed or a program run right off the bat as the user starts the issue. It will be run just as if the user selected it from the menu or icon, but only on startup with "GO", not on return to the shell from another program. Use the "B" command on at most one item. If it's not used at all, no startup item will be executed. If the BEGINABOUT configuration option is used, the about box will be shown before the beginning item is executed. (Added with menu version S7.) C = Copy. This is how the list of files to copy as part of an item is stored, and also is the "action command" to make the copy routine accessible from a menu. The argument to this command is a list of files to be copied as part of the current item, which may include wildcards and subdirectory references. Separate the files in the list with spaces. Sample copy list: C:STUFF.EXE STUFF.DAT STUFF\*.* In file version S9 or higher, an *.* filespec (as above) will cause any subdirectories of the given directory to also be copied. In S1 through S8, the subdirectories aren't copied unless explicitly named. A parameterless "C" command can be used to provide an entry point to the Copy command without actually creating a particular item to be copied; this is used in the pull-down menu item for "Copy Items", for instance. Items with Read or View commands and also a Copy command will have a "Copy" button on the read or view screen. Within a copy list, you can use the ~ALL macro to encompass all files in all other copy lists plus the currently-listed ones; this should be done only once, in the topmost copy list, generally named "Entire Issue", which copies everything in the issue. For this item, include ~ALL plus all files not included in another copy list but which are part of the issue, such as the shell files and text files. ~ALL should be thought of as a macro that expands into a full list of the files contained in all copy lists other than the current one. Using more than one ~ALL on the same issue can have unpredictable results due to the infinite regress it creates on expansion. Another note on subdirectory use: If the copy list for an item contains files that are all in one directory, then the files will be copied directly into the destination directory specified by the user, without creating another layer of directories below it. However, if the copy list includes several different directories, they will all be created as separate directories while copying. (This counts only subdirectories explicitly listed, not ones that are copied automatically as part of a wildcard reference, in file formats S9 and up which support this.) Thus, for instance, if you have each program on an issue in a separate directory, with copy lists like C:PROG1\*.*, then when a user copies one program it will go straight into his destination directory, but if he selects the "Copy All" item, then all separate program directories will be created in order to duplicate the entire issue in its original form. In the copy list, you can use a list of copyable files in an external file by using the syntax ">filename", where "filename" is replaced by whatever the name of the file is that you are using in this manner. This file is in ASCII format, and contains a list of filenames separated by spaces or carriage returns / linefeeds. This is a way around the limitation of 255 characters maximum in the entire icon or menu command logical line (including the copy list). An external copy list defined in this manner can be as long as you need it; each physical line (between carriage returns) is limited to 255 characters, but you can have multiple lines. The ">filename" entries may be combined with normal file entries: "C:TEST.TXT >MORE.FIL TEST2.TXT" will copy TEST.TXT, all files listed in MORE.FIL, then TEST2.TXT. External copy list files may include comments preceded by the "|" character, just like in the menu file. You can specify a different default directory for a particular menu item by including the directory name, beginning with a backward slash (\), in the copy list. Up to 15 different copy directories can be included on an entire issue, including the normal default copy directory based on the issue menu name. Example: "C:\JUNK STUFF.EXE STUFF.DAT" copies this item to the directory "\JUNK". D = Directory specification. This command takes as its argument the name of a directory (relative to the main issue directory) that you want the shell to change to before running the executable program. This does not affect the directory that Read and View files for this item are expected to be in; you must include specific directory references in these and in the Copy command where needed. Example: D:STUFF causes the STUFF directory (within the main issue directory, whether on hard or floppy disk) to be changed to before the program is run. On exit, the system is returned to the main issue directory before the shell is restarted. This works like the CD command in DOS. E = Execute. The argument to this command is the name of an EXE, COM, or BAT file to be run. Batch files will be run by shelling to a new copy of COMMAND.COM if you are using the GO.EXE launcher to load programs (but see the appendix for a work-around in the rare cases where it is necessary to run directly from a batch file without the extra memory overhead of an additional COMMAND.COM shell). If a "Read" or "View" command is included in the same item, the readable or viewable file will be presented first, with an on-screen "Run" button to invoke the Execute item. (Note: Only part-screen View files will have a Run button; full- screen graphics don't have such an option. See below for a discussion of the precedence of action commands.) EW = Execute Windows program. This is a variant of the E command, which works the same except that the program will be launched by running WIN.COM with the desired program name as a parameter. (If you're already in Windows, or if WIN.COM is not anywhere in your DOS PATH, then a dialog box will be shown indicating that it is unable to run the program.) F = Extra file list to be copied during an Copy Entire Issue to A: or B:. This list allows you to copy the shell files to the second and third floppy disks that the issue will be spanned onto by the Copy Issue to A: or B:. G = Extra file list to be copied with a program during a single copy. This list allows you to specify an extra file that you want copied with a single program, but you do not want to include it on the main list of copy files that will be copied with the entire issue. This allows you to copy a new vgashell.exe with some new shell files without having the copy entire issue copying the vgashell.exe file twice. I = Disk Identifier. Used to handle an issue split across multiple disks which have to be swapped. This feature has not been extensively tested, since the present SDPC is available only on high-density disks and hence needs no swapping. However, the feature was added in case it proved necessary. The way it works is to tag each item (readable, runnable, viewable, etc.) with an identifier indicating which disk it is on, of the form "I:1" for disk #1, "I:2" for disk #2, or alternatively, unique names of some other sort: "I:Program Disk", "I:Data Disk". All parts of a given item are expected to be on the same disk. The shell itself is expected to be on the first disk (but can optionally be placed on the other disks too to save swapping). The name or number of the primary disk (if other than "1") is set by the first "I" command encountered in the menu, usually on the "Entire Issue" / "About Icon" item (see discussion of this below). If the file that is needed to run, read, or view is present on the current disk, no swap request will be made, so it is still possible to install an entire issue on one drive and run it there, even if it comes originally on multiple disks with swapping required. K = Keyboard Equivalent. Use this to designate a key that is equivalent in function to the given icon, button, or menu item. You can use as the argument any printable character, or F1 through F10. There's no need to use a K command for the primary keys in the menu area, which are designated by the "underscored" character in the name. However, you can add alternate keys for a menu item through the K command, and can create keyboard equivalents for the icons in this way too. A keyboard equivalent to a top-level menu causes that menu to be pulled up, while a keyboard equivalent to a menu item or icon causes the relevant command to be executed immediately. Icon hotkeys will work in uppercase, lowercase, or with the ALT key (though the latter is disabled if it conflicts with the ALT combination for a menu). L = Logo. Use this only once in the issue menu file, usually in the "Entire Issue" / "About Icon" item (discussed below). It indicates that the X and Y coordinate range in this item refers to the product logo to be grabbed from the main background screen and used on the About screen. M = Memory requirement. Syntax: "M:nnnnnn", where nnnnnn represents the number of bytes of free conventional memory that is required to run a program. If insufficient memory is available, the user will get a dialog box. This flag should be used in the menu entry for an executable item, and applies only to the particular program in that menu entry. Hence, you can have different memory requirements for each runnable item in the issue. N = Non-Animated. Use this for clickable screen items that don't have a graphic in the Icon or Animation files to be placed on the screen, but rather are directly on the main background screen. This is used (in conjunction with the L command) for the main product logo, to make it be clickable to see the About screen, but without an animation on clicking it. It can be used for other items on the main screen if you see fit. In menu versions S7 and above, there are a couple of additional "non-animating" or "non-icon" options: NI causes an icon to be loaded and displayed from the icon screen for this item, but no animation is used; it just stays in place when you click on it. NA causes no icon to be loaded or displayed, but an animation is loaded from the animation screen and used when you click on this item. Do not use more than one "N" command in a single item; combining NI and NA, to have no animation or icon, should be done with a single "N" instead of "NA,NI", as the variables won't be set properly when multiple commands are used. O = Optional Read File. Its argument is the name of an ASCII-format or compressed text file. (See discussion of text file formats below.) This file is not automatically viewed when the item is selected (unless there is no other action command for this item), but it is added to a list of available readable files which can be placed into the menu structure through the use of the ~OPT macro somewhere in the menu section. The ~OPT macro, used on a line by itself, causes all Optional Read File items (whether found before or after the ~OPT macro is encountered) to be added as menu items which, when selected, cause the text files to be viewed (with a "Run" or "View" button as appropriate depending on the other action commands associated with the items). The names of these menu items are taken from the name field in each original item, and must have unique underscored characters as their menu selectors. P = Parameters. The argument specifies the parameters to be passed to the Execute file when it is run. If there is no P command, then the default parameter "/ODMS" (indicating that a program is being run from the shell) is sent, along with all parameters typed by the user when he typed "GO". If these parameters will "choke" a program, you can suppress them by giving a "P:" command with nothing following it. (Note: The colon is still necessary in this case.) If you wish to substitute other parameters instead of the default ones, use P: followed by your desired parameters. If you wish to send parameters of your own in addition to the default ones, include the macro "%u" somewhere within the parameter list, which causes the default and user- typed parameters to be inserted at that point. Q = Quit. Causes the quit command to be invoked, which asks the user if he really wants to quit, then exits the shell if the "Yes" button is selected. R = Read. Causes an ASCII or compressed text file (specified as the argument) to be displayed. Unlike the Optional Read, this is done when the icon or item is selected, and should be used for "urgent" instructions that the user should see before attempting to run the program. If there is a runnable or viewable item, then a "Run" or "View" button is shown. If there is a copy list, then a "Copy" button is shown. There is always a "Print" button, which lets the text be printed. RX:nnn-nnn and RY:nnn-nnn set the coordinates of the text display area. The default is RX:132-591, RY:150-390. Be sure to allow sufficient space outside this window for the frame that is drawn around it, and the buttons beneath it. S = System requirements. (Shell version 1.20 and later.) Requires user to meet certain system requirements to run the current program; running will be disallowed with a dialog box if the requirements are not met. Syntax: "S:ltrs", where "ltrs" are one or more letters setting a system requirement. Currently supported requirement letters: M = Requires mouse. D = Requires "straight DOS"; won't work if you're in Windows or the DOS 5.0 task swapper. T = Toolbar item. If this is present in an item, it is considered to be part of the toolbar, and when the mouse is in its area (even if not clicked), its title will display below it. This is operative only if the X and Y parameters are used to set an icon/button area for this item. This "T" parameter can be used in both the $ICON and $MENU section, so toolbar items may be also on the pulldown menus or not as desired. [S8 or later.] To change the position of the toolbar title, you can append numbers in the form T:x:y or T:y. (If there is just one number, it is used as the y coordinate; two are the x and y.) These numbers are relative to the lower left corner of the icon, and represent the lower left corner of the text to be displayed. Default is X=0, Y=20. (Use file version S9 or higher if using Y coordinates, as this was not supported earlier.) V = View. There are actually several commands in this "family": VG = View GIF file. VP = View PCX file. VW = View Windows BMP file. (Note that this is not VB, which has already been used for a different command.) VS = View graphic script file (see discussion below). The above take as their parameter the name of the file to view. Only one of the above should be used in any item; you can't have multiple view files as part of one item. If used without any of the other "V" commands, these will cause the given file to be displayed as a full-screen graphic (starting in the upper left corner of the screen), using the file's own internal color palettes. On a keypress or mouse click, control returns to the main shell screen. It is the issue assembler's own responsibility to include a prompt for a keypress somewhere on the full-screen graphic, as no on-screen prompting is done. VM = Set graphic mode Used in conjunction with VG or VP, this causes the mode to be set to the mode number given as its argument before the full- screen graphic is displayed. For instance, "VM:23" sets 256- color, 320 x 480 mode, while "VM:4" sets 4-color, 320 x 200 CGA mode. The mode is returned to the standard mode (#18) after you are done viewing the graphic and are returning to the main shell screen. All standard CGA, EGA, and VGA modes will work, but the .GIF or .PCX graphic you are viewing must be set up properly for the given mode, or this may produce strange results. SVGA modes are not presently supported, but if VGASHELL.EXE is recompiled with the SVGA compiler variable defined at the top of VGASHELL.PAS, then these modes would become available (at a slight cost of program size to encompass the required drivers). If you attempt to use an unsupported graphic mode, or one not present on the user's system (e.g., Tandy or Hercules modes), then a dialog box will be shown when the user tries to view the graphic, saying that it is in an unsupported mode. VX = Set X coordinate range for part-screen graphic VY = Set Y coordinate range for part-screen graphic The above commands are used to display a graphic as a part- screen window instead of a full screen. You must use both together. Each takes as its argument a range like "100-200", showing the low and high coordinate values which together define a rectangular area on the screen in which to place the graphic. This should be the exact size of the actual image stored in the graphic file you are viewing. In the graphic file itself, the graphic should be stored starting at the upper-left corner of the screen and extending only the length and width of the image itself (not padded or centered to fill the screen). It will be displayed at the designated place on the screen, and surrounded by a border similar to that surrounding a text file being viewed by the Read command. There will be buttons below the image for "Run" and "Copy" if these features are present in the item. Part-screen graphics are displayed in the color palette settings used in the main screen (but see the VB command for a slight optional modification). Graphics designed for different palettes or modes may not look good at all; it is necessary to specially edit graphics for this use. Also, the VM (set mode) command has no effect on part-screen graphics that use the VX and VY commands. VB = View Black-and-white This is a "modification" command used in conjunction with the VX and VY commands when displaying black-and-white images stored as two-color graphics. It causes color palette 1 to be set to white, no matter what it is in the normal settings. This is done to make the black-and-white graphic be shown as black-and-white, instead of black-and-green or whatever color 1 may be normally set to. This has as a side effect the alteration of the colors of any icons that use this color number, but the icons are often covered up by the graphic being viewed anyway. The palette is restored to its original value when the user returns to the main screen. The VB command has no effect on full-screen graphics. Examples of graphic commands: VG:JIFFY.GIF, VX:200-300, VY:250-350, VB views JIFFY.GIF as a part-screen GIF graphic in the rectangle stretching from (200,250) to (300,350), as a two-color black and white graphic with color #1 = white. VP:GRAPH.PCX, VM:23 views GRAPH.PCX in 256-color 320x480 mode. X = X Coordinate. This command specifies the range of X coordinates comprising the icon representing the current item. Use this only for icons; menus have their own automatically-determined screen positions. The range is expressed in the same form as the GX and GY commands above: "X:200-300" to specify 200 through 300 inclusive. X coordinates range from 0 through 639. NOTE: In menu formats S7 and earlier, icons are "grabbed" from the Icon and Animation graphic files only on byte boundaries, i.e., where the X coordinate is a multiple of 8. You can specify any number for the X coordinate, and the "sensitive" screen area for clicking will be determined precisely by what number is used here, but the actual grabbed graphic will be "rounded outward" to the nearest multiple of 8 to the left of the starting X value, and to a multiple of 8 minus one to the right. Thus, the Icon and Animation graphic files should have sufficient background surrounding the icons to allow them to be placed seamlessly on the main screen. In S8 and later menus, the left edge of grabbing is exact whether it is on a byte boundary or not, but the width of the grabbed icon must be a multiple of 8, so it will be rounded up if necessary. Also note that the X and Y coordinate ranges are used for several different purposes: to find and grab the appropriate graphics on the Icon and Animation screens, to place them at the same location on the main screen, and to indicate what areas of the screen are clickable. In certain cases, not all of these purposes are applicable to a particular item; if the N command is used to designate a non-animated item, the location specifies only a screen location for clicking (and for logo grabbing if the L command is used), but is not grabbed from the Icon or Animation screens. On the other hand, if no action commands are specified on an item in the Icon section, then its associated graphics are grabbed and placed from the Icon screen, but they are not clickable and have no animation with them; this is how to place the text below the icons, or other screen items from the Icon screen that don't represent clickable items. Y = Y Coordinate. Specifies the range of Y coordinates comprising the current icon or item, in the same syntax as the X command above. Y coordinates are not "rounded" to byte boundaries, and hence represent the actual limits of the graphic that is grabbed and placed. Run the shell with the /RECT parameter to show rectangles surrounding all items. This is a diagnostic to show you what coordinates are being used. "ENTIRE ISSUE" / "ABOUT" ITEM: There is one special item present in the Icons section that serves various multiple purposes. It is the first item in the section, and it looks something like: Entire Issue, X:12-227, Y:24-119, A, L, N, ~ C:GO.EXE VGASHELL.EXE ?-SD083.SHL JONATHAN.GIF 83TOON.GIF ~ QUESTION.TXT NEWUSER.TXT USRGUIDE.TXT WARRANTY.TXT ~ CRYPTO.EXE SD83.CSL 83*.TXT ~ALL Some of the things this item does can be figured out from its commands. The N command indicates that it is non-animating, and hence is present on the background screen, not the Icon or Animation files. The L command indicates that the X and Y coordinates represent the location of the product logo, which is grabbed to be used on the About screen. The A command means that if the user clicks on this logo, this will bring up the About screen. The remaining items are the name ("Entire Issue") and the copy list. This is simply the copy-file list for the whole issue, which has been placed here to put it at the top of the list of things that are copyable. Note the ~ALL macro, which tells the shell program to copy all other copyable files in addition to the ones listed here. The reason the copy command does not get executed when the user clicks on the product logo is that the About command takes precedence (see command precedence below). ACTION COMMANDS AND PRECEDENCE: The following commands are "action commands", and at least one should be present in all selectable items and menu items. An icon without an action command is treated as a non-clickable graphic, and a menu item without an action command is treated as a top-line pull-down menu, having as its items the menu items below until the next actionless menu line is reached. The precedence of action commands is in the order they are listed here. The command that is earliest in this list is the one that will be executed when the user selects the item. As noted, some of these commands make buttons available that let the user go on to another associated command. Where no such buttons exist, some combinations of commands may cause one or more of them to be unreachable; for instance, if the About command is present on an item, it will prevent any other action commands in that item from being executed, since the About box has no buttons to reach other commands. 1) About (A). 2) Read (R). (Has buttons for View or Execute (run), and Copy) 3) View (V). (Has buttons for Execute (run) and Copy) 4) Execute (E). 5) Quit (Q). 6) Optional Read (O). (Has buttons for View or Execute, and Copy) 7) Copy (C). ABOUT SECTION SYNTAX After the Icon and Menu sections of the menu file comes the About section, which contains the text for the About box. This text is in straight ASCII format, with some special commands. There are three sections, corresponding to the Info, Credits, and About text in the About section, respectively. In the menu file, they are headed with lines containing "`1", "`2", and "`3" respectively, where the first character is a "backwards apostrophe", found at the upper left of most keyboards. Within each section, the text is in a series of ASCII lines, each one of a length that will fit in the About box (it's proportionally spaced, so you'll have to experiment to see what will fit). Lines are centered automatically. To get a blank line, use a single period (.) on a line by itself, as blank lines are ignored in parsing. If you wish to view an external text file in place of an About box section's embedded text, use ">filename" on the line below the "`" header line. This file will be viewed using the text viewer, with a scroll bar, etc., just like a normal text file for a Read option, except in a different section of the screen in order to fit in the About box. To embed version information, use the following macros: ~IN = Show issue name (title and issue number) ~IV = Show issue version number ~IR = Show issue revision number (internal rev.) ~SN = Show name of shell program (Softdisk PC VGA Shell) ~SV = Show version of shell program ~SR = Show revision (internal) of shell program Effective with menu version S3, these commands work in text files as well. TEXT FILE FORMAT Text files displayed by the Read and Optional Read commands should be standard ASCII files, or compressed files using our internal TEXTCOMP utility. (See TEXTCOMP.DOC.) They should, preferably, have no carriage returns or linefeeds except at the end of a paragraph, to allow word-wrapping to be done where needed. If line breaks are used, the lines must be short enough to fit in the screen window for text viewing, 57 characters or less. Lines beginning with "^C" (a caret character followed by C) are centered. Other commands supported in menu version S3 and later: {...} Text within curly brackets is shown in a "highlighted" color. (See menu definition changes below to find out how to set which color is used for this purpose.) Brackets must always be in matched pairs; mismatched brackets can result in unpredictable effects in the text viewer. _..._ Items within a pair of underscores are underlined. Like brackets, these should be in pairs. | The Upright Bar character is translated into an Underscore, to allow underscores to be added without triggering underline mode, e.g., when you want a whole row of them like in an order form. This works only in text files for the text viewer, not in the menu file, in which the upright bar is already used as a comment character. ^Tnn ^Bnn Set the Text and Bold colors, respectively, to the number given in place of "nn", like "^T12". Works just like the TEXTCOLOR and BOLDCOLOR definition flags defined below, but sets the given definitions only for the current text file. This lets you have different text colors for different documents. You can only have one ^T command and one ^B command in any single file, and they should be at the top of the file, before any actual text lines. These commands should each be on separate lines. ^RX:nnn-nnn ^RY:nnn-nnn Redefine the text display area. You need to do this if you are going to display graphics, since you need to leave an area within the original text window clear. These commands should be used before the first viewable text line in a file, and the coordinate ranges should be entirely within the original text display box as set by the menu RX: and RY: commands (or the default if no menu commands are used to redefine the size). ^VP:xxx,yyy,filename ^VG:xxx,yyy,filename ^VW:xxx,yyy,filename View a PCX, GIF, or Windows BMP file (respectively) at the given coordinates, representing the upper left corner of the graphic. The coordinates should be within the text viewer border, but outside the area you have redefined the text to scroll within. Be sure the graphic itself is sized to fit within the area you chose. The graphic will be displayed whenever the text is scrolled to the point in the file where this command is placed. If you want a graphic to show throughout the entire document, put the command at the top of the file; if you want to change graphics several times as the text is read, put the different graphics at the appropriate places. Graphics will not automatically be un-plotted when the next graphic comes up, so be sure they are sized to entirely overwrite their predecessors if you do not want several graphics on screen at once. When using menu versions S5 and up, the ^V commands cause graphics to display only when scrolling forward, while the ^W command is used to display graphics when scrolling backward, to ensure that a graphic is displayed when a particular block of text is reached from either direction. With S4 or earlier, the ^V commands are parsed both forward and backward. ^VC:x1,y1,x2,y2 Clear the area of the screen from upper-left corner (x1,y1) to lower-right corner (x2,y2) to white. As with the other ^V commands, it is executed only when scrolling forward if the menu version is S5 or above. ^VC was not supported in shell versions prior to 1.40, so it shouldn't be used with menu versions prior to S5. ^W_____________ The ^W commands are identical in syntax to the ^V commands, but work only when scrolling upward. You should use a ^V command at the top of a block of text you'd like a particular graphic to display with, and a ^W command at the bottom of the block, so that the appropriate graphic is shown when the user scrolls to the text block, either forward or backward. (Not supported in shell versions prior to 1.40, so shouldn't be used with menu versions prior to S5.) ^P- ^P+ These commands, which should be on lines by themselves, designate the start and end of a block of text which is not sent to the printer when the user prints the document. ^P= Disables the printer function altogether in a text file. This should be at the beginning of the file, before the first printable line. ^S- ^S+ These commands designate the start and end of a block of text that is not displayed on the screen, but is printed when the user selects the print feature. A block of text that's within a ^P- and a ^S- block simultaneously won't be viewed or printed, and is effectively a comment for internal use (though the user can see it if he/she uses an ASCII file viewer or the DOS TYPE command). NOTE: Like the brackets and underscores, these commands must be used in matched pairs, with the "-" command at the start of the text block and the "+" command at the end. Even if a block of text is at the end of the file, you must still terminate it by turning off the current unprintable, unviewable, underscored, or highlighted status. This is necessary because when the "End" key is pressed, the text viewer jumps to the end of the document and goes backward from there, and all special modes are assumed to be in their default position at the end of the file as they are at the beginning. ^P (on a line by itself) forces a page break on the printer. There is no effect on screen display. ^M:ll-rr sets the left and right margins for printouts. This has no effect on screen output. You can redefine margins at any point in a document, to allow special margins for tables, figures, order forms, etc. >file The ">" sign, followed by a filename (on a line by itself) will cause the indicated file to be inserted into the text at the current point. NOTE: At present, this only works in a text segment that is printed but not displayed on the screen (^P+ and ^S-). In all other positions, a ">" line is just treated as a normal "literal". When using lines beginning with ">" as literals, you can precede the ">" with a "~" to be sure that it won't be interpreted as a filename reference. ~ The "tilde" can be used to precede special characters you wish to use as normal "literals". For instance, if you want to use a curly bracket in your text, use "~{". A tilde can be inserted with "~~", but don't follow this immediately with a special character that is part of a command sequence, because command characters immediately following tildes are ignored in the parsing. SCRIPTED GRAPHIC FILES You can display multiple graphics, and/or graphics with text prompts on-screen, using a new "scripted" graphic display option. Use the menu command "VS:filename" in contexts where "VP:", "VG:", or "VB:" would be appropriate, but the filename here refers to a script file rather than a graphic file. The script file is a normal ASCII file containing one or more lines of the following commands (each taking up a full line): ^V?:xxx,yyy,filename where ? is either P, G, or W to represent the graphic format; this causes a graphic to be displayed with the given coordinates of its upper left corner. ^L:xxx,yyy,string ^C:xxx,yyy,string ^R:xxx,yyy,string Display a text string, left-justified, centered, or right-justified, respectively, at the given x and y coordinates. "string" represents any ASCII text line, which may include the underline (_) or bold({}) operators if desired. ^T:nnn ^B:nnn Set the text and bold attributes respectively. Use positive numbers to set a number in the current palettes (as determined by the last graphic displayed), or negative numbers to find the closest current match to the DOS default color -n. ^P Pause the display at this point, until a keypress or mouse click. After this, the screen is cleared and the script continues. You can use this to set up multi-page slide shows. Scripted graphics may be used in both part-screen and full- screen graphic displays (e.g., with the "VX:" and "VY:" menu commands or without), but if it is a part-screen display, you should not use the ^P command, as it causes the entire screen to clear. Also, in full-screen displays, the palette settings will be changed to that of the last graphic loaded on each screen, while part-screen displays remain in the palette settings of the main screen. One more feature: If you have several graphic script files on an issue, you may combine them (to save disk space, since these files are likely to be small, but each file takes up a full kilobyte on disk) as follows: Put all commands from all scripts into one file, and precede each set of commands with a header using the "reverse-apostrophe" (`) followed by a number, in ascending order. Then, each place in the menu file where a graphic script is referred to, follow the filename with ">n", where n is the number of the portion of the script you are using. Example: In GRAPHICS.SCR: `1 ^VP:10,10,file1.pcx ^VG:200,200,file2.gif `2 ^VP:0,0,newgfx.pcx ^C:320,240,Press key or click mouse to continue. In M-SD087.SHL: Silly Item 1, VS:GRAPHICS.SCR>1, R:GFX1INFO.TXT Silly Item 2, VS:GRAPHICS.SCR>2, R:GFX2INFO.TXT APPENDIX: RUNNING FROM A BATCH FILE While this shell program is designed to be launched from GO.EXE, which also launches all other programs run from the shell, there are occasions in which you must run something that requires a batch file. Since batch files can't be launched directly from GO.EXE, it is necessary in these cases to shell out to a new COMMAND.COM; this is what GO.EXE does (effective with v 1.30). However, this takes more memory than just running it straight from DOS, so sometimes you might wish to run the entire issue from a GO.BAT batch file which contains all necessary batch commands. (This was the method used on the old text-based ODM menu system, and the PC BusinessDisk and SDPC CGA system as well.) This method does away with GO.EXE and does everything through batch files. VGASHELL.EXE will work this way, since it indicates what to run by exiting with errorlevels, which works as well from a batch file as from a directly-run program. However, you need to give the proper parameters to VGASHELL on launching it initially and on returning to it. The following is a sample GO.BAT file for this purpose: @echo off :start goto startb :starta vgashell /ODMS /RET:1 %1 %2 %3 %4 %5 %6 %7 %8 %9 goto startc :startb vgashell /ODMS %1 %2 %3 %4 %5 %6 %7 %8 %9 :startc if errorlevel 3 goto launch3 if errorlevel 2 goto launch2 if errorlevel 1 goto launch1 goto nolaunch :launch3 rem Put commands to launch program #3 here. goto starta :launch2 rem Put commands to launch program #2 here. goto starta :launch1 rem Put commands to launch program #1 here. goto starta :nolaunch If you use a directory-changing command in the menu file (the D command) or in the batch file (the CD command in DOS), be sure to change the directory back before the "goto starta" command. If the directory you changed to is immediately below the issue directory, use "cd .." to return to the main directory. The errorlevels correspond to the position of the executable items within the menu file, including all items in the Icon or Menu sections that include an E (Execute) command. They are numbered from 1 up. When you're using a batch file in this manner to launch programs, no programs will be directly run from the shell program, so whatever file you include in the "E:" command isn't directly used in running the program; however, it is still important to put something in the E command to signal that a runnable item exists, and this must be the name of a file that actually exists (whether .EXE, .COM, .BAT, or any other type) since its existence is checked before the shell will let you run something (and used to determine the need for a disk swap in the case of multi-disk issues). Use the name of a file that is part of the particular program to make the existence check meaningful. THAT'S ALL, FOLKS... That's all the documentation I've got here... it may sound a bit complicated due to all of this detail, but actually, it's not very hard to assemble an issue using this menu shell. The easiest way to do it is to start with a set of issue files already set up (like the ones on this source archive disk), and edit it as needed. --- End of document ---