NAME

Win32::VisualStyles - Apply Win32 Visual (aka XP) Styles to windows

SYNOPSIS

  use Win32::VisualStyles;   # enable visual styles

  # Turn on visual styles from the command line
  C:\> perl -MWin32::VisualStyles script.pl

  my $styles = Win32::VisualStyles::GetThemeAppProperties();
  Win32::VisualStyles::SetThemeAppProperties($styles);

  use Win32::VisualStyles qw(IsThemeActive IsAppThemed);
  my $global_styles_enabled = IsThemeActive();
  my $app_styles_enabled    = IsAppThemed();

  use Win32::VisualStyles qw(GetThemeAppProperties :use_default_context);
    # Get access to GetThemeAppProperties() without changing the
    # activation context

  if( Win32::VisualStyles::control_styles_active() ) {
    # Do something if styles are active for this app.
  }

DESCRIPTION

This module modifies the run-time environment (the "activation context") of a Win32 process to control Visual Styles (aka XP Styles).

Visual Styles are the new graphical designs used for user interface components starting from Windows XP. You may also hear them refered to using the informal term 'v6 manifest'. They are implemented by v6 of Comctl32.dll.

By default this module enables visual styles for all graphical components that support them, and that are created after the module is loaded. There may well be side effects on graphical components created before this module is loaded, so it is recommended to load this module as early in your program as possible. It is possible to override this default behaviour by passing the :use_default_context tag on the import line - this allows you to load the module without enabling visual styles.

Note that the effect is global, and so this module should not be used by module authors themselves.

On Operating systems that do not support Visual Styles (i.e. before Windows XP) this module should have no effect, so it is safe to call unconditionally from your script - although if you expect you script to be run on multiple platforms you should check that it looks correct on each target platform.

In cases where different code needs to be run when Styles are active then you can call the Win32::VisualStyles::control_styles_active() function which will return a true value when visual styles are actually in use.

EXPORTS

By default this module exports nothing into the calling namespace. On request the following symbols may be exported:

GetThemeAppProperties

SetThemeAppProperties

IsAppThemed

IsThemeActive

STAP_ALLOW_NONCLIENT

STAP_ALLOW_CONTROLS

STAP_ALLOW_WEBCONTENT

control_styles_active

The following tags may be used as shortcuts on the import line:

:all

Imports all functions and constants listed above.

:functions

Imports all the functions: GetThemeAppProperties, SetThemeAppProperties, IsAppThemed, IsThemeActive, control_styles_active.

:constants

Imports all the constants: STAP_ALLOW_NONCLIENT, STAP_ALLOW_CONTROLS, STAP_ALLOW_WEBCONTENT.

:use_default_context

This pseudo-tag, when passed on the import line prevents this module from altering the activation context. Use this when you just want assess to the functions provided without forcing visual styles to be enabled. Whether visual styles are actually enabled or not will depend on the build and environment of the perl you are using.

AVAILABLE FUNCTIONS

GetThemeAppProperties

  my $styles = GetThemeAppProperties();

Returns a bitmask with bits set to indicate whether themes are currently being applied to various regions of the application. Note that the returned bitmask may not reflect reality in the case that visual styles are disabled by the operating system and SetThemeAppProperties() has been called.

$styles & STAP_ALLOW_NONCLIENT

If true, themes are active for non-client (frame) areas of windows.

$styles & STAP_ALLOW_CONTROLS

If true, themes are active for controls (buttons etc.) within the client areas of windows.

$styles & STAP_ALLOW_WEBCONTENT

If true, themes are active for controls (buttons etc.) within html (hosted MSHTML/Internet Explorer) windows.

SetThemeAppProperties

  SetThemeAppProperties(STAP_ALLOW_NONCLIENT |
                        STAP_ALLOW_CONTROLS  |
                        STAP_ALLOW_WEBCONTENT);

Sets a mask of bits enabling/disabling themes in various parts of the window. This call will have no effect on operating systems that don't support themes, or when the OS has disabled themes for the application. Note that in the latter case this call will affect the return value from GetThemeAppProperties().

Bitmask bits are as for GetThemeAppProperties.

IsThemeActive

  my $themes_globally_enable = IsThemeActive()

Returns a boolean value indicating whether the OS has globally disabled/enabled visual styles. The return value may be controlled by the computer user through visual style settings in the control panel. If true it does not give any indication whether the application is actually making use of themed content or not.

IsAppThemed

  my $themed = IsAppThemed();

Returns a boolean value indicating whether the OS has disabled/enabled visual styles for the application. The return value may be controlled by the computer user within the compatibility tab of the application's properties - at least on Vista).

control_styles_active

  if(control_styles_active()) {
    ...
  }

Returns a boolean value that indicates whether styles are actually active in the client area of the window. Combines the results from IsThemeActive(), IsAppThemed(), GetThemeAppProperties() & STAP_ALLOW_CONTROLS, and investigates whether the current activation context is actually capable of supporting themes.

SEE ALSO

MSDN http://msdn.microsoft.com for more information on activation contexts and manifests, and for detailed descriptions of the Win32 API calls GetThemeAppProperties(), SetThemeAppProperties(), IsThemeActive(), IsAppThemed().

SUPPORT

Contact the author for support.

AUTHORS

Robert May (robertmay@cpan.org)

COPYRIGHT AND LICENSE

Copyright (C) 2009 by Robert May

This library is free software; you can redistribute it and/or modify it under the same terms as Perl itself.

cpanm Win32::VisualStyles

perl -MCPAN -e shell
install Win32::VisualStyles