Next: Section Selection, Up: Section Plumbing [Contents][Index]
Insert a section at point.
TYPE is the section type, a symbol. Many commands that act on the
current section behave differently depending on that type. Also if
a variable magit-TYPE-section-map exists, then use that as the
text-property keymap of all text belonging to the section (but this
may be overwritten in subsections). TYPE can also have the form
(eval FORM) in which case FORM is evaluated at runtime.
Optional VALUE is the value of the section, usually a string that is required when acting on the section.
When optional HIDE is non-nil collapse the section body by default,
i.e. when first creating the section, but not when refreshing the
buffer. Otherwise, expand it by default. This can be overwritten using
magit-section-set-visibility-hook. When a section is recreated
during a refresh, then the visibility of predecessor is inherited
and HIDE is ignored (but the hook is still honored).
BODY is any number of forms that actually insert the section’s heading and body. Optional NAME, if specified, has to be a symbol, which is then bound to the struct of the section being inserted.
Before BODY is evaluated the start of the section object is set to
the value of point and after BODY was evaluated its end is set to
the new value of point; BODY is responsible for moving point
forward.
If it turns out inside BODY that the section is empty, then
magit-cancel-section can be used to abort and remove all traces of
the partially inserted section. This can happen when creating a
section by washing Git’s output and Git didn’t actually output
anything this time around.
Insert the heading for the section currently being inserted.
This function should only be used inside magit-insert-section.
When called without any arguments, then just set the content slot of
the object representing the section being inserted to a marker at
point. The section should only contain a single line when this
function is used like this.
When called with arguments ARGS, which have to be strings, then
insert those strings at point. The section should not contain any
text before this happens and afterwards it should again only contain
a single line. If the face property is set anywhere inside any of
these strings, then insert all of them unchanged. Otherwise use the
magit-section-heading face for all inserted text.
The content property of the section struct is the end of the heading
(which lasts from start to content) and the beginning of the body
(which lasts from content to end). If the value of content is nil,
then the section has no heading and its body cannot be collapsed.
If a section does have a heading then its height must be exactly one
line, including a trailing newline character. This isn’t enforced;
you are responsible for getting it right. The only exception is
that this function does insert a newline character if necessary.
Cancel the section currently being inserted. This exits the
innermost call to magit-insert-section and removes all traces of
what has already happened inside that call.
Define an interactive function to go to section SYM. TITLE is the displayed title of the section.
Next: Section Selection, Up: Section Plumbing [Contents][Index]