Programming a new layout - ECB - the Emacs Code Browser
Description: ECB - the Emacs Code Browser

Next: Programming special windows, Previous: The layout-engine, Up: The layout-engine

#### 11.5.1 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` (see 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 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 doc &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 of the advice-sets `ecb-basic-adviced-functions` and `ecb-permanent-adviced-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`
>    - `ecb-set-analyse-buffer`
>    - `ecb-set-symboldef-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-to-ecb-buffer`: 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 to the special ecb-buffer at the end. This can be used by third party packages like JDEE to create arbitrary ECB-windows besides the standard special ecb-windows.

>    To make a special ECB-window a dedicated window either one of the seven functions above must be used or a new “window-dedicator”-function has to be defined with `defecb-window-dedicator-to-ecb-buffer` and must be used within the layout-definition.

> 3. Every(!) special ECB-window must be dedicated to a buffer 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                      |
       |                                                     |
       -------------------------------------------------------