User Manual to C-DESK V1.76, the GEM shell for Sozobon C, January 1992 ------------------------------------------------------------------------ written by Frank Specht & Holger Weets Shareware CONTENTS ------------------------------------------------------------------------ 1. Introduction 1.1. History 1.2. Shareware (in Germany) 1.3. Operating security 2. Installation 3. Pulldown menu's 3.1. Menu "C-DESK" 3.1.1. Command "about C-DESK" 3.1.2. Accessories 3.2. Menu "File" 3.2.1. Command "show Info" 3.2.2. Command "select all" 3.2.3. Command "close window" 3.2.4. Option "sort names" 3.2.5. Option "sort type" 3.2.6. Command "copy" 3.2.7. Command "view file" 3.2.8. Command "find pattern" 3.2.9. Command "delete" 3.2.10. Command "new folder" 3.2.11. Command "quit" 3.3. Menu "C-System" 3.3.1. Command "translate" 3.3.2. Command "compiler" 3.3.3. Command "optimizer" 3.3.4. Command "assembler" 3.3.5. Command "linker" 3.3.6. Command "editor" 3.3.7. Command "RSC editor" 3.3.8. Command "archiver" 3.3.9. Command "debugger" 3.3.10. Command "C-Lint" 3.3.11. Command "run project" 3.3.12. Command "sel. changed" 3.4. Menu "Extra" 3.4.1. Command "system info" 3.4.2. Command "install icons" 3.4.3. Command "function keys" 3.4.4. Command "paths" 3.4.5. Command "apropos" 3.4.6. Command "options" 3.4.7. Command "find function" Settings 3.4.8. Command "save" 3.4.9. Command "save as" 3.4.10. Command "load" 3.4.11. Option "fast redraw" 4. Windows 4.1. Types of windows 4.1.1. C-files window 4.1.2. Assembler files window 4.1.3. Library window 4.1.4. Error message window 4.1.5. Directory 4.2. The window elements 4.3. Mouse clicks in windows 4.3.1. Click inside an inactive window 4.3.2. Click inside an active window on an empty line 4.3.3. Click inside an active window on an item 4.3.4. Double click inside an active window 4.3.5. Click with the right mouse button 4.3.6. Click with Control key pressed 4.3.7. Double-click with Alternate key pressed 4.3.8. Move the mouse with mouse button pressed 5. Icons 5.1. Using the icons 5.2. The installation of icons 5.3. The system icons 5.3.1. Project 5.3.2. C-files 5.3.3. Assembler files 5.3.4. Library 5.3.5. Disk 5.3.6. Information icon 5.3.7. Editor 5.4. The utility icons 6. Command line prototypes 6.1. Basics 6.2. The interpretable symbols 6.3. The sequence of evaluation 7. Floatingpoints with C-DESK & Sozobon C 8. Keyboard 9. Known Bugs 1. INTRODUCTION ----------------------------------------------------------------------- We wrote C-DESK in order to simplify the use of the C compiler system from Sozobon Limited. C-DESK is fully developed using the Sozobon C- compiler system. The following programs/libraries where also used: - C-DESK (Holger & Frank) for creation of C-DESK (!) - CED (Holger) for editing the C- and assembler sources of C-DESK - BED (Holger) for creation of the icons - C-Icon (Holger & Frank) for creation of the newer icons - RCS (DR) for creation of the RSC-File (menue's and dialogboxes) - RED (Holger) for recreation of the newer RSC-Files - HAR (Holger) for rearranging, debugging and expanding the libraries - C-Lint (Holger) for debugging the C-DESK - sources - XDLibs (changed by Holger, Frank, Christian and others) - AESFAST (Ian Lepore) for the used GEM-functions - VDIFAST (Ian Lepore) for the used VDI-functions ATTENTION --------- We modified the compiler "hcc.ttp" and the linker "ld.ttp" from the Sozo- bon compiler system, so that a better interface between these programs and our shell is possible. For more information about changes made on the compiler (we named it "xcc.ttp") see "xcc.txt". Changes made on "ld.ttp": - the linker "ld.ttp" can now link more than 100 object files. We in- creased the limit up to 200 object files otherwise we couldn't trans- late our C-DESK system. - by default, the name of the compiled executable file is based on the second (instead of the first) filename given on the command line. The first name is always the startup code, the second name is always the first user object file. In C-DESK the name of the executable file is always defined. - if the linker finds undefined symbols, the name of the corresponding file will be printed completely (instead of the first 8 characters). 1.1. History In search of an efficient C compiler in the public domain we found in 1989 the compiler system from Sozobon. To test its effiency we decided to start a project using this compiler. So we wrote C-DESK, because in case we would like the compiler system, we would immediately have a powerful graphical shell. On the other hand we would also learn programming GEM in the C language, a nice challenge. After a few considerations we immediately began with our project. But un- fortunately we found out that the programming of the user-compiler- interface was simple, but the programming of the user-computer-inter- face... The programming of the graphic environment manager (GEM) proved to be very hard. Many errors in AES and VDI hindered us to write C-DESK within the planned few weeks. The first executable C-DESK version was ready after (only) three months. The first published version was C-DESK 1.31 in July 1990. C-DESK was tested by: - Carsten Setje-Eilers (Kiel, Germany) - Holger Krone (G”ttingen, Germany) - Christian Wempe (Oldenburg, Germany) - Thomas Wempe (Oldenburg, Germany) - Gnter Ellerbrock (Oldenburg, Germany) - Folkert Struck (Oldenburg, Germany) - many C-DESK user (international) - ourselves (Oldenburg, Germany) C-DESK has been tested on following computers : - Mega-ST & TOS 1.04 - Mega-ST & KAOS-TOS 1.42 - 1040 ST & TOS 1.02 - 1040 ST & TOS 1.04 - 1040 STE & TOS 1.06 - AMIGA with ST-emulator - MEGA STE & TOS 2.0n - TT & TOS 3.0n On all above listed system configurations, C-DESK was 100% operational. Problems are only to be expected when the program is not used in high- resolution. We like to thank Dirk Smulders, Aartselaar, Belgium, for most of the english version of this documentation. Tips and critics about C-DESK should be written to the following address: Holger Weets & Frank Specht Dachsweg 44 D-2900 Oldenburg Germany 1.2. Shareware (in Germany) C-DESK is a shareware product, that means that every user is allowed to copy or give away C-DESK as many times as he wants, but every regular user must pay the shareware donation of 20,- DM (Deutsche Mark) or $15 for the time and effort it took to write this program. If you send us the money, a prepaid self addressed envelope and a 3,5" Atari formatted disk, you can get the newest update of C-DESK and all other programs we developed for easier C programming. If you are using a bank transfer, please enclose the payment slip. Transfers can be made to : Holger Weets Banking-account (Konto): 023-182 041 Bank: 280 501 00 Landessparkasse zu Oldenburg, GERMANY For international transfers it is better to use a postal transfer cheque. We would like to make a few observations about the reactions from the C-DESK users until now: 1. we are pleased with the many reactions received; 2. it is easier for us to find errors in our products, if you tell us something about your computer configuration (which ST/STE/TT, using harddisk, ram extensions, graphic cards, which programs in AUTO folder, which accessories, ...) and the version number of our product you use; 3. PLEASE!, if you want to have other products from us or a new update version from C-DESK, send us a PREPAYED SELF ADRESSED ENVELOPE, a formatted DISC AND a LIST with your WISHES; the 20,- DM we possibly received is NOT for covering the mailing expenses. 4. we received several discs in standard letter envelopes. Needless to say that you should use a more protective kind of packaging, discs are after all still sensitive things. 5. if C-DESK doesn't run together with other programs, please send us these programs, if it is allowed. That way we can better reproduce the errors. 6. if you find errors or if you have improvement suggestions, then write us DETAILED informations about the errors or your ideas, and, if possible, add a reproducable example (for errors). If you consider these advices, then you will receive your reply earlier. Besides, chances are good that a more faultless version of C-DESK will be enclosed. 1.3. Operating security In newer C-DESK versions we implemented routines, which should make C-DESK more efficient and safer with regard to badly programmed GEM applications. In detail these are: - C-DESK will close all windows which are not closed from the GEM application after its termination; - you can use non-system Fileselect boxes, which don't send a redraw message to the system. Previously C-DESK "hang" in an endless loop, waiting for the redraw-event. - when running a GEM-application, C-Desk will count all wind_update() and graf_mouse() calls of this program and when it terminates, C-Desk will balance the counters. So you can use menues/windows even after a GEM-application crashes. This is new since V1.74 Do you have some suggestions to make C-DESK safer? Then write to us. 2. INSTALLATION ----------------------------------------------------------------------- The C-DESK system contains the shell program "CDESK.PRG" with its resource file "CDESK.RSC", the user manual "CDESK.TXT", the on-line help manual "APROPOS.TXT", the update manual "UPDATE.TXT" and (possibly) a parameter file "CDESK.INF". Following files should be on the distribution disc : \CDESK\CDESK.TXT this manual \CDESK\UPDATES.TXT version history of C-DESK, only interesting for those who are updating from earlier versions \CDESK\APPROPOS.TXT file with the on-line help \CDESK.PRG the shell program itself \CDESK.RSC the resource file for the program (\CDESK.INF the parameter file for the program (optionally)) It's possible, that the compiler system from Sozobon or parts of it, f. e. the modified compiler and linker, are also included. To install C-DESK you 1. should read this chapter completely. If you still have any problems, print this chapter and place it next to your computer. 2. copy all files, which are necessary to use C-DESK, to that place, where you want to use them (harddisk, floppy disk, ...). The suggested structure on disk is the following: ROOT\ or \ C-DESK.PRG C-DESK.RSC BIN\ CLINT.TTP XCC.TTP JAS.TTP LD.TTP SZADB.TTP TOP.TTP CLINT.TTP TAGFILE.TTP HAR.TTP RED.PRG (your editor) ... CDESK\ APPROPOS.TXT -- online help file for the 'apropos' command CDESK.TXT -- this manual CDESK130.CHG -- update history V1.30 - V1.71 CDESK172.CHG -- update history V1.72 - INCLUDE\ STDIO.H ... LIB\ STD_S.O MIN_S.O ACC_S.O ACC4_S.O FLOAT.A GEMLIB.A UTIL.A WINDOWS.A AESFAST.A VDIFAST.A XDLIBS.A INITARG.O TOSDEBUG.O ... This structure is obviously not forced by C-DESK, but it will be supported from C-DESK as a default, if no parameter file "CDESK.INF" exists. 3. If you work with a ram disk: - install your ram disk with about 400-500 kB; - copy the "bin\" folder with the compiler files on your ram disk, (XCC, TOP, JAS, LD & EDITOR as a minimum for fast working) - copy the "lib\" folder and the "include\" folder on the ram disk, only those LIB and .H files needed for your project are the mini- mum required for fast working; - if there is enough space free, copy your project files to the ram disk also (*.C files, *.O files in order to speed up the editing and linking process). You can do this copying from within C-DESK, too. 4. run C-DESK, then a) choose the menu entry "paths" and press the "test" button. Correct the paths, which show no check mark. b) choose the menu entry "options" and make your own preferences of the system. c) within the library window, check the paths for the used object files and insert the missing object files (for help read chapter 4. "Windows"); d) insert the used source codes into the C files window and the assem- bler window (for help read chapter 4. "Windows"); e) choose the compiler/optimizer/assembler/linker dialogs and make your own preferences of the compiler system (for help read the user manual for the compiler system); f) announce all icons you want to work with (for help read chapter 5 "Icons"); g) at last choose the menu entry "save parameter" and choose the name "CDESK.INF" (or another name, if you like). These actions (a-f) can be made in any order you like. Just a few tips : - if you are going to work on many separate projects, it is recommended that you set up C-DESK the first time without any project related files. Save these settings (f.e. "STANDARD.INF") using the "save settings" option. This way you can later use this file as a base, add the new project files to it and save it under another name (in another folder), creating thus a project related .INF file. - if you are using the ATARI-ST-Desktop, you can work in the following way : 1. Open a window in which you can see C-DESK; 2. Open another window in which you can see the project; 3. Make the project window the TOP one; 4. Start C-DESK by double clicking the program while holding down the right mouse button (=> C-DESK will find the right parameter file if it has the name CDESK.INF, and the program will load the necessary information). - if you are using KAOSDESK it is recommended to put C-DESK under a function key, open then a window with the project files, and start C-DESK using the keyboard ("Ctrl-Fx"). - if you are using the shareware-desktop GEMINI, then add the following line to your version of MUPFEL.MUP: setenv CDESK_PRG "d:n" Now make an Desktop-Icon out of C-Desk; To start C-Desk, open a window with the project files (and the CDESK.INF) and start C-Desk by doubleclicking the C-Desk icon. But the easiest way to use C-Desk is to announce it as an application for Files with the Extension 'INF'. If you want to start C-Desk now, simply open the desired directory and do a double click on the INF-file. 3. PULLDOWN MENU'S ----------------------------------------------------------------------- 3.1. Menu "C-DESK" 3.1.1. Command "about C-DESK" Using this menu item will show the standard Copyright notice, the addresses of the authors and the version of the program. 3.1.2. Accessories The usage of accessories is fully supported, but be careful when using accessories requiring large chunks of memory. 3.2. Menu "File" 3.2.1. Command "show Info" The keyboard shortcut for this command is ()"I" In case that no file is selected in the topmost window (no inverted file name), this command will show a Fileselect box so that you can select the file for which you want information. After the file is selected another dialog box will be shown with the name, date and time stamp of the file. The name of the file can be changed in this dialog box. If there was a file selected in any of the open windows, the command will show the information concerning the selected file. If there is more than one file selected, only information about the first file will be given. 3.2.2. Command "select all" The keyboard shortcut for this command is ()"S" This command will invert all items of the active (top) window. This command is helpfull if there are more items in the window than can be displayed (long lists). 3.2.3. Command "close window" The keyboard shortcut for this command is ()"Undo" This command closes the active (top) window. Very interesting option for the "Directory" window because it will be closed even if the "Root" is not in the window. 3.2.4. Option "sort names" If this command is "checked", then the directory window will display the files alphabetically sorted by file-name. The command is checked when there is a check mark in front of it. Selecting the command will toggle it's selection on and off. 3.2.5. Option "sort type" If this command is "checked", then the directory window will display the files alphabetically sorted by file-extension (file- type). The command is checked when there is a check mark in front of it. Selecting the command will toggle it's selection on and off. 3.2.6. Command "copy" The keyboard shortcut for this command is ()"K" If no window items (files) are selected, the Fileselect box will appear and you will be able to choose the file you want to copy (source-file). After this the Fileselect box will appear again so that you can enter the target file name and select the appropriate path (drive, folder). The file name can be changed if necessary at this point. After this dialog is completed, the copy process will take place. If the target file already exists in the selected folder and the "Confirmation"-option is active, a warning will appear and will give you following options : - source will overwrite existing target file - skip this file copy (if more than one file is to be copied) - abort copy process completely. If the "Confirmation"-option is de-activated, the target will always be overwritten. Copying files from within the windows will happen almost the same way except that : - the Fileselect box will only appear once asking for the target folder, - the Filenames cannot be changed, - multiple files can be selected and copied with one command, - the copy process can be aborted using the "Undo" key (same as in TOS 1.04), - Folders and their contents will be copied. If a file in the C-file window was selected by the "Sel. changed" command, a following copy command will, after confirmation in an alert box, also copy the respective object file. The names and the number of these files will not be reported in the following information box. 3.2.7. Command "view file" The keyboard shortcut for this command is ()"V" If there is no file selected in any of the windows, the Fileselect box will appear asking for a file name. Once there is a file selected, it will be displayed on the screen and following keys can be used to control the display : -'Space' / Left mouse button : next page - 'd' : next half page - 'q'/Right mouse button/Undo : stop displaying the file - 'a' : continually display the file until 'a' is pressed again - 'shift' : halt the display any time (even in 'a' mode) 3.2.8. Command "find pattern" The keyboard shortcut for this command is ()"F" If there are no inverted files in any of the windows, then the usual Fileselect box will appear and you will be able to select a file. Next a dialog box will appear asking for the pattern to look for. At this point you will also have the possibility to check (or uncheck) the "capitalisation"- option (upper-lowercase matching). C-DESK will now search through all selected files and if a match with the pattern is found this will be listed in an output window by the line-number and the line itself. Once a screen has filled up, the process will wait for a keypress or mouse click. Any key except "Q" or "Undo" will continue the output, as will a left mouse click. Clicking the right mouse button (or q or Undo) will abort the search. 3.2.9. Command "delete" The keyboard shortcut for this command is ()"Delete" Again, if no files are selected in the windows (inverted), the Fileselect box will be used in order to select the file to delete. If there were files or folders selected, these will be deleted after answering positively the confirmation dialog. Deletion will happen the same way the ATARI desktop does it; folders will be recursively deleted with their contents. The "Undo" button will abort the process. If the "Delete" button was used to start the process, confirmation will still be asked before deletion. 3.2.10. Command "new folder" The keyboard shortcut for this command is ()"N" This function works analogous to the ATARI desktop. A small dialog box will appear asking for the new folder name. This new folder will be placed in the "Directory" window active at that moment, using the current path. This command can only be activated when the "Directory" window is active. 3.2.11. Command "quit" The keyboard shortcut for this command is ()"Q" This command will terminate the C-DESK program (optionally after a confirmation dialog). 3.3. Menu "C-System" Under this menu all C-DESK main components and their options are located. 3.3.1. Command "translate" The keyboard shortcut for this command is ()"T" The source file translation into a program will start as specified in the "Options" of the "Extra" menu. It can be interrupted by pressing the "Alternate" key. This key will only be scanned by C-DESK during this process, so keep pressing the key until a response follows (this can take a little time). 3.3.2. Command "compiler" This command will activate a dialog box with several options. The meaning of these options should be looked up in the Sozobon-C documentation. Since we have made a lot of changes on the compiler, we renamed it to 'XCC'. C-Desk will only work 100% correct, if you use this extended version. See the file 'XCC.TXT' file for more details. Using an original version, you cant get the compiler errors/warnings in a window, they will appear only on the screen. 3.3.3. Command "optimizer" This command will activate a dialog box with several options. The meaning of these options should be looked up in the Sozobon-C documentation. This program was modified, too. So read the file 'TOP.TXT' for all options that you can't find in the original documentation. 3.3.4. Command "assembler" This command will activate a dialog box with several options. The meaning of these options should be looked up in the Sozobon-C documentation. 3.3.5. Command "linker" The keyboard shortcut for this command is ()"L" This command will activate a dialog box with several options. The meaning of these options should be looked up in the Sozobon-C documentation. 3.3.6. Command "editor" The keyboard shortcut for this command is ()"E" If you issue this command, a dialog box will be presented in which you can enter the command line prototype for the editor. See also chapter 6. for more details about command line prototypes. The dialog is terminated by clicking: - OK: all items (and changes) in the dialog box will be made permanent - CANCEL: none of the changes will become effective. In this dialog box you can also determine which actions C-DESK should take, depending on the editor-exit-code. Following option are available : - Compile => all changed C-source files will be automatically translated. Please note that linking will not take place, even if this option is selected. The maximum translation possible is compile, optimize and assemble. - Compile & Link =>all changed C-source files will be translated and linked. - Compile, Link & Run project => the complete project will be compiled, linked and the program will be started provided no errors occurred. Each of these functions can be given a one digit positive number which represents the return code. Only numbers > 0 will be taken in account. Another setup is the behaviour of a double click on an error in the "Error" output window. The error output will have a line number associated with it which can : - be passed to the editor (if it supports this) and the cursor will then be at the faulty line in the source when the editor starts - the complete error file will be handed to the editor which in turn will open the error file and the source file (faster debugging). In this case you can even specify which file should first be passed to the editor : - the error file or - the source file (most editors will load one file on top of the other, so the error file first makes most sense). If one of these functions doesn't work with your editor (because it doesn't support it) then you should upgrade your editor (for more flexible working conditions) Following editors work with C-DESK : - CED (PD C-editor, still under development by Holger but works already very fine) - EDIMAX (PD), but problems with line numbers as parameter - AS-FAST (PD) - EMACS (PD) - WF_EDIT (PD, MAXON no. 454) - KOLUMBUS (PD, PD-Pool no. ???), but no line numbers supported - CED ( -"- , NOT my Editor!), better take the error file as second parameter - XEDIT (PD, V1.61), but only one filename and a line number can be given to it (for now). - TEMPUS - EDISON - PKS-EDIT since we don't have any of these editors, we couldn't try it, but various messages told us it works without problems; Let us know if you found out wheter it works or not. 3.3.7. Command "RSC editor" Selecting this item, you will be able to type in a command line for your resource-editor. Most products don't process command lines, but RED (Resource-EDitor by Holger) does, and it's very handy. The keyboard shortcut for this command is ()"G" Using this will start the editor immideate. The resource editor which you have set up in the path dialog will be started by using this command. As a default the new RED, written by Holger Weets is selected (it can be ordered by sending 40,- DM with the remark "RED", a 3.5'' Disk and a self-addressed envelope to my address). 3.3.8. Command "archiver" The keyboard shortcut for this command is ()"A" The archiver program which you have set up in the path dialog will be started by using this command. As a default HAR.PRG will be used. This archiver is written by Holger and uses it's own GEM-surface with windows. You can select all files and operations on the files using these windows and pull down menu's or keyboard commands ! 3.3.9. Command "debugger" The keyboard shortcut for this command is ()"D" The debugging program which you have set up in the path dialog will be started by using this command. The file name of the compiled program will be passed to the debugger by default. 3.3.10. Command "C-Lint" The keyboard shortcut for this command is ()"C" When this command is issued a dialog box with the options for the CLINT.TTP will be shown. Please read the CLINT documentation for further specifications about the program but we can tell right now that this is a very good version of the LINT program (CLINT written by... Holger) If you use this command, some of the source files must be selected (inverted). 3.3.11. Command "run project" The keyboard shortcut for this command is ()"R" If you issue this command, a dialog box will be presented in which you can enter the command line prototype for your project (compiled program). This prototype can be stored with this dialog. See also under chapter 6 for more details about command line prototypes. 3.3.12. Command "sel. changed" The keyboard shortcut for this command is ()"U" This command works together with the "mark changed files automatically"-option (Extra's menu). If the option is active, C-DESK will note which source files (C-source and/or assembler) were changed during the session. Issuing the command "sel. changed", all these changed files (source and assembler) will be selected in the top-window. This command is very useful for the preparation of updates especially for RAM-disk users. 3.4. Menu "Extra" 3.4.1. Command "system info" After using this command a dialog box will be shown with following information : system-time, system-date, available system memory and the free disc space on the active drive. In this dialog box system time and date can be set. You can also change the active drive and the available space on the newly selected drive will be shown. This new drive will become the active "Path". 3.4.2. Command "install icons" This command will show a box in which you can select or deselect any icon supported by C-DESK. Following icons are supported : - Project - C-sources window - Assembler source window - Library - Drive - Editor - Utility 1,2,3,4,5,6,7,8 Each entry in this dialog consists of a text line and a check box. If the box is checked (crossed) then the icon will be visible on the desktop. The text indicates the type of icon. Certainly worth mentioning here are the Utility icons. There are eight of them and you can assign any program to these icons. If no program is selected, the name will be Util x, but if you activate one of these buttons (cross the box) then the Fileselect box will be shown (after you enter "OK") and you will have to select the program you whish to assign to this icon. If you don't select a program or you press "Cancel", the icon will not be visible on the desktop. The names can be changed afterwards using the keyboard. 3.4.3. Command "function keys" Selecting this command will show a dialog box, wich will allow you to set up to ten function keys (ALT-F1 - ALT-F10) with any programs you want. At the left of each edit-field you can see a small button. Selecting it will allow you to set the edit- field with the fileselect box. Of course you can give a command-line to every program just by typing it behind the path-specification. If there isn't enough space in that line, use an util-Icon instead. 3.4.4. Command "paths" A dialog box will come up in which you will be able to set the path's for following programs : - Compiler - Optimizer - Assembler - Linker - Archiver - Debugger - C-Lint - Editor - RSC Editor - Project - Apropos-file - Include files (three lines) - Temporary path (folder) for '.s'-Files - Temporary path (folder) for other files (.ERR, .TMP) If you click on one of the buttons, the Fileselect box will be shown, with the actual Path to the program in question. You can now change this path or the program. If the program in question can be found in the new location, a hook will be drawn next to the box to indicate this. In this dialog it is also possible to enter the path's for the Include-Files. Three possible paths are available which can be stored. Each path must be listed on it's own line, and the path should be terminated by '\' (as can be seen in the default settings). In order to speed up the translation process you should list the path for the global include files (STDIO.H, etc) last. This will shorten the compiling stage of the process. The directory for the other temporary files on the other hand is already functional. If a RAM-disk is selected for this path the linking process will be speeded up. All output from the C-LINT program is also put into this directory. In the dialog box is also a button called 'test'. When this button is used C-DESK will check all path and verify all programs that can be found at that location. A hook will be put at each successfully tested path. The button "OK" or "Cancel" will leave the dialog box either storing the data (OK) or forgetting it (Cancel). 3.4.5. Command "apropos" The main purpose of this command is to access an on-line help file which can be adapted to individual taste. After issuing this command a dialog box will be presented in which you can enter a pattern to search for. After clicking "OK" C-DESK will search in the file given in the "apropos" path entered using the "paths" command. All occurrences of the keyword in the file (usually the file "Apropos.txt") will be listed in an output window if the word can be found either in a title or a description. This on-line help file is an ASCII based file which can be edited to suit individual needs or usages. A few rules must be obeyed however : - a file must consist of 'entries' - each entry can maximally consist of 10 lines, each at maximum 80 characters long - the first line is called the title line - if an entry consists of more than 1 line, the first line must end with the character '~' (tilde) and all other lines of the same entry must begin with '~' (spaces before ~ are allowed). In the "Apropos"-file supplied with the system are descriptions about all functions of XDlibs, the standard library of Sozobon C, FLOAT, the floatingpoint library for Sozobon, and all AES- and VDI-calls. This file could be expanded with: - function descriptions of other libraries - C-DESK functions itself - help concerning the C-language itself - etc. 3.4.6. Command "options" The dialog box presented by C-DESK after selecting this command will enable you to set various options concerning the functions of C-DESK itself. - "wait for keypress after TOS-applications" When this option is enabled, C-DESK will wait after each TOS application for a keypress (any key), before it rebuilds it's desktop. This feature is interesting because the output of any TOS (.TTP or .TOS) program will be cleared by C-DESK redrawing it's desktop as soon as the programs terminates; thus in most cases you will only see a brief glimpse of the output and then C-DESK will be active again. With the option enabled the output window of the TOS program will stay on the screen until a key is pressed. (You would get the same action if the TOS application is started from a command line interpreter). If the "translate" command is given, however, this option will be ignored and C-DESK will only wait at the end of the translation if an error occurred. If this option is not selected, C-DESK will only wait if a TOS application terminates with a code other than 0. In most cases (by convention) a return code different from 0 means an error occurred while execution. Most likely, a message concerning the error will be on the screen. - "grow-/shrinkboxes" This option is activated by default and tells C-DESK to draw a growing or shrinking rectangle if a dialog comes on or goes off screen. - "keyboard-commands only with CONTROL-key" If this option is enabled any keyboard command will only be accepted if it is given by pressing the key and the single stroke shortcut key simultaneously. This option is not valid for any key combinations. - "dialogs at mouse position" If this option is activated any dialog box will appear at the actual mouse location. If the option is de-selected, dialogs will appear at their last position. - "show paths in source/library window" If the button is activated, all files will appear in the three mentioned windows preceeded by their actual path. Should the window become 'unreadable or cluttered', de-activate this button and only the file names will be listed. - "confirmations" If this button is activated a confirmation dialog is to be answered to continue in the following cases: - during file copy if the file already exists at the destination - during file deletion - before terminating C-DESK itself - to confirm the termination of a copy or delete action using the key - to confirm the termination of a pattern find action using the key - to confirm termination of translation using the key. - "mark changed files autom. in windows" With this option enabled, C-DESK will automatically update the source or library window files with a hook if the file in question has changed, thus automation the translation process. C-DESK is deciding for you what to translate the next time after editing or compiling. The following rules are used : - after an editor or program activation, C-DESK will check which files were changed, and will mark these files in the window because it is likely they will have to be translated the next time. - during translation C-DESK will un-mark those files which were successfully compiled The marking of the files is not binding for the user. You can still mark or unmark any file you want, anytime. - "only after EDITOR call" This option isby default enabled and will instruct C-DESK only to check for changed files after the Editor program has been used. This option will only work if the option "mark changed files autom. in windows" is enabled. Any program listed on the "Editor" line of the path's dialog will trigger this option. If this option is disabled, any program run from within C-DESK will cause the program to check for changed files. - "break compiling on warnigns" Any C-compiler (and also Sozobon) will abort the compiling process of a source code when errors are detected by the compiler. (These will be shown on the screen or in a window) The compiler may also issue warnings about possible non fatal errors. These warnings will not stop the compiler so if you want to see the warnings you should activate this option. - "Translation with:" - "compiler" If this option is enabled, all .C files will be compiled to .S files. - "optimizer" If this option is enabled the code optimizer will be started automatically after the compiler has completed (successfully). - "assembler" If this option is enabled, all .S files (output from compiler, optimizer or hand written files) will be translated automatically after the compiler or optimizer finishes. - "linker" If this option is enabled the linking process will be started as soon as the assembler finishes. 3.4.7. Command "find function" This command is an interface to the new program 'TAGFILE.TTP', written by Holger (me). This program generates a tagfile from all files of a project (all *.C files in the given directorys). The tagfile contains all function names, their prototypes, the file and line of definition and a list of all files scanned. Calling the function 'find function' will show a dialog with an edit field ('name') and the following buttons: - 'find' C-Desk will search the tag file (which must be in the same directory, as the compilat is) for the given function name. If found, the dialog will be filled with all the information in the tag file, and the 'edit' button will be selectable. - 'edit' This button is only selectable, if you have used the 'find' button before and C-Desk found the given Keyword. In this case he editor will be called witf the file name and the line number (if selected in the editor dialog), so you mustn't find the file and the line of the desired function yourself. - 'update' The 'TAGFILE' program will be called to update the data in the tag file (or to create the tag file) - 'cancel' The dialog will disapear. This function is most usefull when working on large projects or changing programs written by other people (f.e. the SOZOBON- compiler). 3.4.8. Command "save settings" This Command can only be used, if the name of the INF-File is already set (by 'save as' or 'load', implicit or explicit). C-DESK will save the settings as described below, except that no Fileselect box will apear. 3.4.9. Command "save settings as" C-DESK uses a parameter file to store it's settings; this file is by default called 'CDESK.INF'. This parameter file has a specific structure and can be recognized by the C-DESK program. After you have set up C-DESK for your personal taste, you can save these settings by issuing this command, and the program will remember all information, even about closed windows, list inside windows etc. This will allow you to stop C-DESK and start it up later again without noticing it was ever stopped. The command will result in a Fileselect box in which the last used setting's name will be displayed. You can change this name and the path in this dialog to whatever you want. A useful note : when you first start up C-DESK, set it up to your own wishes without any C-files etc. and then save these settings as f.e. 'DEFAULT.INF'. Then use these settings, add all the sources of one project and then save these new settings as a project related '.INF' file. You will then have project related settings (somehow like "make-file", maybe better). 3.4.10. Command "load settings" The settings of C-DESK can be loaded by this command. A Fileselect box will be drawn, and you can select the new parameter file, which will then be loaded, and all settings will immediately be adjusted according to the parameter file. The program will check if it is a valid file so no errors are to be expected (if we exclude malicious actions). If, on the other hand, some error occurred while writing the file (not enough disc space etc.) and the file would be incomplete, the behaviour of C-DESK will become unpredictable... maybe even crash the system. User of older version of C-DESK may experience that their old '.INF' files won't load any more. This only means that the structure has changed, and you should first use the update program ('CONVERT.PRG') for your old inf-files before trying to load them. Parameter files saved on an large-screen system can still be used on a standard-screen system because C-DESK will check the screen size and will adapt the coordinates if necessary. 3.4.11. Option "fast-redraw" This option is interesting only for those of you, who want to run C-DESK in color resolutions on a TT. On this computer, any 'fast redraw' causes a system crash (why ???), so if you are using a TT in color resolution, please klick this option once, for that this item hasn't a hook in front of it. If you have any suggestion about this problem, PLEASE let us know !!! 4. Windows 4.1. Types of windows Several types of windows exist (explained later) and any of these windows can be open, but only one window at a time is active (the op window). A non active window can be made active (Topped) by clicking on the window. Using the keyboard shortcut "W" will make all open window active one after the other (this is also called window cycling) 4.1.1. C-files window The window for C-source files (extension .C or .H) can be opened by double-clicking on it associated icon. The window will list all files entered into it, maybe even with the path if this option is selected. Each item in the window may have a hook in front of it. This means that that item (or file) in question will be translated as specified in the "options" dialog. See earlier. 4.1.2. Assembler files window The window for assembler files (extension .S) can be opened by double-clicking on it associated icon. Each item in the window may have a hook in front of it. This means that that item (or file) in question will be assembled during the translation process, as specified in the "options" dialog. See earlier. 4.1.3. Library window The library window in the C-DESK program contains libraries (extension .A or .LIB) and objects (extension .O) Each item (file) can be shown with or without it's full path (option setting) The library window will also hold all other project related files beside the libraries. A hook in front of an item means that the linker will use this file during it's execution. 4.1.4. Error message window If you are using one of the compilers modified for use with C-DESK, then an output window will be generated by C-DESK during the compilation part of the translation, containing possible errors. If this window is closed, it's contents is lost. 4.1.5. Directory This window is used to display the directory of a disc (floppy, RAM, hard disc). The window is opened by double-clicking on the directory icon. After this action a dialog box will appear in which you can select the drive for which you want to see the contents. In this dialog you can also enter three file-extensions type which will be displayed in the window. A '*' will display all types of files. Folders will always be shown. If you click "OK" in the dialog, the window will open showing the disc contents using the last used path. The items are sorted as specified in the "File" menu, and the window will look similar to the ATARI desktop. The window info line will list the number of files, and the total number of bytes used by all files for the files in the window. This window can also be opened by single clicking the directory icon with the right mouse button; the window will open using the last active path and the current extension selection. If the window is closed by the user, it's contents will be 'forgotten' by C-DESK. 4.2. The window elements Almost all standard GEM window elements are used and all have their normal function. Following extensions are build in, which are non standard implementations: - Single click on the vertical slider: if the slider is in the top position, C-DESK will calculate the window height needed to display all items in the window, and will adjust the height of the window accordingly, or expand to maximum height (depending on screen resolution). - Single click on the horizontal slider: if the slider is in the left position, C-DESK will calculate the window width needed to display the longest item in the window, and will adjust the width of the window accordingly, or expand to maximum width (depending on screen resolution). 4.3. Mouse clicks inside the windows 4.3.1. Click inside an inactive window This action will cause inactive window to become the top window (and thus the active window; action also called "Topping") The top bar of an active window is grey, of an inactive white. 4.3.2. Click inside an active window on an empty line If the window is a directory or error window, nothing will happen. For any other window, this click means you want to enter a file name in that window. In order to enter the file, the file- selectbox appears where you can select the apropriate filename. If this file already exists in the window, a warning will be given (this warning can suppressed), but nothing will happen. If you are entering a file in the C-files window, C-DESK will also check if there is already a corresponding object file item in the Library window. If not, C-DESK will create it, and will open the library window if not already open. If your project hasn't a name and the new entry is the first one in the window, C-DESK will create a name from the new entry, using the extension PRG. 4.3.3. Click inside an active window on an item Single left clicks on existing items will cause these items to toggle between selected and non-selected. Selected is indicated by showing the item in inverse video (white text on black background, if normal you see a white background with black text). This selection of items differs from the ATARI desktop because you can select multiple items in the active window even while you are scrolling in this window. A selected item will stay selected ! 4.3.4. Double click inside an active window Double clicking an empty line will have the same effect as single clicking on an empty line, see above. Double clicking on an item inside an active window results in diffenrent actions, depending on the window type: - in an C-source window or the assembler window, the editor program will be started, and the file name of the item passed to the editor using a command line; - if the double click happened in the error window, the editor will be started again, the file name, the line number and maybe the error-file will be passed to the editor with a command line. These are options which can be set in the editor dialog. Our modified version of the com- piler must be used or the error-file won't be generated; - in the library window, the library dialog will be started; - In the directory window the reaction will vary depending on the file type selected : - if the file selected is a program (*.TTP, *.PRG, *.TOS, *.APP) then this program will be started. (For *.TTP programs a command line will have to be entered as well); - if the double click happened on a folder, then this folder will be opened and it's contents will be shown; - for any other file type it will be assumed it is a text file and the editor will be started with the file name passed to it. 4.3.5. Click with the right mouse button A click with the right button will always select the item on which the click happened, whatever his previous state was. This is not a standard behaviour (which would mean toggle the state) but in this application it just makes more sense to always select it. The click will "pop up" a menu which will bring various options forward depending on the type of window. If no action is required, just click anywhere outside the menu. * In the directory window the only function available is "copy items"; all selected files will be copied to the other windows depending on their file extension : - *.C, *.H files are copied into the C-source window, *.C files will automatically be marked with a hook, *.H files not. - *.S files are copied into the assembler window and are automatically marked with a hook. - *.O, *.A and *.LIB files are copied into the library window also these files will automatically be marked with a hook. Files with other extensions will be ignored by this command. If files become copied into a closed window, then this window will be opened to indicate the above actions. A check will be made if the files are already present or not before the copy will take place and an appropriate warning will be given if file names are duplicated (and the depending option is enabled). * The function "library type" is only available in the library window, together with the commands that follow. If only one item was selected in the library window when this dialog was called, then one of the following buttons will be highlighted in the further appearing dialog, in which you can define the type of library item for the selected file(s) : - "Startup-Code" (STD.O, MIN_S.O, ACC_S.O etc.) the first item in the library window with this setting will be linked as first module. This module should contain the startup of the project (argc,argv, global variables, memory allocations etc). The module will only be linked if it has a hook in front of it. - "System Library" (XDLIBS.A, AESFAST.A, FLOAT.A etc.) all items in the library window marked with a hook will be linked after the project related modules. Files like XDlibs, libraries for AES, VDI etc should have this type. - "other" all object modules which should be linked and don't belong to any of the two types above should have this type. Files entered in the library window get this type by default. All modules of this type are linked directly after the startup- code. Most of the user written modules will have this type. * Following functions are only available with C-source, Assembler- source and Library windows : - "insert item" this option will allow inserting a new item in top of the item selected. Selection of the new item will take place using the Fileselect box. If the file selected is not a *.H file then it will automatically get a hook in front. In the library window, the type will be the same as the item that follows. Automatically a check will be made for duplicate names. Should this happen an (optional) warning will be given and no action will be taken. If your project has no name and the new entry is the first one in the window, C-DESK will create a name from the new entry, using the extension PRG. - "delete item(s)" all selected items are removed, lines deleted. - "overwrite item" basically the same action than insert item, except that this overwrites an item instead of insert a new line. - "check/uncheck item(s)" this item will toggle the status of the selected files; files with a hook in front will have it removed and vica versa. - "new path" with this function you can change the path for all selected files. This can be useful when changing drives or RAM disc to floppy etc. WARNING : if this function is used, only the active window will be aware of this change. You must take care of the update of other windows. If the path of an object module gets changed, you should also change the path of the source file! 4.3.6. Click with Control key pressed The same action as "check/uncheck item(s)" explained in the previous point; all selected items get checked or unchecked. 4.3.7. Double-click with Alternate key pressed If the user click on an item in this way, the contents of the item in question will be shown on the screen. 4.3.8. Move the mouse with mouse button pressed As on the ATARI desktop, you can select several items in a window by drawing a hollow "rubber box" on top of them. All items in the "box" become selected if they weren't, and deselected if they were (selection state of the item will toggle). This action can be performed also while simultaneously pressing the right mouse button, the or key. If this is done, the action will be analog those on a single item, except that it will work on several (see previous item for the individual actions performed). 5. Icons 5.1. Using the icons The icons visible on the C-DESK desktop can be manipulated as if they were on the ATARI desktop, using the mouse. - if you click on an icon and keep the button pressed, the icon can be moved on the desktop. The icon can be placed anywhere on the desktop in a fixed 8 x 8 pixel grid (this grid is for easier positioning of the icons) - if you click on the icon with the right mouse button then a dialog related to the icon will appear in which you can set all functions concerning this icon. Most often you can start the attached action of the dialog from this dialog. There will be no action for the Window icons; - if an icon gets selected with a double click, then the action attached to the icon will be started without any dialogs appearing. 5.2. The installation of icons Not every user of C-DESK needs all possible Icons of this program. Therefore it is possible to hide the unused icons. 5.3. The system icons 5.3.1. Project The icon attached to the project. 5.3.2. C-files A double click on this icon will open the window for the C-Sources sources and/or will make it the top (active) window. 5.3.3. Assembler files A double click on this icon will open the window for the assembler sources and/or will make it the top (active) window. 5.3.4. Library A double click on this icon will open the window for the System and User libraries and/or will make it the top (active) window. 5.3.5. Disk Using this icon the user can open or top the Directory window. A double click on this icon will trigger a dialog in which you can select the drive and up to three file extensions to be displayed (* as file extension will display all). This dialog can be called by double clicking the icon even if the window is already open. If you click on this icon with the right mouse button then the usual dialog box will not appear and the window will open using the last path and file extensions. The keyboard can also be used for the opening of the directory window, or moving it to the top, with a direct drive selection using the keypress for drive A:, for drive B: etc. 5.3.6. Information icon This icon is always on the desktop and cannot be removed. It contains following information : - old and new file length of the compiled project (for comparison while optimizing) - the time the project needed for the last run - activated elements of the translation process ('C'->compiler,'O'->Optimizer, 'A'->Assembler, 'L'->Linker, 'D'->Debugger). 5.3.7. Editor icon When right-clicking on this icon, the same dialog will appear, as from the menu. See there. If double-clicking this icon, the editor programm will be started as if you've typed ([CRTL])"E". See there. 5.4. The utility icons C-DESK gives you the possibility to install 8 icons which have no program attached to it. Instead of having to go to the Directory window and search and start a program, you can attach any program to one of the seven utility icons, install the icon, and then launch the attached program by double clicking on that icon. By using command line prototypes (see later) you can pass arguments to these programs. If you install one of the icons, a dialog will appear asking you to select the program to attach to it. After the icon appears on the desktop, open the dialog for this icon using the right mouse button. You will now be able to enter the command line prototype and the icon will behave as any other system icon. All icons were created using an icon editor called BED. This editor is written by Holger (yes again) and can be obtained directly from him using the standard public domain conventions. (see the start of this manual). The "graphic artist" was Frank who designed the icons using BED. His critics and bug reports helped a lot in the programming of BED. The newer Icons were created with C-ICON, written by Holger Weets & Frank Specht. 6. Command line prototypes 6.1. Basics - parameters can always be passed to the starting program; - it is possible to define for each program how many arguments there will be passed. (none is also possible); - it is possible to enter parameters using the fileselect box or the keyboard; - non-changing paramerters (options etc.) in the command line will have to be entered only once. 6.2. The interpretable symbols Following symbols have a meaning during the interpretation of a command line. The '{}' brackets indicate an optional item. - $f {[TEXT]} The Fileselect box will be called and you can select a file. If the dialog is ended using "OK"-button then the selected filename will be passed as argument. If "Cancel" is used, then the command will be removed from the command line. If you used the [TEXT] option, the text you entered between the brackets will appear above the Fileselect box (without the [] brackets). Example: $f[Edit file] C:\GLOBALS.H The command interpretation will be : 1: the Fileselect box appers with "Edit file" above it, and you can select a file; 2a: the dialog was ended with "OK" or a double click on the file name (f.e. TEST.C); the resulting command line is TEST.C GLOBALS.H. 2b: the dialog was ended using "Cancel"; the command line is GLOBALS.H 3: if no other symbols are found, the resulting command line is passed to the called program. - $F{[TEXT]} The same as $f but when the Fileselect box is ended using the "Cancel"-button, the interpretation of the command line is stopped and the program will not be started. - $k If the interpreter finds this symbol in the command line then it will present a dialog containing the existing command line, and the user can edit the command line using the keyboard. There can only be one "$k" in a command line, any others will automatically be removed. If the edit-dialog is ended using the "Cancel"-button then none of the edits will be taken in account and the old (existing) command line will be passed to the program. - $K The same as $K but when the edit-dialog is ended using the "Cancel"-button, the interpretation of the command line is stopped and the program will not be started. - $. The filename last selected using the Fileselect box will be passed as a parameter but with the extension instead the one from the Fileselect box. This "last selected" file selection could have happend in a command line but could also have happened earlier for example during the last editor call. The signs '<' and '>' don't have to be typed. Example: $F[Edit file] -o $.O The command interpretation will be : 1: the Fileselect box appers with "Edit file" above it, and you can select a file, we assume TEST.S was selected. The command line now looks like 'TEST.S -o $.O' 2: the "$." symbol makes the interpreter change the TEST.S file in TEST.O; and writes it at that place; the resulting command line is now TEST.S -o TEST.O 3: This final result is now passed as a parameter line to the called program. - $C This symbol will be replaced with all the file names from the C-source window having a hook in front. - $c This symbol will be replaced with all the file names from the C-source window which are inverted. - $S This symbol will be replaced with all the file names from the Assembler source window if they have a hook in front. - $s This symbol will be replaced with all the file names from the Assembler source window if they are inverted. - $O This symbol will be replaced with all the file names from the Library window if they have a hook in front. - $o This symbol will be replaced with all the file names from the Library window if they are inverted. 6.3. The sequence of evaluation The symbol are interpreted in a specific order : 1: all '$C' and '$c' symbols 2: all '$S' and '$s' symbols 3: all '$O' and '$o' symbols 4: all '$F' and '$f' symbols 5: all '$.' symbols are evaluated 6: all '$K' and '$k' symbols The position for the '$.' symbols has for consequence that the selected file name will be filled in everywhere the symbol is in the command line. It is impossible to use this symbol for more than one filename. 7. C-DESK, Sozobon C & Floatingpoints The use of floating points with the SOZOBON-C system can lead to some problems mainly due to the absence of documentation. (Don't blame C-DESK) If you are using floating point calculations but you don't need INPUT (using scanf()) or OUTPUT (using printf()) there is no problem. Simply put a hook in front of the floating point library and link it with the project files. If, on the other hand, you are using scanf() and/or printf() the following setup will be required : 1: open the Linker dialog ("C-system / linker") 2: complete the edit field "-u undef" with "__scanf" if scanf() is used with floating point numbers 3: complete the edit field "-u undef" with "__printf" if printf() is used with floating point numbers 4: put a hook in front of the floating point library 5: relink the complete project 6: start the project and smile, everything works now. Why, you might ask yourself, all this trouble. Well, these two functions exist twice; once with and once without floating point arimethic. (Without it will generate shorter code, and is the default) The Floating point library is sorted such that the linker won't use the function scan and printf from this library but from the XDlibs library (even when you are using floating points in your program; for shorter code purpose) Only the above "tricks" will force the linker to use the functions from the floating point library. 8. Keyboard Many C-DESK functions can also be activated by keyboard shortcuts (with or without option). Here is a list of them : - A : Archiver program gets started - C : C-Lint program gets started - D : Debugger program gets started - E : Editor program gets started - F : Find pattern - G : GEM RSC-Editor will be started - I : file info - L : Linker will be started - O : Options dialog will open - P : Paths dialog will open - Q : Quit C-DESK program - R : Run the project program - S : Select all items in the top window - T : Translate the project - U : select all changed files - V : View file (contents) - W : Window cycling (make all windows active one by one) - F1: toggle Compiler on and off ('C' in System-Icon) - F2: toggle Optimizer on and off ('O' -"- - F3: toggle Assembler on and off ('A' -"- - F4: toggle Linker on and off ('L' -"- - F5: toggle Debugger on and off ('D' -"- - shift F1 : - shift F2 : - shift F3 : - shift F4 : - ESC : if the directory window is open and active, it's contents will be refreshed. - DEL : delete files or folders (confirmation will be asked) - HELP : find function - UNDO : close the active window - CURSOR UP : scroll the active window 1 line up - CURSOR DOWN : scroll the active window 1 line down - Ctrl CURSOR UP - Ctrl CURSOR DOWN - HOME - shift HOME - shift A : display first entry starting with 'A' in dir . . . - shift Z : display first entry starting with 'Z' in dir - A : display contents drive A: in directory window . . . . -"- -"- . . . - P : display contents drive P: in directory window - F1 : start programm from 'function keys' dialog . . . - F10 : -"- 9. Known Bugs - If you activate an accessorie which opens a window, make sure you close this acc-window before any program is started. Failing to do so may result in a system crash. We are investigating why this happens, but haven't isolated the problem yet. - If you run a programm under C-DESK make also sure, that you close all ACC-windows before terminating the programm. Otherwise C-DESK will close these windows, guessing that they are unclosed application windows, and this will result almost surely in a system-crash. - C-DESK is not well-tested with TOS 1.00 or TOS 1.02. Also we did not have many oportunities for testing it in any of the color resolutions. Curious result could maybe exist in those cases, please let us know if you encounter them. - There will be probably more bugs (nobody is perfect), but at this moment none are known to us. Please keep testing the program and drop us a line if you find any more bugs. Thank you. Lots of fun and "creative work", Holger Weets and Frank Specht.