Skip to content

Commit 55269c0

Browse files
pryrtpryrt
authored
Merge pull request #36 from pryrt/config-file-syntax
committing the pared-down version of the new Config File syntax page
2 parents 4309ac8 + 86ba638 commit 55269c0

File tree

2 files changed

+228
-0
lines changed

2 files changed

+228
-0
lines changed

‎README.md‎

Lines changed: 1 addition & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -25,6 +25,7 @@ Summary
2525
* [Plugin Communication](content/docs/plugin-communication.md)
2626
* [Preferences](content/docs/preferences.md)
2727
* [Themes](content/docs/themes.md)
28+
* [Configuration Files Details](content/docs/config-files.md)
2829
* [Command Line Arguments](content/docs/command-prompt.md)
2930
* [Shell Extension](content/docs/shell-extension.md)
3031
* [Binary Translation](content/docs/binary-translation.md)

‎content/docs/config-files.md‎

Lines changed: 227 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,227 @@
1+
---
2+
title: Configuration Files Details
3+
linktitle: config-files
4+
weight: 115
5+
---
6+
7+
# Configuration Files
8+
9+
Notepad++ offers a comprehensive user interface to review or change most of its settings. However, there are some special cases where it is worthwhile to edit the configuration files directly, including:
10+
11+
* Customizing the Context Menu
12+
* Editing previously-recorded macros, or crafting new macros manually
13+
* Adding keywords to a language, because the new language version isn't matched yet
14+
15+
The underlying XML files are all found in `%AppData%\notepad++\` (or, for zip-based local installations, in the notepad++ executable directory) unless otherwise noted.
16+
17+
## Editing Configuration Files
18+
19+
**ALWAYS BACKUP THE FILE TO BE EDITED**. If you make a mistake, Notepad++ may erase the whole contents and replace it with useless defaults. This is probably the worst that can happen, but it does happen.
20+
21+
If changes are made in the Notepad++ UI to settings which are stored in configuration files, those will be written to disk when you exit Notepad++ _after_ any file saves you do. Thus, if you are going to edit a Notepad++ configuration file _with_ Notepad++ (and why would you want to edit it with anything else?), you will need to be careful. The safest sequence when editing a configuration file:
22+
23+
1. Close _all_ active instances of Notepad++
24+
2. Open _one_ instance of Notepad++
25+
3. Edit the configuration file
26+
4. Save
27+
5. Exit Notepad++
28+
6. Reload Notepad++
29+
7. The changes will now be in effect.
30+
31+
## The context menu: `contextMenu.xml`
32+
33+
<!-- http://web.archive.org/web/20190518131311/http://docs.notepad-plus-plus.org/index.php/Context_Menu -->
34+
35+
The context menu does not have a GUI-based editor; you just need to edit the file. As a result, the **Settings > Edit Popup Context Menu** entry exists to make it easy for you to access this config file.
36+
37+
All menu commands can be added to the Context Menu, including plugin commands:
38+
39+
* To add a built-in command, you need to provide the main menu name (as it appears in the main menu bar) as the value of the MenuEntryName attribute and the command's item name (as it appears in the menu) as the value of the MenuItemName attribute. The MenuEntryName attribute must reference an entry on the main menu bar and must be an ancestor of the MenuItemName attribute, regardless of its depth.
40+
* To add a plugin command, you need to provide the plugin's menu item name (as it appears in the Plugins menu) as the value of the PluginEntryName attribute and the command's menu item name (as it appears in the plugin's sub-menu) as the value of the PluginCommandItemName attribute.
41+
42+
Note that the value you add should be in English, not in a translated language. The Shortcut Mapper will help you find the English name of plugin commands; simply switch to English localization for the raw name of built-in commands. If you wish to use IDs, they can be found in [menuCmdID.h](https://github.com/notepad-plus-plus/notepad-plus-plus/trunk/PowerEditor/src/menuCmdID.h), or can be found in your localization file.
43+
44+
### Grouping items into sub-menus
45+
46+
If you add a `FolderName="name_of_submenu"` attribute to consecutive items, they will be grouped into a sub-menu with that name. Specifying "" is the same as leaving the FolderName attribute out. Note that sub-menus do not nest - you cannot add a sub-menu to a sub-menu. Non-Latin characters are supported.
47+
48+
### Overriding a menu item name
49+
50+
If you add an `ItemNameAs="new_name_for_the_item"` attribute, the new name will be displayed instead of the standard one, which you'd get from the menu bar or its sub-menus. This is useful when the name is lengthy, as it makes the Context Menu unwieldy otherwise. Non-Latin characters are supported.
51+
52+
## Keyboard shortcuts: `shortcuts.xml`
53+
54+
Defines keyboard shortcuts for various types of commands. The shortcuts are most-easily defined in the various tabs of the [**Settings > Shortcut Mapper**](../preferences/#shortcut-mapper).
55+
56+
This file has the following nodes:
57+
58+
1. `<InternalCommands>`: Keyboard shortcuts for Notepad++ menu commands that have been remapped by the. (Commands that use their default shortcuts are not listed here.)
59+
1. `<Macros>`: Keyboard shortcuts for the macros listed in the lower part of the [**Macro**](../macros/) menu. Also defines what commands those macros execute.
60+
1. `<UserDefinedCommands>`: Keyboard shortcuts for the Run menu entries. Also defines what actions those entries take.
61+
1. `<PluginCommands>`: Keyboard shortcuts for plugin commands that have been remapped. (Commands that use their default shortcuts are not listed here.)
62+
1. `<ScintillaKeys>`: Keyboard shorcuts for Scintilla commands, most of which relate to selecting text and moving around in the editor. (Commands that use their default shortcuts are not listed here.)
63+
64+
The definitions of the `<Macros>` and `<UserDefinedCommands>` are generally all that benefit from manual editing of the `shortcuts.xml`. It is much safer to edit the shortcuts using the [**Shortcut Mapper**](../preferences/#shortcut-mapper)
65+
66+
### Virtual Key Number
67+
68+
All the types of commands in `shortcuts.xml` have a `key` attribute, which uses the Windows virtual key number as the value. This is _not_ necessarily the same as the ASCII code or Unicode codepoint. In standard English locales, the virtual key usually lines up with the ASCII code for the character, but that is not universally true. The complete list of base virtual key code is to be found on [keys.h](https://github.com/notepad-plus-plus/notepad-plus-plus/blob/master/PowerEditor/src/keys.h). Because of this reliance on OS-defined virtual keys, many letters in your native alphabet cannot be used, though for characters that are entered directly with a key on your keyboard, it may be possible (with some effort) to determine the virtual key number for the key. (Some hints are given in the Notepad++ Community Forum at [this post](https://community.notepad-plus-plus.org/post/43733) and [this other post](https://community.notepad-plus-plus.org/post/43888).)
69+
70+
### `<Macros>`
71+
72+
When not empty, this node is made of `<Macro>` nodes, each of which represents an individual macro. Each `<Macro>` holds a nonempty list of `<Action>` tags which represent individual macro steps. These steps are either Scintilla commands or Notepad++ commands, not raw keystrokes. For more details on macro recording, see [Macros](../macros/).
73+
74+
**Attributes for the `<Macro>` node**
75+
76+
Position | Name | Value format | Meaning
77+
:--------|:-----|:-------------|:---
78+
1 | name | string | The name of the macro. Several macros may have the same name
79+
2 | Ctrl | "yes"/"no" | The key being mapped to has the Control modifier
80+
3 | Alt | "yes"/"no" | The key being mapped to has the Alt modifier
81+
4 | Shift | "yes"/"no" | The key being mapped to has the Shift modifier
82+
5 | Key | integer | The base virtual key number, in the 1..255 range
83+
84+
Although it is possible for several macros to share the same name or shortcut, this practice is highly discouraged.
85+
86+
**Attributes for the `<Action>` tag**
87+
88+
89+
Position | Name | Value format | Meaning
90+
:--------|:-----|:-------------|:---
91+
1 | type | integer | `0` for Scintilla messages that do not pass a string as second parameter
92+
| | | `1` for Scintilla messages that pass a string as second parameter
93+
| | | `2` for Notepad++ defined commands
94+
| | | `3` for search and replace recording
95+
2 | message | integer | `0` if `type=2`, otherwise use the message id
96+
3 | wParam | integer | Command id when `type=2` or `type=3`, else actual first parameter of the message. Use `0` if the message or command doesn't require a wParam.
97+
4 | lParam | integer | `0` unless `type=0` and the second parameter of the message is actually used, or scalar value used when `type=3`.
98+
5 | sParam | string | `""` unless `type=1` or `type=3`, in which case this is the string pointed by the second parameter of the message.
99+
100+
The full list of Scintilla messages for `type=0` and `type=1`, as well as a concise documentation, can be found in [Scintilla.iface](https://github.com/notepad-plus-plus/notepad-plus-plus/blob/master/scintilla/include/Scintilla.iface). More details on those messages can be found in the [Scintilla Docs](https://scintilla.org/ScintillaDoc.html).
101+
102+
The `wParam` command IDs for `type=1` can be found as the `IDM` constants in the source file [menuCmdID.h](https://github.com/notepad-plus-plus/notepad-plus-plus/trunk/PowerEditor/src/menuCmdID.h), or you can look at the `localization\English.xml` (or your language of choice), which lists the `<Item id="...">` next to the text of the command; the value of the `id` attribute is the "command ID".
103+
104+
For `type=3` search-and-replace macros, see the detailed description in ["Searching > Searching actions when recorded as macros"](../searching/#searching-actions-when-recorded-as-macros).
105+
106+
You can use any Scintilla or Windows message that does not return a value, that passes an integer in `wParam`, and either an integer or string in `lParam`. There are some messages that require strings in the `wParam`, or various data structures: those will not work in a macro.
107+
108+
For more on the messaging system, see [Plugin Communication](../plugin-communication/).
109+
110+
### `<UserDefinedCommands>`
111+
112+
When not empty, this node contains `<Command>` tags, which have the command string as contents. Their order is reflected in the Run menu, otherwise it doesn't matter.
113+
114+
115+
**Attributes for the `<Command>` tag**
116+
117+
118+
Position | Name | Value format | Meaning
119+
:--------|:-----|:-------------|:---
120+
1 | name | string | The name of the Run command.
121+
2 | Ctrl | "yes"/"no" | The key mapped to has the Control modifier
122+
3 | Alt | "yes"/"no" | The key mapped to has the Alt modifier
123+
4 | Shift | "yes"/"no" | The key mapped to has the Shift modifier
124+
5 | Key | integer | The base virtual key number, in the 1 - 255 range
125+
126+
Although it is possible for several commands to have the same name, this is confusing and thus discouraged.
127+
128+
The run command may contain any valid command for the <abbr title="Operating System: Generally Windows. If you use Notepad++ in a Linux WINE environment or similar, could you create a pull request clarifying whether it's windows-style command syntax or linux-style command syntax.">Windows OS</abbr>. If you use a command that can be found in your PATH (like `cmd.exe`), then you don't need to specify the full path to the command. If it's not in your path, then you _should_ specify the full path. Note that Windows will launch your default browser if you put a URL in this If the command, or one of its arguments, has an embedded space, then put quotes around it (like you would for any command line environement). For example, `<Command name="Run Putty" ... >"c:\program files\putty\putty.exe" -ssh -load "my session"</Command>` shows the quotes around the executable and one of the arguments, because both have spaces.
129+
130+
There are a number of variables available, which are accessed in the form `$(VARIABLE_NAME)`, which can be used to supply portions of the command entry.
131+
132+
Variable | Description | Example
133+
--------------------|:--- |:---
134+
FULL_CURRENT_PATH | The full path to the active file | `E:\My Web\main\welcome.html`
135+
CURRENT_DIRECTORY | The active file's directory | `E:\My Web\main`
136+
FILE_NAME | The active file's name | `welcome.html`
137+
NAME_PART | The filename without extension | `welcome`
138+
EXT_PART | The extension | `html`
139+
SYS._var_ | the _var_ system environment variable | `$(SYS.PATH)` will expand to your `%PATH%` environment variable
140+
CURRENT_WORD | the active selection in Notepad++, or the word under the cursor |
141+
CURRENT_LINE | the line number where the cursor is currently located in the editor window | `1`
142+
CURRENT_COLUMN | the column number where the cursor is currently located in the editor window | `5`
143+
NPP_DIRECTORY | the directory where the `notepad++.exe` executable is located | `c:\Program Files\notepad++`
144+
NPP_FULL_FILE_PATH | the full path to the `notepad++.exe` | `c:\Program Files\notepad++\notepad++.exe`
145+
146+
## User Interface settings: `config.xml`
147+
148+
The following sections are defined:
149+
150+
1. `<GUIConfigs>`: user interface settings (usually set in the [**Settings > Preferences**](../preferences/#preferences)).
151+
2. `<FindHistory>`: most of the latest state of the Find/Replace dialog box.
152+
3. `<History>`: the list of recently used files.
153+
3. `<ProjectPanels>`: associates workspace files with a given project panel
154+
155+
156+
## Keyword lists: `langs.xml`
157+
158+
159+
This file contains the keyword lists for syntax highlighting languages.
160+
161+
**Attributes for the `<Language>` node**
162+
163+
Position | Name | Value format | Meaning
164+
:--------|:-----|:-------------|:---
165+
1 | name | string | The name of the language.
166+
2 | ext | string | The list of file extensions associated to this language by default. Lists are space separated, without leading periods.
167+
3 | commentLine | string | The character(s) that prelude a comment extending to the end of the physical line. Use "" if the feature is not supported.
168+
4 | commentStart | string | The character(s) that start a block comment. Use "" if the feature is not supported.
169+
5 | commentEnd | string | The character(s) that end a block comment. Use "" if the feature is not supported.
170+
6 | exclude | "yes"/"no" | Set to yes" to remove from the Language menu, else "no" or no attribute.
171+
7 | tabSettings | integer | If present, the value encodes the number of spaces a tab is equivalent to: value + 128 if the Replace tabs vy spaces is checked, else raw value. The default value of 4 is used if attribute is absent.
172+
173+
Inside each of the languages, you _could_ add keywords. However, it's better to use [**Settings > Style Configurator**](../preferences/#style-configurator) and make use of the user-defined keywords box for a given category (when available). These user-defined keywords are stored in [`stylers.xml`](#highlighting-schemes-stylers-xml) (described below).
174+
175+
## Highlighting schemes: `stylers.xml`
176+
177+
This file sets the color scheme for the default theme. The other themes are stored in `themes\*.xml`, which follow the same format at `stylers.xml`. In general, use [**Settings > Style Configurator**](../preferences/#style-configurator) for easier maintenance of styles.
178+
179+
Each lexer type has it's own `<LexerType>` section, with multiple `<WordsStyle>` entries. Each lexer from the **Language** menu has it's own list of available `<WordsStyle>` entries. Trying to add a new `<WordsStyle>` to a lexer to try to get more categories of keywords will _not_ be successful, because the underlying code which does the syntax highlighting has no internal rules for mapping the entries found to that style.
180+
181+
If you have added user-defined keywords in the [**Settings > Style Configurator**](../preferences/#style-configurator), they will be stored as the contents of the `<WordsStyle>`, as a space-separated list (for example, `<WordsStyle>fancyKeyword1 fancyKeyword2</WordsStyle>`).
182+
183+
## `functionList.xml`
184+
185+
Defines what counts as a "function" for **View > Function List**. There are some comments in the file, and lots of examples of the builtin languages, which you can customize.
186+
187+
If you want to add **Function List** capability for your User Defined Language (UDL), you can. You need to add two groups of information:
188+
189+
1. In the `<associationMap>` section, you need to add lines like the following
190+
191+
<association id="fn_udl_example" userDefinedLangName="ExampleUDL" />
192+
<association id="fn_udl_example" ext=".ex" />
193+
<association id="fn_udl_example" ext=".exudl" />
194+
195+
where `fn_udl_example` is a name unique to this UDL. It is best to define it both
196+
based on `userDefinedLangName=...` (which must match the name you saved for your UDL) and on extension `ext=...` (which must match the extension(s) of your UDL type, with one extension per entry).
197+
198+
2. In the `<parsers>` section, add a parser, with a similar format to all the builtin parsers shown. An example would be
199+
200+
<parser
201+
id="fn_udl_example"
202+
displayName="Example UDL Name (UDL)"
203+
commentExpr="((--.*?$))"
204+
>
205+
<function
206+
mainExpr="^[\s]*(private[\s]+)?(procedure|function)[\s]*[\w_]+"
207+
displayMode="$functionName"
208+
>
209+
<functionName>
210+
<nameExpr expr="^[\s]*(private[\s]+)?(procedure|function)[\s]*[\w_]+" />
211+
</functionName>
212+
</function>
213+
</parser>
214+
215+
where the `fn_udl_example` must match the `<association id>`. The `displayName` sets what shows in the **Function List** window header. The `...Expr` values are all defined in [regular expression syntax](../searching/#regular-expressions).
216+
217+
## Other Configuration Files
218+
219+
* `autoCompletion\*.xml`: files for defining per-language [auto-completion](../auto-completion/#auto-completion-file-format).
220+
221+
* `doLocalConf.xml`: this will only exist on local installations of Notepad++ (when you tell the installer to not use `%AppData%`, or when you install from the zipfile). This is a zero-byte file that is just used as an indicator to `notepad++.exe` to not go looking for `%AppData%`.
222+
223+
* `nativeLang.xml`: if you make a selection in the [**Settings > Preferences > General > Localization**](../preferences/#general), Notepad++ will copy the appropriate `localization\*.xml` to `nativeLang.xml`.
224+
225+
* `session.xml`: stores the current [session](../session/) information. Overwritten on every exit of Notepad++ if [**Settings > Preferences > Backup > Remember current session for next launch**](../preferences/#backup) is enabled. If you want sessions that you control, use **File > Save Session...** to save it; the file is safe to edit; and you can reload that session at any time using **File > Load Session...**.
226+
227+
* `userDefineLang.xml`: see [the **User Defined Languages** doc](../user-defined-language-system/).

0 commit comments

Comments
 (0)