Complete guide to Android Telegram theming

Complete guide to Android Telegram theming

SnejUgal

Telegram for Android lets you create and use themes. This article is the complete guide to them—how to install, create them and so on.

Installing themes

Since almost a year Telegram began to support themes, a lot of channels and groups with themes appeared, e.g. @androidthemes, @themesandroid, @by_snejugal, @androidthemesgroup, etc. In any of these channels or groups, you'll find a lot of themes for Android.

When you find a theme for yourself, just tap the theme file (all Android Telegram themes' extension is .attheme).

Tap where the red circle is

When the file downloads, tap it again.

Right here

When you tap, a preview of the theme shows up—you can see what the theme looks like on your device. There are two screens—chat screen and chats list screen—are available for preview. You can see both them by swiping left and right.

If you want to apply the theme, tap the Apply button, if not, tap either the Cancel button or the system back button (not that one in chat preview!)

When you apply a theme, Telegram recolors.

You can apply as many themes as you want until you have no memory.

I've downloaded a theme from some website and it doesn't apply

Yes, applying a theme outside Telegram won't work:

You only can apply a theme inside Telegram but not outside. Thus, you have to share the theme via Telegram:

with yourself:

Now you can apply the theme since it's inside Telegram:

Do the same what you did previously

List of themes

All themes you've ever applied are remembered. This list is available at Settings → Theme.

It shows you the current theme and other themes you've ever applied. There are three dots icon beside each theme, tapping which opens this menu:

  • The Share button opens the list of apps via which you can share the theme;
  • The Edit button begins editing the theme;
  • The Delete button removes the theme out of the list.

In case of built-in themes, you'll see only the Share button.

Tapping a theme applies it. Holding one shows the menu described above.

Creating a theme

When the themes appeared, there was only the in-app editor. Nowadays, there are two web editors and two CLIs made by the community.

In-app editor

In-app editor is a good choice for a beginner. Changing a variable, you almost always see the color in action (not always—there's another article on this), and the variables list depends on the screen you are on.

To create a new theme, tap the Create new theme button on the themes list. It will suggest you to name your theme:

When you enter the name and tap OK, a new theme is created and applied, which base is the theme you had when you tapped the Create button. You'll also see a palette icon. You can move this icon anywhere on your screen; if you move it to the screen edge, the theme is saved and the icon disappears.

When you tap the icon, you'll see a list like this one:

  • The Close editor button hides this list but leaves the palette icon on the screen;
  • The Save theme button closes the list and takes the palette icon away. You can always return the icon back by tapping the Edit button on a theme's menu.

The words such as windowBackgroundWhite, actionBarDefault etc. are called variables. The colors applied to variables are called values, they are shows on the left to the variables.

When you tap a variable, this screen shows up:

Let's describe it in details.

  • The first three text fields are for RGB channels. The first one is the red channel, the second one is the green one and the third one is the blue one. The greater a value is, the more the final color has it. The value can be between zero and 255. You can learn more about RGB on Wikipedia;
  • The fourth text field is opacity. The value is between zero and 255 as well; the greater the value, the more opaque the color is;
  • The color wheel sets the hue and saturation of the color in the HSV color model;
  • The brightness slider sets the brightness level in the HSV color model;
  • The opacity level sets the opacity level of the color;
  • The Cancel button denies the color changes. It will cancel them even if you apply them and you open the same variable and tap this button at once;
  • The Default button resets the value to default;
  • The Save button saves the value.

Try changing the fields, wheel and sliders and you'll understand what they do.

You can try opening the editor on another screen and you'll see another list of variables:

Usually the list contains the variables you may face on the current screen. But these lists are not created automatically but by hand by the developer, so it is not rare not to find some variable inside the app.

This editor doesn't support HEX, searching through variables and may even distort the colors. Due to these issues, the community creates their editors with no bugs but improvements.

Third-party editors

The most important things you must know how to do to use community editors are exporting and importing themes. The import process was described above, the export process' steps are:

1. If the theme isn't shared in any chat, follow steps 2-5, otherwise go to step 6.

2. Open the themes list, find the theme you want to share and tap the three dots beside it.

3. Tap Share.

4. Select Telegram.

5. Tap the Saved Messages chat at the top of the list.

6. Download the theme if it isn't downloaded.

7. When the theme is downloaded, tap the three dots at the top right corner of the bubble.

8. Tap Save to Downloads.

A curious reader noticed they can select any app on step 4. It doesn't matter unless you can't extract the file from the app via which you shared your file.

Once you do the steps, the theme is saved in your Downloads folder. You can open this theme in any editor you'll like.

At this time, there are two editor by @snejugal and by @YouTwitFace. We're going to look at both of them.

.attheme editor by @snejugal

When you open the editor, it will suggest you to create a new theme or open an existing file.

Let's open an existing one. Tap Open an existing file and select Documents (it may depend on your browser and device).

And select the theme you want to open.

After you do it, you'll see a screen like this one:

  • The field at the top with words Amber Darkened is the theme name field, it lets you easily rename your theme (using in-app editor, you have to create a new theme);
  • The Close theme button closes the theme letting you open another theme;
  • The Download for further editing button editing button downloads an .attheme-editor file for further editing in this editor, keeping the same name, theme and palette;
  • The Compare with another theme button opens a tool to compare two themes preloading the opened theme in this editor;
  • The Find or add a variable… field lets you find variables and add them (there's no search in the in-app editor);
  • The download button in the bottom right corner downloads the .attheme file, optimizing it if possible.

The list of variables goes next. It looks like this:

A variable “card” has a name of the variable, its value written as HEX and RGBA and the preview of the color in the background. You'll see if a variable is transparent what you can't do using the in-app editor.

When you tap a variable “card”, you'll see this dialog:

It has two tabs. The first Value tab lets you set the color itself using either HEX, RGB or HSL and its alpha. The second Palette tab lets you select a color that's already added in your theme.

It is worth noticing that the alpha isn't changed when you select a color on the palette, which is pretty convenient. Double tap on a color removes it out of the palette. The first color on the palette is the default value of the variable, it doesn't show up only when editing chat_wallpaper.

Palette is a powerful feature of the editor, simple at first glance. You can only specify a color once and then take it on the palette and not typing its value again and again. What's more, you won't get a lot of color variations made by typos when typing the values that mean nothing for a man's brain.

The editor gradually gets previews of variables—what it will look like inside the Telegram app. The preview is completely colored in colors of the theme.

The pro of this feature is that you can see what elements it's hard to get which look like. However, the editor has just few of them what's going to become opposite through time.

Let's look at the search bar. When you tap it, a full list of variables in alphabetical order is shown that you can scroll:

When typing letters, only variables that fit the query are shown:

Tapping a variable starts its editing. The variables is automatically added in the theme if not.

Unfortunately, only one theme can be opened at the same time. It's impossible to set an image as the chat background, it is only saved on theme upload and kept in the file when download. But the pros are: offline mode, compatibility with both PC and Android and Drag'n'drop support:

lungers.com/attheme by @youtwitface

Probably, this editor isn't so handy than the one above is. However, it has a few features that one doesn't. When you open it, you'll see only one button telling you to open a theme.

Such screen appears after you open a theme:

  • The button at the top with current theme's name opens another theme;
  • The link below Edit theme heading opens the glossary of variables;
  • The Variable(s) field is filled with a list of variables separated by comma. Predictions are shown as you type;
  • The HEX field is filled with the value you want to turn entered variables to. As you activate this field, you'll see a panel with RGB channels and alpha fields to easily convert RGB to HEX and put it in the HEX field.
  • The Invert button inverts all color of the opened theme;
  • The Download button downloads the theme.

Hopefully the author of this editor improves it soon. But now, let's look at CLIs.

General information on CLIs

CLI is the abbreviation for Command-line interface. If you don't have a computer, it will be hard to use them, so you can just skip this section.

The CLIs we're going to look at are written on JS and made with Node.js. If you don't have Node.js and npm installed on your computer, download Node.js from the official website. npm comes along with Node.js.

I recommend read tutorials on using terminal for those who can't do it now.

attheme-cli

To install attheme-cli, you need to run this command:

When it's installed, you can run the attheme command in any folder on your computer:

The CLI will suggest you either to create a new theme, open the default theme or open one of themes in the folder you've started the CLI. By hitting top/bottom arrows, the selected item changes. After you choose a theme, you'll be able to run commands.

The list of all available commands is shown by the help command.

It is pretty hard to create a theme using a CLI, but it is ideal to fix a bug in a theme or add a new variable.

attheme-better-cli

The work with this CLI is pretty same. To install it, run this command:

To run the CLI, run the attheme-b command in your terminal:

The available commands are:

  • help—shows the list of available commands;
  • colors—shows all color of the opened theme in HEX. The HEXes are color in their value or a similar to it color—it depends on custom colors support in terminal by your OS;
  • save—saves the theme;
  • open—lets you open another theme;
  • show—shows a value of a variable;
  • set—sets the specified value to a variable.

Text editors

Any theme can be edited with a text editor. But it is not handy and the image of your theme can be damaged, however, we can look at the structure of .attheme files.

Let's open a theme, we'll see something like this:

We already can say what the structure is:

variable=value
variable=value

But what do these numbers mean? Let's look into it.

Let's take any HEX color, for example, #1ba1f3. Omit # and bring the alpha value back to the beginning of the hex so we get ff1ba1f3. Let's look at this number in binary:

0x stands for hexadecimal number

and measure the length of this string:

Let's look at this number as 32-bit. The first bit is 1, so the number is negative. Now we have to get the absolute value of this number, so we subtract that part by 1:

and invert it:

Now we present this number as decimal:

And now let's find -14966285 in the file:

If you do it vice versa, you can get HEX of a signed int. But it can be easier:

Probably, you will set values more often than see their colors in the text editor. Fortunately, you can specify HEX as a value of a variable—either #rrggbb or #aarrggbb:

You can leave comments in a file, but only on new lines:

Let's go deeper:

We can see some binary code begins here—it is the image wallpaper of the theme. The beginning of the image is marked with WPS—Wallpaper start—on the previous line before the image starts. The end of the image is marked with WPE—Wallpaper end—on the next line.

Now you know the structure of .attheme files and, if you're a developer, you can make tools on themes. If you're a JS developer, you can use attheme-js instead of inventing the wheel.

Probably your editor won't save the image correctly when saving the theme—this is why you should edit your themes using third-party editors or the in-app one but not with text ones.


We didn't describe each variable here—there's a glossary of them all. Use it when you don't know what a variables changes, but still try to find it on your own. You may also use @atthemeglossarybot for quicker access to the glossary, but it still knows less than the glossary does. Anyway, people in themes groups will help you with them!