Archive for August, 2010
Note: Not every region has to be filled by a layout element.
In the first code example, we are defining the design to be of type ‘headline’ which results in the general configuration that you see below with the ‘top’ and ‘bottom’ regions stretching across the entire width of the screen space. In this case you only need to set the ‘height’ property for the top and bottom regions.
In the second code example we define the design as ‘sidebar’. With the sidebar design the left and right regions expand to take up 100% of the height of the window, sacrificing the area available to the top and bottom regions. In this case you only need to define the width style property since the height will always be 100%.
In either case the center region will conform to fit the amount of space available based on the sizing of the other regions.
Child Elements of BorderContainer
Each region of a BorderContainer (top, bottom, left, right, center) can be filled by a Dojo layout element. These elements are AccordionContainer, ContentPane, SplitContainer, StackContainer, and TabContainer. You can also created nested BorderContainers to further divide the available layout space.
Child elements are placed inside a region through the use of the ‘region’ attribute as seen below. Notice in the yellow highlighted section that the ‘region’ attribute is set to ‘left’. This will create a ContentPane in the left region. A ContentPane is a very basic layout element and is used as a container for other widgets. In this case it is going to hold a TabContainer (green highlighted code).
The other child layout elements that can be placed inside a BorderContainer include AccordionContainer, SplitContainer, and StackContainer.
AccordionContainers hold a set of panes whose titles are visible, but only one pane’s content is visible at a time. As the user clicks a title, the pane contents become visible. These are excellent user interface containers that can hold a lot of information in a small area.
StackContainers resemble books where only a single pane of information is available at a time. Users can page through various panes of information.
Finally, a SplitContainer is a container that contains multiple children. All the children are displayed side by side either horizontally or vertically with a bar in between. The bars can be dragged to change the relative size of the child areas.
There are a number of other design considerations which you should take into account. ESRI has done a great job of defining those here near the bottom of the page.
Sample Layouts from ESRI
ESRI also provides toolbar helper classes that enable you to easily add in navigation, drawing, or editing functionality. These toolbars aren’t user interface components that you simply drop into your application, but are instead helper classes that make creating the toolbars a snap to create and add to your interface. For now we’ll just take a look at adding a navigation toolbar to your application. There are several steps to adding the toolbar, but all are quite simple.
First you’ll want to add in the references that you’ll need to implement this functionality.
You need a reference to the navigation toolbar along with a reference to dijit.Toolbar and dijit.form.Button. Each of the tools in the toolbar is actually a Dojo Dijit Button that is contained within a Dojo Dijit Toolbar.
Next we’ll define the icons that will be used for each of our buttons. This can be done through CSS styling as seen below. Here we are defining the images to be used along with their width and height.
Finally, we create the toolbar through the use of dijit.Toolbar which is defined inside a ContentPane in the ‘top’ region of our BorderContainer. You can see this in the code below. In the yellow highlighted code we are creating an instance of dijit.Toolbar called ‘navToolbar’. This new toolbar is located inside a ContentPane called ‘toolbar-container’ which is a child layout element of BorderContainer. This code is highlighted in green.
Inside our toolbar (‘navToolbar’) we create a series of dijit.form.Button objects that correspond to the type of function that should be performed by that tool. I’ve highlighted one example of this in the code below. This is the Zoom In tool that a user can click and then drag a rectangle on the map to zoom to a new extent. This tool is defined as type dijit.form.Button. The ‘onClick’ event is particularly important here because it references back to the esri.toolbars.navigation reference that we defined earlier. This actually defines what type of functionality should be provided by this button. In this case, esri.toolbars.Navigation.ZOOM_IN. The ‘iconClass’ attribute is used to reference back to the style we created earlier which contains the icon that will be used for the button.
So, all of that results in a toolbar.
In my last post I introduced the ArcPy Mapping module, released with ArcGIS 10, which provides a number of capabilities including the management of map documents and layers, printing, exporting, ArcGIS Server publishing, map automation, and the creation of PDF map books. Today we’re going to take a closer look at the Layout classes provided by the module.
The ListLayoutElements() function returns a list of Layout elements in the form of various Layout classes. Each element can be one of: GraphicElement, LegendElement, PictureElement, TextElement, MapSurroundElement, or PictureElement as seen in the graphic below.
ListLayoutElements() is a versatile function which in its most basic form is used to return a list of all the layout elements on the page layout of a map document. However, there are two optional parameters that you can supply to filter this list. The first type of filter is an element type filter in which you specify that you only want to return one of the layout element types. You can also apply a wildcard to filter the returned list. These two types of filters can be used in combination. For example, in the code below we are specifying that we only want to return LEGEND_ELEMENT objects with the name “Legend Crime”. This would likely result in a highly filtered list, and as we can see only a single item was returned.
Each graphic on a layout has a ‘name’ property that you can view in ArcMap by right clicking the element and selecting Properties. Most elements are assigned a default name if you don’t specifically supply one. You should make it a best practice to assign a unique ‘name’ to each element on your page layout. This will make it easier for you to access particular elements from your Python scripts.
Each element on the page layout has various properties that can be set through your Python code. For example, in the code block below we are accessing a specific Legend element (“Legend Crime”) and assigning a new title to the legend.
In this case we are only changing the Legend title. However, LegendElement provides other properties that enable it to be repositioned on the page layout as well as getting legend items and the parent data frame.
Below is a brief description of each of the layout elements accessible through Python.
The DataFrame class provides access to data frame properties in the map document file. This object can work with both map units and page layout units depending upon the property being used. Page layout properties such as positioning and sizing can be applied to the properties on this slide including elementPositionX, elementPositionY, elementWidth, and elementHeight.
The GraphicElement object is a generic object for various graphics that can be added to the page layout including tables, graphs, neatlines, markers, lines, and area shapes. You’ll want to make sure that you set the ‘name’ property for each graphic element (and any other element for that matter) if you intend to access it through a Python script.
The LegendElement provides operations for positioning of the legend on the page layout, modification of the legend title, and also provides access to the legend items and the parent data frame. A LegendElement can be associated with only a single data frame.
The MapsurroundElement can refer to north arrows, scale bars, and scale text and like LegendElement is associated with a single data frame. Properties on this object enable repositioning on the page.
PictureElement represents a raster or image on the page layout. The most useful property on this object allows for getting and setting the data source which can be extremely helpful when you need to change out a picture such as logo in multiple map documents. For example, you could write a script that iterates through all your map document files and replaces the current logo with a new logo. You can also reposition the object.
TextElement represents text on a page layout including inserted text, callouts, rectangle text and titles, but does not include legend titles or text that is part of a table or chart. Properties enable modifying the text string which can be extremely useful in situations where you need to make the same text string change in multiple places in the page layout or over multiple map documents, and of course repositioning of the object is also available.
The next session of our Internet based, instructor led course, GIS Programming 101: Mastering Python for Geoprocessing in ArcGIS begins October 25th. This course is only $499 when you register by August 31st. The regular price of this course is $667.Read Full Post | Make a Comment ( None so far )
The ArcPy.Mapping module is new to ArcGIS 10 and brings some really exciting features for mapping automation including the ability to manage map documents and layer files as well as the data within these files. Support is also provided for automating map export and printing as well as the creation of PDF map books and the publication of map documents to ArcGIS Server map services. I’m going to be writing a series of posts of the next few weeks covering some of the functionality provided by this module.
ArcPy.Mapping scripts can be run from a variety of environments just like any other geoprocessing script that you’ve developed with Python for use with the ArcGIS geoprocessor. The new Python Window in ArcMap is a great interface for writing and testing small code blocks. Once tested, these code blocks are often moved into stand-alone Python scripts which can be executed from an IDE such as PythonWin, IDLE, or Wing, but they can also be executed from custom script tools in ArcToolbox, the command line or as scheduled tasks. Many people choose to attach their scripts to script tools in ArcMap or ArcCatalog to provide a visual interface for the scripts within the familiar ArcGIS Desktop environment. Finally, scripts can also be published as geoprocessing tasks in ArcGIS Server.
Before you can actually perform any operations on a map document file you need to get a reference to it in your Python script. This is done by calling the MapDocument() method on the arcpy.mapping module. You can reference either the currently running document or a document at a specific location. To reference the currently active document you simply supply the keyword “CURRENT” as a parameter to the MapDocument() function. This gets the currently active document in ArcMap. To reference a map document on disk you simply supply the path to the map document as well as the map document name as a parameter to MapDocument(). The two code examples below illustrate each of these operations.
In today’s post I’m going to cover a number of the new list functions provided by Arcpy.Mapping. There are a number of list functions provided by Arcpy.Mapping. Each of these list functions returns a Python list which is a highly functional data structure for storing information. Normally, the list functions are used as part of a multi-step process where creating a list is only the first step. Subsequent processing in the script will iterate over one or more of the items in this list. For example, you might obtain a list of broken data links in your map document file and iterate over these links, fixing each as you progress.
The ListLayers() function returns a Python list of all the layers within an mxd file, a data frame within an mxd file, or a layer file. As with all other list functions you can iterate this list through the use of a ‘for’ loop which cycles through each element in the list.
ListDataFrames() returns a Python list of data frames in a map document file. An integer index value can be used to access an individual data frame or you can test for a specific data frame name before applying further processing to the data within the data frame. You can also use a wildcard to filter the data frames that are returned.
Data sources in your map document files are often broken due to data being deleted or moved to a new location. The result can be broken data sources in many map document files. ListBrokenDataSources() returns a list of layer objects that have a broken data connection. In ArcMap, a broken data connection is signified by the red exclamation point just before the layer name.
Typically, the ListBrokenDataSources() function is used as the first step in a script that iterates through the list and fixes the data source. In a future post I’ll show an example script that lists and fixes broken data sources.
ListTableViews() returns a list of Table objects in a map document. You can use a wildcard to return a filtered list of tables.
ListLayoutElements() returns a list of Layout elements in the form of various Layout classes. Each element can be one of: GraphicElement, LegendElement, PictureElement, TextElement, MapSurroundElement, or PictureElement. I’ve outlined some of these layout elements below.
ListLayoutElements() is a versatile function which in its most basic form is used to return a list of all the layout elements on the page layout of a map document. However, there are two optional parameters that you can supply to filter this list. The first type of filter is an element type filter in which you specify that you only want to return one of the layout element types seen on this slide. You can also apply a wildcard to filter the returned list. These two types of filters can be used in combination. For example, in the code example below we are specifying that we only want to return LEGEND_ELEMENT objects with the name “Legend Crime”. This would likely result in a highly filtered list.
In the next post in this series you’ll learn how to fix broken data sources based on a list generated by the ListBrokenDatasources() function.
The next session of our Internet based, instructor led course, GIS Programming 101: Mastering Python for Geoprocessing in ArcGIS begins October 25th. This course is only $499 when you register by August 31st. The regular price of this course is $667.Read Full Post | Make a Comment ( 2 so far )