TfeTextView functions are described in this section.
The header file tfetextview.h
provides:
TFE_TYPE_TEXT_VIEW
.G_DECLARE_FINAL_TYPE
includes some
useful macros.open-response
signal is
defined..tfetextview.c
are declared.Therefore, Any programs use TfeTextView needs to include
tfetextview.h
.
@@@include tfetextview//tfetextview.h @@@
#pragma once
instead of
them. It is non-standard but widely used.gtk4
also has the same mechanism to avoid including it multiple times.TfeTextView
and TfeTextViewClass
are
declared as typedef of C structures._TfeTextView
later._TfeTextViewClass
is defined here.
You don’t need to define it by yourself.TFE_TEXT_VIEW ()
for casting and
TFE_IS_TEXT_VIEW
for type check are defined.A TfeTextView instance is created with tfe_text_view_new
or tfe_text_view_new_with_file
.
*tfe_text_view_new (void); GtkWidget
tfe_text_view_new
just creates a new TfeTextView
instance and returns the pointer to the new instance.
*tfe_text_view_new_with_file (GFile *file); GtkWidget
tfe_text_view_new_with_file
is given a Gfile object as
an argument and it loads the file into the GtkTextBuffer instance, then
returns the pointer to the new instance. If an error occurs during the
creation process, NULL is returned.
Each function is defined as follows.
@@@include tfetextview/tfetextview.c tfe_text_view_new_with_file tfe_text_view_new @@@
tfe_text_view_new
function. Just returns the
value from the function g_object_new
but casts it to the
pointer to GtkWidget. The function g_object_new
creates any
instances of its descendant class. The arguments are the type of the
class, property list and NULL. Null is the end mark of the property
list. TfeTextView “wrap-mode” property has GTK_WRAP_WORD_CHAR as the
default value.tfe_text_view_new_with_file
function.g_return_val_if_fail
is described in GLib API
Reference – g_return_val_if_fail. And also GLib API Reference –
Message Logging. 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.tfe_text_view_new
. The function
creates TfeTextView instance and returns the pointer to the instance. If
an error happens in tfe_text_view_new
, it returns
NULL.tv
. The pointer is assigned to tb
tb
.file
and sets tv->file
to point it.gtk_text_buffer_set_modified (tb, FALSE)
sets the
modification flag of tb
to FALSE. The modification flag
indicates that the contents of the buffer has been modified. It is used
when the contents are saved. If the modification flag is FALSE, it
doesn’t need to save the contents.contents
.tv
, which is a pointer to the newly created
TfeTextView instance. If an error happens, NULL is returned.Save and saveas functions write the contents in the GtkTextBuffer to a file.
void tfe_text_view_save (TfeTextView *tv)
The function tfe_text_view_save
writes the contents in
the GtkTextBuffer to a file specified by tv->file
. If
tv->file
is NULL, then it shows GtkFileChooserDialog and
prompts the user to choose a file to save. Then it saves the contents to
the file and sets tv->file
to point the GFile instance
for the file.
void tfe_text_view_saveas (TfeTextView *tv)
The function saveas
uses GtkFileChooserDialog and
prompts the user to select a existed file or specify a new file to save.
Then, the function changes tv->file
and save the
contents to the specified file. If an error occurs, it is shown to the
user through the message dialog. The error is managed only in the
TfeTextView and no information is notified to the caller.
@@@include tfetextview/tfetextview.c save_file @@@
save_file
is called from
saveas_dialog_response
and tfe_text_view_save
.
This function saves the contents of the buffer to the file given as an
argument. If error happens, it displays an error message. So, a caller
of this function don’t need to take care of errors. The class of this
function is static
. Therefore, only functions in this file
(tfetextview.c
) call this function. Such static functions
usually don’t have g_return_val_if_fail
function.g_file_replace_contents
writes the
contents to the file and returns the status (true = success/ false =
fail). It has many parameters, but some of them are almost always given
the same values.
G_FILE_CREATE_NONE
is
fine.gtk_window_destroy
, so that the dialog disappears when the
user clicks on the button.err
with g_error_free
function.contents
.@@@include tfetextview/tfetextview.c saveas_dialog_response @@@
saveas_dialog_response
is a signal handler
for the “response” signal on GtkFileChooserDialog. This handler analyzes
the response and determines whether to save the contents or not.GTK_RESPONSE_ACCEPT
, the user
has clicked on the Save
button and the contents will be
saved.file
from the
GtkFileChooserDialog.save_file
to save the contents
to the file.save_file
has successfully saved the
contents, the following will be done.
tv->file
is GFile and file
is a
different file, unref tv->file
.tv->file
is GFile and file
points
the same file as tv->file
, nothing needs to do.
Otherwise, tv->file
is set to file
and
“change-file” signal is emitted.file
.@@@include tfetextview/tfetextview.c tfe_text_view_save @@@
tfe_text_view_save
writes the contents to
the tv->file
file. It calls
tfe_text_view_saveas
or save_file
.static
class. Public functions should
check the parameter type with g_return_if_fail
function. If
tv
is not a pointer to a TfeTextView instance, then it logs
an error message and immediately returns. This function is similar to
g_return_val_if_fail
, but no value is returned because
tfe_text_view_save
doesn’t return a value (void).tb
and GtkWidget (GtkWindow)
win
are set. The function
gtk_widget_get_ancestor (widget, type)
returns the first
ancestor of the widget with type. The type is a GType. For example, the
type of GtkWindow is GTK_TYPE_WINDOW
and the one of
TfeTextView is TFE_TYPE_TEXT_VIEW
. Be careful. The
parent-child relationship here is the one for widgets, not classes. The
top level window may be a GtkApplicationWindow, but it depends on the
application. Because TfeTextView is a library, it can’t determine the
top level window type (GtkWindow or GtkApplicationWindow). GtkWindow is
a parent class of GtkApplication window so it is more general.
Therefore, TfeTextView takes GtkWindow as a top level window so that it
can be used by any application.tv->file
is NULL, which means no file has
given yet, it calls tfe_text_view_saveas
to prompt a user
to select a file and save the contents.tv->file
doesn’t point GFile, an error
message is logged out. It is not expected.save_file
to save the
contents to the file tv->file
.@@@include tfetextview/tfetextview.c tfe_text_view_saveas @@@
tfe_text_view_saveas
shows
GtkFileChooserDialog and prompts the user to choose a file and save the
contents.tv
because the caller may be
other object. This function is public.win
is set to the top level window.GTK_FILE_CHOOSER_ACTION_OPEN
,
GTK_FILE_CHOOSER_ACTION_SAVE
and
GTK_FILE_CHOOSER_ACTION_SELECT_FOLDER
. When you want to
save a file, GTK_FILE_CHOOSER_ACTION_SAVE
is the
action.win
, save mode action, cancel and save button.saveas_dialog_response
handler.When you use GtkFileChooserDialog, you need to divide the program
into two parts. One is a function which creates GtkFileChooserDialog and
the other is a signal handler. The function just creates and shows
GtkFileChooserDialog. The rest is done by the handler. It gets Gfile
from GtkFileChooserDialog and saves the buffer to the file by calling
save_file
.
Open function shows GtkFileChooserDialog to a user and prompts them to choose a file. Then it reads the file and puts the text into GtkTextBuffer.
void tfe_text_view_open (TfeTextView *tv, GtkWindow *win);
The parameter win
is the top-level window. It will be a
transient parent window of GtkFileChooserDialog when the dialog is
created.
This function may be called just after tv
has been
created. In that case, tv
has not been incorporated into
the widget hierarchy. Therefore it is impossible to get the top-level
window from tv
. That’s why the function needs
win
parameter.
This function is usually called when the buffer of tv
is
empty. However, even if the buffer 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 appropriate.
Open and read process is divided into two phases. One is showing GtkFileChooserDialog and the other is its response handler. The response handler gets the filename, reads the contents of the file and puts it into the GtkTextBuffer.
@@@include tfetextview/tfetextview.c open_dialog_response @@@
open_dialog_response
has three
parameters.
GTK_RESPONSE_ACCEPT
, the
user has clicked on the “Cancel” button or close button on the header
bar. Then, “open-response” signal is emitted. The parameter of the
signal is TFE_OPEN_RESPONSE_CANCEL
.gtk_file_chooser_get_file
. If it doesn’t point GFile, maybe
an error has occurred. It is not expected, though. Then it emits
“open-response” signal with the parameter
TFE_OPEN_RESPONSE_ERROR
.TFE_OPEN_RESPONSE_ERROR
.contents
is freedTFE_OPEN_REPONSE_SUCCESS
tv->file
isn’t NULL,
g_object_unref(tv->file)
is calledtv->file
is assigned with file
@@@include tfetextview/tfetextview.c tfe_text_view_open @@@
tv
and
win
. Public functions always need to check the
arguments.win
.The whole process between the caller and TfeTextView is shown in the following diagram. It is really complicated. Because signal is the only way for GtkFileChooserDialog to communicate with others.
tv
to a TfeTextView instance by
calling tfe_text_view_new
.tfe_text_view_open
to prompt the user to
select a file from GtkFileChooserDialog.open_dialog_response
.You can get the GFile in a TfeTextView instance with
tfe_text_view_get_file
. It is very simple.
@@@include tfetextview/tfetextview.c tfe_text_view_get_file @@@
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 API Reference –
g_file_dup.
Refer API
document of TfeTextView. The markdown file is under the directory
src/tfetextview
.
You can find all the TfeTextView source codes under src/tfetextview directories.