• Structures
• ByRef parameters
• Operator_Lookup
• Operator_Convert

Structures

Structures are a fixed-size data structure that can contain properties of simple types, such as Integer, String or Boolean.

Normally you would only use Structures with Declare API calls, but they can also work as a lightweight, project item specific data structure.

For Android, Structures are not fixed-sized data structures and are not appropriate for Declares, but they offer slightly more flexibility, especially with regard to Strings. When you add a String to an Android Structure, the specified size is ignored; you can store any size string in the property.

Usage is the same. Create a Structure in the Structure editor for the project item, adding the properties you want.

Note that the Offset and Size columns are not relevant in Android since the Structure is not fixed-size.

In code, you create a structure by name:

Var st As StructTest
st.Age = 42
st.Dead = True
st.Name = "Bob Roberts"
st.Weight = 200.6

Since Android Structures are not size-based, the ByteValue, Size and StringValue members are not useful and will raise an UnsupportedOperationException when used.

ByRef Parameters

ByRef parameters allow you to pass a parameter “by reference” so that the caller can access its new value if it was changed. By default, parameters are passed ByVal (or “by value”) so that the caller does not see any changes made to them in the method.

Use the ByRef keyword in front of the parameter to make it ByRef.

The ByRef page in the docs has more information.

Operator_Lookup

Operator_Lookup might be unique to Xojo. When you add an Operator_Lookup method to a class, it essentially tells the compiler to not do a syntax check on method or property names. Instead, if the name that follows the “.” is not an actual member of the class, then the name is passed as a string parameter to the Operator_Convert method.

You can do some strange things with Operator_Lookup, including making your code much more difficult to debug. Use this advanced feature wisely.

Learn more about Operator_Lookup in the docs.

Operator_Convert

Operator_Convert is used with classes to allow them to either construct a new instance from a value of a different type or to allow them to return a version of itself that is compatible with the destination type.

Here is an example of a Person class that uses Operator_Lookup. The Person class has a property: FullName As String. This is how you might normally create an instance and assign a value to FullName:

// Person is a class with a property FullName As String
Var p1 As New Person
p1.FullName = "Bob Roberts"

Now add an Operator_Convert method to the class like this:

Sub Operator_Convert(name As String)
  Self.FullName = name
End Sub

With that method, you can now assign a string value to a Person variable and it will create an instance and assign the string value to the FullName property. The syntax looks like this:

Var p As Person
p = "Bob Roberts"

You can also add an Operator_Convert method that returns a representation of a class instance as a different type. For example, say you wanted a Person instance to be able to convert itself to a string. First you have to decide what the string would be and in this case it makes sense to use FullName.

Here is that Operator_Convert for Person:

Function Operator_Convert As String
  Return Self.FullName
End Function

This code then assigns a Person instance to a Label’s text property where it gets assigned what is in the FullName property:

Var p2 As New Person
p2.FullName = "Janet Jane"
Label1.Text = p2

Like with Operator_Lookup, Operator_Convert is an advanced feature. Use it carefully. It certainly allows for some code to be simplified, but it also means that code might not be as clear as it would if it used more standard syntax.

Paul learned to program in BASIC at age 13 and has programmed in more languages than he remembers, with Xojo being an obvious favorite. When not working on Xojo, you can find him talking about retrocomputing at Goto 10 and on Mastodon @lefebvre@hachyderm.io.

• Facebook
• X
• LinkedIn
• GitHub
• YouTube

When MyMethod is written as:

Sub MyMethod( i() as integer )
  i = array(10,20,30)
  system.debuglog CurrentMethodName + " i(0) = " + str(i(0)) + " i(1) = " + str(i(1)) + " i(2) = " + str(i(2))
End Sub

What happens if instead of trying to assign a new array you just alter the values in the array passed in?

They are asking what happens if MyMethod is written as follows:

Sub MyMethod( i() as integer )
  i(0) = 10
  i(1) = 20
  i(2) = 30
  system.debuglog CurrentMethodName + " i(0) = " + str(i(0)) + " i(1) = " + str(i(1)) + " i(2) = " + str(i(2))
