Skin development introduction: Difference between revisions

From Official Kodi Wiki
Jump to navigation Jump to search
No edit summary
Tag: Manual revert
 
(29 intermediate revisions by 5 users not shown)
Line 1: Line 1:
{{mininav|[[Development]]|[[Add-on development]]|[[Skin development]]}}
{{mininav|[[Development]]|[[Add-on development]]|[[Skinning]]}}
{{Cleanup}}
XBMC is noted as having a very flexible and robust framework for its GUI, making theme-skinning and personal customization very accessible. Users can create their own skin (or modify an existing skin) and share it with others. "Confluence" is the official skin;


XBMC includes a new GUI library written from scratch. This library allows you to skin/change everything you see in XBMC, from the images, the sizes and positions of all controls, colours, fonts, and text, through to altering navigation and even adding new functionality. The skin system is quite complex, and this portion of the manual is dedicated to providing in depth information on how it all works, along with tips to make the experience a little more pleasant.<br /><br />
{{Kodi}} is noted as having a very flexible and robust framework for its GUI, making theme-skinning and personal customization very accessible. Users can create their own skin (or modify an existing skin) and share it with others.
A skin called “Confluence”, which can be found in the XBMC GIT repo, is included with XBMC; the skin was originally created by Jezz_X and is kept up-to-date by Team XBMC.  
 
