About 0.1% of the total OP4JS RTL system
Since the basic framework is nearing completion at high speed (although some modifications might appear) I thought it could be interesting to demonstrate how to create your very own custom control under OP4JS.
In the Delphi world there are two archetypal programmers: Those that stick to the high level interface of Delphi, meaning that they only use pre-made controls and rarely go beneath the bonnet so to speak – and the second group which create components, packages and love to fiddle around with low-level coding. This type of stereotyping is something more or less unique to RAD languages (which would include Delphi, Lazarus, Visual Basic, Real Basic and languages that are “design” based). In more mature languages like C++, Delphi (yes delphi is just as low level as the C++) or C# low-level work is almost unavoidable. But with Object Pascal you at least have a choice (!)
With OP4JS we have tried to retain much of the HLA (high level abstraction) of Delphi, but the system demands that if you want something unique – you have to create your own controls in order to stand out. If not, you might as well go with the many template-based “app machines” out there that produce programs that all look and feel the same.
The basics of a control
There are two types of controls you can create under OP4JS: Graphical controls and ordinary parent/child controls (like you are used to from Delphi). A graphical control is an object that contains a HTML5 graphics context and canvas, which means you have to draw it yourself. This is good for things like games, charts or anything that cant be represented using “normal” html.
The second type, which is the one 90% of all the standard controls that ship with OP4JS derive from, is TCustomControl. So let’s have a look at how setting up a fancy iPhone header looks like:
type TW3HeaderControl = Class(TCustomControl) private FLabel: TLabel; FBackBtn: TW3ToolButton; FNextBtn: TW3ToolButton; Protected Procedure Resize;Override; protected Procedure InitializeObject;override; Procedure FinalizeObject;override; Procedure StyleTagObject;override; End;
Under Delphi you would probably expect to see a constructor and destructor in the above code, but under OP4JS we try to synchronize the number of steps taken to establish a control (i.e number of resize and position operations). So to solve this we have introduced 3 new methods: InitializeObject, FinalizeObject and StyleTagObject. As the names imply you create any sub-controls and initialize your variables in InitializeObject (just think of it as your constructor), you destroy those instances in FinalizeObject, and you apply any extra styling or property alteration in the StyleTagObject method.
Clever styling
When a control is in the state of creation, it automatically set it’s own style class (think html here) to the name of it’s class. So in order to give our little control a nice look – we edit the default style sheet (this is automatically created when you create a new application) and make it look like a true iPhone header. The rule of thumb is: The name of the CSS class always matches the name of the OP4JS control:
.TW3HeaderControl
{
background-image:-webkit-gradient(linear, left top, left bottom,
from(#b2bbca),
color-stop(0.25, #a7b0c3),
color-stop(0.5, #909cb3),
color-stop(0.5, #8593ac),
color-stop(0.75, #7c8ba5),
to(#73839f));
border-top: 1px solid #cdd5df;
border-bottom: 1px solid #2d3642;
-webkit-box-shadow: rgba(33, 33, 33, 0.2) 0px 1px 1px;
}
Adding behavior
If you don’t know anything about CSS or HTML, don’t worry, you can always copy a style you like from the default skin, and there are plenty of examples around the Internet to learn from (or just get a good book, that would save you a lot of time). OK now we need to add some code to our unit to make it come alive:
Procedure TW3HeaderControl.InitializeObject;
Begin
inherited;
FLabel:=TLabel.Create(self);
FLabel.BorderStyle:=bsDotted;
end;
Procedure TW3HeaderControl.FinalizeObject;
Begin
FLabel.free;
if assigned(FBackBtn) then
FBackBtn.free;
if assigned(FNextBtn) then
FNextBtn.free;
inherited;
end;
Procedure TW3HeaderControl.StyleTagObject;
Begin
inherited StyleTagObject;
end;
Procedure TW3HeaderControl.Resize;
var
wd,hd: Integer;
mTemp: Integer;
dx: Integer;
Begin
wd:=Width;
hd:=Height;
mTemp:=wd;
dx:=4;
dec(mTemp,4); //left margin
dec(mTemp,4); //Right margin
if assigned(FBackBtn)
and (FBackBtn.Visible) then
Begin
//space between "back" & label
dec(mTemp,FBackBtn.width);
dec(mTemp,2);
//offset the left edge of the label
inc(dx,FBackBtn.Width);
inc(dx,2);
// position the back-button
FBackBtn.Left:=4;
FBackBtn.Top:=4;
end;
if assigned(FNextBtn)
and (FNextBtn.Visible) then
Begin
//space between label & "next" button
dec(mTemp,FNextBtn.width);
dec(mTemp,2);
FNextBtn.Left:=mTemp;
FNextBtn.Top:=4;
end;
FLabel.left:=dx;
FLabel.top:=4;
FLabel.Width:=mTemp;
FLabel.Height:=Height-8;
end;
Why all that code? First of all because it’s just a quick example and secondly, because a typical iPhone header have 3 parts: A back button, a next button and some text in the middle. The above code checks to see if you actually have created a back or next button and shrinks the text area accordingly. Let’s see how it looks so far:
That was easy enough
I have set the label to have a dotted frame just to make it easier to work with, we will of-course remove the frame all together later. But now, let’s add some more methods to the class interface. We want to expose the label object to give the user access to it’s full capabilities (caption, font, background, orientation and all the rest), and we also want both back and next buttons.
But, we want to keep resources to a bare minimum, so we will use the old “need” trick and only create the buttons when asked for. So the buttons will only be created when you access them:
TW3HeaderControl = Class(TCustomControl) private FLabel: TLabel; FBackBtn: TW3ToolButton; FNextBtn: TW3ToolButton; procedure ReleaseButtons; Procedure NeedBackButton; Procedure NeedNextButton; function getBackButton:TW3ToolButton; function getNextButton:TW3ToolButton; protected Procedure Resize;Override; protected Procedure InitializeObject;override; Procedure FinalizeObject;override; Procedure StyleTagObject;override; public Property BackButton:TW3ToolButton read getBackButton; Property NextButton:TW3ToolButton read getNextButton; property Title:TLabel read FLabel; Property Options:TW3HeaderButtonOptions read FOptions write setOptions; End;
And the implementation for our new methods are (this is just a quick example):
Procedure TW3HeaderControl.NeedBackButton;
Begin
// Create object on the fly if required
if not assigned(FBackBtn) then
Begin
BeginUpdate;
FBackBtn:=TW3ToolButton.Create(Self);
SetReSized;
EndUpdate;
end;
end;
Procedure TW3HeaderControl.NeedNextButton;
Begin
// Create object on the fly if required
if not assigned(FNextbtn) then
Begin
BeginUpdate;
FNextbtn:=TW3ToolButton.Create(Self);
SetReSized;
EndUpdate;
end;
end;
function TW3HeaderControl.getBackButton:TW3ToolButton;
Begin
NeedBackButton;
result:=FBackBtn;
end;
function TW3HeaderControl.getNextButton:TW3ToolButton;
Begin
NeedNextButton;
result:=FNextBtn;
end;
procedure TW3HeaderControl.ReleaseButtons;
Begin
if assigned(FBackBtn) then
Begin
FBackBtn.free;
FBackBtn:=NIL;
end;
if assigned(FBackBtn) then
Begin
FNextBtn.free;
FNextBtn:=NIL;
end;
end;
The final product
To use our new control, all we have to write (in our Form’s InitializeObject for instance) is something like:
FMyCoolHeader:=TW3HeaderControl.Create(self); FMyCoolHeader.BackButton.Caption:='Back'; FMyCoolHeader.BackButton.onClick:=HandleBackButtonClicked; FMyCoolHeader.Title.Caption:='My cool header!';
And voila – we have a nifty iPhone header that looks and feels like the real thing 🙂
Easy but effective
Notes and addendum
This example is very, very simple. It was put together in 5 minutes just to demonstrate how easy it is to get going and is in no-way an example of code quality or approach. I can think of 1000 ways of making a better header control (the one that ships with OP4JS has a lot more code and does not create buttons this way, and yes — exceptions and error handling is a must).