# Window Demo

## What Is It

This demo lets you see how different configuration options affect new window/dialog/frame. This demo does not feature new/novel code.

## How To Use It

Use the options in the "Configuration" panel to design your new window. Then click the "Show Window" button to actually create and show the window.

This demo lets you see first-hand what certain options actually do. For example:

- What does `Window.setType(..)` actually mean for the end user?
- If you use the Mac-specific options to paint under the title bar: can you interact with components under the titlebar?
- Which will end up on top: a `JDialog` configured so `isAlwaysOnTop()` returns true, OR a `JDialog` configured with so `getType()` returns `POPUP`?
- Which combination of options are incompatible?

Most of the controls feature tooltips that clearly identify which window attribute they change.

It is possible to configure a window in a way that you'll get a `IllegalComponentStateException` when you try to show it. (For example: leave "Undecorated" unselected, and set the "Alpha" to less than 100%.) Any such configuration will throw an exception, and you'll see an error dialog.

### Window Type

Personally I've found the `setType(Type)` property confusing in the past, so I did a little research. The javadoc says:

> - A utility window is usually a small window such as a toolbar or a palette. The native system may render the window with smaller title-bar if the window is either a Frame or a Dialog object, and if it has its decorations enabled.
> - A popup window is a temporary window such as a drop-down menu or a tooltip. On some platforms, windows of that type may be forcibly made undecorated even if they are instances of the Frame or Dialog class, and have decorations enabled.

(Also I've found it subtly affects how VoiceOver on Mac announces the windows; but I haven't found a way to really influence VoiceOver to my satisfaction.)

### Mac Attributes

If you are looking at this on a Mac: the lower half of controls (starting with "Window Style") are all attributes supported exclusively on Mac. Most of these controls were reverse-engineered from studying the sun.lwawt.macosx.CPlatformWindow class. Several of these I've used over the years to help build more native-feeling apps. There are a few attributes (such as "apple.awt.windowShadow.revalidateNow" and "apple.awt.delayWindowOrdering") I intentionally left out because I found them too obscure.

As far as I can tell the modal sheet property doesn't work anymore. (I included it here just in case it starts working or someone can point out a magical combination of properties that make it work.) I know it requires a dialog that uses modality type DOCUMENT_MODAL, but if it is still supported there must be another additional requirement I don't know about. It looks like Apple still supports them in native apps, though.

The "unified" window style also doesn't appear to work. (I'm not sure if it ever did?) I saw one throw-away line in Apple's documentation mentioning, "unifiedTitleAndToolbar: This constant has no effect, because all windows that include a toolbar use the unified style." Or perhaps more importantly: the Aqua L&F in Swing is a lightweight replica of Aqua, but it doesn't actually use the same components. While it may be possible to emulate many things, it may be impossible to create a real native window with certain attributes that works well with Swing components.

The "HUD" window style has the unique distinction of a quick fade out when dismissed. Also using it produces a warning in System.err: "NSPanel requires NSWindowStyleMaskUtilityWindow for a HUD window". I'm not sure what implications that has.

The shadow toggle is invaluable if you ever want a custom/subtle window. (Also if you ever get stuck with a style window shadow cache, you can call `rootPane.putClientProperty("apple.awt.windowShadow.revalidateNow", new Object())`.)

The document attributes ("Window.documentModified" and "Window.documentFile") are great if you want to make a document editor that includes subtle Mac behaviors. If your window represents an unsaved document, then marking it as modified adds a dot in the middle of the close decoration. If your window represents a specific file: the file icon appears in the titlebar, and if you command-click it you can see its file path. (There may be other behaviors I'm unaware of, too.)

The closeable/minimizable/zoomable attributes are actually the original motivation for this demo. I knew it was possible to disable these controls, but I forgot where to look so I decided to make this demo so (hopefully) I'll never forget again. On Windows if I need to make a decorated dialog uncloseable I call:
`setDefaultCloseOperation(WindowConstants.DO_NOTHING_ON_CLOSE);`

Unfortunately that awkward hack leaves the close decoration visible, but it does nothing.

I'm still getting used to the title bar controls ("Transparent Title Bar", "Full Window"). They're a little tricky because you still don't have complete control over the titlebar area. You can paint anything you want there, but you can't control UI components in that space. If the user clicks and drags in the titlebar area: they'll still drag the window. Even if they clicked on a button. So it's hard to emulate, say, Safari's titlebar (which includes the URL text field and some other controls). You could work around this by making the frame undecorated and just adding your own window decorations, but of course if the OS updates the L&F of those buttons in upgrades you'll be out-of-step.

All of these custom Mac properties are configured using client properties, so they should have no effect on other platforms that do not support them. I looked around for a similar suite of properties for Windows, but so far I haven't found them. (If anyone has any leads: let me know and I'll see if I can add them here.)