UserGuide

Difference between revisions of "Moving To API 2.0"

From Xojo Documentation

(Created page with "N/A")
 
Line 1: Line 1:
N/A
+
Moving to API 2.0
 +
 
 +
When you create applications with Xojo, you use the Xojo framework. This consists of classes and modules that provide things like windows, access to files, and more. When you use things like FolderItem and MsgBox, you’re using the APIs that make up the Xojo framework.
 +
 
 +
API 2.0 is our effort to make the way in which you write code easier and faster by replacing existing APIs with ones that are more intuitive and consistent. This document will provide an overview of API 2.0 and explain how you can move to it when you are ready.
 +
 
 +
== Overview ==
 +
 
 +
Creating Variables - The DIM keyword is short for “dimension” and is left over from the original BASIC language of the 1960’s. While you may have become accustomed to it, it’s not intuitive so we have replaced it with Var which is short for Variable.
 +
 
 +
Events - When writing code to respond to events, it’s important to know when the event will occur relative to the execution of your code. For your code to work properly, you need to know if the event already happened, is it currently happening or will it happen after your code executes. Events in Xojo now include tense to make this more obvious. For example, the Open event is now called Opening. For a window, this indicates that the window is in the process of opening but is not yet open when your code executes.
 +
 
 +
Adding/Removing Rows - Working with lists of data is now completely consistent. Adding rows to arrays, a ListBox, PopupMenu, ComboBox and more is done with the AddRow method. Removing rows is done with RemoveRow or to remove all rows, the aptly named RemoveAllRows method.
 +
 
 +
Working with Indexes - All indexes are now 0-based. Methods ending with the word “At” signify that the first parameter will be an index. For example, AddRowAt indicates a row will be added at the index you provide. RemoveRowAt removes a row at the supplied index. The index will always be the first parameter.
 +
 
 +
Data Looping - This is a very common operation. The easiest way to do this is with an iterator which passes through a list of data without requiring you to keep track of the index to access the current item. For example, when looping through an array, you must make sure to remember to start at 0 and then continue to the last row of the array. Such a loop might look like this example:
 +
<rbcode>
 +
For i = 0 To students.Ubound
 +
  If students(i) = "Sally" Then SallyCount = SallyCount + 1
 +
Next
 +
</rbcode>
 +
With an iterator, it’s assumed you will be looping through the entire array and you create a variable to access each row:
 +
<rbcode>
 +
For Each name As String In students
 +
  If name  = "Sally" Then SallyCount = SallyCount + 1
 +
Next
 +
<rbcode>
 +
The following classes or properties now support iterating:
 +
* Dictionary
 +
* Arrays
 +
* RowSet
 +
* URLConnection.ResponseHeaders
 +
* OpenFileDialog.SelectedFiles
 +
 
 +
The ability to iterate through lists will be added to more of the framework in future releases.
 +
 
 +
Avoiding Literal Mistakes - Often when writing code you must deal with numbers that are returned by functions where each possible value has a different meaning. This can result in code that is difficult to read as the purpose of the magic value is not immediately obvious. Enumerations solve this problem by providing an obvious and meaningful keyword that replaces the magic value.
 +
 
 +
For example, in previous versions of Xojo when setting the text alignment of a TextField, you might have previously written the code to center-align the text like this:
 +
<rbcode>
 +
TextField1.Alignment = 2
 +
</rbcode>
 +
It’s not obvious what 2 means in this case. The replacement for TextField.Alignment is TextAlignment. This property is an enumeration. As a result, using the enumeration is required making the code more readable:
 +
<rbcode>
 +
TextField1.TextAlignment = TextField.TextAlignments.Center
 +
</rbcode>
 +
It’s now absolutely clear what the code is going to do. Also because the old Alignment property is an integer, should you have chosen to use a literal value (2 for example), a typo (typing 22 by mistake) would not be caught by the Xojo compiler or by any kind of error when you app runs. Enumerations solve this problem because the only way to assign values is via the enumeration itself.
 +
 
 +
