Function: kotl-mode:add-cell

kotl-mode:add-cell is an interactive and byte-compiled function defined in kotl-mode.el.

Signature

(kotl-mode:add-cell &optional RELATIVE-LEVEL CONTENTS PLIST NO-FILL)

Documentation

Add one or more Koutline cells and return the last one added.

Add new cells relative to the current cell at optional RELATIVE-LEVEL with CONTENTS string, attributes in PLIST, a property list, and NO-FILL flag to prevent any filling of CONTENTS.

Optional prefix arg RELATIVE-LEVEL means one of the following:

 1. when = 0, add as the parent's first child cell (first cell in list);
 2. when < 0, add that number of cells as preceding siblings;
 3. when '(4) (universal arg, \C-u), add as the first child of the
    current cell;
 4. when > 0 or nil (meaning 1), add that number of cells as following
    siblings.

Key Bindings

Source Code

;; Defined in ~/.emacs.d/elpa/hyperbole-20260414.325/kotl/kotl-mode.el
(defun kotl-mode:add-cell (&optional relative-level contents plist no-fill)
  "Add one or more Koutline cells and return the last one added.
Add new cells relative to the current cell at optional
RELATIVE-LEVEL with CONTENTS string, attributes in PLIST, a
property list, and NO-FILL flag to prevent any filling of
CONTENTS.

Optional prefix arg RELATIVE-LEVEL means one of the following:

 1. when = 0, add as the parent's first child cell (first cell in list);
 2. when < 0, add that number of cells as preceding siblings;
 3. when \\='(4) (universal arg, \\`C-u'), add as the first child of the
    current cell;
 4. when > 0 or nil (meaning 1), add that number of cells as following
    siblings."
  (interactive "*P")
  (unless (or (integerp relative-level) (listp relative-level) )
    (error "(kotl-mode:add-cell): `relative-level' must be an integer or a list of integers, not '%s'" relative-level))
  (or (stringp contents) (setq contents nil))
  (cond ((and (zerop (prefix-numeric-value relative-level))
	      (progn (kotl-mode:beginning-of-buffer)
		     (setq relative-level -1)
		     ;; Fall through to add first child of root parent cell 0
		     nil)))
        ((and (< (prefix-numeric-value relative-level) 0)
	      (cond ((zerop (kotl-mode:backward-cell 1))
		     ;; Add preceding sibling if not on first cell at current level
		     (kotl-mode:add-cell (abs (prefix-numeric-value relative-level))
					 contents plist no-fill))
		    ((kotl-mode:up-level 1)
		     ;; Add preceding sibling cell when on first cell at
		     ;; current level other than level 1
		     (kotl-mode:add-child (abs (prefix-numeric-value relative-level))
					  contents plist no-fill))
		    ;; Fall through to add first children of root parent cell 0
		    (t nil))))
	(t (let ((klabel (kcell-view:label))
		 (lbl-sep-len (kview:label-separator-length kotl-kview))
		 cell-level new-cell sibling-p child-p start parent
		 cells-to-add parent-level decrement-func)
	     (setq cell-level (kcell-view:level nil lbl-sep-len)
		   child-p (equal relative-level '(4))
		   sibling-p (unless child-p
			       (cond ((not relative-level) 1)
				     ((>= (prefix-numeric-value relative-level) 0)
				      (prefix-numeric-value relative-level))))
		   parent-level (1- cell-level)
		   cells-to-add (or sibling-p
				    (and (not child-p)
					 (prefix-numeric-value relative-level))
				    1))
	     (if child-p
		 (setq cell-level (1+ cell-level))
	       (unless sibling-p
		 (setq cell-level (if (zerop parent-level) cell-level (1- cell-level))
		       start (point)
		       parent (kcell-view:parent nil lbl-sep-len))
		 (unless (memq parent '(0 t))
		   (goto-char start)
		   (error
		    "(kotl-mode:add-cell): No higher level at which to add cell")))
	       (if (and (eq parent 0) (eq cell-level 1))
		   ;; Add as first child of hidden root cell 0, i.e. as the first
		   ;; cell in the outline
		   (goto-char (point-min))
		 ;; Add as following sibling of current cell's parent.
		 ;; Move to parent.
		 ;; Skip from point past any children to next cell.
		 (when (kotl-mode:next-tree)
		   ;; If found a new tree, then move back to prior cell so can add
		   ;; new cell after it.
		   (kcell-view:previous nil lbl-sep-len))))

	     (unless (eq parent 0)
	       (goto-char (kcell-view:end)))
	     ;;
	     ;; Insert new cells into view.
	     (if (= cells-to-add 1)
		 (setq klabel
		       (cond (sibling-p
			      (klabel:increment klabel))
			     (child-p
			      (kview:id-increment kotl-kview)
			      (klabel:child klabel))
			     ;; add as sibling of parent of current cell
			     (t (klabel:increment (klabel:parent klabel))))
		       new-cell (kview:add-cell klabel cell-level contents plist
						no-fill sibling-p))
	       ;;
	       ;; sibling-p must be number of cells to add if we are looping
	       ;; here, so there is no need to conditionalize how to
	       ;; increment the labels
	       (setq decrement-func (if (> cells-to-add 0) #'1- #'1+))
	       (let ((count cells-to-add))
		 (while (/= count 0)
		   ;; If cells-to-add is negative, cells are inserted
		   ;; before current cell, so the first time through
		   ;; the loop, don't increment the klabel or it will be
		   ;; off by 1.
		   (unless (and (= count cells-to-add)
				(< cells-to-add 0))
		     (setq klabel (klabel:increment klabel)))
		   ;; Since new cells are at the same level as old
		   ;; one, don't fill any of their intial contents.
		   (setq new-cell (kview:add-cell klabel cell-level contents plist t)
			 count (funcall decrement-func count)))))
	     ;;
	     ;; Move back to last inserted cell and then move to its following
	     ;; sibling if any.
	     (kotl-mode:to-valid-position t)
	     (save-excursion
	       (when (kcell-view:forward nil lbl-sep-len)
		 (let ((label-type (kview:label-type kotl-kview)))
		   (when (memq label-type '(alpha legal partial-alpha))
		     ;; Update the labels of these siblings and their subtrees.
		     (klabel-type:update-labels (klabel:increment klabel))))))
	     ;;
	     ;; Leave point within last newly added cell and return this cell.
	     (kotl-mode:beginning-of-cell)
	     new-cell))))