Field events
Change
Calls an event when the value of a field changes.
Example
Sub Change()
...
End Sub
Click
Calls an event when the user clicks an unprotected field.
Example
Sub Click()
...
End Sub
DoubleClick
Calls an event when the user double-clicks an unprotected field.
GotFocus
Makes a field active (receives focus), which triggers an event.
A field can receive focus by being clicked, being selected with the Tab key, or programmatically with the SetFocus method.
LostFocus
Makes a field inactive (loses focus), which triggers an event.
A field loses focus when another field gains the focus.
Field methods
AddItem
Adds an item to an existing list field.
Syntax
[formname].fieldname.AddItem(string)
You can use AddItem to simplify the use of dropdown lists by automating the addition of new items to the list. AddItem finds the item specified in the string parameter and adds to the list. AddItem can only be used on editable and static selection lists and affects the List attribute.
DblClick
Calls an event when the user double-clicks a field.
You can associate code with the DblClick method whenever you wish it to be executed by double-clicking.
Example
Sub DblClick()
...
End Sub
RemoveItem
Removes an item from an existing list field.
Syntax
[formname].fieldname.RemoveItem(string)
You can use RemoveItem to simplify the use of dropdown lists by automating the deletion of items from the list. RemoveItem finds the item specified in the string parameter and removes it from the list, leaving all other entries the same. RemoveItem can only be used on editable and static selection lists and affects the List attribute.
Example
RemoveItem (an item in the list)
SelLength
Sets the length of the selected text in a text field.
Syntax
[formname].fieldname.SelLength(numeric expression)
If a starting point for the selection of text is not set with SelStart, the selected text begins at the first character. If the numeric expression is larger than the number of characters in the text buffer, SelLength selects all of the text in the field. If numeric expression is set to 0, the cursor is placed at the location specified by SelStart (or character 0 if SelStart is not called first) and no text is selected.
Example
Sub Click()
...
StringField1002.SelLength(25) 'select the 1st 25 chars in StringField 1002
StringField1002.SelLength(0) '0 = no selection; place cursor at SelStart
StringField1002.SelLength(5) 'select characters 7 - 12
...
End Sub
SelStart
Sets the starting position in the code for a text selection.
Syntax
[formname].fieldname.SelStart(position)
where position is a numbered string expression.
Use SelStart to specify the character at which to begin a SelLength text selection. Use SelStart(0) to set the selection at the beginning of the text field.
Example
Sub Click()
...
StringField1002.SelStart(5) 'set the starting position for text selection
StringField1002.SelStart(7) 'set the starting position for text selection
...
End Sub
SetFocus
Sets the application focus of a field.
If the form the field is on is shown, but not active, the form is activated and the focus is set. If the field receiving focus is hidden or protected, this method has no effect.
Syntax
[formname].fieldname.SetFocus
Example
Sub Click()
StringField1002.SetFocus 'set focus to StringField 1002
End Sub
Field types
Buttons
Checkbox
Has a default Value attribute equal to 0 (off), 1 (on) or 2 (grayed).
Configure your checkbox in FirstClass Designer if you want more than two positions to be displayed.
Command
You can either set a command in FirstClass Designer to use the button in FirstClass RAD, or assign functionality to the Click method of the button.
The Text attribute allows you to control, programmatically, the text displayed on the button.
Radio
Use with actions such as click, to provide additional programmatic direction when the button is pressed by the user. Radio buttons do not have a Value attribute.
To find which radio button is selected, use the Value attribute of the radio group field which contains the radio button field.
Remember to set each radio button field in any radio group to a different value in FirstClass Designer.
Radio group
Contains the RadioButton value which is currently selected from the available buttons in the group. The radio group field has a Value attribute that is the default.
The button values must be set in FirstClass Designer and must be unique in order to function properly.
URL
Preset in FirstClass Designer to open a single URL. An URL button cannot be modified programmatically in FirstClass RAD.
As a workaround, use a command button and the LaunchURL command in the Click method of the button to achieve the same thing.
Date
Has a Value attribute that contains the date entered or displayed in the field as a Date data type. This pertains to any field that contains a date.
Editable text
Has a Text attribute that contains the text entered into the field.
Editable selection list
Has a List attribute that contains the items displayed in the list exactly as they are assigned in FirstClass Designer.
Items are semicolon delineated. An editable selection list has a Text attribute which contains the string of the selected item from the list. To get a numeric response instead of a string, use a static selection list. You can set editable selection lists to noneditable mode with the Editable attribute in FirstClass Designer or programmatically if you don't want the user to be able to enter values that are not in the list.
Expanding list
Has the same attributes as its subfield type as set in FirstClass Designer. If the subfield type is Text, you can use the Text attribute of any subfield.
Expanding list attributes are accessed as an array. For example, lstExpanding(0)="Hello" would set the first attribute of the expanding list to a literal string. You can use the Reset method to clear all field content for the field, and the Index attribute to identify which element in the list has the focus.
File viewer
Contains arbitrary data including binary data.
The file viewer field method displays the data if there is an available viewer, but can also be used to store undisplayable binary data as well. You can use file viewer fields to display picture data from a database, for example, or provide a method for users to upload data to the program. You can use special attributes, such as FileName, FileSize, FileType, FileCreator, and FileFlags to get information about the file currently held in the file viewer field.
Fixed list
Has the attributes of their subfield type as set in FirstClass Designer.
If the subfield type is text, you can use the text attribute of any subfield.
Fixed list attributes are accessed as if the fixed list is an array, so lstFixed(0)="Hello" would set the first attribute of the fixed list to a literal string. You can use the Reset method to clear all field content for the field and the Index attribute to identify which element in the list has the focus. Fixed lists stay whatever size you initially set them, unlike expanding lists, which grow larger as more elements are added.
Graphics
Icon
Provides a Value attribute that contains the icon ID of the icon displayed in the field.
Line
Has no special attributes.
Oval
Has no special attributes.
Picture
Provides a Value attribute equal to the resource ID of the picture.
The picture resource must exist in the settings file or the FirstClass Resource Registry in order to be properly displayed.
Rectangle
Has no special attributes.
Round rectangle
Has no special attributes.
Group box
Has no special attributes.
Guide text
Has a Text attribute that contains the text displayed in the field.
Marquee
Has a Text attribute that contains the text in the marquee.
Number
Has a Value attribute that contains the number entered in the field.
This field type only allows numeric entry; no text is possible.
Progress bar
Has a Value attribute which can be set or retrieved and indicates the progress on the bar.
The range of this value is set in FirstClass Designer and defaults to 0 to 100.
String with icon
Has both a Text attribute that contains the text portion of the field and an Icon attribute that contains the resource ID of the icon associated with the field.
Time period
Has a Value attribute that contains a numeric representation of the period of time displayed in the field.
Field attributes
Admin
Retrieves or assigns the Admin attribute of a field. This attribute allows the administrator to view and modify a field that is Hidden or Protected.
This attribute has been deprecated. To emulate this functionality, get the user's user ID from the FCUserID function and set the Protected and Hidden attributes explicitly.
Syntax
[formname].fieldname.Admin [= TRUE/FALSE value]
Bold
Displays field text in bold.
Syntax
[formname].fieldname.Bold [= TRUE/FALSE value]
Border
Displays a border around a field. If this field attribute is set, only buttons will trigger a click event for the field.
Syntax
[formname].fieldname.Border [= TRUE/FALSE value]
Bottom
Displays field text aligned with the bottom boundary of the field.
Syntax
[formname].fieldname.Bottom [= TRUE/FALSE value]
Caption
Retrieves or assigns the text caption for nontext fields. This attribute is often used to set the text on button fields.
Syntax
[formname].fieldname.Caption [=string expression]
Center
Displays field text centered between the top and bottom boundaries of the field.
Syntax
[formname].fieldname.Center [= TRUE|FALSE value]
Color
Displays the field text in the default color.
Syntax
[formname].fieldname.Color [= TRUE|FALSE value]
Condense
Displays field text in condensed text style.
The condensed text style is not available on the Windows client; it is only available on the Mac OS client.
Syntax
[formname].fieldname.Condense [= TRUE|FALSE value]
CreationDate
Retrieves the file CreationDate attribute of a file viewer field.
Syntax
[formname].fieldname.CreationDate
Data
Retrieves or assigns a field's binary data. The binary data can, in most instances, be manipulated as a string.
This is used in fields such as a picture or file viewer.
Syntax
[formname].fieldname.Data
DataSize
Retrieves the data size attribute of a file viewer field.
Syntax
[formname].fieldname.DataSize
DataType
Retrieves a constant integer value indicating the data type of the field.
This field attribute is read only at runtime.
Syntax
[formname].fieldname.DataType [constant]
These are the possible values for constant:
• FCString - character or text data
• FCInteger - long integer numeric data
• FCLong - long integer numeric data
• FCSingle - double floating point numeric data
• FCDouble - double floating point numeric data
• FCCurrency - currency data
• FCDate - date and time data.
Editable
Retrieves or assigns the Editable attribute of a field. Setting the Editable field attribute allows the user to edit and modify a field's value.
Syntax
[formname].fieldname.Editable [= TRUE|FALSE value]
Extend
Displays field text in extended text style.
The extended text style is not available on the Windows client; it is only available on the Mac OS client.
Syntax
[formname].fieldname.Extend [=TRUE|FALSE value]
FileCreator
Retrieves the Mac OS file creator attribute of a file viewer field.
Syntax
[formname].fieldname.FileCreator
FileFlags
Retrieves the Mac OS file flags attribute of a file viewer field.
Syntax
[formname].fieldname.FileFlags
Filename
Retrieves the file name attribute of a file viewer field.
Syntax
[formname].fieldname.Filename
FileSize
Retrieves the file size attribute of a file viewer field.
Syntax
[formname].fieldname.FileSize
FileType
Retrieves the Mac OS file type attribute of a file viewer field.
Syntax
[formname].fieldname.FileType
FullJust
Retrieves or assigns whether or not the field is fully justified.
Syntax
[formname].fieldname.FullJust [=TRUE|FALSE]
Gray
Displays field text in gray rather than the default color (black).
Use this attribute in conjunction with the Protected attribute to indicate editable fields that are currently protected.
Syntax
[formname].fieldname.Gray [=TRUE|FALSE value]
Hidden
Hides a field.
When this attribute is set, all users are prevented from viewing and manipulating the field. Since the field is unavailable to the user, modifying data, receiving events, and processing event procedures are not possible from the user interface. Field attributes, values, and events may still be accessed from within the code.
Syntax
[formname].fieldname.Hidden [= TRUE|FALSE]
Icon
Retrieves or assigns the resource ID of the currently displayed icon.
The resource ID must match an icon resource ID that the users have in their settings file, the client itself, or the FirstClass Resource Registry. Otherwise, nothing will be displayed.
Icon changes do not require transfer of data from client to server, so any icon resource ID changes are very quick.
Syntax
[formname].fieldname.Icon [= resource]
Index
Retrieves or assigns the ordinal number of the currently selected field in a fixed list or expanding database list.
Syntax
[formname].fieldname.Index [= numericvalue]
The first element in a list is designated as Index 0. When the focus is set to an item in the list, the Index attribute of the list is set to the field's ordinal value. The Index may also be set by direct assignment to a positive integer value.
Italic
Displays field text in italics.
Syntax
[formname].fieldname.Italic [= TRUE|FALSE value]
Key
Retrieves or assigns a nondisplaying Key value in association with an element in an expanding database list or fixed list field.
The Key attribute can be assigned a value of any type, but once assigned at runtime, the data type of the Key attribute for the list cannot be changed.
Syntax
[formname].fieldname.Key [=anyvalue]
List
Retrieves or assigns the List attribute of a list field.
Syntax
[formname].fieldname.List [=string expression]
The List attribute is stored as a semicolon-delimited list of strings. If the list is used in an enumerated list field, the values will be automatically assigned to each string in the list. Automatically generated numbers begin with 0 and increment one number for each item in the list. Numbers can also be assigned to the list items in an enumerated list.
Example
Cat;Dog;Fish will be displayed in a list field as three separate strings (one string per list): Cat, Dog, and Fish.
Automatically generated numbers:
Cat 'returns 0
Dog 'returns 1
Fish 'returns 2
Assigned numbers:
Cat=100;Dog=23;Fish=7
Cat 'returns 100
Dog 'returns 23
Fish 'returns 7
ListCount
Returns the current number of items in an expanding or fixed list field.
Syntax
[formname].fieldname.ListCount
For more information, see fixed lists and expanding lists in FirstClass Rapid Application Developer Guide.
ModificationDate
Retrieves the modification date attribute of a file viewer field.
Syntax
[formname].fieldname.ModificationDate
Name
Retrieves or assigns the name of a field.
Changing the name of a field with the program running can cause unpredictable behavior unless code is carefully written.
Syntax
[formname].fieldname.Name[= fieldname]
where fieldname is the name of the field in string expression format.
NoOpenSpace
Prevents the form from expanding if the field expands.
Syntax
[formname].fieldname.NoOpenSpace [= TRUE|FALSE value]
Outline
Displays the field text in outline text style.
The outline text style is not available on the Windows client, only on the Mac OS client.
Syntax
[formname].fieldname.Outline [=TRUE|FALSE value]
Password
Displays all text characters as asterisks. Text values will be exactly as they are input, but any input and output to this field will be displayed as asterisks.
Syntax
[formname].fieldname.Password [= TRUE|FALSE value]
Protected
Prevents all users from manipulating the field. This includes modifying data, receiving events, and processing event procedures. Field attribute values and events may still be accessed from within the code.
Syntax
[formname].fieldname.Protected [=TRUE|FALSE value]
ResourceSize
Retrieves the Mac OS resource fork size attribute of a file viewer field.
Syntax
[formname].fieldname.ResourceSize
RJust
Displays field text with right justification.
Syntax
[formname].fieldname.RJust [= TRUE|FALSE value]
Selectable
Makes a field able to be selected.
Syntax
[formname].fieldname.Selectable [=TRUE|FALSE value]
Selected
Sets the focus to the field.
This attribute has been deprecated; use the SetFocus field method.
Syntax
[formname].fieldname.Selected [=TRUE|FALSE value]
Shadow
Displays the field text in shadow text style.
The shadow text style is not available on the Windows client; it is only available on the Mac OS client.
Syntax
[formname].fieldname.Shadow [=TRUE|FALSE value]
Text
Retrieves or assigns the string that is the text value for the field. Text and Value are the default attributes for fields. This is only applicable to fields of string type, such as text fields and editable lists.
Syntax
[formname].fieldname.Text [=string expression]
Transparent
Displays fields with transparent backgrounds. Background fields, such as graphics and icons, are visible through this field.
Syntax
[formname].fieldname.Transparent [TRUE|FALSE]
Underline
Underlines field text.
Syntax
[formname].fieldname.Underline [=TRUE|FALSE value]
Value
Retrieves or assigns the numeric value of a field.
This is only applicable to fields with numeric values, such as checkboxes and enumerated lists.
Syntax
[formname].fieldname.Value [=TRUE|FALSE value]
The Value field attribute also retrieves date information. Text and the Value field attribute are the default attributes for fields.
Wrap
Displays field text with word wrap. This is essential for any multiline text box.
To enter and display carriage returns in a text field, this attribute must be set.
Syntax
[formname].fieldname.Wrap [TRUE|FALSE value]
File attributes
Archive
Retrieves or assigns a file's Windows archive bit. This attribute is ignored for Mac OS file downloads.
Syntax
filevariable.Archive
CreationDate
Retrieves or assigns a file's creation date.
Assignment of the creation date is only applicable to file downloads.
Syntax
filevariable.CreationDate
Data
Retrieves or assigns a file's data.
The Data attribute contains binary data which, in most instances, may be manipulated as a string. The Data attribute is used directly in conjunction with the Download and Read methods.
Syntax
filevariable.Data
DataSize
Retrieves the file's data fork size in bytes.
Syntax
filevariable.DataSize
FileCreator
Retrieves or assigns a file's Mac OS file creator.
The FileCreator attribute is ignored for Windows file operators.
Syntax
filevariable.FileCreator [integer|string]
This attribute may be assigned either a long integer or a four-character string representing the Mac OS file creator (for example, MyFile.FileCreator = "ttxt").
FileFlags
Retrieves or assigns the file's Mac OS file flags.
The FileFlags attribute is ignored for Windows file operators.
Syntax
filevariable.FileFlags
Filename
Retrieves or assigns a file's filename.
Syntax
filevariable.Filename
FileSize
Retrieves a file's size in bytes.
The size of the resource fork, if any, is counted in returning the size of the file.
Syntax
filevariable.FileSize
FileType
Retrieves or assigns the file's Mac OS file type.
This attribute is ignored for Windows file operations.
Syntax
filevariable.FileType [= string]
This attribute may be assigned either a long integer or a four-character string representing the Mac OS file type (for example, MyFile.FileType = "TEXT").
Hidden
Retrieve or assigns a file's Windows hidden bit.
This attribute is ignored for Mac OS file downloads.
Syntax
filevariable.Hidden
ModificationDate
Retrieves or assigns a file's last modification date. Assignment of the modification date is only applicable to file downloads.
Syntax
filevariable.ModificationDate
Normal
Retrieves or assigns the normal file bit for a Windows file.
A file with this attribute does not have the read-only, system, hidden, or archive bits set.
Syntax
filevariable.Normal
ReadOnly
Retrieves or assigns the file's Windows read-only bit.
This attribute is ignored for Mac OS file downloads.
Syntax
filevariable.ReadOnly
ResourceSize
Retrieves the file's resource fork size in bytes.
Syntax
filevariable.ResourceSize
SubDir
Indicates whether the file entry is a subdirectory. It is used for accessing directory information returned from the FindFirst and FindNext methods. This attribute is read only.
The TRUE/FALSE flag indicates whether the item is a subdirectory. TRUE if it is, FALSE if it is a file or other file system object.
Syntax
filevariable.SubDir
System
Retrieves or assigns the file's Windows system bit. The TRUE/FALSE flag indicates whether the file contains the operating system's system bit.
This attribute is ignored for Mac OS file downloads.
Syntax
filevariable.System
File methods
CloseFile
Closes a file that has been opened with the OpenFile method.
If a variable is declared globally, the file closes when the program ends. If a variable is declared locally, the file closes when the program exits that subroutine.
Syntax
filevariable.CloseFile
Example
See the example for the Openfile method.
Download
Initiates a client file download.
To specify the default file name (displayed in the file download dialog) supply the file object's Filename attribute.
The downloaded object may be either a file in a file system or it may be created from a string or data variable. To download a file in a file system, open the desired file for reading with the OpenFile method and then call the Download method. To download a file from a string or data variable, assign the Data attribute of the file object that does not currently have a file open, and call the Download method.
Syntax
filevariable.Download
Example
MyFile.Data = "Test File Data"
MyFile.Filename = "Test.txt"
MyFile.Download
EOF
Returns the current status of the end of file (EOF) flag. The EOF flag indicates whether the file has read up to, or beyond, the end of the file.
Syntax
filevariable.EOF
Example
See the example for the Read file method.
FindFirst, FindNext
Retrieves file information from the server's file system.
Syntax
Filevariable.FindFirst(filespec), filevariable.FindNext
The FindFirst method retrieves information from the first file found matching the filespec argument (any string representing a valid operating system file specification including wildcards). The FindNext method finds the next file (and subsequent files) matching the filespec argument specified in FindFirst.
When there are no more matching files, the filevariable's FileName attribute will be an empty string ('''').
Do not open the filevariable with the OpenFile method when using FindFirst, FindNext.
Example
MyFile.FindFirst ("C:\Winnt\*.exe)
MyFile.FindNext
OpenFile
Opens, creates, or sends a file for reading, writing, and/or downloading.
Syntax
filevariable.OpenFile(path,openconst)
The path specifies a path to a file on the server that is to be opened. The openconst argument specifies how the file should be opened and can consist of the following values:
• fc.Read - opens a file for reading; otherwise displays an error
• fc.Write - opens a file for writing; otherwise displays an error
• fcAppend - opens a file for appending without removing the EOF marker before writing new data.
A new file is created if one does not exist.
• fcUpdate - opens a file for both reading and writing; otherwise displays an error
• fcReadWrite - opens an empty file for both reading and writing.
If the file exists, the contents are deleted. Otherwise, the file is created.
Example
MyFile.OpenFile ("C:\TEST.TXT", fcWrite)
MyFile.OpenFile ("C:\TEST.TXT", fcRead)
Position
Moves the file cursor used for reading and writing.
Syntax
filevariable.Position(origin[,offset])
The Position method moves the position of the cursor in a file in the server's file system. The origin argument indicates the starting point, and the offset argument indicates the number of bytes to move from that location (+ value indicates a move forward; - value indicates a move backwards). The origin argument must be one of the following:
• fcBegin - file cursor origin at the beginning of file
• fcEnd - file cursor origin at the end of file
• fcCurr - file cursor origin at the current position (unchanged).
Example
MyFile.Position (fcBegin) 'position cursor at beginning of file'
MyFile.Position (fcEnd, -10) 'position cursor 10 characters back from end of file'
Read
Attempts a binary read of bytes from a file on the server.
Syntax
filevariable.Read(numbytes)
The read data is stored in the Data attribute of the File object. If the end of file is reached before numbytes bytes are read, the Read method stores the maximum number of bytes.
Example
MyFile.Read(100)
Print MyFile.Data
ReadLine
Reads from an open text file until the end of the current line and returns the result as a string. This makes text parsing much easier and allows for faster reading of text-based data into RAD variables.
Syntax
ReadLine (MaximumBytesToBeRead)
Example
Dim MyFile as File
MyFile.OpenFile ("c:\autoexec.bat", fcRead)
print "The first line of your autoexec.bat file is:" &
MyFile.ReadLine(1024)
MyFile.CloseFile
Write
Writes binary or text data to a file on the server.
If the file has not been opened for writing with the OpenFile method, Write will display an error.
Syntax
filevariable.Write(filedata)
Example
MyFile.Write 'This string is written into the file
Form attributes
Hidden
Shows or hides a form. This form attribute also can be used to determine the current state of a form; if the form is shown, the Hidden attribute is FALSE. Otherwise, the Hidden attribute is TRUE.
Syntax
[formname].Hidden [= TRUE|FALSE value]
Example
Sub Click()
If MyForm.Hidden = TRUE Then
MyForm.Title = "Form Title"
MyForm.Show
End If
End Sub
MouseX,MouseY
Retrieves the last X and Y coordinates clicked on the form body (including any protected controls).
Syntax
formname.MouseX
formname.MouseY
Example
Sub Main()
MyForm.MouseX
MyForm.MouseY
End Sub
Title
Displays the form's window title string.
Syntax
[formname].Title [=string expression]
The title can be assigned any valid string expression.
Example
Sub Click()
MyForm.Title = "My form Title"
MyForm.Show
End Sub
Form events
Activate
Activates an event on a form.
The event is triggered when the form is activated. A form is activated when the form receives focus.
Click
Clicks an event on a form.
The event is triggered when the user clicks on the form body or on a protected field on the form.
Deactivate
Deactivates an event on a form.
The event is triggered when the form is deactivated. A form is deactivated when the focus is set to another form.
DoubleClick
Double-clicks an event on a form.
The event is triggered when the user double-clicks on the form body or on a protected field on the form.
Load
Loads an event.
The event is triggered when the form is first loaded or shown. A form is loaded with the Load command or shown with the Show method.
Unload
Unloads an event.
The event is triggered when a form is closed, either by clicking the close box on the form or programmatically, using the Unload command.
Form methods
DisableFormEvents
Disables the following form events:
• Click
• DoubleClick
• Activate
• Deactivate
and the following field events:
• Click (except buttons)
• DoubleClick
• GotFocus
• LostFocus.
This form method is useful for applications running on high usage systems. If the events listed are not used in the application, disabling these form events can reduce client-server overhead.
Syntax
formname.DisableFormEvents
EnableFormEvents
Enables form and field events disabled with the DisableFormEvents form method.
Syntax
formname.EnableFormEvents
Hide
Hides a form from view.
A hidden form is not unloaded; the form continues to exist with current attributes and values intact. Showing a hidden form will redisplay the form with all attributes set as they were prior to running the Hide form method. If the application ends, a hidden form is automatically unloaded.
Syntax
formname.Hide
Show
Displays a modeless form. If the form has not been loaded, Show will load the form and data environment before displaying.
Syntax
formname.Show
Swap
Hides a form's content and display a second form within the form's original window.
Syntax
formname.Swap(swapform)
The swapform argument can be any string expression that is a valid form name. This method allows the programmer to dramatically change the interface in the window without hiding and unhiding fields.
Be sure to put the swapform argument as a string and not a direct reference to the form object. If the swapform argument is a direct reference to the form object, the form's default attribute, Title, will be used as the swap form name.
Example
Form1.Swap("Form2) 'Correct!
Form1.Swap(Form2) 'Incorrect! Passes Form2's title as an argument.
|