Specification of Arguments in Documentation

[PhilipBrown]

Bob Paehr has raised many interesting questions as he diligently proofs the new Basic4Android book, one of which is why does the documentation specify parameters such as android.graphics.Path in the following

ClipPath (Path1 As android.graphics.Path)

(this comes from http://www.b4x.com/android/help/drawing.html#canvas_clippath)

It is impossible to specify a variable as android.graphics.Path. The only type available is Path, so why bother to specify the android.graphics part? Is there a purpose or does it simply confuse the user?

If there is no benefit in specifying this full path then I propose to shorten all types in the book to their simplest form.

Any comments?

 

[barx]

the path object type is imported from the Android. graphics sdk module. I. e. a path specific for the Android framework. things like string and Int are common to all dialects of java. I have probably used some wrong terminology but you should get the idea.

 

[Erel]

This is indeed a bit confusing however there is a technical reason behind it.

Take for example Bitmap.Initialize2:

It expects a java.io.InputStream object. In most cases you will use the standard (b4a) InputStream object.

B4A InputStream is a wrapper object:

@ShortName("InputStream")
   public static class InputStreamWrapper extends AbsObjectWrapper<java.io.InputStream> {

Being a wrapper means that the compiler can treat it as InputStreamWrapper or java.io.InputStream based on the requirements.


Bitmap.Initialize2 will work with any java.io.InputStream. If tomorrow someone will create a library that returns a subclass of java.io.InputStream then it will also work correctly.

The same is true for Activity.AddView(android.view.View, ...). It will work with any Java view.

 

[PhilipBrown]

Ok, I think that for most developers this knowledge is not necessary, so within the book I will cut the arguments down to their minimum, and the following note will be added near the front of the book:

Specifying Functional Arguments
When we specify the types of the arguments which are used to call functions, we adopt a different convention than that used in the Basic4Android on-line documentation. On-line they include the full path to the argument types, for example:
DrawBitmap (Bitmap1 As android.graphics.Bitmap, SrcRect As android.graphics.Rect, DestRect As android.graphics.Rect)
We find this confusing, so in this book we simply write:
DrawBitmap (Bitmap1 As Bitmap, SrcRect As Rect, DestRect As Rect)

The reason that the full paths are specified on-line is that Basic4Android types such as Bitmap are actually “wrappers” for the full Java class. This allows for greater flexibility in extending the Basic4Android language in future. But in most cases you do not need to worry about this when developing your apps.