Category Archives: Documentation

When interacting with ordinary javascript libraries or a remote webservice you natually have to go native with your datastructures. Under Smart this can be handled in a variety of ways but the two most common approaches are to either use a record or a variant.

Using records

Records in Smart work just like they do in other object pascal environments. And since Smart compiles to javascript rather than machine opcodes, a record will always compile to an ordinary javascript structure. I should note that javascript really doesnt distinguish between what we would call a record and objects. In javascript everything is an object.

So the following object pascal code:

[sourcecode language=”delphi”]
type TMyInfo = Record
miName: String;
miAge: Integer;
miGender: integer;
End;
[/sourcecode]

Results in the following predictable javascript code:

[sourcecode language=”javascript”]
{
miName: "",
miAge: 0,
miGender: 0
}
[/sourcecode]

This means that when you want to interact with native javascript libraries that expects a structure of values, you can use records to match it directly.

Variants

Using variants to achieve the same thing is perhaps easier, especially since you dont have to predefine the structure by hand. As of writing however it does require you to initialize the variant manually. We will probably add some RTL functions to simplify this very soon, but for now you can use this “one liner” ASM snippet:

[sourcecode language=”delphi”]
Procedure testvariant;
var
mData: variant;
Begin
asm @mData = {}; end; // Set variant to "empty JS object"
mData.miName:=’john doe’;
mData.miAge:=39;
mData.miGender:=1;
end;
[/sourcecode]

The resulting javascript structure will be exactly the same as that produced by the record. One difference to keep in mind though, is that the compiler will output the names “as is”. There is no way for Smart to map the content of a native object so make sure you get the names right.

Generating images offscreen and using it is now a snap!

In alpha release 3 several missing bits and pieces from the HTML5 standard was added to Smart Mobile Studio. One of the key methods that were missing from our canvas implementation was toDataUrl – a function which has it’s opposite in TW3ControlBackground and TW3Image fromURL and LoadFromUrl methods.

So in effect, it is now very simple to transport off-screen graphics (graphics you have created on a canvas) and use it as either a background or as the content of a normal image.

Here is an quick example of how to create a picture dynamically and display it in a TW3Image control. Also notice that you can actually assign the image to the background of any TW3CustomControl descendant.

To run the example create a new visual project and replace the code in Form1 with the following:

[sourcecode language=”delphi”]
unit Form1;

interface

uses w3system, w3ctrls, w3forms, w3graphics,w3application;

type

TForm1=class(TW3form)
private
{ Private methods }
FImage: TW3Image;
FGraph: TW3GraphicContext;
FButton: TW3Button;
procedure HandleButtonClicked(Sender:TObject);
protected
{ Protected methods }
Procedure InitializeObject;override;
Procedure FinalizeObject;override;
Procedure StyleTagObject;override;
procedure resize;Override;
end;

Implementation

//############################################################################
// TForm1
//############################################################################

Procedure TForm1.InitializeObject;
Begin
inherited;
FImage:=TW3Image.Create(self);
FImage.Background.fromColor(clWhite);
FButton:=TW3Button.Create(self);
FButton.OnClick:=HandleButtonClicked;
FButton.Caption:=’Click to generate’;
FGraph:=TW3GraphicContext.Create(NIL);
End;

Procedure TForm1.FinalizeObject;
Begin
FImage.free;
FButton.free;
FGraph.free;
inherited;
End;

procedure TForm1.HandleButtonClicked(Sender:TObject);
var
FCanvas: TW3Canvas;
aFrom: String;
aTo: String;
Begin
FGraph.Allocate(FImage.Width,FImage.Height);
FCanvas:=TW3Canvas.Create(FGraph);
try

// Clear background
FCanvas.fillstyle:=’rgb(0,0,99)’;
FCanvas.fillrectF(0,0,FGraph.Width,FGraph.Height);

// Draw some text on the canvas
FCanvas.font:=’10pt verdana’;
FCanvas.FillStyle:=’rgb(255,255,255)’;
FCanvas.FillTextF(‘This was generated on a canvas!’,10,20,MAXINT);

//You can load it in as a picture
FImage.LoadFromUrl(FCanvas.toDataUrl(”));

//.. or load it as a background to a picture (or control)
//FImage.background.fromUrl(FCanvas.toDataUrl(”));

finally
FCanvas.free
end;
FGraph.release;
end;

procedure TForm1.resize;
var
hd: Integer;
dy: Integer;
Begin
FImage.setBounds(5,5,width-10,(height div 2) + (height div 3) );
hd:=height – (FImage.top + FImage.Height + 5);
dy:=(hd div 2) – (FButton.height div 2);
FButton.setBounds(5,dy + FImage.Top + FImage.height,width-10,FButton.height);
end;

Procedure TForm1.StyleTagObject;
Begin
inherited;
StyleClass:=’TW3CustomForm’;
End;

end.

[/sourcecode]

Just like ordinary Delphi, Javascript has it’s own canvas object. As you can imagine the canvas of the browser is quite different from the good old Delphi TCanvas, but not so alien that it doesn’t have it’s similarities. But you will need to brush up on the documentation from Apple in order to use it.

