Getting Started

Read these lines after having successfully installed the ThemeEngine library.

After the installation of the ThemeEngine you will see a new THEMEENGINE tab on the components panel. Its typical view is shown below. All the library components are marked with the "TE" badge.

The first thing you should do to give a new interface appearance to your application is to add add the TTeThemeEngine component on the form. This component provides centralized operating mode of downloading, updating and switching-over of the themes.

If you plan to update already existing project you can use the ThemeEngine converter, just click twice on the component TTeThemeEngine and follow the master's instructions.

Then you can choose an active theme with the help of the TTeThemeEngine component. For this purpose use the ThemeFile, ThemeBuild, ThemeList and ThemeIndex properties. After the active theme is chosen, the application at start will load this theme.

If you want your application forms to have new interface appearance, put the TTeForm component on the form. This component should be added to each form which you want to modify. The TTeForm contains a number of properties which duplicate the properties of the standard form and the number of additional properties. They should be used to avoid a conflict situation. For example, in order to change the headline of the form it would be more correct to use the TTeForm.Caption property instead of the standard form Caption property.

To provide a new style to the control elements you should use only the components which support our library. All these components are equivalent to the standard ones, besides they are able to paint themselves with the use of the themes and are able to react to ThemeEngine events. Besides, more and more additional products supporting ThemeEngine developed both by us as well as other developers appear day by day. But in case no worthy analogues of the components necessary for you have been found, you should use the TTeAdapter component which allows you to adapt the component not supporting the ThemeEngine one.

In order to change the theme in the performance mode it is better to use TTeThemeSwitcher component, it allows to change the active theme easily and quickly, by the drop-down list. Besides, in order to change the active theme you can use the TTeThemeEngine component by changing its properties. Otherwise, you can use the global LoadThemeFromFile, ChangeTheme, etc. procedures.

If you have your own components and you want them to use ThemeEngine or you want to improve the components of other developers read the section about other components.

Available themes

ThemeEngine allows you to use the following kinds of themes: The built-in themes

The built-in themes, such as "OfficeXP", "Flat". These themes are written in ObjectPascal and they increase the size of the application less than 10 kb. Therefore these themes are included into all applications. ThemeEngine Themes

ThemeEngine themes (usually located in the themes catalogue). ThemeEngine supports its own theme format and ThemeEditor tool for creating of the new or updating the ready ones. Microsoft Visual Styles Themes

ThemeEngine allows you to use visual styles developed for operational system Windows XP (msstyles files) in your applications. Now thousands of visual styles which you can easily use without any modifying, are freely available. For example, you can find about one thousand of various themes on the themexp.org site.

Using TTeTheme

Generally the themes is a set of properties and methods with the help of which it is possible to find out the necessary parameters (such as fonts, colors and metrics), and to paint the components of the interface.

ThemeEngine has an abstract base TTeTheme class, which contains all the necessary properties and methods for the correct use of the theme. In other words the programmer does not have to know which theme is active at the current moment, how to load, to change and at last how to paint different themes. ThemeEngine closes the details of realization of concrete themes, such as ThemeEngine themes, msstyles themes, the built-in themes. In other words it is impossible to find out directly what elements the theme consists of, in what format it is saved. The interaction process occurs via the TTeTheme base class.

The global variable CurrentTheme points to the theme active at the current moment. Before using this variable it is necessary to make sure, whether it is possible to use it calling the special IsThemeAvailable(CurrentTheme) function. If this function returns true the active theme is available.

Using te_uxtheme

ThemeEngine emulates a well-described and understandable MS Theme API (uxtheme.dll) interface. If your application or components use MS Theme API for the correct display in Windows XP they can easily get ThemeEngine support, it is only necessary to add te_uxtheme in the module and then if the active theme is ThemeEngine, yours applications and the component will use it. Otherwise if the program is started in Windows XP and the visual styles are active, the uxtheme.dll library will be involved. The detailed MS Theme API documentation can be received here.

ThemeEngine messages

ThemeEngine provides one message for interaction of various components and the cursor itself. Each component which uses the themes is to process this message in order to display itself correctly and to change the necessary parameters and repaint at changing of the active theme. For your component to be able to receive ThemeEngine messages you are to register its AddThemeNotification procedure which is being used. The registration is usually made in the designer. It is necessary to call the RemoveThemeNotification procedure before the destruction of the component (usually in the destructor). SNM_THEMEMESSAGE

lParam is not used in the current version, wParam has one of the following values:

• SMP_CHANGETHEME - the current theme has changed
• SMP_BEFORECHANGE - is sent before changing the current theme
• SMP_AFTERCHANGE - is sent after changing the current theme
• SMP_APPLYTHEME - is sent when the theme is active, and application was in the non-theme mode.
• SMP_REMOVETHEME - is sent when the active theme is deleted and the application is switched off to the non-theme mode.
• SMP_REPAINT - is sent if it is necessary to repaint all the components, for example, by calling RepaintThemedControls