Chapter 3

Object (Property, Event, or Method)

All of the graphical objects that are used in OmniBasic are implemented in a format that allows the maximum flexibility in user programming. Everything that is displayed upon the screen is an Object. The program has a few rules that must be obeyed in order to properly use objects. Objects cannot be used directly in conditional statements such as If or Case Statements. An object property value must be moved to a variable and then the variable used within the conditional statement. Each individual object has properties and events associated with it. Some Objects also have methods attached to them and we will review them last.

Objects that are available off of the IDE object dispenser are:

Different objects have different properties. The following is a list of general-purpose properties as an overview of the choices available. Individual objects use these properties and others. Check the individual Object description for a list of valid and available properties:

Different objects have an assortment of events that can be triggered. Graphical programs tend to be event-driven by nature since you manipulate the objects on the screen to cause the program to react. Different Objects have different characteristics and will require different events. Below is a list of possible events that can be triggered:

A few objects have Methods. Methods are essentially single word actions that directly operate upon the object. The methods available in OmniBasic are:

Property Descriptions

BackColor and TextColor=Integer

The BackColor and the TextColor Property can be a decimal or hexadecimal number that represents the color of the background of the object or the Text on the object. The color is easier to explain in hexadecimal. In Hex the color is represented by 3 groups of two characters such as Button1.BackColor = $FF00C0 The left most pair represented by FF in this example drive the Blue Color. FF being the maximum (255 Decimal) level of Blue and 00 being the minimum, The middle pair represented by 00 is the Green Color and the right pair represented by the C0 (192 Decimal) is the Red Color. This same color in decimal is 16711872, which isn’t nearly as easy to decode. The BackColor can be set via a variable that is dimensioned as a long. When using the IDE you have access to the Color Dialog Box, which allows you to see the color as you select it.

All displayed objects have the BackColor Property while only objects with text have the TextColor Property.

Under program control you can invoke the Color Dialog Box as shown below:

COLORDIALOG TempInt
IF OBDialogFlag=TRUE THEN
             Button1.BACKCOLOR=OBDialogCode
ENDIF

You can send the variable TempInt into the Dialog Box to setup the starting color in the dialog box. If the Accept button is pressed on the dialog box then the OBDialogFlag will be True and the Color Number will be available in the OBDialogCode.

Another method option is to set or read the Backcolor or Textcolor by passing it a number or a constant.

Button1.BackColor=B
B=Button1BackColor

Font=String, Integer (or) Font=FontObject (or) Font

The Font Property can be used with four different programming techniques. Within the program the easiest way to deal with fonts is to use the font dialog box to select a font and then take those results and drop them into the object. The following Code example will accomplish this task:

FONTDIALOG
IF OBDialogFlag = TRUE THEN
   Button1.Font
ENDIF

When the FontDialog Statement is executed the FontDialog Box pops up for the user to access the available fonts on the system. If the user then presses Accept on the FontDialogBox then the OBDialogFlag will be set to true and the Font will then be set in the button1 by using Button1.Font

The special variables reflecting the contents of the font descriptor are:

OBFontName      STRING
OBFontSize         LONG
OBFontWeight     LONG
OBFontSlant        LONG
OBFontEncoding  LONG
OBFontWidth      LONG
OBFontFlags       LONG

The second technique of programming the object font is to CONSTRUCT a Font Object and then using that font object to set the font of another object. It may sound confusing, but this technique can be used to set-up an initial default font for your program. An example:

construct font1 as font with "old english text mt",12
Button1.Font = font1

The third technique of using the font property is to give it a string variable font name and an integer font size. For example:

Button1.Font = “old english text mt”,12

Or if you had declared as a dimensioned string variable A and as a long variable B:

A = “old english text mt”
B = 12
Button1.Font=A,B

The last technique is to use the IDE to set your default font by invoking the Font Dialog Box and using it to select the fonts that you want each object on the form window to use. If you do not select a font with the Font Dialog Box in the IDE then the program defaults to the system font.

Text, ToolTipText = String

The Text and ToolTipText property are the easiest ones to deal with. Objects that can display alphanumeric characters such as Buttons, Labels, TextFields, Text, ComboBox and ListBox use the Text property. Only Buttons have available the ToolTipText property. When you place the cursor over the button the ToolTipText will appear in a floating window. Both properties are used in the same way. The Text property is looking for a string or a string variable. You can place a string variable into a Text property and you can extract a string variable from a text property.

