Skip to content

Commit

Permalink
docs: update tutorial8.md
Browse files Browse the repository at this point in the history 
- Explains UIDefualts friendly way
  • Loading branch information
@miurahr
miurahr committed Sep 23, 2024
1 parent e69fe25 commit 9b59391
Showing 1 changed file with 82 additions and 39 deletions.
121 changes: 82 additions & 39 deletions wiki/tutorial8.md
View file
Original file line number Diff line number Diff line change
@@ -1,4 +1,4 @@
# Lesson 8 : Customizing the User Interface
# Lesson 8: Customizing the User Interface


This is the 8th part of the VLDocking Framework for Java Swing applications.
Expand All @@ -12,10 +12,9 @@ This lesson describes how to change the Look And Feel of VLDocking.


VLDocking uses UI delegate classes to paint the look and feel of many of its components.
Theses classes are dynamically loaded at startup, and use many UI properties to give your application the desired appearance. Here is the list of the current UI delegates :
These classes are dynamically loaded at startup, and use many UI properties to give your application the desired appearance. Here is the list of the current UI delegates :


<table border="1"><thead><tr><th> Component </th><th>UI Delegate class</th></tr></thead>
<table><thead><tr><th> Component </th><th>UI Delegate class</th></tr></thead>
<tbody>
<tr><td>DockView</td><td>com.vlsolutions.swing.docking.ui.DockViewUI</td></tr>
<tr><td>DockViewTitleBar</td><td>com.vlsolutions.swing.docking.ui.DockViewTitleBarUI</td></tr>
Expand All @@ -24,25 +23,26 @@ Theses classes are dynamically loaded at startup, and use many UI properties to
<tr><td>AutoHideExpandPanel</td><td>com.vlsolutions.swing.docking.ui.AutoHideExpandPanelUI</td></tr>
<tr><td>AutoHideButtonPanel</td><td>com.vlsolutions.swing.docking.ui.AutoHideButtonPanelUI</td></tr>
<tr><td>AutoHideButton</td><td>com.vlsolutions.swing.docking.ui.AutoHideButtonUI</td></tr>
</tbody></table>

</tbody>
</table>


### Replacing UI Delegates


Please note that most UI settings are accessible with UI properties, and thus cas be changed
without the need of writing a java class. The only case where you should have to write your own
UI delegate class is when you want a very different rendering (non rectangular for example).
UI delegate class is when you want a very different rendering (non-rectangular, for example).


So, if you need a very different rendering for your dockables, then you will have to provide your custom classes.


Here is how to declare them :

#### Legacy way to declare them

* pre-install the default ui settings in you main() method, or any method prior DockingDesktop usage
* pre-install the default ui settings in your `main()` method, or any method prior DockingDesktop usage
* put your new settings as UIManager properties

Example :
Expand All @@ -55,10 +55,29 @@ Example :
// and start customizing...
UIManager.put("DockViewTitleBarUI", "your.own.ui.UIDelegateClassName");
// (replaced the DockViewTitleBar UI by another class)
...
}
```

#### LookAndFeel friendly way

* Define it in your custom `LookAndFeel#getDefaults`
* Set CustomLookAndFeel class name using `UIManager.setLookAndFeel`

```java
import javax.swing.*;

public class CustomLookAndFeel extends BasicLookAndFeel implements LookAndFeel {

@Override
public UIDefaults getDefaults() {
UIDefaults defaults = UIManager.getDefaults();
defaults.put("DockViewTitleBarUI", "your.own.ui.UIDelegateClassName");
return defaults;
}
}


```


### Updating the existing UI
Expand All @@ -68,43 +87,48 @@ The easiest way to update the UI is by tweaking the UIManager properties.
For example, if you want a special border for maximized dockable, use :

```java
// declare your border
Border myBorder = ...
// put it in the UI property map.
UIManager.put("DockView.maximizedDockableBorder", myBorder);
// and that's it !
public class Main {
public static void main(String[] args) {
// declare your border
Border myBorder = new MyBorder();
// put it in the UI property map.
UIManager.put("DockView.maximizedDockableBorder", myBorder);
// and that's it!
}
}
```


