home *** CD-ROM | disk | FTP | other *** search
/ Amiga Elysian Archive / AmigaElysianArchive.iso / wp_dtp / leggi2v1.lha / Leggi.doc < prev    next >
Text File  |  1992-12-04  |  56KB  |  1,728 lines
  1.  
  2.  
  3. *
  4.  
  5.    This file describes `Leggi' 2.0, a freeware text reader utility featuring
  6. unlimited number of windows on any public screen, scrolling with both mouse
  7. and keys, full AUISG menus and ARexx commands, clipboard support,
  8. AppWindows, fast & residentable activator, full configurability of the
  9. keyboard, settings file which stores even the window position and size,
  10. preferences editor which lets you directly edit settings files, background
  11. mode, standard clock pointer for long operations, fully documented IFF
  12. settings file, support for the ISO/ANSI color/style sequences and for the
  13. backspace character, selectable window refresh type, PowerPacked file
  14. support and more.
  15.  
  16. Copyright © 1990,1991,1992 Sebastiano Vigna
  17.  
  18.  
  19. Introduction
  20. *************
  21.  
  22.    `Leggi' is a rather flexible text reader which I developed some time ago
  23. with two main goals in my mind: first of all, supporting a simple subset of
  24. the IFF FTXT specification, enough to describe multi-font text files, and
  25. secondly being also a good Amiga application--ARexx support, font adaptivity
  26. and so on.
  27.  
  28.    The former goal turned out to be a dead end: indeed, no one was
  29. interested in the FTXT support; the latter one was achieved *theoretically*,
  30. but a lot of bugs and some misfeature made `Leggi' 1.x much less widespread
  31. than I would have liked. My fault anyway. On the other hand, `Leggi''s
  32. specification was a little bit ahead of its times--there was a real lack of
  33. system support for many things (for instance, a simple but transparent
  34. system tracking of the allocation sizes, or a system command line parser).
  35.  
  36.    With Release 2, Commodore eventually produced a beautiful programming
  37. environment in which the routine part of the programmer's work is left to
  38. the operating system. This urged a revision of `Leggi'.
  39.  
  40.    What really happened is that `Leggi' was completely recreated. I'm not
  41. only meaning rewritten--even the specification and the user interface was
  42. radically changed. Since most of `Leggi''s functions were considered in the
  43. `Amiga User Interface Style Guide' (AUISG), Commodore staff's suggestions
  44. were taken as the primary source when designing new functions and while
  45. updating the old ones. At the same time, dropping the support for 1.2/1.3
  46. brought the power of Release 2 (version 2.04) to the program (just to
  47. mention an example, `Leggi' had previously to emulate the whole
  48. `LayoutMenus()' function in gadtools.library). Finally, dropping the FTXT
  49. support (and consequently the handling of multi-font documents) reduced
  50. greatly the size of the code.
  51.  
  52.    The result is a fully AUISG-compliant application, with lots of new
  53. Release 2 related features and no more bugs. I can resume in a couple of
  54. word what you will miss with `Leggi' 2.0: 1.2/1.3 and FTXT support. What you
  55. will get, instead, is:
  56.  
  57.    * Faster text rendering/scrolling operations;
  58.  
  59.    * Better keyboard/mouse handling (scrolling with cursor keys is no longer
  60.      slower than scrolling with the mouse);
  61.  
  62.    * Full AUISG menus and ARexx commands;
  63.  
  64.    * Dozens of new ARexx commands that allow fine control of the window
  65.      position and placement, displayed part of the document, etc.;
  66.  
  67.    * Clipboard support--display the content of any clip in a `Leggi' window,
  68.      or copy a displayed file to it;
  69.  
  70.    * AppWindow support--drop a file icon in a `Leggi' window and the file
  71.      will be loaded;
  72.  
  73.    * Public screen support--open each window on a different public screen;
  74.  
  75.    * Fast & residentable activator (à la `CED' and `TurboText');
  76.  
  77.    * Full configurability of the ARexx port (both global and local);
  78.  
  79.    * Full configurability of the keyboard--any ARexx command can be assigned
  80.      to any keystroke;
  81.  
  82.    * Settings file which stores even the window position and size;
  83.  
  84.    * Preferences editor which lets you directly edit settings files;
  85.  
  86.    * Background mode--`Leggi' remains active even when the last window is
  87.      closed, and will restart via the activator or via an ARexx command;
  88.  
  89.    * Standard clock pointer for long operations--if you use an animation
  90.      utility such as `ClockTick' you will get a spinning hand, too;
  91.  
  92.    * Beautiful 3-D scrolling gadget;
  93.  
  94.    * Faster load operations;
  95.  
  96.    * Fully documented IFF settings file;
  97.  
  98.    * Support for the backspace character;
  99.  
  100.    * Release 3 new look menus support.
  101.  
  102.    Before you ask:  "leggi" in Italian means "read", and I am told it is
  103. pronounced "leeji" in English.
  104.  
  105.  
  106. Usage
  107. ******
  108.  
  109.    This chapter describes how to use `Leggi'. After a brief, idiotproof
  110. introduction a thorough explanation of the various interfaces follows.
  111.  
  112.  
  113. First Steps
  114. ============
  115.  
  116.    The usage of `Leggi' is extremely straightforward. Double click on its
  117. icon, and then open a file using the `Open...' item of the `Project' menu.
  118. You can even drop a file icon over `Leggi''s window, and the file will be
  119. automatically loaded (that is, the window is an Application Window). If you
  120. prefer to use a Shell, you can type
  121.  
  122.      Leggi FILENAME
  123.  
  124. instead. Once loaded a file, you can move around using the scroll bar, the
  125. cursor keys or by clicking in the upper or lower region of the window.
  126.  
  127.    The `Settings' menu allows you to customize the text display; in
  128. particular, you can try to change the display font using the `Set Font...'
  129. item, and to add some interline space using the `Set Line Spacing...' item.
  130.  
  131.  
  132. The Workbench Interface
  133. ========================
  134.  
  135.    `Leggi' is clearly a GUI based application. It has full support for
  136. tooltypes, which can be specified both in the tool icon and in the project
  137. icons. This allows to control both global and local settings from the
  138. Workbench (see Settings).
  139.  
  140.    The available tooltypes closely match the keywords available on the
  141. command line. They are described shortly here, and more detailed information
  142. can be found in The CLI Interface.
  143.  
  144. `PubScreen=PUBLIC SCREEN NAME'
  145.      lets you specify a public screen name.
  146.  
  147. `Settings=SETTINGS FILE NAME'
  148.      lets you override the default settings file name
  149.      (`PROGDIR:Leggi.prefs').
  150.  
  151. `Background=On|Off'
  152.      when set to `On' tells `Leggi' to not exit definitively when the last
  153.      window is closed or when asked to quit. Rather, it will wait for a
  154.      command at its main ARexx port (usually this command will be sent by
  155.      the activator). This allows you to keep `Leggi' always active (possibly
  156.      by starting it in the startup-sequence or via the `WBStartup' drawer)
  157.      and to activate one of its windows on your preferred public screen when
  158.      needed. Since leggi uses less than 30K of memory, this can be a very
  159.      pratical option for users with memory expansions.
  160.  
  161. `NoGUI=On|Off'
  162.      when set to `On' tells `Leggi' to not open the first window, and rather
  163.      waiting in the background until a command arrives from the activator or
  164.      from ARexx. It implies a `Background=On'.
  165.  
  166. `PortName=AREXX PORT NAME'
  167.      overrides the default port name, which is `LEGGI' for the main port,
  168.      and `LEGGI.N', where N is the window number, for the window ports. You
  169.      can override the global name (and thus all the subsequently derived
  170.      window names) by putting this tooltype in the tool icon, or override
  171.      the local window port name by putting it in the project icon.
  172.  
  173.    The `PubScreen', `PortName' and `Settings' tooltypes are available for
  174. inclusion in project icons or in the activator tool icon (see The
  175. Activator), while the other tooltypes are only available in the `Leggi' main
  176. program tool icon. Of course, when included in the activator or project
  177. icons, they refer to local settings, and when included in the main program
  178. tool icon, they refer to global settings (see Settings).
  179.  
  180.  
  181. The CLI Interface
  182. ==================
  183.  
  184.    While being a GUI oriented application, `Leggi' has a full-featured CLI
  185. interface. By typing
  186.  
  187.      Leggi ?
  188.  
  189. you can get the template in standard AmigaDOS format, which is:
  190.  
  191.      Files/M,PubScreen/K,PortName/K,Background/S,NoGUI/S,Settings/K
  192.  
  193.    The template of the activator (see The Activator), instead, is
  194.  
  195.      Files/M,PubScreen/K,PortName/K,Settings/K,Wait/S
  196.  
  197. `Files'
  198.      is filled by an arbitrary number of file name specifications, possibly
  199.      containing AmigaDOS wildcards. Each file will be loaded in a different
  200.      window.
  201.  
  202. `PortName'
  203.      lets you specify an ARexx port name which will override the internal
  204.      name generation of `Leggi'. When included in the main program command
  205.      line, it sets the global port name, while if included in the activator
  206.      command line, it sets the local port name. Note that if you open
  207.      several file via the activator using multiple filename/wildcards and you
  208.      specify a `PortName' keyword, all opened windows will get the same port
  209.      name, probably causing confusion when trying to control one of them via
  210.      ARexx.
  211.  
  212. `PubScreen'
  213.      lets you specify a public screen name which `Leggi' will open its
  214.      window on (by default, they are opened on the default public screen).
  215.      The name is set globally or locally, depending on the calling program,
  216.      just as for the `PortName' argument. An unexisting public screen name
  217.      will keep `Leggi' from opening any window. Note that the name is case
  218.      sensitive.
  219.  
  220. `Settings'
  221.      lets you specify a settings file name to open instead of reading the
  222.      default file at startup or cloning in the standard way global or local
  223.      settings. See Settings.
  224.  
  225. `Background'
  226.      tells `Leggi' to stay forever in the background even when the last
  227.      window is closed or when asked to quit, waiting for a command from the
  228.      activator or from ARexx.
  229.  
  230. `NoGUI'
  231.      tells `Leggi' to not open the first window, and rather waiting in the
  232.      background for a command. It implies a `Background' switch, even if not
  233.      explicitly present.
  234.  
  235. `Wait'
  236.      tells the activator to not return until the window has been closed
  237.      (much like the `Wait' switch of `TurboText').
  238.  
  239.  
  240. The activator
  241. ==============
  242.  
  243.    In the same vein of other Amiga programs, `Leggi' has an activator, named
  244. `LG'. `LG' is a very short, residentable program which sends to the main
  245. program messages telling it to open certain windows, load certain files et
  246. cetera. `Leggi' is not residentable, but it doesn't need to be, since just
  247. one copy needs to be loaded (you can open different windows, with specific
  248. port names on different public screens using a single copy of `Leggi').
  249.  
  250.    Unless you have special needs (for instance, you could want to run
  251. `Leggi' in the background with the `NoGUI' option and some special settings
  252. file from your startup-sequence), you should always invoke `Leggi' through
  253. `LG'. `LG' checks if a copy of `Leggi' is present (it does it by checking
  254. for a port name `LEGGI'; if you started a copy of `Leggi' with another main
  255. port name, you can't use `LG' with it), and if so it sends it a series of
  256. messages by which `Leggi' learns what it has to do (opening windows, loading
  257. files, using certain settings files, etc.). If no copy of `Leggi' is active,
  258. it launches a `Run Leggi >NIL: <NIL: NoGUI' command, and then tries again
  259. for a number of seconds. If the `LEGGI' named port doesn't appear, it gives
  260. up.
  261.  
  262.    Note that since under Release 2 a program can get the directory it belongs
  263. to, you can store a `Leggi.prefs' file in the same directory as of the
  264. `Leggi' main program, and it will be loaded even if you don't specify the
  265. `Settings' argument. This is also where settings are saved when you select
  266. the `Save Settings' menu item.
  267.  
  268.    Note also that by using `LG''s `Wait' switch, you can use `Leggi' as a
  269. text-reader invoked by other programs (such as directory utilities, mail
  270. readers et cetera).
  271.  
  272.  
  273. Keyboard & Mouse
  274. =================
  275.  
  276.    Navigation through a document is accomplished through the keyboard and the
  277. mouse. If you click on the upper or lower part of a window, or while
  278. approximately in the center in the leftmost or rightmost part, you will see
  279. the contents of the window scrolling in the opposite direction. This
  280. behaviour is fixed and cannot be modified; however, you can disable
  281. selectively the left or right mouse scrolling via the ARexx commands
  282. `MouseLeft' and `MouseRight' (see The ARexx Interface), or via `LeggiPrefs'
  283. (see The Settings Editor).
  284.  
  285.    The default keyboard configuration is that cursor keys move by one
  286. line/column, SHIFTed cursor keys by a page (either horizontally or
  287. vertically) and ALTed cursor key move to the top/bottom (or they center the
  288. horizontal position). CTRLed vertical cursor keys move to the next page key
  289. (see Settings; practically, they do a search for the page key forwards or
  290. backwards).
  291.  
  292.    The function keys move to the corresponding bookmark, while the SHIFTed
  293. functions keys set the bookmark. The `B' and BACKSPACE keys are equivalent
  294. to `SHIFT-UP', the space bar is equivalent to `SHIFT-DOWN', while ESC closes
  295. a window (just like `AMIGA-K').
  296.  
  297.    All the keyboard definitions can be overriden by associating a new ARexx
  298. command to a specific key (of course, keystrokes associated to menus such as
  299. `AMIGA-O' can't be redefined since they're directly handled by Intuition).
  300. See The Settings Editor.
  301.  
  302.  
  303. Menus
  304. ******
  305.  
  306.    `Leggi''s menus are extremely straightforward. They follow closely
  307. Commodore's guidelines, and in the near future you should find more and more
  308. applications using a similar, coherent menu scheme.
  309.  
  310.  
  311. Project
  312. ========
  313.  
  314.    The Project menu contains standard and rather obvious items.
  315.  
  316. `New'
  317.      creates a new window, cloning the current settings.
  318.  
  319. `Open...'
  320.      brings up the ASL file requester and lets you choose a file to open. 
  321.      Note that if you have powerpacker.library, you can load a PowerPacked
  322.      file, and it will be automatically decrunched (however, if you have
  323.      powerpacker.library `Leggi' sometimes won't be able to display the very
  324.      last character in a file).
  325.  
  326. `Close'
  327.      closes the current window. If the current window is the last window
  328.      open and `Leggi' wasn't requested to stay in the background (see The
  329.      Workbench Interface, and see The CLI Interface), it exits.
  330.  
  331. `About...'
  332.      displays some information about the program.
  333.  
  334. `Quit'
  335.      closes all opened windows. If `Leggi' wasn't requested to stay in the
  336.      background (see The Workbench Interface, and see The CLI Interface), it
  337.      exits.
  338.  
  339.  
  340. Edit
  341. =====
  342.  
  343.    This menu is named "Edit" just because it contains the `Cut', etc. items
  344. which are always under that name. You can't really edit anything, which is
  345. obvious because `Leggi' is a text reader, not a text editor.
  346.  
  347. `Cut'
  348.      clears the current window, putting its contents in the Clipboard.
  349.  
  350. `Copy'
  351.      copies the content of the current window in the Clipboard.
  352.  
  353. `Paste'
  354.      erases the content of the current window, and then copies in it the
  355.      content of the Clipboard.
  356.  
  357. `Erase'
  358.      erases the content of the current window.
  359.  
  360.  
  361. Search
  362. =======
  363.  
  364.    This menu controls the search system. You can ask `Leggi' to search for
  365. any string; the string can also include any AmigaDOS wildcard (including the
  366. `*' for `#?' if you activated it via `StarBurst' or a similar utility). If
  367. no wildcard is specified, a simplified version of the Boyer-Moore algorithm
  368. is used, which guarantees the highest possible performance. The search speed
  369. depends on many factors, including the number of characters of the search
  370. string (in optimal conditions it can scan about one Megabyte per second). If
  371. wildcards are present, the scan is done using the system functions, which
  372. are many times slower (nonetheless they are extremely fast if you consider
  373. they handle wildcards).
  374.  
  375.    The search starts from the second displayed line. When a match is found,
  376. the line containing the match becomes the top line. If no match is found, a
  377. screen flash is generated. You can iterate the search both forwards and
  378. backwards.
  379.  
  380. `Find...'
  381.      brings up a requester that lets you specify the search string, and then
  382.      it starts a forward search.
  383.  
  384. `Find Next'
  385. `Find Previous'
  386.      iterate forward or backward, respectively, the search with the current
  387.      string.
  388.  
  389.  
  390. Extras
  391. =======
  392.  
  393.    This menu contains a couple of special items.
  394.  
  395. `Jump To Line...'
  396.      issues a requester asking for a line number and jumps to it.
  397.  
  398. `Jump To Column...'
  399.      issues a requester asking for a column number and jumps to it (negative
  400.      numbers can be used to move to the left).
  401.  
  402. `Refresh Window'
  403.      causes a complete refresh of the window, just in case it became
  404.      corrupted for any reason.
  405.  
  406. `Exec ARexx Macro...'
  407.      brings up the ASL file requester and lets you choose an ARexx macro
  408.      which will be executed; it will have as default address port the window
  409.      port.
  410.  
  411.  
  412. Settings
  413. =========
  414.  
  415.    In order to give you the maximum flexibility and customizability, `Leggi'
  416. features a full settings load and save system. "Settings" here denotes all
  417. the options which are contained in the `Settings' menu, the window size and
  418. position and the keyboard macro assignments. Moreover, a particular role is
  419. given to the public screen name (it is cloned or inherited as any other
  420. setting, but it's not loaded or saved). There are also some "hidden"
  421. settings flags (`Background', `MouseLeft' and `MouseRight'). Since they are
  422. option which are seldom changed, they can be set only via the ARexx
  423. interface or by using `LeggiPrefs' (see The ARexx Interface, and see The
  424. Settings Editor).
  425.  
  426.    First of all, we have to distinguish between two kind of settings: global
  427. and local. Global settings are defined at startup time as the default
  428. settings (no flags on, TAB size 8, public screen Workbench, and system
  429. default font) or as the content of the settings file, if present (the
  430. default name of the settings file is `PROGDIR:Leggi.prefs', but it can be
  431. overriden by the keyword or by the tooltype `Settings'). Global settings are
  432. cloned by the first window opened by `Leggi', and by any new window which is
  433. created by a `New' or an `Open' command arriving at `Leggi''s main port
  434. (i.e., the one named `LEGGI'). Global settings can be modified at run-time
  435. by specific ARexx command sent to the main port (`LoadSettings', `Font', and
  436. so on). Note that while the public screen name is not included in the
  437. settings file, it can be specified using the `PubScreen' keyword or tooltype.
  438.  
  439.    Each window has additionally an associated set of local settings, which
  440. can be modified by using the `Settings' menu or by sending an ARexx message
  441. to the window specific ARexx port (say, `LEGGI.4'). In particular, you can
  442. save the current settings of a window in the currently used settings file
  443. using `Save Settings', while `Save Settings As...' allows you to specify a
  444. different file name. `Load settings...' sets your window settings to the
  445. contents of a previously saved settings file. When you create a new window
  446. with the `New' menu item or by sending a `New' command at the window ARexx
  447. port, your current local settings (including the public screen and the
  448. current window size) are cloned.
  449.  
  450.    The `Settings' menu includes a series of on/off menu items (which are
  451. checkmarked if activated) and a series of "valued" menu items (whose current
  452. value appears in the requester they generate when activated); finally, the
  453. load/save commands allow to load/store the current settings.
  454.  
  455. `Smart Refresh'
  456.      The Amiga lets you manage the refresh of your windows in several
  457.      different ways. `Leggi' defaults to `SIMPLE_REFRESH' windows, which
  458.      have to manually redraw obscured parts which are made visible. This
  459.      process tends to slow down the system a little bit, but a
  460.      `SIMPLE_REFRESH' window doens't pratically need any memory in order to
  461.      work. `Leggi' has a reasonably fast text display, so this is the
  462.      default refresh mode. If, however, you checkmark this menu item,
  463.      `Leggi' will use `SMART_REFRESH' windows, in which the operating system
  464.      will automatically save obscured regions in Chip RAM in order to
  465.      refresh the display when the regions are made visible, without
  466.      prompting the application. The depth arrangement and the size reduction
  467.      are completely transparent to the application--`Leggi' needs to redraw
  468.      your window only if the user enlarges it. The disadvantage is that each
  469.      window requires memory for its obscured parts, and if you have many
  470.      windows this can become a major issue: for instance, on a 640x512
  471.      4-color screen a full-size fully obscured window requires 80K. If this
  472.      memory is not available, the system will usually refuse to drag, depth
  473.      arrange or size other windows. Unless you use a lot of non full-size
  474.      windows with frequent switches from one to another, I would suggest
  475.      always using `SIMPLE_REFRESH' windows.
  476.  
  477.      Note that since this option has to be specified when the window is
  478.      opened, changing the menu item will have no effect on the current
  479.      window--the change will be effective from the next window opened (and
  480.      will be recorded if you save your settings). If you want the first
  481.      window being `SMART_REFRESH', you have to override `Leggi''s global
  482.      defaults by writing a settings file.
  483.  
  484. `Line Numbers'
  485.      When this menu item is checkmarked, the total number of lines of the
  486.      current file and the line number of the current top line will be
  487.      displayed in the window title. Updating the top line number can
  488.      slightly slow down the text scrolling, which is the raison d'ètre of
  489.      this option.
  490.  
  491. `Font...'
  492.      brings up the ASL font requester and lets you choose any font for the
  493.      current window.
  494.  
  495. `Wordwrap...'
  496.      brings up a requester which lets you set the number of characters after
  497.      which a line will be wrapped. Wrapping happens at load time, so you
  498.      have to reopen the current file if you want to wordwrap it.
  499.  
  500. `Page Key...'
  501.      `Leggi' lets you have a variable concept of "page" which is specified
  502.      by a key which marks the start of a new page. The key can be up to 40
  503.      characters long, and can contain any AmigaDOS wildcards. You can move
  504.      to the next/previous key by using `CTRL-DOWN/UP'. This allows for
  505.      instance to scan message by message downloads from BBS, BIX and so on.
  506.      This menu item lets you set the page key.
  507.  
  508. `Line Spacing...'
  509.      lets you set the number of pixels that `Leggi' will insert between each
  510.      text line, thus making the display a little less cluttered. Try some
  511.      values until you find the one you prefer.
  512.  
  513. `Load Settings...'
  514.      brings up the ASL file requester and lets you choose a preferences file
  515.      to load. The local settings of the current window will immediately be
  516.      set to the contents of the settings file, but the window won't change
  517.      its refresh mode (see Settings, the `Smart Refresh' menu item
  518.      description). The window will be resized and moved following the
  519.      indications of the settings file, and the old macro key assignments
  520.      will be substituted by the new ones.
  521.  
  522. `Save Settings'
  523.      saves the local settings on the default settings file
  524.      `PROGDIR:Leggi.prefs', unless differently specified via the `Settings'
  525.      keyword/tooltype.
  526.  
  527. `Save Settings As...'
  528.      acts as the previous menu item, but lets you specify a file name
  529.      through the ASL file requester.
  530.  
  531.  
  532. The ARexx Interface
  533. ********************
  534.  
  535.    `Leggi' features an ARexx interface which allows full control of each
  536. window and of the main program. When `Leggi' is started, it opens a main port
  537. named `LEGGI' (or differently if you used the tooltype/keyword `PortName').
  538. Moreover, each window opened gets a port with a unique numbered name:
  539. `LEGGI.1', `LEGGI.2' and so on, or, if you asked, say, for a `PortName
  540. PIPPO', `PIPPO.1', `PIPPO.2' and so on, unless of course you override
  541. locally this name using again the tooltype/keyword `PortName'.
  542.  
  543.    In general, there are two classes of ARexx commands:
  544.  
  545.   1. Commands which can be sent to both main and window ports, and which will
  546.      usually act differently in the two cases;
  547.  
  548.   2. Command which can be sent only to window ports (they generate an error
  549.      if sent to the main port).
  550.  
  551.  
  552.    The first class includes all commands which set a parameter having both a
  553. local and a global copy. The second class includes all document-specific
  554. commands, such as navigation commands, edit commands, search commands and so
  555. on. After the AmigaDOS style template for each command, it is specified if
  556. it can be issued at the main port. A short description of the command and a
  557. list of the return codes follow (including under the case "result" the
  558. content of the `result' variable if `Options Results' was set). Common
  559. return codes are described in Conventions. Many commands correspond directly
  560. to menu items, and behave accordingly.
  561.  
  562.  
  563. Conventions
  564. ============
  565.  
  566.    * The syntax of each command is described using a standard AmigaDOS
  567.      template style; if you don't know anything about templates, you can
  568.      look at the `Using the System Software' manual.
  569.  
  570.    * whenever a command is told to change something globally or locally, it
  571.      is understood this fact depends on the command arriving at the main
  572.      port or at a window port, respectively;
  573.  
  574.    * if a command which can only be sent to a window port is said to do
  575.      something to a window, it is understood to be the window which owns the
  576.      port (unless specified otherwise);
  577.  
  578.    * all syntax errors, including sending a forbidden command to the main
  579.      port, missing parameters, or plainly issueing an unexisting command,
  580.      produce an error code of 10;
  581.  
  582.    * all commands which involve requesters return 5 if the requester was
  583.      canceled;
  584.  
  585.    * all commands which move through the text return 6 if the movement
  586.      couldn't be performed (usually because you tried to move after the end
  587.      or before the start of the file), and return the current line or column
  588.      number in the result variable on success (that is, the number that was
  589.      affected by the command is returned). Note that when the text is placed
  590.      in standard position, the column number is 0.
  591.  
  592.  
  593. File Commands
  594. ==============
  595.  
  596.    There is a single command for loading a file in a (possibly brand new)
  597. window.
  598.  
  599.  
  600. Open
  601. -----
  602.  
  603. Template: FileName/K,PortName/K,PubScreen/K,Settings/K,Wait/S
  604. Main port: Yes
  605.  
  606.    If received at the main port, this command creates a new window
  607. duplicating the current global settings (unless you override this choice
  608. using the suitable keywords) and loads it with the specified filename. If no
  609. filename is specified, a file requester appears.
  610.  
  611.    If received at a window port, this command loads in the window the
  612. specified filename, or brings up a file requester if no filename is
  613. specified. The last three keywords are ignored.
  614.  
  615.    In any case, if the `Wait' switch is specified the command will not return
  616. until the window has been closed.
  617.  
  618. Return codes
  619. ............
  620.  
  621. 5
  622.      No file selected
  623.  
  624. 6
  625.      File not found or out of memory
  626.  
  627. 20
  628.      Can't open window (only when sent to the main port)
  629.  
  630. result
  631.      The ARexx port name assigned to the window
  632.  
  633.  
  634. Window Handling Commands
  635. =========================
  636.  
  637.    These commands allows to modify the position and size of any window.
  638.  
  639.  
  640. ActivateWindow
  641. ---------------
  642.  
  643. Template: ,
  644. Main port: No
  645.  
  646.    This command activates a window (in the Intuition sense, of course).
  647.  
  648.  
  649. ChangeWindow
  650. -------------
  651.  
  652. Template: LeftEdge/N,TopEdge/N,Width/N,Height/N
  653. Main port: No
  654.  
  655.    This command sets both the position and the dimensions of a window. Any
  656. parameter omitted won't be changed. The result could be different from what
  657. you expected if the window couldn't fit into the screen.
  658.  
  659.  
  660. Close
  661. ------
  662.  
  663. Template: ,
  664. Main Port: No
  665.  
  666.    This command closes a window.
  667.  
  668.  
  669. MoveWindow
  670. -----------
  671.  
  672. Template: LeftEdge/N,TopEdge/N
  673. Main port: No
  674.  
  675.    This command sets the position of a window. You can specify one or both
  676. parameters. The result could be different from what you expected if the
  677. window couldn't fit into the screen.
  678.  
  679.  
  680. New
  681. ----
  682.  
  683. Template: PortName/K,PubScreen/K,Settings/K,Wait/S
  684. Main port: Yes
  685.  
  686.    This command creates a new window duplicating the current global or local
  687. settings (unless you override this choice using the suitable keywords). If
  688. the `Wait' switch is specified the command will not return until the window
  689. has been closed.
  690.  
  691. Return codes
  692. ............
  693.  
  694. 20
  695.      Can't open window
  696.  
  697. result
  698.      The ARexx port name assigned to the window
  699.  
  700.  
  701. RedisplayWindow
  702. ----------------
  703.  
  704. Template: ,
  705. Main port: No
  706.  
  707.    This command refreshes the window (the text contained will be
  708. redisplayed).
  709.  
  710.  
  711. Quit
  712. -----
  713.  
  714. Template: ,
  715. Main port: Yes
  716.  
  717.    This command closes all opened windows. If `Leggi' wasn't requested to
  718. stay in the background (see The CLI Interface and see The Workbench
  719. Interface), it exits.
  720.  
  721.  
  722. SizeWindow
  723. -----------
  724.  
  725. Template: Width/N,Height/N
  726. Main port: No
  727.  
  728.    This command sets the width and height of a window. You can specify one or
  729. both parameters. The result could be different from what you expected if the
  730. window couldn't fit into the screen.
  731.  
  732.  
  733. UnZoomWindow
  734. -------------
  735.  
  736. Template: ,
  737. Main port: No
  738.  
  739.    This command set the window to its normal position and size (see
  740. ZoomWindow).
  741.  
  742.  
  743. WindowToBack
  744. -------------
  745.  
  746. Template: ,
  747. Main port: No
  748.  
  749.    This command depth arranges a window, sending it behind all other ones.
  750.  
  751.  
  752. WindowToFront
  753. --------------
  754.  
  755. Template: ,
  756. Main port: No
  757.  
  758.    This command depth arranges a window, bringing it to the front.
  759.  
  760.  
  761. ZoomWindow
  762. -----------
  763.  
  764. Template: ,
  765. Main port: No
  766.  
  767.    This command sets the window to its alternate position and size (just like
  768. the zoom gadget).
  769.  
  770.  
  771. Edit Commands
  772. ==============
  773.  
  774.    These commands control the Clipboard. Note that from ARexx you can access
  775. *any* clip.
  776.  
  777.  
  778. Copy
  779. -----
  780.  
  781. Template: /N
  782. Main port: No
  783.  
  784.    This commands copies the contents of the window (i.e., the whole
  785. document) to the clipboard in the clip specified by the argument. If no
  786. number is specified, 0 (the primary clip) is assumed.
  787.  
  788. Return codes
  789. ............
  790.  
  791. 20
  792.      Couldn't copy to clipboard
  793.  
  794.  
  795. Cut
  796. ----
  797.  
  798. Template: /N
  799. Main port: No
  800.  
  801.    This commands cuts the contents of the window (i.e., the whole document)
  802. to the clipboard in the clip specified by the argument. If no number is
  803. specified, 0 (the primary clip) is assumed.
  804.  
  805. Return codes
  806. ............
  807.  
  808. 20
  809.      Couldn't cut to clipboard
  810.  
  811.  
  812. Erase
  813. ------
  814.  
  815. Template: ,
  816. Main port: No
  817.  
  818.    This command erases the contents of the window, thus freeing the
  819. associated memory.
  820.  
  821.  
  822. Paste
  823. ------
  824.  
  825. Template: /N
  826. Main port: No
  827.  
  828.    This commands pastes the contents of the clipboard in the window using the
  829. the clip specified by the argument. If no number is specified, 0 (the
  830. primary clip) is assumed.
  831.  
  832. Return codes
  833. ............
  834.  
  835. 20
  836.      Couldn't paste from clipboard
  837.  
  838.  
  839. Search Commands
  840. ================
  841.  
  842.    These commands control the search system.
  843.  
  844.  
  845. Find
  846. -----
  847.  
  848. Template: Text/F
  849. Main port: No
  850.  
  851.    This command will set the current search string to the argument `Text',
  852. and will start a forward search; if no argument is specified, the user will
  853. be prompted with a text requester.
  854.  
  855. Return codes
  856. ............
  857.  
  858. 0
  859.      Successful search
  860.  
  861. 5
  862.      No search string was specified or selected
  863.  
  864. 6
  865.      No match found
  866.  
  867. result
  868.      The line containing the match
  869.  
  870.  
  871. FindNext
  872. ---------
  873.  
  874. Template: ,
  875. Main port: No
  876.  
  877.    Iterates forward the search with the current search string. See Find.
  878.  
  879.  
  880. FindPrevious
  881. -------------
  882.  
  883. Template: ,
  884. Main port: No
  885.  
  886.    Iterates backward the search with the current search string. See Find.
  887.  
  888.  
  889. Settings Commands
  890. ==================
  891.  
  892.    These commands allows to set the global settings, and to control some
  893. feature which is not available via GUI.
  894.  
  895.  
  896. Background
  897. -----------
  898.  
  899. Template: On/S,Off/S
  900. Main port: Yes
  901.  
  902.    This command sets globally or locally the background flag. Note that
  903. unless you plan to save your local settings, changing a local background
  904. flag has absolutely no effect (this is why there is no menu item for the
  905. background flag).
  906.  
  907.  
  908. Font
  909. -----
  910.  
  911. Template: Name/K,Height/K
  912. Main port: Yes
  913.  
  914.    This command sets globally or locally the display font. If no argument is
  915. specified, the ASL font requester is issued. If you specify only one of the
  916. two arguments, the other one will be taken from the current font.
  917.  
  918. Return codes
  919. ............
  920.  
  921. 5
  922.      The user canceled the requester
  923.  
  924. 20
  925.      Couldn't open the specified font
  926.  
  927.  
  928. LineNumbers
  929. ------------
  930.  
  931. Template: On/S,Off/S
  932. Main port: Yes
  933.  
  934.    This commands sets globally or locally the line numbers flag.
  935.  
  936.  
  937. LineSpacing
  938. ------------
  939.  
  940. Template: /N
  941. Main port: Yes
  942.  
  943.    This command sets globally or locally the number of pixels `Leggi' will
  944. put inbetween two lines. If no argument is specified, a requester is issued.
  945. Allowed values are between 0 and 99, included.
  946.  
  947. Return codes
  948. ............
  949.  
  950. 5
  951.      The user canceled the requester
  952.  
  953. 20
  954.      Value out of range
  955.  
  956.  
  957. LoadSettings
  958. -------------
  959.  
  960. Template: Settings/K
  961. Main port: Yes
  962.  
  963.    This commands loads in the local or global settings the specified file.
  964.  
  965.  
  966. MouseLeft
  967. ----------
  968.  
  969. Template: On/S,Off/S
  970. Main port: Yes
  971.  
  972.    This command sets globally or locally the mouse left scrolling flag. If
  973. this flag is set (the default), when the mouse is positioned horizontally in
  974. the leftmost eighth of a window, and vertically more or less in the center,
  975. the text will be scrolled horizontally. Note that if you want to disable
  976. left/right scrolling through the keyboard, too, you can override the
  977. definition of the left/right cursor keys with a `NOP' command or with some
  978. command of your choice.
  979.  
  980.  
  981. MouseRight
  982. -----------
  983.  
  984. Template: On/S,Off/S
  985. Main port: Yes
  986.  
  987.    This command sets globally or locally the mouse right scrolling flag. See
  988. MouseLeft.
  989.  
  990.  
  991. PageKey
  992. --------
  993.  
  994. Template: Key/F
  995. Main port: Yes
  996.  
  997.    This command sets globally or locally the key `Leggi' will use when
  998. performing a `Next Key' or a `Previous Key' (which in the default
  999. configuration is equivalent to `CTRL-UP/DOWN'). If no argument is specified,
  1000. a requester is issued. The page key has a maximum length of 39
  1001. characters--longer keys will be silently truncated.
  1002.  
  1003. Return codes
  1004. ............
  1005.  
  1006. 5
  1007.      The user canceled the requester
  1008.  
  1009.  
  1010. SaveSettings
  1011. -------------
  1012.  
  1013. Template: ,
  1014. Main port: Yes
  1015.  
  1016.    This commands saves the local or global settings to the default settings
  1017. file.
  1018.  
  1019.  
  1020. SaveSettingsAs
  1021. ---------------
  1022.  
  1023. Template: Settings/K
  1024. Main port: Yes
  1025.  
  1026.    This commands saves the local or global settings to the specified file. If
  1027. the keyword `Settings' is not specified, the ASL file requester pops up.
  1028.  
  1029.  
  1030. SmartRefresh
  1031. -------------
  1032.  
  1033. Template: On/S,Off/S
  1034. Main port: Yes
  1035.  
  1036.    This commands sets globally or locally the smart refresh flag.
  1037.  
  1038.  
  1039. SmoothScrolling
  1040. ----------------
  1041.  
  1042. Template: On/S,Off/S
  1043. Main port: Yes
  1044.  
  1045.    This commands sets globally or locally the smooth scrolling flag.
  1046.  
  1047.  
  1048. TabSize
  1049. --------
  1050.  
  1051. Template: /N
  1052. Main port: Yes
  1053.  
  1054.    This command sets globally or locally the number of spaces `Leggi' will
  1055. use when expanding a TAB. If no argument is specified, a requester is issued.
  1056. Allowed values are between 0 and 999, included.
  1057.  
  1058. Return codes
  1059. ............
  1060.  
  1061. 5
  1062.      The user canceled the requester
  1063.  
  1064. 20
  1065.      Value out of range
  1066.  
  1067.  
  1068. WordWrap
  1069. ---------
  1070.  
  1071. Template: /N
  1072. Main port: Yes
  1073.  
  1074.    This command sets globally or locally the number of characters after
  1075. which a word wrap will happen. A value of 0 means no wordwrap. Note that
  1076. since wordwrap is done at load time, the change has no visible effect until
  1077. you load a file. If no argument is specified, a requester is issued. Allowed
  1078. values are between 0 and 9999, included.
  1079.  
  1080. Return codes
  1081. ............
  1082.  
  1083. 5
  1084.      The user canceled the requester
  1085.  
  1086. 20
  1087.      Value out of range
  1088.  
  1089.  
  1090. Navigation Commands
  1091. ====================
  1092.  
  1093.    These commands allows you to move in a document.
  1094.  
  1095.  
  1096. Column
  1097. -------
  1098.  
  1099. Template: /N/A
  1100. Main port: No
  1101.  
  1102.    This command changes the horizontal position of the text displayed in the
  1103. window, by adding the argument to the number of the first displayed column.
  1104. Thus, a positive argument moves towards left, while a negative one moves
  1105. towards right. An argument of 0 can be used to just get the current setting.
  1106.  
  1107.  
  1108. GoToBookmark
  1109. -------------
  1110.  
  1111. Template: /N
  1112. Main port: No
  1113.  
  1114.    This command sets the top line number to the bookmark specified by the
  1115. argument. If no argument is specified, 1 is assumed as bookmark number.
  1116. Valid values for bookmark numbers are from 1 to 10, included.
  1117.  
  1118. Return codes
  1119. ............
  1120.  
  1121. 5
  1122.      Bookmark number out of range
  1123.  
  1124. 6
  1125.      Bookmark position greater than file length
  1126.  
  1127.  
  1128. GoToColumn
  1129. -----------
  1130.  
  1131. Template: /N
  1132. Main port: No
  1133.  
  1134.    This command changes the horizontal position of the text displayed in the
  1135. window, by setting the first displayed column number to the argument. If no
  1136. argument is specified, a requester is issued.
  1137.  
  1138.  
  1139. GoToLine
  1140. ---------
  1141.  
  1142. Template: /N
  1143. Main port: No
  1144.  
  1145.    This command changes the vertical position of the text displayed in the
  1146. window, by setting it to the argument. If no argument is specified, a
  1147. requester is issued.
  1148.  
  1149.  
  1150. Line
  1151. -----
  1152.  
  1153. Template: /N/A
  1154. Main port: No
  1155.  
  1156.    This command changes the vertical position of the text displayed in the
  1157. window, by adding the argument to the number of the top line. Thus, a
  1158. positive argument moves forward, while a negative one moves backward. An
  1159. argument of 0 can be used to just get the current setting.
  1160.  
  1161.  
  1162. Next
  1163. -----
  1164.  
  1165. Template: Page/S,Key/S,Windowful/S
  1166. Main port: No
  1167.  
  1168.    This command moves the display position to the next element, where element
  1169. can be a page, i.e., the number of lines displayed in the window minus one
  1170. will be added to the top line, a page as defined by a key, i.e., a search
  1171. for the next key is performed and if a match is found the line containing
  1172. the match becomes the top line (see PageKey), or a horizontal page, i.e.,
  1173. the number of displayed columns minus one is added to the horizontal
  1174. position. You specify one of the three available switch depending of the
  1175. kind of displacement you need.
  1176.  
  1177.  
  1178. Position
  1179. ---------
  1180.  
  1181. Template: SOF/S,EOF/S
  1182. Main port: No
  1183.  
  1184.    This command moves the display position to the start of file (`SOF') or
  1185. to the end of file (`EOF'). Note that in the last case the top line won't be
  1186. the last line of the file, which will be the last displayed line at the
  1187. bottom of the window.
  1188.  
  1189.  
  1190. Previous
  1191. ---------
  1192.  
  1193. Template: Page/S,Key/S,Windowful/S
  1194. Main port: No
  1195.  
  1196.    This command moves the display position to the previous element. See Next.
  1197.  
  1198.  
  1199. SetBookmark
  1200. ------------
  1201.  
  1202. Template: /N
  1203. Main port: No
  1204.  
  1205.    This command set the bookmark specified by the argument to the current top
  1206. line. If no argument is specified, 1 is assumed as bookmark number. Valid
  1207. values for bookmark numbers are from 1 to 10, included.
  1208.  
  1209. Return codes
  1210. ............
  1211.  
  1212. 5
  1213.      Bookmark number out of range
  1214.  
  1215.  
  1216. Support Commands
  1217. =================
  1218.  
  1219.    These commands offer miscellaneous services which can be useful to an
  1220. ARexx macro.
  1221.  
  1222.  
  1223. About
  1224. ------
  1225.  
  1226. Template: ,
  1227. Main port: Yes
  1228.  
  1229.    This command displays a simple information requester about `Leggi'.
  1230.  
  1231.  
  1232. GetName
  1233. --------
  1234.  
  1235. Template: ,
  1236. Main port: No
  1237.  
  1238.    This command returns in the result variable the complete pathname of the
  1239. file currently containted in the window.
  1240.  
  1241. Return codes
  1242. ............
  1243.  
  1244. 5
  1245.      No file is currently loaded
  1246.  
  1247.  
  1248. Help
  1249. -----
  1250.  
  1251. Template: Command
  1252. Main port: Yes
  1253.  
  1254.    This command returns in the result variable the template of the given
  1255. command. It is very useful for Command Shell ARexx scripts. If no command is
  1256. specified, the whole list of available command is printed (you will need an
  1257. I/O console to see it).
  1258.  
  1259. Return codes
  1260. ............
  1261.  
  1262. 5
  1263.      No such command
  1264.  
  1265. result
  1266.      The template of the given command
  1267.  
  1268.  
  1269. NOP
  1270. ----
  1271.  
  1272. Template: ,
  1273. Main port: Yes
  1274.  
  1275.    It does nothing. Mainly useful for inhibiting standard key definitions.
  1276.  
  1277.  
  1278. RequestFile
  1279. ------------
  1280.  
  1281. Template: Title/K,Path/K,File/K,Pattern/K
  1282. Main port: Yes
  1283.  
  1284.    This command issues an ASL file requester on the global or local public
  1285. screen. The requester title is specified by the `Title' argument, while the
  1286. remaining keywords allow to specify default values for the filename, the
  1287. pattern and the path displayed by the requester.
  1288.  
  1289. Return codes
  1290. ............
  1291.  
  1292. 5
  1293.      The user canceled the requester
  1294.  
  1295. result
  1296.      The complete pathname of the file selected
  1297.  
  1298.  
  1299. RequestNotify
  1300. --------------
  1301.  
  1302. Template: Prompt/K/A
  1303. Main port: Yes
  1304.  
  1305.    This command issues a requester on the global or local public screen. The
  1306. user is prompted with the `Prompt' argument, and can only confirm the
  1307. requester.
  1308.  
  1309.  
  1310. RequestNumber
  1311. --------------
  1312.  
  1313. Template: Prompt/K,Default/N/K
  1314. Main port: Yes
  1315.  
  1316.    This command issues a requester on the global or local public screen
  1317. asking for a number. The prompt string lets you select the label appearing
  1318. at the left of the string gadget. If the first letter of the `Prompt'
  1319. argument is a `_', the following letter will be considered a shortcut for
  1320. the activation of the string gadget. The default number will appear in the
  1321. gadget.
  1322.  
  1323. Return codes
  1324. ............
  1325.  
  1326. 5
  1327.      The user canceled the requester
  1328.  
  1329. result
  1330.      The number
  1331.  
  1332.  
  1333. RequestResponse
  1334. ----------------
  1335.  
  1336. Template: Prompt/K/A
  1337. Main port: Yes
  1338.  
  1339.    This command issues a requester on the global or local public screen. The
  1340. user is prompted with the `Prompt' argument, and can confirm or cancel the
  1341. requester.
  1342.  
  1343.  
  1344. RequestString
  1345. --------------
  1346.  
  1347. Template: Prompt/K,Default/K
  1348. Main port: Yes
  1349.  
  1350.    This command issues a requester on the global or local public screen
  1351. asking for a string. The prompt string lets you select the label appearing
  1352. at the left of the string gadget. If the first letter of the `Prompt'
  1353. argument is a `_', the following letter will be considered a shortcut for
  1354. the activation of the string gadget. The default string will appear in the
  1355. gadget.
  1356.  
  1357. Return codes
  1358. ............
  1359.  
  1360. 5
  1361.      The user canceled the requester
  1362.  
  1363. result
  1364.      The string
  1365.  
  1366.  
  1367. RX
  1368. ---
  1369.  
  1370. Template: Console/S,Command/F
  1371. Main port: Yes
  1372.  
  1373.    This commands starts an external ARexx macro. If the `Console' switch is
  1374. specified, an I/O `AUTO' console is opened for I/O (otherwise, the standard
  1375. I/O streams are inherited from the program). If the `Command' argument is
  1376. surrounded by quotes (which aren't strictly necessary even if you use a
  1377. filename with spaces in it, because of the `/F' template specification) it
  1378. is assumed to be a program string (i.e., an ARexx macro itself). This allows
  1379. to program complex functions inside `Leggi' by using ARexx without invoking
  1380. external files. If no command is specified, a file requester will appear.
  1381. Note that in order to pass a quoted argument, you have to diddle with the
  1382. quoting escape conventions of both AmigaDOS and ARexx, which are quite
  1383. complex. If you don't need to use quotes inside the string macro, you can
  1384. use `'''' as delimiter (for instance, `RX '''do for 3; line 1; end'''').
  1385. Otherwise, you have to escape the quotes (for instance, `RX '"*"do for 3;
  1386. line 1; end*""''). The first set of quotes is stripped by ARexx, the second
  1387. one by the system parser.
  1388.  
  1389.  
  1390. Keyboard Macros
  1391. ****************
  1392.  
  1393.    `Leggi' allows you to associate to any keystroke any ARexx command. This
  1394. means you can:
  1395.  
  1396.   1. Assign to a keystroke a specific command; for instance, assigning to
  1397.      `CTRL-U' the command `Line -12' would emulate `Ed''s behaviour. This
  1398.      does not require ARexx.
  1399.  
  1400.   2. Assign to a keystroke an ARexx program via the inline program facility;
  1401.      for instance, assigning to `ALT-R' the command
  1402.  
  1403.           RX 'Options Results; RequestNumber; N=Result; If RC==0 Do For N FindNext; Loop'
  1404.  
  1405.      would cause a number to be requested and then a `FindNext' being
  1406.      performed as many times as specified.
  1407.  
  1408.   3. Assign to a keystroke a full ARexx program stored in a separate file.
  1409.  
  1410.  
  1411.    The macro assignment process is done outside `Leggi' through the
  1412. `LeggiPrefs' program (see The Settings Editor). Macros can be local or
  1413. global as any other setting (remember however that if a macro is present
  1414. globally it is not callable from a window; global macros are simply used for
  1415. cloning when opening a new window; also, see Settings). The only way to
  1416. modify the local macros is via the `Load Settings...' menu item or the ARexx
  1417. command `LoadSettings'. Global macros can be changed by issueing a
  1418. `LoadSettings' command to the main ARexx port.
  1419.  
  1420.    The `Leggi.prefs' file included in the `Leggi' distribution archive has a
  1421. series of macros which assign to ALT+the Nth function key the action of
  1422. bringing to front the Nth window (if it exists). Moreover, `CTRL-F1' edits
  1423. the file currently contained in a window with your preferred editor (via the
  1424. `EDITOR' environment variable). You can take a look at these macros in order
  1425. to have an idea of what can be done.
  1426.  
  1427.  
  1428. ISO/ANSI Compliance
  1429. ********************
  1430.  
  1431.    `Leggi' is able to parse completely a small subset of the ISO/ANSI
  1432. color/style sequences; let's take a look at it:
  1433.  
  1434.      Color/Style Specifications
  1435.      
  1436.      <ESC>[0m    normal char set (all reverts to plain)
  1437.      <ESC>[3m    italics on
  1438.      <ESC>[23m   italics off
  1439.      <ESC>[4m    underline on
  1440.      <ESC>[24m   underline off
  1441.      <ESC>[1m    boldface on
  1442.      <ESC>[22m   boldface off
  1443.      <ESC>[3xm   set foreground color to x (from 0 to 9)
  1444.      <ESC>[4xm   set background color to x (from 0 to 9)
  1445.  
  1446.    You can freely mix together indications.  For instance,
  1447.  
  1448.      <ESC>[4;1;31;40m
  1449.  
  1450. sets underline and boldface on, and sets the color to 1 (fore) and 0 (back).
  1451.  
  1452.    As a final note, `Leggi' supports TABs (you can set their size via the
  1453. corresponding menu item) and backspaces, which move one space backwards the
  1454. cursor; note that backspaces won't be displayed properly with a proportional
  1455. font, for obvious reasons.
  1456.  
  1457.  
  1458. The Settings Editor and File Specification
  1459. *******************************************
  1460.  
  1461.    This chapter focuses on the preferences program that lets you edit a
  1462. settings file, and on the IFF specification of such a file.
  1463.  
  1464.  
  1465. The Settings Editor
  1466. ====================
  1467.  
  1468.    The `LeggiPrefs' program allows you to directly edit each setting in
  1469. `Leggi''s configuration. In particular, it is the place where you can define
  1470. the keyboard macros.
  1471.  
  1472.    The usage of the editor is straightforward: simply put in each gadget the
  1473. value you want, or click on the checkbox gadget to toggle or on off an
  1474. option. Remember that writing `-1' in the `Width' or `Height' field will
  1475. make the window fit the whole screen (starting from the `LeftEdge'/`TopEdge'
  1476. position, of course). Moreover, a `Wordwrap' of `0' means no word wrapping.
  1477. Note also that when the editor is started, no font is displayed above the
  1478. `Set Font...' gadget. If you don't select any font, `Leggi' will open the
  1479. system default font when using that settings file. The editor doesn't
  1480. currently check for out of range values, so please be careful.
  1481.  
  1482.    The keyboard assignment system is very simple to use: if you activate the
  1483. string gadget just under the list and type in a keystroke expression (try,
  1484. for instance, `ALT 80'), the keystroke will be added to the list. You can
  1485. then select it and fill in the `Command' gadget, which describes the command
  1486. associated to the keystroke. Whatever is in the `Command' gadget is also
  1487. copied when you create a new keystroke mapping, so it's very easy to copy an
  1488. assignment many times. If you select an item from the list and click on the
  1489. `Delete' gadget, the assignment will be deleted.
  1490.  
  1491.    The keystroke expressions accepted by `LeggiPrefs' have the following
  1492. template:
  1493.  
  1494.      Shift/S,Alt/S,Control/S,LCommand/S,RCommand/S,Code/N/A
  1495.  
  1496.    The `Code' part is the raw key code assigned to a particular key on the
  1497. keyboard. For a list of those, you can peek at the `KeyCodes' file which is
  1498. supplied with `Leggi', or at the `Amiga Rom Kernel Manuals'. For instance,
  1499. the ten function keys have codes from 80 to 89. You can add to the code as
  1500. many qualifier as you like. `LCommand' and `RCommand' refer to the left and
  1501. right Amiga keys, of course.
  1502.  
  1503.    `LeggiPrefs' has a single menu with the basic Open/Save operations, which
  1504. are rather obvious:
  1505.  
  1506. `Open'
  1507.      opens a settings file (brings up the file requester);
  1508.  
  1509. `Save'
  1510.      saves the current configuration with the current filename;
  1511.  
  1512. `Save As...'
  1513.      saves the current configuration with a name (brings up the file
  1514.      requester);
  1515.  
  1516. `About...'
  1517.      displays some info about `LeggiPrefs';
  1518.  
  1519. `Quit'
  1520.      exits `LeggiPrefs'.
  1521.  
  1522.  
  1523. The Settings File Specification
  1524. ================================
  1525.  
  1526.    The settings file of `Leggi' is an IFF file, namely a LEGG FORM which can
  1527. contain only two chunk types:
  1528.  
  1529. KASS
  1530.      a keyboard assignment; you can have many of those;
  1531.  
  1532. SETT
  1533.      a settings chunk; there must be just one, and it has to be the last
  1534.      chunk in the FORM (just like the BODY in an ILBM FORM).
  1535.  
  1536.    The content of a KASS is given by:
  1537.  
  1538.      typedef struct {
  1539.         USHORT Code, Qualifier;
  1540.         char Command[];
  1541.      } KASS;
  1542.  
  1543. i.e., it's a variable-length structure containing two `USHORT's (`RAWKEY'
  1544. code and qualifier of the macro) and a 0-terminated string which specifies
  1545. the ARexx command to execute. The `Qualifier' field has to contain both or
  1546. none of the SHIFT (or ALT) left/right qualifier flags (i.e., you can't set a
  1547. macro for the left SHIFT only).
  1548.  
  1549.    The content of the SETT chunk is a `Settings' structure:
  1550.  
  1551.      #define PAGEKEYLENGTH 40
  1552.      #define FONTNAMELENGTH 64
  1553.      
  1554.      typedef struct {
  1555.         USHORT   Flags;
  1556.         USHORT   WordWrap;
  1557.         USHORT   TabSize;
  1558.         USHORT   LineSpacing;
  1559.         WORD     LeftEdge, TopEdge, Width, Height;
  1560.         struct   MinList KAList;
  1561.         struct   TextAttr TextAttr;
  1562.         UBYTE    PageKey[PAGEKEYLENGTH];
  1563.         UBYTE    FontName[FONTNAMELENGTH];
  1564.      }  Settings;
  1565.  
  1566.    The `Flags' field can have the following (obvious) flags set:
  1567.  
  1568.      #define LEGGIF_SMOOTHSCROLLING   (1<<0)
  1569.      #define LEGGIF_SMARTREFRESH      (1<<1)
  1570.      #define LEGGIF_LINENUMBERS       (1<<2)
  1571.      #define LEGGIF_BACKGROUND        (1<<3)
  1572.      #define LEGGIF_MOUSELEFT         (1<<4)
  1573.      #define LEGGIF_MOUSERIGHT        (1<<5)
  1574.  
  1575.    The `WordWrap', `TabSize'..., `Height' and `PageKey' fields contain the
  1576. values for the corresponding options. The `KAList' field is irrelevant, and
  1577. can be set to anything. The `TextAttr' field contains information about the
  1578. desired font, but the `ta_Name' field is irrelevant--the font name is stored
  1579. in the `FontName' array. Note that a `-1' in the `Width' or `Height' fields
  1580. will set them to the screen width or height (minus the `LeftEdge' or
  1581. `TopEdge' values, if they're nonzero).
  1582.  
  1583.  
  1584. Acknowledgments
  1585. ****************
  1586.  
  1587.    Many people contributed to this program: the writers of the `Amiga User
  1588. Interface Style Guide', my beta testers, Ilya Shubentsov for designing the
  1589. icon, Steve Tibbett for giving his `StringReq.c' code, Ewout Walraven for
  1590. useful suggestions, and many others. Thanks to them all, and to the people
  1591. who sent me bug reports.
  1592.  
  1593.    But a most special thank goes to Gayle Noble, for her outstanding
  1594. contribution, which exceeds everything I received in my life for my work.
  1595.  
  1596.    `Leggi' is Copyright (C) 1990,1991,1992 Sebastiano Vigna and it's freely
  1597. distributable as long as all of its files are included in their original
  1598. form without additions, deletions, or modifications of any kind, and only a
  1599. nominal fee is charged for its distribution. This software is provided *AS
  1600. IS* without warranty of any kind, either expressed or implied. By using
  1601. `Leggi', you agree to accept the entire risk as to the quality and
  1602. performance of the program.
  1603.  
  1604.    Comments, complaints, desiderata are welcome.
  1605.  
  1606.  
  1607. Author Info
  1608. ************
  1609.  
  1610.          Sebastiano Vigna
  1611.          Via California 22
  1612.          I-20144 Milano MI
  1613.      
  1614.          BIX: svigna
  1615.          INTERNET: vigna@imiucca.csi.unimi.it
  1616.                    vigna@ghost.sm.dsi.unimi.it
  1617.          UUCP:cbmehq!cbmita!sebamiga!seba@cbmvax.cbm.commodore.com
  1618.               ...{uunet|pyramid|rutgers}!cbmvax!cbmehq!cbmita!sebamiga!seba
  1619.          FIDO: 2:332/607.28
  1620.  
  1621.  
  1622. ARexx Command Index
  1623. ********************
  1624.  
  1625.  
  1626.  
  1627.  About                                  About
  1628.  ActivateWindow                         ActivateWindow
  1629.  Background                             Background
  1630.  ChangeWindow                           ChangeWindow
  1631.  Close                                  Close
  1632.  Column                                 Column
  1633.  Copy                                   Copy
  1634.  Cut                                    Cut
  1635.  Erase                                  Erase
  1636.  Find                                   Find
  1637.  FindNext                               FindNext
  1638.  FindPrevious                           FindPrevious
  1639.  Font                                   Font
  1640.  GetName                                GetName
  1641.  GoToBookmark                           GoToBookmark
  1642.  GoToColumn                             GoToColumn
  1643.  GoToLine                               GoToLine
  1644.  Help                                   Help
  1645.  Line                                   Line
  1646.  LineNumbers                            LineNumbers
  1647.  LineSpacing                            LineSpacing
  1648.  LoadSettings                           LoadSettings
  1649.  MouseLeft                              MouseLeft
  1650.  MouseRight                             MouseRight
  1651.  MoveWindow                             MoveWindow
  1652.  New                                    New
  1653.  Next                                   Next
  1654.  NOP                                    NOP
  1655.  Open                                   Open
  1656.  PageKey                                PageKey
  1657.  Paste                                  Paste
  1658.  Position                               Position
  1659.  Previous                               Previous
  1660.  Quit                                   Quit
  1661.  RedisplayWindow                        RedisplayWindow
  1662.  RequestFile                            RequestFile
  1663.  RequestNotify                          RequestNotify
  1664.  RequestNumber                          RequestNumber
  1665.  RequestResponse                        RequestResponse
  1666.  RequestString                          RequestString
  1667.  RX                                     RX
  1668.  SaveSettings                           SaveSettings
  1669.  SaveSettingsAs                         SaveSettingsAs
  1670.  SetBookmark                            SetBookmark
  1671.  SizeWindow                             SizeWindow
  1672.  SmartRefresh                           SmartRefresh
  1673.  SmoothScrolling                        SmoothScrolling
  1674.  TabSize                                TabSize
  1675.  UnZoomWindow                           UnZoomWindow
  1676.  WindowToBack                           WindowToBack
  1677.  WindowToFront                          WindowToFront
  1678.  WordWrap                               WordWrap
  1679.  ZoomWindow                             ZoomWindow
  1680.  
  1681.  
  1682. Concept Index
  1683. **************
  1684.  
  1685.  
  1686.  
  1687.  ARexx                                  The ARexx Interface
  1688.  ARexx conventions                      Conventions
  1689.  ARexx port name                        The Workbench Interface
  1690.  ARexx port name                        The CLI Interface
  1691.  ARexx port name                        The ARexx Interface
  1692.  ARexx port name                        Settings
  1693.  Background mode                        The CLI Interface
  1694.  Background mode                        The Workbench Interface
  1695.  Backspaces                             ISO-ANSI Compliance
  1696.  CLI                                    The CLI Interface
  1697.  Clipboard support                      Edit
  1698.  Colors                                 ISO-ANSI Compliance
  1699.  Escape sequences                       ISO-ANSI Compliance
  1700.  Global settings                        Settings
  1701.  Keyboard                               Keyboard & Mouse
  1702.  LeggiPrefs                             The Settings Editor
  1703.  LG                                     The Activator
  1704.  Local settings                         Settings
  1705.  Macros                                 The Settings Editor
  1706.  Macros                                 Keyboard Macros
  1707.  Menus                                  Menus
  1708.  Mouse                                  Keyboard & Mouse
  1709.  Noble Gayle                            Acknowledgments
  1710.  powerpacker.library                    Project
  1711.  Public screen                          The CLI Interface
  1712.  Public screen                          The Workbench Interface
  1713.  Public screen                          Settings
  1714.  Search                                 Search
  1715.  Search wildcards                       Search
  1716.  Settings                               Settings
  1717.  Settings file specification            The Settings File Specification
  1718.  Shubentsov Ilya                        Acknowledgments
  1719.  Styles                                 ISO-ANSI Compliance
  1720.  Template                               The CLI Interface
  1721.  Tibbett Steve                          Acknowledgments
  1722.  Tooltypes                              The Workbench Interface
  1723.  Walraven Ewout                         Acknowledgments
  1724.  Wildcards                              The CLI Interface
  1725.  Window refresh                         Settings
  1726.  Workbench                              The Workbench Interface
  1727.  
  1728.