Next: , 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
     ;; 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
     ;; 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                      |
   |                                                     |