Purpose
Adds a custom frame to a Layout window.
Syntax
Add Custom Frame [ Window window_id ]
[ Position ( x, y ) [ Units paper_units ] ]
[ Width frame_width [ Units paper_units ] ]
[ Height frame_height [ Units paper_units ] ]
[ Pen ... ] [ Brush ... ] [ Priority n ]
[ Name frame_name ]
From { File addin_mbx_file_name.mbx }
Using serialized_custom_frame_file_name.mlcf
View xps_custom_frame_file_name.xps window_id is a Layout window's integer window identifier.
x, y specifies the position of the upper left corner of the image frame, in paper_units, in the Layout window.
paper_units is a string representing a paper unit name: cm (centimeters), mm (millimeters), in (inches), pt (points), and pica.
- 1 inch (in) = 2.54 centimeters , 254 millimeters, 6 picas, 72 points
- 1 point (pt) = 0.01389 inches, 0.03528 centimeters, 0.35278 millimeters, 0.08333 picas
- 1pica = 0.16667 inches, 0.42333 centimeters, 4.23333 millimeters, 12 points
- 1 centimeter (cm) = 0.39370 inches, 10 millimeters, 2.36220 picas, 28.34646 points
- 1 millimeter (mm) = 0.1 centimeters, 0.03937 inches, 0.23622 picas, 2.83465 points
frame_width and frame_height specify the width and height of the frame in the Layout window.
n is an integer value indicating the Z-Order value of objects (frames) on the Layout window. When creating a clone statement or saving a workspace, MapInfo Pro normalizes the priority of frames to a unique set of values beginning with 1.
frame_name is a string representing the frame name.
addin_mbx_file_name.mbx is a string representing the name of the addin mbx that create the contents of the custom frame and manage its behavior. The file name is short file name or a relative path name if the .mbx is stored within the MapInfo Pro Tools folder.
serialized_custom_frame_file_name.mlcf is a string representing the name of the serialized custom frame. This file is created by the add-in and can be in any format the Add-in developer choose to use as long as this file can be used to re-create the custom frame through the mapbasic command. This file has .mlcf as an extension.
xps_custom_frame_file_name.xps is a string representing the name of the xps file generated when the custom frame was saved into a workspace. This file has .xps as its extension. This file is needed in case when re-running the mapbasic command an error occurred during the loading of the add-in MBX or/and the use of the serialized custom frame file name in ordered to deserialize the custom frame. In such case the .xps file will be used as alternative to display the custom frame as it was when it was saved.
Description
The Add Custom Frame statement is only for .wor persistence and .wor loading. Executing this statement outside of loading a workspace (.wor), such as from a MapBasic window or MapBasic tool, displays an error stating that the executed command is not supported from within the MapBasic window or tool.
Custom frames cannot be cloned. Cloning a Layout window that has a custom frame in it causes MapInfo Pro to clone all of the frames in the Layout window except for the custom frame.