Difference between revisions of "Skinning HowTo/Basics"

From Second Life Wiki
Jump to: navigation, search
m (left: improve entry)
(Terminology)
 
(56 intermediate revisions by 7 users not shown)
Line 1: Line 1:
{{multi-lang}}
+
{{Help|Viewer=*}}
This page is a stub. Improvements to this page are freely welcomed! 
+
{{XUI Nav}}
 +
== Introduction ==
 +
This page describes the skinning capabilities of Viewer 1.20 and higher. This document sets out some basic information about the structure and loading of UI textures, colors, floaters as defined in XML.
  
New skins have already been created -- see the page [[Skinning - Post Your Skins Here]].
+
Caution is always warranted when making changes to Second Life's installed files.  In some cases the Viewer will crash if an XML file is missing a requisite node or element, or if such an element is malformed/misspelled.  Making a backup copy of the unaltered files is highly recommended.  If a malformed file prevents you from running the viewer without an immediate crash, you will need to restore the original file; or re-install Second Life from the [http://secondlife.com/support/downloads.php download page].
  
If you would like to add tutorials with more than Basic information, you might choose to name your page along similar lines:
+
=== Terminology ===
* Skinning HowTo/Resize the toolbar
+
* Skinning HowTo/Changing a highlighting effect
+
* ''etc''
+
  
= Intro =
+
In XML, an ''element'' is like an HTML tag, for example the following code specifies a button element:
This page describes the skinning capabilities of Viewer 1.20 and higher.
+
<button ...>
 +
In XUI, a visual control or "widget" is created via one or more elements.  An element has ''attributes'', for example:
 +
<''element'' ''attribute''=value ''attribute''=value ... >
  
The skinning capabilities of the Second Life viewer are currently limited, but will be continuously improved through the development of the [[Skinning]] Project.  This document sets out some basic information about the structure and loading of UI textures, colors, floaters as defined in XML.
+
=== Helpful tools ===
 
