Skip to content

function-reference.md

Latest commit

 

History

History
781 lines (548 loc) · 24.6 KB

function-reference.md

File metadata and controls

781 lines (548 loc) · 24.6 KB
Raw

Autothemer

Reduce the amount of pain and boilerplate code needed to create custom themes using autothemer-deftheme.

Autothemer also includes interactive commands and functions to assist with theme building, here are a few highlights...

  • Generate specs for unthemed faces using the theme color palette.
    • autothemer-generate-templates
    • autothemer-generate-templates-filtered (filter by regexp)
  • Generate a palette SVG image
    • autothemer-generate-palette-svg
  • Insert a color name or color from the active palette
    • autothemer-insert-color-name
    • autothemer-insert-color
  • Colorize/font-lock palette color names in the buffer
    • autothemer-colorize (requires rainbow-mode during development.)

Function reference

Commands

User Functions

Internal Functions

autothemer-colorize command

In the current buffer, colorize palette color names, from the last evaluated theme, by their color value.

function signature

(autothemer-colorize)

autothemer-generate-palette-svg command

Create an SVG palette image for a theme.

Optional parameter options (a plist). Any required values not supplied in options will use defaults or prompt interactively.

Option Description
:theme-file theme filename
:theme-name override the title found in :theme-file
:theme-description override the description found in :theme-file
:theme-url override the url found in :theme-file
:font-family font name to use in the generated SVG
:columns number of columns for each palette row (default: 6)
:bg-color Page background color
:text-color Main text color
:text-accent-color Text accent color
:page-template see page-template below
:page-top-margin (default: 120)
:page-right-margin (default: 30)
:page-bottom-margin (default: 60)
:page-left-margin (default: 30)
:swatch-template see swatch-template below
:swatch-border-color the border color of a color swatch
:swatch-width px spacing width of a color swatch (default: 100)
:swatch-height px spacing height of a color swatch (default: 150)
:swatch-rotate degrees of rotation for swatch (default: 45)
:h-space horizontal-space between swatches (default: 10)
:v-space vertical-space between swatches (default: 10)
:sort-palette arrange palette using a function name
:group-swatches boolean
:svg-out-file the file/pathname to save SVG output

For advanced customization the :page-template and :swatch-template can be used to provide customize the SVG templates.

Note: Template parameters are filled by format so we mark them as follows:

Page Template parameters:

Parameter Description
%1$s width
%2$s height
%3$s font-family
%4$s text-color
%5$s text-accent-color
%6$s bg-color
%7$s theme-name
%8$s theme-description
%9$s theme-url
%10$s color swatches

Swatch Template parameters:

Parameter Description
%1$s x
%2$s y
%3$s swatch-border-color
%4$s swatch-color
%5$s text-accent-color
%6$s swatch-color-name

function signature

(autothemer-generate-palette-svg (&optional options))

autothemer-generate-templates command

Autogenerate customizations for unthemed faces (optionally by regexp).

Generate customizations that approximate current face definitions using the nearest colors in the color palette of autothemer-current-theme.

An error is shown when no current theme is available.

function signature

(autothemer-generate-templates (&optional regexp))

autothemer-generate-templates-filtered command

Autogenerate customizations for unthemed faces matching regexp.

Calls autothemer-generate-templates after user provides regexp interactively.

function signature

(autothemer-generate-templates-filtered (regexp))

autothemer-insert-color command

Select and insert a color from the current autotheme palette.

function signature

(autothemer-insert-color)

autothemer-insert-color-name command

Select and insert a color name from the current autotheme palette.

function signature

(autothemer-insert-color-name)

autothemer-brightness-group

Return the brightness group of color. Functionally identical to autothemer-hue-groups for brightness. Optionally provide a list of brightness-groups. The default is autothemer-20-percent-brightness-groups.

function signature

(autothemer-brightness-group (color &optional brightness-groups))

autothemer-color-brightness

Return the HSV brightness of color (hex color or autothemer--color struct).

function signature

(autothemer-color-brightness (color))

autothemer-color-hue

Return the HSV hue of color (hex color or autothemer--color struct).

function signature

(autothemer-color-hue (color))

autothemer-color-sat

Return the HSV saturation of color (hex color or autothemer--color struct).

function signature

(autothemer-color-sat (color))

autothemer-color-to-group

Group color using fn, in groups.

function signature

(autothemer-color-to-group (color fn groups))

