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: Programming a new layout,  Next: Programming special windows,  Prev: The layout-engine,  Up: The layout-engine

How to program a new layout
---------------------------

If you just want creating a new layout with the standard ECB-windows like
directories, sources, methods, history and speedbar it's is strongly
recommended to define the new layout interactively with the command
`ecb-create-new-layout' (*note Creating a new ECB-layout::).

If you want creating a new layout and if this layout should contain other
special windows than the standard ECB-windows then it's still recommended to
define this layout interactively with `ecb-create-new-layout' and using the
option to give the created windows user-defined types. For every user defined
type you have then just to program the necessary buffer-set function. For all
the details see *Note Creating a new ECB-layout::.

But if you do not like the interactive way (because you are tough and brave)
but you want programming the new layout with Elisp then use the macro
`ecb-layout-define' (the following definition has stripped the prefix "ecb-"
for better indexing this manual):

 - Macro: layout-define name type &rest create-code
   Creates a new ECB-layout with name NAME. TYPE is the type of the new
   layout and is literal, i.e. not evaluated. It can be left, right, top or
   left-right. DOC is the docstring for the new layout-function
   "ecb-layout-function-<name>". CREATE-CODE is all the lisp code which is
   necessary to define the ECB-windows/buffers. This macro adds the layout
   with NAME and TYPEto the internal variable `ecb-available-layouts'.

   Preconditions for CREATE-CODE:
   1. Current frame is splitted at least in one edit-window and the "column"
      (for layout types left, right and left-right) rsp. "row" (for a top
      layout) for the special ECB-windows/buffers. The width of the "column"
      rsp. the height of the "row" is always defined with the option
      `ecb-windows-width' rsp. `ecb-windows-height'.  Depending on the value
      of the option `ecb-compile-window-height' there is also a compile
      window at the bottom of the frame which is stored in
      `ecb-compile-window'.

   2. All windows are not dedicated.

   3. Neither the edit-window nor the compile-window (if there is one) are
      selected for types left, right and top. For type left-right the left
      column-window is selected

   4. All ECB-advices for the functions in `ecb-advice-window-functions' are
      disabled!

   Things CREATE-CODE has to do:
   1. Splitting the ECB-tree-windows-column(s)/row (s.a.) in all the
      ECB-windows the layout should contain (directories, sources, methods
      and history). The split must not be done with other functions than
      `ecb-split-hor' and `ecb-split-ver'! It is recommended not to to use a
      "hard" number of split-lines or -rows but using fractions between -0.9
      and +0.9! Tip: It is recommended to spilt from right to left and from
      bottom to top or with other words: First create the right-most and
      bottom-most special windows!

   2. Making each special ECB-window a dedicated window. This can be done with
      one of the following functions:
       - `ecb-set-directories-buffer'

       - `ecb-set-sources-buffer'

       - `ecb-set-methods-buffer'

       - `ecb-set-history-buffer'

       - `ecb-set-speedbar-buffer'
      Each layout can only contain one of each tree-buffer-type!

      In addition to these functions there is a general macro:
      `defecb-window-dedicator': This macro defines a so called
      "window-dedicator" which is a function registered at ECB and called by
      ECB to perform any arbitrary code in current window and makes the
      window autom. dedicated at the end. This can be used by third party
      packages like JDEE to create arbitrary ECB-windows besides the standard
      tree-windows.

      To make a special ECB-window a dedicated window either one of the five
      functions above must be used or a new "window-dedicator"-function has
      to be defined with `defecb-window-dedicator' and must be used within
      the layout-definition.

   3. Every(!) special ECB-window must be dedicated as described in 2.

   4. CREATE-CODE must work correctly regardless if there is already a
      compile-window (stored in `ecb-compile-window') or not
      (`ecb-compile-window' is nil).

   Things CREATE-CODE can do or can use:
   1. The value of `ecb-compile-window' which contains the compile-window (if
      there is one). Using the values of `ecb-compile-window-height',
      `ecb-windows-width', `ecb-windows-height'.

   Things CREATE-CODE must NOT do:
   1. Splitting the edit-window

   2. Creating a compile-window

   3. Deleting the edit-window, the compile-window (if there is any) or the
      ECB-windows-column(s)/row (see Precondition 1.)

   4. Referring to the value of `ecb-edit-window' because this is always nil
      during CREATE-CODE.

   Postconditions for CREATE-CODE:
   1. The edit-window must be the selected window and must not be dedicated
      and not be splitted.

   2. Every window besides the edit-window (and the compile-window) must be a
      dedicated window (e.g. a ECB-tree-window).

Use this macro to program new layouts within your `.emacs' or any other file
which is loaded into your Emacs. After loading the file(s) with all the new
layout-definitions you can use it by customizing the option `ecb-layout-name'
to the appropriate name or with the command `ecb-change-layout'.

With the function `ecb-layout-undefine' you can remove a layout from the list
of available layouts:

 - Function: layout-undefine name
   Unbind ecb-layout-function-<NAME> and ecb-delete-window-ecb-windows-<NAME>
   and remove `NAME' from `ecb-available-layouts'.

