com.esri.arcgis.controls
Interface IPageLayoutControl

All Superinterfaces:
Serializable
All Known Subinterfaces:
IPageLayoutControl2, IPageLayoutControl3
All Known Implementing Classes:
IPageLayoutControl2Proxy, IPageLayoutControl3Proxy, IPageLayoutControlProxy, PageLayoutBean, PageLayoutControl

public interface IPageLayoutControl
extends Serializable

Provides access to members that control the PageLayoutControl.

Superseded By

IPageLayoutControl3

Description

The IPageLayoutControl interface is a starting point for any tasks related to the PageLayoutControl, such as setting general appearance, setting page and display properties, adding and finding elements, loading map documents, and printing.

Product Availability

Available with ArcGIS Engine.


Method Summary
 void aboutBox()
          Displays a dialog of information about the PageLayoutControl.
 void addElement(IElement pElement, Object geometry, Object symbology, Object name, int zOrder)
          Adds the supplied element to the PageLayout, with optional geometry, symbolization, name and Z order.
 void centerAt(IPoint centerPoint)
          Moves the center of the PageLayoutControl to the specified location.
 boolean checkMxFile(String fileName)
          Checks the specified filename to see if it is a map document that can be loaded into the PageLayoutControl.
 boolean esri_isEnabled()
          Indicates whether the PageLayoutControl can respond to user generated events.
 void esri_setEnabled(boolean pbool)
          Indicates whether the PageLayoutControl can respond to user generated events.
 IElement findElementByName(String name, int occurence)
          Find the first element with the supplied name, supply an occurrence parameter to find the second, third and so on.
 void fromPagePoint(IPoint pt, int[] x, int[] y)
          Converts a point on the page (in page units) to device co-ordinates (typically pixels).
 IActiveView getActiveView()
          The active view of the PageLayout contained by the PageLayoutControl.
 int getAppearance()
          The appearance of the PageLayoutControl.
 int getBackColor()
          Background color of the PageLayoutControl.
 int getBorderStyle()
          The border style of the PageLayoutControl.
 ITool getCurrentTool()
          Current active tool for the PageLayoutControl.
 IEnvelope getExtent()
          Current extent of the PageLayout in page units.
 IEnvelope getFullExtent()
          Rectangular shape that encloses the PageLayout.
 IGraphicsContainer getGraphicsContainer()
          The graphics container of the PageLayout object contained by the PageLayoutControl.
 int getHWnd()
          Handle to the window associated with the PageLayoutControl.
 Picture getMouseIcon()
          Custom mouse icon used if MousePointer is 99.
 int getMousePointer()
          The mouse pointer displayed over the PageLayoutControl.
 IPage getPage()
          The Page associated with the PageLayout contained by the PageLayoutControl.
 IPageLayout getPageLayout()
          The PageLayout contained by the PageLayoutControl.
 IPrinter getPrinter()
          The printer object used by the PageLayoutControl for printing.
 short getPrinterPageCount(double overlap)
          The number of printer pages the PageLayout will cover.
 ITrackCancel getTrackCancel()
          The object used by the PageLayoutControl to check if drawing has been aborted.
 boolean isOleDropEnabled()
          Indicates if the PageLayoutControl will fire events when data is dragged over the control's window.
 void loadMxFile(String fileName, Object password)
          Loads the specified map document into the PageLayout contained by the PageLayoutControl.
 IElement locateFrontElement(double pageX, double pageY, double tolerance)
          Locates an element at the given page co-ordinates.
 void pan()
          Tracks the mouse while panning the PageLayoutControl.
 void printPageLayout(short startPage, short endPage, double overlap)
          Sends the specified range of pages on the printer.
 void refresh(int phase, Object layerOrElement, Object envelope)
          Redraws the PageLayout, optionally just redraw specified phases or envelope.
 void setAppearance(int pappearance)
          The appearance of the PageLayoutControl.
 void setBackColor(int pclr)
          Background color of the PageLayoutControl.
 void setBorderStyle(int pstyle)
          The border style of the PageLayoutControl.
 void setCurrentToolByRef(ITool pTool)
          Current active tool for the PageLayoutControl.
 void setExtent(IEnvelope extent)
          Current extent of the PageLayout in page units.
 void setFullExtent(IEnvelope fullExtent)
          Rectangular shape that encloses the PageLayout.
 void setMouseIconByRef(Picture ppMouseIcon)
          Custom mouse icon used if MousePointer is 99.
 void setMousePointer(int ppointer)
          The mouse pointer displayed over the PageLayoutControl.
 void setOleDropEnabled(boolean value)
          Indicates if the PageLayoutControl will fire events when data is dragged over the control's window.
 void setPageLayoutByRef(IPageLayout pPageLayout)
          The PageLayout contained by the PageLayoutControl.
 void setPrinterByRef(IPrinter ppPrinter)
          The printer object used by the PageLayoutControl for printing.
 void setTrackCancelByRef(ITrackCancel ppTrackCancel)
          The object used by the PageLayoutControl to check if drawing has been aborted.
 IPoint toPagePoint(int x, int y)
          Converts device co-ordinates (typically pixels) to a point on the page (in page units).
 IEnvelope trackRectangle()
          Rubber-bands a rectangle on the PageLayoutControl.
 void zoomToWholePage()
          Changes the extent of the PageLayout to show a whole page.
 

