Show
Ignore:
Timestamp:
07/09/08 06:19:50 (5 months ago)
Author:
rob
Message:

Updated user manual with sections on preferences and running
* added placeholder text in majormodes.rst

Files:
1 modified

Legend:

Unmodified
Added
Removed

  • trunk/manual/preferences.rst

    r1363 r1475  
    11.. _preferences: 
    22 
    3 ******************************* 
    4 Customization and Preferences * 
    5 ******************************* 
     3***************************** 
     4Customization and Preferences 
     5***************************** 
    66 
    7 [\* To be written...] 
     7There are two ways to change preferences in peppy.  First is to use the Edit 
     8-> Preferences menu (or Peppy -> Preferences menu if you're on Mac OS X). 
     9Most settings are available here, although there are a few that can't be set 
     10through the GUI.  Those settings that can't must be modified by hand in the 
     11configuration directory. 
    812 
    9 Setting Preferences 
     13 
     14Configuration Files 
    1015=================== 
    1116 
     17Peppy maintains a configuration directory on a per-user basis.  Where 
     18it is located depends on which platform you are using: (if you're 
     19familiar with wxWindows, it's the directory that's returned from the 
     20``wx.StandardPaths.GetUserDataDir()`` method) 
     21 
     22 * unix/linux: ``$HOME/.peppy`` 
     23 * windows: ``C:/Documents and Settings/username/Application Data/Peppy`` 
     24 * mac: ``~/Library/Application Support/Peppy`` 
     25 
     26There are a variety of files in that directory, used to store various bits of 
     27data for persistence between runs of peppy.  The user configuration file is 
     28peppy.cfg, and the settings saved by the application go in preferences.cfg. 
     29Don't use preferences.cfg for your user settings, as they are overwritten 
     30when settings are saved after exiting the main application.  Put all your 
     31hand-edited changes in peppy.cfg instead. 
     32 
     33The preferences are stored in `Windows INI`__ format. 
     34 
     35__ http://en.wikipedia.org/wiki/INI_file 
    1236 
    1337Internationalization (i18n) 
    1438=========================== 
     39 
     40Several national languages are available thanks to the members of Launchpad who 
     41have been kind enough to translate my English into other languages.  In the 
     42preferences dialog, click on the General tab and choose the Languages item. 
     43You can select from any of the languages in the list, and the user interface 
     44will change immediately.  No need to restart the application! 
    1545 
    1646 
    … …  
    1848==================== 
    1949 
     50The wxPython StyledTextCtrl uses a single font for the main text, and can 
     51optionally use a separate font for the line numbers.  These fonts are set in 
     52the Preferences dialog: in the General tab, choose the Fonts item and select 
     53the primary editing font (for the main text) and the secondary editing font 
     54(for the line numbers). 
    2055 
    21 Customizing Key Bindings 
    22 ======================== 
     56Font colors and styles are changed using the Edit -> Text Styles dialog.  This 
     57associates particular syntax elements of the text file with styles and colors 
     58specified here. 
    2359 
     60 
     61Key Bindings 
     62============ 
     63 
     64There are three styles of key binding supported by peppy: windows style, Mac 
     65style, and emacs style.  These are controlled by preference settings in the 
     66Preferences menu, in the General tab under the Keyboard item.  This setting 
     67controls the default key bindings for all actions; actions may still be 
     68overridden manually. 
     69 
     70 
     71 
     72 
     73Configuring Key Bindings 
     74------------------------ 
     75 
     76User specified key bindings should be stored in the peppy.cfg file in the 
     77user's preferences directory. 
     78 
     79In the ``peppy.cfg`` file, the section ``KeyboardConf`` controls user overrides 
     80to the default keybindings. 
     81 
     82An example of the section might be:: 
     83 
     84    [KeyboardConf] 
     85    key_bindings = "emacs" 
     86    NextWord = C-N 
     87    PreviousWord = C-P 
     88    Paste = C-V 
     89 
     90Breaking it down by parts: 
     91 
     92[KeyboardConf] 
     93  This is the section header that denotes a keyboard configuration block 
     94 
     95key_bindings = "emacs" 
     96  The ``key_bindings`` variable controls the default keyboard configuration. 
     97  If this variable is not present, the default configuration is automatically 
     98  determined based on the platform.  To set this variable, it should use one 
     99  of the following values: "emacs", "win", or "mac". 
     100 
     101NextWord = C-n 
     102  The remaining entries in the section are keybindings.  The format of each 
     103  line is ``ActionName = keybinding``, where ``ActionName`` is the 
     104  class name of the action you wish to rebind.  Currently, the easiest way 
     105  to discover these name is to run peppy with the ``--show-key-bindings`` 
     106  argument, which will display all of the current keybindings to the console 
     107  in a format usable for the ``KeyboardConf`` section of the preferences. 
     108  You can also use the menu item ``Help -> Show Key Bindings``, or when all 
     109  else fails you can look at the source code.  (A GUI to change the keybindings 
     110  is ticket #53 on the roadmap.  Feel free to add suggestions there.) 
     111   
     112  To specify keystrokes, consult the section below. 
     113 
     114 
     115 
     116Describing Keystrokes 
     117--------------------- 
     118 
     119To modify the key bindings, Key bindings are specified using a special 
     120shorthand showing the modifiers of the key and the key itself.  Modifiers are: 
     121 
     122 * **S** - Shift 
     123 * **C** - Control on win/unix, Command on mac 
     124 * **M** - Meta or Alt on win/unix, Option on mac 
     125 
     126Keys are then specified using a string listing the modifier characters 
     127separated by the - character, and then the unshifted character itself. 
     128Unmodified keys are also possible -- if the keystroke doesn't contain a - 
     129character it is used as a literal character.  For example: 
     130 
     131 * **x** - the letter X 
     132 * **s** - the letter S 
     133 * **S-s** - shift S 
     134 * **C-a** - control A 
     135 * **S-/** - shift slash (note that you can't specify a ? directly -- keys are recognized by their unshifted state in wx) 
     136 * **M-C-q** - alt control Q 
     137 
     138Multiple keystrokes are separated by spaces: 
     139 
     140 * **C-x C-s** - control X followed by control S 
     141 * **C-x 5 2** - control X followed by the number 5 followed by the number 2 
     142 
     143Special characters are given by their text equivalent: 
     144 
     145 * **TAB** - the tab key 
     146 * **S-UP** - shift up arrow 
     147 
     148Here's a list of special characters (note that if you're familiar with 
     149wxPython, this is really just the `WXK_` name with the `WXK_` prefix removed): 
     150 
     151  BACK TAB RETURN ESCAPE SPACE DELETE START LBUTTON RBUTTON CANCEL MBUTTON 
     152  CLEAR PAUSE CAPITAL PRIOR NEXT END HOME LEFT UP RIGHT DOWN SELECT PRINT 
     153  EXECUTE SNAPSHOT INSERT HELP NUMPAD0 NUMPAD1 NUMPAD2 NUMPAD3 NUMPAD4 NUMPAD5 
     154  NUMPAD6 NUMPAD7 NUMPAD8 NUMPAD9 MULTIPLY ADD SEPARATOR SUBTRACT DECIMAL 
     155  DIVIDE F1 F2 F3 F4 F5 F6 F7 F8 F9 F10 F11 F12 F13 F14 F15 F16 F17 F18 F19 
     156  F20 F21 F22 F23 F24 NUMLOCK SCROLL PAGEUP PAGEDOWN NUMPAD_SPACE NUMPAD_TAB 
     157  NUMPAD_ENTER NUMPAD_F1 NUMPAD_F2 NUMPAD_F3 NUMPAD_F4 NUMPAD_HOME NUMPAD_LEFT 
     158  NUMPAD_UP NUMPAD_RIGHT NUMPAD_DOWN NUMPAD_PRIOR NUMPAD_PAGEUP NUMPAD_NEXT 
     159  NUMPAD_PAGEDOWN NUMPAD_END NUMPAD_BEGIN NUMPAD_INSERT NUMPAD_DELETE 
     160  NUMPAD_EQUAL NUMPAD_MULTIPLY NUMPAD_ADD NUMPAD_SEPARATOR NUMPAD_SUBTRACT 
     161  NUMPAD_DECIMAL NUMPAD_DIVIDE 
     162 
     163 
     164 
     165 
     166