« back to all changes in this revision
Viewing changes to info-help/ecb.info-9
- browse files at revision 4
- compare with another revision
- download diff
- download tarball
- view history from revision 4
- Committer: Bazaar Package Importer
- Author(s): Zak B. Elep
- Date: 2006-05-16 00:20:55 UTC
- mfrom: (1.1.2 upstream) (3.1.1 dapper)
- Revision ID: james.westby@ubuntu.com-20060516002055-6un1h7av7a5vwqqi
Tags: 2.32-1
* debian/control
Remove dependency to build PDF and html files.
* debian/emacsen-startup:
Change back to (require 'ecb-autoloads) for quick loading.
* Drop pdf file installation by default.
* Depend on cogre and cedet-contrib.
* Drop jde as suggests
Cai Qian <caiqian@debian.org> Sat, 3 Jue 2006 23:33:00 +0100
* New upstream release. (Closes: #289090, #269793, #292356)
* New maintainer (Closes: #321808).
* Change build system to use CDBS + debhelper.
* debian/rules:
- Remove extraneous .cvsignore files and bash scripts.
(Closes: #301939)
- dh_link now placed in debian/links .
- Handle doc installation via DEB_INSTALL_DOCS_ALL , remove
debian/docs .
* debian/patches:
- Add 10_Makefile_adjust.patch (old fixes)
* debian/control:
- Bump Standards-Version.
- Adjust debhelper dependency to (>= 5.0.7).
- Add homepage to long description.
- Add cdbs and debhelper to Build-Depends.
- Rewrite description synopsis.
* debian/copyright:
- Add notice from ecb.el . Must ping upstream to update FSF
address.
* debian/emacsen-install:
- Get ecb to find its images by properly linking to
/usr/share/emacs/site-lisp/ecb/ecb-images (Closes: #272506)
* debian/emacsen-startup:
- Use (require 'ecb) instead of (require 'ecb-autoloads) so we
can call ECB from the Tools menu (Closes: #296794)
Remove dependency to build PDF and html files.
* debian/emacsen-startup:
Change back to (require 'ecb-autoloads) for quick loading.
* Drop pdf file installation by default.
* Depend on cogre and cedet-contrib.
* Drop jde as suggests
Cai Qian <caiqian@debian.org> Sat, 3 Jue 2006 23:33:00 +0100
* New upstream release. (Closes: #289090, #269793, #292356)
* New maintainer (Closes: #321808).
* Change build system to use CDBS + debhelper.
* debian/rules:
- Remove extraneous .cvsignore files and bash scripts.
(Closes: #301939)
- dh_link now placed in debian/links .
- Handle doc installation via DEB_INSTALL_DOCS_ALL , remove
debian/docs .
* debian/patches:
- Add 10_Makefile_adjust.patch (old fixes)
* debian/control:
- Bump Standards-Version.
- Adjust debhelper dependency to (>= 5.0.7).
- Add homepage to long description.
- Add cdbs and debhelper to Build-Depends.
- Rewrite description synopsis.
* debian/copyright:
- Add notice from ecb.el . Must ping upstream to update FSF
address.
* debian/emacsen-install:
- Get ecb to find its images by properly linking to
/usr/share/emacs/site-lisp/ecb/ecb-images (Closes: #272506)
* debian/emacsen-startup:
- Use (require 'ecb) instead of (require 'ecb-autoloads) so we
can call ECB from the Tools menu (Closes: #296794)
- files added:
- debian/info
- debian/patches
- ecb-images/sources
- ecb-images/sources/height-14_to_21
- files removed:
- debian/docs
- files modified:
- Makefile
added
removed
info-help/ecb.info-9
6
6
END-INFO-DIR-ENTRY
7
7
8
8
9
File: ecb.info, Node: Non-semantic sources, Next: Hide-show, Prev: Compile-window on demand, Up: Tips and tricks
10
11
Parsing and displaying non-semantic sources
12
===========================================
13
14
ECB is mostly designed to display parsing information for files supported by
15
semantic. But beginning with version 1.94 it also supports other parsing
16
engines like imenu and etags, so also files not supported by semantic but by
17
imenu/etags can be displayed in the Method-buffer of ECB. See *Note
18
Definition of semantic- and non-semantic-sources:: for a description of
19
"semantic-sources" and "non-semantic-sources".
20
21
If support of non-semantic-sources is enabled then ECB will display the
22
contents of all sources which can be displayed by speedbar too. This comes
23
from the fact that ECB uses speedbar-logic to parse sources with imenu or
24
etags.
25
26
In most cases imenu-parsing is preferable over etags-parsing because imenu
27
operates on Emacs-buffers and needs no external tool and therefore parsing
28
works also if current contents of a buffer are not saved to disk.
29
30
This section describes all important aspects about parsing and displaying
31
file-contents of file-types not supported by semantic but by imenu and/or
32
etags.
33
34
Enabling parsing and displaying of non-semantic-sources
35
-------------------------------------------------------
36
37
Enabling is simply done with the option `ecb-process-non-semantic-files'.
38
39
ECB offers an option `ecb-non-semantic-parsing-function' to specify on a
40
major-mode basis which parsing-method should be used: imenu or etags.
41
Normally there should be no need to change this option but read the
42
documentation of this option (*note ecb-non-semantic::) for further details.
43
44
IMPORTANT:
45
46
* If imenu-parsing should be used then the option `speedbar-use-imenu-flag'
47
must be set to not `nil'!
48
49
* If some non-semantic-sources are not parsed (i.e. there is an empty
50
Methods-buffer) and you think that they should then maybe they are neither
51
supported by imenu nor by etags or you have to check the options
52
`ecb-non-semantic-parsing-function' and
53
`speedbar-dynamic-tags-function-list' and - especially for etags -
54
`speedbar-fetch-etags-parse-list', `speedbar-fetch-etags-arguments' and
55
`speedbar-fetch-etags-command'.
56
57
* Even with support for semantic-, imenu- and etags-parsing there will
58
remain some file-types rsp. `major-modes' which are not parse-able,
59
neither by semantic, imenu nor etags. This is no problem because these
60
files simply have an empty Methods-buffer. But nevertheless you will get a
61
message "Sorry, no support for a file of that extension" which comes from
62
the speedbar-library and can not switched off. Therefore if a `major-mode'
63
is known as not parse-able by semantic, imenu or etags it can be added to
64
the option `ecb-non-semantic-exclude-modes' and then it will be excluded
65
from being tried to parsed and this (annoying) message will not occur.
66
67
Automatic rescanning/reparsing of non-semantic-sources
68
------------------------------------------------------
69
70
In contrast to semantic (see `global-semantic-auto-parse-mode') there is no
71
built-in mechanism for autom. reparsing non-semantic-sources and then
72
updating the contents of the Methods-buffer.
73
74
For non-semantic-sources you have always at least to call
75
`ecb-rebuild-methods-buffer' (bound to `C-c . r') or saving the source-file
76
(if `ecb-auto-update-methods-after-save' is true) to update the
77
Method-buffer(1).
78
79
Depending on the parsing-mechanism the following options have to be switched
80
on so ECB can rebuild the methods-buffer for non-semantic-sources:
81
82
* imenu:
83
84
The imenu-option `imenu-auto-rescan' must be enabled and
85
`imenu-auto-rescan-maxout' has to be set big enough to auto-parse big
86
files too! But this results not directly in an autom. updated
87
Method-buffer. This is first done after calling the command
88
`ecb-rebuild-methods-buffer' or saving the source-file (if
89
`ecb-auto-update-methods-after-save' is true).
90
91
* etags:
92
93
Only if `ecb-auto-save-before-etags-methods-rebuild' is switched on the
94
command `ecb-rebuild-methods-buffer' rebuilds the method-buffer with
95
current source-contents. See description of this option for an explanation.
96
97
Tip: If you want to program your own real. automatic rescan/reparse/rebuild
98
mechanism for non-semantic-sources you can do:
99
100
Adding to `after-change-functions' a function F which either runs itself
101
`ecb-rebuild-methods-buffer-for-non-semantic' or which adds only another
102
function FF to an idle-timer and the function FF runs
103
`ecb-rebuild-methods-buffer-for-non-semantic'. The latter approach has the
104
advantage that the reparse/rebuild is not performed immediately after every
105
change but first after Emacs is idle for a senseful interval (e.g. 4 seconds)
106
after last change. Of course the function FF has to cancel its own idle-timer
107
at the end, so the next idle-timer is first started again after the next
108
change (i.e. by function F which is still contained in
109
`after-change-functions'.
110
111
Customizing the display of the tags
112
-----------------------------------
113
114
For non-semantic-sources ECB uses does no special organizing of tags in
115
groups and sub-tags but it completely uses the tag-hierarchy the imenu- and
116
etags-parsers of speedbar return. So the displayed tag hierarchy can only be
117
customized with some options speedbar offers for this:
118
119
`speedbar-tag-hierarchy-method', `speedbar-tag-group-name-minimum-length',
120
`speedbar-tag-split-minimum-length' and
121
`speedbar-tag-regroup-maximum-length'. See the speedbar documentation for
122
details about these options.
123
124
With the option `ecb-method-non-semantic-face' you can define the face used
125
for displaying the tags in the Method-buffer for non-semantic-sources.
126
127
`ecb-non-semantic-methods-initial-expand' can be useful too.
128
129
---------- Footnotes ----------
130
131
(1) Maybe future versions of ECB (> 1.94) will offer an autom. mechanism for
132
this.
133
134
135
File: ecb.info, Node: Hide-show, Next: Window-managers and ECB, Prev: Non-semantic sources, Up: Tips and tricks
136
137
Using hide-show from the methods-buffer-menu
138
============================================
139
140
The popup-menu of the Methods-buffer offer two entries for either hiding or
141
showing the block which is related to the selected tag (that tag for which
142
the popup-menu was opened):
143
144
* "Jump to tag and hide block": Jumps to the tag and calls `hs-hide-block'
145
from the hideshow-library which is shipped with (X)Emacs. After that the
146
block is hidden, i.e. only the header-line of that tag (method, variable
147
etc.) is visible, the rest is hidden behind the "...".
148
149
* "Jump to tag and show block": Jumps to the tag and calls `hs-show-block'.
150
This shows the related hidden block if the block was hidden via
151
`hs-hide-block' or the menu-entry "Jump to tag and hide block" (s.a.).
152
153
For this feature the library `hideshow.el' is used which should normally
154
being included in the (X)Emacs-distribution. If this library is not loaded
155
into Emacs, ECB does this automatically before the first call to one of these
156
menu-entries.
157
158
IMPORTANT: If in some `major-mode' hiding and showing does not work as you
159
expect it to work then you must probably add an entry for this `major-mode'
160
to the hideshow-variable `hs-special-modes-alist'. See the documentation of
161
this variable for further details. One example of such a `major-mode' is
162
`jde-mode' of the Java Development Environment JDEE; just add an entry for it
163
like the already contained entries for `c++-mode' or `java-mode' and hiding
164
and showing will work for you with JDEE too.
165
166
167
File: ecb.info, Node: Window-managers and ECB, Next: Tree-buffer styles, Prev: Hide-show, Up: Tips and tricks
168
169
Support of several Emacs-window-managers
170
========================================
171
172
There are several window-managers available which offer an easy interface to
173
jump between different window-configurations within the same frame. A window
174
configuration is the layout of windows and associated buffers within a frame.
175
There is always at least one configuration, the current configuration. You
176
can create new configurations and cycle through the layouts in either
177
direction. Window configurations are often named or numbered, and you can
178
jump to and delete named rsp. numbered configurations.
179
180
Without special support by ECB these window-managers would not work in
181
combination with ECB!
182
183
ECB currently supports the following managers:
184
185
* winring.el: Written by Barry A. Warsaw <bwarsaw@python.org>, available at
186
<http://www.python.org/emacs/>
187
188
* escreen.el: Written by Noah Friedman <friedman@splode.com>, available at
189
<http://www.splode.com/~friedman/software/emacs-lisp/>
190
191
*IMPORTANT*: With one of these window-managers installed and active you can
192
run applications like Gnus, VM or BBDB in the same frame as ECB! Just use
193
different window-configurations (winring.el) or escreens (escreen.el) for ECB
194
and the other applications. Especially with winring.el you can give every
195
configuration a descriptive name like "ECB" or "Gnus"; afterwards you can
196
jump to a window-configuration by name!
197
198
When you go back to the ECB-window-configuration (winring.el) or the
199
ECB-escreen (escreen.el) with any of the special window-manager-commands then
200
the state of ECB will be restored exactly as you have left it when going to
201
another window-configuration rsp. escreen. This includes the whole splitting
202
state of the edit-area and the visibilty of the ecb-windows and of the
203
compile-window!
204
205
The rest of this section describes how to enable the special ECB-support for
206
these window-managers and how to use them.
207
208
Enabling of the support
9
File: ecb.info, Node: ecb-layout, Next: ecb-compilation, Prev: ecb-analyse, Up: Customizable options
10
11
Group ecb-layout
12
----------------
13
14
This group contains settings for the screen-layout of the ECB:
15
16
- User Option: activate-before-new-frame-created-hook
17
Normal hook run before the new ECB-frame is created if `ecb-new-ecb-frame'
18
is not nil (otherwise this hook is not evaluated).
19
20
- User Option: advice-window-functions
21
Advice functions to be more intelligent if used with ECB. You can choose
22
the following functions to be adviced by ECB so they behave as if the
23
edit-window(s) of ECB would be the only windows(s) of the ECB-frame:
24
25
* `other-window' For this one see also the option
26
`ecb-other-window-behavior'!
27
28
* `delete-window'
29
30
* `delete-other-windows'
31
32
* `delete-windows-on'
33
34
* `split-window-horizontally'
35
36
* `split-window-vertically'
37
38
* `split-window' If this advice is enabled then `split-window-vertically'
39
and `split-window-horizontally' are autom. enabled too!
40
41
* `switch-to-buffer'
42
43
* `switch-to-buffer-other-window'
44
45
* `display-buffer' Especially if `ecb-compile-window-height' is not nil
46
it is strongly recommended not to disable this advice!
47
48
* `other-window-for-scrolling' If this advice is enabled then the
49
behavior of the following functions depends on
50
`ecb-other-window-behavior':
51
- `scroll-other-window'
52
53
- `scroll-other-window-down'
54
55
- `beginning-of-buffer-other-window'
56
57
- `end-of-buffer-other-window'
58
59
* `balance-windows': Only the edit-windows are balanced
60
61
For working most conveniently with ECB it is the best to advice all these
62
functions, because then all the standard shortcuts of these functions are
63
also usable with ECB without doing anything else. Also other packages can
64
interact best with ECB if these functions are all adviced. If these
65
adviced functions are called in another frame than the ECB-frame they
66
behave all exactly like the not adviced versions!
67
68
But please read also the following:
69
70
Normally all packages should work correct with ECB and it�s adviced
71
functions but if there occur problems with a package cause of some of
72
these adviced functions ECB offers the following fall-back solution:
73
74
1. Deactivate in `ecb-advice-window-functions' all the adviced-functions
75
which make problems with other packages.
76
77
2. For every of the advice-able functions <adv-func> ECB offers a
78
interactively function named "ecb-<adv-func>" which does exactly the
79
same as the adviced version of <adv-func>. Use "ecb-<adv-func>" instead
80
the original one to get the proper ECB behavior even if the function is
81
not adviced anymore.
82
83
3. You can bind in `ecb-activate-hook' the standard-shortcut of <adv-func>
84
to "ecb-<adv-func>" and rebind it in `ecb-deactivate-hook' to
85
<adv-func>.
86
87
4. Now you have the best of both worlds: The problematic package works and
88
you have the ECB-behavior of <adv-func> as if it would be adviced.
89
90
Here is an example: Suppose you must deactivating the advice for
91
`switch-to-buffer-other-window'. Then you deactivate this function with
92
this option and you can use `ecb-switch-to-buffer-other-window' instead.
93
Bind the shortcut you normally use for `switch-to-buffer-other-window' to
94
`ecb-switch-to-buffer-other-window' (use `ecb-activate-hook' for this) and
95
rebind it to the original function in the `ecb-deactivate-hook'.
96
97
- User Option: advice-window-functions-signal-error
98
Signal an error if an adviced function can not do its job. If not nil then
99
an error is signaled if one of the adviced functions (see
100
`ecb-advice-window-functions') can not do its job. So for example if the
101
user tries to split the compile-window or an ecb-tree-window or if one
102
tries to switch to another buffer in one of the ecb-tree-windows. For
103
details see the documentation of each of the adviced functions to get info
104
when an error is signaled.
105
106
If this option is nil then no error is signaled but the called adviced
107
function does simply nothing.
108
109
Default is nil but it can also be useful to signal errors - so you see
110
when call a function in a situation which is not supported by this
111
function.
112
113
- User Option: fix-window-size
114
Fix size of the ECB-windows/buffers even after frame-resizing. The fix
115
type (valid values are nil, t, width and height) can either be set on a
116
layout-basis (means a different value for each layout) or one value can be
117
set for all layouts.
118
119
For a detailed description of the valid values see description of
120
`window-size-fixed' which is newly introduced in GNU Emacs 21 and is only
121
available there. Therefore this option takes only effect with GNU Emacs 21.
122
123
Note1: Manually resizing the ECB-windows via `enlarge-window',
124
`shrink-window', `mouse-drag-vertical-line' and `mouse-drag-mode-line' is
125
still possible even if the window-sizes are fixed for frame-resizing!
126
127
Note2: The description of `window-size-fixed' in the Elisp-info-manual is
128
more detailed than the description offered by `C-h v'!
129
130
Note3: With current Emacs 21.2.X there seems to be no distinction between
131
`width', `height' and `t'. Therefore this option takes no effect (means
132
all ecb-windows have always unfixed sizes) if `ecb-compile-window-height'
133
is not `nil'.
134
135
Per default no window-size fixing has been done.
136
137
- User Option: hide-ecb-windows-after-hook
138
Hooks run direct after the ECB windows have been hidden. Hiding was done
139
either by `ecb-toggle-ecb-windows' or `ecb-hide-ecb-windows'.
140
141
IMPORTANT: Hiding the ECB-windows is internally done by calling
142
`ecb-redraw-layout' and therefore also the hooks
143
`ecb-redraw-layout-before-hook' and `ecb-redraw-layout-after-hook' are
144
evaluated. The hook-sequence is analogous to that described in
145
`ecb-show-ecb-windows-after-hook'.
146
147
- User Option: hide-ecb-windows-before-hook
148
Hook run direct before the ECB windows will be hidden. Hiding is done
149
either by `ecb-toggle-ecb-windows' or `ecb-hide-ecb-windows'. This means
150
that at runtime of this hook all the ECB-tree-windows of current layout
151
are visible.
152
153
IMPORTANT: Hiding the ECB-windows is internally done by calling
154
`ecb-redraw-layout' and therefore also the hooks
155
`ecb-redraw-layout-before-hook' and `ecb-redraw-layout-after-hook' are
156
evaluated. The hook-sequence is analogous to that described in
157
`ecb-show-ecb-windows-before-hook'.
158
159
- User Option: ignore-display-buffer-function
160
Adviced `display-buffer' ignores `display-buffer-function'. This means,
161
that the adviced version of `display-buffer' (see
162
`ecb-advice-window-functions') ignores the value of
163
`display-buffer-function' when called for the `ecb-frame'. If this
164
variable should not be ignored then the function of
165
`display-buffer-function' is completely responsible which window is used
166
for the buffer to display - no smart ECB-logic will help to deal best with
167
the ECB-window-layout! You can define if and when
168
`display-buffer-function' should be ignored:
169
170
- only when persistent compile window is used - i.e. if
171
`ecb-compile-window-height' is not nil
172
173
- always when ECB is active - that means ignore when ECB is active
174
otherwise not - this is the default value
175
176
- never, the adviced version of `display-buffer' always uses the value of
177
`display-buffer-function' if the value is a function.
178
179
- User Option: ignore-special-display
180
Ignore special-display-handling. This means, that all values of
181
`special-display-function', `special-display-buffer-names' and
182
`special-display-regexps' are ignored
183
184
* only when persistent compile window is used - i.e. if
185
`ecb-compile-window-height' is not nil - this is the default value.
186
187
* always when ECB is active - that means no special-display-handling of
188
buffers when ECB is active
189
190
* never, i.e. special-dislay-handling depends on the values of the
191
options `special-display-function', `special-display-buffer-names' and
192
`special-display-regexps'.
193
194
195
- User Option: layout-always-operate-in-edit-window
196
Adviced window functions work always in the edit-window. If we are in an
197
ECB special buffer (methods, directories, etc), and any of the adviced
198
windowing functions is called interactively (see
199
`ecb-advice-window-functions'), we will select first an edit-window
200
according to the value of `ecb-mouse-click-destination'. This is useful if
201
you have any functions that use such functions and you don't want them to
202
fail with an error complaining that the current buffer can not be split, or
203
something similar.
204
205
Because this may not be desirable in all situations and for all adviced
206
functions this can be enabled separately for every advicable function (see
207
also `ecb-advice-window-functions'). If the symbol of an adviced function
208
is contained in the value of this option, then a edit-window is first
209
selected otherwise either an error is reported or some other special
210
reaction (depends on `ecb-advice-window-functions-signal-error'); see the
211
documentation of the adviced functions for this.
212
213
For `other-window', `other-window-for-scrolling' and
214
`switch-to-buffer-other-window' this makes no sense, therefore you can not
215
enable this for them.
216
217
Per default this is enabled for `switch-to-buffer' and `display-buffer'.
218
219
- User Option: layout-debug-mode
220
Write debug-information about layout-operations in the Messages-buffer.
221
Normally there should be no need to set this option to true but if there
222
are problems to display buffers in the compile-window of ECB (e.g. buffers
223
which should be displayed there aren't or the temporally
224
enlarging-mechanism does not do what you think it should do etc...) then
225
please do the following steps:
226
227
1. Set `ecb-layout-debug-mode' to not nil
228
229
2. Reproduce the wrong behavior exactly by repeating all the operations
230
which lead to the problem.
231
232
3. Now send immediately a bug report with `ecb-submit-problem-report'.
233
234
4. Set `ecb-layout-debug-mode' back to nil if you do not want further
235
debugging output in the *Messages* buffer
236
237
- User Option: layout-name
238
Select a window layout of ECB. Value is any arbitrary string. There are
239
four different types of layouts: left, right, top and left-right, which
240
means the location of the ECB-tree-windows in the ECB-frame. Currently
241
there are 20 predefined layouts; names see below. You can savely try out
242
any of them by changing this value and saving it only for the current
243
session. If you are sure which layout you want you can save it for future
244
sessions. To get a picture of the layout for name <name> call
245
`ecb-show-layout-help'. `ecb-layout-function-9'.
246
247
Currently available layouts:
248
249
* Left layouts: left1 left2 left3 left4 left5 left6 left7 left8 left9
250
left10 left11 left12 left13 left14 left15
251
252
* Right layouts: right1
253
254
* Top layouts: top1 top2
255
256
* Left-right layouts: leftright1 leftright2
257
258
Regardless of the settings you define here: If you have destroyed or
259
changed the ECB-screen-layout by any action you can always go back to this
260
layout with `ecb-redraw-layout'
261
262
- User Option: layout-window-sizes
263
Specifies the sizes of the ECB windows for each layout. The easiest way
264
(and also the strongly recommended way) to change this variable is to
265
change the window sizes by dragging the window borders using the mouse and
266
then store the window sizes by calling the command
267
`ecb-store-window-sizes'. Next time the layout is redrawn the values
268
stored in this option will be used.
269
270
If `ecb-store-window-sizes' is used then the windows sizes are stored per
271
default as fractions of current frame-width and -height of the ecb-frame,
272
so the stored values will "work" for other frame sizes too. But if you
273
call `ecb-store-window-sizes' with a prefix-argument then the fixed values
274
of current width and height are stored!
275
276
If this option is set "by hand" (i.e. not by `ecb-store-window-sizes')
277
then the following is important:
278
- It is recommended to use fractions of frame-width and -height!.
279
280
- The order of the sequence of the inserted window sizes must be the same
281
as `other-window' (the not-adviced version!) would walk!
282
283
- User Option: maximize-ecb-window-after-selection
284
If not nil maximize current tree-window after selection. When selecting
285
another not-tree-window after such an automatic maximizing all
286
tree-windows of current layout are displayed again. But a tree-window is
287
not maximized if either a node has been selected via primary- oder
288
secondarc mouse-button or the popup-menu of that tree-buffer has been
289
opened.
290
291
- User Option: maximize-next-after-maximized-select
292
Maximizes the next logical tree-window after a maximized node-selection.
293
Selecting a node in a maximized tree-window is handled very smart by ECB:
294
295
If a tree-buffer-name is not contained in this option then selecting a
296
node in this maximized tree-buffer automatically "minimizes" that
297
tree-window (i.e. displays all windows of the current layout) so the user
298
can perform the next logical step (e.g. the next logical step after
299
selecting a directory in the directories-buffer is to select a source-file
300
- therefore the sources-buffer of current layout has to be displayed - if
301
the current layout contains one; the next logical step of selecting a
302
source-file is probably to jump to a certain tag via the methods-buffer).
303
304
If a tree-buffer-name is contained in this option then selecting a node in
305
this tree-buffer automatically maximizes the next logical tree-window
306
(e.g. directories -> sources, sources/history -> methods). But if the
307
current maximized tree-buffer is also contained in the option
308
`ecb-tree-do-not-leave-window-after-select' (see also the
309
tree-buffer-command `ecb-toggle-do-not-leave-window-after-select' which is
310
bound to `C-t' in each tree-buffer) then ECB does *not* maximize the next
311
logical tree-window but point stays in the currently maximized tree-buffer
312
so for example the user can select more than one node (e.g. more than one
313
source-file from the sources-buffer.
314
315
The tree-buffer-name can either be defined as plain string or with a
316
symbol which contains the buffer-name as value. The latter one is
317
recommended for the builtin ECB-tree-buffers because then simply the
318
related option-symbol can be used (e.g. `ecb-directories-buffer-name',
319
`ecb-sources-buffer-name' or `ecb-history-buffer-name').
320
321
In future versions this option will probably also allow to define the next
322
logical tree-buffer for a tree-buffer - currently this is hard-coded as
323
follows:
324
- directories -next-logical-> sources
325
326
- sources -next-logical-> methods
327
328
- history -next-logical-> methods.
329
330
- User Option: maximize-next-after-maximized-select
331
Maximizes the next logical tree-window after a maximized node-selection.
332
Selecting a node in a maximized tree-window is handled very smart by ECB:
333
334
If this option is nil then selecting a node in a maximized directories-
335
sources- or history-tree-buffer automatically "minimizes" that tree-window
336
(i.e. displays all windows of the current layout) so the user can perform
337
the next logical step (e.g. the next logical step after selecting a
338
directory in the directories-buffer is to select a source-file - therefore
339
the sources-buffer of current layout has to be displayed - if the current
340
layout contains one; the next logical step of selecting a source-file is
341
probably to jump to a certain tag via the methods-buffer).
342
343
If this option is not nil then selecting a node in a maximized
344
directories- sources- or history-tree-buffer automatically maximizes the
345
next logical tree-window (directories -> sources, sources/history ->
346
methods). But if the current maximized tree-buffer is contained in the
347
option `ecb-tree-do-not-leave-window-after-select' (see also the
348
tree-buffer-command `ecb-toggle-do-not-leave-window-after-select' which is
349
bound to `C-t' in each tree-buffer) then ECB does *not* maximize the next
350
logical tree-window but point stays in the currently maximized tree-buffer
351
so for example the user can select more than one source-file from the
352
sources-buffer.
353
354
- User Option: new-ecb-frame
355
Create a new frame at activation time of ECB.
356
357
- User Option: other-window-behavior
358
The behavior of ECB concerning getting an "other window". This has an
359
effect if either `other-window' or `other-window-for-scrolling' is adviced
360
by ECB, see `ecb-advice-window-functions'. The following settings are
361
possible:
362
363
`all':
364
365
ECB will cycle through all windows of the ECB-frame or scroll simply the
366
next window in the ECB-frame, means it behaves like the original
367
`other-window' rsp. the original `other-window-for-scrolling'.
368
369
`only-edit':
370
371
ECB will only cycle through the edit-windows of ECB or only scroll another
372
edit-window. If the selected window is not an edit-window then it behaves
373
like with value `all'.
374
375
`edit-and-compile':
376
377
Like `only-edit' plus the compile window if any. If the selected window is
378
neither an edit-window nor the compile-window then it behaves like with
379
value `all'.
380
381
`smart':
382
383
With this setting ECB tries to choose the `other-window'-destination or
384
the "other window" to scroll in a smart and intuitive way: If point is in
385
one of the edit-windows and if the edit-area is splitted then always the
386
"next" edit-window is choosen (whereas the next edit-window of the last
387
edit-window is the first edit-window)- if the edit-area is unsplitted then
388
the compile-window is used if there is one. In the context of an
389
`other-window'-call the ARG of `other-window' will be taken into account.
390
391
If one of the special ecb-windows is selected then always the "next"
392
ecb-window is choosen (whereas the next ecb-window of the last ecb-window
393
is the first ecb-window). In the context of an `other-window'-call the ARG
394
of `other-window' will be taken into account. If there is only one
395
ecb-window then ECB considers also the edit-windows
396
397
If the compile-window is selected then always the last edit-window which
398
had the point will be used unless `other-window' has been called with a
399
prefix-argument unequal 1.
400
401
If there is an active minibuffer:
402
403
Regardless of the allowed values above ECB handles the situation of an
404
active minibuffer during a call to `other-window' or `scroll-other-window'
405
like follows:
406
407
If the minibuffer-window is selected then ECB always chooses the window
408
`minibuffer-scroll-window' points to (when this variable is set, otherwise
409
the compile-window or the last selected edit-window is choosen) when the
410
called command is called to choose the 1. next window (always true for
411
scrolling another window or true when `other-window' called without
412
prefix-arg or with prefix-arg equal 1). Otherwise the window ARG steps
413
away is choosen (in case of `other-window').
414
415
If there is an active minibuffer but the minibuffer-window is not selected
416
then `other-window' and `scroll-other-window' behave like the original
417
version.
418
419
In addition to the allowed values above the value of this option can also
420
be a function:
421
422
A function:
423
424
This function gets seven arguments:
425
1. A canonical list of all currently visible windows of the `ecb-frame'
426
427
2. A canonical list of all currently visible edit-windows
428
429
3. A canonical list of all currently visible ecb-windows
430
431
4. The window-object of the compile-window if there is any.
432
433
5. The minibuffer-window of the ECB-frame if there is an active minibuffer.
434
435
6. The result of the function `ecb-where-is-point' - see the documentation
436
of this function for details.
437
438
7. An integer which indicates how many steps away from the current
439
selected window the "other-window" is. Is nil when this function is
440
called in another context then for `other-window'.
441
442
The function has to return a window-object which is then used as "other
443
window" for the command `other-window' or for scrolling another window
444
(e.g. with `scroll-other-window'). Such a function has to handle properly
445
all situation for itself. `ecb-get-other-window-smart' is an example for
446
such a function.
447
448
- User Option: redraw-layout-after-hook
449
Hooks run direct before the ECB windows will be shown either by
450
`ecb-toggle-ecb-windows' or `ecb-show-ecb-windows'. This means that at
451
runtime of this hook the ECB-windows are already visible.
452
453
- User Option: redraw-layout-before-hook
454
Hooks run direct before the ECB-layout will be redrawn by either
455
`ecb-redraw-layout'.
456
457
- User Option: redraw-layout-quickly
458
If non-nil, we will attempt to redraw the layout quickly. Please read also
459
carefully the documentation of `ecb-redraw-layout'.
460
461
- User Option: select-edit-window-on-redraw
462
Select the first edit window on `ecb-redraw-layout'.
463
464
- User Option: show-ecb-windows-after-hook
465
Hooks run direct before the ECB windows will be shown either by
466
`ecb-toggle-ecb-windows' or `ecb-show-ecb-windows'. This means that at
467
runtime of this hook the ECB-windows are already visible.
468
469
IMPORTANT: Showing the hidden ECB-windows is internally done by calling
470
`ecb-redraw-layout' and therefore also the hooks
471
`ecb-redraw-layout-before-hook' and `ecb-redraw-layout-after-hook' are
472
evaluated. So there is the following sequence of hooks during the process
473
of showing the hidden ECB-windows:
474
1. `ecb-show-ecb-windows-before-hook'
475
476
2. `ecb-redraw-layout-before-hook'
477
478
3. <redrawing the layout to show the hidden ECB-windows>
479
480
4. `ecb-redraw-layout-after-hook'
481
482
5. `ecb-show-ecb-windows-after-hook'
483
So be aware which code you add to which hook!
484
485
- User Option: show-ecb-windows-before-hook
486
Hooks run direct before the ECB windows will be shown either by
487
`ecb-toggle-ecb-windows' or `ecb-show-ecb-windows'. This means that at
488
runtime of this hook the ECB-windows are still hidden.
489
490
IMPORTANT: Showing the hidden ECB-windows is internally done by calling
491
`ecb-redraw-layout' and therefore also the hooks
492
`ecb-redraw-layout-before-hook' and `ecb-redraw-layout-after-hook' are
493
evaluated. So there is the following sequence of hooks during the process
494
of showing the hidden ECB-windows:
495
1. `ecb-show-ecb-windows-before-hook'
496
497
2. `ecb-redraw-layout-before-hook'
498
499
3. <redrawing the layout to show the hidden ECB-windows>
500
501
4. `ecb-redraw-layout-after-hook'
502
503
5. `ecb-show-ecb-windows-after-hook'
504
So be aware which code you add to which hook!
505
506
- User Option: split-edit-window-after-start
507
Sets if and how the edit window should be splitted after ECB-start. But
508
be aware: This option determines only if and how the edit-window should be
509
splitted at start-time of ECB. There are five different values allowed for
510
this option:
511
512
- `nil': Do not split the edit-area of ECB after activation, i.e. there
513
will be only one edit-window after starting ECB.
514
515
- `horizontal': Split the edit-area in 2 edit-windows side by side.
516
517
- `vertical': Split the edit-area in 2 edit-windows, one above the other.
518
519
- `before-activation': Split the edit-area as before the ECB-start, i.e.
520
the edit-area will have after start a window-layout as the whole frame
521
had before the start of ECB.
522
523
- `before-deactivation': Split the edit-area into a window-layout ECB had
524
in its edit-area direct before the ECB-deactivation. This value
525
preserves the full state between activations of ECB, i.e. the
526
visibility of the ECB-windows, the visibility of a compile-window and
527
also the full split-state of the edit-area. But this can only be done
528
if important layout-options have not been changed in the meanwhile.
529
These are the options `ecb-layout-name', `ecb-compile-window-height',
530
`ecb-compile-window-width', `ecb-windows-width' and
531
`ecb-windows-height'.
532
533
Default value is `before-deactivation'.
534
535
Some remarks to the value `before-activation': If this value has been set
536
then ECB needs three permanent adivces even when ECB is deactivated:
537
`split-window', `delete-window' and `delete-other-windows'. But these
538
advices do not change any behavior of these functions but only storing in
539
an internal ECB-variable the facts that a window has been splitted or
540
deleted. In addition to this these advices are 100% error-save, means the
541
functionality of the original functions will be performed in every(!)
542
case even if within the advice an error occurs (but normally there can no
543
errors occur in these advices because they are very simple). Conclusion:
544
If you want really all ECB-advices being disabled after deactivating ECB
545
then you have to set this option to other values then `before-activation'.
546
But setting this variable to this value is really completely save.
547
548
- User Option: toggle-layout-sequence
549
Toggle sequence for layout toggling with `ecb-toggle-layout'. Every
550
element of this list has to be a valid layout-name i.e. either one of the
551
predefined layouts or one of the user-defined layouts.
552
553
You can add here as many layouts as you want but to use this option most
554
effective you should not add more than 2 or 3 layouts so every layout can
555
be accessed very fast by toggling with `ecb-toggle-layout'. It is also
556
senseful to add layouts which have the same principal outline, i.e. all
557
their tree-buffers are on the same side of the frame and the
558
tree-buffer-"column" (or -"row") has identical size for the layouts.
559
560
Recommended values are for example:
561
562
- ("left10" "left15"), toggles between methods and directories/history
563
564
- ("left10" "left13"), toggles between methods and directories
565
566
- ("left10" "left14"), toggles between methods and history
567
568
- ("left10" "left13" "left14"), toggles between methods, history and
569
directories
570
571
See also option `ecb-show-sources-in-directories-buffer'.
572
573
This option makes only sense if the value is a list with more than 1
574
element!
575
576
- User Option: windows-height
577
The height of the ECB windows in lines for top-layouts. If the number is
578
less than 1.0 the width is a fraction of the frame height.
579
580
- User Option: windows-width
581
The width of the ECB windows in columns for left- and right layouts. If
582
the number is less than 1.0 the width is a fraction of the frame width.
583
584
585
File: ecb.info, Node: ecb-compilation, Next: ecb-create-layout, Prev: ecb-layout, Up: Customizable options
586
587
Group ecb-compilation
588
---------------------
589
590
This group contains settings for the compile window of ECB:
591
592
- User Option: compilation-buffer-names
593
Additional buffer names that should be displayed in the compile-window.
594
Buffer names can either be defined as strings or as regexps. If the
595
buffer-name of a buffer matches one of the defined string or regexp then
596
it will be displayed in the compile-window of ECB even if
597
`compilation-buffer-p' says nil for this buffer.
598
599
It is not recommended to add the eshell-buffer-names to this list because
600
ECB already handles the eshell-integration as best as possible (*note
601
Using eshell::).
602
603
See also the options `ecb-compilation-major-modes' and
604
`ecb-compilation-predicates'.
605
606
- User Option: compilation-major-modes
607
Additional major-mode that should be displayed in the compile-window. All
608
buffers of a major-mode contained in this list are displayed in the
609
compile-window even if `compilation-buffer-p' says nil for such a buffer.
610
611
It is not recommended to add `eshell-mode' to this list because ECB
612
already handles the eshell-integration as best as possible (*note Using
613
eshell::).
614
615
- User Option: compilation-predicates
616
Predicates when a buffer should be treated as compilation-buffer. Every
617
element of this list has to be a function or lambda-expression which gets
618
as argument a buffer-object and which has to return not nil when this
619
buffer should be treated as compilation-buffer (even if
620
`compilation-buffer-p' says nil) and therefore be displayed in the
621
compile-window of ECB (if there is any).
622
623
In combination with the values of `ecb-compilation-buffer-names' and
624
`ecb-compilation-major-modes' ECB decides when a buffer is displayed in
625
the compile-window.
626
627
Default value is the function `comint-check-proc' which returns not nil
628
when the buffer is related to a living process.
629
630
- User Option: compile-window-height
631
Height of the persistent compilation-window of ECB. If you want a
632
compilation window shown at the bottom of the ECB-layout then set here the
633
height of it (Default is a height of 5). If you redraw the current layout
634
with `ecb-redraw-layout' then the compilation window (if any) has the
635
height you set here. If the number is less than 1.0 the height is a
636
fraction of the frame height.
637
638
If you do not set a persistent compilation window then doing a compilation
639
or displaying temp-buffers (e.g. *Help*-buffers) splits temporally the
640
edit window vertically if the edit window is not splitted already or uses
641
another edit window temporally for compilation output if the edit window
642
is already splitted. This is the recommended value for this option because
643
this is the standard-behavior of Emacs.
644
645
Beware: If you set a persistent compilation window then ECB displays all
646
buffers for which `ecb-compilation-buffer-p' returns not nil in that
647
persistent compilation window. If a buffer which should being displayed
648
there is not displayed there then try to modify the options
649
`ecb-compilation-buffer-names', `ecb-compilation-major-modes' or
650
`ecb-compilation-predicates' (in this sequence).
651
652
See also the options `ecb-compile-window-temporally-enlarge' and
653
`ecb-enlarged-compilation-window-max-height' and also the command
654
`ecb-toggle-compile-window-height'!
655
656
ECB offers the functionality of such a persistent compile-window
657
regardless if the special ECB-windows are visible or not (see the command
658
`ecb-toggle-ecb-windows').
659
660
Regardless of the settings you define here: If you have destroyed or
661
changed the ECB-screen-layout by any action you can always go back to this
662
layout with `ecb-redraw-layout'
663
664
- User Option: compile-window-prevent-shrink-below-height
665
Allow the compile-window to be shrunken below its height. A non nil value
666
means ECB prevents the compile-window from being shrunken below the
667
threshold of `ecb-compile-window-height' by displaying temp-buffers (e.g.
668
*Help* etc.) or after running compilations or greps. But interactively it
669
is always allowed to shrink it to every height!
670
671
If nil then ECB does nothing to prevent being shrunken below the value of
672
`ecb-compile-window-height'.
673
674
Default is t.
675
676
- User Option: compile-window-temporally-enlarge
677
Let Emacs temporally enlarge the compile-window of the ECB-layout. This
678
option has only an effect if `ecb-compile-window-height' is not nil!
679
680
The following values are possible:
681
- `after-display': After displaying a "compilation-buffer" (in the sense
682
of `ecb-compilation-buffer-p'!) in the compile-window of ECB. For the
683
max. height of the enlarged compile-window see the option
684
`ecb-enlarged-compilation-window-max-height'.
685
686
- `after-selection': Selecting the `ecb-compile-window' auto. enlarges it
687
and de-selecting (means leaving `ecb-compile-window') auto. shrinks it.
688
Enlarging and shrinking the `ecb-compile-window' is done with
689
`ecb-toggle-compile-window-height'. See also the documentation of this
690
function!
691
692
- `both': The combination of 'after-display and 'after-selection.
693
694
- `nil': ECB fixes always the height of the `ecb-compile-window' at the
695
value of `ecb-compile-window-height'.
696
697
To restore the ECB-layout after such a buffer-enlarge just call
698
`ecb-toggle-compile-window-height' or `ecb-redraw-layout'.
699
700
- User Option: compile-window-width
701
Width of the compile-window.
702
703
Possible values are `frame' and `edit-window'. With `frame' the
704
compile-window looks like:
705
706
-------------------------------------------------------
707
| | |
708
| Directories | |
709
| | |
710
|--------------| edit-window(s) |
711
| | |
712
| Methods | |
713
| | |
714
-------------------------------------------------------
715
| |
716
| Compilation |
717
| |
718
-------------------------------------------------------
719
720
With `edit-window' the compile-window looks like:
721
722
-------------------------------------------------------
723
| | |
724
| Directories | |
725
| | |
726
|--------------| edit-window(s) |
727
| | |
728
| Methods | |
729
| | |
730
| |---------------------------------------
731
| | |
732
| | Compilation |
733
| | |
734
-------------------------------------------------------
735
736
This option takes only effect if `ecb-compile-window-height' is not nil!
737
738
- User Option: change-layout-preserves-compwin-state
739
Changing the layout preserves the state of the compile-window. This is for
740
example useful if the user toggles between several layouts (see
741
`ecb-toggle-layout') and wants to preserve the hidden-state of the
742
compile-window.
743
744
- User Option: enlarged-compilation-window-max-height
745
The max height of the compile-window after enlarging it. The max height of
746
the compilation window after enlarged by
747
`ecb-toggle-compile-window-height'. The following values are allowed:
748
749
`best':
750
751
ECB fits the height of the compile-window exactly to the size of its
752
current contents but never shrinks below the value of
753
`ecb-compile-window-height' or enlarges over the half of the frame-height
754
of the ECB-frame. The values of the options `compilation-window-height'
755
and `temp-buffer-max-height' are taken into account dependent of the
756
current `major-mode' of the buffer in the compile-window: If
757
`compilation-mode' then `compilation-window-height' is used otherwise
758
`temp-buffer-max-height'.
759
760
`half':
761
762
1/2 the frame-height of the ECB-frame
763
764
Any number:
765
766
Max height in lines. If the number is less than 1.0 the height is a
767
fraction of the frame height (e.g. 0.33 results in a max-height of 1/3 the
768
frame-height).
769
770
- User Option: scroll-other-window-scrolls-compile-window
771
`scroll-other-window' scrolls always the compile-window. For all details
772
about the scroll-behavior of `scroll-other-window' see the advice
773
documentation of `other-window-for-scrolling'.
774
775
776
File: ecb.info, Node: ecb-create-layout, Next: ecb-face-options, Prev: ecb-compilation, Up: Customizable options
777
778
Group ecb-create-layout
209
779
-----------------------
210
780
211
Every support must be enabled explicitly:
212
* winring: Call `ecb-winman-winring-enable-support'. This *MUST* be done
213
*BEFORE* the first call to any winring-command, so also before calling
214
`winring-initialize'!
215
216
* escreen: Call `ecb-winman-escreen-enable-support'. This *MUST* be done
217
*BEFORE* the first call to any escreen-command, so also before calling
218
`escreen-install'!
219
220
If a window-manager-support should be enabled autom. after Emacs-start just
221
put the following into your `.emacs':
222
223
(ecb-winman-winring-enable-support)
224
(winring-initialize)
225
226
;; or - if you like escreen more
227
228
(ecb-winman-escreen-enable-support)
229
(escreen-install)
230
231
Usage of a window-manager in combination with ECB
232
-------------------------------------------------
233
234
After enabling the support of one of the supported window-managers just go on
235
as described in the commentary or introduction of the respective
236
library-file(s) of the window-manager. Here is a short description:
237
238
* winring: First you have to define how to identify the
239
ECB-window-configuration, i.e. the configuration with activated ECB. This
240
done with the option `ecb-winman-winring-name'. There is always only one
241
window-configurations with name `ecb-winman-winring-name'!
242
243
Then run `winring-initialize'. If ECB is active then the resulting
244
window-configuration is the ECB-window-configuration. Otherwise you can
245
create the ECB-window-configuration when you first time call
246
`winring-new-configuration' with name equal to `ecb-winman-winring-name'.
247
In general you can run all commands of the winring-library. If you jump to
248
the ECB-window-configuration then ECB will be autom. activated and if you
249
leave the ECB-window-configuration then ECB will autom. deactivated.
250
251
* escreen: First you have to define how to identify the ECB-escreen i.e.
252
that escreen with activated ECB. This done with the option
253
`ecb-winman-escreen-number'. There is always only one escreen with number
254
`ecb-winman-escreen-number'!
255
256
Then run `escreen-install' (deactivates ECB if currently running). After
257
that you can call `escreen-create-screen' and `escreen-goto-screen'(1).
258
These commands autom. activate ECB if creating or selecting the escreen
259
with number `ecb-escreen-number' (default = 1) and autom. deactivate ECB if
260
leaving the ECB-escreen.
261
262
Disabling the support
263
---------------------
264
265
There is normally no need to do this but nevertheless it can be done by
266
`ecb-winman-escreen-disable-support' rsp.
267
`ecb-winman-winring-disable-support'.
268
269
---------- Footnotes ----------
270
271
(1) And of course all other `escreen-goto-*' commands!
272
273
274
File: ecb.info, Node: Tree-buffer styles, Next: Using semanticdb, Prev: Window-managers and ECB, Up: Tips and tricks
275
276
Displaying the trees of the ECB-windows with different styles
277
=============================================================
278
279
ECB offers three different styles for the tree-buffers in the ECB-windows.
280
Two of the styles are ascii-based and one style uses images for drawing the
281
tree-structure.
282
283
* Menu:
284
285
* Style basics:: Basic knowledge about the styles
286
* Ascii-based styles:: How to customize the ascii-styles
287
* Tree-buffers with images:: Which images are used for the tree
288
* Images for Methods-buffer:: Images for the tags in the Methods-buffer
289
290
291
File: ecb.info, Node: Style basics, Next: Ascii-based styles, Up: Tree-buffer styles
292
293
Basic knowledge about the styles
294
--------------------------------
295
296
There are nine image-names which define the control- and guide-symbols to
297
draw the tree. Here is the list of the allowed image-names and the related
298
corresponding ascii-symbols:
299
300
- open ("[-]"): The control-symbol displayed for an opened tree-node which
301
has several subnodes. Clicking onto this control closes the node.
302
303
- close ("[+]"): The control-symbol displayed for a closed tree-node, i.e. an
304
expandable node with subnodes but all subnodes are hidden. Clicking onto
305
this control opened the node and displays its subnodes - if there are any.
306
If it has no subnodes the empty-symbol will be displayed.
307
308
- empty ("[x]"): The symbol displayed for an empty node. An empty node is a
309
node which could have subnodes but has currently none.
310
311
- leaf ("*"): The symbol displayed for a node which can not have any
312
subnodes so it is a "leaf" in the tree.
313
314
- guide (" |"): The symbol used for drawing vertical "guide-lines" for
315
opened nodes. See the example below.
316
317
- no-guide (" "): Sometimes invisible guide-lines are needed to draw the
318
tree.
319
320
- end-guide (" `"): The symbol used for the guide-line of the last subnode
321
of an opened node.
322
323
- handle ("-"): The symbol displayed before every subnode. Each handle is
324
connected to a guide-line - either a normal guide or an end-guide.
325
326
- no-handle (" "): An invisible handle.
327
328
A tree will be build-up with these elements like follows:
329
330
[-] node-with-subnodes (open)
331
|-[+] not-empty-subnode1 (guide+handle+close)
332
|-[x] empty-subnode (guide+handle+empty)
333
`-[-] not-empty-subnode2 (end-guide+handle+open)
334
|-* leaf-1 (no-guide+no-handle+guide+handle+leaf)
335
`-* leaf-2 (no-guide+no-handle+end-guide+handle+leaf)
336
337
338
File: ecb.info, Node: Ascii-based styles, Next: Tree-buffers with images, Prev: Style basics, Up: Tree-buffer styles
339
340
How to customize the ascii-styles
341
---------------------------------
342
343
The ECB-option `ecb-tree-buffer-style' offers two different styles completely
344
drawn with ascii-controls and -guides.
345
346
Ascii-style with guide-lines (value `ascii-guides')(1):
347
348
[-] ECB
349
| [+] code-save
350
`- [-] ecb-images
351
| [-] directories
352
| | [-] height-15
353
| | | * close.xpm
354
| | | * empty.xpm
355
| | | * leaf.xpm
356
| | `- * open.xpm
357
| | [+] height-17
358
| | [+] height-19
359
| `- [+] height-21
360
| [x] history
361
| [x] methods
362
`- [x] sources
363
364
Ascii-style without guide-lines (value `ascii-no-guides') - this is the style
365
used by ECB <= 1.96:
366
367
[-] ECB
368
[+] code-save
369
[-] ecb-images
370
[-] directories
371
[-] height-15
372
* close.xpm
373
* empty.xpm
374
* leaf.xpm
375
* open.xpm
376
[+] height-17
377
[+] height-19
378
[+] height-21
379
[x] history
380
[x] methods
381
[x] sources
382
383
The tree-layout of both ascii-styles can be affected with the options
384
`ecb-tree-indent' and `ecb-tree-expand-symbol-before' (the examples above
385
have set 4 for the former and true for the latter one). For the guide-style
386
the face and color of the guide- and handle-symbols can be customized with
387
the option `ecb-tree-guide-line-face' (default is the equal-named face).
388
389
---------- Footnotes ----------
390
391
(1) For a better look&feel of such a tree-buffer ECB displays only the last
392
subnode of an opened node with a handle!
393
394
395
File: ecb.info, Node: Tree-buffers with images, Next: Images for Methods-buffer, Prev: Ascii-based styles, Up: Tree-buffer styles
396
397
Which images are used for the tree
398
----------------------------------
399
400
Depending on the value of `ecb-tree-buffer-style' and the image-support of
401
(X)Emacs, the tree-buffer try to use images instead of strings to draw a
402
nice-looking tree.
403
404
If images can and should be used then the option
405
`ecb-tree-image-icons-directories' tells ECB where to search for suitable
406
image-icons for each of the nine image-names (see above). An image is used
407
for displaying a control with name "XXX" if one of the directories of
408
`ecb-tree-image-icons-directories' contains an image-file with basename
409
"ecb-XXX" and an extension which is supported by (X)Emacs. Currently
410
supported extensions are ".xpm", ".png", ".gif", ".jpeg", ."jpg" and ".xbm".
411
412
Example: To display the control with name "open" with a suitable image then
413
one of the directories of `ecb-tree-image-icons-directories' must contain a
414
file with name "ecb-open.xpm" or "ecb-open.png" etc. See the description of
415
this option to get all important details how and in which sequence ECB
416
searches the directories of `ecb-tree-image-icons-directories'.
417
418
ECB comes with predefined default-images usable for every tree-buffer and
419
special images for the Directories- and the Methods-tree-buffer. They are
420
defined in several different heights - so for the most senseful font-heights
421
of a tree-buffer a fitting image-size should be available. The shipped images
422
reside either in the subdirectory "ecb-images" of the ECB-installation or -
423
if ECB is installed as regular XEmacs-package - in the ECB-etc data-directory
424
(the directory returned by evaluating (locate-data-directory "ecb"). If you
425
do not want to change the images then you normally have nothing to do because
426
the default value of `ecb-tree-image-icons-directories' points already to the
427
correct image-directories.
428
429
A special note for XEmacs
430
.........................
431
432
At least XEmacs 21.14 (but probably previous versions too) has a bug in its
433
display-engine which prevents adjacent images to be displayed correctly. The
434
effect is, that in a row of two or more adjacent images (e.g.
435
end-guide+handle+open - see the tree-example above) always all images are
436
masked by the last one, means only the last one is visible. If at least one
437
normal character (e.g. a space) is placed between two images then the images
438
are displayed correctly. Therefore ECB has implemented the following
439
work-around to get best possible results with XEmacs: open-, close-, empty-,
440
leaf-, guide-, end-guide- and no-guide-images are displayed with images and
441
the handle- and the no-handle-images are displayed with the corresponding
442
ascii-symbols (which is "-" rsp. " "). The face (the color) of the
443
handle-symbol is customizable via the option `ecb-tree-guide-line-face'.
444
445
This bug is already reported to the XEmacs-team. If your XEmacs has fixed
446
this bug then add the following to your `.emacs'-file (or whereever your
447
emacs-setup is located):
448
449
(setq tree-buffer-enable-xemacs-image-bug-hack nil)
450
451
Then ECB uses images without any special work-around with XEmacs too. Just
452
try it - if the tree-buffers look ugly then the XEmacs-bug is probably not
453
fixed correctly.
454
455
456
File: ecb.info, Node: Images for Methods-buffer, Prev: Tree-buffers with images, Up: Tree-buffer styles
457
458
Special images for the Methods-buffer
459
-------------------------------------
460
461
ECB can display all the semantic-tags in the Method-buffer with special icons
462
for methods, variables and classes - each of them with a different icon
463
dependend of the protection of the tag. This feature can be disabled/enabled
464
via the option `ecb-display-image-icons-for-semantic-tags'. All the special
465
images are located in that directory where the option
466
`ecb-tree-image-icons-directories' point to for methods.
467
468
469
File: ecb.info, Node: Using semanticdb, Prev: Tree-buffer styles, Up: Tips and tricks
470
471
Using semanticdb to jump to type-tags defined in other files
472
============================================================
473
474
In OO-languages like CLOS, eieio and C++ there can be type-tags in the
475
method-buffer which are somehow virtual because there is no definition in the
476
current source-file. But such a virtual type collects all its outside defined
477
members like methods in C++ which are defined in the `*.cc' file whereas the
478
class-definition is defined in the associated header-file. ECB uses
479
semanticdb to open the definition-file of such a tag and to jump to the
480
definition of this tag. Same for parent-tags in the methods-buffer. This
481
feature can only work correctly if semanticdb is well configured!
482
483
Here is a C++-example:
484
485
This class is defined in a file `ParentClass.h':
486
487
class ParentClass
488
{
489
protected:
490
int p;
491
};
492
493
This class is defined in a file `ClassWithExternals.h'
494
495
#include "ParentClass.h"
496
497
class ClassWithExternals : public ParentClass
498
{
499
private:
500
int i;
501
502
public:
503
ClassWithExternals();
504
~ClassWithExternals();
505
};
506
507
Both the constructor and the desctructor of the class "ClassWithExternals"
508
are defined in a file `ClassWithExternals.cc':
509
510
#include "test.h"
511
512
ClassWithExternals::ClassWithExternals(int i,
513
boolean b,
514
char c)
515
{
516
return;
517
}
518
519
void
520
ClassWithExternals::~ClassWithExternals()
521
{
522
return;
523
}
524
525
ECB displays the contents of `ClassWithExternals.cc' in its methods-buffer
526
like follows:
527
528
[-] [Includes]
529
`- test.h
530
[-] ClassWithExternals
531
| +ClassWithExternals (+i:int, +b:class boolean, +c:char):ClassWithExternals
532
`- +~ClassWithExternals ():void
533
534
Both the constructor and the desctructor of the class "ClassWithExternals"
535
are grouped under their class-type. ECB now uses semanticdb to jump to the
536
definition of class "ClassWithExternals" when you click onto the type-node
537
"ClassWithExternals" in the methods-buffer.
538
539
The contents of `ClassWithExternals.h' are displayed like follows:
540
541
[-] [Includes]
542
`- ParentClass.h
543
[-] ClassWithExternals:class
544
| [-] [Parents]
545
| `- ParentClass
546
| [-] [Variables]
547
| `- -i:int
548
| +ClassWithExternals ():ClassWithExternals
549
| +~ClassWithExternals ():void
550
`- [+] [Misc]
551
552
ECB uses semanticdb to jump to the definition of the class "ParentClass" when
553
you click onto the node "ParentClass".
554
555
To enable this feature `global-semanticdb-minor-mode' must be enabled and
556
semanticdb must be correctly configured. This means mainly that the option
557
`semanticdb-project-roots' must be setup well. See the manual of semanticdb
558
for further informations about this.
559
560
561
File: ecb.info, Node: Elisp programming, Next: Conflicts and bugs, Prev: Tips and tricks, Up: Top
562
563
Entry points for Elisp programmers
564
**********************************
565
566
This chapter describes how ECB can be used/programmed/driven by an
567
Elisp-program. This contains:
568
569
* Menu:
570
571
* List of variables:: Which variables an Elisp-program can use
572
* List of hooks:: All available hooks
573
* tree-buffer:: Some words to the tree-buffer-library
574
* Adviced functions:: How to deal with the adviced functions
575
* The layout-engine:: Programming new layouts and special windows
576
577
578
File: ecb.info, Node: List of variables, Next: List of hooks, Prev: Elisp programming, Up: Elisp programming
579
580
Variables for Elisp-programs
581
============================
582
583
Variables an Elisp-program can use beyond those ones mentioned in *Note The
584
layout-engine:::
585
586
* `ecb-source-path-functions'
587
588
Look at the documentation of these variables to get a description.
589
590
591
File: ecb.info, Node: List of hooks, Next: tree-buffer, Prev: List of variables, Up: Elisp programming
592
593
Available hooks of ECB
594
======================
595
596
The following hooks are available:
597
598
* `ecb-activate-before-new-frame-created-hook'
599
600
* `ecb-activate-before-layout-draw-hook'
601
602
* `ecb-activate-hook'
603
604
* `ecb-before-activate-hook'
605
606
* `ecb-before-deactivate-hook'
607
608
* `ecb-common-tree-buffer-after-create-hook'
609
610
* `ecb-current-buffer-sync-hook'
611
612
* `ecb-deactivate-hook'
613
614
* `ecb-directories-buffer-after-create-hook'
615
616
* `ecb-hide-ecb-windows-after-hook'
617
618
* `ecb-hide-ecb-windows-before-hook'
619
620
* `ecb-history-buffer-after-create-hook'
621
622
* `ecb-methods-buffer-after-create-hook'
623
624
* `ecb-redraw-layout-after-hook'
625
626
* `ecb-redraw-layout-before-hook'
627
628
* `ecb-show-ecb-windows-after-hook'
629
630
* `ecb-show-ecb-windows-before-hook'
631
632
* `ecb-sources-buffer-after-create-hook'
633
634
Look at the documentation of these hooks to get a detailed description.
635
636
637
File: ecb.info, Node: tree-buffer, Next: Adviced functions, Prev: List of hooks, Up: Elisp programming
638
639
The library tree-buffer.el
640
==========================
641
642
The library tree-buffer.el is ECB independent and can be used for other
643
applications too. But such an application is not allowed to use any of the
644
variables of tree-buffer.el especially not the variable *tree-buffers*!
645
646
`tree-buffers': Only for internal use. It contains all tree-buffers of
647
current Emacs-instance, means *all* tree-buffers of *all* applications which
648
uses currently tree-buffers. Every application must store its own collection
649
of tree-buffers in an own variable! For example: ECB stores its tree-buffer
650
set in `ecb-tree-buffers'!
651
652
An application may only use the methods tree-buffer.el provides but no
653
internal variables!
654
655
656
File: ecb.info, Node: Adviced functions, Next: The layout-engine, Prev: tree-buffer, Up: Elisp programming
657
658
How to deal with the adviced window-functions
659
=============================================
660
661
ECB offers for packages which work during activated ECB three macros for easy
662
temporally(1) using all original-functions, all adviced functions or only
663
some adviced functions:
664
665
- `ecb-with-original-functions'
666
667
- `ecb-with-adviced-functions'
668
669
- `ecb-with-some-adviced-functions'
670
671
For a detailed explanation of each macro read the documentation with
672
`describe-function'!
673
674
---------- Footnotes ----------
675
676
(1) I.e. regardless of the settings in `ecb-advice-window-functions'!
677
678
679
File: ecb.info, Node: The layout-engine, Prev: Adviced functions, Up: Elisp programming
680
681
How to program new layouts and new special windows
682
==================================================
683
684
There are two aspects concerning this topic:
685
686
1. Programming a new layout which contains several special ECB-windows like
687
directories, sources, methods, history or other special windows and
688
arranging them in a new outline.
689
690
2. Creating complete new special windows (e.g. a local-variable window for a
691
graphical debugger like JDEbug of JDEE), adding them to a layout and
692
synchronizing them with the current active edit-window.
693
694
The former one covers merely the layout-programming aspect which is explained
695
in the first subsection of this chapter whereas the latter one covers all
696
aspects of creating new special windows and what is necessary to synchronize
697
it with the current active edit-window of ECB. This is explained in the
698
second subsection which will refers to the first subsection.
699
700
* Menu:
701
702
* Programming a new layout:: How to program a new layout
703
* Programming special windows:: Aspects of programming special windows
704
* Possible layout-outlines:: The wide range of possible layouts
705
* The layout-engine API:: The complete layout-engine API
706
707
708
File: ecb.info, Node: Programming a new layout, Next: Programming special windows, Prev: The layout-engine, Up: The layout-engine
709
710
How to program a new layout
711
---------------------------
712
713
If you just want creating a new layout with the standard ECB-windows like
714
directories, sources, methods, history and speedbar it's is strongly
715
recommended to define the new layout interactively with the command
716
`ecb-create-new-layout' (*note Creating a new ECB-layout::).
717
718
If you want creating a new layout and if this layout should contain other
719
special windows than the standard ECB-windows then it's still recommended to
720
define this layout interactively with `ecb-create-new-layout' and using the
721
option to give the created windows user-defined types. For every user defined
722
type you have then just to program the necessary buffer-set function. For all
723
the details see *Note Creating a new ECB-layout::.
724
725
But if you do not like the interactive way (because you are tough and brave)
726
but you want programming the new layout with Elisp then use the macro
727
`ecb-layout-define' (the following definition has stripped the prefix "ecb-"
728
for better indexing this manual):
729
730
- Macro: layout-define name type &rest create-code
731
Creates a new ECB-layout with name NAME. TYPE is the type of the new
732
layout and is literal, i.e. not evaluated. It can be left, right, top or
733
left-right. DOC is the docstring for the new layout-function
734
"ecb-layout-function-<name>". CREATE-CODE is all the lisp code which is
735
necessary to define the ECB-windows/buffers. This macro adds the layout
736
with NAME and TYPEto the internal variable `ecb-available-layouts'.
737
738
Preconditions for CREATE-CODE:
739
1. Current frame is splitted at least in one edit-window and the "column"
740
(for layout types left, right and left-right) rsp. "row" (for a top
741
layout) for the special ECB-windows/buffers. The width of the "column"
742
rsp. the height of the "row" is always defined with the option
743
`ecb-windows-width' rsp. `ecb-windows-height'. Depending on the value
744
of the option `ecb-compile-window-height' there is also a compile
745
window at the bottom of the frame which is stored in
746
`ecb-compile-window'.
747
748
2. All windows are not dedicated.
749
750
3. Neither the edit-window nor the compile-window (if there is one) are
751
selected for types left, right and top. For type left-right the left
752
column-window is selected
753
754
4. All ECB-advices for the functions in `ecb-advice-window-functions' are
755
disabled!
756
757
Things CREATE-CODE has to do:
758
1. Splitting the ECB-tree-windows-column(s)/row (s.a.) in all the
759
ECB-windows the layout should contain (directories, sources, methods
760
and history). The split must not be done with other functions than
761
`ecb-split-hor' and `ecb-split-ver'! It is recommended not to to use a
762
"hard" number of split-lines or -rows but using fractions between -0.9
763
and +0.9! Tip: It is recommended to spilt from right to left and from
764
bottom to top or with other words: First create the right-most and
765
bottom-most special windows!
766
767
2. Making each special ECB-window a dedicated window. This can be done with
768
one of the following functions:
769
- `ecb-set-directories-buffer'
770
771
- `ecb-set-sources-buffer'
772
773
- `ecb-set-methods-buffer'
774
775
- `ecb-set-history-buffer'
776
777
- `ecb-set-speedbar-buffer'
778
Each layout can only contain one of each tree-buffer-type!
779
780
In addition to these functions there is a general macro
781
`ecb-with-dedicated-window'. This macro performs any arbitrary code in
782
current window and makes the window autom. dedicated at the end. This
783
can be used by third party packages like JDEE to create arbitrary
784
ECB-windows besides the standard tree-windows.
785
786
To make a special ECB-window a dedicated window either one of the five
787
functions above must be used or a function(!) which calls in turn the
788
macro `ecb-with-dedicated-window'. See the documentation of this macro
789
how to use it!
790
791
Such a function is called a "dedicated setter" and must(!) use
792
`ecb-with-dedicated-window' to make the window dedicated!
793
794
3. Every(!) special ECB-window must be dedicated as described in 2.
795
796
4. CREATE-CODE must work correctly regardless if there is already a
797
compile-window (stored in `ecb-compile-window') or not
798
(`ecb-compile-window' is nil).
799
800
Things CREATE-CODE can do or can use:
801
1. The value of `ecb-compile-window' which contains the compile-window (if
802
there is one). Using the values of `ecb-compile-window-height',
803
`ecb-windows-width', `ecb-windows-height'.
804
805
Things CREATE-CODE must NOT do:
806
1. Splitting the edit-window
807
808
2. Creating a compile-window
809
810
3. Deleting the edit-window, the compile-window (if there is any) or the
811
ECB-windows-column(s)/row (see Precondition 1.)
812
813
4. Referring to the value of `ecb-edit-window' because this is always nil
814
during CREATE-CODE.
815
816
Postconditions for CREATE-CODE:
817
1. The edit-window must be the selected window and must not be dedicated
818
and not be splitted.
819
820
2. Every window besides the edit-window \(and the compile-window) must be
821
a dedicated window \(e.g. a ECB-tree-window).
822
823
Use this macro to program new layouts within your `.emacs' or any other file
824
which is loaded into your Emacs. After loading the file(s) with all the new
825
layout-definitions you can use it by customizing the option `ecb-layout-name'
826
to the appropriate name or with the command `ecb-change-layout'.
827
828
With the function `ecb-layout-undefine' you can remove a layout from the list
829
of available layouts:
830
831
- Function: layout-undefine name
832
Unbind ecb-layout-function-<NAME> and ecb-delete-window-ecb-windows-<NAME>
833
and remove `NAME' from `ecb-available-layouts'.
834
835
Here is an example for a new layout programmed with `ecb-layout-define':
836
837
(ecb-layout-define "my-own-layout" left nil
838
;; The frame is already splitted side-by-side and point stays in the
839
;; left window (= the ECB-tree-window-column)
840
841
;; Here is the creation code for the new layout
842
843
;; 1. Defining the current window/buffer as ECB-methods buffer
844
(ecb-set-methods-buffer)
845
;; 2. Splitting the ECB-tree-windows-column in two windows
846
(ecb-split-ver 0.75 t)
847
;; 3. Go to the second window
848
(other-window 1)
849
;; 4. Defining the current window/buffer as ECB-history buffer
850
(ecb-set-history-buffer)
851
;; 5. Make the ECB-edit-window current (see Postcondition above)
852
(select-window (next-window)))
853
854
This layout definition defines a layout with name "my-own-layout" which looks
855
like:
856
857
-------------------------------------------------------
858
| | |
859
| | |
860
| | |
861
| Methods | |
862
| | |
863
| | |
864
| | Edit |
865
| | |
866
| | |
867
|--------------| |
868
| | |
869
| History | |
870
| | |
871
-------------------------------------------------------
872
| |
873
| Compilation |
874
| |
875
-------------------------------------------------------
876
877
878
File: ecb.info, Node: Programming special windows, Next: Possible layout-outlines, Prev: Programming a new layout, Up: The layout-engine
879
880
All aspects of programming special windows
881
------------------------------------------
882
883
ECB offers a flexible programmable layout-engine for other packages to
884
display their own contents and informations in special ECB-windows. An
885
example could be a graphical debugger which offers a special window for
886
displaying local variables and another special window for messages from the
887
debugger-process (like JDEbug of JDEE(1)).
888
889
This section explains all aspects of programming new special windows, adding
890
them to a new layout and synchronizing them with edit-window of ECB. This can
891
be done best with an easy example which nevertheless covers all necessary
892
aspects to be a good example and skeleton for complex tools (like a graphical
893
debugger) which want to use the layout-engine of ECB do display their own
894
information.
895
896
Here comes the example:
897
898
The outline of the example layout:
899
..................................
900
901
-------------------------------------------------------
902
|Bufferinfo for <filename>: |[prior] |
903
|Type: file |[next] |
904
|Size: 23456 | |
905
|Modes: rw-rw-rw- | |
906
|-----------------------------------------------------|
907
| |
908
| |
909
| |
910
| |
911
| edit-window |
912
| |
913
| |
914
| |
915
| |
916
-------------------------------------------------------
917
| |
918
| compilation-window |
919
| |
920
-------------------------------------------------------
921
922
The description of the layout-contents
923
......................................
924
925
The top-left window always displays informations about the current buffer in
926
the selected edit-window. This window demonstrates how autom. synchronizing a
927
special window/buffer of a layout with current edit-window.
928
929
The top-right window contains an read-only "action-buffer" and offers two
930
buttons which can be used with the middle mouse-button to scroll the
931
edit-window. This is not very senseful but it demonstrates how to control the
932
edit-window with actions performed in a special window/buffer of a layout.
933
934
(If you have not set a compilation-window in `ecb-compile-window-height' then
935
the layout contains no durable compilation window and the other windows get a
936
little more place).
937
938
The example code
939
................
940
941
Now let have us a look at the several parts of the Elisp-program needed to
942
program this new example layout. ECB contains a library `ecb-examples.el'
943
which contains the full working code of this example. To test this example
944
and to play with it you can load this library into Emacs (with `load-library'
945
for example) and then calling `ecb-change-layout' (bound to `C-c . lc') and
946
inserting "example-layout1" as layout-name. An alternative is calling
947
`ecb-examples-activate' and `ecb-examples-deactivate'. For details see file
948
`ecb-examples.el'.
949
950
The following steps only contain code-skeletons to demonstrate the principle.
951
The full working code is available in `ecb-examples.el'.
952
953
The bufferinfo buffer of the example
954
....................................
955
956
The name of the bufferinfo buffer:
957
958
(defconst ecb-examples-bufferinfo-buffer-name " *ECB buffer info*")
959
960
Two helper functions for displaying infos in a special buffer:
961
962
(defun ecb-examples-print-file-attributes (buffer filename)
963
(ecb-with-readonly-buffer buffer
964
(erase-buffer)
965
(insert (format "Bufferinfo for %s:\n\n" filename))
966
;; insert with the function `file-attributes' some
967
;; informations about FILENAME.
968
))
969
970
(defun ecb-examples-print-non-filebuffer (buffer buffer-name)
971
(ecb-with-readonly-buffer buffer
972
(erase-buffer)
973
;; analogous to `ecb-examples-print-file-attributes'
974
))
975
976
The main synchronizing function added to `ecb-current-buffer-sync-hook' for
977
autom. evaluation by `ecb-current-buffer-sync' which runs dependent on the
978
values of `ecb-window-sync' and `ecb-window-sync-delay'. This function
979
synchronizes the bufferinfo buffer with the current buffer of the edit-window
980
if that buffer has changed.
981
982
(defun ecb-examples-bufferinfo-sync ()
983
(ecb-do-if-buffer-visible-in-ecb-frame
984
'ecb-examples-bufferinfo-buffer-name
985
986
;; here we can be sure that the buffer with name
987
;; `ecb-examples-bufferinfo-buffer-name' is displayed in a
988
;; window of `ecb-frame'
989
990
;; The macro `ecb-do-if-buffer-visible-in-ecb-frame' locally
991
;; binds the variables visible-buffer and visible-window!! See
992
;; documentation of this macro!
993
994
(let ((filename (buffer-file-name (current-buffer))))
995
996
(if (and filename (file-readable-p filename))
997
998
;; real filebuffers
999
;; here we could add a smarter mechanism;
1000
;; see ecb-examples.el
1001
(ecb-examples-print-file-attributes visible-buffer
1002
filename)
1003
1004
;; non file buffers like help-buffers etc...
1005
(setq ecb-examples-bufferinfo-last-file nil)
1006
(ecb-examples-print-non-filebuffer visible-buffer
1007
(buffer-name
1008
(current-buffer)))
1009
))))
1010
1011
The function which makes the bufferinfo-buffer dedicated to a window.
1012
1013
(defun ecb-examples-set-bufferinfo-buffer ()
1014
(ecb-with-dedicated-window
1015
ecb-examples-bufferinfo-buffer-name
1016
'ecb-examples-set-bufferinfo-buffer
1017
(switch-to-buffer (get-buffer-create
1018
ecb-examples-bufferinfo-buffer-name))
1019
(setq buffer-read-only t)))
1020
1021
This is all what we need for the special bufferinfo buffer. We have
1022
demonstrated already three of the important functions/macros of the
1023
layout-engine API of ECB: `ecb-with-readonly-buffer',
1024
`ecb-do-if-buffer-visible-in-ecb-frame' and `ecb-with-dedicated-window'
1025
(*note The layout-engine API::. Especially the second macro is strongly
1026
recommended for programming good synchronizing functions which do not waste
1027
CPU!
1028
1029
The action buffer of the example
1030
................................
1031
1032
The name of the action-buffer:
1033
1034
(defconst ecb-examples-action-buffer-name " *ECB action buffer*")
1035
1036
Two helper functions for creating a readonly action-buffer with a special
1037
local key-map for the middle-mouse-button and two buttons [prior] and [next]:
1038
1039
(defun ecb-examples-insert-text-in-action-buffer (text)
1040
(let ((p (point)))
1041
(insert text)
1042
(put-text-property p (+ p (length text)) 'mouse-face
1043
'highlight)))
1044
1045
(defun ecb-examples-action-buffer-create ()
1046
(save-excursion
1047
(if (get-buffer ecb-examples-action-buffer-name)
1048
(get-buffer ecb-examples-action-buffer-name)
1049
1050
(set-buffer (get-buffer-create
1051
ecb-examples-action-buffer-name))
1052
1053
;; we setup a local key-map and bind middle-mouse-button
1054
;; see ecb-examples.el for the full code
1055
1056
;; insert the action buttons [prior] and [next] and
1057
;; make it read-only
1058
1059
(ecb-with-readonly-buffer (current-buffer)
1060
(erase-buffer)
1061
(ecb-examples-insert-text-in-action-buffer "[prior]")
1062
;; analogous for the [next] button
1063
)
1064
1065
(current-buffer))))
1066
1067
The function which performs the actions in the action-buffer if clicked with
1068
the middle-mouse button onto a button [next] or [prior].
1069
1070
(defun ecb-examples-action-buffer-clicked (e)
1071
(interactive "e")
1072
(mouse-set-point e)
1073
(let ((line (buffer-substring (ecb-line-beginning-pos)
1074
(ecb-line-end-pos))))
1075
(cond ((string-match "prior" line)
1076
(ecb-select-edit-window)
1077
(call-interactively 'scroll-down))
1078
((string-match "next" line)
1079
;; analogous for [next]
1080
))))
1081
1082
The function which makes the action-buffer dedicated to a window.
1083
1084
(defun ecb-examples-set-action-buffer ()
1085
(let ((buf-name (buffer-name (ecb-examples-action-buffer-create))))
1086
(ecb-with-dedicated-window buf-name 'ecb-examples-set-action-buffer
1087
(switch-to-buffer (buffer-name
1088
(ecb-examples-action-buffer-create))))))
1089
1090
We do not need more code for the action buffer. All of the code is standard
1091
emacs-lisp which would also needed if used without ECB.
1092
1093
Adding the bufferinfo- and action-buffer to a new layout
1094
........................................................
1095
1096
Now we add the bufferinfo- and the action-buffer to a new layout of type top
1097
with name "example-layout1":
1098
1099
(ecb-layout-define "example-layout1" top
1100
1101
;; dedicating the bufferinfo window to the bufferinfo-buffer
1102
(ecb-examples-set-bufferinfo-buffer)
1103
1104
;; creating the action-window
1105
(ecb-split-hor 0.75)
1106
1107
;; dedicate the action window to the action-buffer
1108
(ecb-examples-set-action-buffer)
1109
1110
;; select the edit-window
1111
(select-window (next-window)))
1112
1113
This all what we need to define the new layout. See *Note Programming a new
1114
layout:: for more details of the pure layout-programming task.
1115
1116
Synchronizing the bufferinfo-buffer automatically
1117
.................................................
1118
1119
The last thing we have to do is to synchronize the bufferinfo-buffer with
1120
current edit-window. We do this by adding `ecb-examples-bufferinfo-sync' to
1121
the hook `ecb-current-buffer-sync-hook'' (The file `ecb-examples.el' shows a
1122
smarter mechanism for (de)activating the new layout and the synchronization
1123
but this works also very well).
1124
1125
(add-hook 'ecb-current-buffer-sync-hook 'ecb-examples-bufferinfo-sync)
1126
1127
Activating and deactivating new layouts
1128
.......................................
1129
1130
Because a set of new special windows integrated in a new layout is often just
1131
the GUI of a complete tool (like a graphical debugger) we demonstrate here
1132
the complete activation and deactivation of such a tool or at least of the
1133
tool-GUI. We decide that the GUI of our example "tool" needs a compile-window
1134
with height 5 lines and the height of the special windows "row" on top should
1135
be exactly 6 lines (normally width and height of the special windows should
1136
be a fraction of the frame, but here we use 6 lines(2)
1137
1138
Here comes the (de)activation code.
1139
1140
The code for saving and restoring the state before activation (the full code
1141
is available in `ecb-examples.el':
1142
1143
(defun ecb-examples-preactivation-state(action)
1144
(cond ((equal action 'save)
1145
;; code for saving the state
1146
)
1147
((equal action 'restore)
1148
;; code for restoring the state
1149
)))
1150
1151
The following function activates the GUI of our example tool:
1152
1153
(defun ecb-examples-activate ()
1154
(interactive)
1155
1156
;; activating the synchronization of the bufferinfo-window
1157
(add-hook 'ecb-current-buffer-sync-hook
1158
'ecb-examples-bufferinfo-sync)
1159
1160
;; saving the state
1161
(ecb-examples-preactivation-state 'save)
1162
1163
;; switch to our preferred layout
1164
(setq ecb-windows-height 6)
1165
(setq ecb-compile-window-height 5)
1166
(ecb-layout-switch "example-layout1"))
1167
1168
This function deactivates the GUI of our example-tool and restores the state
1169
as before activation:
1170
1171
(defun ecb-examples-deactivate ()
1172
(interactive)
1173
1174
(remove-hook 'ecb-current-buffer-sync-hook
1175
'ecb-examples-bufferinfo-sync)
1176
(ecb-examples-preactivation-state 'restore)
1177
(ecb-layout-switch ecb-layout-name))
1178
1179
Now we have all code for the new layout and the new layout-buffers. The
1180
example is ready for use; just load `ecb-examples.el' (s.a.).
1181
1182
---------- Footnotes ----------
1183
1184
(1) JDEE is available at <http://jdee.sunsite.dk/>
1185
1186
(2) You can change the code in the file `ecb-examples.el' to use a
1187
frame-fraction of 0.2 instead of 6 hard lines, just try it!
781
This group contains settings for creating new ECB-layouts:
782
783
- User Option: create-layout-file
784
File where all layouts created by `ecb-create-new-layout' are stored.
785
786
- User Option: ecb-create-layout-frame-height
787
Frame height of the layout creation frame.
788
789
- User Option: ecb-create-layout-frame-width
790
Frame width of the layout creation frame.
791
792
793
File: ecb.info, Node: ecb-face-options, Next: ecb-faces, Prev: ecb-create-layout, Up: Customizable options
794
795
Group ecb-face-options
796
----------------------
797
798
This group contains settings for all faces used in ECB:
799
800
- User Option: directories-general-face
801
Basic face for the ECB directories buffer. This defines the basic face the
802
whole directory buffer should displayed with. If the face
803
`ecb-default-general-face' is used then the display of all
804
ECB-tree-buffers can be changed by modifying only the face
805
`ecb-default-general-face'.
806
807
Changes take first effect after finishing and reactivating ECB!
808
809
- User Option: directory-face
810
Face used for highlighting current directory in the directories buffer. If
811
the face `ecb-default-highlight-face' is used then the display of all
812
ECB-tree-buffers can be changed by modifying only the face
813
`ecb-default-highlight-face'.
814
815
Changes take first effect after finishing and reactivating ECB!
816
817
- User Option: directory-not-accessible-face
818
Face for not accessible dirs in the directories buffer.
819
820
- User Option: history-face
821
Face used for highlighting current history-entry in the history buffer. If
822
the face `ecb-default-highlight-face' is used then the display of all
823
ECB-tree-buffers can be changed by modifying only the face
824
`ecb-default-highlight-face'.
825
826
Changes take first effect after finishing and reactivating ECB!
827
828
- User Option: history-general-face
829
Basic face for the ECB directory buffer. This defines the basic face the
830
whole history buffer should displayed with. If the face
831
`ecb-default-general-face' is used then the display of all
832
ECB-tree-buffers can be changed by modifying only the face
833
`ecb-default-general-face'.
834
835
Changes take first effect after finishing and reactivating ECB!
836
837
- User Option: method-face
838
Face used for highlighting current method, class or variable in the
839
methods buffer. If the face `ecb-default-highlight-face' is used then the
840
display of all ECB-tree-buffers can be changed by modifying only the face
841
`ecb-default-highlight-face'.
842
843
Changes take first effect after finishing and reactivating ECB!
844
845
- User Option: method-non-semantic-face
846
Face used for for displaying tags of sources not supported by semantic.
847
848
Changes take first effect after finishing and reactivating ECB!
849
850
- User Option: methods-general-face
851
Basic face for the ECB methods buffer. This defines the basic face the
852
whole methods buffer should displayed with. If the face
853
`ecb-default-general-face' is used then the display of all
854
ECB-tree-buffers can be changed by modifying only the face
855
`ecb-default-general-face'.
856
857
Changes take first effect after finishing and reactivating ECB!
858
859
- User Option: source-face
860
Face used for highlighting current source in the sources buffer. If the
861
face `ecb-default-highlight-face' is used then the display of all
862
ECB-tree-buffers can be changed by modifying only the face
863
`ecb-default-highlight-face'.
864
865
Changes take first effect after finishing and reactivating ECB!
866
867
- User Option: source-in-directories-buffer-face
868
Face for source files in the directories buffer.
869
870
- User Option: sources-general-face
871
Basic face for the ECB sources buffer. This defines the basic face the
872
whole sources buffer should displayed with. If the face
873
`ecb-default-general-face' is used then the display of all
874
ECB-tree-buffers can be changed by modifying only the face
875
`ecb-default-general-face'.
876
877
Changes take first effect after finishing and reactivating ECB!
878
879
- User Option: source-read-only-face
880
Face for read-only sources.
881
882
- User Option: tag-header-face
883
Face used for highlighting the tag header after jumping to it by clicking
884
onto a node in the methods buffer.
885
886
887
File: ecb.info, Node: ecb-faces, Next: ecb-download, Prev: ecb-face-options, Up: Customizable options
888
889
Group ecb-faces
890
---------------
891
892
This group contains all faces used in ECB:
893
894
`ecb-bucket-node-face:'
895
Face which can be used for displaying bucket tags in the methods buffer.
896
See also `ecb-bucket-node-display'.
897
898
`ecb-default-general-face:'
899
Basic face for all ECB tree-buffers. It's recommended to define here the
900
font-family, the font-size, the basic color etc.
901
902
In GNU Emacs 21.X all faces (even the face `ecb-default-highlight-face')
903
used in the ECB tree-buffers inherit from this face. Therefore the default
904
attributes like font etc. of a face used in a tree-buffer can be very
905
easily changed with face `ecb-default-general-face'.
906
907
With XEmacs there is no inheritance-feature but the options
908
`ecb-directories-general-face', `ecb-sources-general-face',
909
`ecb-methods-general-face' and `ecb-history-general-face' offer the choice
910
to use the face `ecb-default-general-face' so also with XEmacs the basic
911
face-settings can be easily changed just by customizing the face
912
`ecb-default-general-face'!
913
914
`ecb-default-highlight-face:'
915
Define basic face for highlighting the selected node in an ECB tree-buffer.
916
917
In GNU Emacs 21.X all highlighting faces in the ECB tree-buffers inherit
918
from this face. Therefore the default attributes like font etc. of a face
919
used in a tree-buffer for highlighting the current tag can be very easily
920
changed with face `ecb-default-highlight-face'.
921
922
With XEmacs there is no inheritance-feature but the options
923
`ecb-directory-face', `ecb-source-face', `ecb-method-face' and
924
`ecb-history-face' offer the choice to use the face
925
`ecb-default-highlight-face' so also with XEmacs the basic face-settings
926
can be easily changed just by customizing the face
927
`ecb-default-highlight-face'!
928
929
`ecb-directories-general-face:'
930
Basic face for the ECB directories buffer. It�s recommended to define here
931
the font-family, the font-size, the basic color etc.
932
933
`ecb-directory-face:'
934
Define face used for highlighting current directory in the directories
935
buffer.
936
937
`ecb-directory-not-accessible-face'
938
Define a face for not accessible dirs in the directories buffer.
939
940
`ecb-history-face:'
941
Define face used for highlighting current history-entry in the history
942
buffer.
943
944
`ecb-history-general-face:'
945
Basic face for the ECB history buffer. It�s recommended to define here the
946
font-family, the font-size, the basic color etc.
947
948
`ecb-method-face:'
949
Define face used for highlighting current method, class or variable in the
950
methods buffer.
951
952
`ecb-methods-general-face:'
953
Basic face for the ECB methods buffer. It�s recommended to define here the
954
font-family, the font-size, the basic color etc.
955
956
`ecb-method-non-semantic-face:'
957
Define face used for displaying tags of sources not supported by semantic.
958
959
`ecb-mode-line-data-face'
960
Define face for the data in the mode-line. See `ecb-mode-line-data'.
961
962
`ecb-mode-line-prefix-face'
963
Define face for the prefix in the mode-line. See `ecb-mode-line-prefixes'.
964
965
`ecb-source-face:'
966
Define face used for highlighting current source in the sources buffer.
967
968
`ecb-source-in-directories-buffer-face:'
969
Define a face for displaying sources in the directories buffer.
970
971
`ecb-sources-general-face:'
972
Basic face for the ECB sources buffer. It�s recommended to define here the
973
font-family, the font-size, the basic color etc.
974
975
`ecb-source-read-only-face'
976
Define a face for read-only sources
977
978
`ecb-tag-header-face:'
979
Define face used for highlighting the tag header after jumping to it by
980
clicking onto a node in the methods buffer.
981
982
`ecb-tree-guide-line-face:'
983
Define face for the guide-lines in the tree-buffers. See the option
984
`ecb-tree-buffer-style' for a explanation of guide-lines.
985
986
`ecb-type-tag-class-face:'
987
Define face used with option `ecb-type-tag-display'.
988
989
`ecb-type-tag-enum-face:'
990
Define face used with option `ecb-type-tag-display'.
991
992
`ecb-type-tag-group-face:'
993
Define face used with option `ecb-type-tag-display'.
994
995
`ecb-type-tag-interface-face:'
996
Define face used with option `ecb-type-tag-display'.
997
998
`ecb-type-tag-struct-face:'
999
Define face used with option `ecb-type-tag-display'.
1000
1001
`ecb-type-tag-typedef-face:'
1002
Define face used with option `ecb-type-tag-display'.
1003
1004
`ecb-type-tag-union-face:'
1005
Define face used with option `ecb-type-tag-display'.
1006
1007
`ecb-mode-line-win-nr-face'
1008
Define face for the window-number in the mode-line. See
1009
`ecb-mode-line-display-window-number'.
1010
1011
Just call `customize-face <face-name>' to customize these faces for your
1012
personal taste. Or customize the related option in the group *Note
1013
ecb-face-options::.
1014
1015
1016
File: ecb.info, Node: ecb-download, Next: ecb-help, Prev: ecb-faces, Up: Customizable options
1017
1018
Group ecb-download
1019
------------------
1020
1021
This group contains settings for downloading and installing a new ECB from
1022
within ECB:
1023
1024
- User Option: download-delete-archive
1025
Should the downloaded archive be deleted after successful installation or
1026
after failure during the installation-process. Possible values are:
1027
1028
- `only-after-success': Archive is only deleted after successful
1029
installation but not if a failure occurs during the installation
1030
process.
1031
1032
- `always': Archive is also deleted if an error occurs.
1033
1034
- `nil': Archive will never be deleted.
1035
1036
- User Option: download-install-parent-dir
1037
Parent directory where downloaded packages are installed.
1038
1039
ECB installs a downloaded package in this directory, i.e. the downloaded
1040
archive X.tar.gz will be extracted in this directory so afterwards this
1041
directory contains a new subdirectory X which contains the downloaded
1042
package.
1043
1044
This directory must be write-able!
1045
1046
- User Option: download-package-version-type
1047
Version type ECB is allowed to download for upgrading.
1048
1049
If you want to upgrade to a newer ECB-version via `ecb-download-ecb' or if
1050
you must upgrade to newer semantic- eieio- and/or speedbar-versions
1051
(because ECB requires these newer versions) then this option specifies
1052
which version-types are allowed. ECB checks on the download-sites of
1053
ECB/semantic/eieio/speedbar which versions are currently available and
1054
then downloads always the latest version matching the specified type:
1055
1056
- 2: Get the newest version of all stable versions available.
1057
1058
- 1: Get the newest version of all stable and beta versions available.
1059
1060
- 0: Get the newest version of all stable, beta and alpha versions
1061
available.
1062
1063
- -1: Ask before downloading in the minibuffer for a version
1064
(TAB-completion of all available versions is possible).
1065
1066
So, 2 means stable, 1 means stable and betas, 0 means stable, betas and
1067
alphas and -1 means ask the user for a version.
1068
1069
Per default stable and beta-versions are allowed (value 1).
1070
1071
But all versions must match the restrictions of the specified min- and
1072
max-versions of the required packages. For this see the file README!
1073
1074
- User Option: download-url
1075
URL where download-able ECB-versions are located. The ECB-archive-file
1076
(e.g. ecb-1.70.tar.gz) will be appended to this URL and `ecb-download-ecb'
1077
will try to download this archive.
1078
1079
Note: Normally this URL should never change but who knows...
1080
1081
- User Option: gzip-setup
1082
Configuration for the gzip-utility. For a description about the possible
1083
settings see `ecb-wget-setup'.
1084
1085
- User Option: tar-setup
1086
Configuration for the tar-utility. For a description about the possible
1087
settings see `ecb-wget-setup'.
1088
1089
- User Option: wget-setup
1090
Configuration for the wget-utility. Value is a cons-cell where:
1091
1092
* car is the name of the wget-executable - if the executable can not be
1093
found in the PATH then it must be a full path.
1094
1095
* cdr is the path type of the file-arguments of this binary. Possible
1096
values are `cygwin', `windows' and `other' whereas the latter one is
1097
used for all Unix, Linux, Mac OS etc... If `cygwin' is set then the
1098
cygpath-utility must be in the PATH!
1188
1099
Loggerhead is a web-based interface for Breezy
Version: 2.0.1