Method Detail

setBackColor

void setBackColor(int pclr)
                  throws IOException,
                         AutomationException
Background color of the PageLayoutControl.

Product Availability

Available with ArcGIS Engine.

Parameters:
pclr - The pclr (A COM typedef) (in)
Throws:
IOException - If there are interop problems.
AutomationException - If the ArcObject component throws an exception.

getBackColor

int getBackColor()
                 throws IOException,
                        AutomationException
Background color of the PageLayoutControl.

Description

Returns or sets the Background Color of the PageLayoutControl. The Background color is used to draw the area of the Control outside the Page itself. Internally the OLE_Color is stored as a long integer where the value may be calculated for any RGB combination as follows:

OLE_Color = (Red) + (Green * 256) + (Blue * 256 * 256)

Where Red, Green and Blue are Long Integers within the range 0 - 255.

Product Availability

Available with ArcGIS Engine.

Returns:
The pclr (A COM typedef)
Throws:
IOException - If there are interop problems.
AutomationException - If the ArcObject component throws an exception.

setBorderStyle

void setBorderStyle(int pstyle)
                    throws IOException,
                           AutomationException
The border style of the PageLayoutControl.

Product Availability

Available with ArcGIS Engine.

Parameters:
pstyle - A com.esri.arcgis.controls.esriControlsBorderStyle constant (in)
Throws:
IOException - If there are interop problems.
AutomationException - If the ArcObject component throws an exception.

getBorderStyle

int getBorderStyle()
                   throws IOException,
                          AutomationException
The border style of the PageLayoutControl.

Description

Returns or sets the border style of a PageLayoutControl. By default a border is drawn.

Product Availability

Available with ArcGIS Engine.

Returns:
A com.esri.arcgis.controls.esriControlsBorderStyle constant
Throws:
IOException - If there are interop problems.
AutomationException - If the ArcObject component throws an exception.

esri_setEnabled

void esri_setEnabled(boolean pbool)
                     throws IOException,
                            AutomationException
Indicates whether the PageLayoutControl can respond to user generated events.

Product Availability

Available with ArcGIS Engine.

Parameters:
pbool - The pbool (in)
Throws:
IOException - If there are interop problems.
AutomationException - If the ArcObject component throws an exception.

esri_isEnabled

boolean esri_isEnabled()
                       throws IOException,
                              AutomationException
Indicates whether the PageLayoutControl can respond to user generated events.

Product Availability

Available with ArcGIS Engine.

Returns:
The pbool
Throws:
IOException - If there are interop problems.
AutomationException - If the ArcObject component throws an exception.

setAppearance

void setAppearance(int pappearance)
                   throws IOException,
                          AutomationException
The appearance of the PageLayoutControl.

Product Availability

Available with ArcGIS Engine.

Parameters:
pappearance - A com.esri.arcgis.controls.esriControlsAppearance constant (in)
Throws:
IOException - If there are interop problems.
AutomationException - If the ArcObject component throws an exception.

getAppearance

int getAppearance()
                  throws IOException,
                         AutomationException
The appearance of the PageLayoutControl.

Description

Returns or sets the paint style of a PageLayoutControl to either Flat or 3D. By default the appearance is flat.

Product Availability

Available with ArcGIS Engine.

Returns:
A com.esri.arcgis.controls.esriControlsAppearance constant
Throws:
IOException - If there are interop problems.
AutomationException - If the ArcObject component throws an exception.

setMousePointer

void setMousePointer(int ppointer)
                     throws IOException,
                            AutomationException
