home *** CD-ROM | disk | FTP | other *** search
/ ST-Computer Leser-CD 2001 January / LCD_01_2001.iso / updates / xaaes904 / docs / usrguide.txt < prev   
Encoding:
Text File  |  2000-11-12  |  11.1 KB  |  328 lines
  1. XaAES User Manual
  2. (W)Craig Graham (c_graham@patrol.i-way.co.uk)
  3.  
  4. Most of this text is left unchanged from what Craig wrote earlier, but
  5. a few things need to be pointed out:
  6. - XaAES can be started from inside GEM as any normal program. In fact,
  7.   that's the only way I've got it to run lately, but that may depend
  8.   on my hardware and/or software setup. If you run it that way, only
  9.   the current screen mode can be used.
  10. - There are some new possibilities with the XAAES.CNF file. For example,
  11.   debug output can be turned off and direct calls can be turned on.
  12.   See that file for more information.
  13. Johan Klockars   (rand@cd.chalmers.se)
  14. 980714
  15.  
  16. I never tried to start XaAES from inside GEM
  17.  
  18.  
  19. |    New in v0.8 is marked |
  20.  
  21. |    The built in fileselector is greatly improved.
  22. |    Especially TOS 8+3 names are displayed in upper case
  23.         (like most desktops do).
  24. |    Size adapted to screen size.
  25. |    Full scrollable list box.
  26. |    Very much like Selectric. But without all the desktoplike features.
  27. |    Hey! its multitasking, you can reach the existing desktop!
  28.  
  29. Henk Robbers    (h.robbers@cable.a2000.nl)
  30. 000904
  31.  
  32.     1) INSTALLATION
  33.     -------------------
  34.  
  35.     Installing is pretty easy, just do the following:
  36.  
  37. |    i) Stick these files all in one directroy: lets say <path>
  38.        xaaes.tos    - The kernal
  39. |       xaaesdbg.tos - The kernel compiled with debugging statements
  40.        xaaes.cnf    - Like GEM.CNF, but for xaaes.
  41. |       xaaes.rsc    - various kernal GUI elements (menu, alert template, etc)
  42. |       xaaeswdg.rsc - All the window gadgets
  43. |
  44. |    ii) Copy the mouse device driver 'vmoose.xdd' to one of:
  45.         c:\multitos
  46.         c:\mint
  47.         c:\
  48.         Your auto folder
  49.  
  50.     iii) If you want a console shell (the xaaes.cnf file is set up to give you
  51.         one), you should edit the xaaes.cnf file so it runs your fave shell
  52.         (I use sh, but mupfel, etc will work as well).
  53.  
  54.     iv) Add these lines to your MiNT.CNF file:
  55.  
  56. |          cd <path>
  57. |          GEM=xaaes.tos   ... cq  xaaesdbg.tos
  58. |
  59. |        If XaAES fails to find its cnf and rsc this way,
  60. |         it will look in the following paths:
  61. |             c:\mint
  62. |             c:\mint\xaaes
  63. |            c:\multitos
  64. |            c:\multitos\xaaes
  65. |             c:\gemsys
  66. |             c:\gemsys\xaaes
  67. |             c:\
  68. |            c:\xaaes
  69.  
  70.          Alternatively, if you are a bit more of a techie, XaAES will run
  71.          happily from a command line (and let you exit back to it) or as a
  72.          login shell.
  73.  
  74.     Ok, thats it.
  75.  
  76.     1.1) COMMAND LINE ARGUMENTS
  77.  
  78.  
  79. |    mode or
  80. |    modecode can be a octal number like o7
  81. |                    a hex number   like x26
  82. |                    a bit pattern  like b11010
  83. |                    a decimal number as usual
  84.  
  85.     XaAES has the following command line arguments:
  86.  
  87.     1.1.1) Standard Atari Video Mode Select
  88.  
  89.              -video <mode>
  90.  
  91.     Selects the video mode that XaAES will boot into where <mode> is:
  92.  
  93.           2 = 320*200, 16 colour (ST-Low)
  94.           3 = 640*200, 4 colour (ST-Medium)
  95.           4 = 640*400, 2 colour (ST-High)
  96.           6 = 640*480, 16 colour (TT Medium)
  97.           8 = 1280*960, 2 colour (TT High)
  98.           9 = 320*480, 256 colour (TT Low)
  99.  
  100.     These numbers are simply the VDI physical workstation id's that
  101.     are assigned to each video mode. If you have a strange video card,
  102.     use whatever workstation ID your card's driver is assigned to.
  103.  
  104.     You should use this if you have an ST/TT - it will work on a falcon
  105.     but you will get better performance by using the -fvideo switch 
  106.     instead.
  107.  
  108.     1.1.2) Falcon Video Mode Select
  109.  
  110.         -fvideo <modecode>
  111.  
  112.     Select a falcon video mode, where <modecode> is a video modecode
  113.     as used by the VsetMode() OS call. The format of this is:
  114.  
  115.         BIT    Name    Meaning
  116.         0-2    BPS    Number of bitplanes:
  117.                     000=2colour
  118.                     001=4colour
  119.                     010=16colour
  120.                     011=256colour
  121.                     100=16bits/pixel (True colour)
  122.         3    COL    Number of columns
  123.                     0=40
  124.                     1=80
  125.         4    VGA    Monitor select
  126.                     0=TV mode
  127.                     1=VGA mode
  128.         5    TVSEL    TV standard select
  129.                     0=NTSC
  130.                     1=PAL
  131.         6    OVERSCN    Overscan flag (not valid for VGA)
  132.                     0=don't overscan
  133.                     1=overscan
  134.         7    STMODES    ST Compatibility mode
  135.                     0=Standard VGA video modes
  136.                     1=ST Compatible Video modes
  137.         8    VERTFLAG Vertical mode
  138.                     VGA:
  139.                         0=standard
  140.                         1=line doubling (half res)
  141.                     TV:
  142.                         0=standard
  143.                         1=Interlace (double res!!!)
  144.         9-15    unused
  145.  
  146.     For example, 'xaaes -fvideo 26' will select 640*480*16colour VGA mode.
  147.  
  148.     This should work with video expanders (it works fine with 
  149.     FalconScreen) and with NVDI (I've tried it with NVDI4).
  150.                                      
  151.     2) Using XaAES
  152.     -----------------
  153.  
  154.     2.1) Menus
  155.  
  156.     Generally XaAES is like GEM, but with a few exceptions. Most notably,
  157. |    menu's can be Mac-style pull down, or GEM style drop down.
  158. |    Mac style: you've got to click on a menu title to see the menu.
  159. |    GEM style: just point at it.
  160.  
  161. |    This is governed by the 'menu' config statement.
  162.  
  163.     2.2) Typing            
  164.  
  165. |    XaAES can be point-to-type - so keyboard input goes to the window under the
  166.     mouse and NOT to the top window. This depends on compile time flags - check
  167.     the boot message to see if this feature is active.
  168. |   Is completely disabled in v0.8
  169.  
  170.     3) XaAES Keyboard Combo's
  171.     ----------------------------
  172.  
  173.     There are a couple of keyboard combo's that XaAES uses for itself. These are:
  174.  
  175.     CTRL+ALT+TAB     : swaps menu bars, not top windows.
  176.     CTRL+ALT+L       : Activate the 'Task Manager' window.
  177.     CTRL+ALT+S       : Output a status dump to the debug file
  178.     CTRL+ALT+K       : Clean up - search for dead clients that didn't call
  179.                        appl_exit
  180.     CTRL+ALT+R       : Attempt to recover control of a hung system - use as a last
  181.                        resort, as this will kill the clients that are blocking
  182.                        the system.
  183.     CTRL+ALT+D       : Toggle debug output (if enabled at compile time)
  184.     CTRL+ALT+C       : Shutdown immediately, killing all clients.
  185. |    CTRL+ALT+M       : Recover the mouse.
  186. |    CTRL+ALT+Home    : Recover screen and mouse.
  187.  
  188.     NOTE: CTRL+ALT+S only outputs anything if GENERATE_DIAGS was turned on at
  189.     compile time - in the binary distributions released by me (Craig) they will
  190.     have no effect as all diagnostics are turned off.
  191.  
  192.     4) SYSTEM MENU
  193.     ---------------
  194.  
  195.     The XaAES system menu (CTRL+ALT+TAB until you get it) currently contains two
  196.     useful options.
  197.  
  198.     One is the 'About XaAES...' option which (surprisingly) brings up a nice
  199.     little descriptive box.
  200.  
  201.     The other (more useful) option is in 'Shutdown'. This will kill all GEM
  202.     programs and exit XaAES gracefully. Unlike MultiTOS, if you ran XaAES from a
  203.     command line or as a login shell, you will be returned to the command line or
  204.     login prompt. You can then re-start XaAES, or do whatever - XaAES can be
  205.     exitted and restarted as many times as you like without rebooting the machine.
  206.  
  207.     XaAES catches CTRL+ALT+C and CTRL+ALT+\  (SIGINT & SIGQUIT respectively) and
  208.     executes the shutdown procedure in response to them, so you should be able to
  209.     get back to your command line in most situations.
  210.  
  211.     4.1) TASK MANAGER
  212.     ------------------
  213.     The 'Process' menu of the XaAES System menu also contains the
  214.     'Task Manager' option. This opens a window with a scrolling list
  215.     of current AES client applications. This is not a list of all
  216.     MiNT processes, it's only a list of GEM programs.
  217.  
  218.     The Task Manager allows you to suspend, resume, kill and launch
  219.     GEM programs.
  220.  
  221.     The icons next to each list entry represent the app status
  222.     (Application awake, Accesory awake, Sleeping/suspended, messages
  223.     pending, owns lock, etc).
  224.  
  225.     There is a set of icon buttons at the top of the window
  226.     (from left to right):
  227.  
  228.     o Launch
  229.       Launch a new GEM program. A file selector will prompt you for
  230.       the filename.
  231.  
  232.     o Trash
  233.       Kill the task that is selected in the task list.
  234.  
  235.     o Sleep
  236.       Put the selected task to sleep. This will hide all it's windows
  237.       and send SIGSTOP to the process to suspend it.
  238.  
  239.     o Wake
  240.       Wake up the selected task. This is the opposite of Sleep, and
  241.       will restore all the app's windows (on top, in the order the app
  242.       had them) and send SIGCONT to let the process continue.
  243.  
  244.     As previously mentioned, CTRL+ALT+L will also open the Task Manager.  
  245.  
  246.     6) WINDOW SCROLLING
  247.     --------------------
  248.  
  249.     Scroll bars are extended from the usual GEM style to be similar to WinX's
  250.     behaviour. Clicking and dragging the scroll bar with the right hand button
  251.     will work the same as normal GEM. Clicking and dragging with the left hand
  252.     button will do REALTIME/LIVE scrolling, where the window will update as you
  253.     move the mouse (not just when you release it as in the standard GEM behaviour).
  254.     This is nice for programs that have fast window updates, but is annoying for
  255.     old/slow programs (which is why it's on a seperate button).
  256.  
  257.     7) THE xaaes.cnf FILE
  258.     -----------------------
  259.  
  260.     This is a bit like MultiTOS's GEM.CNF file. It's main purpose is to let you
  261.     auto-launch programs as XaAES starts up. Generally the syntax of this is
  262.     supposed to be the same as Atari's GEM.CNF file
  263.  
  264.     It's a simple text file with the following format:
  265.  
  266.     i)   '#' is a comment line.
  267.     ii)  Commands are not case sensitive (although paths may be, depending on
  268.          your filesystem).
  269.     iii) If a command isn't understood, it gets ignored...
  270. |    iv)  Some of the commands are :
  271.  
  272. |             string <name> <=> <character sequence>
  273. |                Define a environment variable.
  274. |                NOTA BENE: variables must be decared BEFORE any run, desk or shell
  275.  
  276. |                'export' and 'seten'v are synonyms for 'string'
  277.  
  278.              debug <file/device>
  279.                 Set debugging output to <file/device> (default is .\debug.list)
  280.  
  281.              clipboard <directory>
  282.                 Set the GEM clipboard to be in <directory> (default is c:\clipbrd).
  283.  
  284.              accpath <directory>
  285.                 Set the location that XaAES will try to load accessories 
  286.                 from (default is c:\).
  287.  
  288.              run  <program> <parameters....>
  289.                 Launch a program.
  290. |             desk  <program> <parameters....>
  291. |             shell <program> <parameters....>
  292. |                Launch the desktop.
  293.  
  294.     An example xaaes.cnf file (in fact, the one I use)
  295. |    can be found in the distrubution.
  296.  
  297.     8) Programs That Run As APP/ACC.
  298.     ---------------------------------
  299.  
  300.     Several programs that run as either APP or ACC will fail to
  301.     run correctly (or at all) under XaAES. For some reason (don't
  302.     ask why) many of these (for example ST-Guide) will fail if run
  303.     as:
  304.         c:\stguide.app
  305.     but will work fine if run as
  306.         u:\c\stguide.app
  307.     Now, these should be the same path with the same behaviour, but
  308.     there appears to be a subtle differance in the way Pexec() works
  309.     if you launch a u: relative path. So, instead of clicking on st-guide
  310.     in a c: window from Thing, use the u:\c\ window instead...
  311.  
  312.     x) Caveats
  313.     --------------
  314.  
  315. |    Craig:
  316.     I've compiled  out most of the diagnostics, but if you get funny messages on
  317.     the screen, add the line 'debug \dev\null' to the xaaes.cnf file.
  318.  
  319.     Loads of stuff is missing at the moment, don't hassle me - fix it and get
  320.     back to me.
  321.  
  322. |    Henk:
  323.     I would say only a few things are missing at this moment.
  324.     A binary distribution contains 2 binaries:
  325.         xaaes.tos        debugging compiled out. The fast one.
  326.         xaaesdbg.tos    All debugging available. So will be slow!
  327.  
  328.