LPTK User Manual

Authors:

Viktor Nagy <nvitya@freemail.hu>

This document is related to the LPTK project at lptk.sourceforge.net

Table of Contents

Introduction	1

What is the LPTK?	1

How LPTK has Born	1

Main features	2

License	2

Installing LPTK	3

Requirements	3

Requirements on Linux	3

Requirements on Windows	3

Installing the sources	3

LPTK package contents	3

Testing the installation	4

The Structure of an LPTK Application	5

The LPTK Hello application source	5

The result - screenshots	5

Commenting the example source	6

The compiler directives	6

The units	6

Definition of the Example Form Class	6

Describing the Form Layout	6

The Close Event Handler Procedure	7

The main program	7

Basic LPTK Programming	8

Forms and Widgets in General	8

Event handling	8

Unicode string handling	8

Drawing	9

Fonts	9

Colors	9

Key handling	9

Mouse handling	9

Clipboard handling	9

Database handling	10

Setting up the ODBC drivers	10

Database connections: TSqlDBConnection	10

SQL results: TSqlResult	10

Updating the data: TDBuis	10

Core LPTK Widgets	11

Label	11

Edit	11

Memo	11

Button	11

CheckBox	11

ListBox, TextListBox	11

ChoiceList	11

Grid, CustomGrid	11

DBGrid	11

Menu, MenuBar	11

ScrollBar	11

The Visual Form Designer	12

How the VFD works	12

Setting Up the VFD	12

Linux with Lazarus	12

Windows with Delphi	12

Using the VFD	12

Introduction

What is the LPTK?

The LPTK is a development toolkit for creating cross platform GUI (Graphical User Interface) applications in Pascal language. Mainly Linux and Windows supported.

LPTK means Light Pascal ToolKit (the name and the project was inspired after the C++ FLTK project). The main target was to create a simple and small library for fast application development where the applications don't require many large external libraries.

How LPTK has Born

I have a lot of Pascal programming experience. I started with Turbo Pascal 5 and I made several big projects in Delphi.

From 2001 I also use a Linux box at home with Graphical Desktop Environment installed. In 2002 I wanted to create some simple GUI programs that runs on Linux, because I met many of them. I started to study the way and the possibilities how to create GUI applications for Linux (X-window system). This time I planned to use C or C++. I saw that two different lines worth to follow: GTK (gnome) and QT (kde). After a short investigation I thought that QT is much more powerful than GTK.

I created a simple but useful application in QT (C++). I didn't liked that the program compiled very slow. It uses some kind of own C++ extensions through its own preprocessor. The development speed cannot be compared to Delphi. But this didn't fluster me. I wanted to create small software for own use.

I saw that QT has a Windows version too. I downloaded the freeware version of the QT library for Windows. I tried to compile the same application. I managed to compile but the application didn't work. I gave up after a few try. QT isn't really free by the way.

That was the time I started to care about the cross platform development. I searched for free cross platform toolkits. I found several (gtk, fltk, fox etc.) but none of them was as powerful as QT. For example correct Unicode support wasn't provided by them.

I liked FLTK because it compiled fast and run with no problems on both platforms. I saw that it has a relative short source code. I got the sources of the fpGUI toolkit which was written in FreePascal and worked some very basic level both on Windows and Linux. I found not so impossible task to create a toolkit in Pascal. At this time of writing I don't know a native (Free)Pascal GUI toolkit for Linux – except LPTK. (Kylix (2-3) also uses QT and I experienced several cross compiling problems so I gave up with it.)

Because I knew a lot about Windows GUI programming, I focused on the Linux development at the start. The windows has support for GUI elements but on Linux – however I found better the drawing routines - there are no GUI elements in the X-window-system. So the windows are drawn by hand, every single line of them. For the consistent development this level of access was preserved on Windows too (like the other cross platform toolkits do). This means the LPTK does not use the Windows build in controls.

When I reached respectable results, I put the sources on a public website. Later the project moved to the sourceforge.net choosing BSD license.

In the beginning I was just curious if I could really make it. Now I have a more complex applications using LPTK so it is not just a try...

Main features

It does not intend to be compatible with Delphi

Runs on Windows (with FPC and Delphi) and on Linux (with FPC). The applications look identical on the two platforms.

The applications do not depend on huge external libraries (like gtk or qt)

Natively supports Unicode. The texts stored in 16-bit Unicode format.

Anti aliased font rendering on Linux (using Xft)

Auto aligning with acnhors (like Delphi)

Modal forms

Popup windows

ODBC data access, with easy to use SQL interface

Visual Form Designer

Stores the form data in the same pascal source code, in source code format so no additional file required

Easily extendable

Supports unknown widgets and unknown properties

Clipboard handling, mouse wheel handling

Several GUI components

Multi line text editor

Database grid

Buttons with images

Panels (container widget)

etc.

BMP handling (masked)

Internal standard icon collection

License

The LPTK released under BSD style license that does not restricts the usage of the source codes. This allows for example static linking of the LPTK library without providing the object code of the distributed application (in contrast with LGPL).

Installing LPTK

Requirements