But HTML5 also have something else up it’s sleeve, namely that you can create off-screen bitmaps (wrapped in the TW3ImageData class from w3graphics.pas). The difference between a Delphi bitmap and a HTML5 bitmap is 3 fold:

• The bitmap is obtained from the canvas, not the other way around (Delphi’s TBimap has a canvas property)
• Off-screen bitmaps do not have a canvas, they are in reality DIBS (device independent bitmaps)
• Off-screen bitmaps are 32bit exclusively (RGBA, 8888 format).

This is actually good news because it means we can create games and multimedia dealing with pixel data rather than the (excuse me) somewhat cumbersome canvas object. Most javascript developers actually avoid this part because they are used to “high level” coding only – but coders coming from the Delphi community have been knocking out low level graphics libraries for ages. So if you have ever played around with DIBS (device independent bitmaps) in Delphi – you should feel right at home.

Here is a quick example of how to plot some pixels off-screen, and copy the results onto the screen (note: this is a game project):

[sourcecode language=”delphi”]
unit Project8;

interface

uses w3system, w3components, w3application,
w3game, w3gameapp, w3graphics, w3components;

type

TApplication=class(TW3CustomGameApplication)
private
{ Private methods }
FBuffer: TW3ImageData;
protected
{ protected methods }
procedure ApplicationStarting;override;
procedure ApplicationClosing;override;
Procedure PaintView(Canvas:TW3Canvas);override;
end;

Implementation

//############################################################################
// TApplication
//############################################################################

procedure TApplication.ApplicationStarting;
Begin
inherited;

//Initialize refresh interval, set this to 1 for optimal speed
GameView.Delay:=20;

(* Create a our "offscreen bitmap" *)
FBuffer:=GameView.Canvas.CreateImageData(32,32);

//Start the redraw-cycle with framecounter active
//Note: the framecounter impacts rendering speed. Disable
//the framerate for maximum speed (false)
GameView.StartSession(true);
End;

procedure TApplication.ApplicationClosing;
Begin
GameView.EndSession;

inherited;
End;

// Note: In a real live game you would try to cache as much
// info as you can. Typical tricks are:
// 1: Only get the width/height when resized
// 2: Pre-calculate strings, especially RGB/RGBA values
// 3: Only redraw what has changed, avoid a full repaint
// The code below is just to get you started

procedure TApplication.PaintView(Canvas:TW3Canvas);
Begin
// Clear background
canvas.fillstyle:=’rgb(0,0,99)’;
canvas.fillrectF(0,0,gameview.width,gameview.height);

// Draw our framerate on the screen
canvas.font:=’10pt verdana’;
canvas.FillStyle:=’rgb(255,255,255)’;
canvas.FillTextF(‘FPS:’ + IntToStr(GameView.FrameRate),10,20,MAXINT);

// plot some pixels
if FBuffer<>NIL then
Begin
FBuffer.setPixelC(0,2,clGreen);
FBuffer.setPixelC(1,2,clGreen);
FBuffer.setPixelC(2,2,clGreen);

FBuffer.setPixelC(0,4,clRed);
FBuffer.setPixelC(1,4,clRed);
FBuffer.setPixelC(2,4,clRed);

// paste graphics to display
Canvas.putImageData(FBuffer,20,20);
end;
End;

end.

[/sourcecode]

The result may not look so impressive right now, but it’s the foundation for what will become a very impressive browser based graphics system:

Pixels galore

In the future we are going to add a lot more functionality to the TW3ImageData class. Things like line, ellipse, fillrect, circle and flood-fill is already prototyped. But if you feel like playing around with pixels – this is a good start.

Open the file w3graphics.pas and have a look at the methods and properties of TW3ImageData for more information. Also check out this excellent canvas tutorial by Mark Pilgrim.

All descendants of TW3Customcontrol, which is the primary object most visual controls derive from, has a property called Angle. This is a floating point property which will rotate your control in whatever angle you define. Please bear in mind that this property will override any webkit rotation in the current style. If you want the stylesheet to retain it’s position, mark the CSS tag with !important;

For instance:

[sourcecode language=”delphi”]
unit Form1;

interface

uses w3system, w3ctrls, w3forms, w3application;

type
TForm1=class(TW3form)
private
{ Private methods }
FButton: TW3Button;
Procedure HandleClick(Sender:TObject);
protected
{ Protected methods }
Procedure InitializeObject;override;
Procedure FinalizeObject;override;
Procedure StyleTagObject;override;
end;

Implementation

//############################################################################
// TForm1
//############################################################################

Procedure TForm1.InitializeObject;
Begin
inherited;
FButton:=TW3Button.Create(self);
FButton.caption:=’Click me’;
FButton.setBounds(100,50,100,28);
FButton.onClick:=HandleClick;
End;

Procedure TForm1.HandleClick(Sender:TObject);
Begin
if FButton.Angle=60 then
FButton.Angle:=0 else
FButton.Angle:=60;
end;

