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.
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 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.
- 0: This component is not the focus, nor its window's focus.
- 1: This component is its window's focus, but is not the system focus.
- 2: This component is the system focus.
- 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.
- To do a quick-copy, you must have both NewDraw and NewBuild running. Using
the right mouse button, click-drag your graphic from the NewDraw window to
your component.
- height integer (valid values depend on the component's type)
- The vertical size of the component, in pixels.
- The horizontal size is specified by the width property.
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.
- Changing a component's look while that component is visible causes a run-time
error.
- 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.
- 0 As Specified: The program may set values for the width
property.
- 1 This value is not supported.
- 2 As Big As Possible: The group will expand to fill its
parents dimensions, leaving room for its sibling components. If the parent
is Size As Small As Possible, then this component will be of zero size.
- 3 As Needed: The group will be only as large as needed
to fit its caption and its children components; however, if any of those
children are As Big As Possible, then this component will act as if it were
As Big As Possible. Only components which may have children may use this
value.
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.
- 0 As Specified: The program may set values for the height
property.
- 1 This value is not supported.
- 2 As Big As Possible: The group will expand to fill its
parents dimensions, leaving room for its sibling components. If the parent
is As Small As Possible, then this component will be of zero size.
- 3 As Needed: The group will be only as large as needed
to fit its caption and children components; however, if any of those children
are As Big As Possible, then this component will act as if it were As Big
As Possible. Only components which may have children may use this value.
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.
- 0 Center
- 1 Full
- 2 Left
- 3 Right
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.
- 0 Center
- 1 Full
- 2 Top
- 3 Bottom
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.