LPTK compiles and runs on Linux and Windows. Theoretically FreeBSD should also work with FPC (or only minimal changes required) but I couldn't test it.

Requirements on Linux

2.4+ kernel (?)

FreePascal 1.0.6+ compiler with packages

Xft library (version 1 or 2 ?)

X widow system (4+ ?)

Requirements on Windows

NT based windows (tested with Windows 2000 and XP). It does not work on Windows 95/98/ME.

FreePascal 1.0.6+ or Delphi 4+ compiler

Installing the sources

There are no special installation requirements. You can put LPTK sources anywhere. All LPTK library sources are in one directory. You need to set this direcory for the compiler to compile LPTK applications.

LPTK package contents

The LPTK distribution has the following subdirectories:

Directory Name	Description
apps	Small sample (some are very useful) applications using the LPTK library. In the beginning these applications motived me to develop the library.
src	The LPTK library sources.
stdimg	Standard (stock) images in BMP format. The src/stdimages.inc created from these.
tests	Various tests, mainly for the various widgets
utils	Utilities required for the lptk
vfd	The sources of the Visual Form Designer

Testing the installation

Compiling Pascal programs much easier then the C, C++. So there is no Makefile provided only some bat files.

Go to the tests directory and issue the shell command (on Linux):

$ ./buildd.bat lptk

This will compile the main LPTK test. When the compile finished you can start it with:

$ ./lptk

You may need to create some symbolic links for the linking (e.g. ln -s /usr/lib/libXft.so.1 /usr/lib/libXft.so).

On Windows the same result can be achieved with:

C:> buildw.bat lptk

C:> lptk

The same method can be used to compile the applications in the apps directory.

The Structure of an LPTK Application

The LPTK Hello application source

program helolptk;

{$APPTYPE GUI}

{$ifdef FPC}

{$mode delphi}{$H+}

{$endif}

uses

SysUtils, Classes, gfxbase, schar16, gfxform, wglabel, wgbutton;

type

TfrmMain = class(TGfxForm)

public

btnClose : TwgButton;
lbLabel1 : TwgLabel;

procedure AfterCreate; override;

procedure CloseClick(sender : TObject);

end;

procedure TfrmMain.AfterCreate;

begin

SetDimensions(338,154,153,81);
WindowTitle8 := 'Hello LPTK ';
lbLabel1 := CreateLabel(self, 24,12, 'Hello from LPTK');
btnClose := CreateButton(self, 28, 40, 96, 'Close', nil);
btnClose.OnClick := CloseClick;
btnClose.ImageName := 'stdimg.close';
end;

procedure TfrmMain.CloseClick(sender: TObject);

begin

Close;

end;

var

mfrm : TfrmMain;

begin

gfxOpenDisplay('');

mfrm := TfrmMain.Create(nil);

mfrm.Show;

gfxDoMessageLoop;

gfxCloseDisplay;

end.

The result - screenshots

The first screenshot was taken in Windows (XP) the second in Linux (Keramik window manager).

Commenting the example source

The compiler directives

{$APPTYPE GUI}

In the application main source the APPTYPE must be specified. This required only for Windows really. In the case of GUI no console will be allocated. So we can't see the writeln() debug messages (writeln-s redirected to the 'nul' device). If you require these debug messages change {$APPTYPE CONSOLE} for the time of debugging.

{$ifdef FPC}

{$mode delphi}{$H+}

{$endif}

These lines necessary in all source files to tell the FreePascal compiler the right mode ({$mode delphi}), and use ansi strings ({$H+}). Ansi strings are essential for the LPTK. They can store arbitrary length of any data including zero bytes that very frequently appear in unicode strings.

The units

uses

SysUtils, Classes, gfxbase, schar16, gfxform, wglabel, wgbutton;

Unit name	Description
sysutils, classes	Required by any object pascal program.
gfxbase	Contains the core functions and classes of the LPTK. These provide unified interface for the different platforms hiding their differences.
schar16	This unit contains the unicode string handling functions
gfxform	Contains the TGfxForm class. This is the base class of the displayed windows.
wglabel	Contains the TwgLabel widget class. This is the thing for displaying simple texts in the windows / forms.
wgbutton	Contains the TwgButton widget class. This is the closing push button for this example.

Definition of the Example Form Class

type

TfrmMain = class(TGfxForm)

public

btnClose : TwgButton;
lbLabel1 : TwgLabel;

procedure AfterCreate; override;

procedure CloseClick(sender : TObject);

end;

Every LPTK window is descendant of the TGfxForm class. The form contains one button and a label. In the LPTK the main form layouts described in the overridden AfterCreate method of the form class. This called as the last phase in the form object initialization. We want to the CloseClick procedure be called when the push button pressed.

Describing the Form Layout

procedure TfrmMain.AfterCreate;

begin

SetDimensions(338,154,153,81);
WindowTitle8 := 'Hello LPTK ';
lbLabel1 := CreateLabel(self, 24,12, 'Hello from LPTK');
btnClose := CreateButton(self, 28, 40, 96, 'Close', nil);
btnClose.OnClick := CloseClick;
btnClose.ImageName := 'stdimg.close';
end;

