mirror of
https://github.com/ToshioCP/Gtk4-tutorial.git
synced 2025-01-29 20:34:16 +01:00
Update links to API references.
This commit is contained in:
parent
1beb9acefb
commit
42396e46e5
36 changed files with 133 additions and 95 deletions
44
Readme.md
44
Readme.md
|
@ -1,5 +1,7 @@
|
|||
# Gtk4 Tutorial for beginners
|
||||
|
||||
#### Contents of this repository
|
||||
|
||||
This tutorial illustrates how to write C programs with Gtk4 library.
|
||||
It focuses on beginners so the contents are limited to basic things.
|
||||
The table of contents are shown at the end of this abstract.
|
||||
|
@ -9,26 +11,42 @@ The table of contents are shown at the end of this abstract.
|
|||
- Section 24 to 27 describes list model and list view (GtkListView, GtkGridView and GtkColumnView).
|
||||
It also describes GtkExpression.
|
||||
|
||||
Please refer to [Gtk reference manual](https://developer.gnome.org/gtk4/stable/index.html)
|
||||
and [Gnome Developer Center](https://developer.gnome.org/) for further topics.
|
||||
|
||||
If you want to know about GObject and type system, refer to [GObject tutorial](https://github.com/ToshioCP/Gobject-tutorial).
|
||||
It includes the initialization and destruction process of GObject class and instances.
|
||||
These knowledge is necessary to write gtk4 programs.
|
||||
|
||||
This tutorial is under development and unstable.
|
||||
Even though the codes of the examples have been tested on gtk4 version 4.0, there might exist bugs.
|
||||
If you find any bugs, errors or mistakes in the tutorial and C examples, please let me know.
|
||||
You can post it to [github issues](https://github.com/ToshioCP/Gtk4-tutorial/issues).
|
||||
The latest version of the tutorial is located at [Gtk4-tutorial github repository](https://github.com/ToshioCP/Gtk4-tutorial).
|
||||
You can read it without download.
|
||||
|
||||
If you want to get a html or pdf version, you can make them with `rake`, which is a ruby version of make.
|
||||
There is a documentation \("[How to build Gtk4 Tutorial](gfm/Readme_for_developers.md)"\) that describes how to make them.
|
||||
#### Gtk4 Documentation
|
||||
|
||||
Please refer to [Gtk API Reference](https://docs.gtk.org/gtk4/index.html)
|
||||
and [Gnome Developer Documentation Website](https://developer.gnome.org/) for further topics.
|
||||
|
||||
These websites are newly opend lately (Aug/2021).
|
||||
The old documentation is located at [Gtk Reference Manual](https://developer-old.gnome.org/gdk4/stable/) and [Gnome Developer Center](https://developer-old.gnome.org/).
|
||||
The new website is in progress at present, so you might need to refer to the old version.
|
||||
|
||||
If you want to know about GObject and type system, refer to [GObject tutorial](https://github.com/ToshioCP/Gobject-tutorial).
|
||||
They are basic and also necessary to write Gtk4 programs.
|
||||
|
||||
#### Contribution
|
||||
|
||||
This tutorial is under development and unstable.
|
||||
Even though the codes of the examples have been tested on Gtk4 version 4.0, there might exist bugs.
|
||||
If you find any bugs, errors or mistakes in the tutorial and C examples, please let me know.
|
||||
You can post it to [github issues](https://github.com/ToshioCP/Gtk4-tutorial/issues).
|
||||
You can also post corrected files as a commit to [pull request](https://github.com/ToshioCP/Gtk4-tutorial/pulls).
|
||||
When you make corrections, correct the source files, which are under the 'src' directory.
|
||||
And run rake, then GFM files under the 'gfm' directory are automatically updated.
|
||||
|
||||
If you have a question, feel free to post it to the issue.
|
||||
Any question is helpful to make this tutorial get better.
|
||||
|
||||
#### How to get a HTML or PDF version
|
||||
|
||||
If you want to get a HTML or PDF version, you can make them with `rake`, which is a ruby version of make.
|
||||
Type `rake html` for HTML.
|
||||
Type `rake pdf` for PDF.
|
||||
There is a documentation \("[How to build Gtk4 Tutorial](gfm/Readme_for_developers.md)"\) that describes how to make them.
|
||||
|
||||
|
||||
## Table of contents
|
||||
|
||||
1. [Prerequisite and License](gfm/sec1.md)
|
||||
|
|
|
@ -91,7 +91,7 @@ Signals are registered in the class initialization function.
|
|||
The signal "change-file" has no default handler (object method handler).
|
||||
You usually don't need to set a default handler.
|
||||
If you need it, use `g_signal_new_class_handler` function.
|
||||
See [GObject reference manual](https://developer.gnome.org/gobject/stable/gobject-Signals.html#g-signal-new-class-handler) for further information.
|
||||
See [GObject API Reference, g\_signal\_new\_class\_handler](https://docs.gtk.org/gobject/func.signal_new_class_handler.html) for further information.
|
||||
- The return value of `g_signal_new` is the signal id.
|
||||
The type of signal id is guint, which is the same as unsigned int.
|
||||
It is used in the function `g_signal_emit`.
|
||||
|
@ -101,7 +101,7 @@ This signal has a parameter.
|
|||
"open-response" signal has one parameter.
|
||||
- 25: The type of the parameter.
|
||||
`G_TYPE_INT` is a type of integer.
|
||||
Such fundamental types are described in [GObject reference manual](https://developer.gnome.org/gobject/stable/gobject-Type-Information.html).
|
||||
Such fundamental types are described in [GObject reference manual](https://developer-old.gnome.org/gobject/stable/gobject-Type-Information.html).
|
||||
|
||||
The handlers are declared as follows.
|
||||
|
||||
|
|
|
@ -115,7 +115,8 @@ Each function is defined as follows.
|
|||
Just returns the value from the function `g_object_new` but casts it to the pointer to GtkWidget.
|
||||
Initialization is done in `tfe_text_view_init` which is called in the process of `g_object_new` function.
|
||||
- 1-21: `tfe_text_view_new_with_file` function.
|
||||
- 3: `g_return_val_if_fail` is described in [Glib reference manual](https://developer.gnome.org/glib/stable/glib-Warnings-and-Assertions.html#g-return-val-if-fail).
|
||||
- 3: `g_return_val_if_fail` is described in [GLib API Reference, g\_return\_val\_if\_fail](https://docs.gtk.org/glib/func.return_val_if_fail.html).
|
||||
And also [GLib API Reference, Message Logging](https://docs.gtk.org/glib/logging.html).
|
||||
It tests whether the argument `file` is a pointer to GFile.
|
||||
If it's true, then the program goes on to the next line.
|
||||
If it's false, then it returns NULL (the second argument) immediately.
|
||||
|
@ -438,7 +439,7 @@ The important thing is to duplicate `tv->file`.
|
|||
Otherwise, if the caller frees the GFile object, `tv->file` is no more guaranteed to point the GFile.
|
||||
Another reason to use `g_file_dup` is that GFile isn't thread-safe.
|
||||
If you use GFile in the different thread, the duplication is necessary.
|
||||
See [Gio reference manual](https://developer.gnome.org/gio/stable/GFile.html#g-file-dup).
|
||||
See [Gio API Reference, g\_file\_dup](https://docs.gtk.org/gio/method.File.dup.html).
|
||||
|
||||
## The API document and source file of tfetextview.c
|
||||
|
||||
|
|
|
@ -199,7 +199,7 @@ On the other hand, when an instance of GObject (not GInitiallyUnowned) is create
|
|||
And the instance has a normal reference count instead of floating reference.
|
||||
|
||||
If you use `g_object_unref` to an instance that has a floating reference, you need to convert the floating reference to a normal reference in advance.
|
||||
See [GObject reference manual](https://developer.gnome.org/gobject/stable/gobject-The-Base-Object-Type.html#gobject-The-Base-Object-Type.description) for further information.
|
||||
See [GObject Reference Manual](https://developer-old.gnome.org/gobject/stable/gobject-The-Base-Object-Type.html#gobject-The-Base-Object-Type.description) for further information.
|
||||
|
||||
## notebook\_page\_close
|
||||
|
||||
|
|
|
@ -124,7 +124,7 @@ textview {color: yellow; ...}
|
|||
~~~
|
||||
|
||||
Class, ID and some other things can be applied to the selector like Web CSS.
|
||||
Refer [Gtk4 reference manual](https://developer.gnome.org/gtk4/stable/theming.html) for further information.
|
||||
Refer to [Gtk4 API Reference, CSS in Gtk](https://docs.gtk.org/gtk4/css-overview.html) for further information.
|
||||
|
||||
In line 30, the CSS is a string.
|
||||
|
||||
|
@ -306,7 +306,7 @@ In this file, just the source file names are modified from the prior version.
|
|||
|
||||
## source files
|
||||
|
||||
The [source files](https://github.com/ToshioCP/Gtk4-tutorial/tree/main/src/tfe5) of the text editor `tfe` will be shown in the next section.
|
||||
The [source files](../src/tfe5) of the text editor `tfe` will be shown in the next section.
|
||||
|
||||
You can also download the files from the [repository](https://github.com/ToshioCP/Gtk4-tutorial).
|
||||
There are two options.
|
||||
|
|
|
@ -195,7 +195,7 @@ Therefore, `act_quit` has a name "quit" and no parameter.
|
|||
- 17: Adds the action to GtkApplication `app`.
|
||||
GtkApplication implements an interface GActionMap and GActionGroup.
|
||||
GtkApplication (GActionMap) can have a group of actions and the actions are added with the function `g_action_map_add_action`.
|
||||
This function is described in [GMenuModel section in GIO reference manual](https://developer.gnome.org/gio/stable/GActionMap.html#g-action-map-add-action).
|
||||
This function is described in [Gio API Reference, g\_action\_map\_add\_action](https://docs.gtk.org/gio/method.ActionMap.add_action.html).
|
||||
- 18: Connects "activate" signal of the action and the handler `quit_activated`.
|
||||
- 20-23: Creates GMenu and GMenuItem instances.
|
||||
`menubar` and `menu` are GMenu.
|
||||
|
|
10
gfm/sec2.md
10
gfm/sec2.md
|
@ -7,8 +7,8 @@ This section describes how to install Gtk4 into Linux distributions.
|
|||
This tutorial including this section is without any warranty.
|
||||
If you install Gtk4 to your computer, do it at your own risk.
|
||||
|
||||
This section is written on 13/June/2021.
|
||||
"At present" means 13/June/2021 in this section.
|
||||
This section is written on 12/August/2021.
|
||||
"At present" means 12/August/2021 in this section.
|
||||
|
||||
There are three possible way to install Gtk4.
|
||||
|
||||
|
@ -38,7 +38,7 @@ At present, the version of Gtk4 on Ubuntu 21.04 is 4.0.3.
|
|||
|
||||
I installed Gtk4 in January 2021.
|
||||
So, the following is old information, especially for the version of each software.
|
||||
For the latest information, see [Gtk gitlab repository](https://gitlab.gnome.org/GNOME/gtk) and [Gtk official web site](https://docs.gtk.org/gtk4/building.html).
|
||||
For the latest information, see [Gtk API Reference, Building GTK](https://docs.gtk.org/gtk4/building.html).
|
||||
|
||||
### Prerequisites for Gtk4 installation
|
||||
|
||||
|
@ -53,7 +53,7 @@ I installed Gtk4 under the directory `$HOME/local`.
|
|||
This is a private user area.
|
||||
|
||||
If you want to install it in the system area, `/opt/gtk4` is one of good choices.
|
||||
[Gtk4 reference manual](https://developer.gnome.org/gtk4/stable/gtk-building.html) gives an installation example to `/opt/gtk4`.
|
||||
[Gtk API Reference, Building GTK](https://docs.gtk.org/gtk4/building.html) gives an installation example to `/opt/gtk4`.
|
||||
|
||||
Don't install it to `/usr/local` which is the default.
|
||||
It is used by Ubuntu applications, which are not build on Gtk4.
|
||||
|
@ -186,7 +186,7 @@ Compile and install it.
|
|||
$ ninja -C _build
|
||||
$ ninja -C _build install
|
||||
|
||||
If you want to know more information, refer to [Gtk4 reference manual](https://developer.gnome.org/gtk4/stable/gtk-building.html).
|
||||
If you want to know more information, refer to [Gtk4 API Reference, Building GTK](https://docs.gtk.org/gtk4/building.html).
|
||||
|
||||
### Modify env.sh
|
||||
|
||||
|
|
|
@ -870,7 +870,7 @@ PANGO\_SCALE is defined as 1024.
|
|||
Therefore, 10*PANGO\_SCALE is 10240.
|
||||
- 91: calls `set_font_for_display` to set CSS for the GdkDisplay.
|
||||
|
||||
For further information, see [Pango reference manual](https://developer.gnome.org/pango/1.46/).
|
||||
For further information, see [Pango API Reference](https://docs.gtk.org/Pango/).
|
||||
|
||||
## GSettings
|
||||
|
||||
|
@ -930,13 +930,13 @@ For example,
|
|||
~~~
|
||||
|
||||
- 4: The type attribute is "s".
|
||||
It is [GVariant format string](https://developer.gnome.org/glib/stable/gvariant-format-strings.html).
|
||||
It is [GLib API Reference, GVariant Type Strings](https://docs.gtk.org/glib/struct.VariantType.html#gvariant-type-strings).
|
||||
Other common types are:
|
||||
- "b": gboolean
|
||||
- "i": gint32.
|
||||
- "d": double.
|
||||
|
||||
Further information is in [Glib reference manual](https://developer.gnome.org/glib/stable/gvariant-format-strings.html).
|
||||
Further information is in [Glib API Reference, VarientType](https://docs.gtk.org/glib/struct.VariantType.html).
|
||||
|
||||
### gsettings
|
||||
|
||||
|
@ -1066,7 +1066,7 @@ A path determines where the settings are stored in the conceptual global tree of
|
|||
An id identifies the schema.
|
||||
- 4: Key tag has two attributes.
|
||||
Name is the name of the key.
|
||||
Type is the type of the value of the key and specified with [GVariant format string](https://developer.gnome.org/glib/stable/gvariant-format-strings.html).
|
||||
Type is the type of the value of the key and specified with [GLib API Reference, VariantType](https://docs.gtk.org/glib/struct.VariantType.html).
|
||||
- 5: default value of the key `font` is `Monospace 12`.
|
||||
- 6: Summery and description elements describes the key.
|
||||
They are optional, but it is recommended to add them in the XML file.
|
||||
|
|
|
@ -176,7 +176,7 @@ The two functions `app_activate` and `draw_function` is important in this exampl
|
|||
GtkDrawingArea widget uses the function to draw the contents of itself whenever its necessary.
|
||||
For example, when a user drag a mouse pointer and resize a top-level window, GtkDrawingArea also changes the size.
|
||||
Then, the whole window needs to be redrawn.
|
||||
For the information of `gtk_drawing_area_set_draw_func`, see [Gtk4 reference manual](https://developer.gnome.org/gtk4/stable/GtkDrawingArea.html#gtk-drawing-area-set-draw-func).
|
||||
For the information of `gtk_drawing_area_set_draw_func`, see [Gtk API Reference, gtk\_drawing\_area\_set\_draw\_func](https://docs.gtk.org/gtk4/method.DrawingArea.set_draw_func.html).
|
||||
|
||||
The drawing function has five parameters.
|
||||
|
||||
|
|
|
@ -263,13 +263,13 @@ So, it is necessary to include it by `#include <math.h>` and also link the libra
|
|||
- 6: Gets gtk4 library.
|
||||
- 8: Gets gnome module.
|
||||
Module is a system provided by meson.
|
||||
See [Meson build system website](https://mesonbuild.com/Gnome-module.html#gnome-module) for further information.
|
||||
See [Meson build system website, GNUME module](https://mesonbuild.com/Gnome-module.html#gnome-module) for further information.
|
||||
- 9: Compiles ui file to C source file according to the XML file `turtle.gresource.xml`.
|
||||
- 11: Gets flex.
|
||||
- 12: Gets bison.
|
||||
- 13: Compiles `turtle.y` to `turtle_parser.c` and `turtle_parser.h` by bison.
|
||||
The function `custom_target` creates a custom top level target.
|
||||
See [Meson build system website](https://mesonbuild.com/Reference-manual.html#custom_target) for further information.
|
||||
See [Meson build system website, custom target](https://mesonbuild.com/Reference-manual.html#custom_target) for further information.
|
||||
- 14: Compiles `turtle.lex` to `turtle_lex.c` by flex.
|
||||
- 16: Specifies C source files.
|
||||
- 18: Compiles C source files including generated files by glib-compile-resources, bison and flex.
|
||||
|
|
|
@ -3,7 +3,7 @@ Up: [Readme.md](../Readme.md), Prev: [Section 24](sec24.md), Next: [Section 26]
|
|||
# GtkListView
|
||||
|
||||
Gtk4 has added new list objects GtkListView, GtkGridView and GtkColumnView.
|
||||
The new feature is described in the sections "GListModel support" and "List-based widgets" at the top of [the third chapter of Gtk4 reference manual](https://developer.gnome.org/gtk4/stable/gtkobjects.html).
|
||||
The new feature is described in [Gtk API Reference, List Widget Overview](https://docs.gtk.org/gtk4/section-list-widget.html).
|
||||
|
||||
Gtk4 has other means to implement lists.
|
||||
They are GtkListBox and GtkTreeView which are took over from Gtk3.
|
||||
|
@ -59,7 +59,7 @@ There are functions to add items to the list or remove items from the list.
|
|||
- `gtk_string_list_remove` removes an item from the list
|
||||
- `gtk_string_list_get_string` gets a string in the list
|
||||
|
||||
See [Gtk4 reference manual](https://developer.gnome.org/gtk4/stable/GtkStringList.html) for further information.
|
||||
See [Gtk4 API Reference, GtkStringList](https://docs.gtk.org/gtk4/class.StringList.html) for further information.
|
||||
|
||||
I'll explain the other list objects later.
|
||||
|
||||
|
|
|
@ -284,7 +284,7 @@ So, the change of the text in `entry` makes the "label" property reflect it imme
|
|||
|
||||
Closure expression calls closure when it is evaluated.
|
||||
A closure is a generic representation of a callback (a pointer to a function).
|
||||
For information about closure, see [GObject reference manual](https://developer.gnome.org/gobject/stable/chapter-signal.html#closure).
|
||||
For information about closure, see [GObject API Reference, The GObject messaging system](https://docs.gtk.org/gobject/concepts.html#the-gobject-messaging-system).
|
||||
A closure expression is created with `gtk_cclosure_expression_new` function.
|
||||
|
||||
~~~C
|
||||
|
|
|
@ -140,13 +140,13 @@ The function `g_signal_connect` has four arguments.
|
|||
4. Data to pass to the handler. If no data is necessary, NULL should be given.
|
||||
|
||||
You can find the description of each signal in the API reference manual.
|
||||
For example, "activate" signal is in GApplication section in [GIO reference manual](https://developer.gnome.org/gio/stable/GApplication.html#GApplication-activate).
|
||||
For example, "activate" signal is in GApplication section in [GIO API Reference](https://docs.gtk.org/gio/signal.Application.activate.html).
|
||||
The handler function is described in it.
|
||||
|
||||
In addition, `g_signal_connect` is described in [GObject reference manual](https://developer.gnome.org/gobject/stable/gobject-Signals.html#g-signal-connect).
|
||||
In addition, `g_signal_connect` is described in [GObject API Reference](https://docs.gtk.org/gobject/func.signal_connect.html).
|
||||
API reference manual is very important.
|
||||
You should see and understand it to write Gtk applications.
|
||||
They are located in ['GNOME Developer Center'](https://developer.gnome.org/).
|
||||
They are located in ['GTK Documentation'](https://docs.gtk.org/).
|
||||
|
||||
Let's compile the source file above (`pr2.c`) and run it.
|
||||
|
||||
|
|
|
@ -223,7 +223,7 @@ The change is:
|
|||
- The fourth argument of `g_signal_connect` is changed from `NULL` to `win`.
|
||||
|
||||
Most important is the fourth argument of `g_signal_connect`.
|
||||
It is described as "data to pass to handler" in the definition of `g_signal_connect` in [GObject reference manual](https://developer.gnome.org/gobject/stable/gobject-Signals.html#g-signal-connect).
|
||||
It is described as "data to pass to handler" in the definition of `g_signal_connect` in [GObject API Reference](https://docs.gtk.org/gobject/func.signal_connect.html).
|
||||
Therefore, `win` which is a pointer to GtkApplicationWindow is passed to the handler as a second parameter `user_data`.
|
||||
Then, the handler cast it to a pointer to GtkWindow and call `gtk_window_destroy` to destroy the top-level window.
|
||||
Then, the application quits.
|
||||
|
|
|
@ -191,7 +191,7 @@ The string literal "Hello" has 6 bytes because the string has '\0' at the end it
|
|||
`s` is assigned the top address of the memory.
|
||||
`g_free` returns the memory to the heap area.
|
||||
|
||||
`g_strdup` is described in [GLib reference manual](https://developer.gnome.org/glib/stable/glib-String-Utility-Functions.html#g-strdup).
|
||||
`g_strdup` is described in [GLib API Reference](https://docs.gtk.org/glib/func.strdup.html).
|
||||
The following is extracted from the reference.
|
||||
|
||||
> The returned string should be freed with `g_free()` when no longer needed.
|
||||
|
|
|
@ -18,7 +18,7 @@ When the program starts, we give a filename as an argument.
|
|||
Then it opens the file and inserts its contents into the GtkTextBuffer.
|
||||
|
||||
At the beginning of the implementation, we need to know how GtkApplication (or GApplication) recognizes arguments.
|
||||
It is described in the [GIO reference manual](https://developer.gnome.org/gio/stable/GApplication.html#GApplication.description).
|
||||
It is described in the [GIO API Reference, Application](https://docs.gtk.org/gio/class.Application.html).
|
||||
|
||||
When GtkApplication is created, a flag (its type is GApplicationFlags) is given as an argument.
|
||||
|
||||
|
@ -29,8 +29,8 @@ gtk_application_new (const gchar *application_id, GApplicationFlags flags);
|
|||
|
||||
This tutorial explains only two flags, `G_APPLICATION_FLAGS_NONE` and `G_APPLICATION_HANDLES_OPEN`.
|
||||
If you want to handle command line arguments, `G_APPLICATION_HANDLES_COMMAND_LINE` flag is what you need.
|
||||
How to program it is written in [GIO reference manual, g\_application\_run](https://developer.gnome.org/gio/stable/GApplication.html#g-application-run).
|
||||
And the flag is described in the [GApplication section](https://developer.gnome.org/gio/stable/GApplication.html#GApplicationFlags) in GIO reference manual.
|
||||
How to program it is written in [GIO API Reference, g\_application\_run](https://docs.gtk.org/gio/method.Application.run.html).
|
||||
And the flag is described in the [GIO API Reference, ApplicationFlags](https://docs.gtk.org/gio/flags.ApplicationFlags.html).
|
||||
|
||||
~~~
|
||||
GApplicationFlags' Members
|
||||
|
@ -337,7 +337,7 @@ Therefore, the structure is like this:
|
|||
If it is set to TRUE then the tab expands horizontally as long as possible.
|
||||
If it is FALSE, then the width of the tab is determined by the size of the label.
|
||||
`g_object_set` is a general function to set properties in any objects.
|
||||
See [GObject reference manual](https://developer.gnome.org/gobject/stable/gobject-The-Base-Object-Type.html#g-object-set).
|
||||
See [GObject API Reference, g\_object\_set](https://docs.gtk.org/gobject/method.Object.set.html).
|
||||
- 49-51: If it fails to read the file, "No such file" message is outputted.
|
||||
Frees `filename`.
|
||||
- 52-53: If `filename` is NULL, "No valid file is given" message is outputted.
|
||||
|
|
|
@ -97,7 +97,7 @@ tfe_text_view_new (void) {
|
|||
|
||||
If you are curious about the background theory of this program, It's very good for you.
|
||||
Because knowing the theory is very important for you to program GTK applications.
|
||||
Look at [GObject reference manual](https://developer.gnome.org/gobject/stable/).
|
||||
Look at [GObject API Reference](https://docs.gtk.org/gobject/).
|
||||
All you need is described in it.
|
||||
Or, refer to [GObject tutorial](https://github.com/ToshioCP/Gobject-tutorial).
|
||||
However, it's a tough journey especially for beginners.
|
||||
|
|
|
@ -371,7 +371,7 @@ Now I'll show you `app_open` function in the C file `tfe3.c`.
|
|||
48 }
|
||||
~~~
|
||||
|
||||
The whole source code of `tfe3.c` is stored in [src/tfe](https://github.com/ToshioCP/Gtk4-tutorial/tree/main/src/tfe) directory.
|
||||
The whole source code of `tfe3.c` is stored in [src/tfe](../src/tfe) directory.
|
||||
If you want to see it, click the link above.
|
||||
|
||||
### Using ui string
|
||||
|
|
|
@ -1,3 +1,5 @@
|
|||
#### Contents of this repository
|
||||
|
||||
This tutorial illustrates how to write C programs with Gtk4 library.
|
||||
It focuses on beginners so the contents are limited to basic things.
|
||||
The table of contents are shown at the end of this abstract.
|
||||
|
@ -7,21 +9,39 @@ The table of contents are shown at the end of this abstract.
|
|||
- Section 24 to 27 describes list model and list view (GtkListView, GtkGridView and GtkColumnView).
|
||||
It also describes GtkExpression.
|
||||
|
||||
Please refer to [Gtk reference manual](https://developer.gnome.org/gtk4/stable/index.html)
|
||||
and [Gnome Developer Center](https://developer.gnome.org/) for further topics.
|
||||
|
||||
If you want to know about GObject and type system, refer to [GObject tutorial](https://github.com/ToshioCP/Gobject-tutorial).
|
||||
It includes the initialization and destruction process of GObject class and instances.
|
||||
These knowledge is necessary to write gtk4 programs.
|
||||
|
||||
This tutorial is under development and unstable.
|
||||
Even though the codes of the examples have been tested on gtk4 version 4.0, there might exist bugs.
|
||||
If you find any bugs, errors or mistakes in the tutorial and C examples, please let me know.
|
||||
You can post it to [github issues](https://github.com/ToshioCP/Gtk4-tutorial/issues).
|
||||
The latest version of the tutorial is located at [Gtk4-tutorial github repository](https://github.com/ToshioCP/Gtk4-tutorial).
|
||||
You can read it without download.
|
||||
|
||||
If you want to get a html or pdf version, you can make them with `rake`, which is a ruby version of make.
|
||||
#### Gtk4 Documentation
|
||||
|
||||
Please refer to [Gtk API Reference](https://docs.gtk.org/gtk4/index.html)
|
||||
and [Gnome Developer Documentation Website](https://developer.gnome.org/) for further topics.
|
||||
|
||||
These websites are newly opend lately (Aug/2021).
|
||||
The old documentation is located at [Gtk Reference Manual](https://developer-old.gnome.org/gdk4/stable/) and [Gnome Developer Center](https://developer-old.gnome.org/).
|
||||
The new website is in progress at present, so you might need to refer to the old version.
|
||||
|
||||
If you want to know about GObject and type system, refer to [GObject tutorial](https://github.com/ToshioCP/Gobject-tutorial).
|
||||
They are basic and also necessary to write Gtk4 programs.
|
||||
|
||||
#### Contribution
|
||||
|
||||
This tutorial is under development and unstable.
|
||||
Even though the codes of the examples have been tested on Gtk4 version 4.0, there might exist bugs.
|
||||
If you find any bugs, errors or mistakes in the tutorial and C examples, please let me know.
|
||||
You can post it to [github issues](https://github.com/ToshioCP/Gtk4-tutorial/issues).
|
||||
You can also post corrected files as a commit to [pull request](https://github.com/ToshioCP/Gtk4-tutorial/pulls).
|
||||
When you make corrections, correct the source files, which are under the 'src' directory.
|
||||
And run rake, then GFM files under the 'gfm' directory are automatically updated.
|
||||
|
||||
If you have a question, feel free to post it to the issue.
|
||||
Any question is helpful to make this tutorial get better.
|
||||
|
||||
#### How to get a HTML or PDF version
|
||||
|
||||
If you want to get a HTML or PDF version, you can make them with `rake`, which is a ruby version of make.
|
||||
Type `rake html` for HTML.
|
||||
Type `rake pdf` for PDF.
|
||||
@@@if gfm
|
||||
There is a documentation \("[How to build Gtk4 Tutorial](Readme_for_developers.src.md)"\) that describes how to make them.
|
||||
@@@elif html
|
||||
|
@ -30,5 +50,3 @@ There is a documentation \("[How to build Gtk4 Tutorial](Readme_for_developers.s
|
|||
An appendix "How to build Gtk4 Tutorial" describes how to make them.
|
||||
@@@end
|
||||
|
||||
If you have a question, feel free to post it to the issue.
|
||||
Any question is helpful to make this tutorial get better.
|
||||
|
|
|
@ -63,7 +63,7 @@ tfetextview/tfetextview.c tfe_text_view_class_init
|
|||
The signal "change-file" has no default handler (object method handler).
|
||||
You usually don't need to set a default handler.
|
||||
If you need it, use `g_signal_new_class_handler` function.
|
||||
See [GObject reference manual](https://developer.gnome.org/gobject/stable/gobject-Signals.html#g-signal-new-class-handler) for further information.
|
||||
See [GObject API Reference, g\_signal\_new\_class\_handler](https://docs.gtk.org/gobject/func.signal_new_class_handler.html) for further information.
|
||||
- The return value of `g_signal_new` is the signal id.
|
||||
The type of signal id is guint, which is the same as unsigned int.
|
||||
It is used in the function `g_signal_emit`.
|
||||
|
@ -73,7 +73,7 @@ This signal has a parameter.
|
|||
"open-response" signal has one parameter.
|
||||
- 25: The type of the parameter.
|
||||
`G_TYPE_INT` is a type of integer.
|
||||
Such fundamental types are described in [GObject reference manual](https://developer.gnome.org/gobject/stable/gobject-Type-Information.html).
|
||||
Such fundamental types are described in [GObject reference manual](https://developer-old.gnome.org/gobject/stable/gobject-Type-Information.html).
|
||||
|
||||
The handlers are declared as follows.
|
||||
|
||||
|
|
|
@ -51,7 +51,8 @@ tfetextview/tfetextview.c tfe_text_view_new_with_file tfe_text_view_new
|
|||
Just returns the value from the function `g_object_new` but casts it to the pointer to GtkWidget.
|
||||
Initialization is done in `tfe_text_view_init` which is called in the process of `g_object_new` function.
|
||||
- 1-21: `tfe_text_view_new_with_file` function.
|
||||
- 3: `g_return_val_if_fail` is described in [Glib reference manual](https://developer.gnome.org/glib/stable/glib-Warnings-and-Assertions.html#g-return-val-if-fail).
|
||||
- 3: `g_return_val_if_fail` is described in [GLib API Reference, g\_return\_val\_if\_fail](https://docs.gtk.org/glib/func.return_val_if_fail.html).
|
||||
And also [GLib API Reference, Message Logging](https://docs.gtk.org/glib/logging.html).
|
||||
It tests whether the argument `file` is a pointer to GFile.
|
||||
If it's true, then the program goes on to the next line.
|
||||
If it's false, then it returns NULL (the second argument) immediately.
|
||||
|
@ -239,7 +240,7 @@ The important thing is to duplicate `tv->file`.
|
|||
Otherwise, if the caller frees the GFile object, `tv->file` is no more guaranteed to point the GFile.
|
||||
Another reason to use `g_file_dup` is that GFile isn't thread-safe.
|
||||
If you use GFile in the different thread, the duplication is necessary.
|
||||
See [Gio reference manual](https://developer.gnome.org/gio/stable/GFile.html#g-file-dup).
|
||||
See [Gio API Reference, g\_file\_dup](https://docs.gtk.org/gio/method.File.dup.html).
|
||||
|
||||
## The API document and source file of tfetextview.c
|
||||
|
||||
|
|
|
@ -109,7 +109,7 @@ On the other hand, when an instance of GObject (not GInitiallyUnowned) is create
|
|||
And the instance has a normal reference count instead of floating reference.
|
||||
|
||||
If you use `g_object_unref` to an instance that has a floating reference, you need to convert the floating reference to a normal reference in advance.
|
||||
See [GObject reference manual](https://developer.gnome.org/gobject/stable/gobject-The-Base-Object-Type.html#gobject-The-Base-Object-Type.description) for further information.
|
||||
See [GObject Reference Manual](https://developer-old.gnome.org/gobject/stable/gobject-The-Base-Object-Type.html#gobject-The-Base-Object-Type.description) for further information.
|
||||
|
||||
## notebook\_page\_close
|
||||
|
||||
|
|
|
@ -121,7 +121,7 @@ textview {color: yellow; ...}
|
|||
~~~
|
||||
|
||||
Class, ID and some other things can be applied to the selector like Web CSS.
|
||||
Refer [Gtk4 reference manual](https://developer.gnome.org/gtk4/stable/theming.html) for further information.
|
||||
Refer to [Gtk4 API Reference, CSS in Gtk](https://docs.gtk.org/gtk4/css-overview.html) for further information.
|
||||
|
||||
In line 30, the CSS is a string.
|
||||
|
||||
|
@ -256,7 +256,7 @@ In this file, just the source file names are modified from the prior version.
|
|||
|
||||
## source files
|
||||
|
||||
The [source files](https://github.com/ToshioCP/Gtk4-tutorial/tree/main/src/tfe5) of the text editor `tfe` will be shown in the next section.
|
||||
The [source files](tfe5) of the text editor `tfe` will be shown in the next section.
|
||||
|
||||
You can also download the files from the [repository](https://github.com/ToshioCP/Gtk4-tutorial).
|
||||
There are two options.
|
||||
|
|
|
@ -144,7 +144,7 @@ Therefore, `act_quit` has a name "quit" and no parameter.
|
|||
- 17: Adds the action to GtkApplication `app`.
|
||||
GtkApplication implements an interface GActionMap and GActionGroup.
|
||||
GtkApplication (GActionMap) can have a group of actions and the actions are added with the function `g_action_map_add_action`.
|
||||
This function is described in [GMenuModel section in GIO reference manual](https://developer.gnome.org/gio/stable/GActionMap.html#g-action-map-add-action).
|
||||
This function is described in [Gio API Reference, g\_action\_map\_add\_action](https://docs.gtk.org/gio/method.ActionMap.add_action.html).
|
||||
- 18: Connects "activate" signal of the action and the handler `quit_activated`.
|
||||
- 20-23: Creates GMenu and GMenuItem instances.
|
||||
`menubar` and `menu` are GMenu.
|
||||
|
|
|
@ -5,8 +5,8 @@ This section describes how to install Gtk4 into Linux distributions.
|
|||
This tutorial including this section is without any warranty.
|
||||
If you install Gtk4 to your computer, do it at your own risk.
|
||||
|
||||
This section is written on 13/June/2021.
|
||||
"At present" means 13/June/2021 in this section.
|
||||
This section is written on 12/August/2021.
|
||||
"At present" means 12/August/2021 in this section.
|
||||
|
||||
There are three possible way to install Gtk4.
|
||||
|
||||
|
@ -36,7 +36,7 @@ At present, the version of Gtk4 on Ubuntu 21.04 is 4.0.3.
|
|||
|
||||
I installed Gtk4 in January 2021.
|
||||
So, the following is old information, especially for the version of each software.
|
||||
For the latest information, see [Gtk gitlab repository](https://gitlab.gnome.org/GNOME/gtk) and [Gtk official web site](https://docs.gtk.org/gtk4/building.html).
|
||||
For the latest information, see [Gtk API Reference, Building GTK](https://docs.gtk.org/gtk4/building.html).
|
||||
|
||||
### Prerequisites for Gtk4 installation
|
||||
|
||||
|
@ -51,7 +51,7 @@ I installed Gtk4 under the directory `$HOME/local`.
|
|||
This is a private user area.
|
||||
|
||||
If you want to install it in the system area, `/opt/gtk4` is one of good choices.
|
||||
[Gtk4 reference manual](https://developer.gnome.org/gtk4/stable/gtk-building.html) gives an installation example to `/opt/gtk4`.
|
||||
[Gtk API Reference, Building GTK](https://docs.gtk.org/gtk4/building.html) gives an installation example to `/opt/gtk4`.
|
||||
|
||||
Don't install it to `/usr/local` which is the default.
|
||||
It is used by Ubuntu applications, which are not build on Gtk4.
|
||||
|
@ -184,7 +184,7 @@ Compile and install it.
|
|||
$ ninja -C _build
|
||||
$ ninja -C _build install
|
||||
|
||||
If you want to know more information, refer to [Gtk4 reference manual](https://developer.gnome.org/gtk4/stable/gtk-building.html).
|
||||
If you want to know more information, refer to [Gtk4 API Reference, Building GTK](https://docs.gtk.org/gtk4/building.html).
|
||||
|
||||
### Modify env.sh
|
||||
|
||||
|
|
|
@ -654,7 +654,7 @@ PANGO\_SCALE is defined as 1024.
|
|||
Therefore, 10*PANGO\_SCALE is 10240.
|
||||
- 91: calls `set_font_for_display` to set CSS for the GdkDisplay.
|
||||
|
||||
For further information, see [Pango reference manual](https://developer.gnome.org/pango/1.46/).
|
||||
For further information, see [Pango API Reference](https://docs.gtk.org/Pango/).
|
||||
|
||||
## GSettings
|
||||
|
||||
|
@ -705,13 +705,13 @@ tfe6/com.github.ToshioCP.tfe.gschema.xml
|
|||
@@@
|
||||
|
||||
- 4: The type attribute is "s".
|
||||
It is [GVariant format string](https://developer.gnome.org/glib/stable/gvariant-format-strings.html).
|
||||
It is [GLib API Reference, GVariant Type Strings](https://docs.gtk.org/glib/struct.VariantType.html#gvariant-type-strings).
|
||||
Other common types are:
|
||||
- "b": gboolean
|
||||
- "i": gint32.
|
||||
- "d": double.
|
||||
|
||||
Further information is in [Glib reference manual](https://developer.gnome.org/glib/stable/gvariant-format-strings.html).
|
||||
Further information is in [Glib API Reference, VarientType](https://docs.gtk.org/glib/struct.VariantType.html).
|
||||
|
||||
### gsettings
|
||||
|
||||
|
@ -832,7 +832,7 @@ A path determines where the settings are stored in the conceptual global tree of
|
|||
An id identifies the schema.
|
||||
- 4: Key tag has two attributes.
|
||||
Name is the name of the key.
|
||||
Type is the type of the value of the key and specified with [GVariant format string](https://developer.gnome.org/glib/stable/gvariant-format-strings.html).
|
||||
Type is the type of the value of the key and specified with [GLib API Reference, VariantType](https://docs.gtk.org/glib/struct.VariantType.html).
|
||||
- 5: default value of the key `font` is `Monospace 12`.
|
||||
- 6: Summery and description elements describes the key.
|
||||
They are optional, but it is recommended to add them in the XML file.
|
||||
|
|
|
@ -104,7 +104,7 @@ The two functions `app_activate` and `draw_function` is important in this exampl
|
|||
GtkDrawingArea widget uses the function to draw the contents of itself whenever its necessary.
|
||||
For example, when a user drag a mouse pointer and resize a top-level window, GtkDrawingArea also changes the size.
|
||||
Then, the whole window needs to be redrawn.
|
||||
For the information of `gtk_drawing_area_set_draw_func`, see [Gtk4 reference manual](https://developer.gnome.org/gtk4/stable/GtkDrawingArea.html#gtk-drawing-area-set-draw-func).
|
||||
For the information of `gtk_drawing_area_set_draw_func`, see [Gtk API Reference, gtk\_drawing\_area\_set\_draw\_func](https://docs.gtk.org/gtk4/method.DrawingArea.set_draw_func.html).
|
||||
|
||||
The drawing function has five parameters.
|
||||
|
||||
|
|
|
@ -215,13 +215,13 @@ So, it is necessary to include it by `#include <math.h>` and also link the libra
|
|||
- 6: Gets gtk4 library.
|
||||
- 8: Gets gnome module.
|
||||
Module is a system provided by meson.
|
||||
See [Meson build system website](https://mesonbuild.com/Gnome-module.html#gnome-module) for further information.
|
||||
See [Meson build system website, GNUME module](https://mesonbuild.com/Gnome-module.html#gnome-module) for further information.
|
||||
- 9: Compiles ui file to C source file according to the XML file `turtle.gresource.xml`.
|
||||
- 11: Gets flex.
|
||||
- 12: Gets bison.
|
||||
- 13: Compiles `turtle.y` to `turtle_parser.c` and `turtle_parser.h` by bison.
|
||||
The function `custom_target` creates a custom top level target.
|
||||
See [Meson build system website](https://mesonbuild.com/Reference-manual.html#custom_target) for further information.
|
||||
See [Meson build system website, custom target](https://mesonbuild.com/Reference-manual.html#custom_target) for further information.
|
||||
- 14: Compiles `turtle.lex` to `turtle_lex.c` by flex.
|
||||
- 16: Specifies C source files.
|
||||
- 18: Compiles C source files including generated files by glib-compile-resources, bison and flex.
|
||||
|
|
|
@ -1,7 +1,7 @@
|
|||
# GtkListView
|
||||
|
||||
Gtk4 has added new list objects GtkListView, GtkGridView and GtkColumnView.
|
||||
The new feature is described in the sections "GListModel support" and "List-based widgets" at the top of [the third chapter of Gtk4 reference manual](https://developer.gnome.org/gtk4/stable/gtkobjects.html).
|
||||
The new feature is described in [Gtk API Reference, List Widget Overview](https://docs.gtk.org/gtk4/section-list-widget.html).
|
||||
|
||||
Gtk4 has other means to implement lists.
|
||||
They are GtkListBox and GtkTreeView which are took over from Gtk3.
|
||||
|
@ -65,7 +65,7 @@ There are functions to add items to the list or remove items from the list.
|
|||
- `gtk_string_list_remove` removes an item from the list
|
||||
- `gtk_string_list_get_string` gets a string in the list
|
||||
|
||||
See [Gtk4 reference manual](https://developer.gnome.org/gtk4/stable/GtkStringList.html) for further information.
|
||||
See [Gtk4 API Reference, GtkStringList](https://docs.gtk.org/gtk4/class.StringList.html) for further information.
|
||||
|
||||
I'll explain the other list objects later.
|
||||
|
||||
|
|
|
@ -143,7 +143,7 @@ So, the change of the text in `entry` makes the "label" property reflect it imme
|
|||
|
||||
Closure expression calls closure when it is evaluated.
|
||||
A closure is a generic representation of a callback (a pointer to a function).
|
||||
For information about closure, see [GObject reference manual](https://developer.gnome.org/gobject/stable/chapter-signal.html#closure).
|
||||
For information about closure, see [GObject API Reference, The GObject messaging system](https://docs.gtk.org/gobject/concepts.html#the-gobject-messaging-system).
|
||||
A closure expression is created with `gtk_cclosure_expression_new` function.
|
||||
|
||||
~~~C
|
||||
|
|
|
@ -108,13 +108,13 @@ The function `g_signal_connect` has four arguments.
|
|||
4. Data to pass to the handler. If no data is necessary, NULL should be given.
|
||||
|
||||
You can find the description of each signal in the API reference manual.
|
||||
For example, "activate" signal is in GApplication section in [GIO reference manual](https://developer.gnome.org/gio/stable/GApplication.html#GApplication-activate).
|
||||
For example, "activate" signal is in GApplication section in [GIO API Reference](https://docs.gtk.org/gio/signal.Application.activate.html).
|
||||
The handler function is described in it.
|
||||
|
||||
In addition, `g_signal_connect` is described in [GObject reference manual](https://developer.gnome.org/gobject/stable/gobject-Signals.html#g-signal-connect).
|
||||
In addition, `g_signal_connect` is described in [GObject API Reference](https://docs.gtk.org/gobject/func.signal_connect.html).
|
||||
API reference manual is very important.
|
||||
You should see and understand it to write Gtk applications.
|
||||
They are located in ['GNOME Developer Center'](https://developer.gnome.org/).
|
||||
They are located in ['GTK Documentation'](https://docs.gtk.org/).
|
||||
|
||||
Let's compile the source file above (`pr2.c`) and run it.
|
||||
|
||||
|
|
|
@ -101,7 +101,7 @@ The change is:
|
|||
- The fourth argument of `g_signal_connect` is changed from `NULL` to `win`.
|
||||
|
||||
Most important is the fourth argument of `g_signal_connect`.
|
||||
It is described as "data to pass to handler" in the definition of `g_signal_connect` in [GObject reference manual](https://developer.gnome.org/gobject/stable/gobject-Signals.html#g-signal-connect).
|
||||
It is described as "data to pass to handler" in the definition of `g_signal_connect` in [GObject API Reference](https://docs.gtk.org/gobject/func.signal_connect.html).
|
||||
Therefore, `win` which is a pointer to GtkApplicationWindow is passed to the handler as a second parameter `user_data`.
|
||||
Then, the handler cast it to a pointer to GtkWindow and call `gtk_window_destroy` to destroy the top-level window.
|
||||
Then, the application quits.
|
||||
|
|
|
@ -189,7 +189,7 @@ The string literal "Hello" has 6 bytes because the string has '\0' at the end it
|
|||
`s` is assigned the top address of the memory.
|
||||
`g_free` returns the memory to the heap area.
|
||||
|
||||
`g_strdup` is described in [GLib reference manual](https://developer.gnome.org/glib/stable/glib-String-Utility-Functions.html#g-strdup).
|
||||
`g_strdup` is described in [GLib API Reference](https://docs.gtk.org/glib/func.strdup.html).
|
||||
The following is extracted from the reference.
|
||||
|
||||
> The returned string should be freed with `g_free()` when no longer needed.
|
||||
|
|
|
@ -16,7 +16,7 @@ When the program starts, we give a filename as an argument.
|
|||
Then it opens the file and inserts its contents into the GtkTextBuffer.
|
||||
|
||||
At the beginning of the implementation, we need to know how GtkApplication (or GApplication) recognizes arguments.
|
||||
It is described in the [GIO reference manual](https://developer.gnome.org/gio/stable/GApplication.html#GApplication.description).
|
||||
It is described in the [GIO API Reference, Application](https://docs.gtk.org/gio/class.Application.html).
|
||||
|
||||
When GtkApplication is created, a flag (its type is GApplicationFlags) is given as an argument.
|
||||
|
||||
|
@ -27,8 +27,8 @@ gtk_application_new (const gchar *application_id, GApplicationFlags flags);
|
|||
|
||||
This tutorial explains only two flags, `G_APPLICATION_FLAGS_NONE` and `G_APPLICATION_HANDLES_OPEN`.
|
||||
If you want to handle command line arguments, `G_APPLICATION_HANDLES_COMMAND_LINE` flag is what you need.
|
||||
How to program it is written in [GIO reference manual, g\_application\_run](https://developer.gnome.org/gio/stable/GApplication.html#g-application-run).
|
||||
And the flag is described in the [GApplication section](https://developer.gnome.org/gio/stable/GApplication.html#GApplicationFlags) in GIO reference manual.
|
||||
How to program it is written in [GIO API Reference, g\_application\_run](https://docs.gtk.org/gio/method.Application.run.html).
|
||||
And the flag is described in the [GIO API Reference, ApplicationFlags](https://docs.gtk.org/gio/flags.ApplicationFlags.html).
|
||||
|
||||
~~~
|
||||
GApplicationFlags' Members
|
||||
|
@ -205,7 +205,7 @@ Therefore, the structure is like this:
|
|||
If it is set to TRUE then the tab expands horizontally as long as possible.
|
||||
If it is FALSE, then the width of the tab is determined by the size of the label.
|
||||
`g_object_set` is a general function to set properties in any objects.
|
||||
See [GObject reference manual](https://developer.gnome.org/gobject/stable/gobject-The-Base-Object-Type.html#g-object-set).
|
||||
See [GObject API Reference, g\_object\_set](https://docs.gtk.org/gobject/method.Object.set.html).
|
||||
- 49-51: If it fails to read the file, "No such file" message is outputted.
|
||||
Frees `filename`.
|
||||
- 52-53: If `filename` is NULL, "No valid file is given" message is outputted.
|
||||
|
|
|
@ -95,7 +95,7 @@ tfe_text_view_new (void) {
|
|||
|
||||
If you are curious about the background theory of this program, It's very good for you.
|
||||
Because knowing the theory is very important for you to program GTK applications.
|
||||
Look at [GObject reference manual](https://developer.gnome.org/gobject/stable/).
|
||||
Look at [GObject API Reference](https://docs.gtk.org/gobject/).
|
||||
All you need is described in it.
|
||||
Or, refer to [GObject tutorial](https://github.com/ToshioCP/Gobject-tutorial).
|
||||
However, it's a tough journey especially for beginners.
|
||||
|
|
|
@ -122,7 +122,7 @@ Now I'll show you `app_open` function in the C file `tfe3.c`.
|
|||
tfe/tfe3.c app_open
|
||||
@@@
|
||||
|
||||
The whole source code of `tfe3.c` is stored in [src/tfe](https://github.com/ToshioCP/Gtk4-tutorial/tree/main/src/tfe) directory.
|
||||
The whole source code of `tfe3.c` is stored in [src/tfe](tfe) directory.
|
||||
If you want to see it, click the link above.
|
||||
|
||||
### Using ui string
|
||||
|
|
Loading…
Add table
Reference in a new issue