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, 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):

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) 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 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.

    To make a special ECB-window a dedicated window either one of the five functions above must be used or a function(!) which calls in turn the macro ecb-with-dedicated-window. See the documentation of this macro how to use it!

    Such a function is called a "dedicated setter" and must(!) use ecb-with-dedicated-window to make the 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                      |
|                                                     |
-------------------------------------------------------