Button1.Text = “Hello World”

In the above example we set the Button1 Text to the literal string Hello World. In the below example, we read the current text that is on Button1 into a string variable.

A = Button1.Text

And now we set the text on button one equal to the string variable A.

Button1.Text = A

Sometimes the programmer will want to set a numeric value in a text field and/or read a numeric value out of a Text property. In order to do this you must convert between numbers and strings. For example, if you want to take an integer or a floating-point number and place it into a Text property you will convert the number into a string. In the following example A is a String Variable and B is a long integer variable.

A = STR$(B)
Button1.Text = A

If you want to extract a numerical value out of a Text property then reverse the process. If the number is a floating-point number then we dimensioned C as a Float and then take the floating-point value of the A string.

A=Button1.Text
C=FVAL(A)

If the number is an Integer then we will drop the value into B, which we dimensioned as a long integer.

A=Button1.Text
B=VAL(A)

ToolTipText uses the same programming format as the Text property.

Button1.ToolTipText = “Hello World”
A=Button1.ToolTipText

Value = Integer

The Value property is a numeric property that expresses the numeric value that the object is displaying. Objects that use the Value property are: ProgressBar, Slider, Dial, Spinner. These objects are used to display or allow the user to enter or read an integer numeric value.

To read a Value off of a Spinner:
     B=Spinner1.Value
To write a Value to a Spinner:
     Spinner1.Value=B

Range = Integer, Integer

The Range property has two arguments. The first is the minimum allowable value for the object and the second is for the maximum allowable value for the object. Objects that have the Value property also have the Range property.

To set a range for a Slider:
     Slider1.Range=0,100
The Range property is a “write only” property.

Size = Integer, Integer
Width=Integer
Height=Integer

The Size property has two arguments while the Width and Height properties only have one. The first property of Size is the Width of the object and the second property of Size is the Height of the object. These properties are used to change the dimensions of the object and are expressed in pixels.

Size is a “write only” property whereas Width and Height are “read and write” properties. All of the displayable objects have Size, Width and Height. To change the size of a TextField:

TextField1.Size=100,30

Or alternatively:

TextField1.Width=100
TextField1.Height=30

To read back the current Size of a TextField you only have one technique available, to read the value into an integer variable:

W=TextField1.Width
H=TextField1.Height

Position=Integer, Integer
X=Integer
Y=Integer

The Position property is a “write only” property with two arguments and the X and Y properties are “read and write” with single arguments. The Position of an object is expressed in pixels and the 0,0 reference is in the upper left corner of the form window. Button1.Position=100,200 would place the upper left corner of the Button object at 100 pixels down from the top of the form window and 200 pixels from the left side of the form window. The X or Y properties can be expressed in the following ways:

To set: Button1.X = 100 or to read: Variable1=Button1.X

Focus=Boolean

The Focus Property is used to Verify if an object has focus or it can be used to set focus onto an object. Focus is the term used to describe what object will be acted upon. For example, if a Button has focus, when you click on the button, it will cause an event based upon that action. If a TextField has focus then when you type on the keyboard, the characters will go into that TextField. To test for focus, dimension a Boolean variable such as Bull:

Bull=TextField1.Focus
If Bull = TRUE Then
   Rem Do Something
End If

To set the Focus on an object, do the following:

TextField1.Focus=TRUE

Enabled=Boolean

The Enabled property is used to turn on or off an object’s ability to be used or cause an event to occur. Typically the object will gray-out (unless of course the object is already gray) when Enable is False.

Visible=Boolean

Then Visible property is used to hide objects or show objects on the form window or the window itself.

Event Descriptions

An event is used to trigger a program event routine. An event routine has to have the line “Exit Event” at the end of the event. When an event is triggered then a program routine will be run. Typical events that are used are:

Click, DoubleClick

The Click event will be triggered when a user uses the left mouse button to “click” on the object. Use DoubleClick to require 2 clicks. For example, if we want to put the message “Hello World” into TextField1 when Button1 is clicked then we would create the following script in the Event Module:

Button1.click \ This line is the proper syntax for a click event on Button1
TextField1.Text = “Hello World” \ This line sticks Hello World into the TextField1
Exit Event \ This line shows the correct syntax for ending an Event routine.

Mouse1Up, Mouse1Down, Mouse2Up, Mouse2Down, Mouse3Up, Mouse3Down

The Mouse events are triggered by the mouse buttons. Mouse1 is the left mouse button, Mouse2 is the right mouse button and Mouse3 is the center mouse button. When you press down on the mouse button you will cause a mouse down event for that button. When you release that button you will trigger a mouse up event for that button. If you want to turn the color of Button1 blue when you press the left mouse button or green if you press the right mouse button then lets look at the following example:

Button1.Mouse1Down
Button1.BackColor=$ff0000 \ The color blue in hexadecimal
Exit Event

Button1.Mouse2Down
Button1.BackColor=$00ff00 \ The color green in hexadecimal
Exit Event

Hopefully you will find more useful uses for the MousexUp and MousexDown events.

MouseMove

The Mouse Move event is used in cases where you want to trigger an event if the mouse is moving over the object or form. A typical application of the MouseMove event is to move an object around the form. In the following example, The Button will move around the Form after you have clicked on it and then will stop moving around the form when you click on it a second time. The example program is called mousedown.obp:

This Program has 2 Objects on the form. A TextField named WatchWindow and a button named Button1.

In the Declaration Module we will declare a Boolean variable as the MoveItem Flag. Two long variables are used for holding the information on where the Form is relative to the upper left corner of the screen. A string variable will be declared to hold the information we want to put in our textfield.

In the Initialize Module, the MoveItem flag will be set to False and the Title line of our program will be set to “Mouse Down Test”. We will also set the Button1 text to read “Press to Move”.

The Construct Module will display the default settings for the items we have created on the Form. This program will not require any functions, so the Function Module will be empty.

The Event Module contains the bulk of our program. We have created two events. The Button1.Mouse1Down event will activate when the user of the program presses down on Button1. When that action occurs, the program will set the MoveItem Flag to True, turn the Button Green and Change the Text on the button to “Move Me!” If the MoveItem Flag was True, when the button is pressed, we set the flag to false, change the color to red, and change the button text to “Stick Me!” The second event is the OBMain.MouseMove event. The primary form that all OmniBasic programs start with is the OBMain Form. If you want to create additional windows you can name them whatever you want but the original window is always called OBMain. When the mouse is moved over the OBMain form, the program will grab the current position of the OBMain form and store it in Xpos and Ypos. Then Button1 will be moved based upon where the window is on the screen. The OBRootX and OBRootY special variables contain the cursor position on the screen. The Button position is based upon where it is in reference to the OBMain form. That is why we are taking the screen position minus the Form position in order to create a position on the form for the button. When the program Mousedown is running and you click on the button, then the button can be moved around the form until you click on the button again. You can then move the program window around the screen and when you move the button around again, the position information will update with the new position on the screen and in the window.

Resize

The Resize event is triggered when you change the size of a form. For example, if you created the following resize event: OBMain.Resize; then whenever you change the size of the OBMain form, it will trigger an event.

KeyUp, KeyDown

The KeyUp and KeyDown events are triggered by keyboard entry. When someone presses a key on the keyboard, and the object or form that has the keydown event has focus, then this event will be triggered. The Special variable OBCode traps the key code for the key that was pressed.

OBMain.Keydown
IF OBCode=$ff0d THEN\ Enter Key
                A=B+C
ENDIF
Exit Event

GotFocus, LostFocus

The Focus can trigger an event. When an object or a window first gets focus it can trigger a GotFocus event. When you put the focus on another object, then the object you were leaving can also have a LostFocus Event. If someone was typing into a textfield and then clicked on a button, you can have several events. A GotFocus event can be triggered when you go into the textfield, then a LostFocus event for the textfield can be generated a long with a GotFocus event for the button. In this case a LostFocus event could cause the data in the textfield to be transferred elsewhere.

Button1.GotFocus
Button1.Text = “We have Focus”
Exit Event

Button1.LostFocus
Button1.Text = “We don't have Focus”
Exit Event

Enter, Leave

