File

The File component empowers the NewBASIC author with the means to view and manipulate files on a hard disk with a set of input/output actions.

File Properties

name as string
The name of the current file on disk to view or change. Setting this property should happen soon after the creation of a file component and will be the string passed to system libraries to attempt access to the file.
size as integer
The size of the current file on the disk. Setting this property performs a truncation operation on the current file with the given integer.
date as integer
The date of the file is read off the disk and converted to an integer. Setting this property calls FileSetDateTime( ) on the current file. This integer value is stored as a FileDate structure.
FileDate record
FD_YEAR:7, ; year since 1980
FD_MONTH:4 ; month (1 - 12)
FD_DAY:5, ; day of month (1 - 31)
FileDate end
time as long
The file timestamp is stored as a 32-bit double word according to the New Deal FileTime format.
FileTime record
FT_HOUR:5, ; hour (24-hour clock)
FT_MIN:6, ; minute
FT_2SEC:5, ; 2-second increments (0-29 corresponding to 0-58)
FileTime end
trap as integer
The trap property specifies what the file component should do when it encounters an error. The following table maps out trap behavior for the file component:
error as integer
This property returns the error code of the last file error that occured. Setting this property forces the given file error to occur and initiates a response as specified in the trap property.
const ERROR_UNSUPPORTED_FUNCTION 1
const ERROR_FILE_NOT_FOUND 2
const ERROR_PATH_NOT_FOUND 3
const ERROR_TOO_MANY_OPEN_FILES 4
const ERROR_ACCESS_DENIED 5
const ERROR_INSUFFICIENT_MEMORY 8
const ERROR_INVALID_VOLUME 15
const ERROR_IS_CURRENT_DIRECTORY 16
const ERROR_DIFFERENT_DEVICE 17
const ERROR_NO_MORE_FILES 18
const ERROR_WRITE_PROTECTED 19
const ERROR_UNKNOWN_VOLUME 20
const ERROR_DRIVE_NOT_READY 21
const ERROR_CRC_ERROR 23
const ERROR_SEEK_ERROR 25
const ERROR_UNKNOWN_MEDIA 26
const ERROR_SECTOR_NOT_FOUND 27
const ERROR_WRITE_FAULT 29
const ERROR_READ_FAULT 30
const ERROR_GENERAL_FAILURE 31
const ERROR_SHARING_VIOLATION 32
const ERROR_ALREADY_LOCKED 33
const ERROR_SHARING_OVERFLOW 36
const ERROR_NETWORK_CONNECTION_BROKEN 55
const ERROR_NETWORK_ACCESS_DENIED 65
const ERROR_NETWORK_NOT_LOGGED_IN 78
const ERROR_SHORT_READ_WRITE 128
const ERROR_INVALID_LONGNAME 129
const ERROR_FILE_EXISTS 130
const ERROR_DOS_EXEC_IN_PROGRESS 131
const ERROR_FILE_IN_USE 132
const ERROR_ARGS_TOO_LONG 133
const ERROR_DISK_UNAVAILABLE 134
const ERROR_DISK_STALE 135
const ERROR_FILE_FORMAT_MISMATCH 136
const ERROR_CANNOT_MAP_NAME 137
const ERROR_DIRECTORY_NOT_EMPTY 138
const ERROR_ATTR_NOT_SUPPORTED 139
const ERROR_ATTR_NOT_FOUND 140
const ERROR_ATTR_SIZE_MISMATCH 141
const ERROR_ATTR_CANNOT_BE_SET 142
const ERROR_CANNOT_MOVE_DIRECTORY 143
const ERROR_PATH_TOO_LONG 144
const ERROR_ARGS_INVALID 145
const ERROR_CANNOT_FIND_COMMAND_INTERPRETER 146
const ERROR_NO_TASK_DRIVER_LOADED 147
const ERROR_LINK_ENCOUNTERED 148
const ERROR_NOT_A_LINK 149
const ERROR_TOO_MANY_LINKS 150
buffer as component
This returns a memory caching fileBuffer component. This behavior is experimental, and simply provides the following ANSI-C-like interface at this time.
eof as integer
This property stores a boolean value indicating whether or not the end of file has been reached. This property works well as the conditional of loops such as while and until. Often directly checking this property can be avoided by employing the .ends( ) or .goes( ) actions.
data complex
This value stors the actual graphics string as a complex. This value can be passed to other components when setting their .graphic properties.

