Lies. Damned Lies. And Pragma Unused.

Lots of times we might like to clean up our code by making sure we fix all the errors AND all the warnings as well.

And one of those you might find you get warned about is unused parameters. These might come about from implementing some interface for a nice consistent API but some implementors of the methods on the interface dont use all the parameters.

You can go around and read each warning and selectively insert

#pragma unused <whatever one the compiler warned you about>

Or you can actually be lazy and lie to the compiler and kust copy and paste all the method parameters and put a #pragma unused for each parameter. The compiler wont give you a warning or error about having lied to it even if you DID use the parameters after you said it was unused.

For example if you wrote a method like

Sub foo( bar as integer, baz as integer)
   #pragma unused bar
   #pragma unused baz 

   dim i as inteher = bar + baz
End Sub

the compiler will happily accept this and not warn about bar or baz as being flagged as unused

Have fun !

The nature of the change

I’ve seen lots of discussions that talk about how certain bugs have been copied over from API 1.0 to API 2.0.

This is unlikely and mostly not correct. From what I can tell nothing was “copied” from one API to another.

Let me detail why I think this is the case with an analogy.

Suppose you had source code that you could compile into a dynamic library for macOS (a dylib), Windows (a DLL), or Linux (a .so). But in your Xojo application instead of having to write all the declares every time you wanted to call you dynamic library you created class, or module, that put a nice API on it that hid all those declares. A great example of this is something like macOSLib which hides a lot of the details of calling into macOS Cocoa API’s from you. Behind the nice Xojo API this presents are a lot of declares. But you dont have to deal with those. You just use the classes available.

Thats roughly analogous to API 1.0 – the classic API used from the days of REALbasic through to Xojo.

Now if you altered the Xojo code in all those methods and classes by renaming the properties and events in the Xojo API or added new ones, but did not alter the underlying declares, you would have a new, or modified, API. And if you brought all this code into existing projects you’d have to adapt all your existing code if you wanted to use this new API. But you would still retain all of the old bugs you had in the C++ code.

This is roughly whats happened with API 2.0

API 2.0 is a new API on top of much of the same framework that has existed for years. Hence there are old bugs still present along with new ones adding this new API has introduced.

Thats not to say the new API 2.0 work didnt alter any of the underlying code. There are some things like Folderitem which appears to have new more modern OS API’s in use on macOS (a very welcome thing) and a handful of other items.

But by and large API 2.0 sits on the same framework as API 1.0 did.

IsEventImplemented

In 2019r3 Xojo added something that a lot of people have been asking for for a very long time. A way for a class that exposes events to know IF an instance implements the event.