Please note that *to avoid having your own UI settings beeing erased* by the default ones,
you will have to follow the pattern :


* pre-install the default ui settings in you main() method, or any method prior DockingDesktop usage
* pre-install the default ui settings in your `main()` method, or any method prior DockingDesktop usage
* put your new settings as UIManager properties




```java
public class Main {
public static void main(String[] args) {
// first, preload the UI to avoid erasing your own customizations
DockingUISettings.getInstance().installUI();

// declare your border
Border myBorder = ...
Border myBorder = new MyBorder();
// and start customizing...
UIManager.put("DockView.maximizedDockableBorder", myBorder);
...
}
}
```

Now that you know how to proceed, here is the long list of customizable properties...

## Customizable properties
### Border properties

<table border="1">
<table>
<thead>
<tr><th>UI property</th> <th>type</th> <th>effect</th></tr></thead>
<tbody>
Expand All @@ -126,20 +150,22 @@ Now that you know how to proceed, here is the long list of customizable properti
<tr> <td>ToolBarPanel.rightBorder</td> <td>Border</td> <td>Border used when a toolbar in on the right of a container</td></tr>
<tr> <td>FloatingDialog.dialogBorder</td> <td>Border</td> <td>Border used for the FloatingDialog</td></tr>
<tr> <td>FloatingDialog.titleBorder</td> <td>Border</td> <td>Border used for the title (drag header) of the FloatingDialog</td></tr>
</tbody></table>
</tbody>
</table>

### Color properties

<table border="1">
<table>
<thead>
<tr><th>UI property</th> <th>type</th> <th>effect</th></tr></thead>
<tbody>
<tr> <td>DockingDesktop.notificationColor</td> <td>Color</td> <td>blinking color for notifications</td></tr>
</tbody></table>
</tbody>
</table>

### Icons

<table border="1">
<table>
<thead>
<tr><th>UI property</th> <th>type</th> <th>effect</th></tr></thead>
<tbody>
Expand Down Expand Up @@ -184,12 +210,13 @@ property must also be set to true</td></tr>
<tr> <td>DockTabbedPane.menu.float</td> <td>Icon </td> <td>Icon for the float button, in tab pop-up menu</td></tr>
<tr> <td>DockTabbedPane.menu.closeAll</td> <td>Icon </td> <td>Icon for the "close all" button, in tab pop-up menu</td></tr>
<tr> <td>DockTabbedPane.menu.closeAllOther</td> <td>Icon </td> <td>Icon for the "close all other" button, in tab pop-up menu</td></tr>
</tbody></table>
</tbody>
</table>


### Labels and Fonts

<table border="1">
<table>
<thead>
<tr><th>UI property</th> <th>type</th> <th>effect</th></tr></thead>
<tbody>
Expand All @@ -205,11 +232,12 @@ property must also be set to true</td></tr>
<tr> <td>DockTabbedPane.restoreButtonText</td> <td>String</td> <td>Text for the restore button in tab</td></tr>
<tr> <td>DockTabbedPane.maximizeButtonText</td> <td>String</td> <td>Text for the maximize button in tab</td></tr>
<tr> <td>DockTabbedPane.floatButtonText</td> <td>String</td> <td>Text for the float button in tab</td></tr>
</tbody></table>
</tbody>
</table>

### Displaying buttons in title bars

<table border="1">
<table>
<thead>
<tr><th>UI property</th> <th>type</th> <th>effect</th></tr></thead>
<tbody>
Expand All @@ -220,24 +248,26 @@ property must also be set to true</td></tr>
<tr> <td>DockViewTitleBar.isRestoreButtonDisplayed</td> <td>boolean</td> <td>display or not the restore button in the title bar</td></tr>
<tr> <td>DockViewTitleBar.isFloatButtonDisplayed</td> <td>boolean</td> <td>display or not the float button in the title bar</td></tr>
<tr> <td>DockViewTitleBar.isAttachButtonDisplayed</td> <td>boolean</td> <td>display or not the attach button in the title bar</td></tr>
</tbody></table>
</tbody>
</table>

