Next: Core Functions, Previous: Introduction, Up: Magit-Section Developer Manual [Contents]
Create a section object of type CLASS, storing VALUE in its
value slot, and insert the section at point. CLASS is a
subclass of ‘magit-section’ or has the form (eval FORM), in
which case FORM is evaluated at runtime and should return a
subclass. In other places a sections class is often referred
to as its "type".
Many commands behave differently depending on the class of the current section and sections of a certain class can have their own keymap, which is specified using the ‘keymap’ class slot. The value of that slot should be a variable whose value is a keymap.
For historic reasons Magit and Forge in most cases use symbols as CLASS that don’t actually identify a class and that lack the appropriate package prefix. This works due to some undocumented kludges, which are not available to other packages.
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. Else 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 object 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, or
nil, 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 object is the end of the
heading (which lasts from start to content) and the beginning
of the 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.
If provided, optional CHILD-COUNT must evaluate to an integer or
boolean. If t, then the count is determined once the children have been
inserted, using magit-insert-child-count (which see). For historic
reasons, if the heading ends with ":", the count is substituted for
that, at this time as well. If magit-section-show-child-count is nil,
no counts are inserted
Use BODY to insert the section body, once the section is expanded.
If the section is expanded when it is created, then this is
like progn. Otherwise BODY isn’t evaluated until the section
is explicitly expanded.
Cancel inserting the section that is currently being inserted. Remove all traces of that section.
Repeatedly call FUNCTION until it returns nil or the end of the
buffer is reached. FUNCTION has to move point forward or return
nil.
Next: Core Functions, Previous: Introduction, Up: Magit-Section Developer Manual [Contents]