Skip to content

Commit

Permalink
Add app anatomy.
Browse files Browse the repository at this point in the history
rhx committed Dec 30, 2023
1 parent 5290089 commit cee1675
Showing 4 changed files with 67 additions and 3 deletions.
40 changes: 38 additions & 2 deletions Sources/Gtk/Gtk.docc/Documentation.md
Original file line number Diff line number Diff line change
@@ -1,10 +1,46 @@
# Documentation

The documentation for SwiftGtk is written in DocC and contains tutorials
as well as reference documentation auto-generated from the `.gir` files.

You can generate documentation using the
[DocC plugin](https://apple.github.io/swift-docc-plugin/documentation/swiftdoccplugin/).
You can also read a current version of this documentation online
[https://rhx.github.io/SwiftGtk4Doc/](https://rhx.github.io/SwiftGtk4Doc/)

## Documentation Structure

The documentation structure for SwiftGtk follows the structure of the generated Swift source files.
For every [Object](/documentation/GLibObject/Object), there is a Swift
[Protocol](https://docs.swift.org/swift-book/documentation/the-swift-programming-language/protocols/)
that provides a default implementation of the Object's methods and properties.

>Tip: For the documentation, the use of Protocols means that the methods and properties
are usually documented in the `Default Implementations` Section towards the bottom
rather than the main section of the type documentation.

There are two concrete types that wrap the Object in Swift and inherit the protocol implementation:

- a `Ref` type (named after the type with a `Ref` suffix)
that simply provides a typed wrapper around the underlying C language pointer.
This type is typically returned by methods, functions, or properties that reference already
existing instances of a given Object, e.g. a ``/Gtk/MenuModelRef`` returned by the
``/Gtk/Application/menubar`` property or a list (``/GLib/RefList``) of ``/Gtk/WindowRef``
returned by the ``/Gtk/Application/windows`` property.

Memory management for `Ref` instances uses the underlying `GLib`/`Gtk` mechanisms, which in most
cases means that ``/GLibObject/ref`` and ``/GLibObject/unref`` calls need to be used for
reference counting and manual memory management.

- a class type (named after the type without a `Ref` suffix)
that provides a full Swift class implementation of the type.
For most Objects this means that memory is fully managed through Swift's [automatic reference counting]
(https://docs.swift.org/swift-book/documentation/the-swift-programming-language/automaticreferencecounting/)
mechanism.

For example, the documentation for the methods provided by ``/Gtk/Window``
can be found in the ``/Gtk/WindowProtocol`` article. The same is true for ``/Gtk/WindowRef``.

## Using DocC

To preview documentation matching your local installation, simply run
@@ -13,8 +49,8 @@ To preview documentation matching your local installation, simply run

then navigate to the URL shown for the local preview server. Make sure you have JavaScript enabled in your browser.

> Warning: If you have checked out a branch (such as `gtk4-monorepo`) that contains multiple targets,
you need to tell the Swift Package Manager to generate documentation for a particular target.
>Warning: If you have checked out a branch (such as `gtk4-monorepo`) that contains multiple targets,
you need to tell the Swift Package Manager to generate documentation for a particular target.

To generate and preview documentation for a particular target, use the `--target` option
to specify the specific target you are interested in. For example:
20 changes: 20 additions & 0 deletions Sources/Gtk/Gtk.docc/GtkAppAnatomy.md
Original file line number Diff line number Diff line change
@@ -0,0 +1,20 @@
# Anatomy of a Gtk Application

Gtk user interfaces consist of widgets.
Widgets are objects that derive from ``/GlibObject/Object``
and are organised in a hierarchical fashion, i.e.,
every widget is a container that can contain zero, one,
or sometimes more than one other widget.

The main container of a Gtk application is the ``/Gtk/ApplicationWindow``,
which is a subclass of ``Window`` that integrates with the actual ``/Gtk/Application``.
The user interface of an application is created by adding other widgets such as
``/Gtk/Button``s, text ``/Gtk/Entry`` fields, ``/Gtk/MenuBar``s and similar.
While it is possible to add widgets programmatically, a simpler
way is to create an XML `ui` file and use ``/Gtk/Builder`` to create the widgets
from the user interface file. There are tools you can use to design user interfaces
graphically, such as [Cambalache](https://flathub.org/apps/ar.xjuan.Cambalache)
for gtk4 (as well as gtk3) and [Glade](https://gitlab.gnome.org/GNOME/glade)
for gtk3 (but there are [recommendations to write user interface files by hand]
(https://blogs.gnome.org/christopherdavis/2020/11/19/glade-not-recommended/)).

4 changes: 3 additions & 1 deletion Sources/Gtk/Gtk.docc/Package.md
Original file line number Diff line number Diff line change
@@ -2,6 +2,7 @@

A Swift wrapper around gtk-3.x and gtk-4.x that is largely auto-generated from gobject-introspection.
This project tries to make gtk more "swifty" than using the plain C language interface.

For up to date (auto-generated) reference documentation, see [https://rhx.github.io/SwiftGtk/](https://rhx.github.io/SwiftGtk/).


@@ -28,9 +29,10 @@ which makes it more straightforward to keep up with changes in they underlying G
- <doc:Usage>
- <doc:Documentation>

### Tutorial
### Tutorials

- <doc:Tutorial>
- <doc:GtkAppAnatomy>

### Troubleshooting

6 changes: 6 additions & 0 deletions Sources/Gtk/Gtk.docc/Tutorial.md
Original file line number Diff line number Diff line change
@@ -189,3 +189,9 @@ should start, displaying a `Hello, World!` window.

>Tip: This project and the full source code can be found on GitHub:
[https://github.com/rhx/SwiftHelloGtk](https://github.com/rhx/SwiftHelloGtk/tree/gtk4-monorepo)

## Structure of a Gtk Application

The next part of the tutorial looks at the anatomy of a Gtk application:

<doc:GtkAppAnatomy>

0 comments on commit cee1675

Please sign in to comment.