Any additional skins you create, or download must be placed in the '''addons''' sub-folder if you wish to have XBMC auto-detect the skin and allow you to load it from within the Appearance Settings. See [[Installing Skins]] for more. Currently, XBMC Frodo supports skin versions 4.0.0 and above; you will not be able to select and use a skin that is older than version 4.0.0<br /><br />You may wish to start by having a look through the "'''[[XBMC Skinning Manual]]'''" and the "'''[[XBMC Skinning Tutorials]]"''' articles, and try modifying a window or two by adding a button, or altering the textures or layout.
Kodi includes a new GUI library written from scratch. This library allows you to skin/change everything you see in Kodi, from the images, the sizes and positions of all controls, colours, fonts, and text, through to altering navigation and even adding new functionality. The skin system is quite complex, and this portion of the manual is dedicated to providing in depth information on how it all works, along with tips to make the experience a little more pleasant.<br /><br />
Kodi skins once installed are located in [[userdata]] addons folder. This is the folder where all skins are placed and listed.
 
Any additional skins you create or download or install via zip, Kodi will load and ask you if you would like to load the skin and also allow you to load them up from within the Appearance Settings. It is suggested that if you want to make your own skin, then starting by copying an existing skins files over into a new folder (let's say skin.myskin) is a good place to start. Don't forget to modify the addon.xml file and give your new skin a unique addon id.
You can then edit each of the files as you become more familiar with the skinning system. Try modifying a window or two by adding a button, or altering the textures or layout and test the result of your changes in Kodi.
<br /><br />
<br /><br />


== Anatomy of a Skin ==
== Anatomy of a Skin ==
The “Confluence” skin is a great starting point for designing your own skin; it contains many of the latest GIT features found in XBMC. If you want to make your own skin, start by copying the contents of the existing “Confluence” skin sub-folder into a new folder - for example, '''skin.name'''. You can then edit each of the various skin files as you become more familiar with the skinning system.<br /><br />
 
Each skin folder must contain a '''addon.xml''' and this initial set of sub-folders:
Each skin folder contains several subdirectorys, and several files:
; [[Addon.xml|skin.name/addon.xml]]
; [[addon.xml|myskin/addon.xml]]
: This contains the information that XBMC uses to find the other files that XBMC requires to describe it's skin. It also contains credits information, and versioning information.<br />
: This contains the information that Kodi uses to find the other files that Kodi requires to describe it's skin. It also contains credits information, and versioning information.
; skin.name/fonts
; myskin/1080p
: This sub-folder contains all fonts used by the skin. you can add/replace fonts here
: This is a resolution-specific directory. As Kodi can run in multiple resolutions, your skin can have multiple resolution folders. see: [[Addon.xml|How Window XML Files Are Found]]
; skin.name/media
; skin.myskin/backgrounds
: This sub-folder contains all the media files (.png/.gif/.jpg...)
: optional folder containing the background images used in the skin
; skin.name/sounds
; skin.myskin/colors
: This sub-folder contains all the audio files (sounds.xml/.wav...)
: contains a defaults.xml file which is used to define the colours used in the skin
; skin.name/colors
; skin.myskin/extras
: This sub-folder contains xml files describing the colors (text/diffuse) used in the skin, to allow different color themes.; skin.name/media
: optional folder containing any additional items, that don't fit elsewhere
; skin.name/_screenshots
; skin.myskin/fonts
: This sub-folder contains 5 to 10 1280x720 sized jpeg images, showcasing your skin
: This subdirectory contains all fonts used by the skin. you can add/replace fonts here
; skin.name/720p
; myskin/language
: This is a resolution-specific folder.<br /><br />
: contains several subfolders for each language (English/strings.po). you can define strings used in your skin in this file.
You can include multiple resolution-specific folders. The following recognized by XBMC:
; myskin/media
; skin.name/PAL16x9
: This subdirectory contains all the media files (.png/.gif/.jpg...) You can replace/edit these as you like.  
: This is a resolution-specific folder.
; skin.name/NTSC
: This is a resolution-specific folder.
; skin.name/NTSC16x9
: This is a resolution-specific folder.
; skin.name/720p
: This is a resolution-specific folder.
; skin.name/1080i
: This is a resolution-specific folder.<br /><br />
XBMC can run in multiple resolutions, and thus can use different files for some resolutions (as there is a big difference between NTSC at 720x480 pixels and 1080i at 1920x1080 pixels!) You can review the order by which XBMC retrieves resolution information in the '''[[Skin.xml#How window xml files are found|How Window XML Files Are Found]]''' section.<br /><br />
More advanced skins may also contain sub-folders for additional components required to make their skin work; for example:
; skin.name/backgrounds
: Often used to store large background images, that shouldn't be included in  the media folder
; skin.name/themes
; skin.name/themes
: Sometimes used to store additional textures in a different colour to create colour themes<br /><br />
: optional folder for additional skin themes. Used to store textures in a different colour to create colour themes
The goal is to keep your skin folder structure as cleanly organized as possible as it makes it easier to troubleshoot problems; this is becomes very important if you are working as part of a XBMC skin creation team.
; myskin/resources
<br /><br />
: place 10 screenshots (1280x720) of your skin in here. Name them screenshot-01.jpg, screenshot-02.jpg ect. NOTE: You will need to reference these using the asset tag in the addon.xml
; myskin/changelog.txt
: a textfile detailing what has changed in every version of the skin
; myskin/fanart.jpg
: a 1280x720 or 1920x1080 jpeg fanart image for your skin
; myskin/icon.png
: a 256x256 or 512x512 png image for your skin
; myskin/LICENSE.txt
: we recommend to include a Creative Commons license file in your skin: http://creativecommons.org/licenses/
<br />
The goal is to keep your skin folder structure as cleanly organized as possible as it makes it easier to troubleshoot problems; this is becomes very important if you are working as part of a Kodi skin creation team.


== Skin Themes ==
== Skin Themes ==
All the basic media files for a skin should be compressed into the Textures.xbt file, and placed in the media/ folder. You can use the tool [[TexturePacker]] for this. All the images that make up the default skin theme should be in the Textures.xbt file.
All the basic media files for a skin should be compressed into the Textures.xbt file, and placed in the media/ folder. You can use the tool [[TexturePacker]] for this. All the images that make up the default skin theme should be in the Textures.xbt file.


In addition to this, XBMC allows other .xbt files in the media/ folder, each one representing a different theme for your skin. For instance,
In addition to this, Kodi allows other .xbt files in the media/ folder, each one representing a different theme for your skin.  
you could tint all your main textures a red colour, and create a new theme package Red.xbt? – this gives users more choice in the look
For instance, you could tint all your main textures a red colour and create a new theme package called Red.xbt. This gives users more choice in the look of a particular skin.<br>
of a particular skin. Note that only the textures change when you change themes the layout stays the same. If the user has selected
Note that only the textures change when you change themes, the layout stays the same. If the user has selected a theme, then when a control requires a texture, Kodi will first look in the <themename>.xbt file for the texture. It will fall back to the Textures.xbt file if <themename>.xbt doesn't contain the image. This means that the theme .xbt files need only contain the changed textures, all other textures will fall-back to using Textures.xbt as usual.
a theme, then when a control requires a texture, XBMC will first look in the <themename>.xbt file for the texture. It will fall back to the Textures.xbt file if <themename>.xbt doesn't contain the image. This means that the theme .xbt files need only contain the changed textures all other textures will fall-back to using Textures.xbt as usual.


When the user selects a theme, XBMC will automatically also select the themes default color set, based on the <themename>.xml file located in the colors/ folder. See below for more information.
When the user selects a theme, Kodi will automatically also select the theme's default color set, based on the <themename>.xml file located in the colors/ folder. See below for more information.


A suggested method of creating a theme is as follows:
A suggested method of creating a theme is as follows:
Line 61: Line 59:
# Create a separate folder for each theme outside of your normal skin work area, and place the altered copies of each of the textures in them.
# Create a separate folder for each theme outside of your normal skin work area, and place the altered copies of each of the textures in them.
# Run TexturePacker.exe on each of the theme folders created in step 3 to create the themed .xbt files (note you can use the -output switch with TexturePacker.exe to name the theme appropriately).
# Run TexturePacker.exe on each of the theme folders created in step 3 to create the themed .xbt files (note you can use the -output switch with TexturePacker.exe to name the theme appropriately).
# Place Textures.xbt and each of the theme .xbt files in the media/ folder of your skin. XBMC will automatically pick them up.
# Place Textures.xbt and each of the theme .xbt files in the media/ folder of your skin. Kodi will automatically pick them up.
<br /><br />


== Colour Themes ==
== Colour Themes ==
Different colour themes can be accomplished by placing a set of .xml files in the colors/ folder of the skin. [[Colour Themes|See here for more information.]]
The XML files contained in the colors/ folder contain the different colour themes for the skin. This allows you the skinner to define the colours that you'll use for text and images once in terms of English names (rather than hex codes) and potentially allows you to have different colour themes.
 
== Fonts ==
XBMC allows you to customize which fonts are displayed onscreen in the User Interface. See the '''[[Fonts]]''' section for more information.
<br /><br />
 
== Includes ==
The other special (and arguably the most important skinning file of all) is includes.xml. This is, as its title suggests, a place from which you can define the default look, size, and positioning of controls, to save you replicating many of the control's attributes throughout the window .xml files. For instance, you can setup the size, and textures used for a button control, thus allowing you to leave those details out in the rest of the skin files, unless ofcourse you want to override the default look or size etc. in a particular window.<br /><br />
This is extremely valuable as it allows you to greatly simplify a lot of the work in building a skin. For one thing, it means that once you have include files setup, many of the default parameters for a different resolution can be done by just altering the parameters within the include file(s) for the different resolution.<br /><br />
With the 2.1 skinning engine, you can infact have more than one include file - you can specify the file attribute when including from a different file, allowing you to have an include file dedicated to a particular set of attributes.<br /><br />
The layout of an includes file is as follows.


<syntaxhighlight lang="XML" enclose="div">
Each additional colour theme has a single XML file, where the filename should be the same as the name of the colour theme (e.g. orange.xml). The default colours should be placed in defaults.xml - this is a fallback file that is used when the user hasn't requested another colour theme, or when their selected colour theme doesn't contain a particular colour assignment.
  <?xml version="1.0" encoding="UTF-8"?>
  <includes>
    <include name="whitetext">
      <textcolor>ffffffff</textcolor>
    </include>
    <include file="listdefaults.xml" />
    <default type="button">
      <include>whitetext</include>
    </default>
    <constant name="leftedge">50</constant>
  </includes>
</syntaxhighlight>


You'll notice in the above example that we have 4 different types of includes. The first <include> tag basically allows a substitution of the tags underneath it whenever it occurs. For instance, if in a window .xml file you have this:
The layout is as follows (note that the hex code is in ARGB format):


<syntaxhighlight lang="XML" enclose="div">
<syntaxhighlight lang="xml" enclose="div">
   <control type="togglebutton">
<colors>
    <include>whitetext</include>
   <color name="white">ffffffff</color>
    ... other tags go here
  <color name="grey">7fffffff</color>
  </control>
  <color name="green">ff00ff7f</color>
</colors>
</syntaxhighlight>
</syntaxhighlight>


Then it would substitute the <textcolor> tag for where the include tag is. You can have as many includes as you like, and as many tags can be inside an include - even complete controls, or complete control groups.
You can then use <textcolor>white</textcolor> within the main skin files to refer to which colour you want. This allows you to easily change all the colouring in the skin by just adding a new XML file to the colors/ folder.


The second <include> tag in the example demonstrates how to include from a different file. As there is no include name specified, it will include the contents of the entire file at that point.
== Fonts ==
 
There's one special file called Font.xml. This file contains a list of all fonts the skin uses.  
The <default> tag is similar to an include, except that it is used in every control of that type - even if you don't specify that the control is to use includes. Thus every buttoncontrol will have the whitetext include in it. Note that you can override this by specifying the <textcolor> tag in the buttoncontrol.
Kodi will load all the fonts mentioned in this file from the /myskin/fonts directory first, and if that fails,
 
will attempt to load them from Kodi/media/fonts. In the event that Kodi is unable to locate the specified font, it will default to "font13". You can modify this file as you like and add/delete/change fonts. The user friendly font name is referenced by the other xml files mentioned below.
And finally, the <constant> tag allows you to define a numeric (floating point) constant by name for use in place of numeric values (<posx>, height="" etc.) would otherwise be used. This allows alignment of items using the same position values which can then easily be altered in one place.
<br /><br />


== The Window XML Files ==
== The Window XML Files ==
The other xml files each define the skin for a single window. They all have the same basic layout, allowing you to place different controls on the window, and define how navigation should operate.<br /><br />
The other xml files each define the skin for a single window. They all have the same basic layout, allowing you to place different controls on the window, and define how navigation should operate.<br /><br />
The list of all window .xml files and what they represent is be found in the '''[[Window IDs|Window ID's]]''' section.<br /><br />
The list of all window .xml files and what they represent is be found in the '''[[Window IDs|Window ID's]]''' section.<br /><br />
The important thing to remember is that each window has a unique identifying number (id). This is how XBMC identifies the window from within the source code. Furthermore, many of the controls within each window should have a unique id as well, unless they're just used as images or labels where navigation is unimportant and XBMC does not need to be able to identify them uniquely. The window id's are all listed in the [[Window IDs|window list]].<br /><br />
The important thing to remember is that each window has a unique identifying number (id). This is how Kodi identifies the window from within the source code. Furthermore, many of the controls within each window should have a unique id as well, unless they're just used as images or labels where navigation is unimportant and Kodi does not need to be able to identify them uniquely. The window id's are all listed in the [[Window IDs|window list]].<br /><br />
The structure of the window .xml files can be found in the '''[[Window Structure]]''' section.
The structure of the window .xml files can be found in the '''[[Window Structure]]''' section.
<br /><br />
<br /><br />


== Controls ==
Controls are the substance of your skin. They define everything from buttons, to text labels, to visualization placement. The '''[[Controls]]''' section will explain each and every control in detail.
<br /><br />
== Conditional Visibility ==
XBMC's skinning engine versatility is based apon the fact that the skinner can display and hide portions of the skin using a variety of conditional statements that can be combined to create very user friendly UI implementations. For further information of available variable and how they can be applied see the '''[[Conditional Visibility]]''' section.
<br /><br />
== Animating Your Skin ==
The XBMC skinning engine supports animations of any control allowing them to rotate, slide, fade or any combination there-of. Combining animations with conditional statements ensure your skin will have stunning effects that appear as professional as a 1st party product. For further information, see the '''[[Animating Your Skin]]''' section.
<br /><br />
== Skinning Tutorials ==
This '''[[Skinning Tutorials]]''' section is designed to help both people who are new to skinning XBMC get to grips with how the system works, as well as dealing with a few things that the old timers may find useful.
== Skinning Manual ==
This '''[[Skinning Manual]]''' section is designed to give quick overview of all current skin code available to help the developers using the full extend of the possibilities.
'''See [[:Category:Skin_Development]] for a list of information'''
== Helpful Commands ==
When writing Skins one often needs XBMC to reload the current Skin.
To avoid the tedious procedure of loading another Skin and reloading yours or even close and reopen XBMC in order to see changes, you can map a key to refreshing the skin. This is done by [[HOW-TO:Modify keyboard.xml|modifying keyboard.xml]].
'''Example'''
This example keyboard.xml maps F5 to reloading the Skin, F4 followed by F5 to showing the DebugGrid (Skin specific see e.g. Aeon) and F6 to showing a popup notification (DialogKaiToast.xml)
<syntaxhighlight lang="XML" enclose="div">
<?xml version="1.0" encoding="UTF-8" standalone="yes"?>
<keymap>
    <global>
        <keyboard>
            <F5>XBMC.ReloadSkin()</F5>
            <F4>Skin.ToggleSetting(DebugGrid)</F4>
            <F6>Notification(Testing 123,Hello world)</F6>
        </keyboard>
    </global>
</keymap>
</syntaxhighlight>


== See also ==
== See also ==
Line 162: Line 95:
* [[Add-on development]]
* [[Add-on development]]


[[Category:Skin development]]
[[Category:Skin_development]]
[[Category:Add-on development]]
[[Category:Add-on development]]

Latest revision as of 20:36, 16 January 2023

Home icon grey.png   ▶ Development ▶ Add-on development ▶ Skinning ▶ Skin development introduction

Kodi is noted as having a very flexible and robust framework for its GUI, making theme-skinning and personal customization very accessible. Users can create their own skin (or modify an existing skin) and share it with others.

Kodi includes a new GUI library written from scratch. This library allows you to skin/change everything you see in Kodi, from the images, the sizes and positions of all controls, colours, fonts, and text, through to altering navigation and even adding new functionality. The skin system is quite complex, and this portion of the manual is dedicated to providing in depth information on how it all works, along with tips to make the experience a little more pleasant.

Kodi skins once installed are located in userdata addons folder. This is the folder where all skins are placed and listed.

Any additional skins you create or download or install via zip, Kodi will load and ask you if you would like to load the skin and also allow you to load them up from within the Appearance Settings. It is suggested that if you want to make your own skin, then starting by copying an existing skins files over into a new folder (let's say skin.myskin) is a good place to start. Don't forget to modify the addon.xml file and give your new skin a unique addon id. You can then edit each of the files as you become more familiar with the skinning system. Try modifying a window or two by adding a button, or altering the textures or layout and test the result of your changes in Kodi.

Anatomy of a Skin

Each skin folder contains several subdirectorys, and several files:

myskin/addon.xml
This contains the information that Kodi uses to find the other files that Kodi requires to describe it's skin. It also contains credits information, and versioning information.
myskin/1080p
This is a resolution-specific directory. As Kodi can run in multiple resolutions, your skin can have multiple resolution folders. see: How Window XML Files Are Found
skin.myskin/backgrounds
optional folder containing the background images used in the skin
skin.myskin/colors
contains a defaults.xml file which is used to define the colours used in the skin
skin.myskin/extras
optional folder containing any additional items, that don't fit elsewhere
skin.myskin/fonts
This subdirectory contains all fonts used by the skin. you can add/replace fonts here
myskin/language
contains several subfolders for each language (English/strings.po). you can define strings used in your skin in this file.
myskin/media
This subdirectory contains all the media files (.png/.gif/.jpg...) You can replace/edit these as you like.
skin.name/themes
optional folder for additional skin themes. Used to store textures in a different colour to create colour themes
myskin/resources
place 10 screenshots (1280x720) of your skin in here. Name them screenshot-01.jpg, screenshot-02.jpg ect. NOTE: You will need to reference these using the asset tag in the addon.xml
myskin/changelog.txt
a textfile detailing what has changed in every version of the skin
myskin/fanart.jpg
a 1280x720 or 1920x1080 jpeg fanart image for your skin
myskin/icon.png
a 256x256 or 512x512 png image for your skin
myskin/LICENSE.txt
we recommend to include a Creative Commons license file in your skin: http://creativecommons.org/licenses/


The goal is to keep your skin folder structure as cleanly organized as possible as it makes it easier to troubleshoot problems; this is becomes very important if you are working as part of a Kodi skin creation team.

Skin Themes

All the basic media files for a skin should be compressed into the Textures.xbt file, and placed in the media/ folder. You can use the tool TexturePacker for this. All the images that make up the default skin theme should be in the Textures.xbt file.

In addition to this, Kodi allows other .xbt files in the media/ folder, each one representing a different theme for your skin. For instance, you could tint all your main textures a red colour and create a new theme package called Red.xbt. This gives users more choice in the look of a particular skin.
Note that only the textures change when you change themes, the layout stays the same. If the user has selected a theme, then when a control requires a texture, Kodi will first look in the <themename>.xbt file for the texture. It will fall back to the Textures.xbt file if <themename>.xbt doesn't contain the image. This means that the theme .xbt files need only contain the changed textures, all other textures will fall-back to using Textures.xbt as usual.

When the user selects a theme, Kodi will automatically also select the theme's default color set, based on the <themename>.xml file located in the colors/ folder. See below for more information.

A suggested method of creating a theme is as follows:

  1. Run TexturePacker.exe on the folder containing the default texture files, to generate Textures.xbt as you would normally do.
  2. Identify the textures you wish to have themed and copy them to a separate folder.
  3. Create a separate folder for each theme outside of your normal skin work area, and place the altered copies of each of the textures in them.
  4. Run TexturePacker.exe on each of the theme folders created in step 3 to create the themed .xbt files (note you can use the -output switch with TexturePacker.exe to name the theme appropriately).
  5. Place Textures.xbt and each of the theme .xbt files in the media/ folder of your skin. Kodi will automatically pick them up.

Colour Themes

The XML files contained in the colors/ folder contain the different colour themes for the skin. This allows you the skinner to define the colours that you'll use for text and images once in terms of English names (rather than hex codes) and potentially allows you to have different colour themes.

Each additional colour theme has a single XML file, where the filename should be the same as the name of the colour theme (e.g. orange.xml). The default colours should be placed in defaults.xml - this is a fallback file that is used when the user hasn't requested another colour theme, or when their selected colour theme doesn't contain a particular colour assignment.

The layout is as follows (note that the hex code is in ARGB format):

<colors>
  <color name="white">ffffffff</color>
  <color name="grey">7fffffff</color>
  <color name="green">ff00ff7f</color>
</colors>

You can then use <textcolor>white</textcolor> within the main skin files to refer to which colour you want. This allows you to easily change all the colouring in the skin by just adding a new XML file to the colors/ folder.

Fonts

There's one special file called Font.xml. This file contains a list of all fonts the skin uses. Kodi will load all the fonts mentioned in this file from the /myskin/fonts directory first, and if that fails, will attempt to load them from Kodi/media/fonts. In the event that Kodi is unable to locate the specified font, it will default to "font13". You can modify this file as you like and add/delete/change fonts. The user friendly font name is referenced by the other xml files mentioned below.

The Window XML Files

The other xml files each define the skin for a single window. They all have the same basic layout, allowing you to place different controls on the window, and define how navigation should operate.

The list of all window .xml files and what they represent is be found in the Window ID's section.

The important thing to remember is that each window has a unique identifying number (id). This is how Kodi identifies the window from within the source code. Furthermore, many of the controls within each window should have a unique id as well, unless they're just used as images or labels where navigation is unimportant and Kodi does not need to be able to identify them uniquely. The window id's are all listed in the window list.

The structure of the window .xml files can be found in the Window Structure section.


See also

Development: