Вы находитесь на странице: 1из 47

DockPanel Suite Documentation

Release 2.10

Ryan Rastedt, Lex Li, and others

September 20, 2016

 

Contents

1 Topics

3

1.1 Getting Started

.

.

.

.

.

.

.

.

.

.

.

.

.

.

.

.

.

.

.

.

.

.

.

.

.

.

.

.

.

.

.

.

.

.

.

.

.

.

.

.

.

.

.

.

.

.

3

1.2 Tutorials

.

.

.

.

.

.

.

.

.

.

.

.

.

.

.

.

.

.

.

.

.

.

.

.

.

.

.

.

.

.

.

.

.

.

.

.

.

.

.

.

.

.

.

.

.

.

.

.

.

8

1.3 Themes .

.

.

.

.

.

.

.

.

.

.

.

.

.

.

.

.

.

.

.

.

.

.

.

.

.

.

.

.

.

.

.

.

.

.

.

.

.

.

.

.

.

.

.

.

.

.

.

.

.

16

1.4 Contribute

.

.

.

.

.

.

.

.

.

.

.

.

.

.

.

.

.

.

.

.

.

.

.

.

.

.

.

.

.

.

.

.

.

.

.

.

.

.

.

.

.

.

.

.

.

.

.

.

36

2 Contribute to Documentation

 

43

DockPanel Suite Documentation, Release 2.10

Attention: DockPanel Suite 2.10 is now available on NuGet! Please read the Getting Started instructions for installing the latest version from NuGet.

DockPanel Suite Documentation, Release 2.10

CHAPTER 1

Topics

1.1 Getting Started

1.1.1 Installing DockPanel Suite On Windows

By Lex Li

This page shows you how to install DockPanel Suite to your project on Windows.

In this article:

Install DockPanel Suite via NuGet

Install DockPanel Suite via Source Code

Compile DockPanel Suite from Source Code

Related Resources

Install DockPanel Suite via NuGet

The easiest way to get started building applications with DockPanel Suite is to install via NuGet in the latest version of Visual Studio 2015 (including the free Community edition).

1. Install Visual Studio 2015 .

Be sure to specify that you include the Windows and Web Development.

2. Install latest NuGet Package Manager .

This will install the latest NuGet tooling.

3. Open/create an empty Windows Forms project.

4. Install DockPanel Suite NuGet packages following NuGet conventions .

The latest packages can be found at,

• (2.10) VS2012 Light Theme .

• (2.11+) VS2012 Themes .

• (2.10) VS2013 Blue Theme .

DockPanel Suite Documentation, Release 2.10

• (2.11+) VS2013 Themes .

Note:

VS2005MultithreadingTheme is not recommended for general usage.*

Warning: Theme package version should match main library version whenever possible. Otherwise, there can be compatibility issues.

5. Create the DockPanel control in code and insert to the main form

public

MainForm()

{

InitializeComponent();

 

this.dockPanel

=

new

WeifenLuo.WinFormsUI.Docking.DockPanel();

this.dockPanel.Dock

=

System.Windows.Forms.DockStyle.Fill;

this.Controls.Add(this.dockPanel);

}

6. Create other panels by creating a new Form or new UserControl in Visual Studio

public

class

NewForm

:

Form

{

}

Change the base type to WeifenLuo.WinFormsUI.Docking.DockContent

public

class

NewDockContent

:

WeifenLuo.WinFormsUI.Docking.DockContent

{

}

7. Show the custom DockContent in DockPanel as a document

public

void

ShowDockContent()

 

{

var

dockContent

=

new

NewDockContent();

dockContent.Show(this.dockPanel,

DockState.Document);

}

Install DockPanel Suite via Source Code

DockPanel Suite source code can be directly used in your project.

1. Download the source code from GitHub , or clone the repo directly.

2. Open/create a empty Windows Forms project in a solution.

3. Add WinFormsUI.csproj in WinFormsUI directory to your solution.

4. (optional) Add other theme projects such as ThemeVS2003.csproj to your solution.

5. Compile the solution and DockPanel Suite controls are automatically added to Toolbox panel.

6. Open main form of the empty project, and drag the DockPanel control from Toolbox on to it.

This will let Visual Studio generate the necessary code.

DockPanel Suite Documentation, Release 2.10

7. Create other panels by creating new Form or new UserControl in Visual Studio

public

class

NewForm

:

Form

{

}

Change the base type to WeifenLuo.WinFormsUI.Docking.DockContent

public

class

NewDockContent

:

WeifenLuo.WinFormsUI.Docking.DockContent

{

}

8. Show the custom DockContent in DockPanel as a document

public

void

ShowDockContent()

 

{

var

dockContent

=

new

NewDockContent();

dockContent.Show(this.dockPanel,

DockState.Document);

}

Compile DockPanel Suite from Source Code

1. Download the source code from GitHub , or clone the repo directly.

2. Make sure that .NET Framework 4.0 (or above) is installed.

3. Run all.bat in the source code to start compilation.

If everything works, then the binaries are in the bin folder.

Related Resources

Adding DockPanel Suite to Toolbox in Visual Studio

Project History

Basic Usages

Existing Themes

1.1.2 Adding DockPanel Suite to Toolbox in Visual Studio

By Lex Li

This page shows you how to install DockPanel Suite to your project on Windows.

In this article:

Recommended Steps

Related Resources

DockPanel Suite Documentation, Release 2.10

Recommended Steps

1. Follow Installing DockPanel Suite On Windows to compile DockPanel Suite binaries.

2. Open Visual Studio, and navigate to its Toolbox panel.

3. Expand a tab such as General, or create a new tab by right clicking and choosing “Add Tab” menu item.

4. Right click in the tab area and choose “Choose Items

5. Under the ”.NET Framework Components” “Choose Toolbox Items” dialog, click the “Browse

” menu item.

” button.

6. In the “Open” file dialog, navigate to bin\net40 folder that contains the assemblies, and choose all related files,

