542 lines
19 KiB
Plaintext
542 lines
19 KiB
Plaintext
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 (*)
|
|
|
|
|