| Quick Reference | Visual MacStandardBasic 4.0 Reference Manual |
Visual MacStandardBasic 4.0 Tutorial |
Visual MacStandardBasic
4.0
Users Guide
Copyright © 1999 ZCurve Software - All Rights Reserved
MacStandardBasic and ZCurve are trademarks of ZCurve Software.
Macintosh, Apple, and Apple logos are registered trademarks of Apple Computer, Inc.
Visual MacStandardBasic 4.0
Welcome to Visual MacStandardBasic 4.0. The easiest way to create fast, powerful applications for the Macintosh.
Now anyone can create visually their own software and you do not need to know the inner details of the Macintosh.
Visual MacStandardBasic was designed to give you the ability to exploit the graphic and multimedia capabilities of the Macintosh operating systems.
The Visual MacStandardBasic Development System contains a 2 pass optimizing compiler that creates a single file application for both 68K and Power Macintoshes.
Applications you create will run native PowerPC code to harness the speed of Power Macintoshes. At your option, your application will produce 68K code, PowerPC code, or a combination of both. This combination is known as a FAT Binary Application, meaning that it will automatically run the fastest on the type of Macintosh the user has.
The Visual MacStandardBasic language can be extended with Code Resource Modules to ass more functionality.
For the Visual MacStandardBasic Development System:
Macintosh (68030 or 68040) or Power Macintosh Computer
Runs native on Power Macintoshes
System 7.1 or greater
8MB RAM
5MB Hard Drive Space
For an application created using Visual MacStandardBasic:
Macintosh (68K) or Power Macintosh Computer
Runs native on Power Macintoshes
System 7.1 or greater
4MB RAM
Included with Visual MacStandardBasic are many sample applications with project and source code. These are free for you to use in learning to use Visual MacStandardBasic and to use in your own projects. There are more sample applications that are available at the ZCurve website at:
or
http://www.MacStandardBasic.com
Starting Visual MacStandardBasic
To start Visual MacStandardBasic, open the Visual MacStandardBasic folder that was installed and select the Visual MacStandardBasic icon.
After you see the Visual MacStandardBasic logo screen displayed, you are ready to create a new project or open an existing one.
Overview of the Visual Development Environment
After starting Visual MacStandardBasic your Macintosh will be running the Visual Development Environment (VDE). The VDE allows you to:
The following is a description of the menu bar options:
Apple Menu
About MacStandardBasic...
This will display copyright information about Visual MacStandardBasic 4.0.
New Project
Creates a new Visual MacStandardBasic project. You will be prompted for the name of the project file and the name of the application file to be created.
Open Project
Opens an existing project.
Close Project
Closes the current project.
New Form
Creates a new form window allowing you to create and edit controls in Visual MacStandardBasic. When the form saved as a file, it will be added to the Form section of the project list. All files in a project must be in the same folder as the project file.
New Module
Creates a new editor window for a Visual MacStandardBasic source code module. When saved as a file, it will be added to the project list. All files in a project must be in the same folder as the project file.
Save File
Saves the contents of the current editor window. If there is no filename associated with the editor window, it will prompt you for one. If this editor window was created with the New File menu option, then this file will be added to the current project.
Save File As
This option allows you save the current editor window to a new file. If this editor window was created with the New File menu option, then this file will be added to the current project.
Close Window
Closes the current form or module window. It will prompt you to save the file if there have been changes.
Add File
You should use this option to add a Visual MacStandardBasic form, module, or a resource file to the current project. All files in a project must be in the same folder as the project file.
Remove File
This option will just display an instruction alert that you need to hold down the Command key when selecting a file from the project's menu to remove it from the project.
Page Setup
Prompts for changing printed page setup options.
Use this option to print the source code from the current form or module.
Quit
This option will close the current project and exit Visual MacStandardBasic.
Undo
Allows you to undo the last action involving text editing.
Cut
Cuts the selected text from the current editor window and places it in the Clipboard.
Copy
Copies the selected text from the current editor window and places it in the Clipboard.
Paste
Inserts the contents of the Clipboard at the current cursor position or in place of selected text.
Clear
Removes the selected text from the current editor window.
Select All
Selects all the text in current editor window.
Find
Allows you to search the current editor for text matching a text string that you enter.
Find Next
This option will find the next occurrence of the Find text string.
Replace
Allows you to search and replace text in the current editor window.
Replace Next
This options searches for the next replace occurrence in the current editor window.
Goto Line #
Jumps to the line #, that you enter, in the current editor window.
Compile & Run
Compiles the current project. If there are errors, an error log is displayed. If there are no errors, the compiled application will be executed.
Compile
Compiles the current project. If there are errors, an error log is displayed.
Run
Executes the compiled application produced by the current Visual MacStandardBasic project.
Execution Filename
This option allows you to change the name of the application file to be created.
Application Memsize
Use this option to modify the memory parameters for the compiled application produced by the current Visual MacStandardBasic project.
View Tool Palette
Select this option to view the Tool Palette that was previously closed..
View Properties
Select this option to view the Properties window.
Standard FAT Library
This instructs the compiler to compile a application for use with both PowerPC and 68K Macintoshes.
Standard PPC Library
This instructs the compiler to compile a application for use with Power Macintoshes only.
Standard 68K Library
This instructs the compiler to compile a application for use with 68K Macintoshes only.
Please note that with Version 4.0, additional items will be listed in this menu if you add other Libraries.
A Visual MacStandardBasic project contains information on how an application should be created and what source code and resource files will be used. A project can contain many form, module, and resource files and does not care what order they appear in the project list.
Forms are windows and controls visually created in Visual MacStandardBasic. Forms also contain Sub procedures, which can be associated with the controls and Function procedures as you would in Modules.
Modules contain Sub and Function procedures written in the Visual MacStandardBasic language.
Resource files contain the resources such as pictures, icons, & sounds. There should be no source code in a resource file (this means the Data Fork must be empty) for Visual MacStandardBasic to properly recognize that this file should be used as a resource file in the project. Resources stored in source code files will not be used in creating an application. Resource files are shown enclosed in brackets in the project's menu.
When you create a new project, a new form (Form1) is created for you. Several procedures, we call the stationary, are preinstalled in Form1 to provide the framework for your application.
These procedures include Start procedure, that's were execution will start, and other that set a minimal menubar and functionality.
The following is the source code of the procedures preinstalled in Form1. You should refer to the tutorial for a detailed description of the stationary.
Start
Dim A CreateTheMenus Form Form1 A=0 Do While A=0 Loop
Finish Sub CreateTheMenus( )
MenuApple MenuAddItem 1, "About Application", "", AboutTheApp MenuDesk MenuAdd 2, "File", None MenuAddItem 2, "Quit", "Q", QuitTheApp
EndSub Sub QuitTheApp( )
End
EndSub Sub AboutTheApp( )
Dim a
a = MsgBox ("Application Info"+chr(13), 0)
EndSub
When you want to create a new application then you need to create a Visual MacStandardBasic project.
Creating your first Visual Application
A beginning tutorial can show you how to use Visual MacStandardBasic. Go through the Visual MacStandardBasic Tutorial.
Operators below within each group are processed left to right:
Highest to Lowest Precedence:
( ) Function calls ( ) Parentheses enclosure [ ] Array elements ------------------------- - Negation ------------------------- * Multiply / Division ------------------------- + Addition - Subtraction ------------------------- = Equal to < > Not equal to < Less than < = Less than or equal to > Greater than > = Greater than or equal to ------------------------- AND Logical AND OR Logical OR
Strings can be concatenated with the + (plus) operator.
Note: Some BASIC's use the ^ symbol as the 'to power to' operator see the Power() function.
Variables need to be declared in the DIM command before being used in your program. If variables are declared in a GLOBAL module using the DIM command, then all SUB and FUNCTION procedures have access to the variable. A variable declared inside a SUB or FUNCTION is only accessible within that procedure.
Dim var [, var, var, …]
This command will create variables for storing numeric and string values.
Variable Types:
There are five different variable types in Visual MacStandardBasic:
Type Designator Bytes Usage Integer % 2 For integer numeric values between -32768 and 32768. Long & 4 For integer numeric values between + and -2,147,483,648 Single ! 8 For double precision floating point numerics Double # 8 For double precision floating point numerics String $ User Def. For text strings up to 2,147,483,648 in length.
Rules for variables:
TRUE and FALSE
The keywords TRUE and FALSE are reserved values of 1 and 0 respectively. You can use these in your code to improve readability.
Examples: ' The following two statements are equal a = True a = 1 ' The following two statements are equal a = False a = 0
String Variables Important!
Like all variables in Visual MacStandardBasic, string variables must be declared with DIM command. Visual MacStandardBasic requires string variables to have a maximum length assigned to them. If this not designated in the DIM statement then the string variable will have a 100 character length limit. String arrays must have the length explicitly declared in the DIM statement.
This allows Visual MacStandardBasic to process string variables much faster than other BASIC language implementations. For dynamic string storage look at the Memory Buffers section of this manual.
Examples: Dim name$[200] ‘The name$ can be up to 200 characters in length. Dim Age&, Name$ ‘Age is a long variable while Name$ is a ‘ string variable that defaults to 100 chars max. Dim titles$[4][30][850] ‘ titles$ is a 2 dimensioned string array ‘ of 120 elements (4 * 30) that contain ‘ up to 850 characters each.
Assigning values to variables:
var = argument
This command will assign the var the result of the argument.
Examples: Dim a%, b!, name$[200] ‘ We just created 3 new local variables ‘ Please note that names$ is a single ‘ variable with max. of 200 chars, it is NOT an array b! = 63.123 ‘ b is single (floating point) & equals 63.123 a = b ‘ a is an integer ‘and equals 63 (it ‘ truncates right of the decimal point names$ = "The temperature is "+ STR(a)+ " degrees." ‘ name$ equals the string "The temperature is 23 degrees."
There is a special procedure in every Visual MacStandardBasic program, this is called the START procedure. There should be one and only one START procedure in every Visual MacStandardBasic project. Program execution of every Visual MacStandardBasic program starts at START. The FINISH statement designates the end of the START procedure.
Example: START
Dim A&, Num& A = 5 For Num=0 to 15 A = A * 34 Next Num End
FINISH
Programs that you will write in Visual MacStandardBasic will normally have more than just a START procedure. Sub and Function procedures allow you to create callable procedure modules.
Creating a Sub procedure allows you to effectively create a new command. The code in a Sub procedure can call any Visual MacStandardBasic commands, Sub procedures, and Function procedures. In fact, a Sub procedure can call itself, this is called recursion. You should not attempt to call the Start procedure. You must indicate the end of a Sub procedure with the command EndSub.
Variables created as passed variables or with Dim command, within this Sub procedure, are accessible only while code in the Sub procedure is executing. Once the Sub is exited, these variables no longer exist. You can create variables using the Dim command in a Global Module that always exist and are accessible in all Sub and Function procedures.
In an example, as shown below, a Sub procedure ManyBeeps is created and called from the Start procedure. The ManyBeeps Sub procedure will sound the system beep the number of times specified in NumOfLoops&, in this case 5 times.
Subroutines Example: Start
ManyBeeps 5 ‘ This passes the value 5 to ManyBeeps
Finish Sub ManyBeeps ( NumOfLoops&)
Dim Num& For Num=0 to NumOfLoops Beep Next Num
End Sub
Sub procedures can be used when creating windows and controls. These procedures are called when an event happens to that window or control. An event, for example, would be when a user does a mouse click in a button control.
Functions are similar to Sub procedures except that they return a value when done. Function procedures are used in numeric and string arguments for Visual MacStandardBasic commands and user created Sub and other Function procedures.
The code in a Function procedure can call any Visual MacStandardBasic commands, Sub procedures, and Function procedures. In fact, a Function procedure can call itself, this is called recursion. You should not attempt to call the Start procedure. You must indicate the end of a Function procedure with the command EndFunction.
Variables created as passed variables or with the Dim command, within this Function procedure, are accessible only while code in the Function procedure is executing. Once the Function is exited, these variables no longer exist. You can create variables using the Dim command in a Global Module that always exist and are accessible in all Sub and Function procedures.
Functions need to have a return type which is designated with the AS parameter.
Return Type Examples: ' Functions returns an Integer Function AddNum( first#, second! ) AS % Function AddNum( first#, second! ) AS Integer ' Functions returns a Long Function AddNum( first#, second! ) AS & Function AddNum( first#, second! ) AS Long ' Functions returns a Single Function AddNum( first#, second! ) AS ! Function AddNum( first#, second! ) AS Single ' Functions returns a Double Function AddNum( first#, second! ) AS # Function AddNum( first#, second! ) AS Double ' Functions returns a String Function AddNum( first#, second! ) AS $ Function AddNum( first#, second! ) AS String
We can expand on our previous example for Sub procedures but will keep it simple:
Function Example: ‘ The & character after the As means that this function returns a long value Function Multiplier5( value1& ) As Long
Dim Result& Result = value1 * 5 ExitFunction Result
EndFunction Start
ManyBeeps Multiplier5( 2 ) ‘ This passes the value 10 (or 2 * 5) to ManyBeeps
Finish Sub ManyBeeps ( NumOfLoops&)
Dim Num& For Num=0 to NumOfLoopsBeepNext Num
End Sub
In this example the system beep will sound 10 times. The value 2 was passed to the Multiplier5 function procedure. All this function does is multiply the passed value 2 by 5 and return the results.
Global variables are variables that are accessible by all Start, Sub, and Function procedures. Every Form and Module has a Global procedure accessible from the pull-down menu in the Editor window.
The only command allowed in a Global module is the DIM command. Of course you can make comments by using the apostrophe.
Global Example: GLOBAL ‘ All these variable are accessible from any procedure Dim Title$[200] ‘ The string Title can be up to 200 characters in length. Dim Age&, Name$ ‘ Age is a long variable while Name$ defaults to 100 chars max. Dim NameList$[20][50] ‘ NameList is a 1 dimensioned string array ‘ of 20 strings that contain up to 50 characters each. ENDGLOBAL
It is helpful to place text in the source code of a BASIC program for remembering and understanding what a section of source code is suppose to do. This is especially important when the BASIC program is going to be modified by someone else than the original programmer.
Comments are text that is ignored by the Visual MacStandardBasic compiler. You will notice comments in the source code examples in this manual.
There are two ways to add these program comments and both are equally effective:
REM comment
This is a command that allows you to add comments to help in documenting the program. REM is short for the word remark. If it is the 2nd or later command in a program statement it must be proceeded by a colon (:) just like other commands. Remember to place a space after the REM and before the comment text.
‘ comment
This is probably the easiest way to add a comment to your source code. Text following the apostrophe is ignored by the Visual MacStandardBasic compiler. Unlike the REM command, a space is not required after the apostrophe.
The following is a Visual MacStandardBasic source code example that uses both methods for adding comments:
Examples: START
DIM Name$, Fact$[50] ‘ Define some string variables (comment) REM Assign a name to the string ( this is a comment too!) Name = "cool!" Fact = "Macs are " + Fact ‘ Just the facts End : REM All done (everything after the REM is this comment)
FINISH
The tool palette allows you to select what type of control you would like to create. Use Selection Control to move or resize an existing control.
The properties window allows you to interactively modify the properties of forms and controls.
Please note the terms window and form can be used interchangeably.
Name
This is the text name of the form that can be referenced in Visual MacStandardBasic commands and functions.
Example: Form Form1 ' To open a form CtlValue Form1.ScrollBar1, 5 ' Explicit window and control specified
Title
This is the text that will be in the Windows title bar, if it has one.
Left
This number specifies the left side coordinate of the form on the screen.
Top
This number specifies the top coordinate of the form on the screen.
Width
This number specifies the width of the form on the screen.
Height
This number specifies the height of the form on the screen.
Sub Proc.
This text indicates the Sub procedure for window events for this form. If there is not a Sub procedure designated, then this should be set at NONE.
Visible
This indicates if the form will be initially visible when opened with the Form command.
Style
This specifies the form style.
Font
This indicates the default font for the form.
FontSize
This indicates the default font size for the form.
FontStyle
This indicates the default font style for the form.
Show Grid
This indicates whether the grid should be displayed in the visual development environment. This property is only used during design and has no effect during runtime.
Grid Snap
This indicates whether the controls should 'snap' to the grid when they are created, moved, or resized. This property is only used during design and has no effect during runtime.
Grid Size
This number indicates the density, in pixels of the grid to be displayed in the visual development environment. This property is only used during design and has no effect during runtime.
Min. Width
This number indicates the minimum width the form can be when resized by the user of the application.
Max. Width
This number indicates the maximum width the form can be when resized by the user of the application.
Min. Height
This number indicates the minimum height the form can be when resized by the user of the application.
Max. Height
This number indicates the maximum height the form can be when resized by the user of the application.
AutoCenter
This indicates whether the form will be automatically centered on the screen when opened with the Form command
ForeColor
This is used to specify the default foreground color of the form.
BackColor
This is used to specify the default background color of the form.
Please note the terms: window and form can be used interchangeably.
Properties used with each control:
Button
Name, Text, Left (x), Top(y), Width, Height, Sub Proc., Visible, Default, Enabled
Label
Name, Text, Left (x), Top(y), Width, Height, Sub Proc., Visible, Enabled, Font, FontSize, FontStyle, ForeColor, BackColor
TextBox
Name, Text, Left (x), Top(y), Width, Height, Sub Proc., Visible, Enabled,
Single Line, Font, FontSize, FontStyle, ScrollBar, Read Only, Frame,
ForeColor, BackColor
Icon
Name, Left (x), Top(y), Width, Height, Sub Proc., Visible, Value, Enabled, Frame
Picture
Name, Left (x), Top(y), Width, Height, Sub Proc., Visible, Value, Enabled, Frame
CheckBox
Name, Text, Left (x), Top(y), Width, Height, Sub Proc., Visible, Value, Enabled
Radio Button
Name, Text, Left (x), Top(y), Width, Height, Sub Proc., Visible, Value, Enabled, GroupID
DropList
Name, Text, Left (x), Top(y), Width, Height, Sub Proc., Visible, Value, Enabled
ListBox
Name, Text, Left (x), Top(y), Width, Height, Sub Proc., Visible, Value, Enabled, MultiSel., Frame, ForeColor, BackColor
Timer
Name, Text, Left (x), Top(y), Width, Height, Sub Proc., Visible, Interval, Enabled
ScrollBar
Name, Left (x), Top(y), Width, Height, Sub Proc., Visible, Value, Enabled, Min. Value, Max. Value, PgUpDn
Name
This is the text name of the control that can be referenced in Visual MacStandardBasic commands and functions.
Example: CtlValue Form1.ScrollBar1, 5 ' Explicit window and control specified CtlValue CheckBox2, 5 ' The control specified in the local form
Text
This is the text that will be used in the control.
For listboxes and droplists, you can preload multiple items by adding them to the text property, during design time only. Items need to be separated by a vertical bar. | (Usually shift-backslash on Mac keyboards)
Item1|Item2|Item3|Item4
Left
This number specifies the left side coordinate of the control on the form.
Top
This number specifies the top coordinate of the control on the form.
Width
This number specifies the width of the control on the form.
Height
This number specifies the height of the control on the form.
Sub Proc.
This text indicates the Sub procedure for events for the control. If there is not a Sub procedure designated, then this should be set at NONE.
Visible
This indicates if the control will be initially visible when the form is opened with the Form command.
Value
This indicates if the initial value setting for the control. For icons and picture controls this is the resource ID. This is the item initially selected in droplist and listbox controls. For checkbox and radio button controls this sets the on/off state of the control.
Default
This property is for button controls only. It specifies if a button is the default button whose Sub procedure will be called if the user presses the Return (or Enter) key in the form. The exception is if there are textboxes on the form, see the Single Line property description for more information.
Interval
This property is for timer controls only. It specifies the # of ticks (a tick = 1/60 of a second) between calling the controls Sub procedure.
Single Line
This property is for textbox controls only. It specifies if the textbox is limited to a single line of text.
If it is, a press of the Return (or Enter) key will 'tab' to the next textbox. If it is the last or only textbox on the form and there is a 'default' button the form the Sub procedure of the button control will be called.
Enabled
This indicates if the control will be initially enabled when the form is opened with the Form command.
Font
This indicates the font for the control.
FontSize
This indicates the font size for the control.
FontStyle
This indicates the default font style for the control.
ScrollBar
This indicates whether textbox control has a scrollbar.
Read Only
This indicates whether textbox control is set to read only.
Frame
This indicates whether there is a frame displayed around the control.
GroupID
This number indicates what group a radio button is in.
MultiSel.
This specifies whether single or multiple items can be selected in a listbox.
Min. Value
This number indicates the minimum value for a scrollbar.
Max. Value
This number indicates the maximum value for a scrollbar.
PgUpDn
This number indicates the amount the scrollbar will move if the user selects in the region between the arrow buttons and the 'thumb' of the scrollbar.
ForeColor
This is used to specify the foreground color of the control.
BackColor
This is used to specify the background color of the control.
You will use editor windows when you double-click on the content of forms and edit source modules.
The editor allows you to view and edit Sub and Function procedures individually. You can select or create a new procedure from the droplist box at the top of the editor window.
Special Keys for Editing
Arrow Keys Move cursor within the editor
Shift Arrow Keys Moves & highlights cursor within the editor
Home Go to beginning of the current line
End Go to end of the current line
PageUp Go to previous screen of text
PageDown Go to next screen of text
Command C - Copy selected text
Command X - Cut selected text
Command V - Paste text at current cursor location
Command A - Select all text within editor
Command F - Find text
Command C - Find again
Command = - Find & Replace text
Command L - Find & Replace text again
Note: Command C for example means press and hold the command key ( the key with the cloverleaf symbol) and press C key.
Using Editor Window with a Form
To bring up the editor window:
• Double-click on form's control. This will open the form's editor window with that control's event procedure in view.
• Double-click on the area of the form not occupied by a control. This will open the form's editor window with the first procedure, of that form, (alphabetically) in view.
• Double-clicking with the Shift or Command held down on the area of the form not occupied by a control. This will open the form's editor window with the form's event procedure in view.
• Single-clicking on the View Code button in the Properties window. This will open the form's editor window with the first procedure (alphabetically) in view.
Using Editor Window with a Module
To edit the contents of a source module, just select the desired module from the project's menu.
Creating a New Sub procedure
Select the first item in the editor's droplist titled Create Sub Procedure. The framework of a new Sub procedure will appear in the editor window.
If you decide that you do not want this new Sub procedure then:
• Select all the text with the mouse or the A key command.
• Press the delete key
Creating a new Function procedure
Select the second item in the editor's droplist titled Create Function Procedure. The framework of a new Function procedure will appear in the editor window.
If you decide that you do not want this new Function procedure then:
• Select all the text with the mouse or with the Command & A keys.
• Press the delete key
Deleting a current Sub or Function procedure
• Select all the text with the mouse or with the Command & A keys.
• Press the delete key
Now if you click on the editor's droplist the procedure will be gone.
Converting from Visual MacStandardBasic 3 to
Visual MacStandardBasic 4.0
Visual MacStandardBasic 4 will automatically upgrade Visual MacStandard
projects.
Converting from MacStandardBasic 2 to Visual MacStandardBasic 4.0
MacStandardBasic 2 projects files are in completely different format than Visual MacStandardBasic project files. You cannot use them directly but the following directions to use the project's files with Visual MacStandardBasic:
1) In MacStandardBasic 2, each source code file can have multiple Global modules. You need to combine these into one Global module per source file.
2) Be sure that your MacStandardBasic source code files compile under MacStandardBasic 2 without error.
3) In Visual MacStandardBasic create a new project. Close Form1 without saving it.
4) Use the Add File option in the File menu to add all the source code and resource files to the new project. All of the source code files will be listed as under Modules in the project's menu.
You should be able recompile and run your application.