CAUBLESTONE INK

.net development and other geeky stuff

Tutorial – Google Desktop Sidebar – Hello World Part 1, A simple plug-in

Posted on December 10th, 2006


Requirements

.Net Framework SDK 1.1
Google Desktop SDK

Downloads

The zip file listed here is all inclusive of all four tutorial parts. We broke up the article into four parts for ease of reading. Included in the zip is a Word doc version of all four articles.

Download (231KB)

Purpose

In this article I intend to show you how to build a simple Google Desktop Sidebar (GDS) component. The entire source is in C# 1.1. We assume that all developers looking at this article are familiar with writing code in C# and the .Net framework. For this component we will be doing a simple Hello World type sample. We will show screenshots where appropriate. Otherwise we assume you know your way around.

What it shows

We intend to show you how to hook up a basic no frills .Net C# GDS component. What we have done is setup some basic modules under the folder GoogleBase that you can re-use in any component that you develop. These files wrap up all the API and com interaction that Google had setup in the samples sdk. Now it’s easy for you to use. In the article we will show you how to setup the component. Work with a title changing. Adjusting Layout formats (the canned ones). Adding content items. Using the default reader pane, and setting up Property pages.

This tutorial will walk you through the steps taken to get where the sample code is.

Project Setup

To start with create a new solution with and add a Class Library project. If you have not downloaded the code for this article please do so now as it will have some base files you will need to get going. Also, you need to make sure you have the Google Desktop SDK installed for this to work.

Copy and include the GoogleBase folder and all of it’s contents from the zip file into your project. These modules setup the following, ImageConverter object for getting your resource streams down to COM layer, the COM API, structures, etc needed by the GDK, and the base property page object that you can inherit from in order to create your property pages.

Once you have the files include you need to add some references to your project. The first two references are needed for the plug-in to work. In the references window click on the COM Tab and find the following two objects (figure 1) and add them to your project.

Once you have selected those objects it will create the necessary Interop dll’s needed since we are interacting with COM objects instead of managed code.

You also need to include the following references:

  • System.Drawing
  • System.Windows.Forms

Once that is done you need to set your project properties. The Google Sidebar is a COM object so we need to build a COM library. To do so we need to enable that in our project properties. So open your project properties and set the basics like Assembly name, root namespace, etc. Once you have that done goto the Configuration Properties -> Build section and at the bottom of your options change the Register for COM Interop to TRUE. This will enable us to build a com library.

That’s the basic setup for the project. Now we need to start putting together the basic plug-in.

Compilation Notes

When building a COM library you will need some registration functions in your code to allow it to hook in properly. We will show that after we get the basic plug-in up and running with a title.

However, once you compile and register your component with the GD Sidebar you cannot modify it unless you exit the Sidebar application. This will remove the hooks so you can re-compile and re-register. Tedious process if you are doing a lot of testing but it works.

Your first plug-in

Ok, lets setup our first plug-in. Create a new Class file in your project and the following includes for the file.

using System;
using System.Text;
using System.Runtime.InteropServices;
using System.Windows.Forms;
using System.IO;

// used for Registry / Com interop registration
using Microsoft.Win32;
using Google.Base;
// Base module to ease plug-in development
using Google.Base.Utils;
// Base module to ease plug-in development
using GoogleDesktopAPILib;
// Google Type libraries
using GoogleDesktopDisplayLib;
// Google Type libraries

Once you have these in let’s create our first plug-in class. For your class, add the following inheritance chain (or cut / paste and change your class name):

public class HelloWorldPlugin : GoogleDesktopDisplayPluginHelperClass, IGoogleDesktopDisplayPluginHandler, ISpecifyPropertyPages, IObjectWithSite, IPersistStreamInit

Once you have the class inheritance model in place use the Class view to go in and implement all the interfaces.

Now let’s setup some of our base internal values that we will use with our com object. These values will be used with the registration and read by the GDS when you view available plug-ins.

// since this is a com object we can store some info as static members.
static string baseTitle = "Hello World";
static string pluginName = "Hello World";
static string pluginDesc = "Hello World sample written in C#";

There is one other item you must add and it is extremely important. All COM objects need a GUID. So let’s add ours. Using the GUIDGEN utility from the framework choose the registry format to generate and take the value and add it to our class in the following ways:

[GuidAttribute("A674FDFF-D816-4eaf-9D5E-97317158733E")]
public class HelloWorldPlugin : GoogleDesktopDisplayPluginHelperClass, IGoogleDesktopDisplayPluginHandler, ISpecifyPropertyPages, IObjectWithSite, IPersistStreamInit
{
  // You must set a control GUID and it must match the guid attribute in order to work static string     controlGuid = "{A674FDFF-D816-4eaf-9D5E-97317158733E}";
}

