Article Preview

REVIEW

I Wish I Knew How to... Program the Canvas Control with Xojo Desktop

Issue: 15.1 (January/February 2017)
Author: Markus Winter
Article Description: n>No description availabl
Article Length (in bytes): 14,956
Starting Page Number: r>
Article Number: 15102
Related Web Link(s):

http://xdevlibrary.com

Full text of article...

In a small community like Xojo's, reviewing a book like Eugene Dakin's I Wish I Knew How to... Program the Canvas Control with Xojo Desktop is like reviewing your neighbor. I certainly do not want to curb anyone's enthusiasm for writing Xojo books. However, an honest appraisal is required, so that's what you'll get.

But before I even start this review I want to give you another Xojo user's perspective on the book as expressed by him on the forums:

[...] You have a gift for creating well-structured, easy-to-understand learning tools. I purchased two of your gems ... I Wish I Knew How to... Program the Canvas Control with Xojo Desktop and I Wish I Knew How to... Program Excel with Xojo. Matter of fact, your work on the Canvas Control ought to be mandatory reading for all Xojo programmers who want to exploit the full power of the canvas control and broaden their coding horizons by doing things they never knew were possible.

You have a magical way of taking a rather complex subject and exposing the simplicity in a step-by-step fashion. The way you sequentially build the learning points by "connecting the dots" and allowing the student to digest the concepts with small, bite-sized chunks of knowledge (with relevant examples sprinkled throughout) avoids the usual "gaps" I find in many other training materials that have me racing for Google and crying "WTF, how in hell's bells did he get from here to there!!!"

What a shame that all my college textbooks were not done in a similar fashion ... I might have actually enjoyed that 7-year stretch a whole lot more. Thanks for your efforts, Eugene ... I'm here to tell you that they DO make a difference with many of us!

After reading this, my expectations were quite high about learning from a master craftsman about how to approach working with the canvas, especially when it comes to dealing with flicker on Windows, scrolling, zooming, printing, saving, loading, high-res output ("publication ready"), etc. As the book was written in July 2014 I wasn't expecting too much on Retina / HiDPI (but you never know).

Presentation

The first thing I noticed was occasional awkward English that made some of the text hard to read. There were also spelling and grammatical errors. (Though the more advanced chapters were better written.) This is understandable for a self-published book in such a tiny market, but the book is still in serious need of a proofreader.

The layout was mostly good except for the large header and footer graphics showing on each page. I found them distracting, but at least in GoodReader on my iPad I was able to automatically restrict and zoom each page to the relevant content area.

Content

Chapter 1 starts with a general introduction to the canvas. Unfortunately, the graphic used to show the difference between backdrop and graphics layer is more confusing than helpful:

The problems I see is that the backdrop is in front, the perspective wrong, graphics items seem to float between the layers, and graphic items are seen as separate objects and not readily identified as a picture.

As criticising is easy, here is a quick example of what I think it could look like:

The text progresses quickly to drawing basic shapes, setting and converting colors, and drawing curves... before it goes back to performance tips for the canvas. Shouldn't these performance considerations not be part of the general introduction to the canvas?

I can't shake the feeling that beginners were ushered as fast as possible to actually do some drawing because that's "fun," but the book would have greatly benefited from a better structure and a much more in-depth introduction to the canvas.

For example, missing was an explanation as to the difference between a graphic and a picture, something which is immensely confusing to beginners (especially those who are not native English speakers).

Chapter 2 then deals with loading and saving pictures, focussing a bit on the difference between saving the backdrop versus the actual drawing.

After listing available file formats for saving a picture (with no explanation as to what the differences are or which format* should be used *when) we are back to double-buffering. The metaphor of the "pool, buckets, and hose" is now supplemented with "straws," which frankly makes it worse.

