Difference between revisions of "Lazarus Examples Window"

From Free Pascal wiki
Jump to navigationJump to search
(Restructure this page, its no longer a proposal, its under implementation)
(Other Examples)
 
(37 intermediate revisions by the same user not shown)
Line 2: Line 2:
  
  
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.
+
The new Example Window that exists in Lazarus 3.0 and beyond is documented below.
  
== What should the user experience be like ? ==
+
== For the end user ==
 +
===Introduction===
 +
A Lazarus 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 you 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). In basic use, it shows you all the examples shipped with Lazarus.
  
* A user should be able to choose to see content appropriate to their experience.
+
The Example Window will allow you to open, build (and edit) and run any example but note some have specific package requirements. When opened, the examples from the Lazarus Source code are copied to a (user writable) area in the Lazarus Config directory ([[pcp|PCP]]) because, on some systems Lazarus Source is in read-only disk space.  
* 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, 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 ==
+
Feel free to edit or make changes to examples in Lazarus Source, if you totally mess up, its easily refreshed from the Examples Window.
  
The Examples Window scans the Lazarus source tree looking for Example Metadata Files, any it finds are assumed to be in a directory that contains a project. Details (found in the metadata file) are shown to the user who can search for keywords or, if they know it, the Example project name. If the user double clicks on an Example, that example will be copied to a new dir under the Primary Config Path, PCP (configurable) and Lazarus advised to open it there.
+
===Examples in Packages===
 +
When you install a package that has compliant examples, they will also appear in the Lazarus Examples Window. If they don't appear, the most likely reason is that they do not have an example meta data file. See below.
  
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.
+
===Displaying your own Examples===
 +
If you have your own examples in one or more Lazarus projects, you can arrange to have them listed along with the built in examples supplied with Lazarus. Following the same rules as below, you would -
 +
* Ensure each example is in its own directory and is self contained.
 +
* Provide meta data files as described below. Perhaps set the category to something like "Private" ?
 +
* Add an entry to the ./examples/examples.txt file in your Lazarus Source directory. The entry, see the existing ones, should have a relative path from the top of the lazarus source directory to your meta data file. If you are using a packaged version of Lazarus then this examples.txt file might be in read only space and you will need administrative access to it.
 +
* Examples mentioned in examples.txt are always copied to a work area ensuring write access and allowing you to play without affecting the original.
  
The Example Window will also scan the PCP (or location where On-Line Package manager puts packages) so, any packages installed via the OPM that have Examples and a valid metadata file will be treated the same way.
+
===FPC Examples===
 +
FPC also provides a number of examples relating to its packages and RTL. These examples are generally command line driven and don't have the Lazarus project information so are unsuited to working with the Lazarus Examples Window. (It might be nice to find a way to display them however.)
  
Important to note -
+
== For the Developer ==
* 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 no 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 OPM packages are probably best added to that that package rather than to Lazarus itself.
 
  
== The Meta Data File ==
+
=== Examples in the Lazarus Source ===
All Examples that appear in the Example Window have a json metadata file with an extension ".ex-meta". Without a valid metadata file, the Example will not be listed in the Example Window. An individual example project file would look like this -
 
  
<syntaxhighlight lang=text>{
+
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 -
"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."
 
}</syntaxhighlight>
 
  
In this case, the example project files would be in a subdirectory called laz_hello, same spelling but all lowercase consistent with Lazarus.  
+
* 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.
  
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 ?
+
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 )-
  
The Example Window searches the Lazarus Source Tree and the Primary Config Path for metadata files. The PCP because that way, it can find Examples bundled with On-Line Package Manager packages.
+
$> find . -name "*.ex-meta" > examples/examples.txt
  
There is a rough and ready GUI app to manage the metadata file processes, its aimed at the larger process but should be, soon, turned into a general purpose tool to create and validate a metadata file and thats all.
+
=== 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|PCP]])/staticpackages.inc)
 +
* 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 -
 +
[MyPackage]
 +
    [demo]
 +
        mypackage_demo1.ex-meta
 +
        ....
 +
        [demo2]
 +
            mypackage_demo2.ex-meta
 +
            ....
 +
    [package]
 +
        mypackage.lpk
  
 +