The GUID’s in both places need to match. Without this you will be unable to register and use your plug-in.

You will also need to add the following member variables to the class:

// Member variables needed to hook into the Sidebar api
// this retrieves the site info for this plug-in.
private IGoogleDesktopDisplaySite displaySite;

// setup the layout options so the sidebar api knows how to render our information.
private GoogleDesktopDisplayContentItemLayout layout;

What this does is allows your app to hook into the panel that is showing your information. You will notice that we set up above a baseTitle object as static. You do not need to do this if you plan to have your title bar be dynamic. However it aids in this demonstration. The layout property will be used in a later tutorial.

Ok, now that we have some member variables, our interfaces implemented (roughly) and a class to use let’s build the constructor. Here we will setup an initial layout format as well as hook in the About box information. Real quick here about the about box. There are three distinct areas that text is put. The first line will use your logo if any and display your main info like a company name. If you use two new line commands it will kick your text down to the main content area.

Here is our constructor:

public HelloWorldPlugin()
{
  // setup some basic info.
  StringBuilder sb = new StringBuilder();
  sb.Append("Hello World Plug-in by CaubleStone Ink");
  sb.Append("//n//n");
  sb.Append("Shows how to setup basic functionality");
  sb.Append("for a sidebar plug-in.//n");
  this.layout = GoogleDesktopDisplayContentItemLayout.GDD_CONTENT_ITEM_LAYOUT_NOWRAP_ITEMS;   this.about_text = sb.ToString();
}

What we have done here is setup our basic info using a StringBuilder and setting our basic layout to just the plain jane no wrap value. Similar to the TODO list from Google.

Now lets walk through setting up the interfaces. By default you can leave all the interfaces alone however you may need to add a few new keywords on some to aid in the code generation and to help avoid memory leaks.

We are going to start with the IObjectWithSite interface class. All we need to do here is add the following so our app can get a handle to the display surface that the GDS will be using.

public void GetPageContainer(out Object site)
{
  // TODO: Add HelloWorldPlugin.GetPageContainer implementation
  site = null;

}

public void SetSite(Object site)
{
  displaySite = (IGoogleDesktopDisplaySite)site;
}

That’s it. We are slowly on our way to a plug-in. Now on to the next interface IGoogleDesktopDisplayPluginHandler. In this interface we will hook up our Title for our plug-in. What we plan on having is the plug-in adjust the title from Hello World to Hello World – Min when it’s minimized or maximized.

public new void OnCommand(GoogleDesktopDisplayPluginCommand command)
{
  if (command == GoogleDesktopDisplayPluginCommand.GDD_CMD_ABOUT_DLG)
  {
    // always throw this exception when you dont intend to override the default behavior
    // and you want the plug-in helper to do it[ES][SQ]s usual stuff.
    throw new NotImplementedException();
  }
}

public new void OnDisplayStateChange(GoogleDesktopDisplayTileDisplayState display_state)
{
  if (display_state == GoogleDesktopDisplayTileDisplayState.GDD_TILE_DISPLAY_STATE_MINIMIZED ||        display_state == GoogleDesktopDisplayTileDisplayState.GDD_TILE_DISPLAY_STATE_RESTORED)
  {
    // switching between minimized and normal mode, so update the title
    this.GetTitle();
  }
}

Notice that we have the new keyword on both of these methods. That is so it hides the underlying implementation (which there is none since it’s an interface) and helps us to prevent memory leaks. What we are doing is checking the value of display_state which comes in from the interface call. If the component has been minimized or restored it will change our title.

Let’s get our GetTitle function in here.

public void GetTitle()
{
  this.title = baseTitle;
  if (displaySite != null && displaySite.display_state ==  GoogleDesktopDisplayTileDisplayState.GDD_TILE_DISPLAY_STATE_MINIMIZED)
  {
    this.title = baseTitle + " - Min";
  }
}

What we are doing here is setting the underlying classes title property. We are starting with our baseTitle static variable and then appending the “- Min” to it if we are minimized.

Now we are finished with our basic code. Let’s get our registration functions in place so we can see the final results.

COM Registration functions

