Lazarus Examples Window

From Lazarus wiki
Jump to navigationJump to search

This wiki page now a reference for the new Example Window that exists, at present, in lazarus-main but not a release version. Its based on this forum thread -,57680.0.html and is by no means finalized.

For the end user

An end user gets to the Example Window after clicking the button on the Project Wizard screen or from the Tools Menu, "Example Projects". In either case they see a window offering a list of known examples. The list can be filtered by key words or by category (double click between category checkboxes turns all off).

The Example Window will allow the user to open, build (and edit) and run any example but note some have specific package requirements. Lazarus Source examples can be refreshed if necessary.

When opened, the examples from the Lazarus Source code are copied to a (user writable) area in the Lazarus Config directory (PCP) because, on some systems Lazarus Source is in read-only disk space. Further, this permits easy refresh of an example if the user makes changes.

Examples in the Lazarus Source

You can add an example anywhere you like in the Lazarus Source Tree, there are lots under ~/examples but also many associated with different Lazarus sub system. A few rules apply -

  • The Example Name must be unique within Lazarus (when lowercased).
  • The example should be self contained within its own directory. That directory (and any sub directories) will be copied to the work area so don't assume particular files are "just up one dir".
  • The example should have an Example Metadata File, with a file name that corresponds to the project name and an extension of .ex-meta. The content of this file is JSON and must have a name, a category and should have a (multiline) description and keywords. See below.

If you add a new example (or remove one) to the Lazarus Source Tree, the file ~/examples/examples.txt needs to be refreshed. Its plain text, edit it directly or generate a new one with this command (on a *nix )-

$> find . -name "*.ex-meta" > examples/examples.txt

Examples in Third Party Packages

Again, you are free to place your package examples directory where you like but in order for the Lazarus Examples Window to find it, some things must be provided, note, different rules than above !

  • The package must be currently installed in Lazarus (check ? see if its listed in (PCP)/
  • Your example should be in a directory of its own. You should not put more than one example in the same directory.
  • In the case of Package Examples, the example directory is not moved to a work area so it can (but perhaps should not) be dependent on local, relative path files.
  • It must have a Metadata File, see below.
  • The Package file, that is the .lpk file must have entry such as <ExamplesDirectory Value="../demo"/>, typically just below the Author item. The value is the relative path from the .lpk file to a directory containing your example or examples. eg -

(Personally, I would put demo1 in its own directory too but the above would work !)

Note that, at present, Lazarus, when making a package, does NOT create the ExamplesDirectory entry, it will, but its a work in progress. If you want to test, manually adding that entry is the way to go right now.

The Metadata File

All examples that appear in the Example Window have a json metadata file with an extension ".ex-meta" in the top level directory of the example (not the package). Without a valid metadata file, the example will not be listed in the Example Window. An individual example project file would look like this -

"Laz_Hello" : {
    "Category" : "Beginner",
    "Keywords" : ["Lazarus", "Hello World", "TButton", "TMemo"],
    "Description" : "This might be your first Lazarus project, its the traditional Hello World.  Two buttons have been dropped on the form, renamed and their captions set. A memo was then added and each button was double clicked and what they are expected to do was set."

In this case, the example project files would be in a subdirectory called laz_hello, same spelling but all lowercase consistent with Lazarus.

The three fields are free form text, there is no dictionary so, you are free to introduce both new Categories and new Key Words. Its desirable that we do not have too many Categories so, perhaps consider posting a message on the forum before using a new one ? At present, the following Categories are in use -

  • Beginner
  • General
  • TAChart
  • DBase
  • LazReport
  • ThirdParty

There is a rough and ready GUI app to make, edit and importantly, validate metadata files available at .

Can the IDE find the example ?

If the IDE does not find an example, some things to check for -

  • Does it have a metadata file ?
  • Is there a message about the metadata from console ?
  • If its a Lazarus Source example, is it mentioned in examples/examples.txt ?
  • if a Package Example, is it mentioned in (PCP)/ ? and in (PCP)/packagefiles.xml ?


The user can view the project content and, if they choose, build the project. Later, if the user users the Example Window to again open that project, they will be asked if they want to refresh it, doing so will erase any false edits they may have made.

Important to note -

  • Example Projects will not be displayed in the Examples Window unless they have a valid metadata file. An error is dropped to the console if a metadata file with bad json is encountered.
  • The original copy of the Example is not altered when the Example Window is used to open an Example. So, play away !
  • New examples can, potentially be added via the normal Gitlab pull request system.
  • Examples demonstrating aspects of third party packages are probably best added to that package rather than to Lazarus itself.

See also