Component Types

Components are the building blocks with which you build your applications. This chapter contains reference material for the component types available, with information about their actions, events, and properties.


Base Component Set

The following component types are part of the base component set.

Toolbox components

Button ( See Button )
This component acts as a button. The program can handle the event of the user pressing the button.
Choice ( See Choice )
Choices present the user with an exclusive choice: choices must be the children of groups, and only one choice within any group may be selected at any one time. Lists can also provide exclusive choices.
Entry ( See Entry )
The Entry allows the user to enter a single line of text. Programs using an Entry can handle the event when the user is done entering text, or can even handle each letter entered.
Group ( See Group )
The group intelligently manages its children components.
Label ( See Label )
This component displays a single line of text.
List ( See List )
This component presents a list to the user. The items in the list may be strings of text or graphics. The program can handle the event when the user selects an item of the list.
Scrollbar ( See Scrollbar )
A Scrollbar provides a common interface for scrolling through documents, fields, etc. Programs using Scrollbars can intercept events when the user tries to scroll forward or back.
Toggle ( See Toggle )
Toggles act as check-boxes or on-off switches. Programs using toggles can handle the event when the toggle is turned on or off. Lists can also provide on-off choices. When presenting a large number of related on-off choices, you'll probably want to use a list.

Other base components

Alarm ( See Alarm )
This component manages an alarm. It can set this alarm to go off at some time, at which point the component will be alerted. Even if the component's module is dormant, it will still be alerted.
Clipboard ( See Clipboard )
This component monitors the system clipboard, the mechanism that allows cut, copy, paste, and quick transfer.
Clipper ( See Clipper )
Clippers are "primitive" windows. They don't do much other than clip their children to their bounds.
Database ( See Database )
A Database component allows you to organize several pieces of information in a database.
Dialog ( See Dialog )
Dialogs are Windows which alert the user to problems or present the user with a number of choices.
Draw ( See Draw )
Draws provide raw graphic drawing abilities within your NewBASIC modules.
File ( See File )
Files provide input/output operations on external files.
FileBuffer ( See FileBuffer )
FileBuffers provide standard storage for the contents of file operations.
FileSelector ( See FileSelector )
FileSelectors are Windows which provide access to select and open files on hard disks.
Floater ( See Floater )
Floaters are "primitive" dialog boxes. They don't have much built-in functionality, but are very customizable.
Form ( See Form )
Forms are the primary windows of programs. The top-level component of any application will be a form.
Gadget ( See Gadget )
Gadgets are "primitive" components. They can detect text input, and have great control over their appearance. They don't have much built-in functionality, but are very customizable.
Picture ( See Picture )
This component displays a bitmap picture.
Popup ( See Popup )
The Popup functions as a pop-up list. Normally, it takes up little screen area. When selected, it expands, revealing its children to the user.
PrintControl ( See PrintControl )
PrintControls provide printing capabilties to your NewBASIC module.
Spacer ( See Spacer )
The Spacer doesn't do anything; it just takes up space. It comes in handy when you need to pad out a program's UI.
Sprite ( See Sprite )
Sprites provide animation capabilities within your NewBASIC modules.
SpriteContent ( See SpriteContent )
SpriteContents provide convenient places to store sprites within an animation sequence.
Table ( See Table )
A Table component displays data in a table form. It supplies actions supporting row-based scrolling.
Text ( See TimeDate )
The Text component provides a multi-line text editing field.
TimeDate ( See TimeDate )
A component of this type keeps track of the current day and time of day.
Timer ( See Timer )
This component generates keeps track of time elapsed, and generates an event when a certain amount of time has passed.


Some Common Properties

Some properties are common to many component types. They are documented here in alphabetical order. It's worth your while to learn about all of these properties; you will encounter them often.