The mouse pointer displayed over the PageLayoutControl.

Product Availability

Available with ArcGIS Engine.

Parameters:
ppointer - A com.esri.arcgis.controls.esriControlsMousePointer constant (in)
Throws:
IOException - If there are interop problems.
AutomationException - If the ArcObject component throws an exception.

getMousePointer

int getMousePointer()
                    throws IOException,
                           AutomationException
The mouse pointer displayed over the PageLayoutControl.

Description

Use this property when you want to indicate changes in functionality as the mouse pointer passes over the PageLayoutControl. The esriPointerArrowHourglass setting (11) is useful for indicating that the user should wait for a process or operation to finish.

Product Availability

Available with ArcGIS Engine.

Returns:
A com.esri.arcgis.controls.esriControlsMousePointer constant
Throws:
IOException - If there are interop problems.
AutomationException - If the ArcObject component throws an exception.
See Also:
IPageLayoutControl.getMouseIcon()

setMouseIconByRef

void setMouseIconByRef(Picture ppMouseIcon)
                       throws IOException,
                              AutomationException
Custom mouse icon used if MousePointer is 99.

Description

The MouseIcon property provides a custom icon that is used when the IPageLayoutControl::MousePointer property is set to 99.

You can use the MouseIcon property to load either cursor (.cur) or icon (.ico) files. The MouseIcon property provides your program with easy access to custom cursors of any size, with any desired hot spot location. This property cannot be used to load animated cursor (.ani) files.

PageLayoutControl1.MouseIcon = LoadPicture("c:\winnt\cursors\mycursor.cur")

Product Availability

Available with ArcGIS Engine.

Parameters:
ppMouseIcon - A reference to a com.esri.arcgis.support.ms.stdole.Picture (A com.esri.arcgis.support.ms.stdole.Picture COM typedef) (in)
Throws:
IOException - If there are interop problems.
AutomationException - If the ArcObject component throws an exception.

getMouseIcon

Picture getMouseIcon()
                     throws IOException,
                            AutomationException
Custom mouse icon used if MousePointer is 99.

Description

The MouseIcon property provides a custom icon that is used when the MousePointer property is set to esriPointerArrowHourglass (99).

Remarks

In most development evironments the control's property pages can be used to load either a cursor (.cur) or icon (.ico) file. A cursor contains a custom 'hotspot' location and can be any size. The 'hotspot' location for an icon file defaults to the center of the icon. This property cannot be used to load animated cursor (.ani) files.

To programatically create an object implementing IPictureDisp there is the win32 function OleLoadPicture or helper methods depending on the development environment.

Product Availability

Available with ArcGIS Engine.

Returns:
A reference to a com.esri.arcgis.support.ms.stdole.Picture (A com.esri.arcgis.support.ms.stdole.Picture COM typedef)
Throws:
IOException - If there are interop problems.
AutomationException - If the ArcObject component throws an exception.
See Also:
IPageLayoutControl.getMousePointer()

getHWnd

int getHWnd()
            throws IOException,
                   AutomationException
Handle to the window associated with the PageLayoutControl.

Description

The operating environment identifies each window, form and control in an application by assigning it a handle, or hWnd. Many ArcObjects methods and Windows API calls require the hWnd as an argument.

Product Availability

Available with ArcGIS Engine.

Returns:
The hWnd
Throws:
IOException - If there are interop problems.
AutomationException - If the ArcObject component throws an exception.

aboutBox

void aboutBox()
              throws IOException,
                     AutomationException
Displays a dialog of information about the PageLayoutControl.

Description

The AboutBox method causes a modal dialog box to display on top of the PageLayoutControl, containing information about the version and creation date of the PageLayoutControl as well as listing relevant legal and copyright information from ESRI.

Product Availability

Available with ArcGIS Engine.

Throws:
IOException - If there are interop problems.
AutomationException - If the ArcObject component throws an exception.

getCurrentTool

ITool getCurrentTool()
                     throws IOException,
                            AutomationException
Current active tool for the PageLayoutControl. Set to nothing to clear the tool.

Description

The CurrentTool is the tool used to interact will the PageLayoutControl's display. Always check if a tool is enabled before setting it to the CurrentTool property, otherwise a user will be able to use a tool that is actually disabled.

Remarks

When the CurrentTool is set the following events occur:

  1. The ITool::Deactivate event is triggered on the 'old' CurrentTool if one was set. If this event returns false a trappable error ocurrs. If this event returns true the 'old' CurrentTool is removed and replaced.
  2. The ICommand::OnClick event is triggered on the 'new' CurrentTool and its cursor is picked up.

