MetroSidebar Docs

Getting Started

What is MetroSidebar!?

MetroSidebar is an application platform for creating tiles using .NET WPF C#/VB. If you are a .NET developer, you are also a MetroSidebar developer!

Beyond the standard .NET features you are accustomed to, MetroSidebar gives you a set special APIs.

MetroSidebar also takes care of all the “desktop” stuff you don’t want to think about, like installers, so you can focus purely on tile development.

How do I get started?

  1. Download and install MetroSidebar
  2. Follow the tutorial below

MetroSidebar Hello World

In an effort to kick-start your MetroSidebar tile development, and to promote good MetroSidebar programming standards, we’ve prepared a tile sample. You can download the MetroSidebar Tile Samples from GitHub You can use it as a starting point to understand the structure of a MetroSidebar tile.

It starts with an ini file

Technically speaking, a MetroSidebar tile is simply a collection of files (ini/dll/images) contained within a directory. In order for MetroSidebar to understand how to interact with this folder it looks for a file in the root directory called tile.ini. This is a simple ini file that tells MetroSidebar everything it needs to know about your tile.

tile.ini from MetroSidebar HelloWorld:

[MetroSidebar]

Name=Hello World

Publisher=MetroSidebar

Version=1.0.0

As you can see each MetroSidebar tile requires:

  1. Name - the name of your tile for development (when you submit a MetroSidebar tile you choose its official name)
  2. Publisher - the name of the publisher (in this case your name)
  3. Version - the version of your tile for development

tile.dll

tile.dll Is the application developed using .NET WPF C#/VB which contains everything

Let development begin!

Now that you have a sense for the contents of the MetroSidebar Tile, start having some fun and making some changes! Simply edit any file, save it.


Let's open HelloWorld.sln project with Microsoft Visual Studio.

The MetroSidebar tile has two interface elements that users may interact with;

  1. A UserControl MainControl.xaml – The main view of your tile. This UserControl will be loaded when MetroSidebar starts your tile.
  2. A settings window Settings.xaml – a window which is displayed when the user clicks on "settings" button in the charm bar.

As you may notice MetroSidebar tile uses the reference MetroSidebarTile from MetroSidebarTile.dll

MetroSidebarTile.dll is important because:

  1. Tile Interface – It helps MetroSidebar to recognize your dll file and transforms it into a MetroSidebar tile.
  2. SettingsManager – It helps you save/read private settings for you tile.
  3. SettingsManager.SettingsFolder – It helps you to get where the private settings are stored.
  4. SettingsManager.Path – It helps you to get the root directory of your tile.

Saving private settings for your tile

SettingsManager _settingsManager = new SettingsManager();

_settingsManager.ID = this;


SettingsManager.SettingData _mySetting = new SettingsManager.SettingData() { keyword = "mysetting", value = myvalue };


List SettingsCollection = new List();

SettingsCollection.Add(_mySetting);


_settingsManager.SaveSettings(SettingsCollection);

Reading private settings for your tile

SettingsManager _settingsManager = new SettingsManager();

_settingsManager.ID = this;


string _mySetting = _settingsManager.GetSetting("mysetting");

Getting the private settings directory of your tile

SettingsManager _settingsManager = new SettingsManager();

_settingsManager.ID = this;


string _mySettingDirectory = _settingsManager.SettingsFolder;

Getting the root directory of your tile

SettingsManager _settingsManager = new SettingsManager();

_settingsManager.ID = this;


string _myRootDirectory = _settingsManager.Path;

tile.cs

tile.cs contains the basic information for your tile.

namespace HelloWorld

{

  public class Tile : MetroSidebarTile.Tile

  {

    public UserControl MainControl()

    {

      return new MainControl();

    }

    public Window SettingsWindow()

    {

      return null;

    }

    public int Height()

    {

      return 120;

    }

    public int LargeHeight()

    {

      return 264;

    }

    public bool Separator()

    {

      return true;

    }

    public string Background()

    {

      return @"#d34500";

    }

  }

}

Understanding MetroSidebar tile.cs

  • MainControl() - Is the main view of the tile.
  • SettingsWindow() - Is the settings window that shows up when the user clicks the settings button in the charm bar.
  • Height() - Is the default size of the tile.
  • LargeHeight() - Is the large size of the tile.
  • Separator() - Is the line at the bottom of the tile (it includes the gradient pattern).
  • Background() - Is the background color of the tile.

You'll note the SettingsWindow() in this example is null, this means the tile has no settings window.

If Height() has the same value as LargeHeight() then the tile is not resizable.

Add the MetroSidebar Tile

Now that you understand the tile.ini and developed your tile, let's add the MetroSidebar Tile and see what happens.

  1. Go to the MetroSidebar menu
  2. Choose "Add dev tile..." and browse to your MetroSidebar tile directory on your hard drive
  3. Press OK

Voila! The MetroSidebar tile was added! You should see your tile on MetroSidebar. and you're now a MetroSidebar developer.