WerifenLuo.WinFormsUI.Docking.dll, ThemeVS2003.dll, ThemeVS2012Light.dll (2.10), ThemeVS2012.dll (2.11+), ThemeVS2013Blue.dll (2.10), and ThemeVS2013.dll (2.11+).

7. Click the “Open” button to exit the dialog.

8. In ”.NET Framework Components” tab, click “Namespace” column header to reorder the list.

9. Make sure that “DockPanel”, “VS2003Theme”, “VS2005Theme”, “VS2012LightTheme”, “VS2012DarkTheme”

(2.11+), “VS2012BlueTheme” (2.11+), “VS2013BlueTheme”, “VS2013LightTheme” (2.11+), and “VS2013DarkTheme” (2.11+) are checked.

10. Click the “OK” button to exit the dialog.

Related Resources

Installing DockPanel Suite On Windows

Project History

Basic Usages

Existing Themes

1.1.3 Project History

By Lex Li

Microsoft first introduced the docking panel layout in Visual Studio .NET (2002), and soon it became popular in application design. Many commercial .NET component vendors started to provide docking libraries initially, but there was no good free and open source alternative, until WeiFen Luo released DockPanel Suite (DPS for short) on SourceForge.net in 2006.

WeiFen Luo’s Efforts and Early Years

Its 1.0 release was available on Feb 13, 2006, one day before the Valentine’s day 1 . From the SVN repository we could no longer find the commits earlier than Mar 2, 2007. Therefore, we don’t know exactly when WeiFen decided to implement this docking library and the day he started. This release has been downloaded more than 57,000 times on SF.net alone (binaries + source package), which is a huge success.

After that, WeiFen published several new releases. Release 2.0 RC was available on Mar 02, 2007. Release 2.0 followed on Apr 02, while release 2.2 was available on Nov 04, 2007 (more than 68,000 downloads) 2

DockPanel Suite Documentation, Release 2.10

Danilo Corallo wrote an article titled “A Visual Studio 2005-like Interface” 3 on CodeProject.com initially on Jun 06,

2006 to introduce this library for broader audience. The article has been reviewed for more than 586,000 times with

an average rate of 4.89. This article was last updated on 22 Jan, 2007, so it only targets DPS 1.0. However, DPS 2.0 and above do contains breaking changes, so the sample of this article does not work with newer DPS releases.

SharpDevelop 4 , the open source C#/VB.NET IDE, has chosen DPS as its docking library for years (till SD 4.0 migrates to WPF and uses AvalonDock 5 instead of DPS). It is interesting that from SD code base, DPS source files appeared as early as Jan 04, 2005 6 .

On Aug 16, 2009, WeiFen wrote in a discussion thread, that he would like to move this project to CodePlex.com 7 . However, this move was never carried out. But in this thread WeiFen linked one of his important blog posts on DPS 8 , which documented his ideas on why WPF based docking library is better. WeiFen’s interest has been moved to WPF side product called WPF Docking 9 .

Extended Maintenance by Steve Overton and Others

Steve Overton and other contributors stepped up and started to maintain this library in 2009 10 . He managed to release 2.3 on May 08, 2009 (more than 68,000 downloads) 11 12 . 2.4 Followed on Oct 30, 2010 with a few new patches 13 . For the first time, DPS is released with binaries/source code/release notes. This release has been downloaded over

8000 times. Soon release 2.5.0 (with RC1 flag) was available on Nov 25 the same year with more patches included 14 .

This is the last stable release that can be found on SF.net with accumulated downloads of 61,000.

GitHub Fork and The DockPanel Suite Organization

Frustrated DPS users started to discuss about the future of this project 15 , and soon some agreed to create a fork on GitHub 16 .

The new repository was created using svn2git 17 by Lex Li and now is hosted on GitHub under dockpanelsuite orga- nization,

Ryan Rastedt purchased the dockpanelsuite.com domain name and designed a new home page 18 for this project.

This organization evaluated and merged many community patches. A few releases, such as 2.6, 2.7, 2.8, 2.9, and 2.10 have been published in the past few years.

Several significant changes have been introduced in recent releases,

• Kamen Turboto 19 started Visual Studio 2012 Light theme in 2012, which since then becomes the basis for all new themes.

DockPanel Suite Documentation, Release 2.10

• ParallelLoeter contributed a patch to have close buttons on document tabs 20 in 2010, which later is used in all new themes.

• yck1509 developed pressed image support in his fork 21 in 2015, which is used in all new themes.

• Thijs Elenbaas 22 started Visual Studio 2013 Blue theme in 2015, which inspires the later themes.

• Dan Pries 23 suggested a color palette based theme design in early 2016, which is later fully implemented by Lex Li.

Related Resources

Installing DockPanel Suite On Windows

Basic Usages

Existing Themes

1.2 Tutorials

1.2.1 Basic Usages

By Lex Li

This page shows you the basics about DockPanel Suite.

In this article:

Show Contents as Documents

Show Multiple Contents in The Same Dock State

How to Lock Layout and Prevent Dock Panels From Moving

Related Resources

Show Contents as Documents

It is quite common to have a list of dock contents shown as a list of documents.

To show a single document, the following code can be used

doc1.Show(dockPanel,

DockState.Document);

To show a list of documents in order, the following code can be used,

doc1.Show(dockPanel,

DockState.Document);

doc2.Show(doc1.Pane,

null);

doc3.Show(doc1.Pane,

null);

doc4.Show(doc1.Pane,

null);

//

reorder

doc1

and

doc2

doc1.Show(doc1.Pane,

null);

doc2.Show(doc1.Pane,

null);

DockPanel Suite Documentation, Release 2.10

Note: Note that the DockContent.Pane property is used so that documents are placed in the same dock pane.

Show Multiple Contents in The Same Dock State

By default if two or more dock contents are shown in the same dock state will share the same dock pane and become tabs in that pane.

dmcDownloadMonitor.Show(dockPanel,

amcActivateModsMonitor.Show(dockPanel,

DockState.DockBottom);

DockState.DockBottom);

However, sometimes the contents should be placed into different panes and shown side by side. This requires some changes in code,