File Events

None.

File Actions

open( )

open( ) as integer

This action opens the current file for access. Upon encountering an error, open( ) returns a FileError.

close( )

close( ) as integer

This action closes the current file. Upon encountering an error, close( ) returns a FileError.

delete( )

delete( ) as integer

This action deletes the current file. Upon encountering an error, delete( ) returns a FileError.

create( )

create( ) as integer

This action creates a new file under with the current name. Upon encountering an error, create( ) returns a FileError.

commit( )

commit( ) as integer

This action commits changes made to the current file without closing it.

write( )

write(buffer as string, numchars as integer) as integer

Ths action writes numchars characters of string buffer to the current file.

read( )

read(N as integer) as integer

This action returns the string of length N starting at the current position in the current file.

peek( )

peek( ) as integer

This action returns the byte at the current position in the file as an integer. The current position is read with tell( ), set with go(N), and changed with seek(N).

Example: (read an entire file)

dim file as component
dim outputText as component
outputText = MakeComponent("text","top")
file = MakeComponent("file","top")
file.name = "test.txt"
file.open( )
while file.goes( )
outputText.AppendString(Chr(file.peek( )))
loop
file.close( )

poke( )

poke(character as integer) as integer

This action writes the passed character to the current position in the file.

go(N)

go(N as integer) as integer

This action moves the current file position to N (or from end -N.)

seek(N)

seek(N as integer) as integer

This action offsets the current file position by N.

tell( )

tell( ) as long

This action returns the current file position offset as a long.

ends( )

ends( ) as integer

This action returns true if the end of file (EOF) has been reached.

goes( )

goes( ) as integer

This action returns true if the end of file (EOF) has not been reached yet.

move( )

move(path as string) as integer

This action moves the physical presence of the current file to the given path string.

copy( )

copy(path as string) as integer

This action copies the entire file to the passed path.

mkdir(s)

mkdir(s as string) as integer

This action creates the directory given by string s.

rmdir( )

rmdir(s as string) as integer

This action removes the directory described by string s.

chdir( )

chdir(s as string) as integer

This action changes the current directory path to that specified in string s.

pushd( )

pushd( ) as integer

This action pushes the current directory onto the file stack.

popd( )

popd( ) as integer

This action pops the next directory from the file stack and makes it the current one.

dateline( )

dateline(N as integer) as integer

This action return a time stamp string of type N format where N is one of:

const DTF_LONG 1
const DTF_LONG_CONDENSED 2
const DTF_LONG_NO_WEEKDAY 3
const DTF_LONG_NO_WEEKDAY_CONDENSED 4
const DTF_SHORT 5
const DTF_ZERO_PADDED_SHORT 6
const DTF_MD_LONG 7
const DTF_MD_LONG_NO_WEEKDAY 8
const DTF_MD_SHORT 9
const DTF_MY_LONG 10
const DTF_MY_SHORT 11
const DTF_YEAR 12
const DTF_MONTH 13
const DTF_DAY 14
const DTF_WEEKDAY 15
const DTF_HMS 16
const DTF_HM 17
const DTF_H 18
const DTF_MS 19
const DTF_HMS_24HOUR 20
const DTF_HM_24HOUR 21


FileBuffer

The FileBuffer component provides an alternate caching interface to the File Component based on the ANSI-C standard. This component is provided for compatibility. FileBuffer operations use an internally stored "offset" position for file operations.

FileBuffer Properties

parent
The file component with which this fileBuffer interacts. Currently, setting this variable has no effect on the fileBuffer.