autothemer-darkest-order

Return t if the darkness of a > b.

function signature

(autothemer-darkest-order (a b))

autothemer-desaturated-order

Return t if the saturation of a < b.

function signature

(autothemer-desaturated-order (a b))

autothemer-group-and-sort

Group and sort palette using options.

Options is a plist of:

Option Description
:group-fn mandatory group function
:group-args optional group args (to use a non-default group)
:sort-fn optional sort function

See color grouping functions and group lists:

Hue grouping:

Function Description
autothemer-hue-group color hue group for COLOR
Hue Groups Description
autothemer-hue-groups group colors into major hue groups (default)
autothemer-simple-hue-groups group colors into broad hue groups

Brightness grouping:

Function Description
autothemer-brightness-group brightness group for COLOR
Brightness Groups Description
autothemer-dark-mid-light-brightness-groups 3 brightness groups
autothemer-10-percent-brightness-groups 10 brightness groups
autothemer-20-percent-brightness-groups 5 brightness groups (default)

Saturation grouping:

Function Description
autothemer-saturation-group saturation group for COLOR
Saturation Groups Description
autothemer-low-mid-high-saturation-groups 3 saturation groups
autothemer-10-percent-saturation-groups 10 saturation groups
autothemer-20-percent-saturation-groups 5 saturation groups (default)

Sorting:

The sort/ordering functions take args A and B, which are expected to be autothemer--color structs.

Sort Functions Description
autothemer-darkest-order darkest to lightest
autothemer-lightest-order lightest to darkest
autothemer-hue-order sort by hue
autothemer-saturated-order sort by most saturated to least
autothemer-desaturated-order sort by least saturated to most

function signature

(autothemer-group-and-sort (palette options))

autothemer-group-colors

Group palette colors into groups as defined in plist options: :group-fn - mandatory group function :group-args - args for group-fn

function signature

(autothemer-group-colors (palette options))

autothemer-group-sort

Sort groups of colors using sort-fn. groups are produced by autothemer-group-colors.

function signature

(autothemer-group-sort (groups sort-fn))

autothemer-groups-to-palette

Flatten a grouped-palette from autothemer-group-and-sort to a single list.

function signature

(autothemer-groups-to-palette (grouped-palette))

autothemer-hex-to-rgb

Convert hex to (r g b). r, g, b will be values 0..65535

function signature

(autothemer-hex-to-rgb (hex))

autothemer-hue-group

Return the color hue group for color.

Optionally provide a list of hue-groups. (default uses autothemer-hue-groups.) Also available is autothemer-simple-hue-groups, both are customizable, or define your own.

This facilitates hue grouping & sorting by a secondary axis. For example sort a list of colors by some axis (brightness or saturation). Then group by hue groups, and sort the groups. The format of each group in the list is:

(group-name (n1 . n2))

Where group-name is a symbol to name the group, (n1 . n2) is a hue range specifier (in degrees) low n1 to high n2.

A hue range which crosses the apex (i.e. 360°..0°) is permitted.

function signature

(autothemer-hue-group (color &optional hue-groups))

autothemer-hue-order

Return t if the hue of a > b.

function signature

(autothemer-hue-order (a b))

autothemer-lightest-order

Return t if the lightness of a > b.

function signature

(autothemer-lightest-order (a b))

autothemer-saturated-order

Return t if the saturation of a > b.

function signature

(autothemer-saturated-order (a b))

autothemer-saturation-group

Return the saturation group of color. Functionally identical to autothemer-hue-groups for saturation. Optionally provide a list of saturation-groups. The default is autothemer-20-percent-saturation-groups.

function signature

(autothemer-saturation-group (color &optional saturation-groups))

autothemer-sort-palette

Produce a list of sorted theme-colors using sort-fn. If sort-fn is nil, sort by default autothemer-darkest-order. Grouping is supported via group-fn & group-args.

See autothemer-group-and-sort for a full list.

function signature

(autothemer-sort-palette (theme-colors &optional sort-fn group-fn group-args))

autothemer-let-palette

Provide a let block for body from autothemer-current-theme.

Load/eval the required autothemer source (not byte-compiled) to set autothemer-current-theme', before using autothemer-let-palette`

function signature

;; assuming your theme has a palette color of juicy-watermelon
(autothemer-let-palette ;;
  (message "%s" juicy-watermelon))

autothemer--alist-to-reduced-spec internal