Procedure TForm1.FinalizeObject;
Begin
inherited;
End;

Procedure TForm1.StyleTagObject;
Begin
inherited;
StyleClass:=’TW3CustomForm’;
End;

end.

[/sourcecode]

When you click the button it will toggle between normal (0 deg) and tilted (60 deg), like this:

Best not to over do it

Under Delphi and free-pascal there is a component called TTimer. Under Smart Mobile Studio however all types of timer objects have a slightly different architecture – and also different names (we will probably provide a TTimer alias before release). The class you are looking for is called “TW3EventRepeater”.

To use a timer start by adding the unit “w3time” to your unit’s uses section. Unlike Delphi, TW3EventRepeater derives from TObject rather than TComponent. There is no point in creating a component (which adds quite a bit of overhead) when a normal object will do.

Using the event repeater from a form is a snap:

[sourcecode language=”delphi”]
unit Form1;

interface

uses w3system, w3ctrls, w3forms, w3application, w3time;

type
TForm1=class(TW3form)
private
{ Private methods }
FTimer: TW3EventRepeater;
FCount: Integer;
function HandleTimer(sender:TObject):Boolean;
protected
{ Protected methods }
Procedure FormActivated;override;
end;

Implementation

//############################################################################
// TForm1
//############################################################################

Procedure TForm1.FormActivated;
Begin
FTimer:=TW3EventRepeater.Create(HandleTimer,1000);
end;

function TForm1.HandleTimer(sender:TObject):Boolean;
Begin
result:=False;
inc(FCount);
if FCount>9 then
Begin
TW3EventRepeater(sender).free;
result:=true;
w3_showmessage(‘time is up!’);
end;
end;

end.
[/sourcecode]

As expected the timer kicks in after 10 seconds informing us that the time has expired

The timer works just like we expect

You may have noticed that the callback was a function and not a procedure? If you return “true” the timer will stop of it’s own accord. Since this is javascript and not winapi you can actually dispose of the timer while the timer is called. Because the timer object does not go out of scope until the function returns.

Adding a new form to a visual application is a piece of cake. Start by opening your project (or create a new visual project), then click the “add form” button in the IDE or add form from the project menu.

Adding a new form is very simple

This will present you with a brand new unit, ready to be used by your application. Now switch over to your project unit (in this example, the project was automatically called “project7”, and thus the project unit is called “project7″). The project units looks something like this:

[sourcecode language=”delphi”]
unit Project7;

interface

uses w3system, w3ctrls, w3forms, w3application,
form1;

type

TApplication=class(TW3CustomApplication)
private
{ Private methods }
public
{ protected methods }
procedure ApplicationStarting;override;
end;

Implementation

//############################################################################
// TApplication
//############################################################################

procedure TApplication.ApplicationStarting;
var
mForm: TW3CustomForm;
Begin
//Add code above this line
mForm:=TForm1.Create(display.view);
mForm.name:=’Form1′;
RegisterFormInstance(mForm,true);
inherited;
End;

end.
[/sourcecode]

Before you can actually display and work with your form, the application must know about the form’s existance. So we need to register an instance of the form with the form manager inside TApplication (remember to add “form2″ to your uses section). Simply create an instance of your form by copying the code already present. We alter the name ofcourse so we dont get any conflicts, and we send False rather than True as the last parameter:

[sourcecode language=”delphi”]
procedure TApplication.ApplicationStarting;
var
mForm: TW3CustomForm;
Begin
//Add code above this line
mForm:=TForm1.Create(display.view);
mForm.name:=’Form1′;
RegisterFormInstance(mForm,true);

mForm:=TForm2.Create(display.view);
mForm.name:=’Form2′;
RegisterFormInstance(mForm,false);

inherited;
End;
[/sourcecode]

The reason we pass in “false” as the second parameter is because this value defines the “main” form of the application. All visual applications must have a main form, which is also the form the application displays when you start it.

We can now use the methods GotoForm or GotoFormByRef to navigate between forms. Both these commands (which are members of TCustomApplication) takes a second parameter which controls the special effect. As of writing you can only slide the new form in from either the left or right, but more interesting effects are planned.

You can create a class under Smart Mobile Studio the exact same way as you would under Embarcadero Delphi or free-pascal. Just like ordinary object pascal, classes, custom types and functions are stored in a unit file. Below is an example of a very simple class which has one public member:

[sourcecode language=”delphi”]
unit myobject;

interface

uses w3system;

type
TMyObject = Class(TObject)
public
procedure dosomething;
End;

implementation

procedure TMyObject.dosomething;
Begin
w3_showmessage(‘you called me’);
end;

end.
[/sourcecode]

To add a new unit to your project, click the “add unit” button in the IDE, or select add unit from the project menu. You can then proceed to type in the code you want. By default the IDE provides some skeleton code for your unit, so you don’t have to type everything.

To use the unit you have just created – simply add the name of the unit to the uses section in an already existing unit. All unit have a uses section which makes the code in other units visible to that particular unit.

More information

• Writing a class unit (delphi basics)