When you move the cursor over an object, you can trigger an event when you enter the object and when you leave the object.

Button1.Enter
Button1.Text = “You have Entered”
Exit Event

Button1.Leave
Button1.Text=”You have Left”
Exit Event

Update

The Update event is useful to detect when a change has taken place on a Text Object. When a change occurs on a Text object, the Text.modified property flag is set and an update event occurs. In the following example, when someone changes the current text in a text object, the update event will trigger, causing a Boolean variable called Modified to be set to true and a SaveButton on the screen to be enabled, indicating that the text has changed and is currently not saved.

Text.update
TempBool=Text.modified
IF TempBool=True THEN
                Modified=TRUE
                SaveBUTTON.ENABLED=TRUE
ENDIF

Create

 The Create event occurs after an object or form has been created. It can be used to control the sequence of events that take place on the screen.

TimeOut

 The TimeOut event is used to work with Timer Objects. You start a Timer Object by setting the duration of the timer in milliseconds. A value of 1500, will time-out in 1.5 seconds.

Timer1.LENGTH=Interval

Then, when the timer times-out it will trigger the event.

Timer1.TimeOut
TextField1.Text=”TimeOut!”
Exit Event

You can cut short a Timer by using the Stop property of the Timer.

Timer1.Stop

No more timing will occur.

Change

The Change event is useful when a numeric value of an object such as spinner, slider, or dial is changed, or a text entry is changed on a textfield. When a user of the program changes the value on a spinner that triggers a Change event. In the following example, the event will be triggered when Spinner1 is changed, by adjusting its value on the screen.

Spinner1.Change \ This line is the proper syntax for a Change event on Spinner1
Rem Do some action here when someone changes the value of the spinner
Exit Event \ This line illustrates the correct syntax for ending an Event routine.

Close

The Close event is triggered when someone clicks on the ‘X’ in the upper left corner of the Form window of a program. It is useful for testing to make sure that the program is ready to close or to assure an orderly shutdown of your program.

OBMain.close
IF Modified=TRUE THEN
     MSGBOX QUESTION,"Edits Not Saved","Do You Want To Save Project?",YES_NO_CANCEL
     IF OBDialogCode=1 OR OBDialogCode=3 THEN
       Gosub SaveProject
     ENDIF
     IF OBDialogCode=4 THEN
       EXIT EVENT
    ENDIF
ENDIF

Methods

Methods are single word commands that are available to a few of the Objects. Some typical Methods are:

Clear

The Clear method is used to flush out the text stored in an object. Clear is used on most of the multi-line text based Objects such as ComboBox, ListBox and List. If you have a ComboBox that has three items in it and you want to reset it, use the Clear method.

ComboBox1.Clear / This will clear any values out of the ComboBox

Stop

The Timer object uses the Stop method. When a timer object is running, using the Stop method will stop the Timer. For example, TimerA is running and the user pressed Button1 to halt TimerA:

Button1.click
TimerA.Stop
Button1.Text=”Halted Timer”
Exit Event

Minimize

The MainWindow or the Form objects use the Minimize method. When the Minimize method is invoked, the MainWindow or the Form object will be dropped to a minimized condition as if the Minimize icon in the upper right of the window was pressed. This allows minimization via program control. This is not to be confused with hiding or closing a window. To minimize a Form when Button1 is pressed:

Button1.click
Form1.Minimize
Exit Event

Cut, Copy, Paste, SelectAll, Delete

The Text Object has built-in editing capability that uses methods to activate the editing functions. When the Cut method is executed then the selected text in the Text object will be placed into the system edit buffer. Copy will take an image of the selected text and place it into the edit buffer while leaving the original intact. Paste will take whatever is in the system edit buffer and place that in the cursor position or in place of whatever text is highlighted by the cursor. SelectAll will select every-thing in the Text object so that you can Cut, Copy or Delete it. Delete will take the highlighted text in the Text object and remove it from the text object. In this example, we will create four buttons to handle the methods:

CutButton.Click
  Text1.Cut
  Exit Event
CopyButton.Click
  Text1.Copy
  Exit Event
PasteButton.Click
  Text1.Paste
  Exit Event
DeleteButton.Click
  Text1.Delete
  Exit Event

Next Page Chapter 4
Table of Contents