Node:A new tree-buffer, Next:A new tree-node, Previous:Introduction, Up:tree-buffer
The creator-function for a new tree-buffer depends on the fact if the
new tree-buffer should be used as an ECB-interactor or not. For a new
ECB-interactor the macro defecb-tree-buffer-creator has to be
used, otherwise the function tree-buffer-create. In the end
both methods use tree-buffer-create because the BODY-argument
of defecb-tree-buffer-creator must contain a call to this
function!.
This section describes all arguments of tree-buffer-create.
Except the first argument NAME all arguments are key-arguments
of the form :arg-name arg-value, so for example a call looks like
(tree-buffer-create <buffer-name> :frame <frame-object> ...).
These key-arguments (all except the first argument NAME) can be
arranged in any arbitrary order but all of them are not-optional! The
key-arg-name is always a : followed by the lowercase version of the
mentioned argument below (e.g. FRAME -> :frame,
MOUSE-ACTION-TRIGGER -> :mouse-action-trigger).
Here is a description of the arguments of tree-buffer-create -
also available as docstring for this function (via C-h f). The
description below contains also some examples for complex-arguments!
NAME
FRAME
MOUSE-ACTION-TRIGGER
button-release and button-press.
IS-CLICK-VALID-FN
tree-buffer-create rebinds mouse-1, mouse-2,
RET (and TAB) and also in combination with shift and
control (not with TAB). IS-CLICK-VALID-FN is called first
if a node or an expand-symbol is clicked. This function is called with
five arguments:
The function must return not nil iff exactly this click/hit is accepted. If the function returns nil then really nothing is done by the tree-buffer after this click/hit!
Here is an example (call C-h f to see what it does) for this
callback-function:
(defun ecb-interpret-mouse-click (mouse-button
shift-pressed
control-pressed
meta-pressed
tree-buffer-name)
(if (eq mouse-button 0)
(list (if control-pressed 2 1) shift-pressed meta-pressed
'keyboard)
(if (and (not (eq mouse-button 1)) (not (eq mouse-button 2)))
nil
(case ecb-primary-secondary-mouse-buttons
(mouse-1--mouse-2
(if control-pressed
nil
(list mouse-button shift-pressed meta-pressed 'mouse)))
(mouse-1--C-mouse-1
(if (not (eq mouse-button 1))
nil
(list (if control-pressed 2 1) shift-pressed meta-pressed
'mouse)))
(mouse-2--C-mouse-2
(if (not (eq mouse-button 2))
nil
(list (if control-pressed 2 1) shift-pressed meta-pressed
'mouse)))
(otherwise nil)))))
This example would be passed as parameter as follows:
(tree-buffer-create "myname"
:is-click-valid-fn 'ecb-interpret-mouse-click
...)
NODE-SELECTED-FN
For the last four arguments see the description above. This function has to ensure that the expandable- and expanded-state of the selected node is correct after returning.
Here is an example (call C-h f to see what it does) for this
callback-function:
(defun ecb-tree-buffer-node-select-callback (node
mouse-button
shift-pressed
control-pressed
meta-pressed
tree-buffer-name)
(let* ((ecb-button-list (ecb-interpret-mouse-click mouse-button
shift-pressed
control-pressed
meta-pressed
tree-buffer-name))
(ecb-button (nth 0 ecb-button-list))
(shift-mode (nth 1 ecb-button-list))
(meta-mode (nth 2 ecb-button-list))
(keyboard-p (equal (nth 3 ecb-button-list) 'keyboard))
(maximized-p (ecb-buffer-is-maximized-p tree-buffer-name)))
;; now we dispatch to the right action
(when ecb-button-list
(cond ((ecb-string= tree-buffer-name ecb-directories-buffer-name)
(ecb-directory-clicked node ecb-button nil shift-mode
meta-mode))
((ecb-string= tree-buffer-name ecb-sources-buffer-name)
(ecb-source-clicked node ecb-button nil shift-mode
meta-mode))
((ecb-string= tree-buffer-name ecb-history-buffer-name)
(ecb-history-clicked node ecb-button nil shift-mode
meta-mode))
((ecb-string= tree-buffer-name ecb-methods-buffer-name)
(ecb-method-clicked node ecb-button nil shift-mode
meta-mode))
((ecb-string= tree-buffer-name ecb-analyse-buffer-name)
(ecb-analyse-node-clicked node ecb-button nil shift-mode
meta-mode))
(t nil)))))
This example would be passed as parameter as follows:
(tree-buffer-create "myname"
:node-selected-fn 'ecb-tree-buffer-node-select-callback
...)
IMPORTANT: This callback must not modify the slot
EXPANDED of the passed node because this is done automatically
by the tree-buffer-library!
NODE-EXPANDED-FN
This function should add all children nodes to this node if not already done (if possible). This function has to ensure that the expandable- and expanded state of the selected node is correct after returning!
IMPORTANT: This callback must not modify the slot
EXPANDED of the passed node because this is done automatically
by the tree-buffer-library!
NODE-COLLAPSED-FN
This function is only a callback to inform the owner/user of this tree-buffer that this node has been collapsed. This function must not modify the expandable- or expanded state of the selected node!
Often a sensefull value for this parameter is the function
ignore.
IMPORTANT: This callback must not modify the slot
EXPANDED of the passed node because this is done automatically
by the tree-buffer-library!
NODE-MOUSE-OVER-FN
tree-buffer-activate-follow-mouse). With GNU Emacs >=
21 this function is called by the help-echo property added to
each node.
Here is an example (call C-h f to see what it does) for this
callback-function:
(defun ecb-mouse-over-analyse-node (node &optional window no-message
click-force)
(let ((str (when (or click-force
(ecb-show-minibuffer-info
node window
(car ecb-analyse-show-node-info)))
(if (equal (cdr ecb-analyse-show-node-info)
'full-info)
(ecb-analyse-gen-tag-info
(car (tree-node->data node)))
(tree-node->name node)))))
(prog1 str
(unless no-message
(ecb-nolog-message str)))))
MOUSE-HIGHLIGHT-FN
NODE-DATA-EQUAL-FN
Here is an example (call C-h f to see what it does) for this
callback-function:
(defun ecb-analyse-compare-node-data (left right)
"Return not nil when LEFT and RIGHT are identical node-datas."
(and (equal (nth 2 left) (nth 2 right))
(ecb-compare-methods-buffer-node-data (car left)
(car right))))
Often a suitable value for this parameter is equal.
MAYBE-EMPTY-NODE-TYPES
tree-node-new). Nodes with one of these types are
treated as empty if they are not expandable (i.e. they have no
children) and will be displayed with the empty-symbol ([x]); for other
nodes see next argument.
LEAF-NODE-TYPES
Summary for MAYBE-EMPTY-NODE-TYPES and LEAF-NODE-TYPES:
MENU-CREATOR
tree-buffer-create-menu expects as argument - see the
documentation of this function for details. This function gets two
arguments: The name of the tree-buffer and the node for which a
popup-menu should be opened.
Here is an example for such a menu-creator-callback:
(defconst ecb-analyse-nodedata-tag-with-pos 0)
(defconst ecb-analyse-nodedata-tag-without-pos 1)
(defconst ecb-analyse-nodedata-no-tag 2)
(defconst ecb-analyse-nodetype-bucket 0)
(defconst ecb-analyse-nodetype-context 1)
(defconst ecb-analyse-nodetype-arguments 2)
(defconst ecb-analyse-nodetype-completions 3)
(defconst ecb-analyse-nodetype-localvars 4)
(defconst ecb-analyse-nodetype-prefix 5)
(defconst ecb-analyse-nodetype-assignee 6)
(defconst ecb-analyse-nodetype-function 7)
(defconst ecb-analyse-nodetype-function-arg 8)
(defun ecb-analyse-create-menu (node)
"Return a popup-menu suitable for NODE."
(let* ((data (tree-node->data node))
(tag-p (not (equal (nth 1 data) ecb-analyse-nodedata-no-tag)))
(tag-with-pos-p (equal (nth 1 data)
ecb-analyse-nodedata-tag-with-pos))
(nodetype (nth 2 data)))
(delq nil (list (if (equal nodetype ecb-analyse-nodetype-completions)
'(ecb-analyse-complete "Complete"))
(if tag-p
'(ecb-analyse-show-tag-info "Show tag info"))
(if tag-with-pos-p
'(ecb-analyse-jump-to-tag "Jump to tag"))))))
(defun ecb-analyse-menu-creator (tree-buffer-name node)
"Creates the popup-menus for the analyse-buffer."
(let ((nodetype (tree-node->type node)))
(unless (equal nodetype ecb-analyse-nodetype-bucket)
(mapcar (function (lambda (type)
(cons type (ecb-analyse-create-menu node))))
`(,ecb-analyse-nodetype-context
,ecb-analyse-nodetype-arguments
,ecb-analyse-nodetype-completions
,ecb-analyse-nodetype-localvars
,ecb-analyse-nodetype-prefix
,ecb-analyse-nodetype-assignee
,ecb-analyse-nodetype-function
,ecb-analyse-nodetype-function-arg)))))
This example would be passed as parameter as follows:
(tree-buffer-create "myname"
:menu-creator 'ecb-analyse-menu-creator
...)
MENU-TITLES
MODELINE-MENU-CREATOR
tree-buffer-create-menu expects as argument - see the
documentation of this function for details. This function gets one
argument: The name of the tree-buffer. If the function returns a menu
then this menu will be displayed when the user clicks with
mouse-button 3 at the modeline of the tree-buffer. The menu-title will
be "Tree-buffer modeline-menu".
TRUNC-LINES
READ-ONLY
TREE-INDENT
image (see below).
INCR-SEARCH-P
prefix, substring, nil. See the command
tree-buffer-incremental-node-search.
INCR-SEARCH-ADDITIONAL-PATTERN
If this argument is not nil then it must be a cons-cell where car is a
string which should be a regexp-pattern which is added to the
basic-prefix pattern (see above) and both of them prefix the
incr-search-pattern. The cdr is the number of subexpressions in this
additoonal pattern.
ARROW-NAVIGATION
Onto a not expandable node the horizontal arrow-keys go one character in the senseful correct direction.
HOR-SCROLL-STEP
DEFAULT-IMAGES-DIR
tree-buffer-tree-image-names.
ADDITIONAL-IMAGES-DIR
IMAGE-FILE-PREFIX
TREE-STYLE
image): Very nice and modern because image-icons are used to display
the tree-buffer. For this style the arguments TREE-INDENT and
EXPAND-SYMBOL-BEFORE-P have no effect.
Ascii-style with guide-lines (value ascii-guides) and
ascii-style without guidelines (value ascii-no-guides. See
Tree-buffer styles for details about the tree-styles.
Both ascii-styles are affected by the args TREE-INDENT and
EXPAND-SYMBOL-BEFORE-P.
ASCII-GUIDE-FACE
ascii-guides then this defines the face
the guides should be displayed with.
TYPE-FACER:
tree-node-new).
The cdr of a cons can be:
tree-buffer-insert-text). This function can do anything, but
normally it should face a tree-node.
EXPAND-SYMBOL-BEFORE-P
image and Emacs can display
images.
HIGHLIGHT-NODE-FACE
GENERAL-FACE
AFTER-CREATE-HOOK:
local-set-key for this).
Here is an example for such a hook:
(defun ecb-common-after-tree-buffer-create-actions ()
"Things which should be performed after creating a tree-buffer.
The tree-buffer is the current buffer."
(local-set-key (kbd "C-t")
'ecb-toggle-do-not-leave-window-after-select)
(if ecb-running-xemacs
(define-key modeline-map
'(button2up)
'ecb-toggle-maximize-ecb-window-with-mouse)
(local-set-key [mode-line mouse-2]
'ecb-toggle-maximize-ecb-window-with-mouse)))
AFTER-UPDATE-HOOK:
tree-buffer-update.
Here is an example how to create a tree-buffer (if you want a
tree-buffer not for ECB then just strip off the
defecb-tree-buffer-creator and just call
tree-buffer-create):
(defecb-tree-buffer-creator ecb-create-analyse-tree-buffer
ecb-analyse-buffer-name
"Create the tree-buffer for analyse-display."
(tree-buffer-create
ecb-analyse-buffer-name
:frame ecb-frame
:mouse-action-trigger ecb-tree-mouse-action-trigger
:is-click-valid-fn 'ecb-interpret-mouse-click
:node-selected-fn 'ecb-tree-buffer-node-select-callback
:node-expanded-fn 'ecb-tree-buffer-node-expand-callback
:node-collapsed-fn 'ecb-tree-buffer-node-collapsed-callback
:node-mouse-over-fn 'ecb-mouse-over-analyse-node
:mouse-highlight-fn 'ecb-analyse-node-mouse-highlighted-p
:node-data-equal-fn 'ecb-analyse-compare-node-data
:maybe-empty-node-types nil
:leaf-node-types nil
:menu-creator 'ecb-analyse-menu-creator
:menu-titles (ecb-analyse-gen-menu-title-creator)
:modeline-menu-creator 'ecb-common-tree-buffer-modeline-menu-creator
:trunc-lines (ecb-member-of-symbol/value-list
ecb-analyse-buffer-name
ecb-tree-truncate-lines)
:read-only t
:tree-indent ecb-tree-indent
:incr-search-p t
:incr-search-additional-pattern nil
:arrow-navigation ecb-tree-navigation-by-arrow
:hor-scroll-step ecb-tree-easy-hor-scroll
:default-images-dir (car ecb-tree-image-icons-directories)
:additional-images-dir (ecb-member-of-symbol/value-list
ecb-analyse-buffer-name
(cdr ecb-tree-image-icons-directories)
'car 'cdr)
:image-file-prefix "ecb-"
:tree-style ecb-tree-buffer-style
:ascii-guide-face ecb-tree-guide-line-face
:type-facer nil
:expand-symbol-before-p ecb-tree-expand-symbol-before
:highlight-node-face ecb-analyse-face
:general-face ecb-analyse-general-face
:after-create-hook (append
(list (lambda ()
(ecb-common-after-create-actions)))
ecb-common-tree-buffer-after-create-hook
ecb-analyse-buffer-after-create-hook)
:after-update-hook nil))