Vote for Lazarus

Thank you, people from the Lazarus community! For the first time of our project history Lazarus has been nominated for SourceForge's Community Choice Award in the category "Best Tool or Utility for Developers".

Grab your chance to let others know how much you like Lazarus by voting for Lazarus. Spread the news and don't forget to vote, this time to make us winners.

Changes with Button Glyphs

If you ever worked with the Lazarus IDE under windows (or just compiled an LCL application for windows) you were probably sickened by the glyphs on the dialog buttons since it is not native for windows. But on linux all is vice versa - most of the buttons have glyphs (and for example gtk and qt suggest an appropriate API to query "stock" images for buttons with various actions like save, open, apply, cancel, ...).

Therefore I needed a solution which can satisfy both windows and linux users. I started from the TBitBtn class which represents a button control with an image inside it. What I have added is a new property "GlyphShowMode" with 4 states:

• gsmAlways
• gsmNever
• gsmApplication
• gsmSystem

It is clear what the gsmAlways and gsmNever states are for: gsmAlways - to show the glyph always and this is how it worked before, gsmNever - to show the glyph never. Well, you may ask: What do I need the gsmNever state for, if I can use a TButton instead?. And I would answer: TBitBtn is not just a button with an image. It also has a Kind property which is very useful to set the ModalResult and Caption of a button :) But let's return to the other modes. gsmSystem can be used to show glyph depending on current OS - on MS Windows glyph will not be shown and on other system it will. And the last mode which is also default for this property - gsmApplication. In this mode TBitBtn (well, not exactly TBitBtn but TButtonGlyph) will look at the Application object for its value.

So, you can control the visibility of all button glyphs using the Application object. How? There are 2 ways: at run time by changing the Application.ShowButtonGlyphs property or at design time by changing the same property for the TApplicationProperties component. TShowButtonGlyphs is an enumeration too with following elements similar to TGlyphShowMode:

• sbgAlways
• sbgNever
• sbgSystem

The default value for the ShowButtonGlyphs property is sbgAlways and not sbgSystem as one may expect. The reason is compatibility with old applications. Developers don't like surprises after a development tool upgrade and the loss of images is not a nice surprise. Anyway, it is not difficult to change the behavior of your application.

One more thing - glyphs are always visible when you are designing your forms. The glyph visibility mode is applied to the controls only at run time (when you start your application).

And now with regards to the Lazarus IDE. After this change the IDE on windows does not show glyphs on buttons by default, but if you really liked them, you can ask IDE to return them. You need to open the IDE options dialog and select Desktop settings:

No updates on the 0.9.26 fixes branch

I have decided to stop merging revisions from Lazarus trunk to the fixes_0_9_26 branch. There are two reasons:

1. The differences between trunk and the fixes branch have become too many, over a thounds revisions. It is difficult to oversee their relations and dependencies, so I cannot guarantee the quality of the fixes branch just by looking at the patches and revision logs.


2. I want to focus on the 0.9.28 release rather than maintaining 0.9.26.3 and working on a 0.9.26.4 release.

That said, it doesn't mean 0.9.28 is almost ready, a lot of work still needs to be done. The list of issues with that we want to fix before the 0.9.28 release contains about 50 items.

So, from now on nobody from the current Lazarus team maintains the 0.9.26.3 branch. If somebody from the community is using the Lazarus fixes branch on a daily basis and want to extend its life, then that is possible. The new maintainer would supply me a list of revisions to be merged and tests the fixes branch. I would do the actual merging and keep the snapshots of the fixes branch alive. If you are interested, you can contact me and we can work out the details.

fpsvnsync, thanks for your services

Since March 2007, the Lazarus SVN repository has been mirrored on SourceForge. Mirroring it on SourceForge is nice, sometimes people have trouble reaching svn.freepascal.org. And the svn commits count for the SourceForge ranking. Because SourceForge did not allow changing the revprops like author and date, I could not use the official tool called svnsync to create such a mirror. I submitted a tracker item at SourceForge to allow changing revprops, but two years nothing happened. So I wrote a watered down version of svnsync which would do almost the same as svnsync and named it fpsvnsync.

Last week I browsed the SourceForge site status and found an announcement about enabling revprops. This is good news, fpsvnsync does it job, but it needs both trees checked out and it is not as efficient as svnsync itself, because it starts a svn process several times for each changed file.

Last Monday I made a svndump of the Lazarus repository to get all those names and dates (which fpsvnsync cannot / could not set correctly) right. For your information, is a 700 MB file after bzip2-ing. I imported it on SourceForge using the svn migration page. Then I had a surprise when started svnsync init:

svnsync init https://lazarus.svn.sourceforge.net/svnroot/lazarus \
http://svn.freepascal.org/svn/lazarus
svnsync: Cannot initialize a repository with content in it

It only works on empty repositories. Three hours of import wasted.

