This is ecb.info, produced by makeinfo version 4.2 from ecb.texi. INFO-DIR-SECTION GNU Emacs Lisp START-INFO-DIR-ENTRY * ECB: (ecb). Emacs Code Browser END-INFO-DIR-ENTRY  File: ecb.info, Node: ecb-directories, Next: ecb-sources, Prev: ecb-tree-buffer, Up: Customizable options Group ecb-directories --------------------- This group contains settings for the directories-buffer in the ECB: - User Option: add-path-for-not-matching-files Add path of a file to `ecb-source-path' if not already contained. This is done during the auto. windows synchronization which happens if a file is opened not via the file/directory-browser of ECB. In such a situation ECB adds the path of the new file auto. to `ecb-source-path' at least temporally for the current Emacs session. This option defines two things: 1. Should only the root-part (which means for Unix-like systems always '/' and for windows-like systems the drive) of the new file be added as source-path to `ecb-source-path' or the whole directory-part? For remote-files (e.g. tramp, ange-ftp- or efs-files) the root-part is the complete host-part + the root-dir at that host (example: /berndl@ecb.sourceforge.net:/ would be the root-part of /berndl@ecb.sourceforge.net:/tmp/test.txt). 2. Should this path be added for future sessions too? The value of this option is a cons-cell where the car is a boolean for 1. and the cdr is a boolean for 2. A value of not nil for the car (1.) is reasonably if a user often opens files not via the ECB-browser which are not located in any of the paths of `ecb-source-path' because then only one path for each drive (windows) or the root-path (Unix) is added to the directory buffer of ECB. - User Option: auto-expand-directory-tree Automatically expand the directory tree to the current source file. There are three options: - `best': Expand the best-matching source-path - `first': Expand the first matching source-path - `nil': Do not automatically expand the directory tree. - User Option: after-directory-change-hook Hook which run directly after the selected directory has changed. This means not onyl after a click onto a directory in the directory-window of ECB but it means this hook runs always when the current directory changes regardless of the trigger of this change. So for example it runs also when you just switches from one buffer to another via `switch-to-buffer' or `switch-to-buffer-other-window' and the directory of these filebuffers is different but only when auto-synchronizing of the ECB-windows is on (see `ecb-window-sync'). It runs not when switching between buffers and the associated files reside in the same directory. Each function added to this hook will be called with two arguments: The directory which was current _before_ the directory-change-trigger and the directory which was now the current (i.e. after the trigger). Example: If you switch from a filebuffer "~/.emacs" to a filebuffer "/tmp/test.txt" then the functions of this hook will be called with the two arguments "~" and "/tmp". - User Option: cache-directory-contents Cache contents of directories. This can be useful if `ecb-source-path' contains directories with many files and subdirs, especially if these directories are mounted net-drives ("many" means here something > 500, dependent of the speed of the net-connection and the machine). Or if it contains remote-source-paths which means paths in the sense of tramp, ange-ftp or efs. For these directories actualizing the sources- and/or directories- buffer of ECB (if displayed in current layout!) can slow down dramatically so a caching increases speed a lot. The value of this option is a list where each element is a cons-cell and looks like: ( . ) with `:' Regular expression a directory must match to be cached. `:' Number of directory contents must exceed this number. A directory will only be cached if and only if the directory-name matches at least one rexexp of this option and its content-number exceeds the related threshold AND the directory-name matches NOT any regexp of `ecb-cache-directory-contents-not'! The cache entry for a certain directory will be refreshed and actualized only by using the POWER-click (see `ecb-primary-secondary-mouse-buttons') in the directories-buffer of ECB (*note Using the mouse::). Default-value: ECB caches the contents of all remote directories regardless of the size and all other directories if more than 50 entries are contained. Examples: An entry `("/usr/home/john_smith/bigdir*" . 1000)' means the contents of every subdirectory of the home-directory of John Smith will be cached if the directory contains more than 1000 entries and its name begins with "bigdir". An entry `(".*" . 1000)' caches every directory which has more than 1000 entries. An entry `("^/\\([^:/]*@\\)?\\([^@:/]*\\):.*" . 0)' caches every remote (in the sense of tramp, ange-ftp or efs) directory regardless of the number of entries." Please note: If you want your home-dir being cached then you MUST NOT use "~" because ECB tries always to match full path-names! - User Option: cache-directory-contents-not Do not cache the contents of certain directories. The value of this option is a list where the each element is a regular expression a directory must match if it should not being cached. If a directory-name matches at least one of the regexps of this option the directory-contents will never being cached. See `ecb-cache-directory-contents' to see when a directory will be cached. This option can be useful when normally all directories with a certain amount of content (files and subdirs) should be cached but some special directories not. This can be achieved by: - Setting `ecb-cache-directory-contents' to ((".*" . 500)): Caches all directories with more then 500 entries - Setting `ecb-cache-directory-contents-not' to a value which matches these directories which should not being cached (e.g. ("/usr/home/john_smith") excludes the HOME-directory of John Smith from being cached). Please note: If you want your home-dir exclude from being cached then you MUST NOT use "~" because ECB tries always to match full path-names! - User Option: directories-buffer-after-create-hook Local hook running after the creation of the directories-buffer. Every function of this hook is called once without arguments direct after creating the directories-buffer of ECB and it's local key-map. So for example a function could be added which performs calls of `local-set-key' to define new keybindings only for the directories-buffer of ECB. The following keys must not be rebind in the directories-buffer: `F2', `F3' and `F4' - User Option: directories-buffer-name Name of the ECB directory buffer. Because it is not a normal buffer for editing you should enclose the name with stars, e.g. " *ECB Directories*". If it is necessary for you you can get emacs-lisp access to the buffer-object of the ECB-directory-buffer by this name, e.g. by a call of `set-buffer'. Changes for this option at runtime will take affect only after deactivating and then activating ECB again! - User Option: directories-menu-sorter Function which re-sorts the menu-entries of the directories buffer. If a function then this function is called to re-arrange the menu-entries of the combined menu-entries of the user-menu-extensions of `ecb-directories-menu-user-extension' and the built-in-menu `ecb-directories-menu'. If nil then no special sorting will be done and the user-extensions are placed in front of the built-in-entries. The function get one argument, a list of menu-entries. For the format of this argument see `ecb-directories-menu-user-extension'. The function must return a new list in the same format. Of course this function can not only re-arrange the entries but also delete entries or add new entries. - User Option: directories-menu-user-extension Static user extensions for the popup-menu of the directories buffer. Value is a list of elements of the following type: Each element defines a new menu-entry and is either: 1. Menu-command: A list containing two sub-elements, whereas the first is the function (a function symbol) being called if the menu-entry is selected and the second is the name of the menu-entry. 2. Separator: A one-element-list and the element is the string "--": Then a non-selectable menu-separator is displayed. 3. Submenu: A list where the first element is the title of the submenu displayed in the main-menu and all other elements are either menu-commands (see 1) or separators (see 2) or another submenu (see c). This allows deep nested menu-submenu-structures. Currently a level of 4 is allowed but in general there could be an infinite depth of nesting but it makes no sense - if possible at all - to define infinite nested defcustom-types. So there is a limit of 4 levels but tis is not a hard limit: Just increase the value of the `ecb-max-submenu-depth' *BEFORE* first loading ECB! The function of a menu-command must follow the following guidelines: Such a function must be defined with the macro `tree-buffer-defpopup-command'! This macro defines a new popup-command whereas the newly defined command gets one argument NODE. See the docstring of `tree-buffer-defpopup-command' for further details. Example for the definition of such a menu-function: (tree-buffer-defpopup-command ecb-my-special-dir-popup-function "Prints the name of the directory of the node under point." (let ((node-data=dir (tree-node-get-data node))) (message ``Dir under node: %s'' node-data=dir))) Per default the static user-extensions are added at the beginning of the built-in menu-entries of `ecb-directories-menu' but the whole menu can be re-arranged with `ecb-directories-menu-sorter'. These menu-extensions are static. A dynamic menu-extension can be achieved via `ecb-directories-menu-user-extension-function'. - User Option: directories-menu-user-extension-function Dynamic user extensions for the popup-menu of the directories buffer. A function which has to return a list in the same format like the option `ecb-directories-menu-user-extension'. This function is called when the user opens the popup-menu for the directories buffer. If no dynamically evaluated menu-extensions should be added to the directories-buffer the function has to return nil. Therefore the default-value of this option is `ignore'. Per default the dynamic user-extensions are added in front of the static extensions of `ecb-directories-menu-user-extension' but the whole menu can be re-arranged with `ecb-directories-menu-sorter'. - User Option: directories-show-node-info When to display which node-info in the directories-buffer. Define which node info should displayed after moving the mouse over a node (or after a shift click onto the node) in the directories-buffer. You can define "when" a node-info should be displayed: - always: Node info is displayed by moving with the mouse over a node. - if-too-long: Node info is only displayed by moving with the mouse over a node does not fit into the window-width of the tree-buffer window. In the ECB directories buffer this means also if a node is shortend or if the node has an alias (see `ecb-source-path'). - shift-click: Node info is only displayed after a shift click with the primary mouse button onto the node. - never: Node info is never displayed. You can define what info should be displayed: - name: Only the full node-name is displayed. - path: The full-path of the node is displayed. Do NOT set this option directly via setq but use always customize! - User Option: display-default-dir-after-start Automatically display current default-directory after activating ECB. If a file-buffer is displayed in the current active edit-window then ECB synchronizes its tree-buffers to this file-buffer - at least if the option `ecb-window-sync' it not nil. So for this situation `ecb-display-default-dir-after-start' takes no effect but this option is for the case if no file-buffer is displayed in the edit-window after startup: If true then ECB selects autom. the current default-directory after activation even if no file-buffer is displayed in the current active edit-window. This is useful if ECB is autom. activated after startup of Emacs and Emacs is started without a file-argument. So the directory from which the startup has performed is auto. selected in the ECB-directories buffer and the ECB-sources buffer displays the contents of this directory. - User Option: excluded-directories-regexps Directories that should not be included in the directories list. The value of this variable should be a list of regular expression. - User Option: prescan-directories-for-emptyness Prescan directories for emptyness. ECB does this so directories are displayed as empty in the directories-buffer even without user-interaction (i.e. in previous ECB-versions the emptyness of a directory has been first checked when the user has clicked onto a directory). ECB optimizes this check as best as possible but if a directory contains a lot of subdirectories which contain in turn a lot of entries, then expanding such a directory or selecting it would take of course more time as without this check - at least at the first time (all following selects of a directory uses the cached information if its subdirectories are empty or not). Therefore ECB performs this check stealthy (see `ecb-stealthy-tasks-delay') so normally there should no performance-decrease or additional waiting-time for the user. There is one exception: For remote directories (in the sense of tramp, ange-ftp, or efs) this check can descrease performance even if performed stealthy and interruptable. Therefore this option offers three possible settings: * `t' Switch on this feature * `unless-remote' Switch on this feature but not for remote directories. The term "remote" means here directories which are used via tramp, ange-ftp or efs. So mounted directories are counted not as remote directories here even if such a directory is maybe hosted on a remote machine. But normally only directories in a LAN are mounted so there should be no performance-problems with such mounted directories. * `nil' Switch off this feature completely. The option `ecb-prescan-directories-exclude-regexps' offers are more fine granularity to exclude certain directories from this prescan. - User Option: host-accessible-check-valid-time Time in seconds a cached accessible-state of a remote host is valid. This option is a list where each element specifies how long for a certain remote host the cached ping-state (i.e. if the host is accessible or not) should be valid. During this time-intervall ECB pings such a remote host only once, all other checks use the cached value of that real check. But it the cached value is older than the value of this option ECB will ping again. Per default ECB discards after 1 minute the cached ping-state of each remote host. But if you are sure that a certain remote host is always accessible (i.e. means in consequence that you are always online when working with ECB and remote-paths) then add an entry to this option with a high valid-interval. Examples: An entry (".*sourceforge.*" . 3600) ensures that all remote hosts machting the string "sourceforge" will only once pinged during one hour. Or (".*" . 300) would ensure that every remote host would be pinged only once during 5 minutes. - User Option: ping-options List of options for the ping program. These options can be used to limit how many ICMP packets are emitted. Ping is used to test if a remote host of a remote path (e.g. a tramp-, ange-ftp- or efs-path) is accessible See also `ecb-ping-program'. - User Option: ping-program Program to send network test packets to a host. See also `ecb-ping-options'. - User Option: prescan-directories-exclude-regexps Which directories should be excluded from the empty-prescan. If a directory matches any of the regexps of this option it will not be prescanned for emptyness - This option takes only effect if `ecb-prescan-directories-for-emptyness' is not nil. - User Option: show-sources-in-directories-buffer Show source files in directories buffer. - User Option: source-path Paths where to find code sources. Each path can have an optional alias that is used as it's display name. If no alias is set, the path is used as display name. - User Option: source-path Paths where to find code sources. Each path can have an optional alias that is used as it's display name. If no alias is set, the path is used as display name. Lisp-type of tis option: The value must be a list L whereas each element of L is either - a simple string which has to be the full path of a directory (this string is displayed in the directory-browser of ECB) or - a 2-element list whereas the first element is the full path of a directory (string) and the second element is an arbitrary alias (string) for this directory which is then displayed instead of the underlying directory. - User Option: use-speedbar-instead-native-tree-buffer If true then uses speedbar for directories, sources or methods. This means that speedbar is integrated in the ECB-frame and is displayed in that window normally displaying the standard ECB-directories-buffer, ECB-sources-buffer or ECB-methods-buffer. This option takes effect in all layouts which contain either a directory window, a sources window or a method window. This option can have four valid values: - `nil': Do not use speedbar (default) - `dir': Use speedbar instead of the standard directories-buffer - `source': Use speedbar instead of the standard sources-buffer - `method': Use speedbar instead of the standard methods-buffer Note: For directories and sources a similar effect and usability is available by setting this option to `nil' (or `method') and setting `ecb-show-sources-in-directories-buffer' to not `nil', because this combination displays also directories and sources in one window. `ecb-use-speedbar-instead-native-tree-buffer' is for people who like the speedbar way handling directories and source-files or methods and want it in conjunction with ECB.  File: ecb.info, Node: ecb-sources, Next: ecb-methods, Prev: ecb-directories, Up: Customizable options Group ecb-sources ----------------- This group contains settings for the sources-buffer in the ECB: - User Option: read-only-check-exclude-regexps Which directories should be excluded from the sources-read-only-check. If a directory matches any of the regexps of this option their sources will not be checked if they are writable - This option takes only effect if `ecb-sources-perform-read-only-check' is not nil. - User Option: show-source-file-extension Show the file extension of source files. - User Option: source-file-regexps Specifies which files are shown as source files. This is done on directory-base, which means for each directory-regexp the files to display can be specified. If more than one directory-regexp matches the current selected directory then always the first one (and its related file-exclude/include-regexps) is used! If no directory-regexp matches then all files are displayed for the currently selected directory. Important note: It is recommended that the *LAST* element of this list should contain an always matching directory-regexp (`".*"')! So the value of this option is a list of cons-cells where the car is a directory regexp and the cdr is a 2 element list where the first element is a list of exclude regexps and the second element is a list of include regexps. A file is displayed in the source-buffer of ECB iff: The file does not match any of the exclude regexps OR the file matches at least one of the include regexps. But regardless of the value of this option a file F is never displayed in the sources-buffer if the directory matches `ecb-sources-exclude-cvsignore' and the directory contains a file .cvsignore which contains F as an entry! There are three predefined and useful combinations of an exclude and include regexp: * All files * All, but no backup, object, lib or ini-files (except .emacs and .gnus). This means all files except those starting with ".", "#" or ending with "~", ".elc", ".obj", ".o", ".lib", ".dll", ".a", ".so". (but including .emacs and .gnus) * Common source file types (.c, .java etc.) In addition to these predefined values a custom exclude and include combination can be defined. Tips for the directory- and file-rexexps: `"$^"' matches no files/directories, `".*"' matches all files/directories. - User Option: sources-buffer-after-create-hook Local hook running after the creation of the sources-buffer. Every function of this hook is called once without arguments direct after creating the sources-buffer of ECB and it's local key-map. So for example a function could be added which performs calls of `local-set-key' to define new keybindings only for the sources-buffer of ECB. - User Option: sources-buffer-name Name of the ECB sources buffer. Because it is not a normal buffer for editing you should enclose the name with stars, e.g. "*ECB Sources*". If it is necessary for you you can get emacs-lisp access to the buffer-object of the ECB-sources-buffer by this name, e.g. by a call of `set-buffer'. Changes for this option at runtime will take affect only after deactivating and then activating ECB again! - User Option: sources-exclude-cvsignore Specify if files contained in a `.cvsignore' should be excluded. Value is a list of regular expressions or nil. If you want to exclude files listed in a `.cvsignore'-file from being displayed in the ecb-sources-buffer then specify a regexp for such a directory. If you want to exclude the contents of `.cvsignore'-files for every directory then you should add one regexp ".*" which matches every directory. If you never want to exclude the contents of `.cvsignore'-files then set this option to nil. - User Option: sources-menu-sorter Function which re-sorts the menu-entries of the directories buffer. If a function then this function is called to sort the menu-entries of the combined menu-entries of the user-menu-extensions of `ecb-sources-menu-user-extension' and the built-in-menu `ecb-sources-menu'. If nil then no special sorting will be done and the user-extensions are placed in front of the built-in-entries. For the guidelines for such a sorter-function see `ecb-directories-menu-sorter'. - User Option: sources-menu-user-extension Static user extensions for the popup-menu of the sources buffer. For further explanations see `ecb-directories-menu-user-extension'. The node-argument of a menu-function contains as data the filename of the source for which the popup-menu has been opened. Per default the static user-extensions are added at the beginning of the built-in menu-entries of `ecb-sources-menu' but the whole menu can be re-arranged with `ecb-sources-menu-sorter'. - User Option: sources-menu-user-extension-function Dynamic user extensions for the popup-menu of the sources buffer. A function which has to return a list in the same format like the option `ecb-sources-menu-user-extension'. This function is called when the user opens the popup-menu for the sources buffer. If no dynamically evaluated menu-extensions should be added to the sources-buffer the function has to return nil. Therefore the default-value of this option is `ignore'. Per default the dynamic user-extensions are added in front of the static extensions of `ecb-sources-menu-user-extension' but the whole menu can be re-arranged with `ecb-sources-menu-sorter'. - User Option: sources-perform-read-only-check Check if source-items in the tree-buffers are read-only. If a sourcefile is read-only then it will be displayed with that face set in the option `ecb-source-read-only-face'. Because this check can be take some time if files are used via a mounted net-drive ECB performs this check stealthily (see `ecb-stealthy-tasks-delay') so normally the user should not see a performance-decrease or additional waiting-time. But to get sure this option offers three choices: `t', `unless-remote' and `nil'. See `ecb-prescan-directories-for-emptyness' for an explanation for these three choices. The option `ecb-read-only-check-exclude-regexps' offers are more fine granularity to exclude the sources of certain directories from the read-only state-check. - User Option: sources-show-node-info When to display which node-info in the sources-buffer. Define which node info should displayed after moving the mouse over a node (or after a shift click onto the node) in the sources-buffer. You can define "when" a node-info should be displayed: See `ecb-directories-show-node-info' for the possible choices. You can define what info should be displayed: - name: Only the full node-name is displayed. - file-info: File infos for this file are displayed. - file-info-full: Fill infos incl. full path for this file are displayed. Do NOT set this option directly via setq but use always customize! - User Option: sources-sort-ignore-case Ignore case for sorting the source-files of the Sources-buffer. See also `ecb-sources-sort-method'. - User Option: sources-sort-method Defines how the source files are sorted. - `name': Sorting by name. - `extension': Sorting first by extension and then by name. - `nil': No sorting, means source files are displayed in the sequence returned by `directory-files' (called without sorting). See also `ecb-sources-sort-ignore-case'