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.
The following Table looks are available:
Standard Properties: borderBottom, borderLeft, borderRight, borderTop, children, clipboardable, copyable, deletable, focusable, focusState, height, left, look, numChildren, parent, proto, sizeHControl, sizeVControl, top, version, visible, width.
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.
_aboutToDraw( self AS table)
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.
_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.
If more than one modifier is active at a time, the values are added together.
_copy( self AS table )
This event is generated when the component should copy its current selection to the clipboard.
_delete( self AS table )
This event is generated when the component should delete its current selection.
_draw( self AS table )
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.
_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.
_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.
_paste( self AS table )
This event is generated whenever the component should replace its current selection with the contents of the clipboard.
_overallHeightChanged( self AS table )
This event is generated whenever the table's overall height changes; perhaps some BASIC code changed the number of rows or the height of some row.
_scrolled( self AS table )
This event is generated whenever the table scrolls, whether as the result of user action, or BASIC code setting a property such as firstVisibleRow, or BASIC code invoking a table action which in turn causes scrolling.
_selectionChanged( self AS table )
The table's selection has changed.
This event is not generated if the selectionType is five (custom selection).
ClearClipRect( )
This action eliminates the clipping rectangle previously defined by means of the SetClipRect( ) action, if any.
DrawHLine( xStart AS integer, xEnd AS integer, yCoord AS integer,
color AS long)
This action draws a horizontal line one pixel wide.
DrawImage(image AS complex, x AS integer, y AS integer )
This action draws an image.
DrawLine( xStart AS integer, yStart AS integer, xEnd AS integer, yEnd
AS integer, color AS long )
This action draws a line. Note that there are optimized actions for drawing horizontal and vertical lines (DrawHLine( ), DrawVLine( )).
DrawRect( leftEdge AS integer, topEdge AS integer, rightEdge As integer,
bottomEdge AS integer, color AS long )
This action draws a filled rectangle.
DrawText( text AS string, x AS integer, y AS integer, color AS long,
font AS string, pointSize AS integer, textStyle AS integer ) AS
integer
This action draws a string of text. It returns the width of the drawn string, measured in pixels.
DrawUIShape( uiShape[] AS integer, arraySize AS integer, xBase AS
integer, yBase AS integer, color AS long, param0 AS integer, param1 AS integer,
param2 AS integer, param3 AS integer )
This action draws a "UIShape"--a region described by means of an array of integers.
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):
DrawVLine( yStart AS integer, yEnd AS integer, xCoord AS integer,
color AS long )
This action draws a vertical line one pixel wide.
GetAbsYPosAt( row AS integer ) AS long
Returns the y coordinate between 0 and overallHeight of the top of the row.
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
GetRowAt( yPos AS integer ) AS integer
Returns the row being displayed at the passed y coordinate. If the table has no rows or no columns, this action returns 0. If yPos is not showing or does not belong to any row, this action returns firstVisibleRow or lastVisibleRow as appropriate.
GetXPosAt( column AS integer ) AS integer
Returns the x drawing coordinate of the left of the specified column, or -1 if the table is not displaying the column.
GetYPosAt( row AS integer ) AS integer
Returns the y drawing coordinate of the top of the specified row, or -1 if the table is not displaying that row.
DrawLine( xStart AS integer, yStart AS integer, xEnd AS integer, yEnd
AS integer )
This action inverts a line.
InvertRect( leftEdge AS integer, topEdge AS integer, rightEdge As
integer, bottomEdge AS integer )
This action inverts a rectangle--it reverses the color of all pixels within that rectangle. For example, those pixels which were white will now be black, and vice versa.
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.
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):
Redraw( )
This action causes the table to redraw itself and its children.
Scroll(yPosition AS long )
Scrolls the table such that the row containing the specified yPosition will be at the at the top of the table, if possible. If the table scrolls, it will generate _scrolled( ) and _draw( ) events.
SetClipRect( leftEdge AS integer, topEdge AS integer, rightEdge AS
integer, bottomEdge AS integer )
This action defines a clipping rectangle. Further drawings will be "clipped" to the bounds of this rectangle.
SetSelection( x1 AS integer, y1 AS integer, x2 AS integer, y2 AS
integer)
This action causes the Table to select a range of cells, unselecting the previously selected range. Specifying a range which does not conform to the selectionType property results in an error.
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.
TextWidth( testText AS string, font AS string, size AS integer, style
AS integer ) AS integer
This action computes the width, in pixels, necessary to draw the specified string with the given font and style.
Update( leftColumn AS integer, topRow AS integer, rightColumn AS integer,
bottomRow AS integer)
Forces a re-draw of a specific range of cells in the table.
These four numbers specify the range of cells that needs to be updated.