dmcDownloadMonitor.Show(dockPanel,

amcActivateModsMonitor.Show(dmcDownloadMonitor.Pane,

DockState.DockBottom);

DockAlignment.Right,

0.5);

How to Lock Layout and Prevent Dock Panels From Moving

Lock Entire Layout

To lock the entire layout, the following snippet can be used to disable all end user docking at DockPanel level,

dockPanel.AllowEndUserDocking

=

false;

Lock A Single Panels

To lock only a single panel, the following snippet can be used to disable all end user docking at DockContent level,

dockContent.DockHandler.AllowEndUserDocking

=

false;

Avoid A Few Dock States

To prevent a dock panel from entering some dock states, set DockContent.DockAreas to only the areas that are desired.

Related Resources

Installing DockPanel Suite On Windows

Customizing DockContent

Customizing DockWindow

Customizing FloatWindow

Customizing Persistence

Existing Themes

DockPanel Suite Documentation, Release 2.10

1.2.2 Customizing DockContent

This page shows you how to customize DockContent.

In this article:

Bring a DockContent to Front

Prevent The DockContent From Being Closed

Controlling Default Height or Width When Set to Auto-Hide

Dismissing Visible Auto-Hide Panel

Switching Among Documents

Remove a DockContent From DockPanel

Related Resources

Bring a DockContent to Front

Simply call DockContent.Activate. This is usually used to show a tab as active tab in code.

Prevent The DockContent From Being Closed

To prevent a DockContent from every being closed, utilize the CloseButton property. You can also utilize the CloseButtonVisible property to hide the close button when docked in the DockPanel control,

public

CustomContent

 

:

DockContent

 

{

public

CustomContent()

 

{

 

InitializeContent();

 

//

Prevent

this

content

from

being

closed

 

CloseButton

=

false;

//

Hide

the

close

button

so

the

user

isn't

even

tempted

CloseButtonVisible

=

false;

 

}

}

You can also use the OnFormClosing method to prevent the user from closing under certain conditions that cannot be determined until runtime (for example, showing a dialog box asking the user if they are really sure they wish to close the tab),