The SetDimensions sets the position, the width and the height of the form. The first two parameters (the x,y positions) are bypassed because the default behavior of the forms is aligning to the screen center. Then we set 153 pixels for width and 81 pixels for height. All size and position parameters measured in screen pixels.

The WindowTitle8 sets the title line of the window in the frame and on the taskbar. This property accepts a 8-bit string.

In the following lines we create the two form element – widget. We use the special creator functions of the widgets to create them. This way the source code is much sorter.

In the line btnClose.OnClick := CloseClick we assign our event handler procedure for the Click event of the pushbutton.

In the line btnClose.ImageName := 'stdimg.close' we tell the button to display an icon on the button surface, that exists in the LPTK internal image library.

The Close Event Handler Procedure

procedure TfrmMain.CloseClick(sender: TObject);

begin

Close;

end;

This calls the Close method of the TGfxForm class that closes the window but does not free it (just hides). Currently the LPTK program terminates when the last form is closed.

The main program

var

mfrm : TfrmMain;

begin

gfxOpenDisplay('');

mfrm := TfrmMain.Create(nil);

mfrm.Show;

gfxDoMessageLoop;

gfxCloseDisplay;

end.

The gfxOpenDisplay('') initializes the display and the internal structures of the LPTK library. This must be called once in an LPTK application, before any window is displayed.

The mfrm := TfrmMain.Create(nil) creates the main form. The argument nil means that the form visually has no parent. This is usual for the forms. The show method creates the window and subwindow object in the graphical subsystem (that called GDI on Windows and X-window on Linux).

The gfxDoMessageLoop starts the message receiving and processing in an endless loop. The messages come from the graphical subsystem. Until this point nothing is visible on the screen on Linux – however the window objects are already created. Several event required to be procesed to get the application windows working.

The LPTK event processing system provides that the mouse click on the “close” pushbutton will call the assigned CloseClick procedure.

The gfxCloseDisplay closes the display and releases the allocated resources. This function is never called in the current LPTK version but later it might change.

Basic LPTK Programming

Forms and Widgets in General

What is a form? The form is a window on the screen with the following features:

Contains subcomponents (widgets) that provide information or interact with the user

Has titlebar

Has resizeable frame

Moveable

Might appear on the taskbar

Every GUI program uses forms. At least every GUI program has a main window with the properties above.

The visible subcomponents of the form in LPTK are called widgets. Every widget owns a rectangular area on the screen – a part of the form. There are several different widget classes. Some provide only information for the user, some also interact with the user using its screen area. LPTK has several predefined, ready to use widget classes but the LPTK programmer can also easily create custom widgets. There is no limitation in look and behavior of the user interface in LPTK.

Here is an example form:

This form contains:

three one line text input widgets (TwgEdit)

one multiline text input widget (TwgMemo)

two pushbutton widgets (TwgButton)

four input field labels (TwgLabel)

The four input fields and the two pushbuttons can have the keyboard focus. There will be a cursor in the input fields or the buttons will be hilighted when they are focused. (In the example form the OK button is focused.) The field labels are also form widgets but they can not have the focus (the Focusable property is false). They only provide static texts in the form. The user can change the focused widget either with the mouse or the TAB key.

The LPTK widgets intends to provide comfortable environment both for the users and the programers. For example the programmer has to create the TwgEdit object, set its position and size. The initial text can be also set. After finishing the user input the programmer can easily read and process the content of the edit field. This is very similar to other GUI frameworks. The users meet widgets with very similar look and behavior to other GUI programs.

Event handling

How the Modal Forms work

Unicode string handling

The LPTK uses 16 bit unicode strings internally to store the texts that can be displayed on the screen. LTPK stores these strings in normal 8-bit ansi strings. The LPTK programmer should know the string is 16-bit or not. There are (loseless) conversion functions for both directions. LTPK uses the ^ character as escape in 8-bit string encoding to mark special characters. For example “t^369r^337;6” means ”tűrő6”.

8-bit encoding is very important, for example when store unicode strings in pascal source files. The 8-bit encoding can be inportant also when storeing unicode texts into database fields.

All 16 bit string handling functions and types reside in the schar16 unit. For more information see the LTPK Core Reference.

Drawing

Every widget can draw its own area using its Canvas object. The Canvas object provides a collection of drawing routines that behave exactly the same on the different platforms.

Fonts

Colors

Key handling

Mouse handling

Clipboard handling

Database handling

Setting up the ODBC drivers

Database connections: TSqlDBConnection

SQL results: TSqlResult

Updating the data: TDBuis

Core LPTK Widgets

The core widgets have good support in the the VFD and used by the LPTK sample applications.

Label

Edit

Memo

Button

CheckBox

ListBox, TextListBox

ChoiceList

Grid, CustomGrid

DBGrid

Menu, MenuBar

ScrollBar

The Visual Form Designer

How the VFD works

Setting Up the VFD

Linux with Lazarus

Windows with Delphi

Using the VFD

LPTK User Manual - 12

LPTK User Manual

2004-04-17T23:02:08