So I imported an empty repository and called svn init on that repository. Using svnsync sync would be an option to make the mirror up to date, but importing more than 19000 revision this way didn't seem to be a wise choice. So I imported the 700 MB dump again, but without clearing the existing one. But still the svnsync utility didn't want to work. I had to set the svn:sync-last-merged-rev property manually, svnsync keeps this revprop for its administrative puproses at revision 0:

svn propset svn:sync-last-merged-rev --revprop -r0 19091 \
https://lazarus.svn.sourceforge.net/svnroot/lazarus

I updated my crontab to call svnsync every three minutes and the Lazarus svn mirror at SourceForge has been updated nicely after.

Next Lazarus release: 0.9.26.2

More than three months (and 1500 revisions) have passed since the latest Lazarus release, so it is time for a new release. Lazarus trunk has now gtk2 as default widget set on Linux and is not yet in a releasable state. Further, gtk2 on newer Linux distros, requires fpc 2.2.4, which has not been released yet. The first release candidate is expected in the coming week(s). So I don't expect the final fpc 2.2.4 release before March. Waiting for fpc 2.2.4 would mean waiting for the next Lazarus release till April or May.

Fortunately, selected revisions from trunk have been merged to the fixes 0.9.26 branch, which actually has become more than just fixes, also 'stable', finished features from 0.9.27 have been merged, such as the use frames and the project icon.

This release can been regarded as an experiment with time based releases. Trunk releases usually have been scheduled to follow a fpc release or some finished feature and bug fixes. The exact timing of such releases was hard to predict. I tried to keep the fixes 0.9.26 branch always in a releasable state, so for example the switch to gtk2 has not been merged, because that depends on a fpc release.

I think the challenge with this release is the testing. The fixes branch is (almost?) not used by the Lazarus developers and I doubt that Lazarus snapshot users use 0.9.26.1 snapshots as much 0.9.27 snapshots. I want to ask you to try these 0.9.26.1 snapshots and report any regressions compared to the 0.9.26 release.

If everything goes well, we have a 0.9.26.2 release next month. Keep an eye on the release plan.

New TPen properties

1. What is a Pen?

You know we are using pens when we draw a line or a shape border on a graphic canvas. A Pen defines how our lines will look. It can be thick or thin, dotted or solid, color or black. So lets review what properties a pen can have?

First of all pens can be cosmetic and geometric. Cosmetic pens are always 1 pixel wide, while geometric pens can have any width. But width of geometric pens are defined in world units and thus depends on transforms (scaling, rotation, shear, reflection) applied to canvas. Operations with cosmetic pens are faster.

The next pen property is pattern. Different libraries suggest different sets of default patterns (dot, dash, dash dot, dash dot dot, etc). Some of them don't contain any predefined pattern but allow to set a custom pattern. All libraries allow to set a solid pen pattern (usually default pattern) and some of then an empty pattern (invisible :) ).

The next usual pen property is color. Every library allows to set any custom pen color.

Geometric pens usually allow to set the style of end caps and the style of the joins between lines. The end cap can be: Round, Square and Flat. Look at the picture - they are placed in this order. When end caps are round - last points are drawn round, when end caps are square - last points are drawn square. When end caps are flat - last points are not drawn at all.

The join style can be: Round, Bevel and Miter. Look at the picture - they area placed in the same order.

Lazarus is using different libraries and each of them has a different pen implementation. For example Carbon does not supports cosmetic pens. And gtk does not support flat end caps for geometric pens (a similar style exists - GDK_CAP_NOT_LAST but it behaves as GDK_BUTT for geometric pens).

2. What was added and how it behaves

Before 0.9.27 pens were the same in Delphi and Lazarus. Pens were (and are) implemented through TPen class and had the following properties: Color, Style, Width (which cannot be less than 1). In order to create a widgetset object, TPen used a call to the CreatePenIndirect winapi compatibility function.

Thus I looked at how winapi works with all those end caps, join styles, cosmetic/geomtric and found another function which can create all what I need - ExtCreatePen. So the first thing I've done was inclusion of ExtCreatePen into LCL. I tried different pens by assigning that function result to Canvas.Pen.Handle. ExtCreatePen allows to choose whether your pen be cosmetic or geomtric, set a predefined line style or use custom dashes, set a solid color or even any brush to draw a line, set end cap style and join style. Don't expect full winapi compatibility from LCL, if you try to use this function directly. Only solid colors are supported - thus you need to pass BS_SOLID for the brush style and hatch = 0.

Another winapi compatibility function I touched was GetObject. It returns a description for the given GDI object. I've extended it to return correct TLogPen if a pen was created by CreatePenIndirect and TExtLogPen if a pen was created by ExtCreatePen.

Next I touched the TPen class itself. I've added TPenEndCap, TPenJoinStlye enumerations and TPen.EndCap, TPen.JoinStyle properties. Also I've added TPen.Cosmetic property since TPen.Width cannot be less than 1 (in other case I would use Pen.Width = 0 as cosmetic). So if you set TPen.Width = 1 and TPen.Cosmetic = True - you'll get your cosmetic pen (this is set by default for newly created pens). In all other cases pens are geometric. Pen is always geometric if Pen.Width > 1 even if Pen.Cosmetic = True. I've also added TPen.SetPattern method to set user defined patterns. If Pen.Style = psPattern lines will be drawn with dashes defined in the pattern array (first number means dash length, second space length and so forth).