public CustomContent : DockContent { protected override void OnFormClosing(FormClosingEventArgs e) { bool
public
CustomContent
:
DockContent
{
protected
override
void
OnFormClosing(FormClosingEventArgs
e)
{
bool
cancel
=
/ *
add
your
closing
validation
here
* /;
e.Cancel
=
cancel;
base.OnFormClosing(e);
}
}

DockPanel Suite Documentation, Release 2.10

Controlling Default Height or Width When Set to Auto-Hide

The property DockContent.AutoHidePortion controls the auto-hide behaviors.

A value greater than 1 indicates a pixel size, while a value less than 1 indicates a percentage size (as a percentage of

the DockPanel).

Dismissing Visible Auto-Hide Panel

Usually by double clicking the the tab of an auto-hide panel it will be dismissed. Below shows how to do it in code,

this.dockPanel.ActiveAutoHideContent

=

null;

Switching Among Documents

It is possible to add keyboard shortcuts to enable switching among document tabs, not yet part of the default code

base,

1. Derive from DockContent.

2. Override ProcessCmdKey.

3. Find the next DockContent in DockPanel.Documents.

4. Call its Activate method.

Remove a DockContent From DockPanel

To

null.

release

a

DockContent

from

DockPanel,

simply set

DockContent.DockHandler.DockPanel

to

dockContent.DockHandler.DockPanel

=

null;

Related Resources

Installing DockPanel Suite On Windows

Basic Usages

Customizing DockWindow

Customizing FloatWindow

Customizing Persistence

Existing Themes

1.2.3 Customizing DockWindow

By Lex Li

This page shows you how to customize DockWindow.

DockPanel Suite Documentation, Release 2.10

In this article:

Change DockWindow Z-Order

Related Resources

Change DockWindow Z-Order

There are four DockWindow instances created in DockPanel control, where later new DockContent instances can be inserted to. By changing their Z-order, the layout style can be controlled.

this.dockPanel.UpdateDockWindowZOrder(DockStyle.Right,

true);

Related Resources

Installing DockPanel Suite On Windows

Basic Usages

Customizing DockContent

Customizing FloatWindow

Customizing Persistence

Existing Themes

1.2.4 Customizing FloatWindow

This page shows you how to customize FloatWindow.

In this article:

Maximizable FloatWindow

Alt+Tab Support

Overriding Double Clicking Behavior

Positioning for Multiple Monitors

Top-Most FloatWindow

Related Resources

Maximizable FloatWindow

Out of the box, a window that is undocked to a floating state lacks a maximize button. Utilizing the Extender functionality of DockPanel it’s easy to customize the FloatWindow class!

The first step is to create a custom class that extends FloatWindow. By default, FloatWindow has a FormBorderStyle of SizableToolWindow which will only provide a close button. To expose the maximize and minimize button, set FormBorderStyle of the custom window to Sizable,

DockPanel Suite Documentation, Release 2.10

public class CustomFloatWindow : FloatWindow { public CustomFloatWindow(DockPanel dockPanel, DockPane pane) :
public
class
CustomFloatWindow
:
FloatWindow
{
public
CustomFloatWindow(DockPanel
dockPanel,
DockPane
pane)
:
base
(dockPanel,
pane)
{
FormBorderStyle
=
FormBorderStyle.Sizable;
}
public
CustomFloatWindow(DockPanel
dockPanel,
DockPane
pane,
Rectangle
bounds)
: base
(dockPanel,
pane,
bounds)
{
FormBorderStyle
=
FormBorderStyle.Sizable;
}
}

Next,

create a factory class to create the CustomFloatWindow.

IFloatWindowFactory interface,

This is done by implementing the

public

class

CustomFloatWindowFactory

:

DockPanelExtender.IFloatWindowFactory

 

{

public

FloatWindow

CreateFloatWindow(DockPanel

dockPanel,

DockPane

pane,

Rectangle

bounds)

{

 

return

new

CustomFloatWindow(dockPanel,

pane,

bounds);

}

public

FloatWindow

CreateFloatWindow(DockPanel

dockPanel,

DockPane

pane)

{

 

return

new

CustomFloatWindow(dockPanel,

pane);

}

}

Lastly, attach the new factory to the DockPanel control,

this.dockPanel.Extender.FloatWindowFactory

=

new

CustomFloatWindowFactory();

Alt+Tab Support

To enable Alt+Tab between your undocked forms and your main form add this to your CustomFloatWindow constructors,

ShowInTaskbar

=

Owner

null;

=

true;

Overriding Double Clicking Behavior

Note: This requires DockPanel Suite version 2.8 and above.

By default, when a float window’s title bar is double clicked it is redocked into the DockPanel. This behavior can be disabled (and allow the Windows default behavior of maximizing/restoring the window) by setting the following property in your CustomFloatWindow constructor,

DoubleClickTitleBarToDock

=

false;

DockPanel Suite Documentation, Release 2.10

Positioning for Multiple Monitors

When a dock content is set to float, the created FloatWindow might be at a secondary monitor (depending on WinForms underlying positioning).

To force the FloatWindow to appear on a desired monitor, a custom FloatWindow can be created. Then override its SetBoundsCore method to check the monitors based on the information exposed by the Screen class.

Top-Most FloatWindow

To make the FloatWindow top-most, simply create a custom FloatWindow class and set its TopMost property to true.

Related Resources

Installing DockPanel Suite On Windows

Basic Usages

Customizing DockContent

Customizing DockWindow

Customizing Persistence

Existing Themes

1.2.5 Customizing Persistence

By Lex Li

This page shows you how to customize persistence.

In this article:

Layout File Format

Overriding Persistent String

Related Resources

Layout File Format

DockPanel.Persistor.SaveAsXml is the method who saves current layout to an XML file.

It is not recommended to manually edit the generated layout file, as its syntax is complicated.

To achieve customization, it is recommended to override the persistent string.

Overriding Persistent String

As the sample project shows, by default when current layout is saved to disk only class name is persisted. As a result, in delegate IDockContent DeserializeDockContent(string persistString) only class name is used to reconstruct the layout.

DockPanel Suite Documentation, Release 2.10

The current design gives you flexibility to control what other information about each dock items to be persisted, as the method DockContent.GetPersistString() can be overridden by derived classes. By properly overriding it, extra data (such as custom data about the internal components of a dock item) can be appended to the string. Thus, when the layout is reconstructed, the extended persist string can be analyzed and extra data can be extracted and used.

Related Resources

Installing DockPanel Suite On Windows

Basic Usages

Customizing DockContent

Customizing DockWindow

Customizing FloatWindow

Existing Themes

1.2.6 Disabling Patches (2.11+)

By Lex Li

This page shows you how to disable certain community patches of DockPanel Suite.

In this article:

Community Patches

Patch Controller Design

Current Patches in Testing

Community Patches

DockPanel Suite has a very strong developer community where people fork and refine this library with bug fixes and new features. As maintainers, instead of waiting for pull requests we evaluate such commits from time to time and merge them if they are mature and really useful.

However, it would be difficult to assert the quality of such patches, especially when we cannot easily contact the original developers or fully understand the code base.

Patch Controller Design

In order to make patch evaluation more efficient, a mechanism called Patch Controller is designed for 2.11+.

This allows us to ship selected patches and turn them on by default, which gives a bigger audience opportunities to play with the patches. It would be more likely that we receive bug reports and feedbacks on such patches. Of course, this mechanism also allows users to disable the patches individually.

To disable all patches, the following code can be used,

PatchController.EnableAll

=

false;

To disable all patches without modifying source code, the following custom section can be used in app.config or web.config,

DockPanel Suite Documentation, Release 2.10

<?xml

version="1.0"

encoding="utf-8"

?>

 

<configuration>

<configSections>

<section

name="dockPanelSuite"

type="WeifenLuo.WinFormsUI.Docking.Configuration.PatchSection,

Te

</configSections>

<dockPanelSuite

enableAll="false"

/>

</configuration>

To disable a patch in code, such as the HiDPI patch, the following code can be used,

PatchController.EnableHighDpi

=

false;

 

To disable a patch such as the HiDPI patch without modifying source code, the following section can be used in app.config or web.config,

<?xml

version="1.0"

encoding="utf-8"

?>

<configuration>

<configSections>

<section

name="dockPanelSuite"

type="WeifenLuo.WinFormsUI.Docking.Configuration.PatchSection,

Te

</configSections>

<dockPanelSuite

enableHighDpi="false"

/>

</configuration>

 

To disable a patch such as the HiDPI patch via environment variable, please set “DPS_EnableHighDpi” to “false”.

To disable a patch such as the HiDPI patch via registry key, please create a key named “SoftwareDockPanelSuite”, and create a string value named “EnableHighDpi” which should be set to “false”.

Current Patches in Testing

There are several patches included in 2.11 for testing. They are,

More might be added in the next few weeks before the final release.

The magic words to disable them can be found in this source file .

1.3 Themes

1.3.1 Review on Visual Studio Themes

By Lex Li

This page provides a review on Microsoft Visual Studio themes. DockPanel Suite themes follow the look-and-feel.

DockPanel Suite Documentation, Release 2.10

In this article

Visual Studio 2010 Blue Theme

Visual Studio 2012 Themes

Visual Studio 2013 Themes

Visual Studio 2015 Themes

Visual Studio Color Theme Manager

Related Resources

Visual Studio 2010 Blue Theme

Microsoft gave up Windows Forms and built Visual Studio 2010 mainly on WPF. That instantly led to a brand new theme being shipped,

WPF. That instantly led to a brand new theme being shipped, Fig. 1.1: Figure 1: Visual

Fig. 1.1: Figure 1: Visual Studio 2010 Blue Theme

It reassembles many elements of Visual Studio 2008 themes, such as rounded rectangles and icons in auto-hide tabs and tool window tabs, but also features new elements,

• Gradient effect is almost removed.

• More colors are utilized (especially when a visual element is hovered or pressed by mouse).

DockPanel Suite Documentation, Release 2.10

• Document tabs have close buttons.

• Dock target indicators are transparent.

Visual Studio 2012 Themes

When Microsoft designed Visual Studio 2012, they came across the idea to ship a light theme, as well as a dark theme, instead of the blue theme of Visual Studio 2010.

dark theme, instead of the blue theme of Visual Studio 2010. Fig. 1.2: Figure 2: Visual

Fig. 1.2: Figure 2: Visual Studio 2012 Light Theme

There are lots of visual effect changes compared to Visual Studio 2010,

• Icons are removed from auto-hide strips.

• Auto-hide tabs, tool window, document tabs use simple rectangles instead of rounded.

• Separators are used in tool window tabs.

• Vertical splitters use a blurring effect to distinguish from horizontal ones.

By community request, in a later Update, the blue theme was also added back.

The noticeable changes in the blue theme are,

• Its inactive selected document tab is rendered with two blue colors. (the light and dark themes do not use this feature.)

• Its vertical splitters are rendered the same as the horizontal ones.

DockPanel Suite Documentation, Release 2.10

DockPanel Suite Documentation, Release 2.10 Fig. 1.3: Figure 3: Visual Studio 2012 Dark Theme 1.3. Themes

Fig. 1.3: Figure 3: Visual Studio 2012 Dark Theme

DockPanel Suite Documentation, Release 2.10

DockPanel Suite Documentation, Release 2.10 Fig. 1.4: Figure 4: Visual Studio 2012 Blue Theme 20 Chapter

Fig. 1.4: Figure 4: Visual Studio 2012 Blue Theme

DockPanel Suite Documentation, Release 2.10

Visual Studio 2013 Themes

Visual Studio 2013 ship all three themes by default (light, dark, and blue).

ship all three themes by default (light, dark, and blue). Fig. 1.5: Figure 5: Visual Studio

Fig. 1.5: Figure 5: Visual Studio 2013 Blue Theme

This time only small changes are introduced,

• A few colors have changed in the palette.

• Tool window tab separators are removed.

• Tool windows and documents use borders.

• Splitters follow Visual Studio 2012 blue theme style.

Visual Studio 2015 Themes

Visual Studio 2015 ship all three thems by default (light, dark, and blue).

This time except a few color changes in the palette, the look-and-feel is almost the same as Visual Studio 2013.

Visual Studio Color Theme Manager

During Visual Studio 2010 development, an extension was released by Microsoft for end users to design their own themes,

DockPanel Suite Documentation, Release 2.10

DockPanel Suite Documentation, Release 2.10 Fig. 1.6: Figure 6: Visual Studio 2015 Blue Theme 22 Chapter

Fig. 1.6: Figure 6: Visual Studio 2015 Blue Theme

DockPanel Suite Documentation, Release 2.10

Fig. 1.7: Figure 7: Color Theme Manager for Visual Studio

Fig. 1.7: Figure 7: Color Theme Manager for Visual Studio 2010

It can import/export themes to .vstheme files in XML format.

Starting from Visual Studio 2012, .vstheme files use a completely new schema, and Color Theme Manager changes to

a new design,

Related Resources

Installing DockPanel Suite On Windows

Basic Usages

Creating A New Theme

Existing Themes

1.3.2 Theming Basics

By Lex Li

This page shows you the basics about DockPanel Suite themes (2.11+).

DockPanel Suite Documentation, Release 2.10

DockPanel Suite Documentation, Release 2.10 Fig. 1.8: Figure 8: Color Theme Manager for Visual Studio 2012

Fig. 1.8: Figure 8: Color Theme Manager for Visual Studio 2012 and Above

DockPanel Suite Documentation, Release 2.10

In this article:

The Structure of A Theme

Visual Elements of A Theme

Related Resources

The Structure of A Theme

A theme is a collection of multiple elements which control the rendering effect of DockPanel Suite.

public class VS2012LightTheme : VS2012ThemeBase { public VS2012LightTheme() : base(Resources.vs2012light) { }
public
class
VS2012LightTheme
:
VS2012ThemeBase
{
public
VS2012LightTheme()
:
base(Resources.vs2012light)
{
}
}
public
abstract
class
VS2012ThemeBase
:
ThemeBase
{
public
VS2012ThemeBase(byte[]
resources,
IDockPaneSplitterControlFactory
splitterFactory,
IWindo
{
ColorPalette
=
new
DockPanelColorPalette(new
VS2012PaletteFactory(resources));
Skin
=
new
DockPanelSkin();
PaintingService
=
new
PaintingService();
ImageService
=
new
ImageService(this);
ToolStripRenderer
=
new
VisualStudioToolStripRenderer(ColorPalette);
Measures.SplitterSize
=
6;
Measures.AutoHideSplitterSize
=
3;
Measures.DockPadding
=
6;
ShowAutoHideContentOnHover
=
false;
Extender.DockPaneCaptionFactory
=
new
VS2012DockPaneCaptionFactory();
Extender.AutoHideStripFactory
=
new
VS2012AutoHideStripFactory();
Extender.AutoHideWindowFactory
=
new
VS2012AutoHideWindowFactory();
Extender.DockPaneStripFactory
=
new
VS2012DockPaneStripFactory();
Extender.DockPaneSplitterControlFactory
=
splitterFactory
??
new
VS2012DockPaneSplitterContr
Extender.WindowSplitterControlFactory
=
windowsSplitterFactory
??
new
VS2012WindowSplitterCo
Extender.DockWindowFactory
=
new
VS2012DockWindowFactory();
Extender.PaneIndicatorFactory
=
new
VS2012PaneIndicatorFactory();
Extender.PanelIndicatorFactory
=
new
VS2012PanelIndicatorFactory();
Extender.DockOutlineFactory
=
new
VS2012DockOutlineFactory();
Extender.DockIndicatorFactory
=
new
VS2012DockIndicatorFactory();
}
public
override
void
CleanUp(DockPanel
dockPanel)
{
PaintingService.CleanUp();
base.CleanUp(dockPanel);
}
}

2.11 release introduces the new palette based skins, which makes creating new themes much easier. By ex- porting .vstheme files from Visual Studio Color Theme Manager, and injecting them into the constructor of DockPanelColorPalette, the theme can extract the necessary colors from them.

DockPanel Suite Documentation, Release 2.10

Note: Visual Studio 2010 Color Theme Manager exported .vstheme files are not supported yet as it uses a different schema.

DockPanelSkin was a simple container of different kinds of colors. It was mainly developed for Visual Studio 2005 theme.

The ThemeBase class allows its rendering effect to be further changed by overriding properties of its Extender property. The above sample shows that multiple elements are customized,

• DockPaneCapture

• DockPaneStrip

• DockPaneSplitter

• AutoHideStrip

• AutoHideWindow

• DockWindow

• DockWindowSplitterControl

• DockOutline

• PaneIndicator

• PanelIndicator

Measures stores several numbers that control size/length of a few controls. SplitterSize and AutoHideSplitterSize is here to control the sizes of splitters.

CleanUp method should be implemented if a customized IPaintingService implementation is used to clean up GDI+ resources.

You can refer to each of the factory classes to see how a specific part of the theme is customized. Below we will simply check what exactly the above names are there in a theme by highlighting them in screen shots.

Visual Elements of A Theme

Here is a full screen shot of an application that uses DockPanel Suite.

DockPanel Suite Documentation, Release 2.10

DockPanel Suite Documentation, Release 2.10 So generally speaking, such an application employs multiple dock panes, which

So generally speaking, such an application employs multiple dock panes, which are highlighted,

employs multiple dock panes, which are highlighted, You can see five panes are there and between

You can see five panes are there and between panes, splitters are rendered.

A simple pane (such as pane 2 and 5) only contains a single dock content, but a complex pane (such as pane 1 and 4) can contains multiple dock contents.

For document panes, their strips (shown in red rectangle below) contain the tabs of the documents and are rendered at top, where clicking on a tab can switch to a document,

DockPanel Suite Documentation, Release 2.10

DockPanel Suite Documentation, Release 2.10 For tool window panes, their strips (shown in blue rectangle below

For tool window panes, their strips (shown in blue rectangle below ) contain the tabs of the tool windows and are rendered at bottom, where clicking on a tab can switch to a tool.

DockPanel Suite Documentation, Release 2.10

DockPanel Suite Documentation, Release 2.10 Visual Studio 2012 themes use separators between adjacent tool window tabs,

Visual Studio 2012 themes use separators between adjacent tool window tabs, while Visual Studio 2013 and above uses more complicated borders.

Tool window pane strip is suppressed if the pane only contains a single tool window.

Tool window panes also have their captions (shown in red rectangle above) rendering at top, where the tool window can be closed or hidden.

When a visible tool window pane becomes auto-hide, it would be rendered on an auto-hide strip as a tab,

When a visible tool window pane becomes auto-hide, it would be rendered on an auto-hide strip

DockPanel Suite Documentation, Release 2.10

When this auto-hide tool window tab is activated, the tool window slides out and shows in an auto-hide window,

DockPanel Suite Documentation, Release 2.10

DockPanel Suite Documentation, Release 2.10

When a dock content is dragged and move over the dock panel area, indicator icons are displayed to show which target locations this content can be dropped at, and the outline (the blue rectangle in the figure) of the content will also be rendered to show how the content would look like once dropped.

to show how the content would look like once dropped. It is very important to understand

It is very important to understand such elements and then you can see how the Extender mechanism works.

Internally the method ThemeBase.ApplyTo can be used to associate themes with context menu strips and other

DockPanel Suite Documentation, Release 2.10

menu strips. If you are developing an application, this method allows the theme renderer be used for other menu strips outside of DockPanel Suite scope.

Related Resources

Installing DockPanel Suite On Windows

Basic Usages

Creating A New Theme

Existing Themes

1.3.3 Existing Themes

By Lex Li

This page shows you what are the existing themes and how to use them.

In this article

Visual Studio 2003 Theme

Visual Studio 2005 Theme

Visual Studio 2012 Themes

Visual Studio 2013 Themes

Visual Studio 2015 Themes

Visual Studio 2010 Blue Theme

Visual Studio 2005 Theme for Multiple UI Threads

Switching among Themes

Related Resources

Visual Studio 2003 Theme

This is a theme that simulates Visual Studio 2003.

To apply this theme, the following code can be used,

var

this.dockPanel.Theme

theme

=

new

VS2003Theme();

=

theme;

Note: For 2.10 and above, a reference to WeifenLuo.WinFormsUI.Docking.ThemeVS2003.dll (from NuGet package DockPanelSuite.ThemeVS2003) is needed.

Visual Studio 2005 Theme

This is the default theme of DockPanel Suite. When you create a new instance of DockPanel class, the dock panel and its contents use this theme automatically.

DockPanel Suite Documentation, Release 2.10

Visual Studio 2012 Themes

Three themes are there to simulate Visual Studio 2012 Blue, Light and Dark.

Note: The Light theme is introduced in 2.9 release. The Dark theme is introduced in 2.11 release.

To apply the Blue theme, the following code can be used,

var

this.dockPanel.Theme

theme

=

new

VS2012BlueTheme();

=

theme;

To apply the Light theme, the following code can be used,

var

this.dockPanel.Theme

theme

=

new

VS2012LightTheme();

=

theme;

To apply the Dark theme, the following code can be used,

var

this.dockPanel.Theme

theme

=

new

VS2012DarkTheme();

=

theme;

Note: For 2.10, a reference to WeifenLuo.WinFormsUI.Docking.ThemeVS2012Light.dll (from NuGet package DockPanelSuite.ThemeVS2012Light) is needed.

Note: For 2.11 and above, a reference to WeifenLuo.WinFormsUI.Docking.ThemeVS2012.dll (from NuGet package DockPanelSuite.ThemeVS2012) is needed.

Visual Studio 2013 Themes

Three themes are there to simulate Visual Studio 2013 Blue, Light and Dark.

Note: The Blue theme is introduced in 2.10 release. The Dark and Light themes is introduced in 2.11 release.

To apply the Blue theme, the following code can be used,

var

this.dockPanel.Theme

theme

=

new

VS2013BlueTheme();

=

theme;

To apply the Light theme, the following code can be used,

var

this.dockPanel.Theme

theme

=

new

VS2013LightTheme();

=

theme;

To apply the Dark theme, the following code can be used,

var

this.dockPanel.Theme

theme

=

new

VS2013DarkTheme();

=

theme;

Note:

For 2.10, a reference to WeifenLuo.WinFormsUI.Docking.ThemeVS2013Blue.dll (from NuGet

DockPanel Suite Documentation, Release 2.10

Note: For 2.11 and above, a reference to WeifenLuo.WinFormsUI.Docking.ThemeVS2013.dll (from NuGet package DockPanelSuite.ThemeVS2013) is needed.

Visual Studio 2015 Themes

Three themes are there to simulate Visual Studio 2015 Blue, Light and Dark.

Note: The Blue, Dark and Light themes is introduced in 2.11 release.

To apply the Blue theme, the following code can be used,

var

this.dockPanel.Theme

theme

=

new

VS2015BlueTheme();

=

theme;

To apply the Light theme, the following code can be used,

var

this.dockPanel.Theme

theme

=

new

VS2015LightTheme();

=

theme;

To apply the Dark theme, the following code can be used,

var

this.dockPanel.Theme

theme

=

new

VS2015DarkTheme();

=

theme;

Note: For 2.11 and above, a reference to WeifenLuo.WinFormsUI.Docking.ThemeVS2015.dll (from NuGet package DockPanelSuite.ThemeVS2015) is needed.

Visual Studio 2010 Blue Theme

This theme is not yet completed due to its visual complexity, so it is only shipped in source code.

Visual Studio 2005 Theme for Multiple UI Threads

This is derived from the default theme of DockPanel Suite. It is released for applications that use multiple UI threads only, so not recommended for general usage.

Switching among Themes

The sample project demonstrates how to switch among themes in MainForm.SetSchema,

Related Resources

Installing DockPanel Suite On Windows

Basic Usages

Creating A New Theme

DockPanel Suite Documentation, Release 2.10

1.3.4 Creating A New Theme

By Lex Li

This page shows you how to create a new theme.

In this article

Start A New Theme

Related Resources

Start A New Theme

Once you know the basics of Visual Studio 2012/2013 themes, it is quite easy to start your own themes. Below we show an example of developing a custom Visual Studio 2012 theme based on the Light theme.

1.

Open Visual Studio 2012 and install Color Theme Manager extension.

2.

Create a new theme there and export as a .vstheme file.

3.

Open ThemeVS2012.csproj.

4.

Put the .vstheme file into ThemeVS2012\Resources folder and add it to Resources.resx.

5.

Copy ThemeVS2012\VS2012LightTheme.cs to ThemeVS2012\VS2012CustomTheme.

6.

Open VS2012CustomTheme.cs, and rename the class to VS2012CustomTheme.

7.

Change its constructor to use the .vstheme file from the resources.

8.

(Optional) Write your own element factory classes and bind them to Theme.Extender if you want to further customize rendering effect.

Note:

If you don’t want to use Color Theme Manager, please analyze VS2012PaletteFactory source code to

see from where each colors come.

Once the project can compile without an error, you get your own theme ready for testing.

Related Resources

Installing DockPanel Suite On Windows

Basic Usages

Existing Themes

1.4 Contribute

Note: We reuse the ASP.NET docs style guide.

DockPanel Suite Documentation, Release 2.10

1.4.1 GitHub Guide

By Lex Li

This page shows you how to use DockPanel Suite repo on GitHub to collaborate.

In this article:

Submitting a Patch

Reviewing a Patch

Reporting a Bug

Reviewing a Bug

Asking a Question

Answering a Question

Overview of Issue Tags

Suggestions on Creating Pull Requests

Suggestions on Reviewing Pull Requests

Related Resources

Submitting a Patch

An issue might be opened to discuss with the maintainers before creating the patch. This helps the maintainers track your progress, and provide guidance if needed.

1. Learn about GitHub via http://help.github.com/.

2. Create your own fork from the main repo at https://github.com/dockpanelsuite/dockpanelsuite.

3. Create a new branch with a meaningful name.

4. Make the changes on this new branch in your fork, and test it fully.

5. Create a pull request back (link the new branch in your fork to the master branch of main repo).

6. Document all your changes in details as part of the pull request, which is critical to better communicate with maintainers.

Patches will be reviewed and merged as early as possible.

Note: If the patch is large, it might take several weeks to review and merge.

Note: To see what makes a good pull request, please follow Suggestions on Creating Pull Requests section.

Reviewing a Patch

Maintainers should respond to new pull requests as early as possible by commenting like this,

• “Acknowledged. Will start review.”

which gives the contributors a hint that the process has begun.

Further responses can be like,

• “Comments have been left at **. Please revise your patch like this,”

DockPanel Suite Documentation, Release 2.10

• “Reviewed. ** will be merged, while ** will not. The reasons are,”

which will keep all discussions public to reveal all necessary technical information for future reference.

Reporting a Bug

Note: If you already have a patch for the bug, please follow Submitting a Patch section.

Note: If you are not sure whether it is a bug, please follow Asking a Question section.

1. Learn about GitHub via http://help.github.com/.

2. Review existing issues at https://github.com/dockpanelsuite/dockpanelsuite/issues that are marked as bug or enhancement to avoid duplicate.

3. Please also review all open bugs on SF.net tracker before reporting. Existing bugs recorded on SF.net may be gradually fixed in this fork, so you don’t need to create duplicate items on GitHub.

4. Create a new issue on https://github.com/dockpanelsuite/dockpanelsuite/issues and provide all information in details.

You are welcome to provide step by step instructions, as that can help other reproduce and investigate the issue. If you are willing to share a sample project, please use a service such as DropBox or OneDrive.

Reviewing a Bug

Maintainers should respond to bug reports as early as possible by commenting like this,

• “Acknowledged. Will start review.”

which gives the contributors a hint that the process has begun.

Further responses can be like,

• “Could not reproduce it. Please provide more information to assist investigation such as **,”

• “Reviewed. ** is a bug that can be reproduced. Will perform further investigation on how to resolve it. This may take a long time.”

which will keep all discussions public to reveal all necessary technical information for future reference.

Asking a Question

Asking a Question on StackOverflow (Recommended)

1. Log into StackOverflow.

2. Before starting asking a new question, please review all questions under tag dockpanel-suite in case yours has already been answered.

3. Click Ask Question to create a new question.

4. Add tag dockpanel-suite to this question, and also include all information in details.

Then you can wait till users reply to your question.

DockPanel Suite Documentation, Release 2.10

Asking a Question on GitHub

1. Learn about GitHub via http://help.github.com/.

2. Before creating the issue, please review all existing issues especially our FAQ in case the issue has already been reported and resolved.

3. Create a new issue on https://github.com/dockpanelsuite/dockpanelsuite/issues and provide all information in details.

Answering a Question

Maintainers might join StackOverflow and monitor discussions under dockpanel-suite tag.

Maintainers should respond to questions on GitHub as early as possible by commenting like this,

• “Acknowledged. Will start review.”

which gives the contributors a hint that the process has begun.

Further responses can be like,

• “Could not reproduce it. Please provide more information to assist investigation such as **,”

• “Reviewed. ** is a bug that can be reproduced. Will perform further investigation on how to resolve it. This may take a long time.”

which will keep all discussions public to reveal all necessary technical information for future reference.

Tag such an issue with question tag.

Close such issues once a meaningful answer is given.

Mark an issue as faq candidate if it should be considered as an FAQ.

Overview of Issue Tags

Maintainers should use the tags as early as possible so as to help each other to easily track the progress. The decoration tags are most useful for items which are not yet assigned to milestones.

Tags for Item Categories

The following are used to assign an item to a specific category,

bug This item was reported as a bug of this product. The reporter expects a fix.

enhancement This item was reported as an enhancement request. The reporter expects a certain feature to be enhanced or a new feature to be implemented.

task This item was reported as a task. The reporter expects a maintainer to perform a piece of work (usually not development).

idea This item was reported as a new idea. The reporter expects some discussion on a feature request. Once discussed, this item might be upgraded to an enhancement.

question This item was reported as a question. The reporter expects some discussion on a problem met about this product. Once discussed, this item might be upgraded to a bug, an enhancement, or an idea.

tech debt This item was reported as bad smells detected in the code base. The reporter expects changes in the code base to remove the bad smells.

DockPanel Suite Documentation, Release 2.10

pull request This item was used to handle a pull request.

Tags for Decoration

The following are used to decorate an item so as to make it easy to see its status and required actions,

dependency bug This only applies to bug items. It means the bug was caused by a bug of one of the dependencies (such as bugs of .NET Framework/Mono bugs, or bugs of the operating systems).

not an issue This means after discussion, there is nothing to be done further (usually for false positives).

wontfix This means the item (usually bugs) won’t be fixed due to a strong justification. An agreement must be achieved among the maintainers.

duplicate This means the item is exactly the same as another existing item. The maintainers should explicitly point out which item will be the focus and mark all the rest as duplicate.

tentative This means based on the provided information it is not likely to move on. The reporter should provide more information and drive the discussion.

soon to close This means there is little left to do on the item. The maintainers are going to close the item after a few more days (usually applied to tentative and cannot reproduce items).

cannot reproduce This means the maintainers failed to reproduce the symptoms described in a bug report. The reporter should provide more information (process dumps, sample projects, screen shots, video clips and so on) and drive the investigation.

in progress This means the item has been actively investigated by the maintainers.

up for grabs This means community contribution is welcome.

Suggestions on Creating Pull Requests

All pull requests are appreciated (even if some we cannot merge). The following can make the pull requests simpler for reviewers, so hope you can follow them.

• If possible, send multiple pull requests for individual tasks and avoid a pull request for multiple tasks. Properly isolating changes to meaningful batches makes it quicker to analyze and assert the changes.

• Fork and create a new branch with a meaningful name first before making the changes.

• Squash all commits on this new branch to only one or two before sending the pull request.

• Wait for comments from the reviewers. It usually takes weeks as the reviewers might not be able to finish quickly. Don’t make further changes at this stage to avoid changes of this pull request.

• Revise the code based on feedbacks, and then make a second commit with necessary changes and push to the branch in your fork, where GitHub automatically appends it to the pull request for further review.

Then the reviewers will decide whether to accept or reject the pull request based on code quality.

One important notice is that some pull requests might not be accepted, but they are still valuable to the community,

• It contains a nice-to-have feature (such as options to enable/disable part of a theme, or a visual element) for some users but not all.

• It introduces a feature (such as new visual elements) that goes beyond Visual Studio look and feel.

Such pull requests are of great value of course. But since the primary goal of DPS is to simulate Visual Studio look and feel, and the code base is already huge to maintain, we try to avoid bringing in non-core features.

DockPanel Suite Documentation, Release 2.10

Suggestions on Reviewing Pull Requests

Please leave a message that you are going to review a pull request. That should let the submitter know it’s been reviewed.

Leave all comments at a time, so that the submitter can revise them altogether to form a new commit.

Decide carefully whether to accept or reject a pull request. Leave explanation for future reference.

Related Resources

Installing DockPanel Suite On Windows

Basic Usages

Existing Themes

DockPanel Suite Documentation, Release 2.10

CHAPTER 2

Contribute to Documentation

The documentation on this site is the handiwork of our many contributors. We accept pull requests! But you’re more likely to have yours accepted if you follow these guidelines:

1. Read the Contributing Guide.