Skip to content

Documentation

Jump to bottom
SnejUgal edited this page Oct 10, 2019 · 12 revisions

Module structure

Here's a list of submodules of attheme-js you can use.

Submodules in the tools directory are not used by attheme-js and are intended to simplify some work you may face.

Other files are not intended to be external and you should not use them.

Types

If you ever need to use some of interfaces attheme-js defines, you may import attheme-js/lib/types. It exports Color, ColorSignature and VariableIterator.

attheme-js

import Attheme from "attheme-js";

new Attheme(contents?: string | VariableIterator | null)

Constructs a new Attheme instance.

If contents is a string, the constructor will parse them and add the variables (and wallpaper, if present) to the theme.

If contents is a VariableIterator (an iterator over [string, Color]), then its yielded values are collected to the constructed theme.

Attheme#getWallpaper(): string | null

Returns the wallpaper of the theme. If it's not present, it returns null.

Attheme#setWallpaper(newWallpaper: string): void

Sets newWallpaper as the theme's wallpaper.

Attheme#hasWallpaper(): boolean

Returns a boolean whether the theme has a wallpaper.

Attheme#deleteWallpaper(): void

Deletes the wallpaper from the theme.

Important note: the methods above don't work with chat_wallpaper. In .attheme files, the image wallpaper is stored separately from the color value of chat_wallpaper.

Attheme#get(variable: string): Color | null

Returns a copy of the value of variable. If it's defined in the theme, then null is returned.

Attheme#set(variable: string, value: Color): void

Sets a copy of value as the value of variable.

Attheme#has(variable: string): boolean

Returns a boolean whether the theme has variable.

Attheme#delete(variable: string): void

Deletes the variable in the theme.

Attheme#getVariablesAmount(): number

Returns the amount of variables defined in the theme.

Attheme#getVariablesList(): string[]

Returns an array of names of variables defined in the theme.

Attheme#sort(): void

Sorts the theme's variables in place.

Attheme#fallbackToOther(other: Attheme): void

Fallbacks this theme to another theme:

  • Every variable which is present in other but not in this, is copied to this.
  • If this doesn't have a wallpaper, the wallpaper is copied from other.

Example of Attheme#fallbackToOther 

const other = new Attheme([
  [`checkbox`, { red: 0, green: 0, blue: 0, alpha: 255 }],
  [`checkboxCheck`, { red: 255, green: 0, blue: 0, alpha: 255 }],
]);
other.setWallpaper(`wallpaper`);

const theme = new Attheme([
  [`checkbox`, { red: 255, green: 255, blue: 255, alpha: 255 }],
]);
theme.fallbackToOther(other);

console.log(theme.get(`checkbox`)); // { red: 255, green: 255, blue: 255, alpha: 255 }
console.log(theme.get(`checkboxCheck`)); // { red: 255, green: 0, blue: 0, alpha: 255 }
console.log(theme.getWallpaper()); // wallpaper

Attheme#fallbackToSelf(fallbackMap: Map<string, string>): void

Fallbacks variables to other existing variables according to the map.

Example of Attheme#fallbackToSelf 

const theme = new Attheme([[`foo`, { red: 0, green: 0, blue: 0, alpha: 0 }]]);
theme.fallbackToSelf(new Map([[`bar`, `foo`], [`spam`, `eggs`]]));

console.log(theme.get(`bar`)); // { red: 0, green: 0, blue: 0, alpha: 0 }
console.log(theme.get(`spam`)); // null

Attheme#@@iterator()

This is a generator that yields all the theme's variables as a tuple [string, Color]. The first element in the tuple is the variable name and the second one is a copy of the value of the variable.

Examples of Attheme#@@iterator()

This is how you iterate over a theme:

const theme = new Attheme(/* ... */);

for (const [variable, color] of theme) {
  console.log(variable, `has the value`, color);
}

You may copy all the variables from the theme this way:

const theme = new Attheme(/* ... */);
const variablesCopy = new Map(theme);