Within an ITool implementation it is recommended that the ITool::Deactivate event returns true. This allows a 'new' CurrentTool to be set, and allows the release of the CurrentTool when an application is shutting down.

Product Availability

Available with ArcGIS Engine.

Returns:
A reference to a com.esri.arcgis.systemUI.ITool
Throws:
IOException - If there are interop problems.
AutomationException - If the ArcObject component throws an exception.

setCurrentToolByRef

void setCurrentToolByRef(ITool pTool)
                         throws IOException,
                                AutomationException
Current active tool for the PageLayoutControl. Set to nothing to clear the tool.

Product Availability

Available with ArcGIS Engine.

Parameters:
pTool - A reference to a com.esri.arcgis.systemUI.ITool (in)
Throws:
IOException - If there are interop problems.
AutomationException - If the ArcObject component throws an exception.

getPageLayout

IPageLayout getPageLayout()
                          throws IOException,
                                 AutomationException
The PageLayout contained by the PageLayoutControl.

Description

This is the PageLayout CoClass contained within the PageLayoutControl. If the PageLayout is replaced the IPageLayoutControlEvents::OnPageLayoutReplaced event is triggered.

Product Availability

Available with ArcGIS Engine.

Returns:
A reference to a com.esri.arcgis.carto.IPageLayout
Throws:
IOException - If there are interop problems.
AutomationException - If the ArcObject component throws an exception.
See Also:
IPageLayoutControl.getPrinterPageCount(double), IPageLayoutControl.printPageLayout(short, short, double), IPageLayoutControl.getPrinter(), IPageLayoutControl.getPage()

setPageLayoutByRef

void setPageLayoutByRef(IPageLayout pPageLayout)
                        throws IOException,
                               AutomationException
The PageLayout contained by the PageLayoutControl.

Product Availability

Available with ArcGIS Engine.

Parameters:
pPageLayout - A reference to a com.esri.arcgis.carto.IPageLayout (in)
Throws:
IOException - If there are interop problems.
AutomationException - If the ArcObject component throws an exception.

getActiveView

IActiveView getActiveView()
                          throws IOException,
                                 AutomationException
The active view of the PageLayout contained by the PageLayoutControl.

Description

This is the ActiveView on the PageLayout CoClass contained within the PageLayoutControl.

Remarks

When the PageLayoutControl is added to a container the PageLayout's element selection, IActiveView::Selection, is Nothing. This causes the esriViewGraphicSelection draw phase to ignore any selected graphics. To resolve this, set the IActiveView::Selection property to the IViewManager::ElementSelection property. This will result in the MapFrame element becoming selected.

The IActiveView::ShowRuler property will not display any rulers on the PageLayout because the PageLayoutControl does not itself manage rulers. An application must draw its own rulers.

Product Availability

Available with ArcGIS Engine.

Returns:
A reference to a com.esri.arcgis.carto.IActiveView
Throws:
IOException - If there are interop problems.
AutomationException - If the ArcObject component throws an exception.

getExtent

IEnvelope getExtent()
                    throws IOException,
                           AutomationException
Current extent of the PageLayout in page units.

Description

Returns or sets a new envelope which is represents the visible extent of the PageLayout. Setting the Extent property will automatically cause the PageLayoutControl to refresh its display.

Product Availability

Available with ArcGIS Engine.

Returns:
A reference to a com.esri.arcgis.geometry.IEnvelope
Throws:
IOException - If there are interop problems.
AutomationException - If the ArcObject component throws an exception.

setExtent

void setExtent(IEnvelope extent)
               throws IOException,
                      AutomationException
Current extent of the PageLayout in page units.

Product Availability

Available with ArcGIS Engine.

Parameters:
extent - A reference to a com.esri.arcgis.geometry.IEnvelope (in)
Throws:
IOException - If there are interop problems.
AutomationException - If the ArcObject component throws an exception.

getFullExtent

IEnvelope getFullExtent()
                        throws IOException,
                               AutomationException
Rectangular shape that encloses the PageLayout.

Description

Returns or sets an envelope object which by default is the PageLayout's page size expanded by a factor of 1.9 and which is automatically set whenever the page size changes. Setting the FullExtent triggers the IPageLayoutControlEvents::OnFullExtentUpated event.

Remarks