+
* You will need an XML editor program for more easily making edits to an XML file. An example of a free open source editor is [http://www.activestate.com/Products/komodo_ide/komodo_edit.mhtml Komodo Edit].
Caution is always warranted when making changes to Second Life's installed files.  In some cases the viewer will crash if an XML file is missing requisite node or element, or if such an element is malformed/misspelled.  Making a backup copy of the unaltered files is highly recommended.  If a malformed file prevents you from running the viewer without an immediate crash, you will need to restore the original file; or re-install Second Life from the [http://secondlife.com/support/downloads.php download page].
+
 
+
=== Helpful Tools ===
+
* You will need an XML editor program for more easily making edits to an XML file.
+
** ''One such editor that is free and open source is [http://www.activestate.com/Products/komodo_ide/komodo_edit.mhtml Komodo Edit].''
+
  
 
* Most Windows versions do not provide a thumbnail view for tga files (an essential feature while editing the skin files). [http://greggman.com/pages/thumbplug_tga.htm Thumb Plug TGA] is a free open source tga thumbnail plugin that will provide this functionality.  
 
* Most Windows versions do not provide a thumbnail view for tga files (an essential feature while editing the skin files). [http://greggman.com/pages/thumbplug_tga.htm Thumb Plug TGA] is a free open source tga thumbnail plugin that will provide this functionality.  
Line 27: Line 23:
 
** [http://opensimulator.org/wiki/Connecting How to connect to an Open Simulator with your viewer]
 
** [http://opensimulator.org/wiki/Connecting How to connect to an Open Simulator with your viewer]
  
Its usefulness cannot be stressed enough.
+
Its usefulness cannot be stressed enough when dealing with xml files that need a relog (such as colors.xml).
 +
 
 +
=== Useful menu items ===
 +
 
 +
* Advanced > UI > Show Name Tooltops
 +
Shows the XML file name or UI path of whatever element your mouse is hovering over.
 +
 
 +
* Advanced > XUI > Edit UI...
 +
A barest of bones xml file editor. Useful for testing spacing and layout for portions of the UI without relogging.
 +
 
 +
=== Creating new skins ===
 +
New skins have already been created -- see the page [[Skinning - Post Your Skins Here]].
 +
 
 +
For a full list of tutorials -- see the [[Skinning_HowTo/Basics#See_Also]] section.
  
= \SecondLife\app_settings folder =
+
If you would like to add tutorials with more than Basic information, you might choose to name your page along similar lines:
(Note: In a Release Candidate version, the folder referenced here is instead '''\SecondLifeReleaseCandidate\'''app_settings)
+
* Skinning HowTo/Resize the toolbar
== colors_base.xml ==
+
* Skinning HowTo/Changing a highlighting effect
 +
* ''etc''
 +
 
 +
== Skins folder ==
 +
The skins folder is <code>\SecondLife\skins\[SKIN]\</code>
 +
 
 +
Note: colors.xml and colors_base.xml are now associated with specific viewer skins. Each skin folder has its own copy of colors.xml and colors_base.xml
 +
 
 +
=== colors_base.xml ===
 
This file defines the basic colors of the UI as separately named nodes.
 
This file defines the basic colors of the UI as separately named nodes.
  
* WARNING:  It is highly advisable that you do NOT MAKE CHANGES to this file.  Instead, copy & paste entries from this file to the next file (colors.xml) -- which overrides settings in colors_base.xml.  <b>The viewer will crash if any requisite entry is missing or malformed in colors_base.xml!</b>
+
WARNING:  It is highly advisable that you do NOT MAKE CHANGES to this file.  Instead, copy & paste entries from this file to the next file (colors.xml) -- which overrides settings in colors_base.xml.  <b>The viewer will crash if any requisite entry is missing or malformed in colors_base.xml!</b>
  
== colors.xml ==
+
=== colors.xml ===
 
By default, this file has no entries.  However this file can contains entries which will override any identically-named entry in colors_base.xml.
 
By default, this file has no entries.  However this file can contains entries which will override any identically-named entry in colors_base.xml.
  
Line 45: Line 62:
 
...where <code>R,G,B,Opacity</code> are in the range 0-255.  For opacity, 128 is half opacity (ergo, half transparent).
 
...where <code>R,G,B,Opacity</code> are in the range 0-255.  For opacity, 128 is half opacity (ergo, half transparent).
  
(Note: Opacity is also sometimes called the Alpha value)
+
Note: Opacity is also sometimes called the Alpha value.
  
* For example, you could copy the following entries ''from'' colors_base.xml and paste them ''into'' colors.xml, where you can make adjustments:
+
For example, you could copy the following entries ''from'' colors_base.xml and paste them ''into'' colors.xml, where you can make adjustments:
  
<pre>
+
<xml><!-- CHAT AND IM HISTORY TEXTBOX COLORS -->
<!-- CHAT AND IM HISTORY TEXTBOX COLORS -->
+
 
<ChatHistoryBgColor value="0, 30, 80, 200" />
 
<ChatHistoryBgColor value="0, 30, 80, 200" />
 
<ChatHistoryTextColor value="255, 255, 255, 255" />
 
<ChatHistoryTextColor value="255, 255, 255, 255" />
 
<IMHistoryBgColor value="0, 30, 80, 128" />
 
<IMHistoryBgColor value="0, 30, 80, 128" />
<IMHistoryTextColor value="255, 255, 255, 255" />
+
<IMHistoryTextColor value="255, 255, 255, 255" /></xml>
</pre>
+
  
= \SecondLife\skins\textures\ folder =
+
For ease of use, there is also a [[Skinning_How_To/Fully_commented_colors.xml_file|fully commented colors.xml file]] on the wiki that labels each setting.
(Note: In a Release Candidate version, the folder referenced here is instead '''\SecondLifeReleaseCandidate\'''skins\textures)
+
  
2008-04-08: This is where the viewer's installed textures reside.
+
== Textures folder ==
  
== *.j2c, *.tga, *.jpg, *.png ==
+
The <code>\SecondLife\skins\[SKIN]\textures\</code> folder contains the Viewer's installed textures. This folder contains these subfolders:
 +
*bottomtray
 +
*build
 +
*containers
 +
*icons
 +
*navbar
 +
*quick_tips
 +
*taskpanel
 +
*widgets
 +
*windows
 +
*world
  
* Many of these textures have a filename by UUID
+
=== Textures file ===
** most of these are installed textures used on Orientation Island.
+
* As part of the [[Dazzle]] project, every texture that is used in the UI now has a human-readable english filename... with the following EXCEPTIONS (''these omissions will be converted in the [[Skinning]] Phase 1''):
+
** 7a0b1bdb-b5d9-4df5-bac2-ba230da93b5b.tga (Create tool iconic button)
+
** 0098b015-3daf-4cfe-a72f-915369ea97c2.tga (Create tool iconic button, selected iconic button)
+
** 3c18c87e-5f50-14e2-e744-f44734aa365f.tga (Scroll-left-to-firstone |< icon)
+
** 7dabc040-ec13-2309-ddf7-4f161f6de2f4.tga (Scroll-right-to-lastone >|, highlighted icon)
+
** 9cad3e6d-2d6d-107d-f8ab-5ba272b5bfe1.tga (Scroll-left-to-firstone |<, highlighted icon)
+
** 89e9fc7c-0b16-457d-be4f-136270759c4d.tga (Volume "speaker" icon)
+
** 5748decc-f629-461c-9a36-a35a221fe21f.tga (blank icon)
+
+
* In a future phase of [[Skinning]] it is planned to move these UI textures to a separate folder so they can be found/manipulated together more easily.
+
  
* In the past,icon graphics/textures had to have an image size that was a power of two (eg, 32x128, 64x128, etc)but now they can be any size (eg. a 24x96 image).
+
The file <code>textures.xml</code> contains metadata about how to load, display, and scale textures for rendering in the UI. Images do *NOT* have to appear in this file in order to use them as textures in the UI. Simply refer to them by filename (relative to textures directory).
  
== textures.xml ==
+
NOTE: if you want to reuse an image file with different metadata, simply create a new texture entry with the same filename but different name
  
2008-04-08: Here is an example of some simple entries in textures.xml.  They have no stretch rectangle defined, not preloaded, are not referenced by UUID:
+
Here is an example of some simple entries in textures.xml.  They have no stretch rectangle defined, not preloaded, are not referenced by UUID:
<pre>
+
<xml> <icon_auction.tga/>
  <icon_auction.tga/>
+
 
   <icon_avatar_offline.tga/>
 
   <icon_avatar_offline.tga/>
 
   <icon_avatar_online.tga/>
 
   <icon_avatar_online.tga/>
Line 97: Line 109:
 
   <icon_place.tga/>
 
   <icon_place.tga/>
 
   <icon_popular.tga/>
 
   <icon_popular.tga/>
   <icon_top_pick.tga/>
+
   <icon_top_pick.tga/></xml>
</pre>
+
  
==== scaling rectangles (scale_rect) ====
+
==== Scaling rectangles ====
  
UI art textures are often stretched (scaled) in various resizing to accomodate different widths or heights of the same widget.  In order to preserve a crisp look of edges, part of the image is 'preserved' or protected to not be scaled.  By default, the stretching will preserve 8 pixels on all sides of the image.
+
UI art textures are often stretched (scaled) in various resizing to accommodate different widths or heights of the same widget.  In order to preserve a crisp look of edges, part of the image is 'preserved' or protected to not be scaled.  By default, the stretching will preserve 8 pixels on all sides of the image.
  
* To change this default, you set a <b><scale_rect /></b> element.
+
To change this default, set the <b><scale_rect /></b> element.
<code>
+
<xml><scale_rect left="''x1''" top="''y1''"  right="''x2''" bottom="''y2''" /></xml>
<scale_rect left="''x1''" top="''y1''"  right="''x2''" bottom="''y2''" />
+
</code>
+
* The pixel coordinates of the image here are counted from a (0,0) position that refers to the LEFT BOTTOM corner.  (Like a Cartesian coordinate system in quadrant I.)
+
  
* For example, this image toolbar_btn_selected.tga has dimensions of 128 pixels width x 24 pixels height: [[Image:Toolbar btn selected.tga.jpg]]  
+
The pixel coordinates of the image here are counted from a (0,0) position that refers to the LEFT BOTTOM corner(Like a Cartesian coordinate system in quadrant I.)
** The following <scale_rect /> code...
+
  
<code>
+
For example, this image toolbar_btn_selected.tga has dimensions of 128 pixels width x 24 pixels height: [[Image:Toolbar btn selected.tga.jpg]].
  <toolbar_btn_selected.tga>
+
 
 +
The following <scale_rect /> code defines a stretchable rectangle that ''preserves'' 26 pixels to its left and right:
 +
 
 +
<xml>  <toolbar_btn_selected.tga>
 
         <scale_rect left="26" top="24" right="102" bottom="0" />
 
         <scale_rect left="26" top="24" right="102" bottom="0" />
   </toolbar_btn_selected.tga>
+
   </toolbar_btn_selected.tga></xml>
</code>
+
 
:* ...defines a stretchable rectangle that ''preserves'' 26 pixels to its left & right:
+
It results in a display that looks like this:
 +
 
 
:: [[Image:Toolbar btn selected rect example1.jpg]]
 
:: [[Image:Toolbar btn selected rect example1.jpg]]
  
 
==== use_mips ====
 
==== use_mips ====
(under construction)
+
TBD.
  
 
==== preload ====
 
==== preload ====
Line 128: Line 139:
  
 
Example:  
 
Example:  
<code>
+
 
 +
<xml>
 
   <checkbox_disabled_false.tga preload="true" />
 
   <checkbox_disabled_false.tga preload="true" />
</code>
+
</xml>
  
= \SecondLife\skins\xui\ folder =
+
== XUI folder ==
(Note: In a Release Candidate version, the folder referenced here is instead '''\SecondLifeReleaseCandidate\'''skins\xui)
+
  
* XUI (pronounced zoo-e) stands for XML User Interface.  XUI consists of a custom XML data format for describing Second Life's user interface, and the code which processes that data and integrates it with the Second Life viewer.  
+
XUI (pronounced zoo-e) stands for XML User Interface.  XUI consists of a custom XML data format for describing Second Life's user interface, and the code which processes that data and integrates it with the Second Life viewer.  The XUI folder is <code>\SecondLife\skins\[SKIN]\xui\</code>.
  
== ..\[lang] folders ==
+
=== Language folders ===
  
When another language is selected in the viewer (Preferences > General > Language), then the files in the appropriate [lang] folder are loaded hierarchically on top of the en-us version, starting the next time the viewer is run.  
+
When you select a language in the Viewer (Preferences > General > Language), then the files in the appropriate [lang] folder are loaded hierarchically on top of the en-us version, starting the next time the viewer is run. The language folder is <code>\SecondLife\skins\[SKIN]\xui\[lang]</code>, where [lang] is the locale code, such as:
  
If an element (or entire file) is missing in the [lang] version, then the viewer falls back to the value specified in the en-us version.
+
Tier one languages:
 +
* de - German
 +
* fr - French
 +
* ja - Japanese
  
2008-04-08: Existing languages included in the viewer include:
+
Additional languages, for example:
 +
* es - Spanish
 +
* zh - Simplified Chinese - ''not officially supported nor updated regularly''
  
*\ko  Korean
+
If an element (or entire file) is missing in the [lang] version, then the Viewer falls back to the value specified in the en-us version.
*\ja  Japanese
+
*\de  German
+
*\fr  French - ''not officially supported nor updated regularly''
+
*\es  Spanish - ''not officially supported nor updated regularly''
+
*\zh  Simplified Chinese - ''not officially supported nor updated regularly''
+
  
The \[lang] version of floater or panel contains only the minimum values desired to override from the en-us version.
+
The \[lang] version of floater or panel contains only the minimum values desired to override from the en-us version.   Generally this includes only the matching <code>name=</code> property and the translated string/<code>label=</code>.   However in some cases a separate per-language width may be specified, to adjust the size of a particular widget for that language only.
* Generally this includes only a) the matching <code>name=</code> property and b) the translated string/<code>label=</code>.
+
* However in some cases a separate per-language width may be specified, in order to adjust the size of a particular widget for that language only.
+
  
== ..\en-us folder ==
+
=== The en-us folder ===
  
This folder is where the size of floaters, panels, and widgets are defined, as well the text strings in English used by the viewer.  
+
This folder is where the size of floaters, panels, and widgets are defined, as well the text strings in English the Viewer uses.  
  
IMPORTANT NOTE:  Do not ever change any <code>name=</code> parameters from the existing (English) name. The <code>name=</code> parameter is used to identify each node as expected when called in the viewer code, and to match it to other translations of the same node.
+
IMPORTANT NOTE:  Do not ever change any <code>name=</code> parameters from the existing (English) name. The <code>name=</code> parameter is used to identify each node as expected when called in the Viewer code, and to match it to other translations of the same node.
  
=== Related to localizations ===
+
==== Localization ====
A further discussion of the English text strings and how these are manipulated to make translations can be found at [[How to Localize Your World]]
+
[[Skinning HowTo/XUI Text]] describes the XUI elements and attributes related to text strings.
 +
A further discussion of the English text strings and how these are manipulated to make translations can be found at [[How to Localize Your World]].
  
=== Related to colors ===
+
=== Colors ===
2008-04-08: For purposes of skinning, it is important to note that there are still 2 XML files at this time which specify a color from within the \en-us folder:
+
For purposes of skinning, it is important to note that there are still 2 XML files at this time which specify a color from within the \en-us folder.  
===== 1. \skins\xui\en-us\floater_instant_message_ad_hoc.xml=====
+
* contains a <text_editor /> widget with a <code>bg_readonly_color, bg_writeable_color, text_color,</code> and <code>text_readonly_color</code>:
+
  
:A. Widget named "im_history"
+
The file <code>\skins\default\xui\en-us\floater_instant_message_ad_hoc.xml</code> contains a <text_editor /> widget with a <code>bg_readonly_color, bg_writeable_color, text_color,</code> and <code>text_readonly_color</code>:
<pre>
+
 
<text_editor type="string" length="1" bg_readonly_color="ChatHistoryBgColor"  
+
Widget named "im_history"
 +
<xml><text_editor type="string" length="1" bg_readonly_color="ChatHistoryBgColor"  
 
bg_writeable_color="ChatHistoryBgColor"
 
bg_writeable_color="ChatHistoryBgColor"
 
bottom="-265" embedded_items="false" enabled="false"
 
bottom="-265" embedded_items="false" enabled="false"
Line 178: Line 187:
 
max_length="2147483647" mouse_opaque="true" name="im_history"
 
max_length="2147483647" mouse_opaque="true" name="im_history"
 
text_color="ChatHistoryTextColor"
 
text_color="ChatHistoryTextColor"
text_readonly_color="ChatHistoryTextColor" width="490" word_wrap="true" />
+
text_readonly_color="ChatHistoryTextColor" width="490" word_wrap="true" /></xml>
</pre>
+
  
* These 4 values could be set as either a named entry in colors.xml (<code>bg_readonly_color="ChatHistoryBgColor"</code>) or directly as an R,G,B,O value (<code>bg_readonly_color="50, 115, 185, 150"</code>)
+
These four values could be set as either a named entry in colors.xml (<code>bg_readonly_color="ChatHistoryBgColor"</code>) or directly as an R,G,B,O value (<code>bg_readonly_color="50, 115, 185, 150"</code>)
 
** ''Note:  you can set a text color to any such'' <text_editor /> ''widget in the XML using the <code>text_color=</code> parameter.''
 
** ''Note:  you can set a text color to any such'' <text_editor /> ''widget in the XML using the <code>text_color=</code> parameter.''
  
===== 2. \skins\xui\en-us\floater_chat_history.xml=====
+
The file <code>\skins\default\xui\en-us\floater_chat_history.xml</code> contains a couple <text_editor /> widget with a <code>bg_readonly_color, bg_writeable_color, text_color,</code> and <code>text_readonly_color</code>:
* contains a couple <text_editor /> widget with a <code>bg_readonly_color, bg_writeable_color, text_color,</code> and <code>text_readonly_color</code>:
+
  
:A. Widget named "Chat History Editor"
+
'''Example: Widget named "Chat History Editor"'''
<pre>
+
 
<text_editor type="string" length="1" bottom="28" embedded_items="false" enabled="false"
+
<xml><text_editor type="string" length="1" bottom="28" embedded_items="false" enabled="false"
 
follows="left|top|right|bottom" font="SansSerif" height="74" left="5"
 
follows="left|top|right|bottom" font="SansSerif" height="74" left="5"
 
max_length="2147483647" mouse_opaque="true" name="Chat History Editor"
 
max_length="2147483647" mouse_opaque="true" name="Chat History Editor"
Line 195: Line 202:
 
bg_readonly_color="ChatHistoryBgColor"
 
bg_readonly_color="ChatHistoryBgColor"
 
bg_writeable_color="ChatHistoryBgColor"
 
bg_writeable_color="ChatHistoryBgColor"
word_wrap="true" />
+
word_wrap="true" /></xml>
</pre>
+
 
 +
'''Example: widget named "Chat History Editor with mute"'''
  
:B. Widget named "Chat History Editor with mute"
+
<xml><text_editor type="string" length="1" bottom="28" embedded_items="false" enabled="false"
<pre>
+
<text_editor type="string" length="1" bottom="28" embedded_items="false" enabled="false"
+
 
follows="left|top|right|bottom" font="SansSerif" height="74" left="5"
 
follows="left|top|right|bottom" font="SansSerif" height="74" left="5"
 
max_length="2147483647" mouse_opaque="true"
 
max_length="2147483647" mouse_opaque="true"
Line 206: Line 212:
 
text_readonly_color="ChatHistoryTextColor" width="300" word_wrap="true"  
 
text_readonly_color="ChatHistoryTextColor" width="300" word_wrap="true"  
 
bg_readonly_color="ChatHistoryBgColor"
 
bg_readonly_color="ChatHistoryBgColor"
bg_writeable_color="ChatHistoryBgColor"/>
+
bg_writeable_color="ChatHistoryBgColor"/></xml>
</pre>
+
  
=== Related to sizing ===
+
== Size and positioning ==
The XML files in this folder are also where you set the size (width=, height=) of UI widgets per floater, panel, etc.
+
  
The most comment parameters are listed here (under construction):
+
[[Image:Xui-coordinate-system.png|right]]
  
==== Common parameters ====
+
XUI uses a top-left based coordinate system. The top-left corner of the floater or panel is (0,0) as shown in the figure at right.
===== name =====
+
''Required.'' The XML name of this element. The name must be unique to the floater you are editing.  
+
  
* IMPORTANT: As noted above, do not re-name XML elements, even for localization. Many of the element names are looked up by the viewer. If the viewer cannot find an element name it expects, it will crash.
+
Second Life XUI files by convention prefer the order LEFT TOP WIDTH HEIGHT, for example:
  
String: <code>name="input_first_name"</code>
+
rect.left="20" rect.top="40"
===== width =====
+
rect.width="50" rect.height="20"
''Required.'' The width of the element, in pixels.  
+
  
For text, this defines the visible text as well as the clickable area. If the width of a text element is not sufficient to hold the text, the text will be truncated. This is most likely what you will widen when localizing the viewer.
+
You may also specify LEFT TOP RIGHT BOTTOM, for example:
  
For most other elements, this describes the dimensions of an element, such as a button, icon, panel, text_area, etc.
+
rect.left="20" rect.top="40"
 +
rect.right="70" rect.bottom="60"
  
* Tip: See the bounding boxes of all XML elements in the viewer: ''Advanced'' menu > UI > Debug Views.
+
The corresponding XML entry in textures.xml would be:
  
Integer: <code>width="140"</code>
+
<xml><texture name="TextField_Off"  
===== height =====
+
        file_name="widgets/TextField_Off.png"
''Required.'' The height of the element, in pixels.  
+
        preload="true"
 +
        scale.left="4"
 +
        scale.top="18"
 +
        scale.right="252"
 +
        scale.bottom="4" /></xml>
  
For text, this defines the visible text as well as the clickable area. If the height of a text element is not sufficient to hold the text, the text will be truncated. This is most likely what you will lengthen when localizing the viewer.
+
NOTE: preload="true" means that this texture will be ready for use before logging in. When no preload is set, the default is false.
  
For most other elements, this describes the dimensions of an element, such as a button, icon, panel, text_area, etc.
+
=== Size ===
 +
You must specify enough information for the XUI layout system to compute a width and height for each widget.  The best way to do this is to explicitly specify a width and height.  However, you may also specify a left and right edge rather than width, or a top and bottom edge rather than height.  This also works with relative positioning, such as left_pad or top_pad.
  
Integer: <code>height="24"</code>
+
=== Z-order ===
===== left =====
+
''Optional.'' Sets the position in the x dimension of the element's left edge relative to the container's left edge. Positive and negative values are accepted. A negative value will set the position relative to the '''right''' edge of the container.
+
  
Integer: <code> left="6"</code>
+
Z-order refers to which parts of the UI are displayed "in front" (overlaying) of others.
 +
By default, the z-order in the Viewer is:
  
===== right =====
+
# Modal dialogs.
''Optional.'' Sets the position in the x dimension of the element's right edge relative to the container. Positive and negative values are accepted. Best used to align something to the right. For example, given a floater with a width of 500 and a button we wish to right align in the floater, we can set the <code>right</code> to 490 -- putting the right edge of the button 10 pixels away from the right border of the floater.  
+
# Notifications – these may be interactive when there's a modal dialog up.
 +
# Bottom tray pop-up windows (IMs, voice panel, etc.)  These pop-up over other floaters until they're torn off, at which point they behave like other floaters.
 +
# Navbar/Bottom tray.
 +
# Floaters/Task Panel – the task panel will behave like a docked floater in that it will pop to the top of the floater stack when it has focus, but other floaters like search can be placed on top of the Task Panel if they get focus.
  
Integer: <code> right="6"</code>
+
== See also ==
 +
=== Other tutorials ===
 +
* A basic skinning tutorial for recoloring the viewer: [[Skinning_How_To/Skin_the_viewer]]
 +
* [[Skinning HowTo/Increase the transparency of unfocused Chat windows]]
 +
* [[Skinning HowTo/Increase the transparency of Pie Menu]]
 +
* [[Skinning HowTo/Make window backgrounds MORE opaque]]
 +
* [[Skinning How To/Edit a menu]]
 +
* [[Skinning How To/Add custom artwork to the viewer]]
 +
* [[Skinning How To/Add custom fonts to the viewer]]
 +
* [[Skinning How To/Window sizing and resizing]]
 +
* [[Skinning How To/Add 3rd party skins to the skins preferences panel]]
  
===== left_delta =====
+
=== Outdated tutorials ===
''Optional.'' Sets the position in the x dimension of the element's left edge relative to the previous element. Positive and negative values are accepted. Best used to left-align the current element with the previous element. For example, given Button B with a width of 100, a previous Button A with a width of 50 and a distance between elements of 6, we would set the <code>left_delta</code> to -106, putting the left edge of Button B 106 pixels to the left of Button A. We use a negative number to move left, and a positive number to move right.
+
* [[Skinning HowTo/Revert 1.20 to a Classic_look]] by McCabe Maxsted
 +
** Note: the final 1.20 viewer lets you switch between Silver and a Classic look automatically in Preferences > Skin. But this is still a great exercise in learning how the skinning architecture works!
 +
* [[Skinning How To/Remove the release keys button]] in viewer 1.20
 +
** Note: the final 1.21 viewer has permanently removed the release keys button, and moved it to the World menu.
 +
* [http://yukikoomegamu.blip.tv/file/810017 Dazzle Tutorial Part 1] by Yukiko Omegamu
  
Integer: <code> left_delta="-106"</code>
+
=== Helpful Resources ===
 
+
===== right_delta =====
+
''Optional.'' Sets the position in the x dimension of the element's right edge relative to the previous element. Positive and negative values are accepted. Best used to right-align the current element with the previous element. For example, given Button B with a width of 100, a previous Button A with a width of 50 and a distance between elements of 6, we would set the <code>right_delta</code> to 106, putting the left edge of Button B 106 pixels to the left of Button A.
+
 
+
Integer: <code> left_delta="106"</code>
+
+
===== bottom =====
+
''Optional.'' Sets the position in the y dimension of the element's bottom edge relative to the container. Positive and negative values are accepted. For example, given a floater with a height of 300 and a title 20 pixels tall and we want , we can set the <code>bottom</code> to (NEED TO DO MATH, LOL) -- putting the bottom edge of the title 40 pixels away from the top border of the floater.
+
 
+
Integer: <code> bottom="(NEED TO DO MATH, LOL)"</code>
+
 
+
===== bottom_delta =====
+
 
+
===== follows =====
+
''Optional.'' Sets which edge(s) an element follows when the containing element is resized. Specifying all edges results in an element that can dynamically resize itself with its container.
+
 
+
Values: left, top, right, bottom. String multiple values together using pipes.
+
 
+
The following example sets an element to follow both the left and the top, such as a floater's title may be designed:
+
String: <code>follows="left|top"</code>
+
 
+
==== button parameters ====
+
===== scale_image =====
+
''Optional.'' Specifies whether to scale the button art as its container/floater is resized. As of 1.18.x, all button art has this property set to <code>true</code> where the button size is not equal to 32x128.
+
 
+
Boolean: <code>scale_image="true"</code>
+
 
+
===== label =====
+
''Optional.'' Label is the text on the button's face. Without a specified label (and no <code>image_overlay</code> declared), your button will be labeled "Button".
+
String: <code>label="Click Me!" </code>
+
===== label_selected =====
+
''Optional.'' Label is the text on the button's face when pressed into an 'on' state. Your button will inherit the <code> label</code> if you omit this property.
+
String: <code>label_selected="I've been clicked." </code>
+
===== font =====
+
(under construction)
+
===== font_style =====
+
''Optional.'' Styles the text. Allows multiple style selections. As of 1.18.x, the style options are:
+
 
+
* normal: Apply the default styles of the selected font. (For example, SansSerifBold has a default bold style applied to it.)
+
* bold: Bolds the text.
+
* italic: Italicizes the text.
+
* underline: Underlines the text.
+
* drop_shadow: Old-style 1px offset of black under the text.
+
* drop_shadow_soft: New-style 3px offset of blurred shadow under the text.
+
 
+
String: <code>font_style="bold|underline|drop_shadow_soft"</code>
+
 
+
===== halign =====
+
(under construction)
+
 
+
===== image_unselected =====
+
''Optional.'' Overrides the default button art for the unselected/up and enabled button state. Art must be located in the <code>..\skins\textures</code> directory within the Second Life application folder (on a Mac, this is inside the package at <code>Contents/MacOS/Resources/skins/textures</code>). Art must also be named in <code>textures.xml</code> with an assigned UUID. By default, the button art is stretched to fit the specified button size.
+
 
+
String: <code>image_unselected="btn_square_32x128.tga"</code>
+
 
+
===== image_selected =====
+
''Optional.'' Overrides the default button art for the selected/down button state. Art must be located in the <code>..\skins\textures</code> directory within the Second Life application folder (on a Mac, this is inside the package at <code>Contents/MacOS/Resources/skins/textures</code>). By default, the button art is stretched to fit the specified button size.
+
 
+
String: <code>image_selected="btn_square-down_32x128.tga"</code>
+
 
+
===== image_hover_selected =====
+
''Optional.'' Overrides the default button art for the selected/down and mouseover/hover button state. Art must be located in the <code>..\skins\textures</code> directory within the Second Life application folder (on a Mac, this is inside the package at <code>Contents/MacOS/Resources/skins/textures</code>). Art must also be named in <code>textures.xml</code> with an assigned UUID. By default, the button art is stretched to fit the specified button size.
+
 
+
String: <code>image_unselected="btn_square-down-hover_32x128.tga"</code>
+
 
+
===== image_hover_unselected =====
+
''Optional.'' Overrides the default button art for the unselected/up and mouseover/hover button state. Art must be located in the <code>..\skins\textures</code> directory within the Second Life application folder (on a Mac, this is inside the package at <code>Contents/MacOS/Resources/skins/textures</code>). Art must also be named in <code>textures.xml</code> with an assigned UUID. By default, the button art is stretched to fit the specified button size.
+
 
+
String: <code>image_unselected="btn_square-up-hover_32x128.tga"</code>
+
 
+
===== image_disabled =====
+
''Optional.'' Overrides the default button art for the disabled button state. Art must be located in the <code>..\skins\textures</code> directory within the Second Life application folder (on a Mac, this is inside the package at <code>Contents/MacOS/Resources/skins/textures</code>). Art must also be named in <code>textures.xml</code> with an assigned UUID. By default, the button art is stretched to fit the specified button size.
+
 
+
String: <code>image_unselected="btn_square-disabled_32x128.tga"</code>
+
 
+
===== image_disabled_selected =====
+
''Optional.'' Overrides the default button art for the disabled and selected/down button state. Art must be located in the <code>..\skins\textures</code> directory within the Second Life application folder (on a Mac, this is inside the package at <code>Contents/MacOS/Resources/skins/textures</code>). Art must also be named in <code>textures.xml</code> with an assigned UUID. By default, the button art is stretched to fit the specified button size.
+
 
+
String: <code>image_unselected="btn_square-down-disabled_32x128.tga"</code>
+
 
+
===== image_overlay =====
+
''Optional.'' Applies an overlay image to the button. The button art will be sized to fit. As of 1.18.x, these icons should be 16 pixels high at maximum on a standard height 24px button to minimize scaling artifacts. Can be used with or without text. Art must be located in the <code>..\skins\textures</code> directory within the Second Life application folder (on a Mac, this is inside the package at <code>Contents/MacOS/Resources/skins/textures</code>). Art must also be named in <code>textures.xml</code> with an assigned UUID. See [[#image_overlay_alignment|image_overlay_alignment]] for alignment options.
+
 
+
String: <code>image_overlay="icn_media-play_16.tga"</code>
+
 
+
===== image_overlay_alignment =====
+
''Optional.'' Sets the alignment of the <code>image_overlay</code> icon.
+
 
+
Values:
+
* left: left-aligns the art on the button. This standard is used for new button art with text in the Dazzle branch.
+
* right: right-aligns the the art on the button.
+
* center: centers the art on the button. This standard is used for new button art without text in the Dazzle branch.
+
 
+
String: <code>image_overlay_alignment="left"</code>
+
 
+
==== text_editor parameters ====
+
===== max_length =====
+
===== embedded_items =====
+
===== font =====
+
===== word_wrap =====
+
===== hide_scrollbar =====
+
===== cursor_color =====
+
===== text_color =====
+
===== text_readonly_color =====
+
===== bg_readonly_color =====
+
===== bg_writeable_color =====
+
===== bg_focus_color =====
+
 
+
==== line_editor parameters ====
+
===== label =====
+
===== max_length =====
+
===== font =====
+
===== bevel_style =====
+
* none
+
* in
+
* out
+
* bright
+
* line
+
* texture
+
===== border_thickness =====
+
===== select_on_focus =====
+
===== select_all_focus_received =====
+
===== handle_edit_keys_directly =====
+
===== cursor_color =====
+
===== text_color =====
+
===== text_readonly_color =====
+
===== bg_readonly_color =====
+
===== bg_writeable_color =====
+
===== bg_focus_color =====
+
 
+
= See Also =
+
=== Other Tutorials ===
+
* [http://yukikoomegamu.blip.tv/file/810017 Dazzle Tutorial Part 1] by Yukiko Omegamu
+
* [[Skinning HowTo/Revert 1.20 to a Classic_look]] by McCabe Maxsted
+
* [[Skinning HowTo/Increase the transparency of unfocused Chat windows]]
+
* [[Skinning_HowTo/Increase_the_transparency_of_Pie_Menu]]
+
 
* [[Skinning_How_To/Artwork dependencies]]
 
* [[Skinning_How_To/Artwork dependencies]]
 +
* [[Skinning_How_To/Legacy_files]]
 
* [[Skinning_How_To/Hardcoded_limits_in_the_xml_files]]
 
* [[Skinning_How_To/Hardcoded_limits_in_the_xml_files]]
* [[Skinning_How_To/Window_sizing_and_resizing]]
+
* [[Skinning_How_To/The_XML_files_and_what_they_do]]
* [[Skinning_How_To/Edit_a_menu]]
+
* [[Skinning_How_To/Viewer_crash_causes]]
* [[Skinning_How_To/Remove_the_release_keys_button]]
+
* [[Skinning_How_To/Fully_commented_colors.xml_file|Fully commented colors.xml file]]
* [[Skinning_How_To/Skin_the_viewer|Basic skinning tutorial for recoloring the viewer]]
+
  
 
=== Resident Created Skins ===
 
=== Resident Created Skins ===
* see the page [[Skinning - Post Your Skins Here]]
+
See [[Skinning - Post Your Skins Here]].
 
[[Category:Skinning]]
 
[[Category:Skinning]]

Latest revision as of 13:25, 27 May 2010

Introduction

This page describes the skinning capabilities of Viewer 1.20 and higher. This document sets out some basic information about the structure and loading of UI textures, colors, floaters as defined in XML.

Caution is always warranted when making changes to Second Life's installed files. In some cases the Viewer will crash if an XML file is missing a requisite node or element, or if such an element is malformed/misspelled. Making a backup copy of the unaltered files is highly recommended. If a malformed file prevents you from running the viewer without an immediate crash, you will need to restore the original file; or re-install Second Life from the download page.

Terminology

In XML, an element is like an HTML tag, for example the following code specifies a button element:

<button ...>

In XUI, a visual control or "widget" is created via one or more elements. An element has attributes, for example:

<element attribute=value attribute=value ... >

Helpful tools

  • You will need an XML editor program for more easily making edits to an XML file. An example of a free open source editor is Komodo Edit.
  • Most Windows versions do not provide a thumbnail view for tga files (an essential feature while editing the skin files). Thumb Plug TGA is a free open source tga thumbnail plugin that will provide this functionality.
  • OpenSim is a free and open source version of the SL Simulator that you can run yourself. Next to your xml editor and imaging program, this will be your most important tool while skinning the viewer. Linden grid logins can be slow, or disabled, and are inconvenient for testing things like a one line edit of an XML file. Logins on a simulator running on your local machine are significantly faster than logins sent over the Internet, thus providing a quick and easy testbed for edits you've made to your viewer skin.

Its usefulness cannot be stressed enough when dealing with xml files that need a relog (such as colors.xml).

Useful menu items

  • Advanced > UI > Show Name Tooltops

Shows the XML file name or UI path of whatever element your mouse is hovering over.

  • Advanced > XUI > Edit UI...

A barest of bones xml file editor. Useful for testing spacing and layout for portions of the UI without relogging.

Creating new skins

New skins have already been created -- see the page Skinning - Post Your Skins Here.

For a full list of tutorials -- see the Skinning_HowTo/Basics#See_Also section.

If you would like to add tutorials with more than Basic information, you might choose to name your page along similar lines:

  • Skinning HowTo/Resize the toolbar
  • Skinning HowTo/Changing a highlighting effect
  • etc

Skins folder

The skins folder is \SecondLife\skins\[SKIN]\

Note: colors.xml and colors_base.xml are now associated with specific viewer skins. Each skin folder has its own copy of colors.xml and colors_base.xml

colors_base.xml

This file defines the basic colors of the UI as separately named nodes.

WARNING: It is highly advisable that you do NOT MAKE CHANGES to this file. Instead, copy & paste entries from this file to the next file (colors.xml) -- which overrides settings in colors_base.xml. The viewer will crash if any requisite entry is missing or malformed in colors_base.xml!

colors.xml

By default, this file has no entries. However this file can contains entries which will override any identically-named entry in colors_base.xml.

The format for specifying a color is

value="[R],[G],[B],[OPACITY]"

...where R,G,B,Opacity are in the range 0-255. For opacity, 128 is half opacity (ergo, half transparent).

Note: Opacity is also sometimes called the Alpha value.

For example, you could copy the following entries from colors_base.xml and paste them into colors.xml, where you can make adjustments:

<xml> <ChatHistoryBgColor value="0, 30, 80, 200" /> <ChatHistoryTextColor value="255, 255, 255, 255" /> <IMHistoryBgColor value="0, 30, 80, 128" /> <IMHistoryTextColor value="255, 255, 255, 255" /></xml>

For ease of use, there is also a fully commented colors.xml file on the wiki that labels each setting.

Textures folder

The \SecondLife\skins\[SKIN]\textures\ folder contains the Viewer's installed textures. This folder contains these subfolders:

  • bottomtray
  • build
  • containers
  • icons
  • navbar
  • quick_tips
  • taskpanel
  • widgets
  • windows
  • world

Textures file

The file textures.xml contains metadata about how to load, display, and scale textures for rendering in the UI. Images do *NOT* have to appear in this file in order to use them as textures in the UI. Simply refer to them by filename (relative to textures directory).

NOTE: if you want to reuse an image file with different metadata, simply create a new texture entry with the same filename but different name

Here is an example of some simple entries in textures.xml. They have no stretch rectangle defined, not preloaded, are not referenced by UUID: <xml> <icon_auction.tga/>

 <icon_avatar_offline.tga/>
 <icon_avatar_online.tga/>
 <icon_day_cycle.tga/>
 <icon_diurnal.tga/>
 <icon_event.tga/>
 <icon_event_mature.tga/>
 <icon_for_sale.tga/>
 <icon_group.tga/>
 <icon_groupnotice.tga/>
 <icon_groupnoticeinventory.tga/>
 <icon_lock.tga/>
 <icon_place.tga/>
 <icon_popular.tga/>
 <icon_top_pick.tga/></xml>

Scaling rectangles

UI art textures are often stretched (scaled) in various resizing to accommodate different widths or heights of the same widget. In order to preserve a crisp look of edges, part of the image is 'preserved' or protected to not be scaled. By default, the stretching will preserve 8 pixels on all sides of the image.

To change this default, set the <scale_rect /> element. <xml><scale_rect left="x1" top="y1" right="x2" bottom="y2" /></xml>

The pixel coordinates of the image here are counted from a (0,0) position that refers to the LEFT BOTTOM corner. (Like a Cartesian coordinate system in quadrant I.)

For example, this image toolbar_btn_selected.tga has dimensions of 128 pixels width x 24 pixels height: Toolbar btn selected.tga.jpg.

The following <scale_rect /> code defines a stretchable rectangle that preserves 26 pixels to its left and right:

<xml> <toolbar_btn_selected.tga>

       <scale_rect left="26" top="24" right="102" bottom="0" />
 </toolbar_btn_selected.tga></xml>

It results in a display that looks like this:

Toolbar btn selected rect example1.jpg

use_mips

TBD.

preload

Setting preload="true" means the texture is loaded at runtime, before the login screen appears. In general it is best to preload as few textures as possible, since this affects memory usage of the viewer.

Example:

<xml>

 <checkbox_disabled_false.tga preload="true" />

</xml>

XUI folder

XUI (pronounced zoo-e) stands for XML User Interface. XUI consists of a custom XML data format for describing Second Life's user interface, and the code which processes that data and integrates it with the Second Life viewer. The XUI folder is \SecondLife\skins\[SKIN]\xui\.

Language folders

When you select a language in the Viewer (Preferences > General > Language), then the files in the appropriate [lang] folder are loaded hierarchically on top of the en-us version, starting the next time the viewer is run. The language folder is \SecondLife\skins\[SKIN]\xui\[lang], where [lang] is the locale code, such as:

Tier one languages:

  • de - German
  • fr - French
  • ja - Japanese

Additional languages, for example:

  • es - Spanish
  • zh - Simplified Chinese - not officially supported nor updated regularly

If an element (or entire file) is missing in the [lang] version, then the Viewer falls back to the value specified in the en-us version.

The \[lang] version of floater or panel contains only the minimum values desired to override from the en-us version. Generally this includes only the matching name= property and the translated string/label=. However in some cases a separate per-language width may be specified, to adjust the size of a particular widget for that language only.

The en-us folder

This folder is where the size of floaters, panels, and widgets are defined, as well the text strings in English the Viewer uses.

IMPORTANT NOTE: Do not ever change any name= parameters from the existing (English) name. The name= parameter is used to identify each node as expected when called in the Viewer code, and to match it to other translations of the same node.

Localization

Skinning HowTo/XUI Text describes the XUI elements and attributes related to text strings. A further discussion of the English text strings and how these are manipulated to make translations can be found at How to Localize Your World.

Colors

For purposes of skinning, it is important to note that there are still 2 XML files at this time which specify a color from within the \en-us folder.

The file \skins\default\xui\en-us\floater_instant_message_ad_hoc.xml contains a <text_editor /> widget with a bg_readonly_color, bg_writeable_color, text_color, and text_readonly_color:

Widget named "im_history" <xml><text_editor type="string" length="1" bg_readonly_color="ChatHistoryBgColor" bg_writeable_color="ChatHistoryBgColor" bottom="-265" embedded_items="false" enabled="false" follows="left|top|right|bottom" font="SansSerif" height="239" left="5" max_length="2147483647" mouse_opaque="true" name="im_history" text_color="ChatHistoryTextColor" text_readonly_color="ChatHistoryTextColor" width="490" word_wrap="true" /></xml>

These four values could be set as either a named entry in colors.xml (bg_readonly_color="ChatHistoryBgColor") or directly as an R,G,B,O value (bg_readonly_color="50, 115, 185, 150")

    • Note: you can set a text color to any such <text_editor /> widget in the XML using the text_color= parameter.

The file \skins\default\xui\en-us\floater_chat_history.xml contains a couple <text_editor /> widget with a bg_readonly_color, bg_writeable_color, text_color, and text_readonly_color:

Example: Widget named "Chat History Editor"

<xml><text_editor type="string" length="1" bottom="28" embedded_items="false" enabled="false" follows="left|top|right|bottom" font="SansSerif" height="74" left="5" max_length="2147483647" mouse_opaque="true" name="Chat History Editor" text_color="ChatHistoryTextColor" text_readonly_color="ChatHistoryTextColor" width="299" bg_readonly_color="ChatHistoryBgColor" bg_writeable_color="ChatHistoryBgColor" word_wrap="true" /></xml>

Example: widget named "Chat History Editor with mute"

<xml><text_editor type="string" length="1" bottom="28" embedded_items="false" enabled="false" follows="left|top|right|bottom" font="SansSerif" height="74" left="5" max_length="2147483647" mouse_opaque="true" name="Chat History Editor with mute" text_color="ChatHistoryTextColor" text_readonly_color="ChatHistoryTextColor" width="300" word_wrap="true" bg_readonly_color="ChatHistoryBgColor" bg_writeable_color="ChatHistoryBgColor"/></xml>

Size and positioning

Xui-coordinate-system.png

XUI uses a top-left based coordinate system. The top-left corner of the floater or panel is (0,0) as shown in the figure at right.

Second Life XUI files by convention prefer the order LEFT TOP WIDTH HEIGHT, for example:

rect.left="20" rect.top="40" 
rect.width="50" rect.height="20"

You may also specify LEFT TOP RIGHT BOTTOM, for example:

rect.left="20" rect.top="40" 
rect.right="70" rect.bottom="60"

The corresponding XML entry in textures.xml would be:

<xml><texture name="TextField_Off"

        file_name="widgets/TextField_Off.png" 
        preload="true" 
        scale.left="4" 
        scale.top="18" 
        scale.right="252" 
        scale.bottom="4" /></xml>

NOTE: preload="true" means that this texture will be ready for use before logging in. When no preload is set, the default is false.

Size

You must specify enough information for the XUI layout system to compute a width and height for each widget. The best way to do this is to explicitly specify a width and height. However, you may also specify a left and right edge rather than width, or a top and bottom edge rather than height. This also works with relative positioning, such as left_pad or top_pad.

Z-order

Z-order refers to which parts of the UI are displayed "in front" (overlaying) of others. By default, the z-order in the Viewer is:

  1. Modal dialogs.
  2. Notifications – these may be interactive when there's a modal dialog up.
  3. Bottom tray pop-up windows (IMs, voice panel, etc.) These pop-up over other floaters until they're torn off, at which point they behave like other floaters.
  4. Navbar/Bottom tray.
  5. Floaters/Task Panel – the task panel will behave like a docked floater in that it will pop to the top of the floater stack when it has focus, but other floaters like search can be placed on top of the Task Panel if they get focus.

See also

Other tutorials

Outdated tutorials

Helpful Resources

Resident Created Skins

See Skinning - Post Your Skins Here.