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.