Sign in Join
Wiki copytemporary

Lazarus Examples Window: what changed

Revision 2 to 3. Removed lines have a minus sign; added lines have a plus sign.

OldNewLine
1-The new Example Window that exists in Lazarus 3.0 and beyond is documented below.
1+The new Example Window that exists in Lazarus 3.0 and beyond is documented below.
22
33## For the end user
44
55### Introduction
66
7-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.
7+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.
88
9-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.
9+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.
1010
11-Feel free to edit or make changes to examples in Lazarus Source, if you totally mess up, its easily refreshed from the Examples Window.
11+Feel free to edit or make changes to examples in Lazarus Source, if you totally mess up, its easily refreshed from the Examples Window.
1212
1313### Examples in Packages
1414
15-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.
15+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 and/or an appropriate entry in their .lpk file. See below.
1616
1717### Displaying your own Examples
1818
19-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 -
19+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 -
2020
21-- Ensure each example is in its own directory and is self contained.
22-- Provide meta data files as described below. Perhaps set the category to something like "Private" ?
23-- 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.
24-- Examples mentioned in examples.txt are always copied to a work area ensuring write access and allowing you to play without affecting the original.
21+ * Ensure each example is in its own directory and is self contained.
22+ * Provide meta data files as described below. Perhaps set the category to something like "Private" ?
23+ * 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.
24+ * Examples mentioned in examples.txt are always copied to a work area ensuring write access and allowing you to play without affecting the original.
2525
2626### FPC Examples
2727
28-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.)
28+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.)
2929
3030## For the Developer
3131
3232### Examples in the Lazarus Source
3333
34-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 -
35-
36-- The Example Name must be unique within Lazarus (when lowercased).
37-- 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".
38-- 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.
34+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 -
3935
40-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 )-
36+ * The Example Name must be unique within Lazarus (when lowercased).
37+ * 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".
38+ * 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.
4139
42-```text
40+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 )-
41+```
4342$> find . -name "*.ex-meta" > examples/examples.txt
4443```
4544
45+The file is just plain text, each line specifying an ex-meta file and its path from the top of the Lazarus Source Tree. Windows and Mac users could, easily, edit it by hand. Lazarus does not search its own source tree for ex-meta file, for performance reasons it only looks in examples/examples.txt for source tree examples.
46+
4647### Examples in Third Party Packages
4748
48-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 !
49+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 !
4950
50-- The package must be currently installed in Lazarus (check ? see if its listed in ([[pcp|PCP]])/staticpackages.inc)
51-- Your example should be in a directory of its own. You should not put more than one example in the same directory.
52-- 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.
53-- It must have a Metadata File, see below.
54-- 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 -
51+ * The package must be currently installed in Lazarus (check ? see if its listed in ([[pcp|PCP]])/staticpackages.inc)
52+ * Your example should be in a directory of its own. You should not put more than one example in the same directory.
53+ * 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.
54+ * It must have a Metadata File, see below.
55+ * 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 -
5556
56-```text
57-[MyPackage]
58- [demo]
59- mypackage_demo1.ex-meta
60- ....
61- [demo2]
62- mypackage_demo2.ex-meta
57+```
58+// directory structure
59+ [MyPackage]
60+ [demo]
61+ mypackage_demo1.ex-meta
6362 ....
64- [package]
65- mypackage.lpk
63+ [demo2]
64+ mypackage_demo2.ex-meta
65+ ....
66+ [package]
67+ mypackage.lpk
6668```
6769
68-(Personally, I would put demo1 in its own directory too but the above would work !)
70+(Personally, I would put demo1 in its own directory too but the above would work !)
6971
70-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.
72+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.
7173
7274### The Metadata File
7375
74-> **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 )-
75->
76-> `$> find . -name "*.ex-meta" > examples/examples.txt`
77-
78-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 -
76+![Light bulb](https://upload.wikimedia.org/wikipedia/commons/d/d8/Nuvola_apps_ktip.png) **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 )-
77+```
78+$> find . -name "*.ex-meta" > examples/examples.txt
79+```
7980
80-```text
81+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 -
82+```
8183{
82-"Laz_Hello" : {
83- "Category" : "Beginner",
84- "Keywords" : ["Lazarus", "Hello World", "TButton", "TMemo"],
85- "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."
86-}
84+ "Laz_Hello" : {
85+ "Category" : "Beginner",
86+ "Keywords" : ["Lazarus", "Hello World", "TButton", "TMemo"],
87+ "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."}
88+ }
8789```
8890
89-In this case, the example project files would be in a subdirectory called laz_hello, same spelling but all lowercase consistent with Lazarus.
91+In this case, the example project files would be in a subdirectory called laz_hello, same spelling but all lowercase consistent with Lazarus. Note that JSOM requires you to escape **double inverted commas** , easier to use single inverted commas.
9092
91-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 -
93+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 -
9294
93-- Beginner
94-- General
95-- TAChart
96-- DBase
97-- LazReport
98-- ThirdParty
95+ * Beginner
96+ * General
97+ * TAChart
98+ * DBase
99+ * LazReport
100+ * ThirdParty
99101
100-There is a rough and ready GUI app to make, edit and importantly, validate metadata files available at <https://github.com/davidbannon/ExampleMetaData> .
102+There is a rough and ready GUI app to make, edit and importantly, validate metadata files available at <https://github.com/davidbannon/ExampleMetaData> .
101103
102-### Can the IDE find the example ?
104+### Can the IDE find the example ? Debugging
103105
104-If the IDE does not find an example, some things to check for -
106+If the IDE does not find an example, some things to check for -
105107
106-- Does it have a metadata file ?
107-- Is there a message about the metadata from console ?
108-- If its a Lazarus Source example, is it mentioned in examples/examples.txt ?
109-- 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.)
108+ * Does it have a metadata file ? Nothing happens without a meta data file.
109+ * Is there a message about the metadata on the **console** ? If there is a syntax problem in the JSON or missing data, there is a message in the console stream when the Examples Window is opened. Linux users can start Lazarus from the console and see that stream. Windows and Mac users need to capture that stream to a file. There are a number of on-line JSON parsers, paste your suspect ex-meta file in one.
110+ * If its a **Lazarus Source Example** , it must be mentioned in examples/examples.txt. This file, one directory down from the top of the Lazarus tree, lists all the examples in the standard Lazarus install. If its not in there, the Examples Window will not display it. Unix developers can easily regenerate this file with the 'find' command, Windows users will probably edit it by hand. Remember, Lazarus does not search for ex-meta files in its own source tree, it looks in examples/examples.txt
111+ * If a **Package Example, a third party example** , different rules apply. The ex-meta file must be mentioned in ([[pcp|PCP]])/staticpackages.inc file and in ([[pcp|PCP]])/packagefiles.xml file. Unlike the examples.txt file, do not manually edit these files, they should be updated when a package is installed into the the IDE if the package has an appropriate entry in its .lpk file, see above.
110112
111113## Notes
112114
113-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.
115+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.
114116
115-Important to note -
117+Important to note -
116118
117-- 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.
118-- The original copy of the Example is not altered when the Example Window is used to open an Example. So, play away !
119-- New examples can, potentially be added via the normal Gitlab pull request system.
120-- 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.
121-- Examples demonstrating aspects of third party packages are probably best added to that package rather than to Lazarus itself.
119+ * 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.
120+ * The original copy of the Example is not altered when the Example Window is used to open an Example. So, play away !
121+ * New examples can, potentially be added via the normal Gitlab pull request system.
122+ * 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.
123+ * Examples demonstrating aspects of third party packages are probably best added to that package rather than to Lazarus itself.
122124
123125## See also
124126
125-- <https://forum.lazarus.freepascal.org/index.php/topic,57680.0.html>
126-- <https://gitlab.com/freepascal.org/lazarus/lazarus/-/issues/37509>
127-- <https://gitlab.com/dbannon/laz_examples> - this is just a temp home.
128-- <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.
129-- <https://github.com/davidbannon/ExampleMetaData> - a very simple editor to make and validate the Example Meta Data files.
130-- <https://gitlab.com/freepascal.org/lazarus/lazarus/-/blob/main/components/exampleswindow/uexampledata.pas> the unit making decisions about your examples.
127+ * <https://forum.lazarus.freepascal.org/index.php/topic,57680.0.html>
128+ * <https://gitlab.com/freepascal.org/lazarus/lazarus/-/issues/37509>
129+ * <https://gitlab.com/dbannon/laz_examples> \- this is just a temp home.
130+ * <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.
131+ * <https://github.com/davidbannon/ExampleMetaData> \- a very simple editor to make and validate the Example Meta Data files.
132+ * <https://gitlab.com/freepascal.org/lazarus/lazarus/-/blob/main/components/exampleswindow/uexampledata.pas> the unit making decisions about your examples.
131133
132134---
133-*From the Free Pascal wiki, page "Lazarus Examples Window", as it stood on 2024-01-28 after a change by Dbannon, out of the wiki's dump of 2024-05-26. Copyright stays with the author who wrote it, according to the old wiki's [[Licensing]] page. If you have concerns about this material, [message the admin](/wiki-contact).*
134-Category: Development
135-Category: Example programs
136-Category: Proposals
135+*From the Free Pascal wiki, page "Lazarus Examples Window", as the Internet Archive kept it on 2025-03-17, last changed on 2025-03-07. Copyright stays with the author who wrote it, according to the old wiki's [[Licensing]] page. If you have concerns about this material, [message the admin](/wiki-contact).*

Back to history