Now let’s have a look at the Desktop Window Manager (DWM) API. The DWM is responsible for the composition of windows on the desktop and the DWM API allows developers to control how composition affects a particular window. As you will see, the DWM is responsible for much more than just “glass”.

When it comes to graphics, the terms can be confusing. Before working with transparency and translucency in Windows we should clarify some of them.

Terminology

Transparency – Refers to the ability to see through something clearly and without obstruction. Think of it as clear glass. Some applications and APIs use the term transparency to refer to a scale that ranges from “completely” transparent to “completely” opaque.

Translucency – People often use translucency and transparency interchangeably but they actually mean very different things. Translucency refers to the ability to see through something where the background appears unclear whether it is out-of-focus or simply blurry in some way. Windows Vista refers to the glass effect as “transparent glass” when it technically should be called translucent glass.

Opacity – Opacity refers to the state of being opaque and opaque refers to something that is neither transparent nor translucent. Some applications and APIs use the term opacity to refer to a scale that ranges from completely opaque to completely transparent.

Alpha Channel – An alpha channel provides additional information for each pixel in an image that facilitates compositing images together.

Window Regions – A window’s region determines the area within the window where system permits painting. Although Windows 95 supported window regions, it was not until Windows XP that the default theme used regions to present windows with rounded corners. Although the default Windows Vista theme also presents windows with rounded corners, regions are no longer used unless you resort to the Windows Vista Basic theme.

Glass – Glass is the catchy marketing terms that Windows Vista uses to refer to translucency.

Blur – Some of the DWM APIs refer to blur and again this indicates translucency. Presumably, the Windows developers felt it was easier to spell and comprehend.

Desktop Composition – The DWM performs desktop composition, enabling visual effects on the desktop such as glass, 3D window transitions, etc.

RGB – RGB is short for Red, Green and Blue. RGB values are typically packed into a COLORREF (which is just a Cardinal) as follows: $00BBGGRR. As you can see, the first byte is always zero and the remaining three bytes store the individual red, green and blue values in reverse order. Each color value ranges from zero through 255. If all three values are zero then the result is black. If all three values are 255 then the result is white. For example, to represent red specify $000000FF. As you can see, RGB does not provide an alpha channel.

ARGB – ARGB is short for Alpha, Red, Green and Blue. ARGB values are typically packed into an ARGB (which is just a Cardinal) as follows: $AARRGGBB. The first byte stores the alpha value and the remaining three bytes store the red, green and blue values. Note that the color values are stored in the opposite order to RGB.

GDI – The Windows Graphics Device Interface (GDI) API is the original graphics interface used for 2D drawing in Windows. With the exception of a few newer functions, the GDI API does not honor the alpha channel in images. GDI uses RGB values to represent color. The GDI API is wrapped in our beloved Graphics unit.

GDI+ – GDI+ was introduced with Windows XP (and Windows Server 2003) to provide a more capable programming model for 2D drawing, imaging and typography and fully supports alpha blending. GDI+ uses ARGB values to represent color. Although it is not necessary to have GDI+ support in Delphi it is a nice feature and you will need it for drawing black lines and text on “glass” windows. Why is that? You will see. You can obtain the units for GDI+ at http://www.progdigy.com/modules.php?name=gdiplus

Now for some code

If you do not want to read the following stuff you may want to look at the example project at: http://theunknownones.googlecode.com/svn/Libraries/DWMHelper/

The first thing you’ll need is to put the following units in your uses clause

JwaDwmApi,
JwaUxTheme

The most important one of them is the first one since it wraps up all the DWM API has to offer. Let us now look how to achieve things. Don’t be afraid of looking into JwaDwmApi.pas. It looks much more complicated than it is. As always Microsoft developers seem to love passing records to their functions. I don’t love that all to much so I wrote some helper functions to make live easier. Those can also be found in TUO’s SVN http://theunknownones.googlecode.com/svn/Libraries/DWMHelper/

The simplest thing to do is to blur the background behind a window:

You can call the function this way:

Now your window looks like this, easy isn’t it`?

HELP!!! My Window is opaque and/or white!!! What did I do wrong?
There can be different reasons for that

1. You do not have Windows Vista installed. (Ok this sounds stupid… but I really got that issue with some newbies)
2. You only have Vista Home Personal installed or the Destkop Window Manager Service is switched off. (Translucent Windows are only supported under Aero)
3. Your Form1.Color is different from clBlack=$00000000 (WHY THAT? Calm down I’ll explain)

Why it works with black windows only

As we have learned in the terminology section Delphi and Windows Vista use different color values (RGB vs. ARGB, remember?) Now Delphi draws only RGB colors with the help of GDI routines. Windows however expects ARGB values and assumes to receive one. So the color Windows assumes to be the right one is in most cases the wrong one, due to different byte order and missing alpha value.

How can we pass a valid value to Windows? As we want to receive a translucent window the color we should set to the window is transparent. The ARGB value for transparent is $00000000. Which color could we take in RGB to represent transparent? Right: BLACK. This is a major drawback for us. Most of the labels, buttons and edits etc. use black as their default foreground color. Now They all will become transparent. You may have or will read various attempts using SetLayeredWindowAttributes in order to change the transparent color but it seems this worked with some preview releases of Vista only.

How can you draw something black, transparent etc. on the window? Use GDI+…

More Glass

The vigilant reader may have observed that DWM_EnableBlurBehind takes a region as parameter. With this parameter you can pass a more or less complicated region to the DWM to tell it where do draw translucent. Try the following:

And voilà

Making the Frame thicker

In order to control the drawing of the blurred window frame you gotta consider another function called DwmExtendFrameIntoClientArea. Because of my lazyness I introduces a little helper:

Calling it this way

Leads to that result:

I don’t want a Frame at all

Sometimes this effect is referred to as “Sheet Of Glass” I don’t know how Microsoft developers call it since they ‘abuse’ one of their own functions to reach that effect. I personally would have introduced a distinct function for that. But it shows that people at Microsoft put on their pants one leg at a time as well.

Now you sould see something like that:

Conclusion

There isn’t really more magic behind it than that. Of course this is a very raw approach. For example the effect will collapse as soon as the screensaver switched on and back off. One could call the DWM_* routines in CreateWindowHandle for example.

1. Elevate the application from the beginning
2. Elevate special parts of your application

Both ways needs a manifest to be included into your application.

1. Elevate the application from the beginning

The easiest way to elevate an application is to tell Windows to do it for you. This is done by applying a manifest.

A manifest is a text resource that tells Windows what needs to be prepared before your application starts. This includes theme support and privileges your application needs. Developers maybe know it from Windows XP where it enables themed window controls.

Telling Windows to start your application as an administrator is done by using “requireAdministrator” as required security level in the manifest. However the code below is just an excerpt. You can get a full version of the manifest with a warning.

If you are going to use this manifest in your application, you have to consider that your application needs to be elevated all the time. Thus users without administrator access cannot launch your application at all.

However there is a second way which does not need a manifest at all. Some applications do start their own process with elevated rights. They start a second instance, close the actual one and go on elevated.
Examples are :

• the Taskmanager can elevate itself by clicking “Show processes from all users”
  
• ProcessExplorer
  

JWSCL contains a unit called JwsclElevation which provides the necessary functions to allow this simple elevation.

function JwShellExecute(const hWnd: HWND; FileName, Parameters,
Directory: TJwString; ShowCmd: Integer): HINST;
This function just works like the usual ShellExecute but let’s you elevate any program or your application. The return value In the following way you can start the command line prompt with elevated privileges.

The developer version (revision > 317) does have some more extension, less bugs and a different behavior.

Let me list the differences :

• JwShellExecute raises EJwsclWinCallFailedException when the call to ShellExecuteEx fails.
• The new optional parameter Flags controls some aspects
  • sefNoUi does not allow ShellExecute to show error messages on the user’s screen
  • sefIgnoreElevationIfNotAvailable. Usually JwShellExecute checks whether the user is already elevated and if so just starts the application. However this call will fail on preVista systems. If this flag is set the function will not fail on preVista systems and just execute the application.
  • sefFixDirWithRunAs. ShellExecute ignores the directory parameter if it is called with the “runas” verb. However with this flag set, the JEDI function uses a trick to start the application in the correct directory. In this way there maybe a command window visible.
  • sefNoClosehProcess. The newer version of JwShellExecute closes the returned process handle for you if this flag is not set. If you need that process handle (e.g. waiting for the process to end) you should remove it.
• The return value is a handle to the process. It is now automatically closed for your if you do not deny it through the flag parameter.

The following code shows how to start the application with elevated privileges from whithin the same app.

2. Elevate special parts of your application

To elevate special parts of your application is the prefered way for a Vista application. This is done by separate the parts of your application that needs administrative rights, into an external process. We do not need to create a new application and do the inter-process communication stuff. Windows Vista uses an external COM process for this task. So the solutions goes with a COM DLL that we have to implement. In addition to that we also have to add a manifest – of course.

I will not tell the whole story about how to create a COM DLL and do all the stuff that has to be done. You should read Aleksander Oven’s tutorial how to accomplish that.
I’m going to show you how you can use the JWSCL methods.

Create your COM Dll and implement the COM interface. This may look like this (from the RunEl example in JWSCL):

The important stuff comes here.

Use the TElevationClassFactory or TJwElevationClassFactory (in developer version > 317) for registering the COM class in Windows. After you registered the COM class using regsvr32 (see Tutorial) you can retrieve an instance of the COM class with JwCoCreateInstanceAsAdmin.

If the thread has already elevated privileges the function JwCoCreateInstanceAsAdmin simply returns an instance without using the elevation prompt.

In developer version (revision > 317) the returned result value can contain information about the status.

• ERROR_SUCCESS – No error
• (revision > 317) ERROR_CANCELLED – the user has canceled the UAC prompt.
• (revision > 317) E_CLASS_IS_NOT_SETUP – the requested COM class has not been setup to be used for elevation.
• CoGetObject (if elevation is required) or CoCreateInstance (if elevation is not required) may return an error value

Be warned:
If you try to execute this function on a preVista system, the function is going to fail with EJwsclUnsupportedWindowsVersionException.

• RunEl (JwShellExecute and COM DLL) or Current repository.
• VistaElevation (COM DLL). Download JWSCL or Current repository.

Warning:
There is a problem with the manifest scanner on Windows XP. If you try to start an application with a manifest created for Vista you’re goingt to probably have a Blue Screen of Death. So you have to get a correct manifest from here (english translation).

Tell me how you liked this blog entry by adding a comment.

If you start the program without any parameter, you’ll get the help screen.

RunEl V1.0 – Run application elevated
by Christian Wimmer @ 2008
Visit us at http://blog.delphi-jedi.net

RunEl [/INSTALL][/UNINSTALL][/W[D][G]] [AppName] [Parameters]

Parameters:
/INSTALL – installs the RunElCOM.dll. Needed for parameter /D
RunElCOM.dll must be in the same folder as RunEl.
/UNINSTALL – uninstalls the RunElCOM.dll.
W – Wait for called process to be finished.
D – uses own elevation COM Class. Before using must be setup with /INSTALL .
G – uses foreground window to display UAC Prompt on.
Parameters W, D and G must be mixed up with only one “/”

Despite the INSTALL parameter, you do not have to install the program! I implemented two different ways to elevate an application. There is on the one side ShellExecute, which can elevate an application by passing “runas” as a parameter. On the other hand, I implemented the usual way by registering a COM DLL. In the last case, you have to register the DLL first. We get back there later.

Let’s see how we can use it. Open a command line window and type:

RunEl cmd

This command starts the Windows command line interpreter as an Administrator. You get the UAC prompt, allow the action and a new cmd window is opened. If you disallow the action, RunEl will return an error value through its process return value. This us useful if you want to check the errorlevel in a batch file.

Elevation failed. (2147943623) The operation was canceled by the user.

If you need to wait for the process to be closed, you can add the wait parameter. This is also mandatory if you want to check your application’s return value. Because it is clear that we have to wait until the process’ end to get the return value.

RunEl /w cmd

Sometimes the UAC prompt does not appear and just blinks in the task to get attention. This is because there is no available window. In this case you can specify parameter “g”, which uses the foreground window. The UAC prompt will appear again then.

RunEl /g cmd

Of course you can also combine both parameters. However there must only be one slash.
All these combinations are the same, so it ignores the case-sensitivity and the order of the three options letters.

RunEl /wg cmd
RunEl /gw cmd
RunEl /Gw cmd
RunEl /GW cmd

The last parameter “d” takes the usual way to get elevated privileges. It runs a COM method as the elevated user, creates the process, returns to non-elevated status and then eventually waits for the process or returns immediately.
However you have to install the provided DLL RunElCOM.dll at first. This is done by using RunEl.

RunEl /install
The COM DLL was successfully installed.

Now you are able to run applications with the “d” parameter in the nearly same way as shown above.

Run /d cmd
Run /dw cmd
Run /dwg cmd
…

I say nearly because of two issues:

1. You always have to use /d parameter. Otherwise ShellExecute is used
2. A major problem of ShellExecute is that it ignores the current directory if it is used for elevation. I circumnavigated this problem by using the following command line internally.
   

   cmd /C cd /d <current dir> & <your application> <parameters>

   The disadvantage of this solution is that you do not get the application’s return value. Cmd is the main process, so we get its return value instead of <your application>.
   If you need the correct return value directly, you have to use /d switch.

In the end you can uninstall the COM library.

runel /uninstall
The COM DLL was successfully uninstalled.

If you try to run an application using runel /d you’ll get the following error message.

RunEl /d cmd
Elevation failed. (2148007959) The class is not configured to support Elevated activation.

1. Do nothing and accept this dialog
2. Wait until I buy or get the very expensive sign certificate. I tell you that it will last a really long time.
3. Use your own certificate to sign the file

Download and Sourecode:

You get the newest version of RunEl in the JWSCL Download section of RunEl.

RunEl is also available through Subversion repository:

https://jedi-apilib.svn.sourceforge.net/svnroot/jedi-apilib/jwscl/trunk/examples/runel

You can browse the repository or download it with a Subversion client.

Please send bugs to mail@delphi-jedi.net , the mailinglist or the forum.

Both tokens are linked together. Thus the following conditions are true.

Token.LinkedToken = TwinToken
TwinToken.LinkedToken = Token

You can use the twin token in any way you treat a token if you are powerful enough. Use it in CreateProcess or impersonate the user to do things as the user.

At the end I post a quite useful piece of code that displays primary information about a token.

Tell me how you liked this blog entry by adding a comment.