ArcGIS API for WPF - Library Reference
Bookmark Class
Members  Example  See Also  Send comments on this topic
ESRI.ArcGIS.Client.Toolkit Namespace : Bookmark Class

The Bookmark Control allows for setting pre-defined Map.Extent values using a name for speedy navigation of the Map.

Object Model

Bookmark ClassMap Class

Syntax

Visual Basic (Declaration) 
Public Class Bookmark 
   Inherits System.Windows.Controls.Control
C# 
public class Bookmark : System.Windows.Controls.Control 

Example

How to use:

This example provides a default Bookmark Control that is bound to a Map Control to experiment with its functionality. Additionally, there are several Buttons that can be clicked to see how some of the behavior and appearance of the Bookmark Control can be modified via the code-behind.

The XAML code in this example is used in conjunction with the code-behind (C# or VB.NET) to demonstrate the functionality.

The following screen shot corresponds to the code example in this page.

Demonstrating a default Bookmark Control and usage of several Properties and Methods.

XAMLCopy Code
<Grid x:Name="LayoutRoot">
  
  <!-- Provide the instructions on how to use the sample code. -->
  <TextBlock Height="70" HorizontalAlignment="Left" Name="TextBlock1" VerticalAlignment="Top" Width="626" 
             TextWrapping="Wrap" Margin="2,9,0,0" 
             Text="This example provides a default Bookmark Control that is bound to a Map Control to 
                  experiment with its functionality. Additionally, there are several Buttons that can be 
                  clicked to see how some of the behavior and appearance of the Bookmark Control can be 
                  modified via the code-behind." />
  
  <!-- Add a Map Control. -->
  <esri:Map Background="White" HorizontalAlignment="Left" Margin="12,85,0,0" Name="Map1" 
            VerticalAlignment="Top" Height="360" Width="401" >
  
    <!-- Add a default ArcGISTiledMapServiceLayer for visual display in the Map. -->
    <esri:ArcGISTiledMapServiceLayer ID="PhysicalTiledLayer" 
                 Url="http://services.arcgisonline.com/ArcGIS/rest/services/World_Street_Map/MapServer" />
  </esri:Map>
  
  <!-- 
  Add a default Bookmark Control. The Bookmark.Map Property has been bound to the Map Control. 
  The Bookmark.IsolatedStorage Property have been set to False (the default is True) to clear
  out the MapBookmark items each time the application runs. -->
  <esri:Bookmark HorizontalAlignment="Left" Margin="419,278,0,0" Name="Bookmark1" 
                 VerticalAlignment="Top" Width="208" Height="168" 
                 Map="{Binding ElementName=Map1}" UseIsolatedStorage="False"/>
  
  <!-- 
  A Button with code-behind to show adding a MapBookmark to the Bookmark Control. This version
  uses an Envelope.Extent via String X,Y coordinate pairs to populate the MapBookmark.Extent. 
  -->
  <Button Content="AddBookmark Method" HorizontalAlignment="Left" Margin="420,86,0,0" 
          Name="Button_AddBookmark" VerticalAlignment="Top" Width="209" Click="Button_AddBookmark_Click"/>
  
  <!-- 
  A Button with code-behind to show adding a MapBookmark to the Bookmark Control. This version
  uses the current Map.Extent for the MapBookmark.Extent value.  
  -->
  <Button Content="AddBookmark v2 Method" Height="23" HorizontalAlignment="Left" Margin="421,115,0,0" 
          Name="Button_AddBookmarkv2" VerticalAlignment="Top" Width="208" Click="Button_AddBookmarkv2_Click"/>
  
  <!-- A button with code-behind to clear out all items in the Bookmark Control. -->
  <Button Content="ClearBookmarks Method" Height="23" HorizontalAlignment="Left" Margin="421,144,0,0" 
          Name="Button_ClearBookmarks" VerticalAlignment="Top" Width="209" Click="Button_ClearBookmarks_Click"/>
  
  <!-- A button with code-behind to clear out just the first MapBookmark item in the Bookmark Control. -->
  <Button Content="DeleteBookmarkAt Method" Height="23" HorizontalAlignment="Left" Margin="420,173,0,0"
          Name="Button_DeleteBookmarkAt" VerticalAlignment="Top" Width="209" Click="Button_DeleteBookmarkAt_Click" />
  
  <!-- 
  A button with code-behind to display all of the MapBookmark.Name and MapBookmark.Extent values in 
  the Bookmark Control via a MessageBox. -->
  <Button Content="Bookmarks Property" Height="23" HorizontalAlignment="Left" Margin="420,202,0,0" 
          Name="Button_Bookmarks" VerticalAlignment="Top" Width="209" Click="Button_Bookmarks_Click"/>
  
  <!-- A button with code-behind to change the default Title of the Bookmark Control. -->
  <Button Content="Title Property" Height="23" HorizontalAlignment="Left" Margin="420,231,0,0" 
          Name="Button_Title" VerticalAlignment="Top" Width="209" Click="Button_Title_Click"/>
</Grid>
C#Copy Code
private void Button_AddBookmark_Click(object sender, System.Windows.RoutedEventArgs e)
{
  // This function add a new named Map.Extent (aka. a bookmark) to the ObservableCollection<MapBookmark>.
  ESRI.ArcGIS.Client.Geometry.Envelope myExtent = new ESRI.ArcGIS.Client.Geometry.Envelope(-1837672.03060728, 3202886.78616195, 4708662.7690822, 9079895.58388817);
  Bookmark1.AddBookmark("Europe", myExtent);
}
            
private void Button_AddBookmarkv2_Click(object sender, System.Windows.RoutedEventArgs e)
{
  // An alternate method of adding a named MapExtent (aka. a bookmark) to the ObservableCollection<MapBookmark>.
  Bookmark1.AddBookmark("A custom location", Map1.Extent);
}
            
private void Button_ClearBookmarks_Click(object sender, System.Windows.RoutedEventArgs e)
{
  // This Clears ALL of the Bookmarks. Same functionality as the 'Clear' button in the default GUI for the control.
  Bookmark1.ClearBookmarks();
}
            
private void Button_DeleteBookmarkAt_Click(object sender, System.Windows.RoutedEventArgs e)
{
  // This function deletes the first occurrence of a MapBookmark from the Bookmark.Control.
  
  Collections.ObjectModel.ObservableCollection<ESRI.ArcGIS.Client.Toolkit.Bookmark.MapBookmark> myBookmarks = null;
  myBookmarks = Bookmark1.Bookmarks;
  if (myBookmarks.Count > 0)
  {
    // Delete the top most bookmark
    Bookmark1.DeleteBookmarkAt(0);
  }
}
            
private void Button_Bookmarks_Click(object sender, System.Windows.RoutedEventArgs e)
{
  // This function loops through all of the MapBookmark items in the Bookmark.Bookmarks 
  // ObservableCollection<MapBookmark> to display the MapBookmark.Name and MapBookmark.Extent.
            
  Collections.ObjectModel.ObservableCollection<ESRI.ArcGIS.Client.Toolkit.Bookmark.MapBookmark> myBookmarks = null;
  myBookmarks = Bookmark1.Bookmarks;
  
  foreach (ESRI.ArcGIS.Client.Toolkit.Bookmark.MapBookmark oneMapBookmark in myBookmarks)
  {
    MessageBox.Show("The MapBookmark: " + oneMapBookmark.Name + Environment.NewLine + "Has the Extent: " + oneMapBookmark.Extent.ToString());
  }
}
            
private void Button_Title_Click(object sender, System.Windows.RoutedEventArgs e)
{
  // Modify the default title of the Bookmark Control.
  Bookmark1.Title = "My Custom Title";
}
VB.NETCopy Code
Private Sub Button_AddBookmark_Click(ByVal sender As System.Object, ByVal e As System.Windows.RoutedEventArgs)
  
  ' This function add a new named Map.Extent (aka. a bookmark) to the ObservableCollection(Of MapBookmark).
  Dim myExtent As New ESRI.ArcGIS.Client.Geometry.Envelope(-1837672.03060728, 3202886.78616195, 4708662.7690822, 9079895.58388817)
  Bookmark1.AddBookmark("Europe", myExtent)
  
End Sub
            
Private Sub Button_AddBookmarkv2_Click(ByVal sender As System.Object, ByVal e As System.Windows.RoutedEventArgs)
  
  ' An alternate method of adding a named MapExtent (aka. a bookmark) to the ObservableCollection(Of MapBookmark).
  Bookmark1.AddBookmark("A custom location", Map1.Extent)
  
End Sub
            
Private Sub Button_ClearBookmarks_Click(ByVal sender As System.Object, ByVal e As System.Windows.RoutedEventArgs)
  
  ' This Clears ALL of the Bookmarks. Same functionality as the 'Clear' button in the default GUI for the control.
  Bookmark1.ClearBookmarks()
  
End Sub
            
Private Sub Button_DeleteBookmarkAt_Click(ByVal sender As System.Object, ByVal e As System.Windows.RoutedEventArgs)
  
  ' This function deletes the first occurrence of a MapBookmark from the Bookmark.Control.
  
  Dim myBookmarks As Collections.ObjectModel.ObservableCollection(Of ESRI.ArcGIS.Client.Toolkit.Bookmark.MapBookmark)
  myBookmarks = Bookmark1.Bookmarks
  If myBookmarks.Count > 0 Then
    
    ' Delete the top most bookmark
    Bookmark1.DeleteBookmarkAt(0)
    
  End If
  
End Sub
            
Private Sub Button_Bookmarks_Click(ByVal sender As System.Object, ByVal e As System.Windows.RoutedEventArgs)
  
  ' This function loops through all of the MapBookmark items in the Bookmark.Bookmarks 
  ' ObservableCollection(Of MapBookmark) to display the MapBookmark.Name and MapBookmark.Extent.
  
  Dim myBookmarks As Collections.ObjectModel.ObservableCollection(Of ESRI.ArcGIS.Client.Toolkit.Bookmark.MapBookmark)
  myBookmarks = Bookmark1.Bookmarks
  
  For Each oneMapBookmark As ESRI.ArcGIS.Client.Toolkit.Bookmark.MapBookmark In myBookmarks
    MessageBox.Show("The MapBookmark: " + oneMapBookmark.Name + vbCrLf +
                    "Has the Extent: " + oneMapBookmark.Extent.ToString)
  Next
  
End Sub
            
Private Sub Button_Title_Click(ByVal sender As System.Object, ByVal e As System.Windows.RoutedEventArgs)
  
  ' Modify the default title of the Bookmark Control.
  Bookmark1.Title = "My Custom Title"
  
End Sub

Remarks

The Bookmark is a User Interface (UI) control that allows clients to define preset Map.Extent values using a name for quick navigation in the Map Control. The Bookmark Control can be created in at design time in XAML or dynamically at runtime in the code-behind. The Bookmark Control is one of several controls available in the Toolbox in Visual Studio when the ESRI ArcGIS API for Silverlight/WPF is installed, see the following screen shot:

Example of the Bookmark Control on the XAML design surface of a Silverlight application.

The default appearance of the Bookmark Control can be modified using numerous inherited Properties from System.Windows.FrameworkElement, System.Windows.UIElement, and System.Windows.Controls. An example of some of these Properties include: .Height, .Width, .BackGround, .BorderBrush, .BorderThickness, .FontFamily, .FontSize, .FontStretch, .FontStyle, .Foreground, .HorizontalAlignment, .VerticalAlignment, .Margin, .Opacity, .Visibility, etc.

Note: you cannot change the core behavior of the sub-components (i.e. Button, DataGrid, etc.) of the Bookmark Control using standard Properties or Methods alone. To change the core behavior of the sub-components and their appearance of the Control, developers can modify the Control Template in XAML and the associated code-behind file. The easiest way to modify the UI sub-components is using Microsoft Expression Blend. Then developers can delete/modify existing or add new sub-components in Visual Studio to create a truly customized experience. A general approach to customizing a Control Template is discussed in the ESRI blog entitled: Use control templates to customize the look and feel of ArcGIS controls. Specific code examples of modifying the Control Template of the Bookmark control to can be found in the Bookmark.DeleteBookmarkAt Method and Bookmark.AddBookmark Method documents.

In order to use the Bookmark Control it is mandatory that the Bookmark.Map Property be set to a Map Control. This can be done via Binding in the XAML or by setting the Map Property in the code-behind file.

The Bookmark Control is comprised of mainly five sub-components:

The following image shows a typical Bookmark Control and its various sub-component parts:

Describing the various parts of the Bookmark Control.

To use the Bookmark Control, clients use the various pan/zoom functions on the Map Control to select a visual Map.Extent and then type in a name for in the TextBox. Then they click the + button to add that named Map.Extent (aka. a bookmark) into the DataGrid. Later when the user decides to go back to a previous Map.Extent, they click on the name in the DataGrid and the Map will automatically pan/zoom to that named Map.Extent (aka. a bookmark). Users click the Clear button to remove all of the named Map.Extent (aka. a bookmark) values from the DataGrid.

If a portion of the current Map.Extent is in the named Map.Extent (aka. a bookmark) when the user clicks on a bookmark item in the DatGrid, the map will pan/zoom using an animation to the clicked bookmark. If the current Map.Extent does not contain any spatial overlap with the named Map.Extent (aka. a bookmark) that the user clicks on in the DataGrid, there will be not be any animation and the Map will immediately go to the new Bookmark location.

By default the ESRI.ArcGIS.Client.Toolkit.Bookmark.UseIsolatedStorage value equals True. This means that the application will remember from one session to another the named Map.Extent (aka. a bookmark) values previously entered. If the Bookmark.UseIsolatedStorage is set to False, the next time a user begins another client session of the application the named Map.Extent (aka. a bookmark) settings will be lost. Note: There is only one IsolatedStorage container per application. This may have implications if you have multiple Maps, each with their own set of Bookmarks. This means you may need to make use of the Bookmark.Bookmarks Property which returns an ObservableCollection(Of Bookmark.MapBookmark) object to persist across the various Maps.

When a Bookmark Control is created the ObservableCollection (Of MapBookmark) object is also created that is accessible from the Bookmark.Bookmarks Property. Although the Bookmark.Bookmarks Property is ReadOnly, meaning you can only get the ObservableCollection (Of MapBookmark) object, you can use its Members to like: Add, Clear, Remove, etc. to define how the Bookmark Control behaves.

To change the text of a previously entered named Map.Extent (aka. a bookmark) in the DataGrid, click on the text portion inside of the selected DataGrid item and the bounding box around the text will turn Black (meaning it is ready to accept the cursor for text changes). Then type the desired edits and when done making text changes for the named Map.Extent (aka. a bookmark) click with the mouse cursor somewhere outside of the editiable portion of the DataGrid. It may take some practice of first selecting a DataGrid item and then clicking on the text inside of the DataGrid to get the Black editable background (two clicks in the same spot but not a double-click).

When the user types in a name for the current Map.Extent to add to the DataGrid by clicking the + button, the text value that is typed will remain after the user clicks the + button. The text value does not automatically clear when the + button is clicked.

It is possible to programmatically control the removal of one named Map.Extent (aka. a bookmark) from the DataGrid in the Bookmark Control rather than removing all of them via the Clear button. Use the Bookmark.DeleteBookmarkAt Method to supply an index number for the correct named Map.Extent (aka. a bookmark) in the DatGrid to be removed. The visually top most named Map.Extent (aka. a bookmark) in the DataGrid is the 0 index value.

The text of the Title for the Bookmark can be controlled via the Title Property in XAML or code-behind.

Controlling the input text for the TextBox that provides a name for the Map.Extent is done via client interaction. Developers can programmatically assign a text value by modifying the sub-component AddBookmarkName TextBox of the Bookmark Control using a custom Control Template.

Controlling the behavior and appearance of the + button to add a named Map.Extent (aka. a bookmark) to the DataGrid can be programmatically controlled by modifying the sub-component AddBookmark Button of the Bookmark Control using a custom Control Template.

Controlling the behavior and appearance of the DataGrid that contains the ObservableCollection of named Map.Extent (aka. a bookmark) values can be programmatically controlled by modifying the sub-component BookmarkList DataGrid of the Bookmark Control using a custom Control Template.

Controlling the behavior and appearance of the Clear button to remove all named Map.Extent (aka. a bookmark) values from the DataGrid can be programmatically controlled by modifying the sub-component ClearBookmarks Button of the Bookmark Control using a custom Control Template.

Inheritance Hierarchy

System.Object
   System.Windows.Threading.DispatcherObject
      System.Windows.DependencyObject
         System.Windows.Media.Visual
            System.Windows.UIElement
               System.Windows.FrameworkElement
                  System.Windows.Controls.Control
                     ESRI.ArcGIS.Client.Toolkit.Bookmark

Requirements

Target Platforms: Windows XP Professional, Windows Server 2003 family, Windows Vista, Windows Server 2008 family

See Also

© ESRI, Inc. All Rights Reserved.