mirror of
https://github.com/ToshioCP/Gtk4-tutorial.git
synced 2025-01-12 20:03:28 +01:00
176 lines
8.7 KiB
Markdown
176 lines
8.7 KiB
Markdown
# Functions in TfeTextView
|
|
|
|
In this section I will explain each function in TfeTextView object.
|
|
|
|
### tfe.h and tfetextview.h
|
|
|
|
`tfe.h` is a top header file and it includes `gtk.h` and all the header files.
|
|
Every C source files, which are `tfeapplication.c`, `tfenotebook.c` and `tfetextview.c`, include `tfe.h` at the beginning of each file.
|
|
|
|
@@@ tfe5/tfe.h
|
|
|
|
`tfetextview.h` is a header file which describes the public functions in `tfetextview.c`.
|
|
|
|
@@@ tfe5/tfetextview.h
|
|
|
|
- 1-2: These two lines are used to define TfeTextView.
|
|
- 4-10: Definitions of parameter used in the handler of "open-response" signal.
|
|
- 12-28: Public functions on GtkTextView.
|
|
|
|
Each function will be explained later in this section.
|
|
|
|
## Functions to generate TfeTextView object
|
|
|
|
TfeTextView Object is generated by `tfe_text_view_new` or `tfe_text_view_new_with_file`.
|
|
|
|
GtkWidget *tfe_text_view_new (void);
|
|
|
|
`tfe_text_view_new` just generates a new TfeTextView object and returns the pointer to the new object.
|
|
|
|
GtkWidget *tfe_text_view_new_with_file (GFile *file);
|
|
|
|
`tfe_text_view_new_with_file` is given a Gfile object as the argument and it loads the file into the GtkTextBuffer object, then returns the pointer to the new object.
|
|
|
|
Parameter:
|
|
|
|
- `file`: a pointer to the GFile object.
|
|
|
|
Return value:
|
|
|
|
- A pointer to the generated TfeTextView object but it is casted to a pointer to GtkWidget.
|
|
If an error occures during the genration process, NULL is returned.
|
|
|
|
Each function is defined as follows.
|
|
|
|
@@@ tfe5/tfetextview.c tfe_text_view_new_with_file tfe_text_view_new
|
|
|
|
- 18-21: `tfe_text_view_new`.
|
|
Just returns the value from the function `gtk_widget_new`.
|
|
Initialization is done in `tfe_text_view_init` which is called in the process of `gtk_widget_new` function.
|
|
- 1-16: `tfe_text_view_new_with_file`
|
|
- 3: `g_return_val_if_fail` is described in [Glib API reference](https://developer.gnome.org/glib/stable/glib-Warnings-and-Assertions.html#g-return-val-if-fail).
|
|
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.
|
|
And at the same time it logs out the error message (usually the log is outputted to stderr or stdout).
|
|
This function is used to check the programmer's error.
|
|
If an error occurs, the solution is usually to change the (caller) program and fix the bug.
|
|
You need to distinguish programmer's errors and runtime errors.
|
|
You shouldn't use this function to find runtime errors.
|
|
- 9-10: If an error occurs when reading the file, then return NULL.
|
|
- 11-15: Generate TfeTextView and set the pointer to it to `tv`.
|
|
Set the contents read from the file to GtkTextBuffer `tv->tb`.
|
|
Free the memories pointed by `contents`.
|
|
Duplicate `file` and set it to `tv->file`.
|
|
Return `tv`.
|
|
|
|
## Save and saveas functions
|
|
|
|
Save and saveas functions write the contents in GtkTextBuffer to a file.
|
|
|
|
void tfe_text_view_save (TfeTextView *tv)
|
|
|
|
`save` function writes the contents in GtkTextBuffer to a file specified by `tv->file`.
|
|
If `tv->file` is NULL, then it shows GtkFileChooserDialog and lets the user to give a file to the program. After that, it saves the contents to the specified file and set the file into `tv->file`.
|
|
|
|
void tfe_text_view_saveas (TfeTextView *tv)
|
|
|
|
`saveas` function uses GtkFileChooserDialog and lets the user to give a new file to the program. Then, the function changes `tv->file` and save the contents to the specified new file.
|
|
|
|
If an error occures, it is shown to the user through the message dialog.
|
|
The error is managed only in the object and no information is notified to the caller.
|
|
|
|
@@@ tfe5/tfetextview.c saveas_dialog_response tfe_text_view_save tfe_text_view_saveas
|
|
|
|
- 17-53: `Tfe_text_view_save` function.
|
|
- 19: If `tv` is not a pointer to TfeTextView, then it logs an error message and immediately returns.
|
|
This function is similar to `g_return_val_if_fail` function, but no value is returned because `tfe_text_view_save` doesn't return a value.
|
|
- 28-29: If the buffer hasn't modified, then it doesn't need to save it.
|
|
So the function returns.
|
|
- 30-31: If `tv->file` is NULL, no file has given yet.
|
|
It calls `tfe_text_view_save`, which lets the user to choose a file to save.
|
|
- 33-35: Save the buffer to the file.
|
|
If it succeeds, assigns FALSE to `tv->changed`.
|
|
- 38-50: If file writing fails, it assigns NULL to `tv->file`.
|
|
Emits "change-file" signal.
|
|
Shows the error message dialog (45-49).
|
|
Because the handler is `gtk_window_destroy`, the dialog disappears when user clicks on the button in the dialog.
|
|
- 55-68: `tfe_text_view_saveas` function.
|
|
It shows GtkFileChooserDialog and lets the user choose a file and give it to the signal handler.
|
|
- 62: Generate GtkFileChooserDialog.
|
|
The title is "Save file".
|
|
Transient parent of the dialog is `win`, which is the top level window.
|
|
The action is save mode.
|
|
The buttons are Cancel and Save.
|
|
- 63: connect the "response" signal of the dialog and `saveas_dialog_response` handler.
|
|
- 1-15: `saveas_dialog_response` signal handler.
|
|
- 5-13: If the response is `GTK_RESPONSE_ACCEPT`, which is set to the argument when the user has clicked on Save button, then gets a pointer to the GFile object, set it to `tv->file`, assign TRUE to `tv->changed`, emits "change-file" signal then call `tfe_text_view_save` to save the buffer to the file.
|
|
|
|
|
|
|
|
When you use GtkFileChooserDialog, you need to divide the program into two parts.
|
|
They are a function which generates GtkFileChooserDialog and the signal handler.
|
|
The function just generates and shows the dialog.
|
|
The rest is done by the handler.
|
|
It gets Gfile from GtkFileChooserDialog, save the buffer to the file and do some things necessary.
|
|
|
|
## Open function
|
|
|
|
Open function shows GtkFileChooserDialog to the user and let him/her choose a file.
|
|
Then read the file and set it to GtkTextBuffer.
|
|
|
|
void tfe_text_view_open (TfeTextView *tv)
|
|
|
|
TfeTextView object `tv` has to be generated in advance.
|
|
And it should be empty and `tv->file` is NULL.
|
|
If it is not empty, `tfe_text_view_open` doesn't treat it as an error.
|
|
If you want to revert the buffer, calling this function is apropreate.
|
|
Otherwise probably bad things will happen.
|
|
|
|
@@@ tfe5/tfetextview.c open_dialog_response tfe_text_view_open
|
|
|
|
- 33-45: `tfe_text_view_open` function.
|
|
- 39: Generate GtkFileChooserDialog.
|
|
The title is "Open file".
|
|
No transient parent window.
|
|
The action is open mode.
|
|
The buttons are Cancel and Open.
|
|
- 43: connect the "reponse" signal of the dialog and `open_dialog_response` signal handler.
|
|
- 44: Show the dialog.
|
|
- 1-31: `open_dialog_response` signal handler.
|
|
- 9-10: If the response from GtkFileChooserDialog is not `GTK_RESPONSE_ACCEPT`, which means the user has clicked on the "Cancel" button or close button, then it emits "open-response" signal with the parameter `TFE_OPEN_RESPONSE_CANCEL`.
|
|
- 11-12: Get a pointer to Gfile by `gtk_file_chooser_get_file`.
|
|
If it is not GFile, maybe an error occured.
|
|
Then it emits "open-response" signal with the parameter `TFE_OPEN_RESPONSE_ERROR`.
|
|
- 13-22: If an error occurs when it has read the file, then it decreases the reference count of Gfile, shows a message dialog to report the error to the user and emits "open-response" signal with the parameter `TFE_OPEN_RESPONSE_ERROR`.
|
|
- 24-28: If the file has successfully read, then the text is set to GtkTextBuffer, free the temporary buffer pointed by `contents`, set file to `tv->file` (no duplication or unref is not necessary) and emits "open-response" signal with the parameter `TFE_OPEN_RESPONSE_SUCCESS`.
|
|
- 30: close GtkFileCooserDialog.
|
|
|
|
Now let's think about the whole process between the other object (caller) and TfeTextView.
|
|
It is shown in the following diagram and you would think that it is really complicated.
|
|
Because signal is the only way for GtkFileChooserDialog to communicate with others.
|
|
In Gtk3, `gtk_dialog_run` function is available.
|
|
It simplifies the process.
|
|
However, in Gtk4, `gtk_dialog_run`is unavailable any more.
|
|
|
|
|
|
|
|
1. A caller get a pointer `tv` to TfeTextView by calling `tfe_text_view_new`.
|
|
2. The caller connects the handler (left bottom in the diagram) and the signal "open-response".
|
|
3. It calls `tfe_text_view_open` to let the user select a file from GtkFileChooserDialog.
|
|
4. The dialog emits a signal and it invokes the handler `open_dialog_response`.
|
|
5. The handler read the file and set it into GtkTextBuffer and emits a signal to inform the response status.
|
|
6. The handler outside TfeTextView recieves the signal.
|
|
|
|
## Get file function
|
|
|
|
`gtk_text_view_get_file` is a simple function show as follows.
|
|
|
|
@@@ tfe5/tfetextview.c tfe_text_view_get_file
|
|
|
|
The important thing is duplicate `tv->file`.
|
|
Otherwise, if the caller free the GFile object, `tv->file` is no more guaranteed to point the GFile.
|
|
|
|
## Source file of tfetextview.c
|
|
|
|
All the source files are listed in [Section 13](ch13.html).
|