(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.
  
= Legacy Information =
+
=== The Metadata File ===
  
 +
{{Note| 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 from the top level Lazarus directory (on a *nix )-
  
== Progress Report Dating back to Development Stages ==
+
$> find . -name "*.ex-meta" > examples/examples.txt
 +
}}
  
March 8th, 2022
+
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 -
  
* A working prototype can now be found at https://gitlab.com/dbannon/lazarus/-/tree/newexamples - this uses Examples in the Source Code, its not On-Line.
+
<syntaxhighlight lang=text>{
* You should git clone or download https://gitlab.com/dbannon/lazarus/-/archive/newexamples/lazarus-newexamples.zip - that will get you an almost current trunk Lazarus with the 'old' Examples Window replaced with the new one and all the examples in ~/examples visible, usable and working.
+
"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."
 +
}</syntaxhighlight>
  
* Compile the above with the usual "make bigide"
+
In this case, the example project files would be in a subdirectory called laz_hello, same spelling but all lowercase consistent with Lazarus.  
* Start it up, remember to set an alternative config path so not to overwrite your usual Lazarus.
 
* in the IDE, go to Package -> Open Package File (.lpk) and browse to where you downloaded to, components/exampleswindow/exampleprojects.lpk and open that, click Use->Install and let i rebuild as usual.
 
* In use, there is a menu entry, Tools->Example Projects or in the startup mode with a project loaded, the ProjectWizard has an Example Projects button.
 
  
 +
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
  
* Most if not all of the viable examples in Laz-Dir/examples have now been categorized and have a metadata file. Some 104 projects made it through.
+
There is a rough and ready GUI app to make, edit and importantly, validate metadata files available at https://github.com/davidbannon/ExampleMetaData .
  
'''Still to do -'''
+
=== Can the IDE find the example ?===
* Process the remaining Examples in the Lazarus Source, about 200 ?
 
* Encourage third party package maintainers to add a metadata file if they have examples.[[File:NewLazExWin.png]]
 
  
== Why is there a problem ? ==
+
If the IDE does not find an example, some things to check for -
  
The existing Examples system has issues, perhaps in that it has not keep up Lazarus's own rapid development. There are a number of issues identified (in no particular order) -
+
* Does it have a metadata file ?
* Linux Lazarus installs based on (distro) Packages have the Examples in read only space.
+
* Is there a message about the metadata from console ?
* Most Examples do not have any indication of the topic covered other than file/project name.
+
* If its a Lazarus Source example, is it mentioned in examples/examples.txt ?
* Examples don't have a category system identifying who target audience is, beginner to advanced user.
+
* if a Package Example, is it mentioned in ([[pcp|PCP]])/staticpackages.inc ? and in ([[pcp|PCP]])/packagefiles.xml ? (Unlike the examples.txt file, do not manually edit these files, they should be updated when a package is installed into the the IDE.)
* Many examples are outdated, many don't, for example use the Lazarus Form Designer confusing new users who expect to see Object Inspector content.
 
* The system is limited to only those examples shipped in the main Lazarus distribution, cannot cover eg Examples applicable to OPM.
 
  
 +
==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 -
== Methodology ==
+
* 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.  
There appears to be two broad models available, each with their own advantages and disadvantages. Choosing one or the other model and determining what our metadata file looks like is the next phase.
+
* When examples are added to or removed from the Lazarus Source, changes need be made to the (eg) ~/lazarus_3_0/examples/examples.txt file. See the Metadata section.
 
+
* Examples demonstrating aspects of third party packages are probably best added to that package rather than to Lazarus itself.
Its likely that the metadata design is substantially the same either model.
 
 
 
Both Example Model will require -
 
* An extensive review of all existing Examples is required (for both models).
 
* Additional of a metadata file.
 
* A call for more Examples.
 
* A means to scan for 'other' Examples, such as ones in OPM packages.
 
 
 
=== Examples Remain in Distribution. ===
 
 
 
This is the KISS solution, it involves the least structural change but may not necessarily involve less work. As well as reviewing and adding meta data, we may wish to re-organize the location of packages.
 
 
 
It would make sense to still move a selected project from its location in the SRC tree to (eg) Lazarus config area to to -
 
* Solve the Linux Read Only problem and
 
* allow a user who has edited an example project excessively to "roll back" and start again.
 
* continuity if the user updates their Lazarus.
 
 
 
The Process is probably to add the meta data to each existing project over time and eventually, when that is all done, alter the existing Lazarus Examples Window to use the new model. The metadata file will aide the existing Lazarus Example Window but will do no harm either.
 
 
 
The down sides of this approach are -
 
 
 
* An end user cannot browse the Examples (online). They will need to close a project they are working on, find the relevant Example and open it in Lazarus.
 
* The changes that must happen to the existing Examples will need extensive Lazarus Developer involvement. Either one very scary diff or lots of somewhat smaller ones.
 
 
 
=== Examples move on-line ===
 
 
 
Possibly a simpler change because much of it is implemented externally, at some stage the Examples Window will need to be changed in the Lazarus Distro but lots of building, adjusting of existing Examples, testing can happen without annoying Lazarus Developers.
 
 
 
Prototype code to download files, index projects and build a master metadata file already exists.
 
 
 
A very rough and ready '''example example repository''' has been established at https://gitlab.com/dbannon/laz_examples
 
 
 
The process would be to complete the metadata and testing of all Examples. Next the existing gitlab tree at under dbannon would move to being under the FPC/Lazarus, finally, the Lazarus Examples Window would change to point to the Examples in the official gitlab tree. At some stage, the existing Examples would be removed from the Lazarus SRC, perhaps leaving a small representative number.
 
 
 
'''The downsides of this approach''' -
 
 
 
* Its a drastic structural change.
 
* And end user requires network access to download an Example.
 
 
 
=== Using the Demo App ===
 
 
 
Firstly, you can [https://gitlab.com/dbannon/laz_examples browse the repository], just looking for snipits of code, you can download a particular Example directory as a zip file and use it locally. This is perhaps, for many users, easier than closing their existing project, opening up the example, seeing what they are looking for and going back to their real project and continuing working. But you need online access....
 
 
 
An application now exists that makes creating and managing the metadata files. We'll call it EMT, Example Management Tool, https://gitlab.com/dbannon/laz_examples/-/tree/main/Utility/ExScanner . It will copy a project's files into a ready to push git directory. The process is -
 
 
 
* Check the default directories in EMT, they are set to suit me, probably not you !
 
 
 
* In EMT, press the Set button and point to the directory containing the example you plan to test and process. Important you do this before compiling the project otherwise you will be trying to add compiled binary files.
 
 
 
* Open that project in Lazarus, make sure it works, does what it appears to claim to do and if all OK, fill in the meta data in EMT, if the project has a readme.txt file, use at least some of its content. Click Save.
 
 
 
EMT will also allow you the directly edit a metadata file and save it back where it came from. And it incorporates a '''draft Lazarus Examples Windows''', a prototype of what may go into Lazarus eventually.
 
 
 
 
 
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 -
 
<syntaxhighlight lang=text>{
 
"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."
 
 
 
}</syntaxhighlight>
 
 
 
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.
 
  
 
== See also ==
 
== See also ==
Line 165: Line 113:
 
* https://gitlab.com/freepascal.org/lazarus/lazarus/-/issues/37509
 
* https://gitlab.com/freepascal.org/lazarus/lazarus/-/issues/37509
 
* https://gitlab.com/dbannon/laz_examples - this is just a temp home.
 
* https://gitlab.com/dbannon/laz_examples - this is just a temp home.
 +
* https://gitlab.com/dbannon/laz_examples/-/tree/main/Utility/ExScanner - a tool for manipulating Example Projects in and around the Lazarus Src Tree. Probably past its use by date. Also has a framework to 'exercise' the Lazarus Examples Window in a stand alone, easier to manage environment.
 +
* https://github.com/davidbannon/ExampleMetaData - a very simple editor to make and validate the Example Meta Data files.
 +
* https://gitlab.com/freepascal.org/lazarus/lazarus/-/blob/main/components/exampleswindow/uexampledata.pas the unit making decisions about your examples.
 +
  
  

Latest revision as of 01:33, 28 January 2024


The new Example Window that exists in Lazarus 3.0 and beyond is documented below.

For the end user

Introduction

A Lazarus 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 you 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). In basic use, it shows you all the examples shipped with Lazarus.

The Example Window will allow you to open, build (and edit) and run any example but note some have specific package requirements. 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.

Feel free to edit or make changes to examples in Lazarus Source, if you totally mess up, its easily refreshed from the Examples Window.

Examples in Packages

When you install a package that has compliant examples, they will also appear in the Lazarus Examples Window. If they don't appear, the most likely reason is that they do not have an example meta data file. See below.

Displaying your own Examples

If you have your own examples in one or more Lazarus projects, you can arrange to have them listed along with the built in examples supplied with Lazarus. Following the same rules as below, you would -

  • Ensure each example is in its own directory and is self contained.
  • Provide meta data files as described below. Perhaps set the category to something like "Private" ?
  • Add an entry to the ./examples/examples.txt file in your Lazarus Source directory. The entry, see the existing ones, should have a relative path from the top of the lazarus source directory to your meta data file. If you are using a packaged version of Lazarus then this examples.txt file might be in read only space and you will need administrative access to it.
  • Examples mentioned in examples.txt are always copied to a work area ensuring write access and allowing you to play without affecting the original.

FPC Examples

FPC also provides a number of examples relating to its packages and RTL. These examples are generally command line driven and don't have the Lazarus project information so are unsuited to working with the Lazarus Examples Window. (It might be nice to find a way to display them however.)

For the Developer

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)/staticpackages.inc)
  • 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 -
[MyPackage]
    [demo]
        mypackage_demo1.ex-meta
        ....
        [demo2]
            mypackage_demo2.ex-meta
            ....
    [package]
        mypackage.lpk

(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

Light bulb  Note: 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 from the top level Lazarus directory (on a *nix )-

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

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 https://github.com/davidbannon/ExampleMetaData .

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)/staticpackages.inc ? and in (PCP)/packagefiles.xml ? (Unlike the examples.txt file, do not manually edit these files, they should be updated when a package is installed into the the IDE.)

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.
  • When examples are added to or removed from the Lazarus Source, changes need be made to the (eg) ~/lazarus_3_0/examples/examples.txt file. See the Metadata section.
  • Examples demonstrating aspects of third party packages are probably best added to that package rather than to Lazarus itself.

See also