6.8.5 Interactively creating new layouts

If you want to create your own ECB-layout then you can do this very easy “by example” with the command ecb-create-new-layout. This command creates a new empty frame and offers a small set of keys to create the new layout by splitting windows. ecb-create-new-layout and this couple of keys are your guide during the layout-creation-process¹.

After calling ecb-create-new-layout you will be asked which type of layout you want to create: “left”, “right”, “top” or “left-right”. Here you specify where the ECB-tree-windows/buffers should be located in the ECB-frame:

• left: All ECB-tree-windows are located on the left side
• right: All ECB-tree-windows are located on the right side
• top: All ECB-tree-windows are located on the top side
• left-right: All ECB-tree-windows are located on the left and right side

Depending on the type you choose the window is splitted by the values of the options ecb-windows-width (types “left”, “right” and “left-right”) or ecb-windows-height (type “top”).

Afterwards you will see a frame like follows (here the layout-type is “left-right”):

   -----------------------------------------------------------------
   |<point>       |                                   |            |
   |              | ECB-layout creation mode          |            |
   |              | ========================          |            |
   |              |                                   |            |
   |              | <This is a persistent help-screen>|            |
   |              |                                   |            |
   |              |                                   |            |
   |              |                                   |            |
   |              |                                   |            |
   |              |                                   |            |
   |              |                                   |            |
   |              |                                   |            |
   |              |                                   |            |
   |              |                                   |            |
   |              |                                   |            |
   -----------------------------------------------------------------
                  |
                  |   ,---
                  `---| Splitted by the value of ecb-windows-width.
                      `---

The big window (here the middle window) will be the edit-area of the new layout and can not be selected, deleted or splitted during the creation process. It displays the help-screen for the layout-creation mode. Here all the available commands are displayed.

The small window(s) (here the left and right windows) can be splitted by you wherever you want (C-s). The left one contains the point. You must give every ECB-tree-window you create a type (C-t) which can be either

• One of the built-in types

  This can be either “directories”, “sources”, “methods”, “history” or “speedbar”.

• Any user-defined type:

  In this case you insert “other” after hitting C-t and you will then be asked for the name of the user-defined type. You can insert any arbitrary type name X. But to get this layout working you have to define a function with name ecb-set-X-buffer whereas X is the name of the user-defined type you have specified during layout-creation.

  This function ecb-set-X-buffer must be defined with the macro defecb-window-dedicator-to-ecb-buffer and has to switch to the buffer you want to display in this window. This macro automatically ensures that this window is dedicated to that buffer.

  Here is an example: Suppose you have inserted as type name “example” then you have to define and load a function ecb-set-example-buffer which could be defined like follows:

          (defecb-window-dedicator-to-ecb-buffer ecb-set-example-buffer " *ECB example-buf*"
            (switch-to-buffer (get-buffer-create " *ECB example-buf*")))
  

  If you forget to define such a function for the user-defined type then nevertheless ECB will draw this layout but it will use the default-function ecb-set-default-ecb-buffer instead.

If you are satisfied with your new layout just hit C-q. You will be asked for a new layout-name (TAB-completion is offered to get a list of all names already in use) and after inserting a new(!) name the new layout is saved in the file defined by the option ecb-create-layout-file. The new layout is now available via the option ecb-layout-name.

There is no need for you to load the file ecb-create-layout-file manually into your Emacs because it's automatically loaded by ECB!

Please note: During the layout-creation process only the commands displayed in the help-screen are available. ALL other commands are temporally disabled (even the mouse-commands).

For programming new layouts with emacs-lisp see The layout-engine.

With the command ecb-delete-new-layout you can delete previously created layouts (TAB-completion is offered for all names of user created layouts).