### KeyStrokes

<table border="1">
<table>
<thead>
<tr><th>UI property</th> <th>type</th> <th>effect</th></tr></thead>
<tbody>
<tr> <td>DockingDesktop.closeActionAccelerator</td> <td>KeyStroke</td> <td>KeyStroke for close action (on selected dockable)</td></tr>
<tr> <td>DockingDesktop.maximizeActionAccelerator</td> <td>KeyStroke</td> <td>KeyStroke for maximize/restore action (on selected dockable)</td></tr>
<tr> <td>DockingDesktop.dockActionAccelerator</td> <td>KeyStroke</td> <td>KeyStroke for hide/dock action (on selected dockable)</td></tr>
<tr> <td>DockingDesktop.floatActionAccelerator</td> <td>KeyStroke</td> <td>KeyStroke for float/attach action (on selected dockable)</td></tr>
</tbody></table>
</tbody>
</table>

### UI Delegates


<table border="1"><thead><tr><th>UI property</th><th>type</th><th>effect</th></tr></thead><tbody>
<table><thead><tr><th>UI property</th><th>type</th><th>effect</th></tr></thead><tbody>
<tr><td>AutoHideButtonUI</td> <td>class name</td> <td>UI delegate for the AutoHideButton</td></tr>
<tr><td>AutoHideButtonPanelUI</td> <td>class name</td> <td>UI delegate for the AutoHideButtonPanel</td></tr>
<tr><td>AutoHideExpandPanelUI</td> <td>class name</td> <td>UI delegate for the AutoHideExpandPanel</td></tr>
Expand All @@ -247,14 +277,15 @@ property must also be set to true</td></tr>
<tr><td>DockViewTitleBar.height</td> <td>int</td> <td>Height of the title bars</td></tr>
<tr><td>DockingSplitPaneUI</td> <td>class name</td> <td>UI delegate for SplitContainer component</td></tr>
<tr><td>ToolBarGripperUI</td> <td>class name</td> <td>UI delegate for the toolbar "gripper"</td></tr>
</tbody></table>
</tbody>
</table>

### Cursors

Starting from version 2.0.3 it is now possible to change the mouse cursor images used during
drag gestures.

<table border="1"><thead><tr><th>UI property</th><th>type</th><th>effect</th></tr></thead><tbody>
<table><thead><tr><th>UI property</th><th>type</th><th>effect</th></tr></thead><tbody>
<tr><td>DragControler.stopDragCursor</td> <td>java.awt.Image</td> <td>Image (max 32x32) used when the mouse pointer is above a place where drop is not possible</td></tr>
<tr><td>DragControler.detachCursor</td> <td>Image</td> <td>Image used to denote a floating action </td></tr>
<tr><td>DragControler.dragCursor</td> <td>Image</td> <td>Image used (together with a shape) to denote a position where drop is possible</td></tr>
Expand All @@ -264,7 +295,7 @@ drag gestures.

### Other properties

<table border="1">
<table>
<thead>
<tr><th>UI property</th> <th>type</th> <th>effect</th></tr></thead>
<tbody>
Expand Down Expand Up @@ -293,26 +324,38 @@ You can choose select between the following provided styles (more to come) with


```java
// version 1.0 style
DockingPreferences.setShadowDesktopStyle();
public class Main {
public static void main(String[] args) {
// version 1.0 style
DockingPreferences.setShadowDesktopStyle();
}
}
```

![](shadowed_style.jpg)

_The "Shadow Style"_

```java
// or version 1.0 alternative style
DockingPreferences.setDottedDesktopStyle();
public class Main {
public static void main(String[] args) {
// or version 1.0 alternative style
DockingPreferences.setDottedDesktopStyle();
}
}
```

![](dotted_style.jpg)

_The "Dotted Style"_

```java
// or version 2.0 default style
DockingPreferences.setFlatDesktopStyle();
public class Main {
public static void main(String[] args) {
// or version 2.0 default style
DockingPreferences.setFlatDesktopStyle();
}
}
```

![](flat_style.jpg)
Expand Down

0 comments on commit 9b59391

Please sign in to comment.