Here is an example for a new layout programmed with `ecb-layout-define':

   (ecb-layout-define "my-own-layout" left nil
     ;; The frame is already splitted side-by-side and point stays in the
     ;; left window (= the ECB-tree-window-column)
   
     ;; Here is the creation code for the new layout
   
     ;; 1. Defining the current window/buffer as ECB-methods buffer
     (ecb-set-methods-buffer)
     ;; 2. Splitting the ECB-tree-windows-column in two windows
     (ecb-split-ver 0.75 t)
     ;; 3. Go to the second window
     (other-window 1)
     ;; 4. Defining the current window/buffer as ECB-history buffer
     (ecb-set-history-buffer)
     ;; 5. Make the ECB-edit-window current (see Postcondition above)
     (select-window (next-window)))

This layout definition defines a layout with name "my-own-layout" which looks
like:

   -------------------------------------------------------
   |              |                                      |
   |              |                                      |
   |              |                                      |
   |  Methods     |                                      |
   |              |                                      |
   |              |                                      |
   |              |               Edit                   |
   |              |                                      |
   |              |                                      |
   |--------------|                                      |
   |              |                                      |
   |  History     |                                      |
   |              |                                      |
   -------------------------------------------------------
   |                                                     |
   |                    Compilation                      |
   |                                                     |
   -------------------------------------------------------


File: ecb.info,  Node: Programming special windows,  Next: Possible layout-outlines,  Prev: Programming a new layout,  Up: The layout-engine

All aspects of programming special windows
------------------------------------------

ECB offers a flexible programmable layout-engine for other packages to
display their own contents and informations in special ECB-windows. An
example could be a graphical debugger which offers a special window for
displaying local variables and another special window for messages from the
debugger-process (like JDEbug of JDEE(1)).

This section explains all aspects of programming new special windows, adding
them to a new layout and synchronizing them with edit-window of ECB. This can
be done best with an easy example which nevertheless covers all necessary
aspects to be a good example and skeleton for complex tools (like a graphical
debugger) which want to use the layout-engine of ECB do display their own
information.

*IMPORTANT*: See *Note tree-buffer:: for a full documentation of the library
tree-buffer.el which can be used for programming a new special window as a
tree!

Here comes the example:

The outline of the example layout:
..................................

   -------------------------------------------------------
   |Bufferinfo for <filename>:            |[prior]       |
   |Type: file                            |[next]        |
   |Size: 23456                           |              |
   |Modes: rw-rw-rw-                      |              |
   |-----------------------------------------------------|
   |                                                     |
   |                                                     |
   |                                                     |
   |                                                     |
   |                 edit-window                         |
   |                                                     |
   |                                                     |
   |                                                     |
   |                                                     |
   -------------------------------------------------------
   |                                                     |
   |                 compilation-window                  |
   |                                                     |
   -------------------------------------------------------

The description of the layout-contents
......................................

The top-left window always displays informations about the current buffer in
the selected edit-window. This window demonstrates how autom. synchronizing a
special window/buffer of a layout with current edit-window.

The top-right window contains an read-only "action-buffer" and offers two
buttons which can be used with the middle mouse-button to scroll the
edit-window. This is not very senseful but it demonstrates how to control the
edit-window with actions performed in a special window/buffer of a layout.

(If you have not set a compilation-window in `ecb-compile-window-height' then
the layout contains no persistent compilation window and the other windows
get a little more place).

The example code
................

Now let have us a look at the several parts of the Elisp-program needed to
program this new example layout. ECB contains a library `ecb-examples.el'
which contains the full working code of this example. To test this example
and to play with it you can load this library into Emacs (with `load-library'
for example) and then calling `ecb-change-layout' (bound to `C-c . lc') and
inserting "example-layout1" as layout-name. An alternative is calling
`ecb-examples-activate' and `ecb-examples-deactivate'. For details see file
`ecb-examples.el'.

The following steps only contain code-skeletons to demonstrate the principle.
The full working code is available in `ecb-examples.el'.

The bufferinfo buffer of the example
....................................

The name of the bufferinfo buffer:

   (defconst ecb-examples-bufferinfo-buffer-name " *ECB buffer info*")

Two helper functions for displaying infos in a special buffer:

   (defun ecb-examples-print-file-attributes (buffer filename)
     (ecb-with-readonly-buffer buffer
       (erase-buffer)
       (insert (format "Bufferinfo for %s:\n\n" filename))
       ;; insert with the function `file-attributes' some
       ;; informations about FILENAME.
       ))
   
   (defun ecb-examples-print-non-filebuffer (buffer buffer-name)
     (ecb-with-readonly-buffer buffer
       (erase-buffer)
       ;; analogous to `ecb-examples-print-file-attributes'
       ))