console.log(variabliesCopy.entries().next()); // [variable name, its value]

Attheme#toString(colorSignature: ColorSignature = "int"): string

Serializes the theme.

Examples of Attheme#toString 

const theme = new Attheme(/* ... */);
fs.writeFile(`theme.attheme`, String(theme));
const theme = new Attheme(/* ... */);
fs.writeFile(`theme.attheme`, theme.toString(`hex`)); // Uses HEX

variables

import VARIABLES from "attheme-js/lib/variables";

A list of all variable names.

fallbacks

import FALLBACKS from "attheme-js/lib/fallbacks";

A fallback map used by Telegram.

defaultThemes/default

import defaultTheme from "attheme-js/lib/defaultThemes/default";

A function that generates the default theme. Note that it does not have all variables, use the VARIABLES constant from the [variables] file.

defaultThemes/mono

import mono from "attheme-js/lib/defaultThemes/mono";

A function that generates a Mono theme with the accent color provided as the first argument.

defaultThemes/dark

import dark from "attheme-js/lib/defaultThemes/dark";

A function that generates a Dark theme with the accent color provided as the first argument.

defaultThemes/arctic

import arctic from "attheme-js/lib/defaultThemes/arctic";

A function that generates an Arctic theme with the accent color provided as the first arguments.

defaultThemes/graphite

import graphite from "attheme-js/lib/defaultThemes/graphite";

A function that generates the Graphite theme. Note that this theme is only available in debug builds, so, if the theme is removed never reaching production builds, this file may be removed without a major version bump.

tools/themeToObject

import themeToObject from "attheme-js/lib/tools/themeToObject";

const IMAGE_KEY = Symbol.for(`image`);

interface ObjectTheme {
  [key: string]: Color;
  [IMAGE_KEY]?: string;
}

themeToObject(theme: Attheme): ObjectTheme

Converts a new theme into an old one. This is useful for working with code that only knows the old API.

Examples of themeToObject 

const newTheme = new Attheme(/* ... */);
const oldTheme = themeToObject(newTheme);

await toTDesktopTheme(oldTheme); // Does something like this exist?

tools/node/fromFile

import fromFile from "attheme-js/lib/tools/node/fromFile";

fromFile(path: string): Promise<Attheme>

Asynchroniously reads the theme from the file at path. Note that the path is given to fs.readFile as it is, which reads the file relatively to process.cwd().

This function will read the theme at the given path correctly so the wallpaper won't spoil.

Examples of node/fromFile 

const themePath = process.argv[2];

fromFile(themePath).then(theme => {
  // ...
});

tools/node/toFile

import fromFile from "attheme-js/lib/tools/node/fromFile";

toFile(theme: Attheme, path: string, colorSignature?: ColorSignature): Promise<void>

Asynchronously writes the theme to the file at path.

Examples of node/to 

const theme = new Attheme(null, {
  defaultValues
});

toFile(theme, `The best most coolest theme.attheme`).then(() =>
  console.log(`Saved the theme!`);
);

tools/browser/fromFile

import fromFile from "attheme-js/lib/tools/browser/fromFile";

fromFile(file: File): Promise<Attheme>

Reads the theme from the file opened by the user, e.g. via <input type="file"> or Drag'n'Drop.

This function will read the theme at the given path correctly so the wallpaper won't spoil, which is a common mistake.

Examples of browser/fromFile 

const input = document.querySelector(`[name="theme"]`);

input.addEventListener(`change`, async () => {
  for (const file of input.files) {
    const theme = await fromTheme(file);

    // ...
  }
});

tools/browser/toBlob

import toBlob from "attheme-js/lib/tools/browser/toBlob";

toBlob(theme: Attheme, name: string, colorSignature?: ColorSignature): string

Serializes the theme and generates a Blob which you can use to download the theme.

Examples of browser/toBlob 

const theme = new Attheme(null, {
  defaultValues,
});

const link = document.createElement(`a`);

link.href = toBlob(theme, `The best theme ever`);
link.click();
link.remove();
Clone this wiki locally