add to README, add README for examples subdirectory

README.md

@@ -14,10 +14,22 @@ Most of the code for GLib support (`GType`, `GValue`, `GObject`, etc.) was copie
 
 Documentation for the master branch version of this package can be found [here](https://juliagtk.github.io/Gtk4.jl/dev/). Complete GTK documentation is available at [https://www.gtk.org/docs](https://www.gtk.org/docs).
 
+## Package scope and alternatives
+
+This package is intended to be a relatively thin wrapper of the GTK library based largely on GObject introspection, analogous to [PyGObject](https://pypi.org/project/PyGObject/). Using it beyond simple widgets requires some knowledge of the GTK API (the Gtk4.jl [documentation](https://juliagtk.github.io/Gtk4.jl/dev/) covers a small fraction of the API available through introspection). It is also very possible to crash or freeze Julia if you're not careful.
+
+Those seeking a more user friendly, well documented, curated GUI building experience based on GTK should consider using [Mousetrap](https://github.com/Clemapfel/mousetrap.jl). Other popular packages for creating desktop GUI interfaces include [QML.jl](https://github.com/JuliaGraphics/QML.jl), [Blink.jl](https://github.com/JuliaGizmos/Blink.jl), [Electron.jl](https://github.com/davidanthoff/Electron.jl), and [CImGui.jl](https://github.com/Gnimuc/CImGui.jl).
+
+## Related packages
+
+Other registered packages extend the functionality of Gtk4.jl:
+- [GtkObservables.jl](https://github.com/JuliaGizmos/GtkObservables.jl): provides integration with [Observables.jl](https://github.com/JuliaGizmos/Observables.jl). This can simplify making interactive GUI's with Gtk4.jl.
+- [Gtk4Makie.jl](https://github.com/JuliaGtk/Gtk4Makie.jl): provides integration with the popular plotting package [Makie.jl](https://github.com/MakieOrg/Makie.jl), specifically its interactive, high performance GLMakie backend. This allows you to include interactive plots in your GUI.
+
 ## Current status
 For auto-generated code, Gtk4.jl relies on GObject introspection data generated on a Linux x86_64 machine, which may result in code that crashes on 32 bit computers. This seems to affect mostly obscure parts of GLib that are unlikely to be useful to Julia users, but 32 bit users should be aware of this.
 
-Note that this package uses binaries for the GTK library and its dependencies that are built and packaged using [BinaryBuilder.jl](https://github.com/JuliaPackaging/BinaryBuilder.jl). On Linux it does **not** use the binaries that are packaged with your distribution. The build scripts for these binaries, including the library versions currently being used, can be found by perusing [Yggdrasil.jl](https://github.com/JuliaPackaging/Yggdrasil.jl).
+Note that this package uses binaries for the GTK library and its dependencies that are built and packaged using [BinaryBuilder.jl](https://github.com/JuliaPackaging/BinaryBuilder.jl). On Linux it does **not** use the binaries that are packaged with your distribution. The build scripts for the binaries used by Gtk4.jl, including the library versions currently being used, can be found by perusing [Yggdrasil.jl](https://github.com/JuliaPackaging/Yggdrasil.jl).
 
 ## Enabling GTK4's EGL backend (Linux)
 On Wayland, a Cairo-based fallback backend will be used unless you tell `libglvnd_jll` where to find libEGL. This can be done by setting the environment variable __EGL_VENDOR_LIBRARY_DIRS. See [here](https://gitlab.freedesktop.org/glvnd/libglvnd/-/blob/master/src/EGL/icd_enumeration.md) for details.
@@ -29,3 +41,4 @@ Gtk4.set_EGL_vendorlib_dirs("/usr/share/glvnd/egl_vendor.d")
 [ Info: Setting will take effect after restarting Julia.
 ```
 where "/usr/share/glvnd/egl_vendor.d" is a typical location for Mesa's libEGL (this should be modified if it's somewhere else on your distribution). Other vendor-provided libraries may be in other locations, and a colon-separated list of directories can be used for that situation. **Note that this has only been tested for the Mesa-provided libEGL on Fedora and Ubuntu.**
+

examples/README.md

@@ -0,0 +1,23 @@
+# Gtk4.jl Examples
+
+## Basic examples
+- `calculator4.jl` demonstrates a simple GUI with lots of buttons. Adapted from an example in Gtk.jl by Nand Vinchhi.
+- `css.jl` demonstrates widget styling using CSS.
+- `dialogs.jl` demonstrates various types of dialogs.
+
+## Drawing
+- `canvas.jl` demonstrates use of `GtkCanvas`, which allows drawing with Cairo. Also shows how to change the cursor when it's over a certain widget.
+- `canvas_cairomakie.jl` shows how to draw a CairoMakie plot into a `GtkCanvas`.
+- `glarea.jl` shows how to use the `GtkGLArea` widget to draw using OpenGL.
+
+## Lists
+- `filteredlistview.jl` demonstrates `GtkListView` to show a huge list of strings, with a `GtkSearchEntry` to filter what's shown.
+- `listbox.jl` demonstrates `GtkListBox` to show a huge list of strings. This widget is a little easier to use than `GtkListView`.
+- `listview.jl` demonstrates a simple way of using `GtkListView`.
+
+## Applications
+
+- `application.jl` is a simple example of using `GtkApplication` and `GAction`s.
+- `application2.jl` together with `application.jl` shows how to use remote actions with DBus. This probably only works on Linux.
+- The `ExampleApplication` subdirectory shows how to use Gtk4.jl with [PackageCompiler.jl](https://github.com/JuliaLang/PackageCompiler.jl).
+