Next: , Previous: , Up: Magit-Section Developer Manual   [Contents]


3 Core Functions

Function: magit-current-section

Return the section at point or where the context menu was invoked. When using the context menu, return the section that the user clicked on, provided the current buffer is the buffer in which the click occurred. Otherwise return the section at point.

Function magit-section-at &optional position

Return the section at POSITION, defaulting to point. Default to point even when the context menu is used.

Function: magit-section-ident section

Return an unique identifier for SECTION. The return value has the form ((TYPE . VALUE)...).

Function: magit-section-ident-value value

Return a constant representation of VALUE.

VALUE is the value of a magit-section object. If that is an object itself, then that is not suitable to be used to identify the section because two objects may represent the same thing but not be equal. If possible a method should be added for such objects, which returns a value that is equal. Otherwise the catch-all method is used, which just returns the argument itself.

Function: magit-get-section ident &optional root

Return the section identified by IDENT. IDENT has to be a list as returned by magit-section-ident. If optional ROOT is non-nil, then search in that section tree instead of in the one whose root magit-root-section is.

Function: magit-section-lineage section &optional raw

Return the lineage of SECTION. If optional RAW is non-nil, return a list of section objects, beginning with SECTION, otherwise return a list of section types.

Function: magit-section-content-p section

Return non-nil if SECTION has content or an unused washer function.

The next two functions are replacements for the Emacs functions that have the same name except for the magit- prefix. Like magit-current-section they do not act on point, the cursors position, but on the position where the user clicked to invoke the context menu.

If your package provides a context menu and some of its commands act on the "thing at point", even if just as a default, then use the prefixed functions to teach them to instead use the click location when appropriate.

Function magit-point

Return point or the position where the context menu was invoked. When using the context menu, return the position the user clicked on, provided the current buffer is the buffer in which the click occurred. Otherwise return the same value as point.

Function magit-thing-at-point thing &optional no-properties

Return the THING at point or where the context menu was invoked. When using the context menu, return the thing the user clicked on, provided the current buffer is the buffer in which the click occurred. Otherwise return the same value as thing-at-point. For the meaning of THING and NO-PROPERTIES see that function.


Next: Matching Functions, Previous: Creating Sections, Up: Magit-Section Developer Manual   [Contents]