Exploring the GrabAPicture Application (Part 5)

At this point, most of the graphics are out of the way. The previous post, Exploring the GrabAPicture Application (Part 4), discussed some of the considerations for working with icons. If you have some additional questions about that post, please be sure to let me know. A future post will likely contain some refinements on those techniques, but for now, let’s begin looking at the data storage mechanism for this application.

This application stores two kinds of source information: local and remote URIs. In order to make it easier to work with these data sources, you’ll create special classes. Use these steps to create the class files:

 

  1. Right click the project entry in Solution Explorer and choose Add | New Item from the context menu. You’ll see the Add New Item dialog box shown here.

    GrabAPicture0501

  2. Highlight the Class template.
  3. Type LocalUri.vb for the first class in the Name field and click Add. Visual Studio creates a blank class with the appropriate name for you.
  4. Repeat Steps 1 through 3 for the RemoteUri.vb class.

Another class in this application holds all of the code used to manipulate the data and also change the wallpaper. We’re going to work on this class quite a bit as these posts progress. For now, use Steps 1 through 3 to create a third class called WinWallpaper.vb.

Interestingly enough, you actually need to add something to the WinWallpaper class before you can proceed with either the LocalUri or RemoteUri classes. This example relies heavily on enumerations to reduce the risk of entering the wrong information when working with a class. The Styles enumeration is central to many tasks, but all of these tasks are somehow associated with WinWallpaper, so you’ll place the following enumeration there.

' A list of wallpaper display styles.
Public Enum Styles As Integer
   Tiled
   Centered
   Stretched
   Unknown
End Enum

The purpose of this enumeration is to define how to display the wallpaper on screen. The default setting is Unknown. This value actually ends up acting as a means of checking for error conditions later in the application. For now, just remember that Unknown means that the style hasn’t been configured by the user or the application.

Now, let’s begin by looking at the LocalUri class. The following code shows everything needed to create the class (including the initial code that Visual Studio creates for you).

Imports System.Xml
Imports GrabAPicture.WinWallpaper
 
<Serializable()> _
Public Class LocalUri
   ' List of local values for each entry.
   Private _Name As String = ""
   Private _Location As String = ""
   Private _Style As Styles = Styles.Unknown
 
   ' Handle the item name.
   Public Property Name() As String
      Get
         Return _Name
      End Get
      Set(ByVal Value As String)
         _Name = Value
      End Set
   End Property
 
   ' Handle the item location.
   Public Property Location() As String
      Get
         Return _Location
      End Get
      Set(ByVal Value As String)
         ' This bit of code verifies that Value contains a
         ' valid URI. If it doesn't, the class will throw
         ' an exception during the double conversion to and
         ' from a URI.
         _Location = (New Uri(Value)).ToString()
      End Set
   End Property
 
   ' Handle the item display style.
   Public Property Style() As Styles
      Get
         Return _Style
      End Get
      Set(ByVal Value As Styles)
         If Value = WinWallpaper.Styles.Unknown Then
            ' The unknown style is only for error trapping.
            Throw New ArgumentException( _
               "Style cannot be Unknown")
         Else
            ' Set the correct style.
            _Style = Value
         End If
      End Set
   End Property
End Class

In order to use this class, you must import both the System.Xml namespace and the GrabAPicture.WinWallpaper class. Notice that this class is marked with the Serializable() attribute. This attribute makes it possible to perform certain XML-related tasks with considerable ease. Otherwise, there isn’t anything special about the class declaration.

The LocalUri class consists of three private fields and three public properties. Here is a description of each of the properties.

 

  • Name: Accepts any source name value. The application could probably add some error trapping for it, but the run-time will capture any major issues. Names can include any characters. About the only limit (and it would be an artificial one) would be to set the number of characters that a Name can contain.
  • Location: Accepts the location of the source as a String. The conversion from a String to a Uri also prevents someone from sending nonsense information. A String input that won’t convert to a Uri will always raise an exception.
  • Style: Defines the way in which the application displays the image on the Desktop. Because this isn’t a value that you can easily check any other way, the Style is always set to Unknown at the outset. If the value remains Unknown, the application raises an error. An image must have a style associated with it. Notice how the use of an enumeration simplifies the code in this case.

The RemoteUri class is similar to the LocalUri class. In fact, you won’t see any major differences in this version of the application. The main reason to use two separate classes is to make the code more readable and to make the application more flexible. For example, a future version of the application could obtain remote sources from a Web service, which would mean changing the RemoteUri class in ways that the LocalUri class wouldn’t require. Here is the RemoteUri class code.

Imports System.Xml
Imports GrabAPicture.WinWallpaper
 
<Serializable()> _
Public Class RemoteUri
   ' List of local values for each entry.
   Private _Name As String = ""
   Private _Location As String = ""
   Private _Style As Styles = Styles.Unknown
 
   ' Handle the item name.
   Public Property Name() As String
      Get
         Return _Name
      End Get
      Set(ByVal Value As String)
         _Name = Value
      End Set
   End Property
 
   ' Handle the item location.
   Public Property Location() As String
      Get
         Return _Location
      End Get
      Set(ByVal Value As String)
         ' This bit of code verifies that Value contains a
         ' valid URI. If it doesn't, the class will throw
         ' an exception during the double conversion to and
         ' from a URI.
         _Location = (New Uri(Value)).ToString()
      End Set
   End Property
 
   ' Handle the item display style.
   Public Property Style() As Styles
      Get
         Return _Style
      End Get
      Set(ByVal Value As Styles)
         If Value = WinWallpaper.Styles.Unknown Then
            ' The unknown style is only for error trapping.
            Throw New ArgumentException( _
               "Style cannot be Unknown")
         Else
            ' Set the correct style.
            _Style = Value
         End If
      End Set
   End Property
End Class

The next post will begin looking at some of the tasks performed with the WinWallpaper class (beside providing the Styles enumeration). For now, you know that the XML file that holds the data source information will include three entries for each source: Name, Location, and Style. These three values are enough to display any image on the Desktop. Let me know if you have any questions about these serializable classes at John@JohnMuellerBooks.com. You can see the next post in this series at Exploring the GrabAPicture Application (Part 6).