The FullExtent property is a shortcut to IActiveView::FullExtent which is in turn a shortcut to IDisplayTransformation::Bounds. Setting the FullExtent property will not affect the Extent property.

Product Availability

Available with ArcGIS Engine.

Returns:
A reference to a com.esri.arcgis.geometry.IEnvelope
Throws:
IOException - If there are interop problems.
AutomationException - If the ArcObject component throws an exception.

setFullExtent

void setFullExtent(IEnvelope fullExtent)
                   throws IOException,
                          AutomationException
Rectangular shape that encloses the PageLayout.

Product Availability

Available with ArcGIS Engine.

Parameters:
fullExtent - A reference to a com.esri.arcgis.geometry.IEnvelope (in)
Throws:
IOException - If there are interop problems.
AutomationException - If the ArcObject component throws an exception.

getPage

IPage getPage()
              throws IOException,
                     AutomationException
The Page associated with the PageLayout contained by the PageLayoutControl.

Description

The Page property is based upon the IPageLayout::Page property. Use the Page to manage the on screen visual representation of the printer page such as page size and orientation.

Product Availability

Available with ArcGIS Engine.

Returns:
A reference to a com.esri.arcgis.carto.IPage
Throws:
IOException - If there are interop problems.
AutomationException - If the ArcObject component throws an exception.
See Also:
IPageLayoutControl.getPrinterPageCount(double), IPageLayoutControl.printPageLayout(short, short, double), IPageLayoutControl.getPageLayout(), IPageLayoutControl.getPrinter()

getGraphicsContainer

IGraphicsContainer getGraphicsContainer()
                                        throws IOException,
                                               AutomationException
The graphics container of the PageLayout object contained by the PageLayoutControl.

Description

This property is a shortcut to IActiveView::GraphicsContainer.

Remarks

This property will always return a reference to the PageLayout's GraphicsContainer rather than to any GraphicsContainer associated with a Map.

Product Availability

Available with ArcGIS Engine.

Returns:
A reference to a com.esri.arcgis.carto.IGraphicsContainer
Throws:
IOException - If there are interop problems.
AutomationException - If the ArcObject component throws an exception.

printPageLayout

void printPageLayout(short startPage,
                     short endPage,
                     double overlap)
                     throws IOException,
                            AutomationException
Sends the specified range of pages on the printer.

Description

PrintPageLayout sends the PageLayout to the Printer. If the Page does not fit the IPrinter::Paper, the value of IPage::PageToPrinterMapping will determine whether the Page is cropped, scaled or tiled across the Printer's paper.

Remarks

Before using the PrintPageLayout property, ensure that the orientation of IPrinter::Paper is the same orientation as the Page.

Product Availability

Available with ArcGIS Engine.

Parameters:
startPage - The startPage (in, optional, pass 1 if not required)
endPage - The endPage (in, optional, pass 0 if not required)
overlap - The overlap (in, optional, pass 0 if not required)
Throws:
IOException - If there are interop problems.
AutomationException - If the ArcObject component throws an exception.
See Also:
IPageLayoutControl.getPrinterPageCount(double), IPageLayoutControl.getPageLayout(), IPageLayoutControl.getPrinter(), IPageLayoutControl.getPage()

getPrinter

IPrinter getPrinter()
                    throws IOException,
                           AutomationException
The printer object used by the PageLayoutControl for printing.

Description

Unless the Printer property has been set to a specific printer, the property will return the default system printer. Before issuing a print always check that the PageLayoutControl has a printer.

Product Availability

Available with ArcGIS Engine.

Returns:
A reference to a com.esri.arcgis.output.IPrinter
Throws:
IOException - If there are interop problems.
AutomationException - If the ArcObject component throws an exception.
See Also:
IPageLayoutControl.getPrinterPageCount(double), IPageLayoutControl.printPageLayout(short, short, double), IPageLayoutControl.getPageLayout(), IPageLayoutControl.getPage()

setPrinterByRef

void setPrinterByRef(IPrinter ppPrinter)
                     throws IOException,
                            AutomationException
The printer object used by the PageLayoutControl for printing.

Product Availability

Available with ArcGIS Engine.

Parameters:
ppPrinter - A reference to a com.esri.arcgis.output.IPrinter (in)
Throws:
IOException - If there are interop problems.
AutomationException - If the ArcObject component throws an exception.

getTrackCancel

ITrackCancel getTrackCancel()
                            throws IOException,
                                   AutomationException
The object used by the PageLayoutControl to check if drawing has been aborted.

