A table component provides a table-oriented display. Like a spreadsheet, it allows you to display data in an array of cells. It provides optimized drawing support, only drawing those cells that are visible.
The Table is optimized for row-based scrolling. By working with the firstVisibleRow property and the ShowRow() and Scroll() actions, you may cause the Table to scroll to a given row.
Drawing a table can be tricky--the table draws its own gridlines, but it's up to your handler to draw cell contents and any custom borders. It can be confusing if you don't know when various handlers are called. When the system redraws a table, it does so in the following order.
1. _aboutToDraw() event generated. If your table has children components that should be rearranged, this is a good time to do so.
2. Table blanks out exposed area (paints itself white). Table draws its gridlines.
3. _drawCell() event generated for each visible cell.
The following Table looks are available:
0 Record List. Table's grid-lines are solid.
1 Dotted Cells. Each cell drawn in a rounded dotted rectangle.
2 Dotted Horizontal Lines. Each row drawn with a dotted horizontal line.
Standard Properties:
borderBottom, borderLeft, borderRight, borderTop, children, clipboardable, copyable, deletable, focusable, focusState, height, left, look, numChildren, parent, proto, sizeHControl, sizeVControl, top, version, visible, width.
borderBottom, borderLeft, borderRight, borderTop: Tables can have no borders; the border sizes are always zero.
children: There is a bug: A Button which is the child of a Table component may appear very small.
bottomRow (described with topRow, below)
columnWidths[] integer (0-1024)
This array specifies the widths of the columns of the table. Changing a column's width causes the table to redraw.
defaultRowHeight integer (0-1024)
When new rows are added (when you increase numRows), the new rows added at the end of the table will have this height. This property is 14 by default.
firstVisibleRow integer (-1- numRows-1)
The row displaying at the top of the table. Changing this value cases the table to redraw. If there are no rows in the table, this property is -1. However, you cannot directly set this property to -1.
focusable integer (0-1)
When set zero, this component (and all of its children) will never get the system focus (and therefore, they will never get keyboard input, or be part of clipboard operations).
focusState integer (0-2)
This read-only property keeps track of whether the table is the system focus, the focus within its window, or not focused at all. This property will have one of the following values:
lastVisibleRow integer (-1- numRows-1)
The row displaying at the bottom of the table. Changing this value cases the table to redraw. If there are no rows in the table, this property is -1. However, you cannot directly set this property to -1.
leftColumn (described with topRow, below)
numColumns integer (0-39)
The number of columns in the table. Changing this number causes the table to redraw. If new columns are added (if you increase this number), the new columns will have zero width.
numRows integer (0-3999)
The number of rows in the table. If you change this value, the table will redraw. The new rows added will have a height of defaultRowHeight.
overallHeight long (0-4M)
Combined height of all rows in the table, including those rows the table is not currently showing. Do not confuse this with the height property, the on-screen size of the table. This property is read-only.
rightColumn (described with topRow, below)
rowHeights[numRows] integer(0-1024)
This array describes the height of each row. Changing one of these values causes the table to redraw.
topRow integer (0 - numRows-1)
leftColumn integer (-1 - numColumns-1)
rightColumn integer (leftColumn - numColumns-1)
bottomRow integer (topRow - numRows-1)
These four properties specify the current selection range. The cells in this range are drawn highlighted unless selectionType is zero. If leftColumn is -1, then there is no selection.
Setting one of these properties may change others to make the current selection conform to the selectionType. For example, if the selection type is select-row (2), then setting topRow will also change bottomRow and setting rightColumn will do nothing.
If, through assignment, rightColumn becomes less than leftColumn, their values will be switched. Similarly, if bottomRow becomes less than topRow, their values will be switched.
To change the values of these properties, use the SetSelection() action.
This event is generated when the table is about to draw itself. This is a good time to draw things that should appear "under" the table.
If your table has children that should be re-positioned before the table draws, this is an excellent time to do so.
_acceptPaste( self AS table, format AS string ) AS integer
Handle this event by returning 1 if the component can accept clipboard items of the given format; return zero otherwise.
self table
The component experiencing the event.
format string
The format of data to consider.
_char(self AS table, action AS integer, char AS integer, buttonState AS integer) AS integer
This event is generated whenever the user enters a character and the Table is the focus.
To ignore the character event and pass it to your parent, return zero. Return non-zero to signal that the handler has handled the event and it should not be passed on to the parent. If you're using a PC keyboard, know that the Alt, Ctrl, Shift, Num Lock, and Caps Lock keys will not generate this event--though they will affect the modifierState of future _char() events.
self gadget
The Gadget experiencing the event.
action integer (1, 2, 5)
If the event is result of the user interacting with a physical keyboard, this gives information about what's going on with the keyboard; many applications will want to ignore events whose action is not equal to one.
1 = Press. The user has pressed down on the keyboard in question.
2 = Repeat. The user has held down the key past the key repeat time.
5 = Release. The user has released the key.
char integer
Unicode value of the character entered. Some special keys/gestures will appear as special constant values:
KEY_BS (Backspace), KEY_DEL (Delete), KEY_ENTER, KEY_KP_RETURN (Numeric Keybad Enter), KEY_HOME, KEY_TAB, KEY_END, KEY_ESC, KEY_UP_ARROW, KEY_LEFT_ARROW, KEY_RIGHT_ARROW, KEY_DOWN_ARROW.
modfierState integer
This is the state of the various modifier keys and "sticky" keys; e.g., Shift, Caps Lock.
The Alt, Control and Shift keys do not generate keyboard events, instead they cause certain bits in the modifierState argument to be set.
LEFT_ALT - &H0080
RIGHT_ALT - &H0040
LEFT_CTRL - &H0020
RIGHT_CTRL - &H0010
LEFT_SHIFT - &H0008
RIGHT_SHIFT - &H0004
CAPS_LOCK - &H0400
NUM_LOCK - &H0200
SCROLL_LOCK - &H0100
If more than one modifier is active at a time, the values are added together.
self table
The component experiencing the event.
This event is generated after the table has drawn its cell contents and details determined by looks (e.g., cell borders), but before its children components draw. You may use it to draw custom artwork that draws "on top of" the table, but below its children.
You are not allowed to perform actions that require the table to redraw during this event (e.g., changing the number of rows, moving children components).
This action is not generated when the Update() action is invoked.
self table
The table experiencing the event.
_drawCell(self AS table, row AS integer, column AS integer, x AS integer, y AS integer)
This event is generated when the Table wants to draw the cell specified by row and column. No clipping rectangle is set, but your code may set one as desired.
Your handler for this event may not do anything that would require the table to redraw; e.g., you may not change the number of rows in the Table; you may not change the position/visibility of any of the Table's children; you may not invoke the table's Update() event.
self table
The component experiencing the event.
column integer (0 - numColumns-1)
The column and row of the cell to be redrawn.
y integer (0-...)
The drawing coordinates of the top left corner of the cell.
_focusChanged( self AS table, oldFocusState AS integer )
This event is generated whenever the table becomes the focus or stops being the focus--whenever its focusState property has changed.
self table
The component experiencing the event.
oldFocusState integer
The old value of the focusState property. For the new value, check the property itself.
This action eliminates the clipping rectangle previously defined by means of the SetClipRect() action, if any.
xStart integer
The x coordinate at which to start drawing.
xEnd integer
The x coordinate at which to finish drawing.
yCoord integer
The y coordinate at which to draw.
color long (0-255)
The color to draw. The following constants are available: RED, YELLOW, BLACK, WHITE, GRAY_50, LIGHT_BLUE, DARK_BLUE, LIGHT_CYAN, DARK_CYAN, LIGHT_GREEN, DARK_GREEN, LIGHT_ORANGE, DARK_ORANGE, LIGHT_PURPLE, DARK_PURPLE, LIGHT_GRAY, DARK_GRAY. For more information about colors, see
See Color
.
image complex
The image to draw. This is a graphic-style complex data value. You might retrieve data of this sort from the graphic property of a Picture component.
x integer
The x coordinate at which to draw the bitmap--this will be the x coordinate of the top-left corner of the image.
y integer
The y coordinate at which to draw the bitmap--this will be the y coordinate of the top-left corner of the image.
xStart integer
The x-coordinate of the line's starting point.
yStart integer
The y-coordinate of the line's starting point.
xEnd integer
The x-coordinate of the line's starting point.
yEnd integer
The y-coordinate of the line's starting point.
color long (0-255)
The color to draw. The following constants are available: RED, YELLOW, BLACK, WHITE, GRAY_50, LIGHT_BLUE, DARK_BLUE, LIGHT_CYAN, DARK_CYAN, LIGHT_GREEN, DARK_GREEN, LIGHT_ORANGE, DARK_ORANGE, LIGHT_PURPLE, DARK_PURPLE, LIGHT_GRAY, DARK_GRAY. For more information about colors, see
See Color
.
leftEdge integer
The x-coordinate of the rectangle's left edge
topEdge integer
The y-coordinate of the rectangle's top edge
rightEdge integer
The x-coordinate of the rectangle's right edge
bottomEdge integer
The y-coordinate of the rectangle's bottom edge
color long (0-255)
The color to draw. The following constants are available: RED, YELLOW, BLACK, WHITE, GRAY_50, LIGHT_BLUE, DARK_BLUE, LIGHT_CYAN, DARK_CYAN, LIGHT_GREEN, DARK_GREEN, LIGHT_ORANGE, DARK_ORANGE, LIGHT_PURPLE, DARK_PURPLE, LIGHT_GRAY, DARK_GRAY. For more information about colors, see
See Color
.
text string
The text to draw. The text is not parsed--if it contains special characters, those characters may not be displayed correctly.
x integer
The x coordinate at which to draw.
y integer
The y coordinate at which to draw.
color long
The color with which to draw. The following constants are available: RED, YELLOW, BLACK, WHITE, GRAY_50, LIGHT_BLUE, DARK_BLUE, LIGHT_CYAN, DARK_CYAN, LIGHT_GREEN, DARK_GREEN, LIGHT_ORANGE, DARK_ORANGE, LIGHT_PURPLE, DARK_PURPLE, LIGHT_GRAY, DARK_GRAY. For more information about colors, see
See Color
.
pointSize integer (12)
Pass 12.
textStyle integer
Pass zero to draw plain, pass one to draw bold.
uiShape[] integer (values 16384-32767 have special meaning)
The UIShape to draw.
The definition of the UIShape is somewhat complicated.
Set the first element to be the number of words in the mask description.
For a row of the bitmask, specify the row number, the pixels in that row in which to turn drawing on or off, and finish the row description with the special number -32768; you need only give this information for those rows that are different from the rows beneath them, and for those rows, you need only specify the pixels in that row that are different from the rows beneath them.
You must specify the rows in order from the lowest number to the highest. Within each row, you must specify the pixels in order, from the lowest number to the highest.
Consider the following example:
To create a UIShape of this shape, you would use the following code:
DIM myShape[15] AS integer
myShape[0] = -1 REM The first row we describe is the y=-1 row.
myShape[1] = -32768 REM End of this row's description; it's empty.
REM We don't need to describe the y=0 row;
REM it's the same as the row beneath it.
myShape[2] = 1 REM Now we will describe the y=1 row.
myShape[3] = 0 REM For this row, drawing starts at pixel 0...
myShape[4] = 16 REM ...and stops at pixel 16.
myShape[5] = -32768 REM We're done with this row's description.
REM We don't need to describe the y=2, y=3, y=4,
REM or y=5 rows; each is the same as the row
REM beneath it.
myShape[6] = 6 REM Now we will describe the y=6 row.
myShape[7] = 0 REM For this row, drawing starts at pixel 0...
myShape[8] = 18 REM ...and stops at pixel 18.
myShape[9]= -32768 REM We're done with this row's description.
REM We don't need to describe the y=7 row; it's the
REM same as the row beneath it.
myShape[10]=8 REM Now we will describe the y=8 row.
myShape[11]=2 REM For this row, drawing starts at pixel 2...
myShape[12]=18 REM ...and stops at pixel 18.
myShape[13]= -32768 REM We're done with this row's description.
myShape[14]= -32768 REM We're done describing the mask.
When drawing the region, this action will add xBase to all x coordinates and yBase to all y coordinates.
You may specify "parameterized" coordinates. The true values of these coordinates will be computed using the values of the param0 , param1 , param2 , and param3 arguments. To specify a parameterized coordinate, use an integer in one of the following ranges (expressed here in hexadecimal notation):
&H4000-&H5fff true coordinate = param0 + parameterized coordinate - &H5000
&H6000-&H7fff true coordinate = param1 + parameterized coordinate - &H7000
&H8000-&H9fff true coordinate = param2 + parameterized coordinate - &H9000
&Ha000-&Hbfff true coordinate = param3 + parameterized coordinate - &Hb000
arraySize integer
The number of elements in the uiShape[] array.
xBase integer
This number will be added to all x coordinates in the UIShape.
yBase integer
This number will be added to all y coordinates in the UIShape.
color long (0-255)
The color to draw. The following constants are available: RED, YELLOW, BLACK, WHITE, GRAY_50, LIGHT_BLUE, DARK_BLUE, LIGHT_CYAN, DARK_CYAN, LIGHT_GREEN, DARK_GREEN, LIGHT_ORANGE, DARK_ORANGE, LIGHT_PURPLE, DARK_PURPLE, LIGHT_GRAY, DARK_GRAY. For more information about colors, see
See Color
.
param0 integer
This number can be used to determine the value of certain "parameterized coordinates" in the UIShape.
param1 integer
This number can be used to determine the value of certain "parameterized coordinates" in the UIShape.
param2 integer
This number can be used to determine the value of certain "parameterized coordinates" in the UIShape.
param3 integer
This number can be used to determine the value of certain "parameterized coordinates" in the UIShape.
yStart integer
The y coordinate at which to start drawing.
yEnd integer
The y coordinate at which to finish drawing.
xCoord integer
The x coordinate at which to draw.
color long (0-255)
The color to draw. The following constants are available: RED, YELLOW, BLACK, WHITE, GRAY_50, LIGHT_BLUE, DARK_BLUE, LIGHT_CYAN, DARK_CYAN, LIGHT_GREEN, DARK_GREEN, LIGHT_ORANGE, DARK_ORANGE, LIGHT_PURPLE, DARK_PURPLE, LIGHT_GRAY, DARK_GRAY. For more information about colors, see
See Color
.
row integer (0 - numRows)
A row. To find out the coordinate of the bottom of the last row, pass numRows.
GetColumnAt( xPos AS integer ) AS integer
Returns the column at the passed x coordinate. If the Table has no columns or no rows, the action will return -1. If the passed xPos is less than zero, the action will return 0; if the passed xPos is beyond the rightmost column, the action will return numColumns-1
column integer (0 - column)
A column. To find out the coordinate of the right edge of the last column, pass numColumns.
row integer (0 - numRows)
A row. To find out the coordinate of the bottom of the last row, pass numRows.
xStart integer
The x-coordinate of the line's starting point.
yStart integer
The y-coordinate of the line's starting point.
leftEdge integer
The x-coordinate of the rectangle's left edge
topEdge integer
The y-coordinate of the rectangle's top edge
rightEdge integer
The x-coordinate of the rectangle's right edge
bottomEdge integer
The y-coordinate of the rectangle's bottom edge
InvertUIShape( uiShape[] AS integer, arraySize AS integer, xBase AS integer, yBase AS integer, param0 AS integer, param1 AS integer, param2 AS integer, param3 AS integer )
This action inverts a "UIShape" area--a region described by means of an array of integers. It inverts the colors of all pixels within the area; for example, all black pixels will become white and vice versa.
uiShape[] integer (values 16384-32767 have special meaning)
The UIShape to draw.
The definition of the UIShape is somewhat complicated.
Set the first element to be the number of words in the mask description.
For a row of the bitmask, specify the row number, the pixels in that row in which to turn drawing on or off, and finish the row description with the special number -32768; you need only give this information for those rows that are different from the rows beneath them, and for those rows, you need only specify the pixels in that row that are different from the rows beneath them.
You must specify the rows in order from the lowest number to the highest. Within each row, you must specify the pixels in order, from the lowest number to the highest.
Consider the following example:
To create a UIShape of this shape, you would use the following code:
DIM myShape[15] AS integer
myShape[0] = -1 REM The first row we describe is the y=-1 row.
myShape[1] = -32768 REM End of this row's description; it's empty.
REM We don't need to describe the y=0 row;
REM it's the same as the row beneath it.
myShape[2] = 1 REM Now we will describe the y=1 row.
myShape[3] = 0 REM For this row, drawing starts at pixel 0...
myShape[4] = 16 REM ...and stops at pixel 16.
myShape[5] = -32768 REM We're done with this row's description.
REM We don't need to describe the y=2, y=3, y=4,
REM or y=5 rows; each is the same as the row
REM beneath it.
myShape[6] = 6 REM Now we will describe the y=6 row.
myShape[7] = 0 REM For this row, drawing starts at pixel 0...
myShape[8] = 18 REM ...and stops at pixel 18.
myShape[9]= -32768 REM We're done with this row's description.
REM We don't need to describe the y=7 row; it's the
REM same as the row beneath it.
myShape[10]=8 REM Now we will describe the y=8 row.
myShape[11]=2 REM For this row, drawing starts at pixel 2...
myShape[12]=18 REM ...and stops at pixel 18.
myShape[13]= -32768 REM We're done with this row's description.
myShape[14]= -32768 REM We're done describing the mask.
When drawing the region, this action will add xBase to all x coordinates and yBase to all y coordinates.
You may specify "parameterized" coordinates. The true values of these coordinates will be computed using the values of the param0 , param1 , param2 , and param3 arguments. To specify a parameterized coordinate, use an integer in one of the following ranges (expressed here in hexadecimal notation):
&H4000-&H5fff true coordinate = param0 + parameterized coordinate - &H5000
&H6000-&H7fff true coordinate = param1 + parameterized coordinate - &H7000
&H8000-&H9fff true coordinate = param2 + parameterized coordinate - &H9000
&Ha000-&Hbfff true coordinate = param3 + parameterized coordinate - &Hb000
arraySize integer
The number of elements in the uiShape[] array.
xBase integer
This number will be added to all x coordinates in the UIShape.
yBase integer
This number will be added to all y coordinates in the UIShape.
param0 integer
This number can be used to determine the value of certain "parameterized coordinates" in the UIShape.
param1 integer
This number can be used to determine the value of certain "parameterized coordinates" in the UIShape.
param2 integer
This number can be used to determine the value of certain "parameterized coordinates" in the UIShape.
param3 integer
This number can be used to determine the value of certain "parameterized coordinates" in the UIShape.
leftEdge integer
The x-coordinate of the rectangle's left edge
topEdge integer
The y-coordinate of the rectangle's top edge
rightEdge integer
The x-coordinate of the rectangle's right edge
bottomEdge integer
The y-coordinate of the rectangle's bottom edge
x1 integer (-1 - numColumns-1)
x2 integer (-1 - numColumns-1)
y2 integer (0 - numRows-1)
The boundaries of the new selection range. To specify that no cells should be selected, pass -1 in the x1 and x2 arguments.
TextHeight( font AS string, size AS integer, style AS integer ) AS integer
This action returns the height, in pixels, it would take to draw the passed text using the passed font, size, and style. This can come in useful if you're not sure what font sizes your font supports--use this action to find out what size the table will really use when you request a given font size with a given font.