Node:Programming a new layout, Next:, Previous: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 and history it's is strongly recommended to define the new layout interactively with the command ecb-create-new-layout (see Creating a new ECB-layout).

But if you want programming a new layout with elisp-code and if this layout should even contain other special windows than the standard ECB-windows use the macro ecb-layout-define (the following definiton has stripped the prefix "ecb-" for better indexing this manual):

layout-define name type &rest create-code Macro
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) resp. "row" (for a top layout) for the special ECB-windows/buffers. The width of the "column" resp. the height of the "row" is always defined with the option ecb-windows-width resp. 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 recommened 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
    Each layout can only contain one of each tree-buffer-type!

    In addition to these functions there is a general macro ecb-with-dedicated-window. This macro performs 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.

    It's strongly recommended not to use any other function/macro to make a window dedicated!

  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:

layout-undefine name Function
Unbind ecb-layout-function-<NAME>, ecb-delete-window-ecb-windows-<NAME>, ecb-delete-other-windows-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                      |
|                                                     |
-------------------------------------------------------