Remarks

Use the TrackCancel object to enable users to stop printing, exporting or drawing processes by using the escape or spacebar keys.

Product Availability

Available with ArcGIS Engine.

Returns:
A reference to a com.esri.arcgis.system.ITrackCancel
Throws:
IOException - If there are interop problems.
AutomationException - If the ArcObject component throws an exception.

setTrackCancelByRef

void setTrackCancelByRef(ITrackCancel ppTrackCancel)
                         throws IOException,
                                AutomationException
The object used by the PageLayoutControl to check if drawing has been aborted.

Product Availability

Available with ArcGIS Engine.

Parameters:
ppTrackCancel - A reference to a com.esri.arcgis.system.ITrackCancel (in)
Throws:
IOException - If there are interop problems.
AutomationException - If the ArcObject component throws an exception.

pan

void pan()
         throws IOException,
                AutomationException
Tracks the mouse while panning the PageLayoutControl.

Description

Pan preserves the scale of the PageLayout, but changes the Extent property.

Remarks

Use the Pan method within the IPageLayoutControlEvents::OnMouseDown event to allow the user to pan contents of the PageLayoutControl. The IPageLayoutControlEvents::OnMouseMove event will be triggered during the pan, but no IPageLayoutControlEvents::OnMouseUp event will occur. The ESC key on the keyboard can be used during panning to cancel the Pan.

Product Availability

Available with ArcGIS Engine.

Throws:
IOException - If there are interop problems.
AutomationException - If the ArcObject component throws an exception.

centerAt

void centerAt(IPoint centerPoint)
              throws IOException,
                     AutomationException
Moves the center of the PageLayoutControl to the specified location.

Description

The CenterAt method positions the supplied point in the center of the PageLayoutControl. The Extent of the PageLayoutControl will change, but the scale will remain the same.

Product Availability

Available with ArcGIS Engine.

Parameters:
centerPoint - A reference to a com.esri.arcgis.geometry.IPoint (in)
Throws:
IOException - If there are interop problems.
AutomationException - If the ArcObject component throws an exception.

trackRectangle

IEnvelope trackRectangle()
                         throws IOException,
                                AutomationException
Rubber-bands a rectangle on the PageLayoutControl.

Description

Use the TrackRectangle method within the IPageLayoutControlEvents::OnMouseDown event to rubberband a user defined rectangle. The IPageLayoutControlEvents::OnMouseMove event will be triggered during the track, but no IPageLayoutControlEvents::OnMouseUp event will occur. The ESC key on the keyboard can be used during the track to cancel the TrackRectangle.

Product Availability

Available with ArcGIS Engine.

Returns:
A reference to a com.esri.arcgis.geometry.IEnvelope
Throws:
IOException - If there are interop problems.
AutomationException - If the ArcObject component throws an exception.

addElement

void addElement(IElement pElement,
                Object geometry,
                Object symbology,
                Object name,
                int zOrder)
                throws IOException,
                       AutomationException
Adds the supplied element to the PageLayout, with optional geometry, symbolization, name and Z order.

Description

Adds an element to the GraphicsContainer.

geometry an object that implements IGeometry
symbology an object that implements ISymbol or IColor (symbology is applied to the element using the IPropertySupport interface)
name a string

Product Availability

Available with ArcGIS Engine.

Parameters:
pElement - A reference to a com.esri.arcgis.carto.IElement (in)
geometry - A Variant (in, optional, pass null if not required)
symbology - A Variant (in, optional, pass null if not required)
name - A Variant (in, optional, pass null if not required)
zOrder - The zOrder (in, optional, pass 0 if not required)
Throws:
IOException - If there are interop problems.
AutomationException - If the ArcObject component throws an exception.
See Also:
IPageLayoutControl.locateFrontElement(double, double, double), IPageLayoutControl.findElementByName(String, int)

locateFrontElement

IElement locateFrontElement(double pageX,
                            double pageY,
                            double tolerance)
                            throws IOException,
                                   AutomationException
Locates an element at the given page co-ordinates. If more than one element is at the location the element nearest the front is returned.

Description

LocateFrontElement is typically used within the IPageLayoutControlEvents::OnMouseDown event to retrieve an element at the given page coordinates. If more than one element exists at the given page coordinates, the element located at the front is returned.

Product Availability

Available with ArcGIS Engine.