Enumerations are also easy to auto-complete as in almost all cases, the name of the enumeration is the plural form of the name of the property with which it’s associated. For example the property TextAlignmment is an enumeration of type TextAlignments.
 +
 
 +
Handling Errors - In the past, many functions in Xojo returned error codes when a function could not succeed. While errors are usually the exception not the rule, good software design dictates that your code be prepared for this possibility. Take this example (written how you would write it prior to API 2.0) that connects to a database to find a record, updates it and then returns the shipping status:
 +
<rbcode>
 +
If db.connect Then
 +
  Dim rs As RecordSet
 +
  rs = db.SQLSelect("SELECT ShipStatus WHERE TrackingNumber = " + TrackingNumber)
 +
  rs.edit
 +
  If db.Error Then
 +
    MsgBox("The record cannot be updated due to an error.")
 +
  Else
 +
    Dim today As New Date
 +
    rs.Field("LastChecked").StringValue = Today.SQLDate
 +
    rs.Update
 +
  End If
 +
  Return rs.Field("ShipStatus").StringValue
 +
  rs.close
 +
Else
 +
  MsgBox("Database Error: " + db.ErrorMessage)
 +
End If
 +
</rbcode>
 +
Notice the IF statements required to do the error checking. With API 2.0, nearly all error checking is handled with exceptions. This makes cleans up the code nicely and puts all the error checking in on place.
 +
<rbcode>
 +
Try
 +
  db.connect
 +
  Var rs As RowSet
 +
  rs = db.SQLSelect("SELECT ShipStatus WHERE TrackingNumber = " + TrackingNumber)
 +
  rs.EditRow
 +
  rs.Column("LastChecked").StringValue = DateTime.Now.ToString
 +
  rs.SaveRow
 +
  Return rs.Column("ShipStatus").StringValue
 +
  rs.close
 +
Catch error As DatabaseException
 +
  MessageBox("Database Error: " + error.Message)
 +
End Try
 +
</rbcode>
 +
Threads for updating your UI
 +
 
 +
Improvements Under The Hood - folderitem re-write, URLConnection, SelectSQL supports Prepared Statements without requiring you to use the PreparedStatement classes.
 +
 
 +
Transitioning
 +
 
 +
Auto-Complete
 +
 
 +
Replacing Events
 +
 
 +
Analyze Project
 +
 
 +
 
 +
Once you transition, there’s no going back so make sure you are ready - if your app runs well on r2, there’s not likely to be any reason to go back.

Revision as of 20:38, 19 September 2019

Moving to API 2.0

When you create applications with Xojo, you use the Xojo framework. This consists of classes and modules that provide things like windows, access to files, and more. When you use things like FolderItem and MsgBox, you’re using the APIs that make up the Xojo framework.

API 2.0 is our effort to make the way in which you write code easier and faster by replacing existing APIs with ones that are more intuitive and consistent. This document will provide an overview of API 2.0 and explain how you can move to it when you are ready.

Overview

Creating Variables - The DIM keyword is short for “dimension” and is left over from the original BASIC language of the 1960’s. While you may have become accustomed to it, it’s not intuitive so we have replaced it with Var which is short for Variable.

Events - When writing code to respond to events, it’s important to know when the event will occur relative to the execution of your code. For your code to work properly, you need to know if the event already happened, is it currently happening or will it happen after your code executes. Events in Xojo now include tense to make this more obvious. For example, the Open event is now called Opening. For a window, this indicates that the window is in the process of opening but is not yet open when your code executes.

Adding/Removing Rows - Working with lists of data is now completely consistent. Adding rows to arrays, a ListBox, PopupMenu, ComboBox and more is done with the AddRow method. Removing rows is done with RemoveRow or to remove all rows, the aptly named RemoveAllRows method.

