Class Browser

(back to index)

Scrolling list of lines

Inherits from Browser_

Subclasses: Hold_Browser  Multi_Browser  Select_Browser  

Property index


Function index


Key properties

readonly integer sizeNumber of lines
integer valueCurrently selected line
integer toplineTop line number visible

Key functions

void add(string s)Add an line at end
void remove(integer n)Remove an line
string text(integer n)Text of line
void load(string filename)Load contents from file


The Browser widget displays a scrolling list of text lines. This is not a text editor or spreadsheet! But it is useful for showing a vertical list of named objects to the user.

Each line in the browser is identified by number. The numbers start at one; zero is reserved for "no line" in the selective browsers. Unless otherwise noted, the methods do not check to see if the passed line number is in range and legal. It must always be greater than zero and <= size.

The base class does nothing when the user clicks on it. The subclasses Select_Browser, Hold_Browser, and Multi_Browser react to user clicks to select lines in the browser and do callbacks.

The base class called Browser_ provides the scrolling and selection mechanisms of this and all the subclasses, but the dimensions and appearance of each item are determined by the subclass. Subclasses of Browser_ could display information other than text, or text that is dynamically produced from your own data structures. If you find that loading the browser is a lot of work or is inefficient, you may want to make a subclass of _Browser_.

Formatting codes at the beginning of each line modify how the rest of the line is printed: Notice that the @. command can be used to reliably terminate the parsing. To print a random string in a random color, use sprintf("@C%d@.%s", color, string) and it will work even if the string starts with a digit or has the format character in it.

The format character @ may be changed with the format_char property, or all formatting can be disabled with clear_format_char()

Browsers support the display of multiple columns, if the column_widths property is set. Each line is split into columns by the column_char; it defaults to the tab character. See column_widths for more information.

Detailed reference

remove(integer n): void

Remove line n and make the browser one line shorter.

add(string s): void

Add a string to the end of the lines.

insert(integer n, string s): void

Insert a new line before line n. If n > size then the line is added to the end.

move(integer to, integer from): void

Line from is removed and reinserted at to; to is calculated after the line is removed.

load(string filename): void

Clears the browser and reads the file, adding each line from the file to the browser. If the filename is nil or a zero-length string then this just clears the browser. This returns nil if there was any error in opening or reading the file

clear(): void

Remove all the lines in the browser.

size: readonly integer

Returns how many lines are in the browser. The last line number is equal to this.

topline: integer

The current top line in the browser. Setting topline will scroll the browser such that the top line is this value.

If there is no vertical scrollbar then this will always return 1.

bottomline(integer n): void

Scrolls the browser so the bottom line in the browser is n.

middleline(integer n): void

Scrolls the browser so the middle line in the browser is n.

select(integer n, boolean value=1): boolean

Sets the selection state of line n to value.

Note that subclasses other than Multi_Browser will behave unpredictably if more than one line is selected.

selected(integer n): boolean

Returns true if line n is selected; otherwise nil.

show(integer n): void

Makes line n visible for selection. This undoes the effect of hide().

hide(integer n): void

Makes line n invisible, preventing selection by the user. The line can still be selected under program control.

visible(integer n): boolean

Returns true if line n is visible. See hide() for more information.

value: integer

The currently selected line number; 0 if no line is selected.

You should not change this on instances of Browser; it's only relevant to its subclasses.

text(integer n): string

Returns the text of line n. If n is out of range, it returns nil.

set_text(integer n, string s): void

Sets the text of line n to s

format_char: string

Sets the character used for format codes. See the class description for more information.

column_char: string

Sets the character used to separate columns. See the class description and column_widths()for more information.

column_widths: list

Specifies the widths in pixels of each column. The text is split at each column_char and each part is formatted into it's own column. After the last column any remaining text is formatted into the space between the last column and the right edge of the browser, even if the text contains instances of column_char . The default value is an empty list, which specifies no columns.

displayed(integer n): boolean

Returns true of line n is visible in the list.

make_visible(integer n): void

Displays line n, scrolling the list as necessary.

doctool generated at Sun Aug 12 22:23:18 2001