|
|
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 ideaof the parts/states but for up-to-date information, pleaserefer 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 (*)
|
