Purpose
Returns information about a frame within a Layout window. In a multi-page layout, this function only returns information about a frame on the current page selection. You can call this function from the MapBasic window in MapInfo Pro.
This function is very similar to the LayoutPageItemInfo() function, which you can use if the page you want to query is not the currently visible page in the Layout window.
Syntax
LayoutItemInfo( window_id, frame_id, attribute )window_id is an integer window identifier for a Layout window.
frame_id is a number, or the string name, that specifies which frame within the Layout window you want to query. Frames are numbered 1 to n where n is the number of frames in the layout. Frame names are strings with at most 255 characters that are set in the Name clause when the frame is created, or by using the Alter Designer Frame statement, or editing the Name field in the Layout Frame Properties dialog.
attribute is an integer code indicating which type of information to return. For values, see the table later in this description.
Return Value
Depends on the attribute parameter, see the table later in this description.
Description
The LayoutItemInfo() function returns information about a Layout window. The function does not apply to the classic Layout window. In a multi-page layout, this function only returns information about a frame on the current page selection.
The window_id parameter specifies which window to query. To obtain a window identifier, call the FrontWindow() function immediately after opening a window, or call the WindowID() function at any time after the window's creation.
There are several attributes that LayoutItemInfo() returns about any given Layout window. The attribute parameter tells the LayoutItemInfo() function what Layout window statistic to return. The attribute parameter should be one of the codes from the following table; codes are defined in MAPBASIC.DEF.
| Attribute Parameter | ID | LayoutItemInfo() Return Value |
|---|---|---|
| LAYOUT_ITEM_INFO_POS_X | 1 | Float value: Returns the position of the item as a distance from the left edge of the layout in paper units. |
| LAYOUT_ITEM_INFO_POS_Y | 2 | Float value: Returns the position of the item as a distance from the top edge of the layout in paper units. |
| LAYOUT_ITEM_INFO_WIDTH | 3 | Float value: Returns the width of the item in the layout in paper units. |
| LAYOUT_ITEM_INFO_HEIGHT | 4 | Float value: Returns the height of the item in the layout in paper units. |
| LAYOUT_ITEM_INFO_WIN | 5 | Integer value: Returns the window id for the layout item (frame). Or returns 0 if there is no associated window. |
| LAYOUT_ITEM_INFO_SELECTED | 6 | Logical value: Returns True if the item is currently selected. |
| LAYOUT_ITEM_INFO_ACTIVATED | 7 | Logical value: Returns True if the item is currently activated (for example, activating a map frame by pressing Alt while clicking on the frame). |
| LAYOUT_ITEM_INFO_EMPTY | 8 | Logical value: Returns True if the item is an empty frame, false otherwise. |
| LAYOUT_ITEM_INFO_LEGEND_FRAME_ID | 9 | Integer value: For legend frames. Returns the index number for a legend frame in the parent Legend window. This value can be used in Legend MapBasic statements. Returns 0 for non-legend frames. |
| LAYOUT_ITEM_INFO_LEGEND_DESIGNER_WINDOW | 10 | Integer value: For legend frames. Returns the window ID for the parent Legend window. This value can be used in Legend MapBasic statements. Returns 0 for non-legend frames. |
| LAYOUT_ITEM_INFO_TYPE | 11 | SmallInt value: Returns a number representing the frame type. See table below. |
| LAYOUT_ITEM_INFO_IMAGE_FILE | 12 | String value: For image frames. Returns the full path of the image file in a frame. If the image frame is in an error state, the path is to the file that the frame is trying to display. Returns an empty string for non-image frames. |
| LAYOUT_ITEM_INFO_OBJ | 13 | Object value: Returns the object in a text or shape frame. For text frames, returns an object. For shape frames, returns a line, rectangle, rounded rectangle, or ellipse object. For frames that do not contain an object, returns an uninitialized object. |
| LAYOUT_ITEM_INFO_NAME | 14 | String value: Returns the name of the layout frame. |
| LAYOUT_ITEM_INFO_PEN | 15 | Pen value. Returns the pen of a shape or a frame. |
| LAYOUT_ITEM_INFO_FILL_BRUSH | 16 | Brush value. Returns the brush style of a shape or a frame. This is not valid for a frame containing a line shape. |
| LAYOUT_ITEM_INFO_Z_ORDER | 17 | Integer: Returns the z-order of the item. The z-order is taken from the normalized set of frame priorities where each element is unique. |
| LAYOUT_ITEM_INFO_ANGLE | 18 | Float value that returns either the frame rotation for Image and Text frames, or the TrueType symbol rotation for symbol frames . The value represents the angle in degrees. If a frame does not support rotation, it will return 0.0. |
| LAYOUT_ITEM_INFO_ADDIN_FILE_NAME | 19 | String: Name of the custom frame add-in file. |
| LAYOUT_ITEM_INFO_SERIALIZED_NAME | 20 | String: Name of the custom frame serialized file. |
| LAYOUT_ITEM_INFO_XPS_VIEW_NAME | 21 | String: Name of the custom frame XPS view file. |
| LAYOUT_ITEM_INFO_NUM_ITEMS_ON_PAGE | 22 | Integer: Number of frames on this layout page. Frame ID is ignored. |
| LAYOUT_ITEM_INFO_FRAME_UNIQUE_ID | 23 | String: Unique frame id of layout frame. |
| LAYOUT_ITEM_INFO_TEXTSTRING | 24 | String: only valid for text frames. Returns the unformatted string contained in the text frame control. This is the same string returned by using the ObjectInfo attribute OBJ_INFO_TEXTSTRING (3) on the text object returned by LAYOUT_ITEM_INFO_OBJ. Formatting such as All Caps and Expanded are not part of the returned string. |
| LAYOUT_ITEM_INFO_SMART_TEXTSTRING | 25 | String: only valid for text frames. Returns the unformatted string displayed in the text frame control; if the text contains Smart Text expressions, the evaluated return value of the expressions are returned within the string. If any Smart Text expression fails evaluation an error string is returned. Formatting such as All Caps and Expanded are not part of the returned string. |
The following lists the frame type returned using LAYOUT_ITEM_INFO_TYPE.
| Frame Type | ID | Frame Description |
|---|---|---|
| LAYOUT_ITEM_TYPE_ANY | -1 | The first frame found with the specified name, regardless of what type of frame it is. |
| LAYOUT_ITEM_TYPE_EMPTY | 0 | An empty frame: a frame with no content. |
| LAYOUT_ITEM_TYPE_MAPPER | 1 | A map frame. |
| LAYOUT_ITEM_TYPE_BROWSER | 2 | A browser frame. |
| LAYOUT_ITEM_TYPE_LEGEND | 3 | A legend frame. |
| LAYOUT_ITEM_TYPE_TEXT | 4 | A text frame. |
| LAYOUT_ITEM_TYPE_SHAPE | 5 | A shape frame, such as a line, rectangle, rounded rectangle, or ellipse. |
| LAYOUT_ITEM_TYPE_IMAGE | 6 | An image frame. |
| LAYOUT_ITEM_TYPE_CUSTOM | 7 | An custom frame. |
Paper unit values are in inches by default. To change the paper units, use the Set Paper Units statement.
Use the LayoutPageItemInfo() function to obtain information for any page in a Layout window.
See Also:
FrontWindow() function, LayoutInfo() function, LayoutItemID() function, LayoutPageItemInfo() function, Set Paper Units statement, WindowID() function