Geany
1.24.1
|
Document related actions: new, save, open, etc. More...
Data Structures | |
struct | GeanyDocument |
Structure for representing an open tab with all its properties. More... | |
struct | GeanyFilePrefs |
File Prefs. More... | |
Macros | |
#define | DOC_FILENAME(doc) (G_LIKELY((doc)->file_name != NULL) ? ((doc)->file_name) : GEANY_STRING_UNTITLED) |
Returns the filename of the document passed or GEANY_STRING_UNTITLED (e.g. More... | |
#define | DOC_VALID(doc_ptr) ((doc_ptr) != NULL && (doc_ptr)->is_valid) |
NULL-safe way to check doc_ptr->is_valid . More... | |
#define | documents ((GeanyDocument **)GEANY(documents_array)->pdata) |
Wraps documents_array so it can be used with C array syntax. More... | |
#define | documents_foreach(i) foreach_document(i) |
#define | foreach_document(i) |
Iterates all valid documents. More... | |
Typedefs | |
typedef struct GeanyFilePrefs | GeanyFilePrefs |
File Prefs. More... | |
Functions | |
gboolean | document_close (GeanyDocument *doc) |
Closes the given document. More... | |
gint | document_compare_by_display_name (gconstpointer a, gconstpointer b) |
Compares documents by their display names. More... | |
gint | document_compare_by_tab_order (gconstpointer a, gconstpointer b) |
Compares documents by their tab order. More... | |
gint | document_compare_by_tab_order_reverse (gconstpointer a, gconstpointer b) |
Compares documents by their tab order, in reverse order. More... | |
GeanyDocument * | document_find_by_filename (const gchar *utf8_filename) |
Finds a document with the given filename. More... | |
GeanyDocument * | document_find_by_real_path (const gchar *realname) |
Finds a document whose real_path field matches the given filename. More... | |
gchar * | document_get_basename_for_display (GeanyDocument *doc, gint length) |
Returns the last part of the filename of the given GeanyDocument. More... | |
GeanyDocument * | document_get_current (void) |
Finds the current document. More... | |
GeanyDocument * | document_get_from_page (guint page_num) |
Finds the document for the given notebook page page_num. More... | |
gint | document_get_notebook_page (GeanyDocument *doc) |
Gets the notebook page index for a document. More... | |
const GdkColor * | document_get_status_color (GeanyDocument *doc) |
Gets the status color of the document, or NULL if default widget coloring should be used. More... | |
GeanyDocument * | document_index (gint idx) |
Accessor function for GeanyData::documents_array items. More... | |
GeanyDocument * | document_new_file (const gchar *filename, GeanyFiletype *ft, const gchar *text) |
Creates a new document. More... | |
GeanyDocument * | document_open_file (const gchar *locale_filename, gboolean readonly, GeanyFiletype *ft, const gchar *forced_enc) |
Opens a document specified by locale_filename. More... | |
void | document_open_files (const GSList *filenames, gboolean readonly, GeanyFiletype *ft, const gchar *forced_enc) |
Opens each file in the list filenames. More... | |
gboolean | document_reload_file (GeanyDocument *doc, const gchar *forced_enc) |
Reloads the document with the specified file encoding forced_enc or NULL to auto-detect the file encoding. More... | |
gboolean | document_remove_page (guint page_num) |
Removes the given notebook tab at page_num and clears all related information in the document list. More... | |
void | document_rename_file (GeanyDocument *doc, const gchar *new_filename) |
Renames the file in doc to new_filename. More... | |
gboolean | document_save_file (GeanyDocument *doc, gboolean force) |
Saves the document. More... | |
gboolean | document_save_file_as (GeanyDocument *doc, const gchar *utf8_fname) |
Saves the document, detecting the filetype. More... | |
void | document_set_encoding (GeanyDocument *doc, const gchar *new_encoding) |
Sets the encoding of a document. More... | |
void | document_set_filetype (GeanyDocument *doc, GeanyFiletype *type) |
Sets the filetype of the document (which controls syntax highlighting and tags) More... | |
void | document_set_text_changed (GeanyDocument *doc, gboolean changed) |
Updates the tab labels, the status bar, the window title and some save-sensitive buttons according to the document's save state. More... | |
Variables | |
GPtrArray * | documents_array |
Dynamic array of GeanyDocument pointers holding information about the notebook tabs. More... | |
Document related actions: new, save, open, etc.
#define DOC_FILENAME | ( | doc | ) | (G_LIKELY((doc)->file_name != NULL) ? ((doc)->file_name) : GEANY_STRING_UNTITLED) |
Returns the filename of the document passed or GEANY_STRING_UNTITLED
(e.g.
_("untitled")) if the document's filename was not yet set. This macro never returns NULL
.
#define DOC_VALID | ( | doc_ptr | ) | ((doc_ptr) != NULL && (doc_ptr)->is_valid) |
NULL-safe
way to check doc_ptr->is_valid
.
This is useful when doc_ptr was stored some time earlier and documents may have been closed since then.
document_get_current()
!= NULL
. #define documents ((GeanyDocument **)GEANY(documents_array)->pdata) |
Wraps documents_array so it can be used with C array syntax.
Example: documents[0]->sci = NULL;
#define documents_foreach | ( | i | ) | foreach_document(i) |
Iterates all valid documents. Use like a for
statement.
i | guint index for document_index(). |
#define foreach_document | ( | i | ) |
Iterates all valid documents.
Use like a for
statement.
i | guint index for document_index(). |
typedef struct GeanyFilePrefs GeanyFilePrefs |
File Prefs.
gboolean document_close | ( | GeanyDocument * | doc | ) |
Closes the given document.
doc | The document to remove. |
TRUE
if the document was actually removed or FALSE
otherwise.gint document_compare_by_display_name | ( | gconstpointer | a, |
gconstpointer | b | ||
) |
Compares documents by their display names.
This matches GCompareFunc
for use with e.g. g_ptr_array_sort()
.
a | GeanyDocument** . |
b | GeanyDocument** . |
gint document_compare_by_tab_order | ( | gconstpointer | a, |
gconstpointer | b | ||
) |
Compares documents by their tab order.
This matches GCompareFunc
for use with e.g. g_ptr_array_sort()
.
a | GeanyDocument** . |
b | GeanyDocument** . |
gint document_compare_by_tab_order_reverse | ( | gconstpointer | a, |
gconstpointer | b | ||
) |
Compares documents by their tab order, in reverse order.
This matches GCompareFunc
for use with e.g. g_ptr_array_sort()
.
a | GeanyDocument** . |
b | GeanyDocument** . |
GeanyDocument* document_find_by_filename | ( | const gchar * | utf8_filename | ) |
Finds a document with the given filename.
This matches either an exact GeanyDocument::file_name string, or variant filenames with relative elements in the path (e.g. "/dir/..//name"
will match "/name"
).
utf8_filename | The filename to search (in UTF-8 encoding). |
NULL
. GeanyDocument* document_find_by_real_path | ( | const gchar * | realname | ) |
Finds a document whose real_path
field matches the given filename.
realname | The filename to search, which should be identical to the string returned by tm_get_real_path() . |
NULL
. TMWorkObject::file_name
. gchar* document_get_basename_for_display | ( | GeanyDocument * | doc, |
gint | length | ||
) |
Returns the last part of the filename of the given GeanyDocument.
The result is also truncated to a maximum of length characters in case the filename is very long.
doc | The document to use. |
length | The length of the resulting string or -1 to use a default value. |
GeanyDocument* document_get_current | ( | void | ) |
Finds the current document.
NULL
if there are no opened documents. GeanyDocument* document_get_from_page | ( | guint | page_num | ) |
Finds the document for the given notebook page page_num.
page_num | The notebook page number to search. |
NULL
. gint document_get_notebook_page | ( | GeanyDocument * | doc | ) |
Gets the notebook page index for a document.
doc | The document. |
const GdkColor* document_get_status_color | ( | GeanyDocument * | doc | ) |
Gets the status color of the document, or NULL
if default widget coloring should be used.
Returned colors are red if the document has changes, green if the document is read-only or simply NULL
if the document is unmodified but writable.
doc | The document to use. |
NULL
if the default color should be used. The color object is owned by Geany and should not be modified or freed.GeanyDocument* document_index | ( | gint | idx | ) |
Accessor function for GeanyData::documents_array items.
doc->is_valid
). idx | documents_array index. |
NULL
if idx is out of range.GeanyDocument* document_new_file | ( | const gchar * | utf8_filename, |
GeanyFiletype * | ft, | ||
const gchar * | text | ||
) |
Creates a new document.
Line endings in text will be converted to the default setting. Afterwards, the "document-new"
signal is emitted for plugins.
utf8_filename | The file name in UTF-8 encoding, or NULL to open a file as "untitled". |
ft | The filetype to set or NULL to detect it from filename if not NULL . |
text | The initial content of the file (in UTF-8 encoding), or NULL . |
GeanyDocument* document_open_file | ( | const gchar * | locale_filename, |
gboolean | readonly, | ||
GeanyFiletype * | ft, | ||
const gchar * | forced_enc | ||
) |
Opens a document specified by locale_filename.
Afterwards, the "document-open"
signal is emitted for plugins.
locale_filename | The filename of the document to load, in locale encoding. |
readonly | Whether to open the document in read-only mode. |
ft | The filetype for the document or NULL to auto-detect the filetype. |
forced_enc | The file encoding to use or NULL to auto-detect the file encoding. |
NULL
. void document_open_files | ( | const GSList * | filenames, |
gboolean | readonly, | ||
GeanyFiletype * | ft, | ||
const gchar * | forced_enc | ||
) |
Opens each file in the list filenames.
Internally, document_open_file() is called for every list item.
filenames | A list of filenames to load, in locale encoding. |
readonly | Whether to open the document in read-only mode. |
ft | The filetype for the document or NULL to auto-detect the filetype. |
forced_enc | The file encoding to use or NULL to auto-detect the file encoding. |
gboolean document_reload_file | ( | GeanyDocument * | doc, |
const gchar * | forced_enc | ||
) |
Reloads the document with the specified file encoding forced_enc or NULL
to auto-detect the file encoding.
doc | The document to reload. |
forced_enc | The file encoding to use or NULL to auto-detect the file encoding. |
TRUE
if the document was actually reloaded or FALSE
otherwise. gboolean document_remove_page | ( | guint | page_num | ) |
Removes the given notebook tab at page_num and clears all related information in the document list.
page_num | The notebook page number to remove. |
TRUE
if the document was actually removed or FALSE
otherwise. void document_rename_file | ( | GeanyDocument * | doc, |
const gchar * | new_filename | ||
) |
Renames the file in doc to new_filename.
Only the file on disk is actually renamed, you still have to call document_save_file_as() to change the doc object. It also stops monitoring for file changes to prevent receiving too many file change events while renaming. File monitoring is setup again in document_save_file_as().
doc | The current document which should be renamed. |
new_filename | The new filename in UTF-8 encoding. |
gboolean document_save_file | ( | GeanyDocument * | doc, |
gboolean | force | ||
) |
Saves the document.
Also shows the Save As dialog if necessary. If the file is not modified, this function may do nothing unless force is set to TRUE
.
Saving may include replacing tabs by spaces, stripping trailing spaces and adding a final new line at the end of the file, depending on user preferences. Then the "document-before-save"
signal is emitted, allowing plugins to modify the document before it is saved, and data is actually written to disk.
On successful saving:
"document-save"
signal is emitted for plugins.doc->file_name
has an absolute path unless you want the Save As dialog to be shown. A NULL
value also shows the dialog. This behaviour was added in Geany 1.22.doc | The document to save. |
force | Whether to save the file even if it is not modified. |
TRUE
if the file was saved or FALSE
if the file could not or should not be saved. gboolean document_save_file_as | ( | GeanyDocument * | doc, |
const gchar * | utf8_fname | ||
) |
Saves the document, detecting the filetype.
doc | The document for the file to save. |
utf8_fname | The new name for the document, in UTF-8, or NULL. |
TRUE
if the file was saved or FALSE
if the file could not be saved.void document_set_encoding | ( | GeanyDocument * | doc, |
const gchar * | new_encoding | ||
) |
Sets the encoding of a document.
This function only set the encoding of the document, it does not any conversions. The new encoding is used when e.g. saving the file.
doc | The document to use. |
new_encoding | The encoding to be set for the document. |
void document_set_filetype | ( | GeanyDocument * | doc, |
GeanyFiletype * | type | ||
) |
Sets the filetype of the document (which controls syntax highlighting and tags)
doc | The document to use. |
type | The filetype. |
void document_set_text_changed | ( | GeanyDocument * | doc, |
gboolean | changed | ||
) |
Updates the tab labels, the status bar, the window title and some save-sensitive buttons according to the document's save state.
This is called by Geany mostly when opening or saving files.
doc | The document to use. |
changed | Whether the document state should indicate changes have been made. |
GPtrArray* documents_array |
Dynamic array of GeanyDocument pointers holding information about the notebook tabs.
Once a pointer is added to this, it is never freed. This means you can keep a pointer to a document over time, but it might no longer represent a notebook tab. To check this, check doc_ptr->is_valid
. Of course, the pointer may represent a different file by then.
You also need to check GeanyDocument::is_valid
when iterating over this array, although usually you would just use the foreach_document() macro.
Never assume that the order of document pointers is the same as the order of notebook tabs. Notebook tabs can be reordered. Use document_get_from_page()
.