Skip to content


Subversion checkout URL

You can clone with
Download ZIP
Fetching contributors…

Cannot retrieve contributors at this time

658 lines (526 sloc) 26.7 KB
;;; ecb-help.el --- online help for ECB and bug reporting
;; Copyright (C) 2001 Jesper Nordenberg
;; Copyright (C) 2001 Free Software Foundation, Inc.
;; Copyright (C) 2001 Klaus Berndl <>
;; Author: Klaus Berndl <>
;; Maintainer: Klaus Berndl <>
;; Keywords: java, class, browser
;; This program is free software; you can redistribute it and/or modify it
;; under the terms of the GNU General Public License as published by the Free
;; Software Foundation; either version 2, or (at your option) any later
;; version.
;; This program is distributed in the hope that it will be useful, but WITHOUT
;; ANY WARRANTY; without even the implied warranty of MERCHANTABILITY or
;; FITNESS FOR A PARTICULAR PURPOSE. See the GNU General Public License for
;; more details.
;; You should have received a copy of the GNU General Public License along
;; with GNU Emacs; see the file COPYING. If not, write to the Free Software
;; Foundation, Inc., 59 Temple Place - Suite 330, Boston, MA 02111-1307, USA.
;;; Commentary:
;; Contains all online-help for ECB (stolen something from recentf.el)
;; $Id$
;;; Code
(require 'ecb-layout)
(defconst ecb-help-message
General description
ECB is a global minor-mode which offers a few ECB-windows for browsing your
sources comfortable with the mouse and the keyboard. There are currently three
different types of ECB-windows:
1. ECB Directories:
- Select directories \(and - if enabled - source files) in the \"*ECB
Directories*\" buffer by clicking a mouse button (see \"Usage of ECB\"
below) on the directory name or by hitting ENTER/RETURN when the cursor is
placed on the item line.
- Directory names with a \"[+]\" symbol after \(or before) them can be
expanded/collapsed by clicking on the symbol, pressing the TAB key when the
cursor is placed on the package line or clicking a mouse button (see \"Usage
of ECB\" below) on the item.
- Right clicking on an item will open a popup menu where different operations
on the item under the mouse cursor can be performed.
- Pressing F1 in the directories buffer will update it. Pressing F2 will open
the ECB customization group in the edit window ECB Sources:
2. ECB Sources:
- Source files can be selected by clicking a mouse button (see \"Usage of
ECB\" below) or hitting ENTER/RETURN on the source row in the \"*ECB
Sources*\" or \"*ECB History*\" windows.
IMPORTANT: If you hold down the SHIFT-key while clicking with the primary
mouse button (see \"Usage of ECB\" below) on a source row in the \"*ECB
Sources*\" or \"*ECB History*\" windows then the source will not be
displayed in the edit-window but it will be scanned in the background and
all it´s methods and variables are listed in the \"ECB Methods\" window. So
you can get an overlook over the source without changing the buffer in the
- Clicking on the source file with the secondary mouse button (see \"Usage of
ECB\" below) will open the class file in the other edit window.
- Right clicking on a source file will open a popup menu where different
operation on the item under the mouse cursor can be performed.
3. ECB Methods:
- The \"*ECB Methods*\" buffer contains the methods \(and variables, if you
want) in the selected source file. When a method/variable is selected with
the primary mouse button (see \"Usage of ECB\" below) or ENTER/RETURN the
edit buffer will jump to the method/variable.
- Clicking on a method/variable with the secondary mouse button (see \"Usage
of ECB\" below) will jump to the method in the other edit window.
In addition to these ECB-windows you have always one or two edit-windows in
the ECB-frame and \(if you want) at the bottom a compilation-window, where all
the output of Emacs-compilation \(compile, grep etc.) is shown.
Activation and deactivation
Call M-x `ecb-activate' and M-x `ecb-deactivate' to activate or deactivate
ECB. If you want ECB started in a new frame see the option
`ecb-new-ecb-frame' \(default is nil). `ecb-activate' always raises and
selects the ECB-frame even if ECB is already started.
Because ECB is a global minor-mode it can also be (de)activated/toggled by
M-x `ecb-minor-mode'.
Usage of ECB
Working with the mouse in the ECB-buffers:
Normally you get best usage if you use ECB with a mouse.
ECB distinguishes between a primary and a secondary mouse-button:
A click with the primary button causes the main effect in each ECB-buffer:
- ECB Directories: Expanding/collapsing nodes and displaying files in the ECB
Sources buffer.
- ECB sources/history: Opening the file in that edit-window specified by the
option `ecb-primary-mouse-jump-destination'.
- ECB Methods: Jumping to the method in that edit-window specified by the
option `ecb-primary-mouse-jump-destination'.
Per default the complete node-name of an item in a tree-buffer is displayed in
the echo-area if the mouse moves over it, regardless if the related window is
the active one or not \(for this see also the option
`ecb-show-node-name-in-minibuffer'). You get the same effect if you click with
the primary mouse-button onto a node while SHIFT is held.
IMPORTANT: Doing this SHIFT-click in the \"*ECB Sources*\" or \"*ECB
History*\" windows does not only show the node in the echo-area but it also
opens the clicked source only in the background and shows all its
methods/variables in \"ECB Methods\"; the buffer of the edit-window is not
changed! This is very useful to get only an overlook for a certain source.
The secondary mouse-button is for opening \(jumping to) the file in the other
window \(see the documentation `ecb-primary-mouse-jump-destination').
With the option `ecb-primary-secondary-mouse-buttons' the following
combinations of primary and secondary mouse-buttons are possible:
- primary: mouse-2, secondary: C-mouse-2 \(means mouse-2 while CTRL-key is
pressed). This is the default setting.
- primary: mouse-1, secondary: C-mouse-1
- primary: mouse-1, secondary: mouse-2
If you change this during ECB is activated you must deactivate and activate
ECB again to take effect
In each ECB-buffer mouse-3 \(= right button) opens a special context
popup-menu for the clicked item where you can choose several senseful actions.
Working with the keyboard in the ECB-buffers:
In the ECB-buffers RET and TAB work as primary \"buttons\" \(see above), means
RET selects a directory or opens a source or jumps to a method and TAB toggles
expanding/collapsing of an expandable node.
Incremental search for a node in current tree-buffer. Each displayable key
\(e.g. all keys normally bound to `self-insert-command') is appended to the
current seach-pattern. The tree-buffer tries to jump to the first node which
matching the current search-pattern either as substring or as prefix \(see
below). If no match is found then nothing is done. There are some special
- \[backspace] and \[delete]: Delete the last character from the search-pattern.
- \[home]: Delete the complete search-pattern
- \[end]: Expand either to a complete node if current search-pattern is
already unique or expands to the greates common substring or prefix
of the nodes.
For better overlooking the current search-pattern is shown in the echo area.
After selecting a node with RET the search-pattern is cleared out.
With `ecb-tree-incremental-search' you can specify if the current
search-pattern must be a real prefix of the node \(default) or if any
substring is matched.
For faster and easier finding the right node in a ecb-window thi incremental
search ignores the following non interesting stuff:
+ any leading spaces
+ expand/collapse-buttons: [+] resp. [-]
+ protection-signs (+, -, #) in the method-window if uml-notation is used
+ variables types or returntypes in front of variable- or method-names.
+ const specifier for variables
This means: Just type in the prefix \(resp. a substring) of a class-,
variable-, method-, directory- or filename and ECB will bring you as fast as
possible to the node you want.
Tip: The `ecb-minor-mode' offers you in the `ecb-mode-map' some keys for
selecting every window of the ecb-frame. This makes window-selection a child´s
play. For example you can jump into the method-window by hitting \"C-c . m\".
Working with the edit-window of ECB:
ECB offers you all what you need to work with the edit-window as if the
edit-window would be the only window of the ECB-frame.
ECB offers you to advice the following functions so they work best with ECB
- `other-window'
- `delete-window'
- `delete-other-windows'
- `split-window-horizontally'
- `split-window-vertically'
- `switch-to-buffer'
- `switch-to-buffer-other-window'
- `other-window-for-scrolling'
The behavior of the adviced functions is:
- All these adviced functions behaves exactly like their corresponding
original functons but they always act as if the edit-window\(s) of ECB would
be the only window\(s) of the ECB-frame. So the edit-window\(s) of ECB seems
to be a normal Emacs-frame to the user.
- If called in a not edit-window of ECB all these function jumps first to the
\(first) edit-window, so you can never destroy the ECB-window layout
- If called in another frame than the ECB-frame these functions behave exactly
like the not adviced original versions!
If you want to work within the edit-window with splitting and unsplitting the
edit-window\(s) it is highly recommended to use the adviced-functions of ECB
instead of the original Emacs-functions \(see above). For example the adviced
`other-window' can only work correctly if you split the edit window with the
adviced `split-window-vertically' \(or horizontally) and NOT with the original
Per default ECB does advice all of the functions mentioned above but with the
option `ecb-advice-window-functions' you can customizes which functions should
be adviced by ECB. Please read carefully the documentation of this option!
Temp-buffer and compilation-buffer display in ECB:
If you call any help in Emacs, e.g. by calling `describe-function', or if you
do a completion in the minibuffer, then Emacs displays the result-buffer in
another window. This behavior you have also in ECB. If the edit-window is
already splitted then the temp-buffer is displayed in the \"other\"
edit-window otherwise the edit-window will be splitted first. The variables
`temp-buffer-max-height' and `temp-buffer-resize-mode' work also correctly
with ECB.
Same for all compilation output-buffers \(e.g. after a `compile' or `grep')
and the variable `compilation-window-height'.
This is default behavior of ECB. But there is also another way to display such
With the option `ecb-compile-window-height' you can define if the ECB layout
should contain per default a compilation-window at the bottom \(and if yes the
height of it). If yes ECB displays all output of compilation-mode \(compile,
grep etc.) in this special window. Same for displaying help-buffers or similar
With the option `ecb-compile-window-temporally-enlarge' you can allow Emacs to
enlarge temporally the ECB-compile-window after finishing compilation-output.
Please read the comment of this option.
But because ECB works best without such a durable compilation-window you
should read the comments of these two option carefully!
Rebuilding the ECB-method buffer:
In almost all cases there is NO need to manually rebuild the method-buffer,
because it is always done automatically if necessary. But nevertheless there
exist a few rare scenarios where a complete manual rebuild is necessary. Here
are some of them:
+ If an elisp-file is parsed which contains a defun X in the middle where the
closing ) is missing, then semantic parses only until this defun X is reached
and you will get an incomplete ECB-method buffer. In such a case you must
complete the defun X and then completely reparse the elisp-file and rebuild
the ECB method buffer!
+ If you change only the name of a method or a variable and you want the new
name be shown immediately in the ECB-method buffer then you must call this
A complete manually rebuild is done by `ecb-rebuild-methods-buffer'.
Redrawing the ECB-layout:
If you have unintenionally destroyed the ECB-layout, you can always restore the
layout with calling `ecb-redraw-layout'. This is even true, if you get
messages like \"wrong-type-argument window-live-p #<window 222>\".
Hiding/Showing the ECB windows:
With `ecb-toggle-ecb-windows' you can hide/show all the ECB windows without
changing the activation state of ECB and also without deactivating the advices
for `delete-other-windows' and/or `delete-window'. This is most useful if you
use layout nr.10 \(see \"Tips and tricks\" below) or if you want to have
maximum space for editing and you don´t need the browsing windows all the
Available interactive ECB commands:
- `ecb-minor-mode'
- `ecb-activate'
- `ecb-deactivate'
- `ecb-update-directories-buffer'
- `ecb-current-buffer-sync' \(normally not needed)
- `ecb-rebuild-methods-buffer' \(see \"Rebuilding the ECB-method buffer\")
- `ecb-redraw-layout'
- `ecb-clear-history'
- `ecb-show-help'
- `ecb-submit-problem-report'.
- `ecb-goto-window-directories' \(and much more `ecb-goto-window...'
- `ecb-toggle-ecb-windows'
Most of these functions are also available via the menu \"ECB\" and also via
the ECB keymap with prefix \"C-c .\" \(see `ecb-minor-mode' for a complete
list of the keybindings).
Customization of ECB
All customization of ECB is divided into the following customize groups:
- ecb-general: General customization of ECB
- ecb-directories: Customization of the ECB-directories buffer.
- ecb-sources: Customization of the ECB-sources buffer.
- ecb-methods: Customization of the ECB-methods buffer.
- ecb-history: Customization of the ECB-history buffer.
- ecb-layout: Customization of the layout of ECB.
You can highly customize all the ECB behavior/layout so just go to this groups
and you will see all well documented ECB-options. The easiest access for this
customize groups is via the menu \"ECB\".
Here are the most important options \(it is recommended to check the
following options before working with ECB):
- `ecb-source-path': You must set this option!
- `ecb-new-ecb-frame': Should ECB create a new frame at activation time.
- `ecb-primary-secondary-mouse-buttons', `ecb-primary-mouse-jump-destination':
Define how to use the mouse.
- `ecb-tree-expand-symbol-before' and `ecb-tree-indent' \(maybe you like a
value of 4 for the latter one if you display the expand-symbol before!).
- `ecb-source-file-regexps': Which files will \(not) be shown in ECB.
- `ecb-show-node-name-in-minibuffer': When the complete nodename should be
displayed in the minibuffer? Default is when the mouse moves over it and the
nodename is longer than the window-width.
- `ecb-layout-nr': The ECB layout, means which windows you want to be
displayed in the ECB-frame and also the location of these windows.
- All the options in the customize group 'ecb-layout'
Submitting a problem report
If you run into problems with ECB you can/should send a problem report to the
ECB mailing list \( ECB offers you a command
which does all necessary for you to send a problem report. Just call
`ecb-submit-problem-report'! Please read the documentation of this command.
This command creates a problem-report buffer for you. After that you get a
menu \"Mail\" \(dependend on the mail-package used, the menu can have a
different name) with commands to send the problem report. But for this the
varibale `mail-user-agent' must be configured right for your system. If you
can´t get working this mechanism you can simply copy the whole problem-report
buffer after filling it out and sending it with your standard mail-client to
Tips and tricks
Working with small screens:
If your screen is very small so you need every sqare-centimeter for displaying
the buffer which you want to edit, ECB offers you a special layouts, where
only the ECB-methods buffer is displayed on top or on left-side. Here comes
what you should/can do to work best with ECB in such a situation:
- First customize your ECB:
1. Customize `ecb-layout-nr' to layout nr. 10 \(on top) or nr. 11 \(on left-side)
2. Ensure that `ecb-compile-window-height' is nil.
3. Optional: Ajust the `ecb-windows-height' resp. `ecb-windows-width'.
4. Save your changes.
- To edit your buffers:
Call `ecb-toggle-ecb-windows' \(also available via the menu \"ECB\" and by
\"C-c . t\") or `ecb-hide-ecb-windows' to hide the ECB-method buffer so you
get all the place of your screen for editing.
- To browse and select functions:
Call `ecb-toggle-ecb-windows' or `ecb-show-ecb-windows' to make the
ECB-method buffer visible if not already. If you want select a
method/variable with the keyboard instead with the mouse you should read the
section \"Working with the keyboard in the ECB-buffers\" in this online
The possibility of hiding temporally the ECB windows like described above is
also useful for all the other layouts.
Simulating speedbar without an extra frame:
You can simuate a speedbar-like layout within ONE frame by doing the following:
1. Customize `ecb-layout-nr' to layout nr. 11
2. Optional: Ensure that `ecb-compile-window-height' is nil.
3. Optional: Ajust the `ecb-windows-width'.
4. Save your changes.
Entry points for elisp programmers
Variables an elisp-program can use:
- `ecb-source-path-functions'
Available hooks:
- `ecb-activate-before-new-frame-created-hook'
- `ecb-activate-before-layout-draw-hook'
- `ecb-activate-hook'
- `ecb-deactivate-hook'
Look at the documentation of these variables and hooks to get description.
Known conflicts with other packages
Here is a list of known conflicts of ECB with other packages and helpful
1. Package VC
The variable `vc-delete-logbuf-window' must be set to nil during active
ECB. This can be done with the hooks mentioned above.
2. Package follow-mouse.el
ECB works very well with follow-mouse if follow-mouse is turned on BEFORE
ECB is activated \(e.g. within the `ecb-activate-hook'). But if you
activate follow-mouse first after ECB is already activated, then the
follow-mouse stuff prevents the complete node-name to be displayed in the
echo-area if mouse moves over it.
Because ECB has a much more intelligent mouse tracking mechanism than
follow-mouse the follow-mouse stuff profit from ECB and works even better
and saver as without activated ECB!
3. Package avoid.el
With GNU Emacs ECB must deactivate `mouse-avoidance-mode' if the option
`ecb-show-node-name-in-minibuffer' is set to either 'if-too-long or
'always. This is only be done as long ECB is activated.
(defconst ecb-help-buffer-name "*ECB help*")
(defvar ecb-buffer-before-help nil)
(defun ecb-cancel-dialog (&rest ignore)
"Cancel the ECB dialog."
(kill-buffer (current-buffer))
(if ecb-buffer-before-help
(switch-to-buffer ecb-buffer-before-help t))
(setq ecb-buffer-before-help nil)
(message "ECB dialog canceled."))
(defvar ecb-dialog-mode-map nil
"`ecb-dialog-mode' keymap.")
(if ecb-dialog-mode-map
(setq ecb-dialog-mode-map (make-sparse-keymap))
(define-key ecb-dialog-mode-map "q" 'ecb-cancel-dialog)
(define-key ecb-dialog-mode-map (kbd "C-x k") 'ecb-cancel-dialog)
(set-keymap-parent ecb-dialog-mode-map help-mode-map))
(defun ecb-dialog-mode ()
"Major mode used to display the ECB-help
These are the special commands of `ecb-dialog-mode' mode:
q -- cancel this dialog."
(setq major-mode 'ecb-dialog-mode)
(setq mode-name "ecb-dialog")
(use-local-map ecb-dialog-mode-map))
(defun ecb-show-help ()
"Shows the online help of ECB."
(when (not (ecb-point-in-edit-window))
(if (get-buffer ecb-help-buffer-name)
(switch-to-buffer ecb-help-buffer-name t)
(if (not ecb-buffer-before-help)
(setq ecb-buffer-before-help (current-buffer)))
(with-current-buffer (get-buffer-create ecb-help-buffer-name)
(switch-to-buffer (current-buffer) t)
(let ((inhibit-read-only t))
(let ((all (overlay-lists)))
;; Delete all the overlays.
(mapcar 'delete-overlay (car all))
(mapcar 'delete-overlay (cdr all)))
;; Insert the dialog header
(insert "Type \"q\" to quit.\n")
(insert ecb-help-message)
(insert "\n\n")
(make-variable-buffer-local 'buffer-read-only)
(setq buffer-read-only t)
(goto-char (point-min))
(ignore-errors (help-make-xrefs))
(goto-char (point-min)))))
;; Problem reporting functions stolen from JDE
(defvar ecb-problem-report-mail-address "" )
(defconst ecb-problem-report-message
"Please enter the details of your bug report here")
(defun ecb-submit-problem-report()
"Submit a problem report for the ECB to the ECB mailing-list. This command
generates in the edit-window a problem-report which contains already the
current values of all ECB options, the current backtrace-buffer if there is
any and the current message-buffer. You will be asked for a problem-report
subject and then you must insert a description of the problem. Please describe
the problem as detailed as possible!"
(if (not (ecb-point-in-edit-window))
(if (not (locate-library "reporter"))
(error "You need the reporter.el package to submit a bugreport for ECB!")
(require 'reporter)
(y-or-n-p "Do you want to submit a problem report on the ECB? ")
(message "Preparing problem report...")
;;prepare the basic buffer
;; (let ((reporter-prompt-for-summary-p "Subject of the report: "))
(format "ECB: %s, Semantic: %s, JDE: %s"
(if (boundp 'semantic-version)
(if (boundp 'jde-version)
"No JDE"))
(insert (read-string "Problem report subject: "
(format "ECB-%s -- " ecb-version)))
(search-forward ecb-problem-report-message)
(message "Preparing bug report...done")))))
(defun ecb-problem-report-post-hook()
"Function run the reporter package done its work. It looks for a message- and
a backtrace-buffer and inserts the contents of that."
;; if the mail-packages has already inserted a signature we must not go to
;; the buffer-end but just before the signature
(if (re-search-forward "^--[ \t]*$" nil t)
(insert-string "\n\n\n")
(forward-line -2))
(goto-char (point-max))
(insert-string "\n\n"))
(let* ((messages-buffer
(if running-xemacs " *Message-Log*" "*Messages*")))
(backtrace-buffer (get-buffer "*Backtrace*")))
;;insert the contents of the backtrace buffer if it is there.
(insert-string "\n\n-----------------------------------------------------\n")
(if backtrace-buffer
(insert-string "The contents of the *Backtrace* buffer were\n\n")
(insert-buffer backtrace-buffer)
;; we must force the mark
(goto-char (mark t))
(insert-string "\nEnd Insert *Backtrace* buffer" ))
(insert-string "There was no *Backtrace* buffer" ))
(insert-string "\n-----------------------------------------------------\n\n")
;;insert the contents of the messages buffer if it is there.
(insert-string "-----------------------------------------------------\n")
(if messages-buffer
(insert-string "The contents of the *Messages* buffer were\n\n")
(insert-buffer messages-buffer)
(goto-char (mark t))
(insert-string "\nEnd Insert *Messages* buffer" ))
(insert-string "There was no *Messages* buffer" ))
(insert-string "\n-----------------------------------------------------\n\n"))))
(defun ecb-problem-report-list-all-variables()
"List all variables starting with `ecb-' and some other variables which
could be interesting for support."
(let ((emacs-vars `(semantic-after-toplevel-bovinate-hook
,(if (boundp 'ediff-quit-hook)
(lambda (symbol)
(when (and (string-match "ecb-" (symbol-name symbol))
(get symbol 'custom-type))
(setq ecb-vars (cons symbol ecb-vars)))))
(setq ecb-vars
(sort ecb-vars
(function (lambda (l r)
(string< (symbol-name l) (symbol-name r))))))
(setq emacs-vars
(sort emacs-vars
(function (lambda (l r)
(string< (symbol-name l) (symbol-name r))))))
(append emacs-vars ecb-vars)))
(provide 'ecb-help)
;; ecb-help.el ends here
Jump to Line
Something went wrong with that request. Please try again.