Its literally called IsEventImplemented (see http://feedback.xojo.com/case/58342)

But it remains undocumented

Previously if you wrote a class that could have some default behaviour IF an instance did not implemnent the event to alter the behaviour you had no way to know if you should operate in whatever way was the default or not.

You could never have your superclass do something like

If IsEventImplemented("Action") then
   // call the instance' code
   raiseEvent Action
else
   // do nothing
end if

In this case its not so bad and you could probably just use RaiseEvent without any impact. But if you wanted to do something more, like know if you should use a default color or not you had a much more difficult task

// if we had an event ChooseColor that instances could implement or not

defaultBackGroundColor = raiseEvent ChooseColor

// if setColor IS implemented we'd get a color 
// if setColor is NOT implemented we still get a color - its just all 0's
// and we have no way to know which is the case 

But now with IsEventImplemented we could know

// if we had an event ChooseColor that instances could implement or not

if IsEventImplemented("ChooseColor") then
   defaultBackGroundColor = raiseEvent ChooseColor
else
   defaultBackgroundColor = &cFF00FF // or whatever
end if

// now we can use defaultBackgroundColor knowing whether 
// it did or did not come from the instance

However, Xojo has chosen to not document this (see http://feedback.xojo.com/case/58868)

The comment almost makes it seem as if this method might disappear despite its usefulness whether API 2.0 event have or have not been reverted.

Use it carefully !

Fail early. Fail often. Fail loudly.

And by that no I don’t mean that YOU personally should fail. I’m of the same mind as my dad on that front. You should work your ass off to do the best job you know how to do. That doesn’t mean you’re perfect or that you expect perfection. There are lots of things in this world that I do not know how to do very well – but when given the opportunity I try to do the very best job I know how to and I try to learn how to do it better next time.

What I mean by the above is that your CODE should fail early often and loudly. I know some folks say “software should never fail” and thats a great goal to strive for but there are times and reasons why that is very close to impossible to prove without it being so ridiculously expensive that its just not practical for the vast majority of use cases.

And in those cases that you DO detect a failure, more than likely some exception, that you cannot handle or did not code for your code should bitch moan whine and grind to a halt immediately. Don’t try and recover from something you didn’t foresee. You may, by trying to recover from some unforeseen failure, actually cause more damage. If memory got corrupted and you try to recover you could wipe the hard drive or so something else much worse.

Personally I’m a fan of writing code in a way that it basically asserts preconditions at the beginning of the method and what inputs it expects. Some languages make this really easy to do – but you can do this in any language.

Range checks, format checks, nil checks and other checks as the first few lines of a method making sure things are the way your code expects make it easier to handle any issues that arise before you get far.

User inputs should be checked and sanitized at the point they are gathered. And if they are then your code should never get values for parameters that are unexpected (you did check ranges and such right ?????)

After that you code as defensively as you can and behave reasonably. But trying to recover from something that is a potentially fatal error (not just an out of bounds which you _should_ be able to handle in a reasonable fashion)

An unexpected runtime exception that is NOT one you anticipated SHOULD, IMHO, STOP your app right then and there and set things up in a way the end user CAN report it to you so you can fix it. It should not try to do anything else as you have NO assurance you CAN do anything else reasonable at that point.

Trying to continue on operation may well result in even more failures hat could do even more damage.

So write the best most well thought out code you can.

And when all the rest of the world and your environment is letting you down FAIL before you seriously break something else (like deleting a database or corrupting it)

And tell your user as much as you can WHY things failed.

And then fix it as correctly and quickly as you can

Rust

and other cruft starts to accumulate if you’re not careful. But thats not what this post is about.

Its literally about the programming language Rust.

It’s been quite some time since I’ve had to do a lot in C which is what Rust feels like. Full of curly braces and semicolons its VERY C like – and I’ll post about my adventures getting familiar with it and how I think it can be leveraged in a cross platform world.

It has some nice characteristics. It can compile for a wide range of targets from the get go. So far it looks like you can cross compile from macOS to Windows and vice versa (as well as many other targets) which is handy. And you can have Rustc compile exe’s, dylibs and several other types as well as its own custom types.

Looks darned fun.

Bit twiddling in a CSS age

Got a curious question the other day. One I had never really thought much about but after a discussion it became clear to me why the questions were the way they were.

Bit flipping and bit masking is not intuitive.

And unless you’ve had to do it then approaching it for the first time may no make a pile of sense.

For instance, if you have a look at the binary representation of a value in a Uint8, with code like

Dim i As UInt8 = 8
Dim s As String = Bin(i)

break

that 8, in binary, is 1000 (note I consider it a bug that any leading 0’s are not shown – they should be as the value 1000 is only 4 bits not all 8. Xojo’s Bin and ToBinary do not show it which is, incorrect, IMHO)

A Uint8 is 8 bits wide/ a Unit16 is 16 bits wide. A Uint32 is 32 bits wide. And any value stored in there uses ALL those bits either set to 0 or 1. So a 32 bit version of 8 should be

&b00000000000000000000000000001000

With this starting bit of info out of the way bit masking using the built in operators, AND, OR, NOT and XOR becomes somewhat simpler. Especially if you write things in binary using the &b notation although with really big values it becomes hard to read. This is often why you see people use HEX – or hexadecimal. It’s more compact. Octal is another form that is less often used.

If we start with our original value, 8 , as a Uint8 (or &b00001000) and want to test if certain bits are set then the AND operator is VERY useful.

In binary the LOW BIT, or bit 0, is the RIGHT MOST one – just like in decimal the ones is right most, tens next to that and so on.

So if we want to test if bit 3 is set in &b00001000 we can do

dim result as integer = 8 AND &b00001000
if result <> 0 then
  // tada ! bit 3 IS set !!!!
end if

The AND operator will take two bit patterns and match them up. Where there is a 1 in both operands, 8 and &b00001000, the result will have a 1. Since 8 is, in binary &b00001000 we get a result of &b00001000 – bit 3 is set in both 8 and so the result gets a 1 in that bit position.

     8 => &b00001000
AND       &b00001000
---------------------
          &b00001000

If we try a different value, 9, then we get results like

     9 => &b00001001
AND       &b00001000
---------------------
          &b00001000

Note the representation of 9 is basically “8 + 1”. Again when we apply the AND operator we get a result that is not 0. From that we know that in the two patterns some bits matched and gave us a result that was NOT all 0’s.

Other operators do slightly different things.

The OR operator will make sure that bits in the result are set to 1 if a bit is set to 1 in either operand. if we wanted to make sure that bit 3 WAS set then we could use OR

     8 => &b00001000       0 => &b00000000
OR        &b00001000    OR      &b00001000
---------------------   ------------------
result    &b00001000    result  &b00001000

In the left example above we started with the bit set. OR will not change it and so it remains set in the result. In the right hand example we start with the bit NOT set. OR makes sure it is set and the result has the bit set.

The NOT operator will flip all bits in the result. It only takes 1 operand. Any that are set to 1 will be flipped to be 0 in the result. Any that are 0 will be flipped to 1.

     8 => &b00001000       0 => &b00000000      170 => &b10101010
NOT                     NOT                    NOT
---------------------   ------------------     ------------------
result    &b11110111    result  &b11111111     result  &b01010101

In the left most example above we started with the bit set. NOT will change it and so is cleared result. But not also inverts all the other 0’s to 1’s as shown in the middle example. In the right hand example we start with the bit pattern for 170 (&b10101010). When we use NOT it flips every bit to the opposite.

XOR is the weirdest one. it full name is “exclusive or”. What that means it in its 2 input operands the result will be a 0 every where the inputs match. And a 1 everywhere they do not.

     8 => &b00001000        0 => &b00000000         170 => &b10101010
XOR       &b10101010    XOR      &b10101010     XOR        &b10101010
---------------------   -------------------     ---------------------
result    &b10100010    result   &b10101010     result     &b00000000

In the left most example you can see that we get 1’s in every spot where the second operand has a 1 and the first doesnt. But because bit 3 matches we get a 0 instead of a 1. The middle example shows that when one operand is all 0 you get a copy of the second operand. And in the right most we go no 1’s because all the spots in both match in every position and so we get all 0’s.

As I said writing these out for anything larger than an 8 bit value as binary is tedious and error prone. And so you often see hexadecimal used.

So how to determine the “right” hex to use ?

Again, EVERY integer is ALWAYS as the FULL width of whatever type you used. So always make sure you write things out in full.

We’ll start simple with an 8 bit value.

To convert &b10101010

  • write it in groups of 4 bits each(&b1010 1010)
  • each group of 4 bits is ONE hexadecimal “character”
  • the low bit position in the group of 4 is like the “ones” in decimal, the next like the tens and so on.
  • the lowest bit, if set, means a value of 1
  • the next bit, if set, means a value of 2
  • the next bit, if set, means a value of 4
  • the next bit. if set, means a value of 8

so in our case, &b1010, means, working from right to left, 0 + 2 + 0 + 8 or 10 * (You can check thins in Xojo code if you care to)

Now the screwy part. Our normal counting system is base 10. so whenever we get to 10 we start a new position to the left of the current one. In hexadecimal you count up to 16 – not 10. And so up to 9 things are the same but then for 10-15 we use the letters A to F (A = 10, B = 11, C = 12, D = 13, E = 14, F = 15) You convert each group of 4 bits exactly the same way.

So in hexadecimal our value is &hAA (= &b1010 1010) Again you can check this in code

if &hAA = &b10101010 then
  msgbox "Norm was right"
end if

Because hex is much more compact its widely used. And for large values its simpler to read and can be used just as effectively for bit masking. You just have to know how to convert you binary bit masks into hex.

*The number theory behind how decimal, binary, hexadecimal, octal and other counting systems works is really quite interesting. They’re all positional based systems and the difference is the base they use, not so much HOW they use the digits in the specific counting system. Heck we all use one every day that is base 60 and it seems perfectly normal whenever the minutes go by and turn into hours 😛

Where I’m starting to hang out most often

Lately I’d been hanging out on some alternative Xojo discussion venues.

The one I’m finding useful is IfNotNil as they permit discussions of ANY topics which lead to cross platform development. So you can talk about Rust, Go, B4X products, LiveCode, Web and other toolsets you might use for cross platform software development.

Using events as a way to pass information to instances

Most of the time when we talk about events the first thing that pops into someones head isa UI control and the events is has for interaction with the user. A pushbuttons Action (or Pressed) event for instance. Or the various events on listboxes for selecting rows, handling mouse clicks, keyboard events and the myriad of other user interface and interaction related things listboxes handle.

But thats not the only way to use events 🙂

Sometimes you may write a control and it needs to get data from the layout its on or from something else outside its control. So how do you get access to this ?

You could, as I’ve seen in some code, make everything PUBLIC and then the specific control just gets its parent control and grabs what ever property or calls whatever parent method it needs.

This is, IMHO, a bad practice as it makes your code more fragile since a change in the method or property you’re accessing this way could cause unrelated code to break. And because it destroys any encapsulation you might have created. Its a huge violation of the Law Of Demeter I wrote about before. You should only use things that are passed to you as parameters, that you own and control, or that are declared in your code. Reaching way outside to the parent control would definitely violate this principle.

So what can you do ?

As discussed before, subclasses CAN create NEW events and you could use an event to ask the containing layout for whatever property value or reference to something else the layout has access to.

We’ll create a small project to demonstrate the idea. What we will have is a custom canvas control that will ask the outside world for the color that it should draw itself as. You might normally do this as a simple property but I am NOT going do that to demonstrate. The other thing we will have on the layout is yet another custom canvas that acts simply as a color picker.

I’m using 2019r1.1 so some things may be different if your using a newer version

First start a new desktop project

Add a new subclass of Canvas by dragging the canvas control from the Library over to the Navigator (or you can add a new class and set its super to Canvas in the inspector). Name this new class ColorSelectorSwatch.

Add a public property called FillColor as Color

We’ll add the MouseUp event handler and put the following code in it

  Dim c As Color
  
  If SelectColor(c, "Select a color") Then
    Me.FillColor = c
    Me.Invalidate
    RaiseEvent Updated
  End If

Also add the Mouse Down event handler and put this code in it

  Return True

Also add a new Event Definition and name it Updated

Thats it for our little color selector swatch

Add an instance of our ColorselectorSwatch to the default layout, Window1, by dragging it from the Navigator on to the layout Window1. By default its name will be ColorSelectorSwatch1

Add the event handler for the new Updated event. We’re not going to put any code in it just yet. We’ll return to this later once we create our other custom control.

Now add another canvas subclass to your project. Again you can do this by dragging or by simply adding a class and changing the superclass in the inspector. Name this class CustomCanvas. This is the one we’re going to add the event to that will ask the outside world what color it should draw itself in.

Add the Event handler for the Paint event to the CustomCanvas.

Also add a new event definition colorToDrawWith() As color.

Note that this event handler has a return value that is a color. When we need to get the color we’ll raise this event, get whatever return value, and then paint our canvas with this color. *

The code for the Paint event is fairly simple

Dim c As Color

c = RaiseEvent ColorToDrawWith // call the event to get the color 
                               // from the outside world

g.ForeColor = c
g.FillRect 0,0, g.width, g.height

Drag an instance of this custom canvas onto the default window and make sure it does not overlap your other canvas. By default it will be named CustomCanvas1.

Now we’ll add the handler for the ColorToDrawWith event. All we need is one line

return ColorSelectorSwatch1.FillColor

Now return to the Updated event of ColorSelectorSwatch1. In there we need one line to make it so our CustomCanvas will know to redraw itself when the color selector swatch gets a new color selected. In the Updated event put

CustomCanvas1.Invalidate

And run. Every time you select a new color in the color swatch the other canvas will update and redraw itself. And, to do so we have used an event to return information to the control instance that tells it what color to draw with.

Here’s my completed sample

*Of note one of the things that got added in versions after 2019r1.1 is a way to tell IF the event is implemented. You could use this to know whether you should redraw with the color returned or not.

The only change would be to make the Paint event of CustomCanvas read as follows

If IsEventImplemented("ColorToDrawWith") Then
  Dim c As Color 
  
  c = RaiseEvent colorToDrawWith
  
  g.ForeColor = c
  g.FillRect 0,0, g.width, g.height
End If

Exercise caution with catch clauses

Xojo now generally uses exceptions to handle errors.

And with that comes some things you should know about how exceptions work that you need to be aware of before you cause yourself problems.

First off, in my opinion, you should put your try catch blocks as close to the code that causes the error. While Xojo lets you use one EXCEPTION or CATCH block at the end of any method like the following


// do a bunch of code 
// do a bunch of code 
// do a bunch of code 
// do a bunch of code 
// do a bunch of code 
// do a bunch of code 
// do a bunch of code 
// do a bunch of code 
// do a bunch of code 
// do a bunch of code 
// do a bunch of code 
// do a bunch of code 
// do a bunch of code 
// do a bunch of code 
// do a bunch of code 
// do a bunch of code 
// do a bunch of code 
// do a bunch of code 
// do a bunch of code 
// do a bunch of code 
// do a bunch of code 
// do a bunch of code 
// do a bunch of code 
// do a bunch of code 


Catch foo As RuntimeException // or Exception foo as RuntimeException
Break

I would suggest you avoid this form. It’s not obvious unless your methods are VERY short and it on one screen of code. For instance, does the following method have a catch ? Without actually looking at the very end you cannot tell (In fact it does but that isnt clear)

As well using a single consistent form is probably a better practice than sometimes using this form and sometimes using other forms. Even if the entire method is surrounded in a TRY CATCH block its more obvious. This is the exact same method with the addition of the TRY keyword at the very beginning and “END TRY” at the very end

try
  // do a bunch of code 
  // do a bunch of code 
  // do a bunch of code 
  // do a bunch of code 
  // do a bunch of code 
  // do a bunch of code 
  // do a bunch of code 
  // do a bunch of code 
  // do a bunch of code 
  // do a bunch of code 
  // do a bunch of code 
  // do a bunch of code 
  // do a bunch of code 
  // do a bunch of code 
  // do a bunch of code 
  // do a bunch of code 
  // do a bunch of code 
  // do a bunch of code 
  // do a bunch of code 
  // do a bunch of code 
  // do a bunch of code 
  // do a bunch of code 
  // do a bunch of code 
  // do a bunch of code 
  
  
Catch foo As RuntimeException 
    Break
End Try

The other thing to be careful about is how you write your catch statements. The documentation shows a legal CATCH statement as

Catch [[ErrorParameter] [As ErrorType]]

Note that EVERYTHING except the CATCH keyword is optional. Again I would suggest you almost NEVER use just a CATCH by itself as you will catch every type of exception, perhaps even those you cannot actually handle.

The other thing that is often confusing is if you write

Catch someException

which is legal what you have in fact got is

Catch someException as RuntimeException

and the local variable is name someException. Save yourself the grief and ALWAYS use the fully spelled out form of CATCH like

Catch <localVariableUsableInTheExceptionHandlingCode> as <ExceptionType>

Using it this way insures you are never surprised at catching more than you were prepared to handle. Also note that the localVariableUsableInTheExceptionHandlingCode is in fact defining a local variable that you can use in the body of this specific CATCH block. What that means is code like

Catch iox as IOException
   system.debuglog iox.errormessage

is legal and, in this case, iox is usable within the rest of the code following that catch until you get to another catch, the finally block, or the end try. The following WOULD NOT be legal

Catch iox as IOException
   system.debuglog iox.errormessage
Catch oob as OutOfBoundsException
   system.debuglog iox.errormessage

iox would not be in scope in the code following the catch of the out of bounds exception. Nor would oob be usable in the block handling the IOException.

And this last example shows something you can legally do. You can have more than one catch statement. The only thing you need to be careful about here is not catching the most general types before the more specific ones. What do I mean by that ?

Since all exceptions are descendants of RuntimeException they are more specific types of exceptions than RuntimeException is. If your code was like

Try
  Raise New nilobjectexception
  
Catch rte As RuntimeException
  Break
Catch noe As NilObjectException
  Break
End Try

you would find that any code following the catch of the NilObjectException would NOT get executed. Because NilObjectException is descended from RuntimeException the first catch block will handle EVERY exception. Changing this code to

Try
  Raise New nilobjectexception
  
Catch noe As NilObjectException
  Break
Catch rte As RuntimeException
  Break
End Try

will now execute the NilObjectException code since that matches the more specific type. Note this is not peculiar to try catch statements but a general thing to keep in mind when dealing with if then else, select case and other kinds of statements that use boolean values to determine if their code should execute.

Now go catch stuff 🙂

Shifts ahoy !

Bit shifting can be troublesome. Especially if you’re not sure WHY they can be troublesome.

So some recommend only using UNSIGNED integers for such operations. And using *2 and \2 to do bit shifting.

At a very low level most modern CPUs implement certain numerical standards in various instructions. And, of note, nearly every last one has two (or more) forms of shifts. One is a logical shift, and one is an arithmetic shift.

The difference between them is VERY subtle – but important.

It turns out that this is the reason that you SHOULD use unsigned integers IF you use * 2 and \ 2 to do bit shifting. When you multiply by 2 a modern compiler might realize this is a simple arithmetic shift and write the machine code to perform exactly that operation. An arithmetic shift will preserve the sign. And so when you do a \2 operation you do not get a result that flips signs. The sign bit (left most bit) is preserved. For instance

Dim i as int8 = -8 // this is &b11111000 in binary 
                   // MSB is 1 indicating a negative value

dim j as int8 = i \ 2 
// j is now -4 which is &b11111100 in binary
// note the MSB is STILL set so the result did NOT change sign

Arithmetic shifts generally preserve the sign esp when the sign bit is initially set. Otherwise you get odd sign changes.

But the same is not true when you do a LOGICAL shift. This just moves bits without regard to signs. Starting with almost the same code, but using BITWISE.ShiftRight instead of \2 we get very different results IF you expect to get a value you can use as a number.

Dim i As Int8 = -8 // this is &b11111000 in binary 

Dim j As Int8 = BitWise.ShiftRight(i,1,8)
// j is now 124 which is &b01111100 in binary

The shift this time made NO effort to preserve the sign bit as we were doing logical shifts which make no effort to preserve the sign bit.

So when, or if, you need to do any bit manipulation make sure you understand whats going on at a low level and IF you use * and \ to do shifting use unsigned values.

Shifts away !