FileBuffer Events

None.

FileBuffer Actions

getc( ) as integer

This action returns the byte at the current (internally stored) position as an integer

putc(character as integer)

This action writes the given integer character as a byte at the current (internally stored) position.

gets(length as integer)

This action returns the string of characters stored from the current position to the passed length.

puts(buffer as string, length as integer)

This action writes length characters from the string passed in buffer to the parent file.

geti( ) as integer

This action returns a 16-bit word length integer at the current position.

puti(value as integer)

This action writes the passed 16-bit word length integer value to the parent file.


FileSelector

The FileSelector component provides a user interface component to grant the user access to select a file from the file system. This component is often used in conjunction with Open and Save menu events.

FileSelector Properties

size as integer
The number of files to display in the file selector. This property often affects the height of the displayed interface. This size does not affect the actual number of items within the file selector; it only affects how many are visible at one time.
selection as string
The name of the selected file without any path information. For example, "README.TXT' is a valid selection.
path as string
The path of the selected file relative to the current disk, including the filename in question. For example, if the current disk is stored as "C:" then a path may take the form of "\NEWDEAL\README.TXT"
disk as string
A full string description of the current disk that the selected file is stored on. For example, "C:" is a valid disk value.
filename as string
The full path description to the current selection including all disk information. This property effectively returns ".disk" appended with ".path". For example, in the above descriptions, the full filename would appear as "C:\NEWDEAL\README.TXT"

FileSelector Events

None.

FileSelector Actions

None.


Floater

The Floater acts as a "floating" window--like a dialog box, it clips graphics so that it obscures whatever it is drawn over.

This is a "primitive" component type; it doesn't do much on its own. It's been left plain so that you may customize its behavior.

Floater Properties

Standard Properties: borderBottom, borderLeft, borderRight, borderTop, children, class, height, left, numChildren, parent, proto, sizeHControl, sizeVControl, tile, tileLayout, tileSpacing, tileHAlign, tileHInset, tileVInset, tileVAlign, top, version, visible, width.

enabled:
If the Floater is disabled and holds the system focus, the window itself will become the system focus.
sizeHControl, sizeVControl:
Only SIZE_AS_NEEDED and SIZE_AS_SPECIFIED are supported. SIZE_AS_NEEDED is partially supported: when the component becomes visible and their height or width is zero, the component will size itself to a default value.
parent:
The only valid parent for a Floater is the null component, also known as "app."
visible: Setting a Floater visible not only makes it visible, but also brings it to the front, as if you had invoked the BringToFront( ) action.
focus component (must be a child or descendant of the Floater (or a null component))
This property holds the component that the window will set as the active system focus when the window becomes active. The property will hold the component with the system focus as long as the system focus remains within the window.
If the value of the focus property is the null component and the window is becoming visible or becoming active, then the window will set the system focus to the first child component that will accept it.
When the system focus is in the window, setting the focus property will also set the system focus.
Note that a popped-up Popup window, though a child of the window, will not show up in its focus property. This is because the popped-up Popup is a window itself, and keeps track of its own focus.
type integer (0-5)
If the floater's parent is "app," then this property determines the floater's modality and placement relative to other windows. This property cannot be changed while the floater is visible.
Floater Events
0 NON_MODAL:
Non-modal floaters are normal windows.
1 TOOL_BOX:
Toolbox floaters appear above Non-modal windows and also never get the focus (and so never become active). Children of this type of floater will never become the active selection (the user can not copy their data to the clipboard).
2 MODAL:
Modal windows will not allow keyboard input to be sent to components that are not either children of the dialog or of "On-top" windows. This means that components attempting to grab the mouse and attempts to set the focus will fail if the component is not either a child of the modal window or of an On-top window. Modal windows clear the mouse grab and pop down any Popup windows before becoming active.
3 SYS_MODAL:
System-modal floaters behave similarly to Modal floaters, but always appear above other System-modal windows.
4 ON_TOP:
"On-top" floaters behave like Toolbox windows but appear above everything but Popup windows, and have the special ability to receive input even when a modal window is active. Because they are like Toolbox windows, they will never get the focus. Children of this type of floater will never become the active selection (the user can not copy their data to the clipboard).
5 POPUP:
Popup floaters go away whenever the user clicks on anything inside or outside them. They go away as soon as the user lifts the mouse. They also go away whenever a Modal or System-modal window becomes visible. Children of this type of floater will never become the active selection (the user can not copy their data to the clipboard).