Generate a reduced-spec for facename, based on the face attribute alist.

function signature

(autothemer--alist-to-reduced-spec (facename alist))

autothemer--approximate-spec internal

Replace colors in reduced-spec by their closest approximations in theme. Replace every expression in reduced-spec that passes color-defined-p by the closest approximation found in autothemer-current-theme. Also quote all face names and unbound symbols, such as normal or demibold.

function signature

(autothemer--approximate-spec (reduced-spec theme))

autothemer--color-distance internal

Return the distance in rgb space between color and AUTOTHEMER-color. Here, color is an Emacs color specification and AUTOTHEMER-color is of type autothemer--color.

function signature

(autothemer--color-distance (color autothemer-color))

autothemer--color-to-hsv internal

Convert rgb, a list of (r g b) to list (h s v). The r g b values can range between 0..65535.

In (h s v) h, s and v are 0.0..1.0.

function signature

(autothemer--color-to-hsv (rgb))

autothemer--colorize-alist internal

Generate an alist for use with rainbow-mode.

To colorize use:

(rainbow-colorize-by-assoc (autothemer--colorize-alist))

Colors are from autothemer-current-theme.

function signature

(autothemer--colorize-alist)

autothemer--cons-to-tree internal

Turn the-cons into a list, unless its cdr is unspecified.

function signature

(autothemer--cons-to-tree (the-cons))

autothemer--current-theme-guard internal

Guard functions from executing when there's no current theme.

function signature

(autothemer--current-theme-guard)

autothemer--demote-heads internal

Demote every list head within expr by one element. E.g., (a (b c d) e (f g)) -> (list a (list b c d) e (list f g)).

function signature

(autothemer--demote-heads (expr))

autothemer--extract-display internal

Extract from palette display specification #n.

function signature

(autothemer--extract-display (palette n))

autothemer--extract-let-block internal

Extract a variable definition block from palette for display type n.

function signature

(autothemer--extract-let-block (palette n))

autothemer--face-to-alist internal

Return the attribute alist for face in frame (selected-frame).

function signature

(autothemer--face-to-alist (face))

autothemer--fill-empty-palette-slots internal

Fill empty palette slots so each display has all color-definitions.

function signature

(autothemer--fill-empty-palette-slots (palette))

autothemer--find-closest-color internal

Return the element of colors that is closest in rgb space to color. Here, color is an Emacs color specification and colors is a list of autothemer--color structs.

function signature

(autothemer--find-closest-color (colors color))

autothemer--get-color internal

Return color palette object for (string) color-name.

Search the autothemer-current-theme color palette for color-name and returns a color in the form of autothemer--color struct.

See also autothemer--color-p, autothemer--color-name, autothemer--color-value.

function signature

(autothemer--get-color (color-name))

autothemer--pad-with-nil internal

Make sure that row has at least min-number-of-elements. Pad with nil if necessary.

function signature

(autothemer--pad-with-nil (row min-number-of-elements))

autothemer--reduced-spec-to-facespec internal

Create a face spec for display, with specs reduced-specs.

For example:

 (autothemer--reduced-spec-to-facespec '(min-colors 60) '(button (:underline t :foreground red)))
 ;; => `(button (((min-colors 60) (:underline ,t :foreground ,red)))).

function signature

(autothemer--reduced-spec-to-facespec (display reduced-specs))

autothemer--replace-nil-by-precursor internal

Replace nil colors in palette-row with their precursor.

palette-row is of the form (name color [color ...])

Where the first color must be non nil.

Any subsequent nil color will be replaced by the previous value.

For example:

 ("red-foo" "#FF0000" nil)

Will become:

 ("red-foo" "#FF0000" "#FF0000")

function signature

(autothemer--replace-nil-by-precursor (palette-row))

autothemer--select-color internal

Select a color from the current palette, optionally use prompt. Current palette is read from autothemer-current-theme.

The selected color will be in the form of a autothemer--color

See also autothemer--color-p, autothemer--color-name, autothemer--color-value.

function signature

(autothemer--select-color (&optional prompt))

autothemer--unindent internal

Unindent string s marked with | chars.

function signature

(autothemer--unindent (s))

autothemer--unthemed-faces internal

Find uncustomized faces. Iterate through all currently defined faces and return those that were left uncustomized by the most recent call to autothemer-deftheme.

function signature

(autothemer--unthemed-faces)