windows-nt/Source/XPSP1/NT/shell/themes/themedir/themes.txt

542 lines
19 KiB
Plaintext
Raw Permalink Normal View History

2020-09-26 03:20:57 -05:00
Windows Themes .INI Files - 05/10/00
------------------------------------
1. A theme .ini file is a standard Windows .ini file. All text is compared
case-insensitive. The File can be created in either ANSI or UNICODE
character sets.
2. Types and names of theme files
- there are 2 types of theme .ini files:
- themes.ini - specifies available color schemes and sizes for a theme
- classdata file - contains theme data for specific size/color
3. primitive property values
- below is the list of primitive property types and their associated
value format
- when values have multiple parts, the parts can be separated by
optional commas
- value parts must be listed in the order described unless the optional
partnames are used (format: partname:value)
4. primitive property types (10):
- string (any text to right of "='; no quotes)
- int (signed integer or hex number)
- bool (one of the values: "true" or "false")
- color (comma-sep. list of 3 numbers. partnames: "r", "g", "b")
- enum (a string value that gets matched to a declared enum)
- margins (a comma-sep. list of 4 int's. partnames: "lw", "rw", "th", "bh"
note: these can be negative & control spacing of odd-shaped images)
- filename (a relative path that gets fully qualified; currently cannot contain
spaces or quotes; filenames are relative to the theme's directory)
- size (an integer followed by optional "twips", "pixels", or "points")
(the default size units is "pixels")
- position (a comma-sep. list of 2 int's. partnames: "x", "y".
interpreted as pixels)
- rect (a comma-sep. list of 4 int's. partnames: "l", "t", "r", "b")
- font (familyname, size, fontflags. familyname can contain spaces)
ex: arial, 10 (the default font units is "points")
ex: ms san serif, 18 pixels, bold italic
5. there are a number of predefined enums and property names (based on primitive types);
refer to the file "TmSchema.h" for a current and complete list
6. all theme files consists of 1 or more sections. each section contains
1 or more property-setting lines of the form:
<name> "=" <value>
7. <property names>
- for the "<name> = "<value>" lines within the any section except the [documentation] section,
<name> is required to be a primative name, a predefined enum name, or a predefined type.
- examples:
- ImageFile
- SizingMargins
- myPredefinedStringName
- this hard "typing" of property names gives us some parsing services at file load time
and helps standardize the name of recurring properties.
- a list of which property names apply to each drawing routine can be found in Appendix B.
8. Sections allowed in "themes.ini" files:
- [documentation] section
- [Size.xxx] sections
- [ColorScheme.xxx] sections
- [File.xxx] sections
- the "documentation" section is optional
- at least one occurance of each of the "size", "ColorScheme", and "file"
sections are required
9. [documentation] section:
- any property name can go here; unrecognized property names are ignored without generating
errors
- all properties in the [documentation] section are interpreted as string properties
- certain properties in this section are recognized and used by the theme selection UI. these
properties are also written to a string table in the packed theme file, for localization
access. the recognized properties are:
- DisplayName
- ToolTip
- Author
- Company
- Copyright
- URL
- Version
- Description
10. [ColorScheme.xxx] section:
- the "xxx" should be replaced the simple color scheme name (no spaces)
- the first [ColorScheme.xxx] section in the "themes.ini" file is the
default Color Scheme (for UI selection)
- the property names recognized in a [ColorScheme.xxx] section are:
- DisplayName (UI name for this color scheme choice)
- ToolTip (tooltip text for this color scheme choice)
- FromColor1 (thru FromColor5)
- ToColor1 (thru ToColor5)
- FromHue1 (thru FromHue5)
- ToHue1 (thru ToHue5)
- each color scheme is a set of transformations on the explicit
color values and the colors contained in each image of associated
classdata files
- For example, the following sections specifies 3 color schemes:
[ColorScheme.Bright]
DisplayName "Bright Colors"
FromColor1 = 128 0 0
ToColor1 = 255 0 0
[ColorScheme.Dark]
DisplayName = "Dark Colors"
FromColor1 = 128 0 0
ToColor1 = 25 0 0
[ColorScheme.Random]
DisplayName = "Wierd, Random Colors"
Tooltip = "Caution: this is a dev-authored color scheme"
FromColor1 = 128 0 0
ToColor1 = 255 3 32
- an empty set of transformations can be used to name the normal, untransformed color
scheme. this could be used by a file for its default color scheme or a file that
doesn't support color scheme transformations (where each color scheme is implemented
as a separate classdata file). Examples:
[ColorScheme.Default]
DisplayName = "Default"
[ColorScheme.RedDesign]
DisplayName = "Fall Reds"
11. [Size.xxx] section:
- the "xxx" should be replaced the simple size name (no spaces)
- the first [Size.xxx] section in the "themes.ini" file is the
default Size (for UI selection)
- the property names recognized in a [Size.xxx] section are:
- DisplayName
- ToolTip
- the "DisplayName" property will be the name of the size in the UI to select a theme
- the "ToolTip" property specifies the tooltip text to be used in the theme
selection UI for this size
- For example, the following sections specifies 3 sizes:
[Sizes.Default]
DisplayName = "Default"
[Sizes.Small]
DisplayName = "Very Small"
Tooltip = "Choose this if you like to squint"
[Sizes.Large]
DisplayName = "Very Large"
12. [File.xxx] section:
- the "xxx" should be replaced a simple, unique name for the classdata file (no spaces)
- the propertes recognized in this section are:
- Filename (to name the classdata file)
- ColorSchemes (to specify the list of color schemes
that the file supports)
- Sizes (to specify the sizes that the file supports)
- Examples:
[File.One]
Filename = large.ini
ColorSchemes = default, red, green, blue
Sizes = Large
[File.Two]
Filename = smallred.ini
ColorSchemes = red
Sizes = Small
- the "ColorSchemes" property must specify a comma separated list of previously
declared simple color scheme names (from [ColorScheme.xxx] sections)
- the "Sizes" property must specify a comma separated list of previously
declared simple size names (from [Size.xxx] sections)
- the lists can be continued on multiple lines by starting the continued line
with an equals sign ("=")
- each unique color/size combination can only be associated with one file
13. Sections allowed in "classdata" files:
- [globals] section
- [sysmetrics] section
- class sections
- all sections are optional
- multiple class sections allowed
- if used, the [globals] section must be the first section
- if used, the [sysmetrics] section must appear before any class sections
14. [globals] section:
- the globals section is a list of <property name> settings that are inherited by each parent class
section. the class section can overwrite any of the properties set in the global section. At runtime,
a control can use the "GetPropertyOrigin()" to determine if the property is specified locally,
in the parent node, globally, or not at all.
- the "CharSet" property, which specifies the numeric character set for all fonts in the
classdata file, has the following special rules:
- can only appear in the [globals] section
- must appear before the first "Font" property setting
15. [sysmetrics] section:
- this section allows a theme author to set the system metrics when the theme is loaded
so that the look of non-themed applications can be made to more closely match the look
of the theme.
- for this section, the "appname::" option is not allowed
- for this section, the ".partid" option is not allowed
- the supported system metrics are:
- system colors
Scrollbar, Background, ActiveCaption, InactiveCaption, Menu
Window, WindowFrame, MenuText, WindowText, CaptionText
ActiveBorder, InactiveBorder, AppWorkSpace, Highlight, HighlightText
BtnFace, BtnShadow, GrayText, BtnText, InactiveCaptionText
BtnHighlight, DkShadow3d, Light3d, InfoText, InfoBk, ButtonAlternateFace, HotTracking
GradientActiveCaption, GradientInactiveCaption, MenuBar, MenuHilight
- system fonts
CaptionFont, SmallCaptionFont, MenuFont, StatusFont, MsgBoxFont
IconTitleFont
- system sizes
BorderWidth, ScrollBarWidth, ScrollBarHeight, CaptionBarWidth, CaptionBarHeight
SmCaptionBarWidth, SmCaptionBarHeight, MenuBarWidth, MenuBarHeight
- system booleans
FlatMenus, DropShadows, MouseVanish, CursorShadow
TooltipFade, TooltipAnimation, SelectionFade
- system strings
CssName, XmlName
- only the above property names are allowed in this section
- if any values of any of the above system metrics are not specifed, they
default to the system setting for the "Windows Standard" scheme.
16. class sections:
- the section name for class sections is consists of 1-4 names, as shown below. Each
name can contain 1 or more the following chars: letters, numbers, "-", and "_").
a. (optional) group name followed by a "::"
(the "group name" is the base name of an application for the OpenThemeData() API
but can also be any logical grouping name when passed by the SetWindowTheme() API).
b. the windows classname or user-created name
c. (optional) a "." followed by a child part name. Note: the child
part name must be defined as a part name for its class in the "TmSchema.h" file
d. (optional) a state named enclosed in parenthesis. Note: the
state name must be defined as a state name for its part int the
"TmSchema.h" file
- examples:
[button] // simple class name
[button-OK] // specialized class name
[explorer::button] // only applies to buttons in "explorer"
[button.pushbutton] // a part of button called "pushbutton"
[button.pushbutton(up)] // the "up" state of pushbuton
[button(disabled)] // the "disabled" state of button
- there are some special predeclared names that are not registered class names but are recognized
by the theme code as appropriate:
- dialog (for dialog frame/backgrounds)
- menu (for uxcontrol menus)
- desktop (for desktop wallpaper)
- nonclient (for captioned window frames)
- child sections inherit from their parent section of the same name. at runtime,
each API for the theme drawing & information take a PartId (int) to select the parent
or child section.
- state sections inherit from their parent class or part section of the same name.
at runtime, each API for theme drawing & information take a PartId (int) to
select the state of the part or class.
- these state, part, and parent class sections contain, together with the
inherited "globals" section, all of the properties values needed to draw
the specified window class (see section 7 on <property names>).
- a list of the standard controls/windows, along with which drawing services they
use, can be found in Appendix C.
17. applications that don't want to apply the current Theme
- applications that want to have no theme-effects on their controls or who want to specify another
theme will have put this info into the registry under the "ThemeManager" key. More details to follow on
this.
APPENDIX A: Theme Drawing Routines and their Associated Properties:
DrawBackground:
- BgType = ImageFile
- ImageFile
- SizingMode (enum: TrueSize, Stretch, Tile, TileHorz, TileVert, TileCenter, SystemSize, SystemPos)
- SizingMargins
- ContentMargins
- ImageCount
- BorderOnly (bool)
- Transparent (bool)
- TransparentColor
- BgFill (bool)
- FillColor (used when drawing TRUESIZE imsages with BgFill is TRUE )
- BgType = BorderFill
- BorderType (enum: Rect, RoundRect, Ellipse)
- BorderColor
- BorderSize
- RoundCornerWidth (int as percentage; only for RoundRect)
- RoundCornerHeight (int as percentage; only for RoundRect)
- FillType (enum: Solid, VertGradient, HorzGradient, RadialGradient, TileImage)
- FillColor (for Solid)
- GradientColor1 - GradientColor5 (for gradient filltypes)
- GradientRatio1 - GradientRatio5 (for gradient filltypes)
- ImageFile (for TileImage)
- BgType = NtlFile (not yet implemented)
- NtlFile
- ImageFile (for TileImage)
- ContentMargins
DrawText:
- Font
- TextColor
- ContentAlignment
- TextShadowOffset
- TextShadowColor
- TextShadowType
- TextBorderColor
- TextBorderSize
"NonFrame" Drawing:
- AutoSize (bool)
- Offset (x,y)
- OffsetType
- CaptionMargins
Progress Drawing:
- ProgressChunkSize
- ProgressSpaceSize
APPENDIX B: Parts and States of the standard controls and windows:
The list below shows how the Ux Controls are broken down into
parts and states. This list is provided to give the reader an idea
of the parts/states but for up-to-date information, please
refer to the "TmSchema.h" file.
An asterisk (*) is shown by the parts that support text drawing.
All parts support background drawing.
"NonClient" Parts & States:
Frame = Active, Inactive, Disabled
Caption (*) = Active, Inactive, Disabled
HorzScroll = Normal, Hot, Pushed, Disabled
HorzThumb = Normal, Hot, Pushed, Disabled
VertScroll = Normal, Hot, Pushed, Disabled
VertThumb = Normal, Hot, Pushed, Disabled
SysButton = Normal, Hot, Pushed, Disabled
MINButton = Normal, Hot, Pushed, Disabled
MAXButton = Normal, Hot, Pushed, Disabled
CloseButton = Normal, Hot, Pushed, Disabled
HorzScroll
HorzThumb
VertScroll
VertThumb
"Button" Parts & States:
PushButton (*) = Up, Pushed, Disabled, Hot, UpDefault
RadioButton (*) = Unchecked(1), Checked, UncheckedDown, CheckedDown
CheckBox (*) = Unchecked(1), Checked, UncheckedDown, CheckedDown
GroupBox (*)
UserButton
"Rebar" Parts & States:
Gripper
GripperVert
Band
"Toolbar" Parts:
Button (*)
DropDownButton
SplitButton
SplitButtonDropDown
Separator
SeparatorVert
"Toolbar" Common States:
Up, Pushed, Disabled, Hot, Checked
"Status" Parts:
Pane
Gripper
"Menu" Parts:
MenuItem (*)
MenuDropDown
MenuBarItem (*)
MenuBarDropDown
Chevron
Separator
"Menu" Common States:
Normal
Selected
Demoted
"ListView" Parts:
ListItem (*)
ListGroup (*)
ListDetail
ListSortedDetail
EmptyText
"ListView" Common States:
Normal
Hot
Selected
SelectedNotFocus
Disabled
"Header" Parts:
HeaderItem (*)
"Header" Common States:
Normal
Hot
Pushed
SortedUp
SortedDown
"Progress" Parts:
Bar
BarVert
Chunk
ChunkVert
"TabControl" Parts & States:
TabItem (*) = Normal, Disabled, Hot, Selected, Focused
TabItemLeftEdge = Normal, Disabled, Hot, Selected, Focused
TabItemRightEdge = Normal, Disabled, Hot, Selected, Focused
TabItemBothEdge = Normal, Disabled, Hot, Selected, Focused
TopTabItem (*) = Normal, Disabled, Hot, Selected, Focused
TopTabItemLeftEdge = Normal, Disabled, Hot, Selected, Focused
TopTabItemRightEdge = Normal, Disabled, Hot, Selected, Focused
TopTabItemBothEdge = Normal, Disabled, Hot, Selected, Focused
Pane
"Trackbar" Parts & States:
Trackbar = Normal
Track = Normal
TrackVert = Normal
Thumb = Normal, Hover, Pressed, Focused
ThumbTop = Normal, Hover, Pressed, Focused
ThumbBottom = Normal, Hover, Pressed, Focused
ThumbVert = Normal, Hover, Pressed, Focused
ThumbLeft = Normal, Hover, Pressed, Focused
ThumbRight = Normal, Hover, Pressed, Focused
Tics = Normal
TicsVert = Normal
"ToolTip" Parts:
Standard (*)
StandardTitle (*)
Balloon (*)
BalloonTitle (*)