End Sub

Are the contents of the array altered when you get back to the calling method?
To test this, in a new desktop project we have:

Dim i() As Integer
i = Array(1,2,3)
System.debuglog CurrentMethodName + " i(0) = " + Str(i(0)) + " i(1) = " + Str(i(1)) + " i(2) = " + Str(i(2))
MyMethod(i)
System.debuglog CurrentMethodName + " i(0) = " + Str(i(0)) + " i(1) = " + Str(i(1)) + " i(2) = " + Str(i(2))

and run this code we see something like:

9:46:13 AM : My Application Launched
             Window1.Open i(0) = 1 i(1) = 2 i(2) = 3
             Window1.MyMethod i(0) = 10 i(1) = 20 i(2) = 30
             Window1.Open i(0) = 10 i(1) = 20 i(2) = 30

And indeed the values changed do remain when we get back to the caller. Why is this the case? We didn’t use ByRef and still could alter the array?

Recall that ByRef is needed when you want to change the instance referred to. And in this case that isn’t what we’re doing. We’re altering the contents, but not the instance itself. We’re not replacing the entire array with a new one.

This works with classes as well. If you pass an instance in you can alter that instance’ properties based on normal scope rules.

The moral of the story – ByRef is used when you want to alter the actual item. When its a value type like an integer this alters the value it holds. When its a reference type this would allow you to assign a new instance.

If you have code like:

dim i as integer = 1
system.debuglog "Before call i = " + str(i)
call MyMethod(i)
system.debuglog "After call i = " + str(i)

and MyMethod is written as

Sub MyMethod( i as integer ) 
  i = i + 1

  system.debuglog CurrentMethodName + " i = " + str(i)
End Sub

When you run this code you would see

Before call i = 1
MyMethod i = 2
After call i = 1

Following along, before the call i is set to 1. Then the call is made and because i as not passed ByRef, it is passed by value (ByVal), a copy of the value is sent to MyMethod in a temporary variable also named i – but this a copy not an original.

The method is run, i is altered to be 2 and the message “MyMethod i = 2” printed to the log. Then the method ends, the temporary variable is disposed of and the main code still has the original copy of i so the last message printed showing i is unchanged. To preserve the method’s change back in the caller you need to make the parameter be ByRef and then the actual variable is passed instead of a new temporary being created.

Now let’s apply this same sequence to a reference type like an array:

dim i() as integer = Array(1, 2, 3)
system.debuglog "Before call i(0) = " + str(i(0)) + " i(1) = " + str(i(1)) + " i(2) = " + str(i(2))
call MyMethod(i)
system.debuglog "After call i(0) = " + str(i(0)) + " i(1) = " + str(i(1)) + " i(2) = " + str(i(2))

and MyMethod is written as

Sub MyMethod( i() as integer ) 
  i = array(10,20,30)
  system.debuglog CurrentMethodName + " i(0) = " + str(i(0)) + " i(1) = " + str(i(1)) + " i(2) = " + str(i(2))
End Sub

With a reference type (see my earlier post What Kind of Variable Are You if you need any help with that) what we are altering is the contents that are referred to – but not the specific instance that is referred to. So running the code you see this output:

Before call i(0) = 1 i(1) = 2 i(2) = 3
Window1.MyMethod i(0) = 10 i(1) = 20 i(2) = 30
After call i(0) = 1 i(1) = 2 i(2) = 3

So just like with the previous integer example, the reference is not permanently altered despite the effort to do so. Again, in order to change what the parameter refers to you must use ByRef.

If MyMethod were written as such you would be altering the reference that the caller refers to.

Sub MyMethod(byref i() as integer )
  i = array(10, 20, 30)
  system.debuglog CurrentMethodName + " i(0) = " + str(i(0)) + " i(1) = " + str(i(1)) + " i(2) = " + str(i(2))
End Sub

Which is not the same as a reference type. The output of the above method is this:

Before call i(0) = 1 i(1) = 2 i(2) = 3
Window1.MyMethod i(0) = 10 i(1) = 20 i(2) = 30
After call i(0) = 10 i(1) = 20 i(2) = 30