A gadget can intercept user input and can draw.
Gadget is a "primitive" component type. By default, it doesn't do much. However, with the actions and events it provides, it is very customizable.
Standard Properties
children, class, clipboardable, copyable, deletable, enabled, focusable, focusState, height, left, numChildren, parent, proto, tile, tileHAlign, tileHInset, tileLayout, tileSpacing, tileVAlign, tileVInset, top, version, visible, width.
focusable, focusState: (Tom, need definition here.)
visible: Any block of code that sets a Gadget visible should call the Update() routine before using any of the Gadget's drawing actions.
_acceptPaste( self AS gadget, 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 gadget
The component experiencing the event.
format string
The format of data to consider.
_char(self AS gadget, action AS integer, char AS integer, buttonState AS integer) AS integer
This event is generated whenever the user enters a character and the Gadget 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 Keypad 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 gadget
The component experiencing the event.
This event is generated whenever the gadget needs to draw itself; e.g., when the gadget first becomes visible or when the gadget is revealed after having been obscured by a window.
You cannot assume that the gadget's drawing area has been erased at the point this event is generated--to clear the area, you may use the DrawRect() action.
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
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
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
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
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
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
.
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.
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. This clipping rectangle will be used only until the end of the current _draw() event; it will then be discarded.
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
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 gadget will really use when you request a given font size with a given font.