_aboutToClose( )

_aboutToClose( self AS floater )

This event is generated when the Floater is about to go away (when visible has changed from one to zero).

Pass:

self floater
The Floater experiencing the event.

_aboutToOpen( )

_aboutToOpen( self AS floater )

This event is generated when the Floater is about to appear (when visible has changed from zero to one).

Pass:

self floater
The Floater experiencing the event.

_activeChanged( )

_activeChanged( self As floater, gained AS integer )

This event is generated when a different window becomes an active window: this floater has just become (or just ceased to be) the active non-modal, modal, or system-modal window.

Passed:

self floater
The component experiencing the event.
gained integer
If this argument is non-zero, then this floater has just become the active window of its type (non-modal or modal/system-modal). Otherwise, the floater just ceased to be the active window.

Floater Actions

BringToFront( )

BringToFront( )

This action causes the floater to come to the front, appearing on top of other floaters and dialogs with the same or lesser priority. This may result in the floater becoming the active window.

Pass:

Nothing.

RedoGeometry( )

RedoGeometry( )

This action causes the floater to re-compute the positions of all its children, their children, etc.

Pass:

Nothing.


Form

The Form acts as a full-sized window holding UI gadgetry. On small devices, Forms will typically fill up the full screen.

Form Looks

The following looks are available:

0 Blank
A plain form.
1 Gray
A gray rectangle.
2 Bordered
Drawn with a border.

Form Properties

Standard Properties: borderBottom, borderLeft, borderRight, borderTop, caption, children, class, enabled, height, left, look, numChildren, parent, proto, sizeHControl, sizeVControl, tile, tileHAlign, tileHInset, tileLayout, tileSpacing, tileVAlign, tileVInset, top, version, visible, width.

enabled:
If the form is disabled and holds the system focus, the window itself will become the system focus.
height, width:
These properties are read-only, and are based on the size of the screen.
left, top:
These properties are read-only and zero.
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 the minimum allowable value, the component will size itself to a default value.
parent:
The only valid parent for a form is the null component, also known as "app."
visible:
Setting a Form visible not only makes it visible, but also brings it to the front, as if you had invoked the BringToFront( ) action.
focus component (must be a child or descendant of the Form (or a null component))
This property holds the component that the window will set as the active system focus when the window becomes active. The property will hold the component with the system focus as long as the system focus remains within the window.
If the value of the focus property is the null component and the window is becoming visible or becoming active, then the window will set the system focus to the first child component that will accept it.
When the system focus is in the window, setting the focus property will also set the system focus.
Note that a popped-up Popup window, though a child of the window, will not show up in its focus property. This is because the popped-up Popup is a window itself, and keeps track of its own focus.

Form Events

_aboutToClose( )

_aboutToClose( self AS form )

This event is generated when the Form is about to go away (when visible has changed from one to zero).

Pass:

self form
The Form experiencing the event.

_aboutToOpen( )

_aboutToOpen( self AS form )

This event is generated when the Form is about to appear (when visible has changed from zero to one).

Pass:

self form
The Form experiencing the event.

_activeChanged( )

_activeChanged( self AS form, gained AS integer )

This event is generated when the form becomes the active form or stops being the active form.

Passed:

self form
The component experiencing the event.
gained integer
If this argument is non-zero, then this form has just become the active form. Otherwise, it has just ceased to be the active form.

Form Actions

BringToFront( )

BringToFront( )

This action causes the Form, if it is visible, to come to the front of the screen.

Pass:

Nothing.