List

A List allows the user to select one or more items from a list. Each list item contains a text string, a bitmap graphic, or both.

List Looks

The following looks are available:

0 Arrow Down
A popout list, arrow down.
1 Arrow Right
A popout list, arrow right.

List Properties

Standard Properties: class, enabled, height, left, look, parent, proto, sizeHControl, sizeVControl, top, version, visible, width.

sizeHControl, sizeVControl:
Only SIZE_AS_NEEDED and SIZE_AS_SPECIFIED will be supported. SIZE_AS_NEEDED will only be partially supported: when the component becomes visible and their height or width is zero, the component will size itself to a default value.
behavior integer (0-2)
This property determines how many items may be selected at any one time.
0 At most one item.
1 Exactly one item.
2 Any number of items.
captions[ ] string
Array of strings to display. To change a list item's string, change the appropriate element of this array. To add a new list item to the end of the list, do something like the following:
list1.captions[list1.numItems] = "Last Minute Addition"

You may take advantage of this behavior to add several list items at a time:

list1.captions[list1.numItems + 9] = "Longstocking"

...would create 10 new list items, the first nine having blank captions, the last one having the caption "Longstocking."
To add a new list item in the middle of the list, use the Insert( ) action.

numItems integer (0-1024)
Number of items in the list. This property is read-only. To change the number of properties in the list, add items to the captions and/or graphics properties or use the Insert( ), Delete( ), or Clear( ) actions.
numSelections integer(0-numItems)
The number of items selected. This property is read-only.
numVisibleItems integer (1-15)
This property is ignored.
selectedItem integer(-1-(numItems-1))
The index a selected item, or -1 if there is no item selected. Changing the value of this property deselects all previously selected items and selects the item whose index is the new value of selectedItem; setting this property to -1 deselects all items in the list.
selections[numItems] integer (0-1)
This array keeps track of whether each item is selected. You may use this array to select and deselect items. If the list's behavior demands that exactly one item be selected, then setting an item unselected via the selections property (by settings its array element to zero) will have no effect.

List Events

_changed( )

_changed( self AS component, index AS integer )

This event is generated when the user clicks on a list item, causing that list item to be selected or unselected. Not all clicks result in a change of selection--only those clicks that do will generate this event.

Pass:

self component
The List experiencing the event.
index integer (0-numItems)
If the List's behavior property is zero or one, then this argument is the index of the item the user selected or unselected. If the List's behavior property is two, then this argument is the index of the first item currently selected in the list, or zero if there is no item selected.

List Actions

Clear( )

Clear( )

This action deletes all items from the List.

Pass:

Nothing.

Delete( )

Delete( index AS integer )

This action deletes an item from the List.

If this deletes the selected item in an exclusive list (i.e., a list with behavior of 1), then the first list item, if any, will get the selection.

