Getting started with Metro UI in DotNetBar for WinForms
DotNetBar for Windows Forms includes set of Metro controls to help you develop great looking Metro look and feel user interface for your apps. Usually Metro applications will use at least:
The easiest way to get started is to simply use new form template in Visual Studio that we provide. In Visual Studio go to Project->Add Windows Forms in your Windows Forms project and from the list choose Metro App Form (you might need to scroll form template list in some versions of VS.NET to find this template). Template will give you basic shell like this:
MetroAppForm can show any control as modal panel. The control will be centered inside of the form and it will cover all form content but leave visible only form title (if MetroShell is used). It will also disable all commands on MetroShell practically giving you same functionality as modal dialog. To show a control as modal panel simply call ShowModalPanel method on MetroAppForm. You will specify control you want shown as modal panel as well as optional slide animation that will accompany showing of the control. To close the modal panel call CloseModalPanel method and pass reference to your control as well. You can also specify the slide animation to be performed while panel is taken out of the view.
You can stack multiple modal panels on top of each other by calling ShowModalPanel method.
Key MetroAppForm Properties
Following key properties are provided on MetroAppForm to control its behavior:
- BorderColor – allows you to override theme border colors for the form.
- BorderThickness – specifies the custom form border thickness.
- CloseBoxVisible – specifies whether x button in top-right corner of the form chrome that closes the form is visible.
- FormResizeBorder – specifies the thickness in pixels around the form edge which allows user to resize the form.
- IsActive – returns whether form is active.
- MetroShell – returns reference to MetroShell control that provides form chrome.
- Sizable – specifies whether form can be resized.
MetroAppForm provides its own Metro styled system menus. The menu text can be localized using standard WinForms localization by setting following properties on MetroAppForm:
SystemMenuClose, SystemMenuMaximize, SystemMenuMinimize, SystemMenuMove, SystemMenuRestore and SystemMenuSize.
MetroForm is a standard form with window chrome which you can use for modal dialogs (although we recommend using modal panels instead). The easiest way to add new MetroForm to your project is using templates we provide. In Visual Studio go to Project->Add Windows Forms in your Windows Forms project and from the list choose Metro Form (you might need to scroll form template list in some versions of VS.NET to find this template). Template will give you form like this:
MetroShell is a root control that is docked to the top of the form and it provides form chrome (system buttons to close, minimize and maximize form), backstage or application menu, quick access toolbar and top-level application tabs. Many elements that are displayed by MetroShell control are optional, so for example you do not have to have application menu or backstage and you can remove it at design-time. Same applies to quick access toolbars and even tabs.
If your application does not have need for application menu simply selection File button and delete it.
Quick Access Toolbar
You can provide default commands by adding them at design-time. To add button to QAT at design-time right-click the QAT and choose Create Button context-menu command. If you want some buttons in QAT to be permanently there and which end-user cannot remove, set CanCustomize=false on those buttons.
User can add commands to QAT from MetroToolbar controls by right-clicking the command and choosing appropriate command from context-menu. Note that MetroToolbar toolbars that have commands that can be added to QAT should be available, i.e. loaded, when MetroShell control is created as well. This will ensure that any customization that end-user has made to the QAT can be applied and loaded. You load and save QAT customization by serializing MetroShell.QatLayout property which is simple text property an which can be serialized to any storage of your choice, like registry or text file.
To prevent buttons from MetroToolbar from being added to the QAT set CanCustomize=false on those buttons. MetroToolbar.Text property will be used in QAT Customization Dialog to categorize available QAT commands.
Help and Settings Buttons
These buttons do not necessarily have to be used for Help and Settings, you can change their text using SettingsButtonText and HelpButtonText properties. Events SettingsButtonClick and HelpButtonClick are invoked when buttons are clicked. You can hide any of the buttons using SettingsButtonVisible and HelpButtonVisible properties all on MetroShell control.
Key MetroShell Control Properties, Methods and Events
- CanCustomize – Indicates whether control can be customized and items added to Quick Access Toolbar by end-user.
- CaptionFont – Indicates custom Font that is used to render the form caption.
- CaptionHeight – Indicates custom height for the form caption.
- CaptionVisible – Indicates whether control shows the caption which includes system buttons, form title and QAT.
- CategorizeMode – Specifies how commands are categorized in QAT Customize Dialog.
- GlobalContextMenuBar – Specifies Context menu bar associated with the this control which is used as part of Global Items feature.
- Items – Gets the collection of the items that appear in tab-strip area of the control.
- MouseWheelTabScrollEnabled – Indicates whether selected tab is changed when mouse wheel is used over the tab-strip.
- QatFrequentCommands – Get the collection of the commands that are displayed on the Customize Quick Access Toolbar menu and which allow end-user to quickly add or remove them from QAT. Commands shown here should be available on MetroToolbar controls.
- QatLayout – Gets or sets the Quick Access Toolbar layout. This property is used to save and load the QAT customizations.
- QatLayoutChanged – Gets whether end-user made any customizations to QAT.
- QuickToolbarItems – Gets collection that holds all items displayed on QAT.
- SelectedTab – Gets or sets currently selected Metro tab.
- SystemText – Gets the object that holds all internal strings MetroShell control uses. When performing Localization you will change properties on this object.
- TabStripFont – Gets or sets the font that Metro tab-strip area uses.
- TitleText – Specifies the form title-bar text. By default control uses Form.Text to display it on title-bar, but if you wish that displayed title text is different from Form.Text or if you wish to use our text-markup, set this property.
- UseCustomizeDialog – Indicates whether built-in customize dialog is used to customize the quick access toolbar. You can handle the EnterCustomize event to display your custom dialog instead of built-in dialog for customization.
- UseExternalCustomization – Indicates whether custom context menu content is used instead of built-in customization menu which is shown when end-user clicks the buttons on MetroToolbar. When set to true you must handle BeforeCustomizeMenuPopup event to provide your own customize context menu commands.
- BeforeQatCustomizeDialog – Occurs before Quick Access Toolbar dialog is displayed. This event provides the opportunity to cancel the showing of built-in dialog and display custom customization dialog.
- AfterQatCustomizeDialog – Occurs after the Quick Access Toolbar dialog is closed.
- AfterQatDialogChangesApplied – Occurs after any changes done on the Quick Access Toolbar dialog are applied to the actual Quick Access Toolbar.
- BeforeAddItemToQuickAccessToolbar – Occurs before an item is added to the quick access toolbar as result of user action. This event provides ability to cancel the addition of the item by setting the Cancel=true of event arguments.
- BeforeCustomizeMenuPopup – Occurs just before the customize popup menu is displayed and provides the ability to cancel the menu display as well as to add/remove the menu items from the customize popup menu.
- BeforeRemoveItemFromQuickAccessToolbar – Occurs before an item is removed from the quick access toolbar as result of user action. This event provides ability to cancel the addition of the item by setting the Cancel=true of event arguments.
- TitleTextMarkupLinkClick – Occurs when text markup link from TitleText markup is clicked. Markup links can be created using “a” tag.
- AddItemToQuickAccessToolbar – Adds an object that inherits from BaseItem to QAT.
- RemoveItemFromQuickAccessToolbar – Remove an item from QAT.
- CreateTab – Creates a metro tab and associated panel.
- ShowQatCustomizeDialog – Shows Quick Access Toolbar customize dialog.
- RegisterToolbar – Registers MetroToolbar with control so it can participate in QAT customization.
- UnregisterToolbar – Removes MetroToolbar from QAT customization.
MetroToolbar is a toolbar like control which displays the most frequently used items at all times but also allows the access to extra or infrequently used items when expanded. Here is MetroToolbar control in its default state displaying the top-level items:
Notice the button with 3 dots in right-hand side. That is expand button which expands the toolbar and shows extra toolbar items as shown below:
Toolbar will be automatically collapsed once extra button is clicked or mouse is clicked somewhere outside the toolbar.
Working with MetroToolbar is very simple. At design-time right-click toolbar to create items. Drag & drop items between top-level and extra line to change their position.
Since MetroToolbar shows the extra content inline, meaning its size and location is changed to show it, we recommend placing the control on the form without setting its Dock or even Anchor properties. Reason for this is that when MetroToolbar expands it should not change the layout of the other controls, which would happen if you set Dock or Anchor properties. Expanding the MetroToolbar should simply cover other control temporary while choice of extra items is being made.
Key MetroToolbar Properties
- AnimationSpeed – Specifies toolbar collapse/expand animation speed duration in milliseconds. Default value is 150 milliseconds. Set to zero, 0 to disable animation.
- AutoCollapse – Specifies whether control is automatically collapsed, i.e. Expanded property set to False, if control was expanded and any button on the control was clicked or mouse is clicked elsewhere, parent form has lost input focus or some other control gains input focus.
- AutoRegister – Specifies whether toolbar is attempted to be automatically registered with parent MetroShell control so it can participate in Quick Access Toolbar operations. Default value is true.
- ExpandDirection – Specifies expand direction for the toolbar. Default value is Auto.
- Expanded – Indicates whether control is expanded or not. When control is expanded both main and extra toolbar items are visible. When collapsed only main items are visible.
- ExtraItems – Gets collection that holds extra items displayed on toolbar when expanded.
- Items – Gets collection of top-level items toolbar displays at all times.
- ItemSpacing – Specifies spacing between toolbar items.
Key MetroToolbar Events
- ExpandedChanging – Occurs before Expanded property has changed, i.e. control expanded or collapsed and allows you to cancel action by setting Cancel=true on event arguments.
- ExpandedChanged – Occurs after Expanded property value has changed, i.e. control was expanded or collapsed.
Metro UI uses StyleManager component to control its appearance. We have developed proprietary color scheme generation algorithms that will take two colors you specify and generate complete color scheme for all UI elements in a way that color scheme is visually pleasing and is perfect fit for Metro UI. StyleManager is automatically added to the form once you add MetroShell control. We provide number of per-defined very good looking color combinations but please experiment yourself.
Our color scheme generation algorithm takes 2 colors as input:
- Canvas color which is a background color for forms etc.
- Base color which is a master signature color for the color scheme and which is used with Canvas color to generate whole color scheme.
These colors can be specified on StyleManager.MetroColorParameters object. Simply select it in VS.NET property dialog and change its values as shown below:
Ambient Properties i.e. BackColor, ForeColor
When Metro style is chosen on StyleManager all controls on the forms will automatically receive the Metro color scheme ambient settings, meaning their BackColor and ForeColor properties will be set to match current Metro theme. There are cases where you might want to have custom BackColor and/or ForeColor properties set on controls and you do not want StyleManager to override them. In that case add StyleManagerAmbient component to your form which manages which controls have ambient properties set. When you add StyleManagerAmbient component to your form all controls will receive an attached property EnableAmbientSettings which you can use to indicate which ambient properties, if any, StyleManager will change on that specific control.
How to change metro color table
Metro specific controls like MetroTab, MetroShell, MetroForm, MetroToolbar and MetroStatusBar use colors from MetroColorTable object. To customize these system colors you need to access current MetroColorTable and change appropriate properties on it. For example to change the MetroForm caption color that is rendered by MetroShell you can use following code:
MetroColorTable table = DevComponents.DotNetBar.Metro.Rendering.MetroRender.GetColorTable(); table.MetroTab.ActiveCaptionText = Color.Green; table.MetroTab.InactiveCaptionText = Color.Red;
Note that if you change current style or change StyleManager.MetroColorParameters any changes made to MetroColorTable will be overwritten and need to be done again.
No related posts.