#region Registration functions
/// <summary>
/// Called when the plug-in is registered with the system. We add a few registry
/// keys and register with GoogleDesktop as a plug-in.
/// </summary>
/// <param name="t" /></param>
[ComRegisterFunctionAttribute]
static void RegisterFunction(Type t)
{
  try
  {
    // Set the "MiscStatus" value in registry to a valid value string keyName = @"CLSID\" + t.GUID.ToString("B");

    using (RegistryKey key = Registry.ClassesRoot.OpenSubKey(keyName, true))
    {
      key.CreateSubKey("Control").Close();
      using (RegistryKey subkey = key.CreateSubKey("MiscStatus"))
      {
        subkey.SetValue("", "whateveryouwant");
      }
      key.CreateSubKey("Control").Close();
      key.SetValue("",pluginName);
      using (RegistryKey subkey = key.CreateSubKey("Description"))
      {
        subkey.SetValue("", pluginDesc);
      }
    }

    // Create the registrar object
    GoogleDesktopRegistrarClass registrar = new GoogleDesktopRegistrarClass();

    // Start component registration by specifying our attributes
    object[] descriptions = { "Title", pluginName, "Description", pluginName, "Icon", "" };

    registrar.StartComponentRegistration(controlGuid, descriptions);
    // A single component can register for multiple plugins with Google Desktop.
    // Here we register a single display plug-in.
    IGoogleDesktopRegisterDisplayPlugin displayRegistration =
        (IGoogleDesktopRegisterDisplayPlugin)         registrar.GetRegistrationInterface("GoogleDesktop.DisplayPluginRegistration");

    displayRegistration.RegisterPlugin(controlGuid, false);
    // Done with component registration.
    registrar.FinishComponentRegistration();
  }
  catch (Exception e)
  {
    MessageBox.Show("Exception thrown during registration. Description=" + e.Message);
  }
}

/// <summary>
/// Called when the plug-in is unregistered. We unregister our plug-in with
/// GoogleDesktop.
/// </summary>
/// <param name=""t"" /></param>
[ComUnregisterFunctionAttribute]
static void UnregisterFunction(Type t)
{
  try
  {
    // Create the registrar object
    GoogleDesktopRegistrarClass registrar = new GoogleDesktopRegistrarClass();
    // Unregister ourselves
    registrar.UnregisterComponent(controlGuid);
  }
  catch (Exception e)
  {
    MessageBox.Show("Exception thrown during registration. Description=" + e.Message);
  }
}
#endregion

What this block of code does is writes to the registry values needed to register your component for COM interop. By using the GoogleDesktopRegistarClass it also registers your COM object for use and visibility by the GDK. For the most part you can just copy / paste whenever you build a plug-in.

Compiling and Running

Ok, now that you have all the code in place it’s time to compile and run your application. If your build was successful you should see the following:

Once you get this message hit yes. If you have the Google Sidebar running you should see it show up immediately. If not startup the Sidebar and if not there add the panel.

Based on what we have done you should see something like the following:

Normal

Minimized

What you are seeing is the Hello World plug-in with only a title. The title will change when you Minimize or Restore the panel.

What you have learned

In this part of our tutorial you have learned the basics of creating a very simple plug-in for the Google Desktop Sidebar using C#. As you can see it only took minimal setup steps thanks to some of the items that Google provided and we broke out for you.

In our next article we will cover adding content items, basic format to the plug-in.

Errata

04-12-2006

Thanks to M. Loeffen for catching this. If you were working through the examples you would indeed recieve a compile error because we did not define the layout property. We have adjusted the tutorial to add this variable to our main plugin class. If you want to see it here this is what you need to add:

  // setup the layout options so the sidebar api knows how to render our information.
  private GoogleDesktopDisplayContentItemLayout layout;

Understanding Value and Reference Types

Posted on March 10th, 2004


Supporting Downloads
valuereferencetypes.doc (52kb)
valuereferencetypes.zip (11kb)

Purpose

The purpose of this document is to explain the usage of Value and Reference types within the dot net framework. Since each type behaves differently when used as a plain value and when used as a parameter to a method, it is important to understand what is actually happening. We will be covering how each type actually works within the framework when used by themselves and when used as parameters to a method.

Meet the Types

When dealing with the dot net framework you will come across many objects. Each object will belong to either the Value type or Reference type category. To understand how these two objects differ we need to look at how memory is allocated for our application.

There are two areas in memory that are used to store this data, the stack and the heap. If you are a C++ programmer you are probably familiar with these memory units. In the dot net framework all Value types are pushed to the stack where as Reference types are pushed to the heap while a pointer to this memory usage is placed on the stack. Let’s break it down. When you create a Value type in your application it asks the framework to allocate memory based on the size of the type to hold whatever data you need. This data is then placed on the stack for usage. Once data goes onto the stack it stays on the stack until it is removed by our application. This can happen when a variable goes out of scope. Also, if you assign a Value type to another Value type a copy is made of this data and placed on the stack so, even though they are both the same thing the variables are accessing the data from two very different areas of memory. Let’s look at an example:

VB.Net

Public Sub TestValueType()
  Dim x As Integer
  Dim y As Integer

  x = 5
  y = x + 5

  Console.WriteLine(x)
  Console.WriteLine(y)
End Sub

C#

public void TestValueType()
{
  int x, y;

  x = 5;
  y = x + 5;

  Console.WriteLine(x);
  Console.WriteLine(y);
}

In our example we created two variables x and y, which we told the framework were Integers (which is a value type, see the chart at the end of this document for a list of common Value types.). Next we assign the variable x to the value of 5, this tells the framework to place on the stack a value of 5 and assign it to the variable x. Next, we assign the value of y to the value of x. This has just told the framework to create a value of 5 on the stack and assign it to the variable y. Notice, that it did not set the value on the stack to be x but rather the contents of the variable x. This is important because we are dealing with value types and the stack, we have created an exact duplicate of the value stored in the variable x and it did not just point the variable y to the value of x, but instead copied it’s data. Next, we assign the value of y to be equal to its current value plus 5. This will of course make the y variable equal to the value of y plus 5. So, our variable y is now 10. Now, how did this effect our value of x, it did not. Since the variables we are using are value types the data was copied rather than referenced. Later I will show how this can be very beneficial. The key to understand is that any object that is placed on the stack is always copied or modified directly it is never referenced.

Reference types however are placed on the heap. The heap is used in a very different manner than the stack. The heap is a dynamic memory location where objects that may exist at any point in time are created, destroyed, used, etc. in any order, there is no logical flow to the creating or removing of elements on the heap. When working in the dot net framework it is important to understand the heap is managed by the Garbage Collection services in the dot net framework. This means that it is possible and highly likely that an object that goes out of scope in your application is still in memory and can be accessed. This is where you get memory leaks and the nice blue screen of death (when they are not handled properly). When you create a reference type the framework tells the computer to create an area of memory on the heap (wherever it can) and then assigns our objects data to this memory location. Now for our object to be able to have access to this data the framework also creates a location on the stack in which it creates a pointer to the memory address at which our object resides on the heap. Now if you remember earlier we stated that when you create a copy of a value type it actually copies the data from the stack to another area of the stack, almost like a photocopier makes exact copies yet they are in themselves separate objects in that you can highlight data on one page and throw another away and whatever you do only effects the page you are dealing with. However with a reference type when you copy the object you are coping the memory pointer not the actual data itself. What does this mean, it means that whatever you do to one you do to the other. Let’s look at an example:

VB.Net

Public Sub TestReferenceType()
  Dim f1 As New System.Windows.Forms.Form()
  Dim f2 As New System.Windows.Forms.Form()

  f1.Text = "This is form1"

  Console.WriteLine(f1.Text)
  f2 = f1
  f2.Text = "This is form2"

  Console.WriteLine(f1.Text)
End Sub

C#

public void TestReferenceType()
{
  System.Windows.Forms.Form f1, f2;

  f1 = new System.Windows.Forms.Form();
  f2 = new System.Windows.Forms.Form();

  f1.Text = "This is Form1";

  Console.WriteLine(f1.Text);
  f2 = f1;
  f2.Text = "This is Form2";

  Console.WriteLine(f2.Text);
}

What will the second writeline statement print? If you said This is Form2 then you are correct. Why did this happen? Earlier we stated that a reference types data exists on the heap and that a pointer to the memory reference exits on the stack, now when we copied our object into the f2 variable it copied the data that exits on the stack. In the reference type world this is also known as a shallow copy. The reason for this is that only the data that exists on the stack is copied such that you now have two objects in code that are pointing to and using the same information. Why would you want this?, you might ask. Well let’s say that you have an application that needs to modify a value by passing it to a method and return the result. If you can pass a reference to this object so that it will point to the original, you can modify it without having to use a lot of extra memory to do so. This will also help the performance of your application since you will not need to perform a complete copy and use twice as much data space in memory.

Using Types with Methods

We are now going to look at how types are used when passed to a method. As you may know there are two ways to pass a parameter to a method, by value, and by reference. If you remember from earlier how Value and Reference types are different when assigning them to different values then you can probably guess how the data is passed to the methods. For those of you who are coming from prior versions of VB you probably remember that by default all parameters were passed by reference. In the dot net framework by default everything is passed by value. Which in most cases is what we intend to begin with.

Now the difficulty is now remembering how the types interact with the application when they are passed by value or by reference. Let’s first look at how to pass a Value type by value and by reference.

VB.Net