borderBottom integer (0-)
The distance between the bottom of the area in which the component keeps its children and the bottom of its drawing area. This property is read-only; its value depends on the component type and look.
borderLeft integer (0-)
The distance between the left edge of the area in which the component keeps its children and the left edge of its drawing area. This property is read-only; its value depends on the component type and look.
borderRight integer (0-)
The distance between the right edge of the area in which the component keeps its children and the right edge of its drawing area. This property is read-only; its value depends on the component type and look.
borderTop integer (0-)
The distance between the top of the area in which the component keeps its children and the top of its drawing area. This property is read-only; its value depends on the component type and look.
caption string
The text caption for the component. For example, an OK button's caption is "OK." You may change this property using NewBuild; change the Caption Text field in the General area of the Component Properties box and press the Apply button.
children[] component
This is a read-only array of components, this component's children. The numChildren property is the number of children. You may make one component the child of another in the Builder by placing the child component within the parent component.
At run time, you may make one component the child of another by setting the child's parent property to the parent component. To make sure that the prospective parent will accept the child, call the ValidParent( ) function.
For more information about parent and children components, see Component Tree: Parents & Children.
class string
This read-only string is the component's type (e.g., "form," "button," "label"). The class of a component is set when the component is created.
clipboardable integer (0-1)
When set to zero, the component refuses to perform any clipboard (cut/copy/paste) operations. When set to 1, the component will attempt to perform these operations.
copyable integer (0-1)
Set this property to one if your component's selected data may be copied to the clipboard; set it to zero otherwise.
deletable integer (0-1)
Set this property to one if your component's selected data may be deleted.
enabled integer (0-1)
Normally, this flag will be 1; if it is zero, then the user will not be able to interact with the component, and the component will appear grayed-out.
You may set this property using NewBuild by turning on or off the Enabled option in the General area of the Component Properties box and pressing the Apply button.
focusable integer (0-1)
When this property is set to zero, this component (and its children) will never become the focus--they will never get keyboard input or be part of clipboard operations.
focusState integer (0-2)
This read-only property reflects the component's focus state.
graphic complex
Graphic part of a component caption. To set this property using NewBuild, use the NewDraw application to draw the graphic. Select the graphic and quick-copy it to the component.
height integer (valid values depend on the component's type)
The vertical size of the component, in pixels.

You may read these properties at any time. You may change a component's height if its sizeVControl property is zero. You may or may not be able to change a component's height using NewBuild. If its sizeVControl property is zero, you may change the component's height by positioning the mouse pointer at the top or bottom edge of the component. The mouse pointer should change to an arrow symbol. If you now do a click-drag, you will change the vertical size of the component.

left integer
The horizontal position of the component, relative to its parent. (The vertical position is determined by the top property.) This position is measured in pixels. Note that if the component's parent is tiles its children (has a tile property of one), then you may not set the left and top properties, only read them. You can use NewBuild to set the left property of a component if that component's parent does not tile its children. Do a click-drag starting within the component; it will be dragged to a new position.
look integer (0-15)
The meaning of this field depends upon the component type. Some component types may differ in appearance: a toggle might appear as a check-box, or as a menu item with a toggle-box. To learn the meanings of the looks associated with a component type, see the documentation for that component type.
numChildren integer (0-)
This read-only property is the component's number of children.
parent component
The component's parent component. To change a component's parent property in NewBuild, click-drag to place it within the bounds of the parent component. Some components may have a null parent. For example, Dialogs and Forms typically have null parents. At run-time, you can find out if a component's parent is null via BASIC code like "IsNullComponent(aComponent.parent)." If you're creating a component with BASIC code and want it to have no parent, use the special "app" argument to MakeComponent( ). For example:
DIM form2 AS form
form2 = MakeComponent("form", "app")

For more information about parent and children components, see Component Tree: Parents & Children.

proto string (up to 80 characters; alphanumeric characters and underlines only)
This string determines the component name for purposes of constructing the name of event handlers. For example, if you set button1's proto property to "FunButton," then it would generate FunButton_pressed( ) events instead of button1_pressed( ) events.
Components created with NewBuild will automatically have their proto set to their name; you may change this value by means of the General area of the Component Properties box.
Components you create via MakeComponent( ) won't have their proto property set by default; you must set it explicitly.
Because the proto property will form the first part of one or more routine names, make sure that it would be a legal beginning for a routine name. Its first character should be a letter; other characters should be letters, numbers, or underscore characters ("_").
sizeHControl integer (0-3)
Using this property, you can base a component's width on that of its child or parent components.

You can change the value of this property in NewBuild by choosing one of the Width choices in the General area of the Component Properties box and pressing the Apply button.

sizeVControl integer (0-3)
Using this property, you can base a component's width on that of its child or parent components.

You can change the value of this property in the Builder by choosing one of the Height choices in the General area of the Component Properties box and pressing the Apply button.

tile integer (0-1)
Set this property to one to make the component tile its children (i.e., arrange them nicely); set it to zero to tell the component to leave its children alone.
You can set this property in NewBuild by changing the Tile Children option in the Children area of the Component Properties box and pressing the Apply button.
tileHAlign integer (0-3)
Horizontal alignment to use when placing tiled child components. If the component's tile property is zero, then this property will be ignored.

You can set this property in NewBuild by choosing one of the Align Horizontal choices in the Children area of the Component Properties box and pressing the Apply button.

tileHInset integer (0-63)
Distance, in pixels, by which the tiled child components should be horizontally inset from the sides of this component. You might think of this as the right and left margins. If the component's tile property is zero, then this property will be ignored.
You can set this property in NewBuild by choosing one of the Align Vertical choices in the Children area of the Component Properties box and pressing the Apply button.
tileLayout integer (0-1)
Direction to orient tiled children: zero for vertical, one for horizontal. If the component's tile property is zero, then this property will be ignored.
You can set this property in NewBuild by choosing one of the Layout choices in the Children area of the Component Properties box and pressing the Apply button.
tileSpacing integer (0-63)
Desired spacing, in pixels, between tiled child components. If the component's tile property is zero, then this property will be ignored.
You can set this property in NewBuild by setting the Tile Spacing number in the Children area of the Component Properties box and pressing the Apply button.
tileVAlign integer (0-3)
Vertical alignment to use when placing tiled child components. If the component's tile property is zero, then this property will be ignored.

You can set this property in NewBuild by choosing one of the Align Vertical choices in the Children area of the Component Properties box and pressing the Apply button.

tileVInset integer (0-63).
Distance, in pixels, by which the tiled child components should be vertically inset from the sides of this component. You might think of this as the top and bottom margins. If the component's tile property is zero, then this property will be ignored.
You can set this property in NewBuild by setting the Vertical Inset number in the Children area of the Component Properties box and pressing the Apply button.
top integer
The vertical position of the component, relative to its parent. (The horizontal position is specified by the left property.) This position is measured in pixels. If the component's parent is tiled, then you may not set the left and top properties, only read them.
You can use NewBuild to set the top property of a component if that component's parent is not tiled. Do a click-drag starting within the component to drag the component to a new position.
version integer (0-)
In the future, we may come up with new additional API for these component types. The read-only version property reflects the API version of the component. If you think your program might take advantage of features not available on all versions, check the version property before using that feature.
visible integer (0-1)
Normally, this flag will be 1; if it is zero, then the component will be invisible. Also, all of its children will be invisible.
You can set this property in NewBuild by changing the Visible option in the General area of the Component Properties box and pressing the Apply button.
width integer (valid values depend on component type)
The horizontal size of the component, in pixels. (The vertical size is specified by the height property.) You may read these properties at any time. You may change a component's width if its sizeHControl property is zero. You may write a component's height if its sizeVControl property is zero.
You can change the width of a component whose sizeVControl property is zero in NewBuild. Position the mouse pointer over the left or right edge of the component. The mouse pointer's shape should change to an arrow. Click-drag to change the width of the component.