Parameters:
pageX - The pageX (in)
pageY - The pageY (in)
tolerance - The tolerance (in, optional, pass 0 if not required)
Returns:
A reference to a com.esri.arcgis.carto.IElement
Throws:
IOException - If there are interop problems.
AutomationException - If the ArcObject component throws an exception.
See Also:
IPageLayoutControl.findElementByName(String, int), IPageLayoutControl.addElement(com.esri.arcgis.carto.IElement, java.lang.Object, java.lang.Object, java.lang.Object, int)

findElementByName

IElement findElementByName(String name,
                           int occurence)
                           throws IOException,
                                  AutomationException
Find the first element with the supplied name, supply an occurrence parameter to find the second, third and so on.

Description

If an empty string is supplied then any elements with no name are found. By default new elements are created with no name. To give an element a name so it can easily be found use one of the following methods: either supply a name string when using the AddElement method, or implement the IElementProperties interface.

Product Availability

Available with ArcGIS Engine.

Parameters:
name - The name (in)
occurence - The occurence (in, optional, pass 1 if not required)
Returns:
A reference to a com.esri.arcgis.carto.IElement
Throws:
IOException - If there are interop problems.
AutomationException - If the ArcObject component throws an exception.
See Also:
IPageLayoutControl.locateFrontElement(double, double, double), IPageLayoutControl.addElement(com.esri.arcgis.carto.IElement, java.lang.Object, java.lang.Object, java.lang.Object, int)

loadMxFile

void loadMxFile(String fileName,
                Object password)
                throws IOException,
                       AutomationException
Loads the specified map document into the PageLayout contained by the PageLayoutControl.

Description

Loads an map document into the PageLayoutControl. The map document can be an ArcMap document, an ArcMap template or an ArcReader document. Use the CheckMxFile method to determine if the specified map document is a valid map document.

Remarks

When LoadMXfile is used the user may be prompted for a password; refer to the tables below to determine when this may occur. Additionally, password prompts may be given if accessing MapDocuments using either the PageLayoutControl's PropertyPage, ArcMap or ArcReader; the tables also show in what circumstances this will occur.

Loading Map Documents (*.mxd, *.mxt, *.pmf) which reference IMS Services (with and without security)

Application No Secure Services MXD/ MXT/ PMF files Secure Servcies MXD/ MXT/ PMF files Secure Servcies (password cached) MXD/ MXT files Secure Servcies (password cached) PMF files
PageLayoutControl (programmatically) No Prompt Prompt No Prompt Prompt
PageLayoutControl (property pages) No Prompt Prompt No Prompt Prompt
ArcMap No Prompt Prompt No Prompt Prompt
ArcReader (PMF files only) No Prompt Prompt N/A No Prompt

* The Connection to the Internet server must have the Save User/ Password setting enabled. This can be set, for example, when using Add Internet Server in the Add Layers Dialog. Additionally, in the case of PMF files the ArcPublisher Cache password in PMF file setting must be enabled.

Loading Published Map Files (*.pmf) (with and without password protection)

Application PMF with No Password PMF with Password
PageLayoutControl (programmatically) No Prompt Supply in Code
PageLayoutControl (property pages) No Prompt Prompt
ArcMap No Prompt Prompt
ArcReader No Prompt Prompt

Product Availability

Available with ArcGIS Engine.

Parameters:
fileName - The fileName (in)
password - A Variant (in, optional, pass null if not required)
Throws:
IOException - If there are interop problems.
AutomationException - If the ArcObject component throws an exception.
See Also:
IPageLayoutControl.checkMxFile(String)

isOleDropEnabled

boolean isOleDropEnabled()
                         throws IOException,
                                AutomationException
Indicates if the PageLayoutControl will fire events when data is dragged over the control's window.

Description

Indicates if the PageLayoutControl will accept data dragged from another application and fire the IPageLayoutControlEvents::OnOleDrop event. By default the OleDropEnabled property is set to false.

Product Availability

Available with ArcGIS Engine.

Returns:
The value
Throws:
IOException - If there are interop problems.
AutomationException - If the ArcObject component throws an exception.

setOleDropEnabled

void setOleDropEnabled(boolean value)
                       throws IOException,
                              AutomationException
Indicates if the PageLayoutControl will fire events when data is dragged over the control's window.

Product Availability

Available with ArcGIS Engine.

Parameters:
value - The value (in)
Throws:
IOException - If there are interop problems.
AutomationException - If the ArcObject component throws an exception.

checkMxFile

boolean checkMxFile(String fileName)
                    throws IOException,
                           AutomationException