Public Sub PassingValues()
  Dim x As Integer
  Dim y As Integer

  x = 5
  y = x + 5

  PassValueTypes(x, y)

  Console.WriteLine(x)
  Console.WriteLine(y)
End Sub

Public Sub PassValueTypes(ByVal xval As Integer, _ ByRef yval As Integer)
  xval += 10
  yval += 20
End Sub

C#

public void PassingValues()
{
  int x,y;

  x = 5;
  y = x + 5;

  PassValueTypes(x,ref y);

  Console.WriteLine(x);
  Console.WriteLine(y);
}

public void PassValueTypes(int xval, ref int yval)
{
  xval += 10;
  yval += 20;
}

Now lets find out what happened. Can you guess what is going to be written to the console? If you guessed 5 for x and 30 for y then you are correct. However you might be asking how since you added 10 to the x value as well. When you pass a Value type by value to a method the framework creates a copy of the data and assigns it to the variable that is defined in the function and places that data into a new location on the stack. Now, when you pass a Value type by reference something different takes place. While the data is still located on the stack a pointer is created, again on the stack, that tells the framework where the data is for the value in question. In this way you have created a way for the method to access directly the data contained in the passed Value type variable. When this happened you now have the ability to alter the data that exists in that variable and since you are accessing it directly the calling variable will be able to see those changes. Once the calling method is finished it clears the two variables off of the stack, the by value variable is destroyed while the by reference variable only has the pointer destroyed.

So, when you pass a Value type to a method by value it is just like creating another Value type and assigning it the data, which creates a copy of the other variable on the stack. However when you pass a Value type by reference it behaves more like a Reference type in that the framework creates a pointer instead of a copy of the data so that the method will know where the data is on the stack, by doing this the method can modify the value of the variable directly.

Reference types however behave much differently. Lets look at some code.

VB.Net

Public Sub PassingReferences()
  Dim f1 As New System.Windows.Forms.Form()
  Dim f2 As New System.Windows.Forms.Form()

  f1.Text = "This is Form1"
  f2.Text = "This is Form2"

  PassRefTypes(f1, f2)

  Console.WriteLine(f1.Text)
  Console.WriteLine(f2.Text)
End Sub

Public Sub PassRefTypes(ByVal frm1 As System.Windows.Forms.Form, ByRef frm2 As System.Windows.Forms.Form)
  frm1.Text = "We have modified form1"
  frm2.Text = "We have modified form2"
End Sub

C#

public void PassingReferences()
{
  System.Windows.Forms.Form f1, f2;

  f1 = new System.Windows.Forms.Form();
  f2 = new System.Windows.Forms.Form();

  f1.Text = "This is Form1";
  f2.Text = "This is Form2";

  PassReferenceTypes(f1,ref f2);

  Console.WriteLine(f1.Text);
  Console.WriteLine(f2.Text);
}

public void PassReferenceTypes(System.Windows.Forms.Form frm1, ref System.Windows.Forms.Form frm2)
{
  frm1.Text = "We have modified Form1";
  frm2.Text = "We have modified Form2";
}

Can you guess what is going to happen here? If you guessed that the information written to the console will be what is in the PassReferenceTypes function then you are correct. Let’s see why.

As you know when you create a Reference type the data for that type is created on the heap with a pointer placed on the stack. When you copy a Reference type, its pointer is copied into the new variable and placed on the stack. The data it contains on the heap is not replicated, so in essence they both point to the same data. Now here is the gotcha, when you pass a Reference type by value it works the same as when you pass it by reference. Why is this, you might ask. Well when you pass a variable by value what happens? The framework makes a copy of what is on the stack and sends it to the method. Now what does a Reference type have on the stack, a pointer to the heap. So, if we pass a Reference type by value it is going to copy its stack value which in this case is the pointer. This is very important to understand because when you pass a reference type to any method whether it is by value or by reference it will always create a new variable on the stack that contains a pointer to data that is managed on the heap. Thus, you need to be careful when passing a reference type and be sure of what your intending when doing it.

Value Type(s)

Below is a list of the common Value types that are defined in the dot net framework. This list was pulled from the MSDN Library.

C#
enum, struct, bool, byte, sbyte, char, decimal, double, float, int, uint, long, ulong, short, ushort, and string.

VB.Net
Enum, Struct, Boolean, Byte, Char, Date, Decimal, Double, Integer, Long, Short, Single, and String.

Conclusion

I hope that this document will help alleviate some of the confusion around Value and Reference types, and how they are used and managed within the dot net framework. It is also my hope that this document will help eliminate more questions than it answers. So, when venturing into the world of dot net be careful of the types that you use.

Page 4 of 41234