(If you want a much better explanation then I suggest you look it up on wikipedia [https://en.wikipedia.org/wiki/Multiple_buffering#Double_buffering_in_computer_graphics].)

The description is again contradictory, first stating that you load the picture into the backdrop layer, but then describing it as accessing the graphics layer to draw the picture. So which one is it being drawn into now? The backdrop or the graphics layer?

I'm familiar with the technique of drawing to a picture first, and then drawing the complete picture to the canvas (which is essentially what double-buffering is). What I would have liked to see is at least a note about the difference in double-buffering between the different operating systems; a test on the effects and benefits of adding your own double-buffering to the double-buffering already built into OS X; and an explanation of the differences in drawing the picture to the canvas backdrop vs drawing it in the canvas graphics.

I would like to point out that there is also a difference between saving a picture and exporting a picture, a difference that was not addressed. For example saving a picture doesn't have to mean saving it as a jpg or gif file, it can mean saving as a text or binary file all the instructions on how to draw the separate elements. The advantage is that after loading the instructions, you can easily undo a step or modify an instruction (for example to change the color or position of one of your drawn items). Marc Zeedar's SimpleDraw in xDev 12.5 is an excellent example of this approach. You could then export the picture to any format you desire (jpg, gif, png, tiff, etc), but that means you can no longer easily modify its contents or undo changes.

Chapter 3 deals with drawing text.

A serious error is the statement on page 56 that

"Invalidate and Refresh are slightly different, as Invalidate immediately forces the Canvas to update, where refresh allows other commands to finish before updating."

It is the other way round, and it is difficult to fathom how such a fundamental error has not been spotted. Especially as this erroneous information is propagated throughout the book (e.g. pages 60, 62, 64, 115, etc).

On rotating text it is stated that "Rotating text requires... the understanding of radians." Surely then it would be helpful to actually explain what a radian is (for a nice explanation see https://betterexplained.com/articles/intuitive-guide-to-angles-degrees-and-radians/), and not just declare it as being 57.295 degree.

Shoved into chapter 3 are also sections about scrolling and zooming a canvas. It would have been much better to deal with scrolling and zooming in a separate chapter.

One thing I learned from Chapter 3 is that TextSize is not necessarily an integer as I had always assumed.

Chapter 4 deals with the mouse, starting with drawing freehand on the canvas, dragging with the mouse, to zooming with the mouse. Combining zooming from chapter 3 and chapter 4 into a new chapter after chapter 4, followed by a chapter on scrolling, would work better in my opinion.

Chapter 5 deals with creating a reusable custom canvas class called DefaultCanvas, and the code in the canvas Open and Paint events finally moves to where it should have gone a long time ago: into the Open and Paint event of the superclass (the custom canvas class DefaultCanvas).

However, then the book continues like this:

There are some things to keep in mind when using a class. In the previous example, the Open and Paint events are being used, and when DefaultCanvas1 events are shown, the Open and Paint events are missing.

Which isn't surprising. The Open and Paint events are not shown in the instance DefaultCanvas1 as they are already implemented in the superclass DefaultCanvas.

Unfortunately, there is no way to have a working Open and/or Paint event to occur. Yes, an Event Definition can be added, but an Open event will not fire when the Open DefaultCanvas1 Event Definition is started.

No! That is horribly, horrendously wrong. You can propagate the Open event from the superclass to the subclass. You simply add an event definition in the superclass and name it Open. And both Open events will fire (the one in the superclass and the one in the subclass). All you have to do is call the Open event of the subclass from the superclass like this:

// CustomCanvas class OPEN event

me.EraseBackground = False

me.DoubleBuffer = True

Open // calls the subclass Open event that was added as an event definition

This shows a serious lack of understanding of the Xojo event model, and I couldn't believe that Eugene (or contributor Alain Bailleul) should not know about how events and event handlers work in Xojo.

Chapter 6 deals with making charts. It starts with a very simple line chart (basically drawing some lines), then continues to make it more and more complex, but also more customizable, before continuing with column and pie charts. This allows the reader to follow along nicely.

The importance of naming also becomes evident here. As all the Init method does is create a new picture that is being used as a buffer every time the old buffer is being discarded, it would have been better to name it descriptively. For example, call it CreateNewBufferPicture. Then Init could be used descriptively too: to initialize values (especially those that aren't easily set in the IDE, like a list of words or a dictionary). That is pretty much a standard convention, and one should not deviate from it lightly.

Instead a new RunOnce method is added that sets property default values for the properties of the custom canvas class. This is, of course, completely unnecessary as you can simply set the default values for the properties in the IDE, with no need for a separate method. In effect, the property values are being set twice, once to their default value, and then again by the RunOnce method. This setup is also a source of confusion if the user should change the property values in the IDE without realizing that they get overwritten by the RunOnce method.

Bizarrely, there are also a few places in chapter 6 where text suddenly stops mid-sentence (page 108) or a paragraph seems to be missing altogether (e.g. page 104), begging the question if any proof-reading at all had been done.

Chapter 7 aims to introduce object-oriented drawing techniques, but sadly without first giving an overview of the chosen approach (which would have been especially helpful for this topic).

Verdict

There is much more in the book (including building custom controls based on the canvas, animation, and games programming), but I'll stop here as otherwise this review will be longer than the book itself! I'm also aware that I mostly highlighted problems and areas that need improvement, rather than those that convey a more balanced view (which quite possibly makes me a bad reviewer).

So what is my verdict for the whole book? Between the awkward writing, a tremendous amount of repetition in the book, lack of in-depth explanations and background information, and several serious errors, I came away disappointed.

Part of this could be the approach: I would have preferred a book that built up a reusable canvas class that implemented scrolling, zooming, dragging, saving, loading, exporting, and more. That would have made it a "must buy" for me.

On the plus side, the book is more in-depth than the Xojo documentation. I still find it a useful and valuable addition to the Xojo literary stable, and at $11.99 it is a terrific value for beginners.

However, anyone able to follow Marc's SimpleDraw article in xDev 12.5 is probably already beyond the target audience. That said, Eugene is prolific and updates his work frequently, so hopefully he'll release a new edition that fixes errors and adds chapters on zooming, scrolling, high-resolution printing, and HiDPI screens

End of article.