Checks the specified filename to see if it is a map document that can be loaded into the PageLayoutControl.

Description

Determines whether the specified map document (*.mxd, *.mxt, *.pmf) is a valid map document and can be loaded into the PageLayoutControl. The method verifies the file exists and verifies the file internals conform to an expected storage format. The method does not read and validate the entire contents of the file; use the LoadMxFile to do this.

Product Availability

Available with ArcGIS Engine.

Parameters:
fileName - The fileName (in)
Returns:
The result
Throws:
IOException - If there are interop problems.
AutomationException - If the ArcObject component throws an exception.
See Also:
IPageLayoutControl.loadMxFile(String, java.lang.Object)

zoomToWholePage

void zoomToWholePage()
                     throws IOException,
                            AutomationException
Changes the extent of the PageLayout to show a whole page.

Description

The method is based upon the IPageLayout::ZoomToWhole method.

Product Availability

Available with ArcGIS Engine.

Throws:
IOException - If there are interop problems.
AutomationException - If the ArcObject component throws an exception.

getPrinterPageCount

short getPrinterPageCount(double overlap)
                          throws IOException,
                                 AutomationException
The number of printer pages the PageLayout will cover.

Product Availability

Available with ArcGIS Engine.

Parameters:
overlap - The overlap (in, optional, pass 0 if not required)
Returns:
The pageCount
Throws:
IOException - If there are interop problems.
AutomationException - If the ArcObject component throws an exception.

refresh

void refresh(int phase,
             Object layerOrElement,
             Object envelope)
             throws IOException,
                    AutomationException
Redraws the PageLayout, optionally just redraw specified phases or envelope.

Description

Use the Refresh method to redraw the display. If the Refresh method is used and no arguments are supplied the refresh is based upon the IActiveView::Refresh method.

In all other cases the refresh is based upon the IActiveView::PartialRefresh method. The Refresh method supports the esriViewDrawPhases given below:

0 :esriViewNone

1 :esriViewBackground

2 :esriViewGeography

4 :esriViewGeoSelection

8 :esriViewGraphics

16 :esriViewSelection

32 :esriViewForeground

If the Refresh method is used and no phase argument is supplied, but one of the other arguments is supplied then all phases will be refreshed and the phase value will be 65535. Always supply a phase whenever possible to increase efficiency.

Use the layerOrElement argument to refresh a particular layer or graphic element. Use the envelope argument to refresh only a particular region. For example, if a new graphic is added you may only want to refresh the area surrounding the graphic.

Remarks

Use the TrackCancel object to set whether users can stop drawing processes by using the escape or spacebar keys or by clicking the mouse.

Product Availability

Available with ArcGIS Engine.

Parameters:
phase - A com.esri.arcgis.carto.esriViewDrawPhase constant (in, optional, pass 65535 if not required)
layerOrElement - A Variant (in, optional, pass null if not required)
envelope - A Variant (in, optional, pass null if not required)
Throws:
IOException - If there are interop problems.
AutomationException - If the ArcObject component throws an exception.

fromPagePoint

void fromPagePoint(IPoint pt,
                   int[] x,
                   int[] y)
                   throws IOException,
                          AutomationException
Converts a point on the page (in page units) to device co-ordinates (typically pixels).

Description

The FromPagePoint method takes an input point in IPage::Units, and populates two variables with the equivalent control coordinates in pixels.

Product Availability

Available with ArcGIS Engine.

Parameters:
pt - A reference to a com.esri.arcgis.geometry.IPoint (in)
x - The x (in/out: use single element array)
y - The y (in/out: use single element array)
Throws:
IOException - If there are interop problems.
AutomationException - If the ArcObject component throws an exception.
See Also:
IPageLayoutControl.toPagePoint(int, int)

toPagePoint

IPoint toPagePoint(int x,
                   int y)
                   throws IOException,
                          AutomationException
Converts device co-ordinates (typically pixels) to a point on the page (in page units).

Description

ToPagePoint converts a (X,Y) location in pixels to IPage::Units.

Product Availability

Available with ArcGIS Engine.

Parameters:
x - The x (in)
y - The y (in)
Returns:
A reference to a com.esri.arcgis.geometry.IPoint
Throws:
IOException - If there are interop problems.
AutomationException - If the ArcObject component throws an exception.
See Also:
IPageLayoutControl.fromPagePoint(com.esri.arcgis.geometry.IPoint, int[], int[])