Browse statement - MapBasic - 2023

Purpose

Opens a new Browser window. You can issue this statement from the MapBasic window in MapInfo Pro.

Syntax

Browse expression_list From table
	[ Position ( x, y ) [ Units paper_units ] ]
	[ Width window_width [ Units paper_units ] ]
	[ Height window_height [ Units paper_units ] ]
	[ Row n ]
	[ Column n ]
	[ Min | Max | Floating | Docked | Tabbed | AutoHidden | Hide] 
	[ Pen .... ] [ Priority n ] [ Name framename ]
	[ Into { Window layout_win_id } { ID empty_frame_id } ]

expression_list is either an asterisk or a comma-separated list of column expressions.

table is a string representing the name of an open table.

x, y specifies the position of the upper left corner of the Browser, in paper_units. With the Into Window clause, the position is relative to the upper left corner of 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

Floating docking state makes the window floating.

Docked docking state docks the window to the default position.

Tabbed docking stae makes the window tabbed, in this state it is also callled as a document.

AutoHidden docking state auto hides the window.

Hide is an optional keyword that creates the window in a hidden state, and behaves the same as the Set Window id hide. You can then show the hidden window by using the Set Window...Show statement.

window_width and window_height specify the size of the Browser, in paper_units. With the Into Window clause, this represents the width and height of the frame in the Layout window. If a valid width or height is not specified, then a value is generated for the frame.

n is a positive integer value of 1 or higher.

framename is a string representing the name for this browser embedded in a layout frame. If a name is assigned to a frame in the Layout window, it will be written to the WOR. When the Name clause is written to the WOR, the workspace version is updated to version 1500.

layout_win_id is a Layout window's integer window identifier.

empty_frame_id is an emptly Layout window's integer window identifier.

Description

The Browse statement opens a Browse window to display a table. You can also use it to insert a Browser window into a Layout window when preparing a layout. This description will use the name Browser to mean either a Browser window in MapInfo Pro or a browser frame in a Layout window.

If the expression_list is simply an asterisk (*), the new Browser includes all fields in the table. Alternately, the expression_list clause can consist of a comma-separated list of expressions, each of which defines one column that is to appear in the Browser. Expressions in the list can contain column names, operators, functions, and variables. Each column's name is derived from the expression that defines the column. Thus, if a column is defined by the expression population / area(obj, "acre"), that expression will appear on the top row of the Browser, as the column name. To assign an alias to an expression, follow the expression with a string; see the example below.

An optional Position clause lets you specify where on the screen or in a layout to display the Browser. The x coordinate specifies the distance (in paper units) from the left edge of the MapInfo Pro application window to the left edge of the Browser window, or from the left edge of the Layout window to the left edge of a browser frame. For details about paper units, see Set Paper Units statement. The y coordinate specifies the distance from the top of the window down to the top of the Browser.

The optional Width and Height clauses specify the size of the Browser window, in paper units. If no Width and Height clauses are provided, MapInfo Pro assigns the Browser a default size that depends on the table in question. For a Browser window, its height will be one quarter of the screen height, unless the table does not have enough rows to fill a Browser window that large; and the Browser width will depend on the widths of the fields in the table.

The optional Width and Height clauses specify the size of the Browser, in paper units. If no Width and Height clauses are provided, MapInfo Pro assigns the Browser a default size that depends on the table in question. For a Browser window, its height will be one quarter of the screen height, unless the table does not have enough rows to fill a Browser window that large; and the Browser window's width will depend on the widths of the fields in the table.

If the Browse statement includes the optional Max keyword, then the resulting Browser is maximized, taking up all of the screen space available to MapInfo Pro or the entire canvas in a Layout Desinger window. Conversely, if the Browse statement includes the Min keyword, the Browser is minimized immediately.

The Row clause dictates which row of the table should appear at the top of the Browser. If the Browse statement does not include a Row clause, the first row of the table will be the top row in the Browser.

Similarly, the Column clause dictates which of the table's columns should appear at the left edge of the Browser. If the Browse statement does not include a Column clause, the table's first column will appear at the left edge of the Browser.

Pen is a valid Pen clause. This clause is designed to turn on (solid) or off (hollow) and set the color of the border of the frame.

Priority 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.

The Into Window clause creates a new frame within an existing Layout window.

Use the ID clause to insert open tables into an empty layout frame. The frame properties already set for the empty frame are retained (pen, brush, position, size, name, and z-order). An error results when the:

• From Window ID is not a map or browser: 1696 "Error: Expecting Map or Browser Window."
• Frame ID is not empty: 1698 "Layout frame ^0 must be empty."
• From Window does not close: 1697 "Unable to clone Window into empty frame."
• Map legends does not clone: 1708 "Unable to clone Legends for Map frame."

The following example creates a browser for the open table called World and inserts it into the empty frame in the Layout window.

Browser World Into Window layout_win_id ID empty_frame_id

To reuse a frame after it has been filled with content it needs to be emptied, see the Set Designer Frame statement. This leaves behind an empty frame of the same size and position as the content it just contained, and retains the name currently assigned to it.

Example

The following example opens the World table and displays all columns from the table in a Browser window.

Open Table "world"
Browse * From world

The next example specifies exactly which column expressions from the World table should be displayed in the Browser.

Open Table "world"
Browse
	country, 
	population,
	population/area(obj, "sq km") "Density"
	From world 

The resultant Browser has three columns. The first two columns represent data as it is stored in the World table, while the third column is derived. Through the third expression, MapBasic divides the population of each country record with the geographic area of the region associated with that record. The derived column expression has an alias ("Density") which appears on the top row of the Browse window.

See Also:

FrontWindow() function, Set Browse statement, Set Designer Frame statement, Set Paper Units statement, Set Window statement, WindowID() function