(To blank out a list item's string without deleting the item, set the appropriate element of the captions array to ".")

Pass:

index integer
The index of the item to delete.

Insert( )

Insert( index AS integer, caption AS string )

This action inserts an item into the List. To add a new item to the end of the list, you can just use the captions property.

Pass:

index integer (0-numItems-1)
The position at which to insert the new item; the new item will be inserted before the item with this index.
caption string
The text, if any, which should appear in the new item.


Popup

A Popup is a special sort of group. It has a collapsed state in which it doesn't show its children, but only its caption and/or graphic. The user can make the group "pop up" so that it shows its children.


Picture

A Picture displays a picture.

Picture Properties

Standard Properties: classsizeHControl, sizeVControl: Only SIZE_AS_NEEDED and SIZE_AS_SPECIFIED are supported.

Picture Events

None.

Picture Actions

None.

Popup Looks

Only one look is supported.

Popup Properties

Standard Properties: caption, children, enabled, height, left, look, numChildren, sizeHControl, sizeVControl, tile, tileHAlign, tileHInset, tileLayout, tileSpacing, tileVAlign, tileVInset, top, version, visible, width.

sizeHControl, sizeVControl:
Only SIZE_AS_NEEDED and SIZE_AS_SPECIFIED will be supported. SIZE_AS_NEEDED will only be partially supported: when the component becomes visible and their height or width is zero, the component will size itself to a default value.
visible:
Applies to the Popup's button, not to any menu window that gets created when this button is pressed.

Popup Events

_aboutToClose( )

_aboutToClose( self AS popup )

This event is generated when the user has finished with the Popup, and the Popup is about to collapse.

Pass:

self popup
The Popup experiencing the event.

_aboutToOpen( )

_aboutToOpen( self AS popup )

This event is generated when the user has clicked on the Popup, and the Popup is about to open to reveal its children.

Pass:

self popup
The Popup experiencing the event.

Popup Actions

None.

PrintControl

The PrintControl provides a user interface component that creates a "Print..." button to initiate a default user print dialog.

PrintControl Properties

output as component
The component that is to be printed once the print dialog "Print" button is pressed.

Print Events

None.

Print Actions

print( )

This action prints the current output. Sending this action is equivalent to pressing the print button in the print dialog.

show( )

This action initiates the print dialog.

cancel( )

This action cancels the current print job.

complete( )

This action is sent by the output object (often during its _draw event) to specify that printing is complete.


Scrollbar

Scrollbars are typically used to allow the user to scroll a window onto a document or control the data displayed by a table component.

No Scrollbar may be the child of a Clipper, nor the child of a child of a Clipper, etc.

Two Common Examples

There are two main ways that programs use Scrollbars:

  1. Work with the built-in scrolling behavior of a Text or Table component; or
  2. Re-position the child of a clipper component.

A Scrollbar working with a Text or Table component, will use the concept of rows of cells or lines of text; the Scrollbar's value should reflect a row or line number. If the number of rows/lines changes, you'll probably want an event handler that looks something like the following handler for a text component's _numLinesChanged( ) event:

SUB text1_numLinesChanged( self AS text )
scrollbar1.maximum = self.numLines
scrollbar1.thumbSize = self.lastVisibleLine - self.firstVisibleLine + 1
END SUB
SUB scrollbar1_changed( self AS scrollbar, scrollType AS integer )
text1.firstVisibleLine = self.value
END SUB

A Scrollbar which vertically re-positions the child of a clipper would probably be set up something like this:

sub module_init( )
scrollbar1.maximum = childOfClipper.height
scrollbar1.thumbSize = clipper1.height
end sub
SUB scrollbar1_changed( self AS scrollbar, scrollType AS integer )
childOfClipper.top = -self.value
END SUB

Scrollbar Looks

The following looks are available:

0 Normal Scrollbar.
Note that within NewBuild, the scrollbar's on-screen thumb size depends upon the thumbSize property.
1 Spin Buttons.

Scrollbar Properties

Standard Properties: enabled, height, left, sizeHControl, sizeVControl, parent, proto, top, version, visible, width.

height, width:
When height and/or width is too small to draw the scrollbar, its look is undefined. The height of horizontal scrollbars, and the width of vertical scrollbars are fixed and cannot be changed regardless of the sizeHControl and sizeVControl properties.
sizeHControl, sizeVControl:
Only SIZE_AS_NEEDED and SIZE_AS_SPECIFIED will be supported. SIZE_AS_NEEDED will only be partially supported: when the component becomes visible and their height or width is zero, the component will size itself to a default value.
increment integer (1-)
Amount by which thumb (the part of the scrollbar which slides up and down) will move when the user taps the scroll-up or scroll-down button on the Scrollbar.
minimum integer
The smallest amount that the value property can attain, i.e. when the thumb (the part of the scrollbar which slides up and down) is all the way to the left or the top of the Scrollbar, then value = minimum.
maximum integer
The largest amount that the value property can attain, i.e. when the thumb (the part of the scrollbar which slides up and down) is all the way to the right or the bottom of the Scrollbar, then value is the greater of (maximum-thumbSize) and minimum.
notifyDrag integer (0-1)
By default, the changed event is generated when the thumb (the part of the scrollbar which slides up and down) is dropped by the user. Setting notifyDrag non-zero causes this event to be sent continuously as the thumb is being dragged (though it will not be sent when the thumb is dropped). This property may be changed at run-time only if the Scrollbar's visible property is zero.
orientation integer (0-1)
The Scrollbar's direction: 0 means horizontal, 1 means vertical. Changes to this property will not take effect if the scollbar is visible.
thumbSize integer (0-)
Amount of total range currently being shown (relative to the entire size of the document). Set to zero if this metric is not appropriate for the situation. thumbSize determines how much the value property changes when the user clicks inside the scroller area.
value integer (minimum-(maximum-thumbSize) )
Describes the position of the top of the thumb. Lowest value occurs when the thumb is in the topmost (vertical) or leftmost (horizontal) position.

Scrollbar Events

_changed( )

_changed( self AS component, scrollType AS integer )

This event is generated when the user interacts with the Scrollbar, either tapping a button, tapping the Scrollbar itself, or dragging the thumb (the part of the scrollbar which slides up and down). (If the notifyDrag property is 0, this event is generated when the user releases the thumb. If notifyDrag is 1, the event is generated with each movement of the thumb, but is not generated when the thumb is released.)

This event is only generated as the direct result of the user interacting with the Scrollbar--it won't be generated each time your BASIC code changes the Scrollbar's value property.

When this event is generated, the Scrollbar's value property will already reflect changes made by the user.

Pass:

self component
The Scrollbar experiencing the event.
scrollType integer (1-5)
Number specifying what the user did to the Scrollbar.
1 Dragged or dropped the thumb (the part of the scrollbar which slides up and down).
2 Tapped the back button (the up/left button)
3 Tapped the forward button (the down/right button)
4 Tapped the page back area (the up page/left page area)
5 Tapped the page forward area (the down page/right page area)

Scrollbar Actions

None.


Sound

The sound component allows your program to emit beeps and whistles. There is a sound component in the system module. To access it, do something like that shown in the following example:

system:sound!StandardSound( SS_ERROR )

Sound Properties

Standard Properties: class, parent, proto, version.

Sound Events

None

Sound Actions

StandardSound( )

StandardSound( standardSound AS integer )

This action plays a "standard sound," one of the standard error or warning beeps.

Pass:

standardSound integer
Which of the standard sounds to play.
0 SS_ERROR: Error dialog box sound
1 SS_WARNING: Warning beep
2 SS_NOTIFY: Notify beep
3 SS_NO_INPUT: Beep indicating user's input is being ignored
4 SS_KEY_CLICK: "Click" associated with keyboard is press or tap on floating keyboard.
5 SS_ALARM: Standard alarm sound.

Any other value will sound like SS_ERROR.


Spacer

The spacer does nothing more than occupy screen space, separating other components.

Spacer Looks

The following looks are supported:
0 Blank
1 1-pixel solid line
2 1-pixel dotted line

Spacer Properties

Standard Properties: class, height, left, look, parent, proto, sizeHControl, sizeVControl, top, version, visible, width.

Spacer Events

None.

Spacer Actions

None.


Sprite

The Sprite component gives the NewBASIC programmer the power to create vivid animations and video game quality motion. A sprite stores separate graphic images in a frame array of draw components.

Sprite Properties

x as integer
The x position of this sprite.
y as integer
The y position of this sprite.
xVel as integer
The x portion of the velocity vector of this sprite. Sprites given a non-zero velocity move along the indicated axis.
yVel as integer
The y portion of the velocity vector of this sprite. Sprites given a non-zero velocity move along the indicated axis.
rotation as integer
The current rotation of this sprite.
color as integer
The current color of this sprite.
imageCount as integer
The number of images in the frame array to be animated.

Sprite Events

None.

Sprite Actions

setframe( )

setframe(frameNum as integer, graphic as long) as integer

This action sets the given frame in the frame array to the given graphic.

getframe( )

getframe(frameNum as integer) as long

This action returns the frame at the given offset.

dim draw1 as component
draw1 = MakeComponent("draw","top")
draw1.start( )
draw1.moveto(0,3)
draw1.lineto(2,-2)
draw1.lineto(0,0)
draw1.lineto(-2,-2)
draw1.lineto(0,3)
draw1.stop( )
dim spriteWin as component
spriteWin = MakeComponent("spriteContent","top")
spriteWin.visible = 1
dim sprite1 as component
sprite1 = MakeComponent("sprite",spriteWin)
sprite1.imageCount = 1
sprite1.x = 10
sprite1.y = 10
sprite1.rotation = 2
sprite1.setframe(0,draw1)
spriteWin.start( )


SpriteContent

The SpriteContent component acts as the parent to which sprite components are added. The component also controls game flow.

SpriteContent Properties

None.

SpriteContent Events

None.

SpriteContent Actions

start( )

start( ) as integer

This action starts animation within a spriteContent.

pause( )

pause( ) as integer

This action pauses animation within a spriteContent.