Customizing The TopSpeed Environment - TSCFG ============================================= The TopSpeed configuration text file (TSCFG.TXT) and other files TS*.TXT included by it contain the message text, menu definitions, project system configuration and compiler definitions installed in the TopSpeed System. This information may be 're-compiled' (using TSCFG.EXE) to produce a new TSDATA.OVL data overlay which is read whenever the TopSpeed environment is entered. This allows you to change your environment menu layout, hot keys, Editing keys and text messages to your own requirements. The top-level configuration file TSCFG.TXT sets some directives (see below), then includes other .TXT files which contain configuration text as follows: TSMAIN.TXT editor keys, menus, and environment options TSPRJ.TXT configuration of project system (see Developers Guide). TSMAKE.TXT Messages and initialization data for Project System and Linker TSISL.TXT Messages for code generator TSCPP.TXT C++ compiler messages TSC.TXT C compiler messages TSPAS.TXT Pascal compiler messages TSMOD.TXT Modula2 compiler messages To run TSCFG.EXE just type: TSCFG at the main DOS or OS/2 prompt in the system directory where you keep TSDATA.OVL. This will create a new TSDATA.OVL, and the old TSDATA.OVL is renamed to TSDATA.OLD. The new configuration can then be immediately used on starting the TopSpeed Environment. You are encouraged to experiment by changing the TopSpeed Configuration File TSMAIN.TXT to discover the setup that best suits you. However, before you edit TSMAIN.TXT, you should save a copy of the file, in case you later want to go back to the default definitions supplied with the TopSpeed system. The following sections describe changes you can make within the Menu Definition File. Changing the Main Menu Type --------------------------- You can use three types of menus: pop-up, pull-down, and bar. The type of the main menu is defined by the line ! LinePull | [ TopSpeed ] which defines a "Bar" style menu (i.e. a Pull-Down menu with no frame). If you wish to have a horizontal "Pull-Down" menu with a frame, you should change LinePull to PullDown. If you want a vertical "Pop-Up" style menu, you should change LinePull to PopUp. If you wish to change the title displayed at the top of a menu, you can edit the "TopSpeed" between the square brackets ('[' and ']'). For example, you may want to change it to: !PullDown [ My TopSpeed C, Hands Off! ] | You can also change the key that invokes the main menu by changing the after the '|' . For example, if you need ShiftF10 to invoke the main menu you might have the line: !PullDown [ TopSpeed ] | Changing Menu Text ------------------ In the Menu Definition File, you can change the text displayed in the menu by editing the appropriate line. For example, if you want to change Files to read PcDos on the Main Menu you can change the line: {F}iles | to {P}cDos | Note that the character enclosed in the braces ( { and } ) defines the command character that invokes the menu line. This command character may be in the middle of the word - for example, Pc{D}os - or left out altogether if not required. The number of leading spaces before the menu text defines the Level of the menu within the menu tree. Don't change this unless the menu tree is to be changed, as described in the next section. Changing the Menu Tree ---------------------- In addition to changing the text of the menu, you can also change the actual structure of the menu tree. This means you can reorder menus, create new submenus or even delete unwanted commands. To illustrate how to change the menu tree, suppose you wish to group the "Compilation Functions" together in a single menu. To do this, the lines containing: {E}dit | Editor {C}ompile | Compiler {L}ink | Linker {M}ake | Make {R}un | Run program {P}roject | {ProjOptions} [Project Options] could be changed to: {E}dit | Editor {C}ompilation {C}ompile | Compiler {L}ink | Linker {M}ake | Make {R}un | Run program {P}roject | {ProjOptions} [Project Options] This creates a new submenu under the command Compilation. The indentation of the menu text (i.e. number of leading spaces) determines the start and end of each menu. In the above example, this means that the extra spaces added in front of {C}ompile cause a new submenu to be started. This submenu continues until {P}roject where the indentation returns to its previous level. Look at the Project Menu for further examples of "nested" submenus. Changing ShortCut Keys ---------------------- At the end of a Menu Definition Line, there also may be a ShortCut key sequence defined. This sequence activates that function or submenu. You may change or add to these key definitions to change the ShortCut keys. For example, to assign the key F4 to the {O}ptions {R}un {C}ommand-Line function, you would change the line: {C} - Command line | Command Line to {C} - Command line | Command Line You can specify multiple keys after the line, if you need more than one key to activate the same function. You can also define keys independently of the menus. An example of this is the zoom window function, which is defined as follows: !Key | Zoom Window You can change, add to, or delete these key definitions in the same way as changing the Menu Definition lines. External DOS Commands --------------------- As you may have already noticed, there is an Action Name after the | and before the ShortCut keys in Menu and Key Definition lines. This name defines the action that is performed when the menu line is selected, or the ShortCut key is pressed. In addition to the pre-defined environment actions (which are listed further on) you can also install a DOS Command String which will be executed under a DOS shell whenever the Menu Line is selected. In this way, you can attach your own programs to the environment menus and keys. For example, if you required the DOS command delete *.bak as a menu function, then you might add the line: Delete {B}AK files | 'del *.BAK' to the menu definition. The DOS command required should be enclosed by single or double quote characters, and may prompt for parameters by placing %M or %P within the command string. The Editor Keys and Menus ------------------------- The Environment Editor has its own specific keys and menus. These are separated from the rest of the Menu Definition by the line: !Editor Everything after this line and before the line !MsgText is only valid when within the Editor. If you want to add or change Editor keys or menus, the you should edit the lines after !Editor. Text Messages ------------- Text after the !MsgText directive (and in included files) defines all the text messages used by the environment. These may be translated to other languages or personalized by adding your own text. The length of most messages may be changed, but in general it is best to retain the approximate length of each message (especially when lengthening messages). Some messages are used as initialized data and should only be changed with extreme care (or preferably not at all!) An example of this is the C reserved words. TSMAIN.TXT Format ================= The TopSpeed Configuration file contains lines of text that may be either Directives, Menu Text or Message text. Blank lines are not significant, and can therefore be used for clarity. Directives inform the TSCFG program of, Menu Types, Menu Titles, Conditional sections and ShortCut Keys. The Menu Text defines the structure of the menu tree and the associated functions. The Message Text defines the text used and displayed by the TopSpeed Environment. Directives ---------- Directives always begin with a '!'. Following the '!' is the directive name, together with any parameters required. Directives can be global to the entire environment, or they can be restricted to the editor. The directives, together with some examples, are as follows: Menu Type --------- You can have three forms of Menu Type directives: !PopUp [ MenuTitle ] | KeySequences or: !PullDown [ MenuTitle ] | KeySequences or: !LinePull | KeySequences Such directives define the type and title of a top level menu and any ShortCut keys that should invoke the menu. The menu title and shortcut keys are optional. The type of the top menu can be one of the following Line Pull (default), a Pull Down menu with no frame or title. Pop Up, which has vertical menu selections. Pull Down, which has horizontal menu selections. The menu title is text - enclosed by square brackets ( [ and ] ) and will appear in the top center of the frame enclosing the menu. You can define one or more KeySequences to invoke the menu. The KeySequence format later. Example: !PullDown [ TopSpeed ] | specifies that the menu named "TopSpeed" is to be a pull down menu, and is to be activated by pressing F10. Editor Section -------------- !Editor Generally, your directives will apply to the entire environment. Sometimes, however, you may have directives that should apply only to the editor. For example, you might want to use a different Help Line for the editor. To make this possible, the menu definition is split into two distinct sections. The first section contains general menus and keys, available from anywhere within the environment. The second section contains editor menus and keys that are only available while editing. To split the two sections, the directive !Editor must be included in the menu definition. Everything above this directive is global to the environment, and everything down to the Message text section is local to the editor. ShortCut Key Definition ----------------------- !Key | Action KeySequences You can use the !Key directive to define ShortCut keys that invoke commands not found on any menu. This directive assigns the specified action to one or more key sequences. The format of actions (which can be a DOS command) is described below. Whenever a sequence of keys is pressed, the appropriate action will be invoked. Keys defined before the !Editor directive will be active anywhere within the environment, and keys defined after will be active only while editing. An example of an Editor Key is the Case Correct Key which is defined as follows: !Key | Ed Case Correct Comment ------- !! A line beginning with '!!' serves as a comment on other material. The line is ignored by the environment, but will be useful to you or someone else trying to get an overview of the file's contents. You can include comment lines anywhere in the file. Example: !! TopSpeed C Version 3.10 !! ----------------------- Conditional Sections -------------------- Sections of the menu definition may be bracketed by the !if and !end directives these take the form: !if conditionname conditional section !end If the condition has been previously set using the !set directive (e.g: !set conditionname) then the conditional section will be read, otherwise it will be ignored by the TSCFG program. These sections may be nested and cannot bracket messages in the !MsgText section. Multiple conditions may be specified - for example !if c | cpp will cause the following lines to be included if either of the conditions have been specified. Menu Line Definition -------------------- A menu line defines the menu level, the menu text, the command character, and the function to be invoked, as well as any ShortCut keys. The format of a menu line definition is: MenuText | Action KeySequences The menu text specifies what will appear on the screen when the menu is invoked. The level of the menu is determined by the number of leading spaces before the menu text. When a new submenu definition begins, its text is indented further to the right. When the submenu definition ends, the text is indented to the left to the same indentation as the parent menu. The Action is the name of the function to be invoked and is described in the following section, "Menu Actions". Note that menu lines that invoke submenus should not have an Action defined. They can have associated ShortCut keys, however. Within the menu text, you can define a single command character (which invokes that menu line) by enclosing that character within braces - for example, {E}. A command character defined in this way should be unique for that particular menu. Trailing and leading spaces are ignored within the menu text (except that leading spaces serve to define the menu level, as described above). If you need actual spaces at the beginning or end of the text, you should use the underscore _ character. This will be translated into actual spaces in the displayed menu text. A Menu Line may also contain after the '|' character, Help File Links (contained within the braces '{' and '}'), Menu title text (contained between '[' and ']') and, after the action, option definition text. Option definition text (also contained within the characters '[' and ']') is read and decoded by the TopSpeed compilers and environment so should NOT be changed. You may change the Menu Title Text however which determines the title displayed at the top and center of the menu window. Menu Actions ------------ The menu actions are invoked either by a key or by menu selection. There are two different kinds of actions, Pre-Defined Actions and External Actions. Pre-Defined Actions invoke an environment command, while External Actions run an external program under DOS. Pre-Defined Actions ------------------- These actions are specified by name. The first eight non-space characters in the name are significant. The following lists specify the pre-defined actions, together with the page number of the section that describes their function. The first list shows the global actions and the second list shows the actions accessible in the editor. Global Actions -------------- The Global Actions, which may be invoked throughout the environment, are as follows: LoadFile (load file into editor) LoadF RO (Load file read-only) PickFile (Pick file from pick list) SaveFile (Save file in current editor) SaveAllF (Save all files) ChangeDir (Change DOS directory) Directory (Display DOS directory) DOSShell (Execute DOS Shell) Execute (Execute single line program) Quit (Leave environment) Editor (Invoke editor) Compiler (Compile program) Make (Make project) Run program (Run program) ProjNew (New project name) ProjOpt (Project options) ModelOpt (Memory model options) CompOpt (Compiler options) MakeOpt (Make options) Command Line (Command line for Run program) RunOpt (Run options) EdOpt (Editor Options) Default Filenames (Define default filenames) Default Extensions (Define default extensions) No Of Backups (No of editor file backups) Top Scroll Zone (Set top scroll zone) Bottom Scroll Zone (Set bottom scroll zone) EnvOpt (Environment option) Load Red File (Load redirection file) Red Edit (Edit redirection file) Load Macs (Load macro file) Save Macs (Save macro file) Load Config File (Load CFG file) Save Config File (Save CFG file) Asciitab (Ascii table) Calculator (Calculator) Find Error (Find run-time error) WildSearch (Search for text) Search List (Search pick-list) ScanCodes (Keyboard codes) Print (Print file) PrintSet (Print settings) Review Screen (Review DOS screen) View File (View file as data) Help (Enter help system) Info (Information window) Edit0-Edit9 (Invoke editor windows 0-9) Zoom Window (Zoom window) Cycle Windows (Cycle windows) CutKey (Cut text from screen) (Single key only) WinKey (Enter window control mode) (Single key only) Editor Actions -------------- The Editor Actions, which may be invoked throughout the editor but not elsewhere, are as follows: Ed Load File Ed Load F RO Save File Ed Write File Ed Find Ed Replace Ed Start Screen Ed End Screen Ed Start File Ed End File Ed Start Line Ed End Line Ed Goto Begin Block Ed Goto End Block Ed Prev Position Ed Del End Line Ed Restore Line Ed Goto Line Save File Save All Files Ed Begin Block Ed End Block Ed Hide Block Ed Mark Word Ed Mark Line Ed Copy Block Ed Move Block Ed Del Block Ed Read Block Ed Write Block Ed Get Block Ed Print Block Ed Indent Block Ed Undo Ed Quit Ed Opt Toggle RO Ed Tab Width Ed Word Left Ed Page Down Ed Move Right Ed Move Up Ed Word Right Ed Del Forward Ed Del Backward Ed Tab Ed Find Again Ed Ins Line Ed Ins Below Ed Prefix Ed Page Up Ed Move Left Ed Del Word Ed Upper Case Ed Scrl Down Ed Move Down Ed Del Line Ed Scrl Up Ed Next Error Ed Prev Error Ed Case Correct Ed Goto M1 Ed Goto M2 Ed Set M1 Ed Set M2 Paste Editor Actions can only be used as the action within the Editor section of the menu definition, while Global Actions can be used in either section. External Commands ----------------- Within the environment menu system it's possible to attach an external DOS or OS/2 command or program to any key or menu entry. This can be done by enclosing the command line in either single or double quotes and using it as an Action in the Menu or Key definition described above. For example, suppose you have the following menu lines defined: {B}ackup Files | 'copy *.c a:' !Key | "find 'Version' *.h" If you select the {B}ackup Files menu entry, then the DOS command line: copy *.C a: is executed. Similarly, when you press AltZ the command line: find 'Version' *.h is executed. External Command Parameters --------------------------- Suppose you need to pass the current Project name to the command you want to execute. You can do this, by including %M in the command at the spot in which you want the name. Similarly %L can be used to insert the current command line set. To prompt for a string you can put %P (prompt string) in the command string. The %P will then be expanded to the entered string. For example, suppose you define: {E}rase | 'del %P(File to delete: )' {D}ebug | 'debug %M.EXE' Selecting Erase prompts for File to delete: After you type a file name (let's say, FTODEL) and press Enter, the command line: del ftodel is executed. Similarly selecting Debug will prompt for the Project name and will then execute the command debug mainfile.exe You can include as many '%P's as you need in the command string. Key Sequences ------------- The !Key directives and menu entries can have one or more KeySequences attached. These key sequences consist of key names enclosed by the characters '<' and '>'. Examples of key sequences include: Alt A Control Z Control Q followed by D Control K followed by M then 1 F2 Shifted Home followed by End The following keys are valid and represent the names to use: F1 - F10 CtrlF1 - CtrlF10 ShiftF1 - ShiftF10 AltF1 - AltF10 Alt0 - Alt9 AltA - AltZ UpArr DownArr LeftArr RightArr CtrlUpArr CtrlDownArr CtrlLeftArr CtrlRightArr PageDown PageUp Home End CtrlPageDown CtrlPageUp CtrlHome CtrlEnd Del Ins AltEqual ShiftTab If ambiguous key sequences are defined in the menu definition (for example, CtrlK and CtrlK B and CtrlK K), then the menu system will wait a short interval after the initial sequence has been typed. If the remainder of a longer sequence is typed, within this time then the long sequence will be executed. Otherwise, the shorter sequence will be assumed. This can be used to create automatic "pop-up" menus in the menu definition. To remove the automatic Pop-Up facility from the standard menu configuration, remove the "short" key sequences - that is, remove the lines in TSMAIN.TXT containing the sequences CtrlQ, CtrlK and CtrlO. Message Text ------------ The message text section is located at the end of the TSCFG.TXT file and is introduced by the !MsgText directive. Text following this directive will be interpreted as text messages. The !MsgText directive when followed by a filename can also be used to 'include' an external set of text messages. e.g: !MsgText starts the message text section. Text messages have the format: decimal number followed by a single space followed by the message text. Trailing in the message text spaces are ignored, but if required can be added by placing a '@' delimiter character at the desired end of message. In this case the '@' is deleted. Text messages must be kept in the correct numerical sequence. However some message numbers may be omitted. TopSpeed compilers have their error messages within external files and are included as described above. Generally it is easy to determine the message use from either inspection or trial and error. Some useful messages that may be configured are listed below: 25 - Default Backup extension 26 - Backup extension when no of backups > 1 34 - Printer device as used by the editor 36 - Characters used together with alpha-numerics to define a 'word' (as used by next/prev word, delete word etc) 46 - Character Prefix prompt (CtrlP) 61 - Yes or No alternative keys (YN) 73 - Abort/Retry alternative keys (AR) 81-82 - am pm for date strings 119,127,144,145,149,156,181-183 - Help lines displayed at the bottom of the screen. Text enclosed in braces is highlighted. ~nnn specifies the ASCII character nnn, which can be used to insert unprintable characters. 147 - The names of the keys 174-178,185-186,189-190,195-199: Various default filenames and extensions 180 - Search option characters 188 - Location of OS/2 error message file 193 - OS/2 Start session command line 210+n DOS error message for error n 250-264 Project file text messages 310-315 Command line options description 400-460 TopSpeed Run-time-error messages 500-516 DLL Run-time-error messages