The main synchronizing function added to `ecb-current-buffer-sync-hook' for
autom. evaluation by `ecb-current-buffer-sync' which runs dependent on the
values of `ecb-window-sync' and `ecb-window-sync-delay'. This function
synchronizes the bufferinfo buffer with the current buffer of the edit-window
if that buffer has changed.

   (defun ecb-examples-bufferinfo-sync ()
     (ecb-do-if-buffer-visible-in-ecb-frame
         'ecb-examples-bufferinfo-buffer-name
   
       ;; here we can be sure that the buffer with name
       ;; `ecb-examples-bufferinfo-buffer-name' is displayed in a
       ;; window of `ecb-frame'
   
       ;; The macro `ecb-do-if-buffer-visible-in-ecb-frame' locally
       ;; binds the variables visible-buffer and visible-window!! See
       ;; documentation of this macro!
   
       (let ((filename (buffer-file-name (current-buffer))))
   
         (if (and filename (file-readable-p filename))
   
             ;; real filebuffers
             ;; here we could add a smarter mechanism;
             ;; see ecb-examples.el
             (ecb-examples-print-file-attributes visible-buffer
                                                 filename)
   
           ;; non file buffers like help-buffers etc...
           (setq ecb-examples-bufferinfo-last-file nil)
           (ecb-examples-print-non-filebuffer visible-buffer
                                              (buffer-name
                                                (current-buffer)))
           ))))

Two conveniance commands for the user:

   (defun ecb-maximize-bufferinfo-window ()
     "Maximize the bufferinfo-window.
   I.e. delete all other ECB-windows, so only one ECB-window and the
   edit-window\(s) are visible \(and maybe a compile-window). Works
   also if the ECB-analyse-window is not visible in current layout."
     (interactive)
     (ecb-display-one-ecb-buffer ecb-examples-bufferinfo-buffer-name))
   
   (defun ecb-goto-bufferinfo-window ()
     "Make the bufferinfo-window the current window."
     (interactive)
     (ecb-goto-ecb-window ecb-examples-bufferinfo-buffer-name))

The function which makes the bufferinfo-buffer dedicated to a window and
registers the new special window/buffer at ECB.

   (defecb-window-dedicator ecb-examples-set-bufferinfo-buffer
       ecb-examples-bufferinfo-buffer-name
     "Set the buffer in the current window to the bufferinfo-buffer
   and make this window dedicated for this buffer."
     (switch-to-buffer (get-buffer-create
                         ecb-examples-bufferinfo-buffer-name))
     (setq buffer-read-only t))

This is all what we need for the special bufferinfo buffer. We have
demonstrated already three of the important functions/macros of the
layout-engine API of ECB: `ecb-with-readonly-buffer',
`ecb-do-if-buffer-visible-in-ecb-frame' and `defecb-window-dedicator' (*note
The layout-engine API::.  Especially the second macro is strongly recommended
for programming good synchronizing functions which do not waste CPU!

The action buffer of the example
................................

The name of the action-buffer:

   (defconst ecb-examples-action-buffer-name " *ECB action buffer*")

Two helper functions for creating a readonly action-buffer with a special
local key-map for the middle-mouse-button and two buttons [prior] and [next]:

   (defun ecb-examples-insert-text-in-action-buffer (text)
     (let ((p (point)))
       (insert text)
       (put-text-property p (+ p (length text)) 'mouse-face
                                                'highlight)))
   
   (defun ecb-examples-action-buffer-create ()
     (save-excursion
       (if (get-buffer ecb-examples-action-buffer-name)
           (get-buffer ecb-examples-action-buffer-name)
   
         (set-buffer (get-buffer-create
                       ecb-examples-action-buffer-name))
   
         ;; we setup a local key-map and bind middle-mouse-button
         ;; see ecb-examples.el for the full code
   
         ;; insert the action buttons [prior] and [next] and
         ;; make it read-only
   
         (ecb-with-readonly-buffer (current-buffer)
           (erase-buffer)
           (ecb-examples-insert-text-in-action-buffer "[prior]")
           ;; analogous for the [next] button
           )
   
         (current-buffer))))

The function which performs the actions in the action-buffer if clicked with
the middle-mouse button onto a button [next] or [prior].

   (defun ecb-examples-action-buffer-clicked (e)
     (interactive "e")
     (mouse-set-point e)
     (let ((line (buffer-substring (ecb-line-beginning-pos)
                                   (ecb-line-end-pos))))
       (cond ((string-match "prior" line)
              (ecb-select-edit-window)
              (call-interactively 'scroll-down))
             ((string-match "next" line)
              ;; analogous for [next]
              ))))

Two conveniance-commands for the user:

   (defun ecb-maximize-action-window ()
     "Maximize the action-window.
   I.e. delete all other ECB-windows, so only one ECB-window and the
   edit-window\(s) are visible \(and maybe a compile-window). Works
   also if the ECB-analyse-window is not visible in current layout."
     (interactive)
     (ecb-display-one-ecb-buffer ecb-examples-action-buffer-name))
   
   (defun ecb-goto-action-window ()
     "Make the action-window the current window."
     (interactive)
     (ecb-goto-ecb-window ecb-examples-action-buffer-name))

The function which makes the action-buffer dedicated to a window and
registers it at ECB.

   (defecb-window-dedicator ecb-examples-set-action-buffer
       (buffer-name (ecb-examples-action-buffer-create))
     "Set the buffer in the current window to the action-buffer
   and make this window dedicated for this buffer."
     (switch-to-buffer (buffer-name (ecb-examples-action-buffer-create))))

We do not need more code for the action buffer. All of the code is standard
emacs-lisp which would also needed if used without ECB. You see that you can
use any arbitrary code as second argument for `defecb-window-dedicator' as
long it returns a buffer-name.

Adding the bufferinfo- and action-buffer to a new layout
........................................................

Now we add the bufferinfo- and the action-buffer to a new layout of type top
with name "example-layout1":

   (ecb-layout-define "example-layout1" top
   
     ;; dedicating the bufferinfo window to the bufferinfo-buffer
     (ecb-examples-set-bufferinfo-buffer)
   
     ;; creating the action-window
     (ecb-split-hor 0.75)
   
     ;; dedicate the action window to the action-buffer
     (ecb-examples-set-action-buffer)
   
     ;; select the edit-window
     (select-window (next-window)))

This all what we need to define the new layout. See *Note Programming a new
layout:: for more details of the pure layout-programming task.

Synchronizing the bufferinfo-buffer automatically
.................................................

The last thing we have to do is to synchronize the bufferinfo-buffer with
current edit-window. We do this by adding `ecb-examples-bufferinfo-sync' to
the hook `ecb-current-buffer-sync-hook'' (The file `ecb-examples.el' shows a
smarter mechanism for (de)activating the new layout and the synchronization
but this works also very well).

   (add-hook 'ecb-current-buffer-sync-hook 'ecb-examples-bufferinfo-sync)

Activating and deactivating new layouts
.......................................

Because a set of new special windows integrated in a new layout is often just
the GUI of a complete tool (like a graphical debugger) we demonstrate here
the complete activation and deactivation of such a tool or at least of the
tool-GUI. We decide that the GUI of our example "tool" needs a compile-window
with height 5 lines and the height of the special windows "row" on top should
be exactly 6 lines (normally width and height of the special windows should
be a fraction of the frame, but here we use 6 lines(2)

Here comes the (de)activation code.

The code for saving and restoring the state before activation (the full code
is available in `ecb-examples.el':

   (defun ecb-examples-preactivation-state(action)
     (cond ((equal action 'save)
            ;; code for saving the state
            )
           ((equal action 'restore)
           ;; code for restoring the state
           )))

The following function activates the GUI of our example tool:

   (defun ecb-examples-activate ()
     (interactive)
   
     ;; activating the synchronization of the bufferinfo-window
     (add-hook 'ecb-current-buffer-sync-hook
               'ecb-examples-bufferinfo-sync)
   
     ;; saving the state
     (ecb-examples-preactivation-state 'save)
   
     ;; switch to our preferred layout
     (setq ecb-windows-height 6)
     (setq ecb-compile-window-height 5)
     (ecb-layout-switch "example-layout1"))

This function deactivates the GUI of our example-tool and restores the state
as before activation:

   (defun ecb-examples-deactivate ()
     (interactive)
   
     (remove-hook 'ecb-current-buffer-sync-hook
                  'ecb-examples-bufferinfo-sync)
     (ecb-examples-preactivation-state 'restore)
     (ecb-layout-switch ecb-layout-name))

Now we have all code for the new layout and the new layout-buffers.  The
example is ready for use; just load `ecb-examples.el' (s.a.).

---------- Footnotes ----------

(1) JDEE is available at <http://jdee.sunsite.dk/>

(2) You can change the code in the file `ecb-examples.el' to use a
frame-fraction of 0.2 instead of 6 hard lines, just try it!


File: ecb.info,  Node: Possible layout-outlines,  Next: The layout-engine API,  Prev: Programming special windows,  Up: The layout-engine

The wide range of possible layout-outlines
------------------------------------------

In the two previous sections *Note Programming a new layout:: and *Note
Programming special windows:: we have explained in detail how to program new
layouts and how to program new special windows/buffers and adding them to a
new layout.

The intention of this section is to be a summary what are the real
restrictions for a new layout-outline programmed with `ecb-layout-define'.
This is necessary because until now we just programmed "obvious" layouts,
means layout which are in principle very similar to the standard ones which
means one big edit-window and some special windows "around" this edit-window.
This section will show you that a layout can have also very different
outlines.

OK, here are the real restrictions and conditions for a layout programmed
with `ecb-layout-define':
1. It must have exactly one edit-window regardless of its size. The user of
   this layout can later split this edit-window in as many edit-windows as he
   like.

2. All other windows created within the CREATE-CODE body of
   `ecb-layout-define' (*note Programming a new layout::) must be dedicated
   to their buffers.

3. All the dedicated windows must (exclusive!) either reside on the left,
   right, top or left-and-right side of the edit-window. This will be defined
   with the TYPE-argument of `ecb-layout-define' (*note Programming a new
   layout::).

You see, there are only three restrictions/conditions. These and only these
must be fulfilled at layout-programming.

Demonstrating what this really means and how flexible the layout-engine of
ECB really is, can be done best with some "pathological" layout-outlines. All
the following are correct layouts (working code is added below each layout):

The following is a top layout with three vertical layered special windows.

   ------------------------------------------------------------------
   |                                                                |
   |                 Upper special window                           |
   |                                                                |
   |----------------------------------------------------------------|
   |                                                                |
   |                 Middle special window                          |
   |                                                                |
   |----------------------------------------------------------------|
   |                                                                |
   |                 Lower special window                           |
   |                                                                |
   |================================================================|
   |                                                                |
   |                         Edit-area                              |
   |      (can be splitted by the user in several edit-windows)     |
   ------------------------------------------------------------------
   |                                                                |
   |                 Compilation-window (optional)                  |
   |                                                                |
   ------------------------------------------------------------------

Here is the code for that top layout (all buffers are dummy-buffers):


   ;; The "window dedicator" functions:
   
   (defecb-window-dedicator ecb-set-usw-buffer "Upper special window"
     (switch-to-buffer (get-buffer-create "Upper special window")))
   
   (defecb-window-dedicator ecb-set-msw-buffer "Middle special window"
     (switch-to-buffer (get-buffer-create "Middle special window")))
   
   (defecb-window-dedicator ecb-set-lsw-buffer "Lower special window"
     (switch-to-buffer (get-buffer-create "Lower special window")))
   
   ;; The layout itself:
   
   (ecb-layout-define "example-layout3" top
     nil
   
     ;; here we have an edit-window and above one top window which we can
     ;; now split in several other windows. Dependent on the value of
     ;; `ecb-compile-window-height' we have also a compile-window at the
     ;; bottom.
   
     (ecb-set-usw-buffer)
     (ecb-split-ver 0.33)
     (ecb-set-msw-buffer)
     (ecb-split-ver 0.5)
     (ecb-set-lsw-buffer)
   
     ;; select the edit-window.
     (select-window (next-window)))

The following is a left-right layout which has six special windows in the
left-"column" and one big special window in the right-"column". For
left-right layouts the left-"column" and the right-"column" have always the
same width.

   ------------------------------------------------------------------
   |             |       |                   |                      |
   | Left1       | Left5 |                   |                      |
   |             |       |                   |                      |
   |-------------|       |                   |                      |
   |      |      |       |                   |                      |
   |      |      |       |                   |                      |
   |      |      |       |                   |                      |
   | Left2| Left3|-------|     Edit-area     |   Right1             |
   |      |      |       | (can be splitted  |                      |
   |      |      |       |  in several edit- |                      |
   |      |      |       |      windows)     |                      |
   |-------------|       |                   |                      |
   |             |       |                   |                      |
   | Left4       | Left6 |                   |                      |
   |             |       |                   |                      |
   ------------------------------------------------------------------
   |                                                                |
   |                 Compilation-window (optional)                  |
   |                                                                |
   ------------------------------------------------------------------

Here is the code for that left-right layout, again with dummy-buffers
(depending to your screen-resolution you will need a quite big value for
`ecb-windows-width', e.g. 0.4):

Here is one of the "window dedicator"-functions(1):

   (defecb-window-dedicator ecb-set-left1-buffer "Left1"
     (switch-to-buffer (get-buffer-create "Left1")))

Here is the layout-definition itself:

   (ecb-layout-define "example-layout2" left-right
     nil
   
     ;; here we have an edit-window and left and right two windows each
     ;; with width `ecb-windows-width'. Dependent to the value of
     ;; `ecb-compile-window-height' we have also a compile-window at the
     ;; bottom.
   
     (ecb-set-left1-buffer)
     (ecb-split-hor 0.66 t)
     (ecb-split-ver 0.75)
     (ecb-set-left4-buffer)
     (select-window (previous-window (selected-window) 0))
     (ecb-split-ver 0.25 nil t)
     (ecb-set-left2-buffer)
     (ecb-split-hor 0.5)
     (ecb-set-left3-buffer)
     (select-window (next-window (next-window)))
     (ecb-set-left5-buffer)
     (ecb-split-ver 0.5)
     (ecb-set-left6-buffer)
     (select-window (next-window (next-window)))
     (ecb-set-right1-buffer))
   
     ;; select the edit-window
     (select-window (previous-window (selected-window) 0)))

Especially the last example should demonstrate that even very complicated
layouts are easy to program with `ecb-layout-define'.  If such layouts are
senseful is another topic ;-)

---------- Footnotes ----------

(1) The "window dedicators" for all these ecb-windows/buffers are not
explicitly described - they look all like `ecb-set-left1-buffer' - of course
with different buffer-names!


File: ecb.info,  Node: The layout-engine API,  Prev: Possible layout-outlines,  Up: The layout-engine

The complete layout-engine API of ECB
-------------------------------------

This section lists all functions, macros, variables and user-options the
layout-engine API of ECB offers foreign packages. Call `describe-function'
rsp. `describe-variable' to get a detailed description.

Functions and macros for programming with layouts and special ecb-windows:
 - `defecb-window-dedicator'

 - `ecb-available-layouts-member-p'

 - `ecb-canonical-ecb-windows-list'

 - `ecb-canonical-edit-windows-list'

 - `ecb-compile-window-live-p'

 - `ecb-compile-window-state'

 - `ecb-do-if-buffer-visible-in-ecb-frame'

 - `ecb-exec-in-window'

 - `ecb-get-current-visible-ecb-buffers'

 - `ecb-layout-define'

 - `ecb-layout-switch'

 - `ecb-layout-undefine'

 - `ecb-point-in-compile-window'

 - `ecb-point-in-ecb-window'

 - `ecb-point-in-edit-window'

 - `ecb-select-edit-window'

 - `ecb-split-hor'

 - `ecb-split-ver'

 - `ecb-where-is-point'

 - `ecb-with-dedicated-window'(1)

Utility functions/macros:
 - `ecb-display-one-ecb-buffer'

 - `ecb-enlarge-window'

 - `ecb-fix-filename'

 - `ecb-goto-ecb-window'

 - `ecb-window-live-p'

 - `ecb-with-readonly-buffer'

Some other maybe useful functions/macros:
 - `ecb-with-adviced-functions'

 - `ecb-with-original-functions'

 - `ecb-with-some-adviced-functions'

Some useful *READONLY* variables:
 - `ecb-compile-window'

 - `ecb-last-edit-window-with-point'

 - `ecb-last-source-buffer'

*Caution*: DO NOT USE THE VARIABLE `ecb-edit-window' IN YOUR PROGRAMS!

User-options and hooks related to the layout-engine API:
 - `ecb-current-buffer-sync-hook'

 - `ecb-hide-ecb-windows-after-hook'

 - `ecb-hide-ecb-windows-before-hook'

 - `ecb-redraw-layout-after-hook'

 - `ecb-redraw-layout-before-hook'

 - `ecb-show-ecb-windows-after-hook'

 - `ecb-show-ecb-windows-before-hook'

 - `ecb-windows-height'

 - `ecb-windows-width'

 - `ecb-compile-window-height'

---------- Footnotes ----------

(1) Normally not needed because `defecb-window-dedicator' does all necessary.


File: ecb.info,  Node: Conflicts and bugs,  Next: FAQ,  Prev: Elisp programming,  Up: Top

Conflicts and bugs of ECB
*************************

This chapter describes what to do when there are conflicts with other
packages and also the known (and currently unfixed) bugs of ECB. If possible
(and in most cases it is possible ;-) then a practicable solution or
workaround is described.

* Menu:

* Conflicts::                   Conflicts with other packages
* Bugs::                        Known bugs


File: ecb.info,  Node: Conflicts,  Next: Bugs,  Prev: Conflicts and bugs,  Up: Conflicts and bugs

Conflicts with other packages
=============================

This chapter contains a list of already known conflict between ECB and other
packages and how to solve them - in most cases ECB already contains a
suitable workaround.

That is followed by a general recipe what you can do when you have detected a
conflict between ECB and a package is not listed in the
know-conflicts-section.

Proved workarounds or recommendations for other packages
--------------------------------------------------------

Here is a list of packages which are proved to work properly with ECB and if
not (i.e. there are conflicts) then helpful solutions/hints/workarounds are
offered:

Package bs.el
.............

The package bs.el offers a nifty buffer-selection buffer. The main command of
this package is `bs-show'. With ECB < 2.20 this command does not really
working well within activated ECB. But as of version 2.20 of ECB there should
be no problems using this package.

If you add "*buffer-selection*" as buffer-name to the option
`ecb-compilation-buffer-names' then ECB will always display the
buffer-selection buffer of bs in the compile-window (if there is one).
Otherwise bs will use the edit-area to do its job.

Package BBDB
............

As of ECB 2.21 there should be no conflicts between BBDB and ECB, so BBDB can
be used even when the ECB-windows are visible.

But if you encounter problems then it is recommened to use one of the
window-managers escreen.el or winring.el (*note Window-managers and ECB::).
With such a window-manager ECB and BBDB should work together very well under
all circumstances!

Package calendar.el
...................

With activated ECB `calendar' does not shrink itīs window to the small size
but splits the window equally. But if you add this to your `.emacs' it works:

   (add-hook 'initial-calendar-window-hook
             (function (lambda ()
                         (when (and ecb-minor-mode
                                    (ecb-point-in-edit-window))
                           ;; if no horizontal split then nothing
                           ;; special to do
                           (or (= (frame-width) (window-width))
                               (shrink-window (- (window-height) 9))))
                        )))

Package cygwin-mount.el
.......................

There can be a conflict between ECB and cygwin-mount.el if the following
conditions are true:

 - You are working with cygwin-mount.el (sounds clear :-)

 - You have set `cygwin-mount-build-mount-table-asynch' to not nil

 - ECB is automatically started after starting Emacs (e.g. with
   `ecb-auto-activate' or calling `ecb-activate' in `window-setup-hook')

 - Your Emacs-setup contains a call of `cygwin-mount-activate'.

Under these circumstances Emacs 21.X sometimes eats up the whole CPU (at
least with Windows XP) and the cygwin-mount-table is never build.

But there is an easy work-around: Call `cygwin-mount-activate' first *AFTER*
ECB is activated. This can be done with the hook `ecb-activate-hook':

   (add-hook 'ecb-activate-hook
             (function (lambda ()
                         (require 'cygwin-mount)
                         (setq cygwin-mount-build-mount-table-asynch t)
                         (cygwin-mount-activate))))

Package desktop.el
..................

ECB works perfectly with the desktop-saver desktop.el. But to ensure this the
option `desktop-minor-mode-table' *MUST* contain the following entry:

   (ecb-minor-mode nil)

Without this entry desktop.el tries for each buffer it loads after
Emacs-start to enable `ecb-minor-mode' and therefore to start ECB. This
conflicts with ECB! Therefore you must add the entry above to
`desktop-minor-mode-table'!

Further it is strongly recommended to add entries for all the minor-mode of
the semantic-package to `desktop-minor-mode-table', so for example add also:

   (semantic-show-unmatched-syntax-mode nil)
   (semantic-stickyfunc-mode nil)
   (senator-minor-mode nil)
   (semantic-idle-scheduler-mode nil)

Which modes you have to add depends on which modes of semantic you use. But
to get sure you should add all minor-modes of the semantic-package because
these modes are normally activated by the related "global" command (e.g.
`global-semantic-show-unmatched-syntax-mode') or by adding the minor-mode to
the related major-mode-hook.

It has also been reported that just disabling the Tip-Of-The-Day (option:
`ecb-tip-of-the-day') fixes the compatibility-problems with desktop.el. Just
try it out!

Package edebug (Lisp Debugger)
..............................

It is strongly recommended to run edebug only when the ECB-windows are
hidden. With visible ECB-windows there will probably serious conflicts
between the ECB-layout and the edebug-window-manager.

Package ediff.el
................

In most cases ECB works very well with ediff (see option
`ecb-run-ediff-in-ecb-frame'). But currently suspending ediff with
`ediff-suspend' and restoring the ediff-session (e.g. with command
`eregistry') does confuse the window-management of ECB.

If you often use ediff in a scenario where you suspend ediff and reactivate
it later then it is recommended to exit ECB first (`ecb-deactivate' or
`ecb-minor-mode')!

Package func-menu.el
....................

This package has been reported to produce some conflicts under some
circumstances when ECB is activated. Some of them could be reproduced by the
ECB-maintainer. So the recommendation is to disable func-menu-support when
using ECB. Normally using func-menu makes no sense in combination with ECB
because ECB provides the same and even more informations as func-menu - so
func-menu is redundant ;-)

Package Gnus (Newsreader)
.........................

As of ECB 2.21 there should be no conflicts between Gnus and ECB, so Gnus can
be used even when the ECB-windows are visible.

But if you encounter problems then it is recommened to use one of the
window-managers escreen.el or winring.el (*note Window-managers and ECB::).
With such a window-manager ECB and Gnus should work together very well under
all circumstances!

Package JDEE (Java Development Environment)
...........................................

JDEE has a lot of "dialogs" where the user can select among several choices.
An example is importing classes via the command `jde-import-find-and-import'.
These dialogs are strongly designed to work in an environment where a new
temporary window is created, the contents of the dialog are displayed in the
new window, the user select his choice and hits [OK]. After that the new
window is deleted and the selection is performed (for example the chosen
import statement are inserted in the source-buffer.

*Caution*: ECB can work very well with this dialogs but only if the
buffer-name of these dialog-buffers (normally "Dialog") is not contained in
the option `ecb-compilation-buffer-names'. So do not add the string "Dialog"
to this option!

*Please Note*: Regardless if a persistent compile-window is used (i.e.
`ecb-compile-window-height' is not nil) or not, these JDEE-dialogs will
always being displayed by splitting the edit-window of ECB and not within the
compile-window.

Package scroll-all.el (scroll-all-mode)
.......................................

ECB advices `scroll-all-mode' so it is working correct during running ECB.
This means if point stays in an edit-window and the edit-window is splitted
then all edit-windows are scrolled by `scroll-all-mode' and no other window!
If point stays in any other window just this selected window is scrolled.
This is the only senseful behavior of `scroll-all-mode' with ECB.

Package VC (Version Control)
............................

The variable `vc-delete-logbuf-window' must be set to nil during active ECB.
This can be done with the hooks mentioned in *Note Elisp programming::.

Package VM (Emacs Mail-Client)
..............................

As of ECB 2.21 there should be no conflicts between VM and ECB, so VM can be
used even when the ECB-windows are visible.

But if you encounter problems then it is recommened to use one of the
window-managers escreen.el or winring.el (*note Window-managers and ECB::).
With such a window-manager ECB and VM should work together very well under
all circumstances!

Package winner.el (winner-mode)
...............................

`winner-mode' is autom. disabled as long as ECB is running. ECB has its own
window-management which is completely incompatible with `winner-mode'! But
`winner-mode' makes also not really sense with ECB.

Package wb-line-number.el
.........................

Do not use the package wb-line-number.el in combination with ECB - it will
not work and it will not work under any circumstances and there is no way to
make it work together and there will be no way in the future!

The reason behind that is: wb-line-number.el uses additional dedicated
windows to display the line-numbers. And ECB can not work if there there are
additional dedicated windows - additional to that ones created by ECB.

Application xrefactory
......................

Xrefactory (also known as Xref, X-ref and Xref-Speller), the refactoring
browser for (X)Emacs(1), can be used during running ECB regardless if the
ECB-windows are visible or not. There should be no conflicts as of ECB
versions >= 2.21.

If there are conflicts with the Xref-browser then the most recommended way is
to use one of the window-manager escreen.el or winring.el (and then use
different escreens or window-configurations for ECB and Xrefactory-browsing -
*Note Window-managers and ECB::).

What to do for unknown conflicts with other packages
----------------------------------------------------

As of version 2.20 the layout-engine of ECB is so flexible that normally
there should be no conflicts with other packages unless these packages have
their own complete window-layout-management (e.g. Gnus, BBDB, Xrefactory).
But these packages can and should be handled very well with the
window-manager-support of ECB (*note Window-managers and ECB::).

So if you detect an unknown (i.e. not listed in the conflicts-list in the
next subsection) conflict with a small package and some of its commands and
you have installed an ECB-version < 2.20 the first task you have to do is to
upgrade to a version >= 2.20!

If this doesn't solve the problem a very probable reason for the conflict is
that the command fails if called from another window than an edit-window of
the ecb-frame. So please check if the problem disappears if you call the
failing command from an edit-window of ECB.  If this is true then you you can
add the following code to your .emacs (and of course replace the XXX with the
failing command):

   (defadvice XXX (before ecb activate)
     "Ensures `XXX' works well when called from another window
   as an edit-window. Does nothing if called in another frame
   as the `ecb-frame'."
     (when (equal (selected-frame) ecb-frame)
       (unless (ecb-point-in-edit-window)
         (ecb-select-edit-window))))

This before-advice runs before the command XXX and ensures that the XXX is
called from within an edit-window if the current selected window is not an
edit-window. It does nothing if called for another frame as the ecb-frame.

If such an advice solves the problem then please send a note with the
solution to the ECB-mailing-list or direct to the ECB-maintainer so the
solution can be integrated in the next ECB-release

If calling from an edit-window fails too then please file a complete
bug-report to the ECB-mailing-list (*note Submitting problem report::). This
report should contain a detailed description which command of which package
fails under which circumstances!

---------- Footnotes ----------

(1) Xrefactory is available at <http://www.xref-tech.com>


File: ecb.info,  Node: Bugs,  Prev: Conflicts,  Up: Conflicts and bugs

Known bugs
==========

This section describes all currently known bugs of ECB. The maintainers of
ECB try to fix these bugs as soon as possible.

Following the source-file link in a help-buffer
-----------------------------------------------

The following bug occurs only in ECB-versions < 1.96 and is fixed since ECB
1.96!!

This bug only occurs if a compile-window is used and visible!

If you call functions like `describe-function' which displays a help-buffer
in the compile-window, then you will often get an output like this in the
compile-window:

   ecb-activate is an interactive compiled Lisp function in `ecb'.
   (ecb-activate)
   
   Activates the ECB...

The link to `ecb' is normally a click-able link, means if you click with the
middle-mouse button onto it the file is opened (in our example `ecb.el' would
be opened.

If you click onto it when the help-buffer is already the current buffer (i.e.
the compile-window is already selected before the click!)  then all is
working fine (i.e. the file is opened in the edit-window), but if you click
onto the link without selecting the compile-window before (i.e. the
edit-window is the current selected window) then the file is opened in the
compile-window which is probably not what you want. Not a big problem but
annoying.

The only available workaround is, first selecting the compile-window and then
clicking onto the link!

Extra history-entries for JDEE source-buffers
---------------------------------------------

ECB on occasions creates an extra edit buffer for entries in the history
window. For example, let say there are three entries in the history window:

   Test1
   Test2
   Test3

In the edit window Test1 file is edited. When clicked on Test2 entry in
history, on occasion instead of switching to the existing buffer for Test2, a
new edit buffer is opened for Test2 file. At this point, there are four
entries in the history as follows:

   Test2
   Test2<2>
   Test1
   Test3