3. Limitations

As I wrote before, Carbon does not support cosmetic pens and Gtk has its own point of view about Flat end caps :) But is this all you need to keep in mind?

When I wrote my test application and launched it on Mac OS X I've found that anti aliasing is not always a good friend :) My dashes were invisible and the pen looked almost solid for all styles when its width was equal to one. To eliminate this defects I've added TCanvas.Antialiasing property and now we can control it (only on Carbon and Qt though).

4. Conclusion

Almost all pen capabilities you can find in different libraries are now present in the LCL TPen class. If you missed ExtCreatePen or GetObject winapi functions - you can use them now too. If you don't understand something or just need more info then read msdn (ExtCreatePen), Qt help (QPen class reference) and Gtk reference manual (Graphics Contexts). If you want to look at TPen extensions yourself then launch our "Pen and Brush" example (I was inspired by a Qt Basic Drawing example when wrote it).

Compressed HTML help (CHM) in Freepascal

What are CHM files?

CHM files are html archives that are compressed using the LZX compression algorithm.

The Idea

In early 2000 something, there was a discussion about Lazarus and making the help system better. Many different ideas were thrown around but the one that caught my eye was CHM, to me it made sense.

So I began to search for a way to make Lazarus help available as CHM files. The Freepascal documentation: the Run Time Library(RTL), Free Component Library(FCL) and the Lazarus Documentation Lazarus Component Library(LCL) were and are, all available in html format either to download as a zip file or from a website for browsing. This was good because CHM's are just html files in a special archive so in theory it's easy to make CHM's from the existing HTML files.

A bunch of History

I used the MS HTML Help Workshop to make some CHM's from the existing html files. This worked just fine but already I was seeing a problem: CHM readers only exist for Windows.

I found a library, libchm, which was capable of reading and decompressing CHM files. I started working with that and in not too long I was able to extract any file from within a CHM file and display it. This was wonderful but still it was not a perfect solution since Lazarus, if it provided a CHM help system, would rely on an uncommon library.

So I searched using google for an explanation of the CHM file format and found a very detailed specification. http://www.speakeasy.org/~russotto/chm/
The real work began. I converted the LZX decompression code in chmlib from C to Pascal. At first it did not work, but with the help of Micha Nelissen I corrected the mistakes from the conversion and that was finished.

Next came the part which required actual understanding of the innermost workings of a CHM archive. This is when I realized that reading CHM files was not just one file to understand but many. I'll explain: We already know that a CHM file is an archive that contains compressed HTML documents, but how do we know which HTLM documents are included and where they are, or how big they are? CHM's have a document index which uses a tree structure to store information about the directory and files within. After some time I was able to read this structure and see a list of all files and directories in CHM's. Subsequently I realized that a CHM has files stored within it that are added when it is made, which contain information about the Table of Contents, Index, which file is the “Home page” of the CHM and many other disinteresting but important things. Understanding a CHM involves understanding these internal files of a chm.

The specification I referred to above had all the information I needed about reading a CHM's contents but not how to understand these other internal files. Google to the rescue. I found another website http://www.nongnu.org/chmspec/latest/ that had information about the internal files! Not much later I was able to open, extract, and show correctly chm files. All without any external library dependencies.

I was very pleased but the CHMs made by the MS HTML Workshop did not have a very helpful Table of Contents or Index. Additionally there was some discomfort on the part of Lazarus developers that the documentation could only be compiled on Windows PC's since many of the Lazarus developers only used Linux.

This is why several months later, I began work on a CHM compiler! During a two week period I converted more C code to Pascal so a LZX compressor existed for pascal, and wrote from scratch several units to write CHM files.

Now it is possible to write and read CHM's files. The code is included with Freepascal in the packages/chm folder. Also fpdoc the Freepascal documentation tool incorporates the ability to write CHM files.

A program was made (LHelp) and a package made for Lazarus to integrate CHM help. It did not gain popularity however. Why? I'm not sure but it could be because people didn't know it was there. It required setting up in the Lazarus which may have been too compilicated for some. But regardless two years go by.

Recent Progress

I had recently been distracted away from Lazarus development by life and not paying much attention to it's progress. Then an email on the mailinglist caught my eye. A Freepascal dev, Marco van de Voort, was working on integration CHM help into the FP ide. I immediately started reading the logs to find out what interest had been shown in CHM's.

So in the last few weeks I implemented something I had wanted to but as yet, not been motivated to do: I implemented creating and reading the search index CHM's can contain.

What does this mean? This means that now it is possible to author searchable CHM files in any os/platform that FreePascal supports and also read them, all with Pascal code and with no external library requirements.

In the not too distant future, Lazarus may by default use these CHM files to display help when you need it.