Working with Indexes - All indexes are now 0-based. Methods ending with the word “At” signify that the first parameter will be an index. For example, AddRowAt indicates a row will be added at the index you provide. RemoveRowAt removes a row at the supplied index. The index will always be the first parameter.

Data Looping - This is a very common operation. The easiest way to do this is with an iterator which passes through a list of data without requiring you to keep track of the index to access the current item. For example, when looping through an array, you must make sure to remember to start at 0 and then continue to the last row of the array. Such a loop might look like this example:

For i = 0 To students.Ubound
If students(i) = "Sally" Then SallyCount = SallyCount + 1
Next

With an iterator, it’s assumed you will be looping through the entire array and you create a variable to access each row:

For Each name As String In students
If name = "Sally" Then SallyCount = SallyCount + 1
Next
<rbcode>
The following classes or properties now support iterating:
* Dictionary
* Arrays
* RowSet
* URLConnection.ResponseHeaders
* OpenFileDialog.SelectedFiles

The ability to iterate through lists will be added to more of the framework in future releases.

Avoiding Literal Mistakes - Often when writing code you must deal with numbers that are returned by functions where each possible value has a different meaning. This can result in code that is difficult to read as the purpose of the magic value is not immediately obvious. Enumerations solve this problem by providing an obvious and meaningful keyword that replaces the magic value.

For example, in previous versions of Xojo when setting the text alignment of a TextField, you might have previously written the code to center-align the text like this:
<rbcode>
TextField1.Alignment = 2

It’s not obvious what 2 means in this case. The replacement for TextField.Alignment is TextAlignment. This property is an enumeration. As a result, using the enumeration is required making the code more readable:

TextField1.TextAlignment = TextField.TextAlignments.Center

It’s now absolutely clear what the code is going to do. Also because the old Alignment property is an integer, should you have chosen to use a literal value (2 for example), a typo (typing 22 by mistake) would not be caught by the Xojo compiler or by any kind of error when you app runs. Enumerations solve this problem because the only way to assign values is via the enumeration itself.

Enumerations are also easy to auto-complete as in almost all cases, the name of the enumeration is the plural form of the name of the property with which it’s associated. For example the property TextAlignmment is an enumeration of type TextAlignments.

Handling Errors - In the past, many functions in Xojo returned error codes when a function could not succeed. While errors are usually the exception not the rule, good software design dictates that your code be prepared for this possibility. Take this example (written how you would write it prior to API 2.0) that connects to a database to find a record, updates it and then returns the shipping status:

If db.connect Then
Dim rs As RecordSet
rs = db.SQLSelect("SELECT ShipStatus WHERE TrackingNumber = " + TrackingNumber)
rs.edit
If db.Error Then
MsgBox("The record cannot be updated due to an error.")
Else
Dim today As New Date
rs.Field("LastChecked").StringValue = Today.SQLDate
rs.Update
End If
Return rs.Field("ShipStatus").StringValue
rs.close
Else
MsgBox("Database Error: " + db.ErrorMessage)
End If

Notice the IF statements required to do the error checking. With API 2.0, nearly all error checking is handled with exceptions. This makes cleans up the code nicely and puts all the error checking in on place.

Try
db.connect
Var rs As RowSet
rs = db.SQLSelect("SELECT ShipStatus WHERE TrackingNumber = " + TrackingNumber)
rs.EditRow
rs.Column("LastChecked").StringValue = DateTime.Now.ToString
rs.SaveRow
Return rs.Column("ShipStatus").StringValue
rs.close
Catch error As DatabaseException
MessageBox("Database Error: " + error.Message)
End Try

Threads for updating your UI

Improvements Under The Hood - folderitem re-write, URLConnection, SelectSQL supports Prepared Statements without requiring you to use the PreparedStatement classes.

Transitioning

Auto-Complete

Replacing Events

Analyze Project


Once you transition, there’s no going back so make sure you are ready - if your app runs well on r2, there’s not likely to be any reason to go back.