Lazarus Examples Window

From Free Pascal 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 - https://forum.lazarus.freepascal.org/index.php/topic,57680.0.html and is by no means finalized.

What should the user experience be like ?

  • A user should be able to choose to see content appropriate to their experience.
  • Be able to see a summary of what an Example is about before opening it.
  • Be able to open an Example, have a play with it, make a few changes and recompile to see what happens. Maybe roll back to the original Example if they make a full mess of it.
  • Examples should be generally short, contain appropriate, relevant code focused on one topic each. But there will be many exceptions to that.
  • If a user installs a third party package, eg via OPM or manually, then any examples it contains should be treated in the same manner.
  • Be useful to allow a user to browse through example content while working on a real project, copy and past a snipit as required.

How it Works

The Lazarus IDE Examples Window shows all (compliant) examples in a list, filterable by a category and searchable by name or keyword. As of Lazarus Main April 7th, it finds examples shipped with the Lazarus Source but few if any other packages. To allow the IDE to find and use an example in a package the following is needed -

  • The the example or examples in the package must have a suitable metadata file, its a simple JSON file with only a few fields.
  • The example must be self contained in its own directory (and any directories below it). A shared file, or one in a specific location in the package tree will NOT work.
  • The package must be installed in the IDE using either OPM or a manual install and the IDE can find it.
  • A small number of packages, due to their file structure, need some further additions to Lazarus to add a new field to their Package File.

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.

There is a rough and ready GUI app to make, edit and importantly, validate metadata files available at https://github.com/davidbannon/ExampleMetaData .

A standalone example ?

When user opens an example project (from the Example Window) it has been copied to a work area (in the Lazarus PCP) so if the example depends on other files from the package source tree, it won't find them. So, ensure all needed files are in or under the example top level directory. Sometimes, this may lead to duplication of files in the package tree but it is necessary for several reasons, firstly, Linux users using distro versions of Lazarus have all their examples in read only diskspace, secondly, its important that we can restore an example if the user messes it up badly. So, the user playing with the original example code is discouraged (but not prevented).

Can the IDE find the example ?

This is a question not completely answered at this stage. An example project, part of an installed package, will be found if -

  • It has a metadata file and
  • The package has its LPK file in the package top level directory or
  • The LPK file is in a lower directory and the LPK file has a valid OtherUnitsDirectory field that points to the toplevel directory (and possible down again, eg "../Other") or
  • The LPK file has a valid "ExampleDirectory" field showing how far down the LPK file is (ie '../../.');

The last option, ExampleDirectory, is not yet being written into an LPK file by the IDE but is read and used if present.

Notes

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


Legacy & Developer Information

  • There is some consideration of moving the core Lazarus examples to an on-line repo, such as https://gitlab.com/dbannon/laz_examples . At present, the code to do so is disabled because of problems in MacOS SSL but that repo is used if you click the View Project button. Not all Lazarus and no third party examples are there.

In the event that we re-introduce the On Line Examples model, the master.ex-meta file, regenerated frequently and downloadable from the repo to be cached locally would look like this - 

{ 
"LastUpDate" : "2021-10-19T11:44:41+11:00",

"Beginner/laz_hello" : {
    "Name" : "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.",

"Components/listview" : {
    "Name" : "ListView",
    "Category" : "Components",
    "Keywords" : ["TListView", "grid", "needs work"],
    "Description" : "A project that demonstrates some of a TListView's capabilities. Not so much a \"how to use\" as an exerciser of capabilities. Note, entering an invalid column number triggers a crash."

}

Note the date in ISO format, overall, the file is still reasonably human readable. And now, of course, its easily extendable. We could add a format version but I don't consider it necessary.

Retrieved from "http://wiki.freepascal.org/index.php?title=Lazarus_Examples_Window&oldid=156230"