HybridDog/geany
1
0
Fork 0
Code Issues Pull Requests Packages Projects Releases Wiki Activity

Add support for generating API reference documentation using doxygen.

Browse Source 
This is the first step, it is far away from being complete.
Add make target "api-doc" to generate the reference documentation.
Add documentation comments to a few functions.
Move basic plugin documentation from plugindata.h to doc/plugins.dox.	       


git-svn-id: https://geany.svn.sourceforge.net/svnroot/geany/trunk@2263 ea778897-0a13-0410-b9d1-a72fbfd435f5
This commit is contained in:
Enrico Tröger 2008-02-17 18:00:42 +00:00
parent 753e2936d8
commit 0e65cff820
14 changed files with 967 additions and 228 deletions
Show Stats Download Patch File Download Diff File Expand all files Collapse all files

13
ChangeLog
View File

@ -1,3 +1,16 @@
2008-02-17 Enrico Tröger <enrico(dot)troeger(at)uvena(dot)de>
* configure.in, doc/Doxyfile.in, doc/Makefile.am, doc/plugins.dox,
src/dialogs.c, src/dialogs.h, src/document.c, src/document.h,
src/encodings.c, src/encodings.h, src/plugindata.h, src/utils.c,
src/utils.h:
Add support for generating API reference documentation using doxygen.
This is the first step, it is far away from being complete.
Add make target "api-doc" to generate the reference documentation.
Add documentation comments to a few functions.
Move basic plugin documentation from plugindata.h to doc/plugins.dox.
2008-02-16 Enrico Tröger <enrico(dot)troeger(at)uvena(dot)de>
* doc/geany.html, doc/geany.txt:

1
configure.in
View File

@ -232,6 +232,7 @@ doc/Makefile
doc/geany.1
geany.spec
geany.desktop.in
doc/Doxyfile
])
echo "----------------------------------------"

270
doc/Doxyfile.in Normal file
View File

@ -0,0 +1,270 @@
# Doxyfile 1.5.4
#---------------------------------------------------------------------------
# Project related configuration options
#---------------------------------------------------------------------------
DOXYFILE_ENCODING = UTF-8
PROJECT_NAME = Geany
PROJECT_NUMBER = @VERSION@
OUTPUT_DIRECTORY = ./
CREATE_SUBDIRS = NO
OUTPUT_LANGUAGE = English
BRIEF_MEMBER_DESC = YES
REPEAT_BRIEF = YES
ABBREVIATE_BRIEF = "The $name class " \
"The $name widget " \
"The $name file " \
is \
provides \
specifies \
contains \
represents \
a \
an \
the
ALWAYS_DETAILED_SEC = NO
INLINE_INHERITED_MEMB = NO
FULL_PATH_NAMES = NO
STRIP_FROM_PATH =
STRIP_FROM_INC_PATH =
SHORT_NAMES = NO
JAVADOC_AUTOBRIEF = YES
QT_AUTOBRIEF = NO
MULTILINE_CPP_IS_BRIEF = NO
DETAILS_AT_TOP = NO
INHERIT_DOCS = YES
SEPARATE_MEMBER_PAGES = NO
TAB_SIZE = 4
# ALIASES taken from pidgin
ALIASES = "signal=- @ref " \
"signaldef=@subsection " \
"endsignaldef= " \
"signalproto=@code " \
"endsignalproto=@endcode " \
"signaldesc=@par Description: " \
"signals=@b Signals: " \
"endsignals= "
OPTIMIZE_OUTPUT_FOR_C = YES
OPTIMIZE_OUTPUT_JAVA = NO
BUILTIN_STL_SUPPORT = NO
CPP_CLI_SUPPORT = NO
SIP_SUPPORT = NO
DISTRIBUTE_GROUP_DOC = NO
SUBGROUPING = YES
TYPEDEF_HIDES_STRUCT = YES
#---------------------------------------------------------------------------
# Build related configuration options
#---------------------------------------------------------------------------
EXTRACT_ALL = NO
EXTRACT_PRIVATE = NO
EXTRACT_STATIC = NO
EXTRACT_LOCAL_CLASSES = YES
EXTRACT_LOCAL_METHODS = NO
EXTRACT_ANON_NSPACES = NO
HIDE_UNDOC_MEMBERS = YES
HIDE_UNDOC_CLASSES = YES
HIDE_FRIEND_COMPOUNDS = NO
HIDE_IN_BODY_DOCS = YES
INTERNAL_DOCS = NO
CASE_SENSE_NAMES = YES
HIDE_SCOPE_NAMES = NO
SHOW_INCLUDE_FILES = NO
INLINE_INFO = NO
SORT_MEMBER_DOCS = YES
SORT_BRIEF_DOCS = YES
SORT_BY_SCOPE_NAME = NO
GENERATE_TODOLIST = YES
GENERATE_TESTLIST = NO
GENERATE_BUGLIST = YES
GENERATE_DEPRECATEDLIST= NO
ENABLED_SECTIONS =
MAX_INITIALIZER_LINES = 30
SHOW_USED_FILES = NO
SHOW_DIRECTORIES = NO
FILE_VERSION_FILTER =
#---------------------------------------------------------------------------
# configuration options related to warning and progress messages
#---------------------------------------------------------------------------
QUIET = NO
WARNINGS = YES
WARN_IF_UNDOCUMENTED = YES
WARN_IF_DOC_ERROR = YES
WARN_NO_PARAMDOC = YES
WARN_FORMAT = "$file:$line: $text "
WARN_LOGFILE =
#---------------------------------------------------------------------------
# configuration options related to the input files
#---------------------------------------------------------------------------
INPUT = ../src/ ./
INPUT_ENCODING = UTF-8
FILE_PATTERNS = *.c \
*.cc \
*.cxx \
*.cpp \
*.c++ \
*.h \
*.hh \
*.hxx \
*.hpp \
*.h++ \
*.dox \
*.py \
*.C \
*.CC \
*.C++ \
*.H \
*.HH \
*.H++ \
*.dox \
RECURSIVE = NO
EXCLUDE =
EXCLUDE_SYMLINKS = NO
EXCLUDE_PATTERNS =
EXCLUDE_SYMBOLS =
EXAMPLE_PATH =
EXAMPLE_PATTERNS = *
EXAMPLE_RECURSIVE = NO
IMAGE_PATH =
INPUT_FILTER =
FILTER_PATTERNS =
FILTER_SOURCE_FILES = NO
#---------------------------------------------------------------------------
# configuration options related to source browsing
#---------------------------------------------------------------------------
SOURCE_BROWSER = NO
INLINE_SOURCES = NO
STRIP_CODE_COMMENTS = YES
REFERENCED_BY_RELATION = NO
REFERENCES_RELATION = NO
REFERENCES_LINK_SOURCE = YES
USE_HTAGS = NO
VERBATIM_HEADERS = NO
#---------------------------------------------------------------------------
# configuration options related to the alphabetical class index
#---------------------------------------------------------------------------
ALPHABETICAL_INDEX = NO
COLS_IN_ALPHA_INDEX = 5
IGNORE_PREFIX =
#---------------------------------------------------------------------------
# configuration options related to the HTML output
#---------------------------------------------------------------------------
GENERATE_HTML = YES
HTML_OUTPUT = reference/
HTML_FILE_EXTENSION = .html
HTML_HEADER =
HTML_FOOTER =
HTML_STYLESHEET =
HTML_ALIGN_MEMBERS = YES
GENERATE_HTMLHELP = NO
HTML_DYNAMIC_SECTIONS = NO
CHM_FILE =
HHC_LOCATION =
GENERATE_CHI = NO
BINARY_TOC = NO
TOC_EXPAND = NO
DISABLE_INDEX = NO
ENUM_VALUES_PER_LINE = 4
GENERATE_TREEVIEW = NO
TREEVIEW_WIDTH = 250
#---------------------------------------------------------------------------
# configuration options related to the LaTeX output
#---------------------------------------------------------------------------
GENERATE_LATEX = NO
LATEX_OUTPUT = latex
LATEX_CMD_NAME = latex
MAKEINDEX_CMD_NAME = makeindex
COMPACT_LATEX = NO
PAPER_TYPE = a4wide
EXTRA_PACKAGES =
LATEX_HEADER =
PDF_HYPERLINKS = NO
USE_PDFLATEX = NO
LATEX_BATCHMODE = NO
LATEX_HIDE_INDICES = NO
#---------------------------------------------------------------------------
# configuration options related to the RTF output
#---------------------------------------------------------------------------
GENERATE_RTF = NO
RTF_OUTPUT = rtf
COMPACT_RTF = NO
RTF_HYPERLINKS = NO
RTF_STYLESHEET_FILE =
RTF_EXTENSIONS_FILE =
#---------------------------------------------------------------------------
# configuration options related to the man page output
#---------------------------------------------------------------------------
GENERATE_MAN = NO
MAN_OUTPUT = man
MAN_EXTENSION = .3
MAN_LINKS = NO
#---------------------------------------------------------------------------
# configuration options related to the XML output
#---------------------------------------------------------------------------
GENERATE_XML = NO
XML_OUTPUT = xml
XML_SCHEMA =
XML_DTD =
XML_PROGRAMLISTING = YES
#---------------------------------------------------------------------------
# configuration options for the AutoGen Definitions output
#---------------------------------------------------------------------------
GENERATE_AUTOGEN_DEF = NO
#---------------------------------------------------------------------------
# configuration options related to the Perl module output
#---------------------------------------------------------------------------
GENERATE_PERLMOD = NO
PERLMOD_LATEX = NO
PERLMOD_PRETTY = YES
PERLMOD_MAKEVAR_PREFIX =
#---------------------------------------------------------------------------
# Configuration options related to the preprocessor
#---------------------------------------------------------------------------
ENABLE_PREPROCESSING = YES
MACRO_EXPANSION = YES
EXPAND_ONLY_PREDEF = YES
SEARCH_INCLUDES = NO
INCLUDE_PATH =
INCLUDE_FILE_PATTERNS =
# make G_GNUC_PRINTF a no-op unless doxygen would ignore functions with varargs
PREDEFINED = "G_GNUC_PRINTF(x,y)="
EXPAND_AS_DEFINED =
SKIP_FUNCTION_MACROS = NO
#---------------------------------------------------------------------------
# Configuration::additions related to external references
#---------------------------------------------------------------------------
TAGFILES =
GENERATE_TAGFILE =
ALLEXTERNALS = NO
EXTERNAL_GROUPS = YES
PERL_PATH = /usr/bin/perl
#---------------------------------------------------------------------------
# Configuration options related to the dot tool
#---------------------------------------------------------------------------
CLASS_DIAGRAMS = NO
MSCGEN_PATH =
HIDE_UNDOC_RELATIONS = YES
HAVE_DOT = NO
CLASS_GRAPH = YES
COLLABORATION_GRAPH = YES
GROUP_GRAPHS = YES
UML_LOOK = NO
TEMPLATE_RELATIONS = NO
INCLUDE_GRAPH = YES
INCLUDED_BY_GRAPH = YES
CALL_GRAPH = NO
CALLER_GRAPH = NO
GRAPHICAL_HIERARCHY = YES
DIRECTORY_GRAPH = YES
DOT_IMAGE_FORMAT = png
DOT_PATH =
DOTFILE_DIRS =
DOT_GRAPH_MAX_NODES = 50
MAX_DOT_GRAPH_DEPTH = 1000
DOT_TRANSPARENT = YES
DOT_MULTI_TARGETS = NO
GENERATE_LEGEND = YES
DOT_CLEANUP = YES
#---------------------------------------------------------------------------
# Configuration::additions related to the search engine
#---------------------------------------------------------------------------
SEARCHENGINE = NO

5
doc/Makefile.am
View File

@ -1,7 +1,7 @@
man_MANS=geany.1
DOCDIR = $(DESTDIR)/$(datadir)/doc/@PACKAGE@
IMAGE_FILES = images/*.png
EXTRA_DIST = geany.html geany.css geany.txt geany.1 \
EXTRA_DIST = geany.html geany.css geany.txt geany.1 plugins.dox \
$(srcdir)/$(IMAGE_FILES)
pdf: geany.txt
@ -10,6 +10,9 @@ pdf: geany.txt
rm -f geany.tex geany.aux geany.log geany.out
mv $(srcdir)/geany.pdf geany-$(VERSION).pdf
api-doc: Doxyfile
doxygen >/dev/null
doc: geany.txt
rst2html -stg --stylesheet=geany.css $(srcdir)/geany.txt geany.html

266
doc/plugins.dox Normal file
View File

@ -0,0 +1,266 @@
/*
* plugins.dox - this file is part of Geany, a fast and lightweight IDE
*
* Copyright 2008 Enrico Tröger <enrico(dot)troeger(at)uvena(dot)de>
* Copyright 2008 Nick Treleaven <nick(dot)treleaven(at)btinternet(dot)com>
*
* This program is free software; you can redistribute it and/or modify
* it under the terms of the GNU General Public License as published by
* the Free Software Foundation; either version 2 of the License, or
* (at your option) any later version.
*
* This program is distributed in the hope that it will be useful,
* but WITHOUT ANY WARRANTY; without even the implied warranty of
* MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the
* GNU General Public License for more details.
*
* You should have received a copy of the GNU General Public License
* along with this program; if not, write to the Free Software
* Foundation, Inc., 51 Franklin Street, Fifth Floor, Boston,
* MA 02110-1301, USA.
*
* $Id$
*
* This file contains additional plugin documentation like the signal system and a small howto.
* It is best viewed when filetype is set to C or C++.
*/
/**
*
* @mainpage Geany Plugin API Documentation
*
* @author Enrico Tröger, Nick Treleaven
* @date $Date$
*
* @section Intro
* This is the Geany API documentation. It is far from being complete and should be
* considered as a work in progress.
* We will try to %document as many functions and structs as possible.
*
* For additional documentation of things like plugin signals or a simple plugin please
* see Related Pages.
*
*
*
* @page symbols Plugin Symbols
*
* The following symbols (functions) should be exported by every plugin. Some of them
* are optional, i.e. they can be omitted, others are required and must be defined.
*
* - @code version_check() @endcode
* Use VERSION_CHECK() macro instead. Required by Geany.
*
* - @code PluginInfo* info() @endcode
* Use PLUGIN_INFO() macro to define it. Required by Geany.
*
* - @code GeanyData* geany_data @endcode
* Geany owned fields and functions.
*
* - @code PluginFields* plugin_fields @endcode
* Plugin owned fields, including flags.
*
* - @code GeanyCallback geany_callbacks[] @endcode
* An array for connecting GeanyObject events, which should be terminated with
* {NULL, NULL, FALSE, NULL}. See @link signals Signal documentation @endlink.
*
* - @code void configure(GtkWidget *parent) @endcode
* Called when the plugin should show a configure dialog to let the user set some basic
* plugin configuration. Optionally, can be omitted when not needed.
*
* - @code void init(GeanyData *data) @endcode
* Called after loading the plugin. data is the same as geany_data.
*
* - @code void cleanup() @endcode
* Called before unloading the plugin. Required for normal plugins - it should undo
* everything done in init() - e.g. destroy menu items, free memory.
*
*
*
* @page signals Plugin Signals
*
*
* @section Usage
*
* To use plugin signals in Geany, you simply create a GeanyCallback array, list the signals
* you want to listen to and create the appropiate signal callbacks for each signal.
* @note The GeanyCallback array has be ended with a final NULL entry.
*
* The following code demonstrates how to use signals in Geany plugins. The code can be inserted
* in your plugin code at any desired position.
*
* @code
static void on_document_open(GObject *obj, gint idx, gpointer user_data)
{
printf("Example: %s was opened\n", DOC_FILENAME(idx));
}
GeanyCallback geany_callbacks[] =
{
{ "document-open", (GCallback) &on_document_open, FALSE, NULL },
{ NULL, NULL, FALSE, NULL }
};
* @endcode
*
* @section Signals
*
* @signaldef document-new
* @signalproto
* void user_function(GObject *obj, gint idx, gpointer user_data);
* @endsignalproto
* @signaldesc
* Sent when a new %document is created.
* @param obj a GeanyObject instance, should be ignored.
* @param idx the index of the new %document.
* @param user_data user data.
* @endsignaldef
*
* @signaldef document-open
* @signalproto
* void user_function(GObject *obj, gint idx, gpointer user_data);
* @endsignalproto
* @signaldesc
* Sent when a new %document is opened.
* @param obj a GeanyObject instance, should be ignored.
* @param idx the index of the opened %document.
* @param user_data user data.
* @endsignaldef
*
* @signaldef document-save
* @signalproto
* void user_function(GObject *obj, gint idx, gpointer user_data);
* @endsignalproto
* @signaldesc
* Sent when a new %document is saved.
* @param obj a GeanyObject instance, should be ignored.
* @param idx the index of the saved %document.
* @param user_data user data.
* @endsignaldef
*
* @signaldef document-activate
* @signalproto
* void user_function(GObject *obj, gint idx, gpointer user_data);
* @endsignalproto
* @signaldesc
* Sent when switching notebook pages.
* @param obj a GeanyObject instance, should be ignored.
* @param idx the index of the new %document.
* @param user_data user data.
* @endsignaldef
*
* @signaldef project-open
* @signalproto
* void user_function(GObject *obj, GKeyFile *config, gpointer user_data);
* @endsignalproto
* @signaldesc
* Sent after a project is opened but before session files are loaded.
* @param obj a GeanyObject instance, should be ignored.
* @param config an exising GKeyFile object which can be used to read and write data.
* It must not be closed or freed.
* @param user_data user data.
* @endsignaldef
*
* @signaldef project-save
* @signalproto
* void user_function(GObject *obj, GKeyFile *config, gpointer user_data);
* @endsignalproto
* @signaldesc
* Sent when a project is saved(happens when the project is created, the properties
* dialog is closed or Geany is exited). This signal is emitted shortly before Geany
* will write the contents of the GKeyFile to the disc.
* @param obj a GeanyObject instance, should be ignored.
* @param config an exising GKeyFile object which can be used to read and write data.
* It must not be closed or freed.
* @param user_data user data.
* @endsignaldef
*
* @signaldef project-close
* @signalproto
* void user_function(GObject *obj, GKeyFile *config, gpointer user_data);
* @endsignalproto
* @signaldesc
* Sent after a project is closed.
* @param obj a GeanyObject instance, should be ignored.
* @param config an exising GKeyFile object which can be used to read and write data.
* It must not be closed or freed.
* @param user_data user data.
* @endsignaldef
*
*
*
* @page howto Plugin Howto
*
* @section intro Introduction
*
* Since Geany 0.12 there is a plugin interface to extend Geany's functionality and
* add new features. This %document gives a briefly overview about how to add new
* plugins by writing a simple "Hello World" plugin in C.
*
*
* @section start Getting started
*
* @subsection structure Plugin structure
*
* Every plugin must contain some essential symbols unless it won't work. A complete
* list of all necessary and optional symbols can be found in
* @link symbols Plugin Symbols @endlink.
* Every plugin should include "geany.h" and "plugindata.h" which provide necessary
* preprocessor macros and other basic information.
* There are two important preprocessor macros which need to be used at the beginning:
* PLUGIN_INFO() and VERSION_CHECK().
*
* PLUGIN_INFO() tells Geany about basic plugin information like name, description,
* version and author of the plugin.
*
* VERSION_CHECK() checks for compatibility of the API version which the plugin uses with
* the used Geany sources. Furthermore, it also checks the binary compatiblity of the plugin
* with Geany.
*
* A few functions are necessary to let Geany work with the plugin, at least init() must
* exist in the plugin. cleanup() should also be used to free allocated memory or destroy
* created widgets.
*
* @subsection buildenv Build environment
*
* To be able to write plugins for Geany, you need the source code and some development
* packages for GTK and its dependencies. I will only describe the way to compile and
* build plugins on Unix-like systems [1].
* If you already have the Geany source code and compiled it from them, you can skip the
* following.
*
* First you need to get the source code of Geany from the website at
* http://geany.uvena.de/Download/Releases [2]. Then install the development files for GTK
* and its dependencies. The easiest way to do this is to use your distribution's package
* management system, e.g. on Debian and Ubuntu systems you can use
* @code apt-get install libgtk2.0-dev intltool @endcode
* This will install all necessary files to be able to compile Geany and plugins. On other
* distributions, the package names and commands to use may differ.
*
* Basically, we are done at this point and could continue with writing the plugin code.
* You don't need necessarily to configure and build the Geany sources when the sources
* have the same version as your running Geany installation. But if the version of the
* sources differ from your Geany installation or especially when you used the source code
* from the Subversion repository, we strongly recommend to configure and build these
* sources and use it. To do so, run @code
./configure && make
su -c "make install"
* @endcode
* in your Geany source directory. This will build and install Geany on your system.
*
* [1] For Windows, it is basically the same but you might have some more work on setting up
* the general build environment(compiler, GTK development files, ...). This is described on
* Geany's website at http://geany.uvena.de/Support/BuildingOnWin32.
*
* [2] You can also use the bleedging edge source code from our Subversion repository.
* More information about this can be found at http://geany.uvena.de/Download/SVN.
*
* @section helloworld "Hello World"
*
* We want to write a really simple "Hello World" plugin which opens a message dialog
* and just prints "Hello World".
*
*
* ... to be continued ...
*
*
**/

29
src/dialogs.c
View File

@ -581,8 +581,11 @@ static gboolean gtk_show_save_as(const gchar *initdir)
#endif
/* Show the Save As dialog for the current notebook page.
* Returns: TRUE if the file was saved. */
/**
* Show the Save As dialog for the current notebook page.
*
* @return @a TRUE if the file was saved, otherwise @a FALSE.
**/
gboolean dialogs_show_save_as()
{
gboolean result;
@ -607,6 +610,16 @@ gboolean dialogs_show_save_as()
}
/**
* Show a message box of the type @c type with @c text.
* On Unix-like systems a GTK message dialog box is shown, on Win32 systems a native Windows
* message dialog box is shown.
*
* @param type A GtkMessageType, can be one of: GTK_MESSAGE_INFO, GTK_MESSAGE_WARNING,
* GTK_MESSAGE_QUESTION, GTK_MESSAGE_ERROR
* @param text Printf()-style format string.
* @param ... Arguments for the @c text format string.
**/
void dialogs_show_msgbox(gint type, const gchar *text, ...)
{
#ifndef G_OS_WIN32
@ -1300,7 +1313,7 @@ void dialogs_show_file_properties(gint idx)
static gboolean show_question(GtkWidget *parent, const gchar *yes_btn, const gchar *no_btn,
const gchar *question_text, const gchar *extra_text)
const gchar *question_text, const gchar *extra_text)
{
gboolean ret = FALSE;
#ifdef G_OS_WIN32
@ -1337,6 +1350,16 @@ static gboolean show_question(GtkWidget *parent, const gchar *yes_btn, const gch
}
/**
* Show a question message box with @c text and Yes/No buttons.
* On Unix-like systems a GTK message dialog box is shown, on Win32 systems a native Windows
* message dialog box is shown.
*
* @param text Printf()-style format string.
* @param ... Arguments for the @c text format string.
*
* @return @a TRUE if the user answered with Yes, otherwise @a FALSE.
**/
gboolean dialogs_show_question(const gchar *text, ...)
{
gboolean ret = FALSE;

5
src/dialogs.h
View File

@ -21,6 +21,11 @@
* $Id$
*/
/**
* @file dialogs.h
* File related dialogs, miscellaneous dialogs, font dialog.
**/
#ifndef GEANY_DIALOGS_H
#define GEANY_DIALOGS_H 1

152
src/document.c
View File

@ -22,8 +22,8 @@
*/
/*
* Document related actions: new, save, open, etc.
* Also Scintilla search actions.
* Document related actions: new, save, open, etc.
* Also Scintilla search actions.
*/
#include "geany.h"
@ -121,10 +121,17 @@ static gchar *get_real_path_from_utf8(const gchar *utf8_filename)
}
/* filename is in UTF-8 for non-TagManager filenames.
* is_tm_filename should only be used when passing a TagManager filename,
* which is therefore locale-encoded and already a realpath().
* Returns: the document index which has the given filename. */
/**
* Find and retrieve the index of the given filename @a filename in the %document list.
*
* @param filename The filename to search (in UTF-8 encoding for non-TagManager filenames,
* else in locale encoding).
* @param is_tm_filename Whether the passed @a filename is a TagManager filename and therefore
* locale-encoded and already a realpath().
*
* @return The %document index which has the given filename @a filename or @c -1
* if @a filename is not open.
**/
gint document_find_by_filename(const gchar *filename, gboolean is_tm_filename)
{
guint i;
@ -187,7 +194,14 @@ gint document_get_notebook_page(gint doc_idx)
}
/* returns the index of the given notebook page in the document list */
/**
* Find and retrieve the index of the given notebook page @a page_num in the %document list.
*
* @param page_num The notebook page number to search.
*
* @return The index of the given notebook page @a page_num in the %document list or @c -1
* if no documents are opened.
**/
gint document_get_n_idx(guint page_num)
{
ScintillaObject *sci;
@ -200,7 +214,12 @@ gint document_get_n_idx(guint page_num)
}
/* returns the index of the current notebook page in the document list */
/**
* Find and retrieve the index of the current %document.
*
* @return The index of the current notebook page in the %document list or @c -1
* if no documents are opened.
**/
gint document_get_cur_idx()
{
gint cur_page = gtk_notebook_get_current_page(GTK_NOTEBOOK(app->notebook));
@ -217,7 +236,11 @@ gint document_get_cur_idx()
}
/* returns NULL if no documents are open */
/**
* Find and retrieve the current %document.
*
* @return A pointer to the current %document or @c NULL if there are no opened documents.
**/
document *document_get_current()
{
gint idx = document_get_cur_idx();
@ -238,6 +261,13 @@ void document_finalize()
}
/**
* Update 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.
*
* @param idx The %document index to operate on.
**/
void document_set_text_changed(gint idx)
{
if (DOC_IDX_VALID(idx) && ! main_status.quitting)
@ -478,7 +508,14 @@ static gint document_create_new_sci(const gchar *filename)
}
/* removes the given notebook tab and clears the related entry in the document list */
/**
* Remove the given notebook tab at @a page_num and clear all related information
* in the document list.
*
* @param page_num The notebook page number to remove.
*
* @return @a TRUE if the document was actually removed or @a FALSE otherwise.
**/
gboolean document_remove(guint page_num)
{
gint idx = document_get_n_idx(page_num);
@ -516,7 +553,11 @@ gboolean document_remove(guint page_num)
build_menu_update(-1);
}
}
else geany_debug("Error: idx: %d page_num: %d", idx, page_num);
else
{
geany_debug("Error: idx: %d page_num: %d", idx, page_num);
return FALSE;
}
return TRUE;
}
@ -531,12 +572,16 @@ static void store_saved_encoding(gint idx)
}
/* Create a new document.
* filename is either the UTF-8 file name, or NULL.
* If ft is NULL and filename is not NULL, then the filetype will be guessed
* from the given filename.
* text is the contents of the new file in valid UTF-8 encoding, or NULL.
* Returns: idx of new file in doc_list. */
/**
* Creates a new %document.
* After all, the "document-new" signal is emitted for plugins.
*
* @param filename The file name in UTF-8 encoding, or @c NULL to open a file as "untitled".
* @param ft The filetype to set or @c NULL to detect it from @a filename if not @c NULL.
* @param text The initial content of the file (in UTF-8 encoding), or @c NULL.
*
* @return The index of the new file in the @ref doc_list array.
**/
gint document_new_file(const gchar *filename, filetype *ft, const gchar *text)
{
gint idx = document_create_new_sci(filename);
@ -597,11 +642,30 @@ gint document_new_file(const gchar *filename, filetype *ft, const gchar *text)
}
/* This is a wrapper for document_open_file_full(), see that function for details.
* Do not use this when opening multiple files (unless using document_delay_colourise()). */
/**
* Open a %document specified by @a locale_filename.
* After all, the "document-open" signal is emitted for plugins.
*
* When opening more than one file, either:
* -# Use document_open_files().
* -# Call document_delay_colourise() before document_open_file() and
* document_colourise_new() after opening all files.
*
* This avoids unnecessary recolourising, saving significant processing when a lot of files
* are open of a %filetype that supports user typenames, e.g. C.
*
* @param locale_filename The filename of the %document to load, in locale encoding.
* @param readonly Whether to open the %document in read-only mode.
* @param ft The %filetype for the %document or @c NULL to auto-detect the %filetype.
* @param forced_enc The file encoding to use or @c NULL to auto-detect the file encoding.
*
* @return The index of the opened file or -1 if an error occurred.
**/
gint document_open_file(const gchar *locale_filename, gboolean readonly,
filetype *ft, const gchar *forced_enc)
{
/* This is a wrapper for document_open_file_full().
* Do not use this when opening multiple files (unless using document_delay_colourise()). */
return document_open_file_full(-1, locale_filename, 0, readonly, ft, forced_enc);
}
@ -1087,8 +1151,18 @@ void document_open_file_list(const gchar *data, gssize length)
}
/* Takes a linked list of filename URIs and opens each file, ensuring the newly opened
* documents and existing documents (if necessary) are only colourised once. */
/**
* Opens each file in the list @a filenames, ensuring the newly opened documents and
* existing documents (if necessary) are only colourised once.
* Internally, document_open_file() is called for every list item.
*
* @param filenames A list of filenames to load, in locale encoding.
* @param readonly Whether to open the %document in read-only mode.
* @param ft The %filetype for the %document or @c NULL to auto-detect the %filetype.
* @param forced_enc The file encoding to use or @c NULL to auto-detect the file encoding.
*
* @return The index of the opened file or -1 if an error occurred.
**/
void document_open_files(const GSList *filenames, gboolean readonly, filetype *ft,
const gchar *forced_enc)
{
@ -1104,9 +1178,15 @@ void document_open_files(const GSList *filenames, gboolean readonly, filetype *f
}
/* Reload document with index idx.
* forced_enc can be NULL to detect the file encoding.
* Returns: TRUE if successful. */
/**
* Reloads the %document with the given index @a idx with the specified file encoding
* @a forced_enc or @c NULL to auto-detect the file encoding.
*
* @param idx The %document index for the file to reload.
* @param forced_enc The file encoding to use or @c NULL to auto-detect the file encoding.
*
* @return @a TRUE if the %document was actually reloaded or @a FALSE otherwise.
**/
gboolean document_reload_file(gint idx, const gchar *forced_enc)
{
gint pos = 0;
@ -1170,9 +1250,19 @@ static void get_line_column_from_pos(gint idx, guint byte_pos, gint *line, gint
}
/* This saves the file.
* When force is set then it is always saved, even if it is unchanged(useful when using Save As)
* It returns whether the file could be saved or not. */
/**
* Save the %document specified by @a idx. Saving includes replacing tabs by spaces,
* stripping trailing spaces and adding a final new line at the end of the file (all only if
* user enabled these features). The filetype is set again or auto-detected if it wasn't
* set yet. After all, the "document-save" signal is emitted for plugins.
*
* If the file is not modified, this functions does nothing unless force is set to @c TRUE.
*
* @param idx The %document index for the file to save.
* @param force Whether to save the file even if it is not modified (e.g. for Save As).
*
* @return @c TRUE if the file was saved or @c FALSE if the file could not or should not be saved.
**/
gboolean document_save_file(gint idx, gboolean force)
{
gchar *data;
@ -2161,6 +2251,14 @@ void document_ensure_final_newline(gint idx)
}
/**
* 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.
*
* @param idx The index of the %document.
* @param new_encoding The encoding to be set for the %document.
**/
void document_set_encoding(gint idx, const gchar *new_encoding)
{
if (! DOC_IDX_VALID(idx) || new_encoding == NULL ||

93
src/document.h
View File

@ -21,6 +21,12 @@
* $Id$
*/
/**
* @file document.h
* Document related actions: new, save, open, etc.
* Also Scintilla search actions.
**/
#ifndef GEANY_DOCUMENT_H
#define GEANY_DOCUMENT_H 1
@ -36,72 +42,105 @@ typedef struct FileEncoding
} FileEncoding;
/* Structure for representing an open tab with all its related stuff. */
/**
* Structure for representing an open tab with all its properties.
**/
typedef struct document
{
/** General flag to represent this document is active and all properties are set correctly. */
gboolean is_valid;
/** Whether this %document support source code symbols(tags) to show in the sidebar. */
gboolean has_tags;
// the filename is encoded in UTF-8, but every GLibC function expect the locale representation
/** The UTF-8 encoded file name. Be careful glibc and GLib functions expect the locale
representation of the file name which can be different from this.
For conversion into locale encoding for use with file functions of GLib, you can use
@ref utils_get_locale_from_utf8. */
gchar *file_name;
/** The encoding of the %document, must be a valid string representation of an encoding, can
* be retrieved with @ref encodings_get_charset_from_index. */
gchar *encoding;
/** Internally used flag to indicate whether the file of this %document has a byte-order-mark. */
gboolean has_bom;
/** The filetype for this %document, it's only a reference to one of the elements of the global
* filetypes array. */
filetype *file_type;
/** TMWorkObject object for this %document. */
TMWorkObject *tm_file;
/** The Scintilla object for this %document. */
ScintillaObject *sci;
/** GtkLabel shown in the notebook header. */
GtkWidget *tab_label;
/** GtkLabel shown in the notebook right-click menu. */
GtkWidget *tabmenu_label;
/** GtkTreeView object for this %document within the Open Files treeview of the sidebar. */
GtkWidget *tag_tree;
/** GtkTreeStore object for this %document within the Open Files treeview of the sidebar. */
GtkTreeStore *tag_store;
GtkTreeIter iter; // open files item for this document
/** Iter for this %document within the Open Files treeview of the sidebar. */
GtkTreeIter iter;
/** Whether this %document is read-only. */
gboolean readonly;
/** Whether this %document has been changed since it was last saved. */
gboolean changed;
/** %Document-specific line wrapping setting. */
gboolean line_wrapping;
/** %Document-specific indentation setting. */
gboolean auto_indent;
gfloat scroll_percent; // % to scroll view by on paint, if positive.
time_t last_check; // to remember the last disk check
/** Percentage to scroll view by on paint, if positive. */
gfloat scroll_percent;
/** Time of the last disk check. */
time_t last_check;
/** Modification time of this %document on disk. */
time_t mtime;
/** Internally used by the Undo/Redo management code. */
GTrashStack *undo_actions;
/** Internally used by the Undo/Redo management code. */
GTrashStack *redo_actions;
/** Internally used. */
FileEncoding saved_encoding;
/** %Document-specific tab setting. */
gboolean use_tabs;
} document;
/* dynamic array of document elements to hold all information of the notebook tabs */
// Dynamic array of document elements to hold all information of the notebook tabs.
extern GArray *doc_array;
/* doc_list wraps doc_array so it can be used with C array syntax.
* Example: doc_list[0].sci = NULL; */
/**
* doc_list wraps doc_array so it can be used with C array syntax.
* Example: doc_list[0].sci = NULL;
**/
#define doc_list ((document *)doc_array->data)
#define DOC_IDX_VALID(idx) \
((idx) >= 0 && (guint)(idx) < doc_array->len && doc_list[idx].is_valid)
/**
* DOC_IDX_VALID checks whether the passed index points to a valid %document object by checking
* important properties. It returns FALSE if the index is not valid and then this index
* must not be used.
**/
#define DOC_IDX_VALID(doc_idx) \
((doc_idx) >= 0 && (guint)(doc_idx) < doc_array->len && doc_list[doc_idx].is_valid)
/**
* DOC_FILENAME) returns the filename of the %document corresponding to the passed index or
* GEANY_STRING_UNTITLED (e.g. _("untitled")) if the %document's filename was not yet set.
* This macro never returns NULL.
**/
#define DOC_FILENAME(doc_idx) \
((doc_list[doc_idx].file_name != NULL) ? \
(doc_list[doc_idx].file_name) : GEANY_STRING_UNTITLED)
((doc_list[doc_idx].file_name != NULL) ? (doc_list[doc_idx].file_name) : GEANY_STRING_UNTITLED)
/* returns the document index which has the given filename.
* is_tm_filename is needed when passing TagManager filenames because they are
* dereferenced, and would not match the link filename. */
gint document_find_by_filename(const gchar *filename, gboolean is_tm_filename);
/* returns the document index which has sci */
gint document_find_by_sci(ScintillaObject *sci);
/* returns the index of the notebook page from the document index */
gint document_get_notebook_page(gint doc_idx);
/* returns the index of the given notebook page in the document list */
gint document_get_n_idx(guint page_num);
/* returns the index of the current notebook page in the document list */
gint document_get_cur_idx();
/* returns NULL if no documents are open */
document *document_get_current();
@ -113,33 +152,25 @@ void document_finalize();
void document_set_text_changed(gint idx);
// Apply just the prefs that can change in the Preferences dialog
void document_apply_update_prefs(gint idx);
/* removes the given notebook tab and clears the related entry in the document list */
gboolean document_remove(guint page_num);
/* See document.c. */
gint document_new_file(const gchar *filename, filetype *ft, const gchar *text);
gint document_clone(gint old_idx, const gchar *utf8_filename);
/* See document.c. */
gint document_open_file(const gchar *locale_filename, gboolean readonly,
filetype *ft, const gchar *forced_enc);
gint document_open_file_full(gint idx, const gchar *filename, gint pos, gboolean readonly,
filetype *ft, const gchar *forced_enc);
/* Takes a new line separated list of filename URIs and opens each file.
* length is the length of the string or -1 if it should be detected */
void document_open_file_list(const gchar *data, gssize length);
/* Takes a linked list of filename URIs and opens each file, ensuring the newly opened
* documents and existing documents (if necessary) are only colourised once. */
void document_open_files(const GSList *filenames, gboolean readonly, filetype *ft,
const gchar *forced_enc);
@ -147,16 +178,11 @@ void document_open_files(const GSList *filenames, gboolean readonly, filetype *f
gboolean document_reload_file(gint idx, const gchar *forced_enc);
/* This saves the file.
* When force is set then it is always saved, even if it is unchanged(useful when using Save As)
* It returns whether the file could be saved or not. */
gboolean document_save_file(gint idx, gboolean force);
gboolean document_search_bar_find(gint idx, const gchar *text, gint flags, gboolean inc);
/* General search function, used from the find dialog.
* Returns -1 on failure or the start position of the matching text. */
gint document_find_text(gint idx, const gchar *text, gint flags, gboolean search_backwards,
gboolean scroll, GtkWidget *parent);
@ -173,7 +199,6 @@ void document_set_font(gint idx, const gchar *font_name, gint size);
void document_update_tag_list(gint idx, gboolean update);
/* sets the filetype of the document (sets syntax highlighting and tagging) */
void document_set_filetype(gint idx, filetype *type);
gchar *document_get_eol_mode(gint idx);

57
src/encodings.c
View File

@ -178,18 +178,17 @@ const GeanyEncoding *encodings_get_from_index(gint idx)
}
/*
* gtk_status_icon_get_stock:
* @idx: #GeanyEncodingIndex to retrieve the corresponding character set
/**
* Gets the character set name of the specified index e.g. for use with
* @ref document_set_encoding().
*
* Gets the character set name of the specified index e.g. for use with
* document_set_encoding.
* @param idx @ref GeanyEncodingIndex to retrieve the corresponding character set.
*
* Return value: charset according to idx,
* or %NULL if the index is invalid.
*
* Since: 0.13
*/
* @return The charset according to idx, or @c NULL if the index is invalid.
*
* @since 0.13
**/
const gchar* encodings_get_charset_from_index(gint idx)
{
g_return_val_if_fail(idx >= 0 && idx < GEANY_ENCODINGS_MAX, NULL);
@ -406,19 +405,18 @@ void encodings_init(void)
}
/*
* encodings_convert_to_utf8_from_charset:
* @buffer: the input string to convert
* @size: the length of the string, or -1 if the string is nul-terminated
* @charset: the charset to be used for conversion
* @fast: TRUE to only convert the input and skip extended checks on the converted string
/**
* Tries to convert @a buffer into UTF-8 encoding from the encoding specified with @a charset.
* If @a fast is not set, additional checks to validate the converted string are performed.
*
* Tries to convert @buffer into UTF-8 encoding from the encoding specified with @charset.
* If @fast is not set, additional checks to validate the converted string are performed.
* @param buffer The input string to convert.
* @param size The length of the string, or -1 if the string is nul-terminated.
* @param charset The charset to be used for conversion.
* @param fast @c TRUE to only convert the input and skip extended checks on the converted string.
*
* Return value: If the conversion was successful, a newly allocated nul-terminated string,
* which must be freed with g_free(). Otherwise %NULL.
*/
* @return If the conversion was successful, a newly allocated nul-terminated string,
* which must be freed with g_free(). Otherwise @c NULL.
**/
gchar *encodings_convert_to_utf8_from_charset(const gchar *buffer, gsize size,
const gchar *charset, gboolean fast)
{
@ -462,18 +460,17 @@ gchar *encodings_convert_to_utf8_from_charset(const gchar *buffer, gsize size,
}
/*
* encodings_convert_to_utf8:
* @buffer: the input string to convert
* @size: the length of the string, or -1 if the string is nul-terminated.
* @used_encoding: return location of the detected encoding of the input string, or %NULL
/**
* Tries to convert @a buffer into UTF-8 encoding and store the detected original encoding in
* @a used_encoding.
*
* Tries to convert @buffer into UTF-8 encoding and store the detected original encoding in
* @used_encoding.
* @param buffer the input string to convert.
* @param size the length of the string, or -1 if the string is nul-terminated.
* @param used_encoding return location of the detected encoding of the input string, or @c NULL.
*
* Return value: If the conversion was successful, a newly allocated nul-terminated string,
* which must be freed with g_free(). Otherwise %NULL.
*/
* @return If the conversion was successful, a newly allocated nul-terminated string,
* which must be freed with g_free(). Otherwise @c NULL.
**/
gchar *encodings_convert_to_utf8(const gchar *buffer, gsize size, gchar **used_encoding)
{
gchar *locale_charset = NULL;

16
src/encodings.h
View File

@ -22,6 +22,11 @@
*/
/**
* @file encodings.h
* Encoding conversion and Byte Order Mark (BOM) handling.
**/
/*
* Modified by the gedit Team, 2002. See the gedit AUTHORS file for a
* list of people on the gedit Team.
@ -47,12 +52,19 @@ typedef enum
GEANY_ENCODING_GROUPS_MAX
} GeanyEncodingGroup;
/** Structure to represent an encoding to be used in Geany. */
typedef struct
{
/** The index of the encoding, must be one of GeanyEncodingIndex. */
gint idx;
/** Internally used member for grouping */
gint order;
/** Internally used member for grouping */
GeanyEncodingGroup group;
/** String representation of the encoding, e.g. "ISO-8859-3" */
gchar *charset;
/** Translatable and descriptive name of the encoding, e.g. "South European" */
gchar *name;
} GeanyEncoding;
@ -85,6 +97,10 @@ gboolean encodings_is_unicode_charset(const gchar *string);
* Copyright (C) 2002 Red Hat, Inc.
*/
/**
* @enum GeanyEncodingIndex
* List of known and supported encodings.
**/
typedef enum
{
GEANY_ENCODING_ISO_8859_1,

75
src/plugindata.h
View File

@ -25,70 +25,13 @@
#ifndef PLUGIN_H
#define PLUGIN_H
/**
* Public symbols supported:
*
* version_check()
* Use VERSION_CHECK() macro instead. Required by Geany.
*
* PluginInfo* info()
* Use PLUGIN_INFO() macro to define it. Required by Geany.
*
* GeanyData* geany_data
* Geany owned fields and functions.
*
* PluginFields* plugin_fields
* Plugin owned fields, including flags.
*
* GeanyCallback geany_callbacks[]
* An array for connecting GeanyObject events, which should be terminated with
* {NULL, NULL, FALSE, NULL}. See signals below.
*
* void configure(GtkWidget *parent)
* Called when the plugin should show a configure dialog to let the user set some basic
* plugin configuration. Optionally, can be omitted when not needed.
*
* void init(GeanyData *data)
* Called after loading the plugin. data is the same as geany_data.
*
* void cleanup()
* Called before unloading the plugin. Required for normal plugins - it should undo
* everything done in init() - e.g. destroy menu items, free memory.
*/
/**
* Signals:
*
* "document-new"
* Sent when a new document is created.
* Handler: void user_function(GObject *obj, gint idx, gpointer user_data);
*
* "document-open"
* Sent when a file is opened.
* Handler: void user_function(GObject *obj, gint idx, gpointer user_data);
*
* "document-save"
* Sent when a file is saved.
* Handler: void user_function(GObject *obj, gint idx, gpointer user_data);
*
* "document-activate"
* Sent when switching notebook pages.
* Handler: void user_function(GObject *obj, gint idx, gpointer user_data);
*
* "project-open"
* Sent after a project is opened but before session files are loaded.
* Handler: void user_function(GObject *obj, GKeyFile *config, gpointer user_data);
*
* "project-save"
* Sent when a project is saved(happens when the project is created, the properties
* dialog is closed or Geany is exited). This signal is emitted shortly before Geany
* will write the contents of the GKeyFile to the disc.
* Handler: void user_function(GObject *obj, GKeyFile *config, gpointer user_data);
*
* "project-close"
* Sent after a project is closed.
* Handler: void user_function(GObject *obj, gpointer user_data);
*/
* @file plugindata.h
* This file defines the plugin API, the interface between Geany and its plugins.
* For detailed documentation of the plugin system please read the plugin
* API documentation.
**/
/* The API version should be incremented whenever any plugin data types below are
@ -142,17 +85,23 @@ PluginInfo;
}
/* For geany_callbacks array - see top of file. */
/** callback array entry */
typedef struct GeanyCallback
{
/** The name of signal, must be an existing signal. For a list of available signals,
* please see the @link signals Signal documentation @endlink. */
gchar *signal_name;
/** A callback function which is called when the signal is emitted. */
GCallback callback;
/** Set to TRUE to connect your handler with g_signal_connect_after(). */
gboolean after;
/** The user data passed to the signal handler. */
gpointer user_data;
}
GeanyCallback;
typedef enum
{
PLUGIN_IS_DOCUMENT_SENSITIVE = 1 << 0 // if menu_item should be disabled when there are no documents

159
src/utils.c
View File

@ -223,6 +223,17 @@ gboolean utils_goto_line(gint idx, gint line)
}
/**
* Write the given @c text into a file with @c filename.
* If the file doesn't exist, it will be created.
* If it already exists, it will be overwritten.
*
* @param filename The filename of the file to write, in locale encoding.
* @param text The text to write into the file.
*
* @return 0 if the directory was successfully created, otherwise the @c errno of the
* failed operation is returned.
**/
gint utils_write_file(const gchar *filename, const gchar *text)
{
FILE *fp;
@ -639,12 +650,18 @@ gdouble utils_scale_round (gdouble val, gdouble factor)
}
/* (taken from libexo from os-cillation)
* NULL-safe string comparison. Returns TRUE if both a and b are
* NULL or if a and b refer to valid strings which are equal.
*/
/**
* @a NULL-safe string comparison. Returns @a TRUE if both @c a and @c b are @a NULL
* or if @c a and @c b refer to valid strings which are equal.
*
* @param a Pointer to first string or @a NULL.
* @param b Pointer to first string or @a NULL.
*
* @return @a TRUE if @c a equals @c b, else @a FALSE.
**/
gboolean utils_str_equal(const gchar *a, const gchar *b)
{
/* (taken from libexo from os-cillation) */
if (a == NULL && b == NULL) return TRUE;
else if (a == NULL || b == NULL) return FALSE;
@ -656,8 +673,13 @@ gboolean utils_str_equal(const gchar *a, const gchar *b)
}
/* removes the extension from filename and return the result in
* a newly allocated string */
/**
* Remove the extension from @c filename and return the result in a newly allocated string.
*
* @param filename The filename to operate on.
*
* @return A newly-allocated string, should be freed when no longer needed.
**/
gchar *utils_remove_ext_from_filename(const gchar *filename)
{
gchar *last_dot = strrchr(filename, '.');
@ -938,8 +960,20 @@ gchar *utils_get_initials(gchar *name)
}
/* Wrapper functions for Key-File-Parser from GLib in keyfile.c to reduce code size */
gint utils_get_setting_integer(GKeyFile *config, const gchar *section, const gchar *key, const gint default_value)
/**
* Convenience function for g_key_file_get_integer() to add a default value argument.
*
* @param config A GKeyFile object.
* @param section The group name to look in for the key.
* @param key The key to find.
* @param default_value The default value which will be returned when @c section or @c key
* don't exist.
*
* @return The value associated with c key as an integer, or the given default value if the value
* could not be retrieved.
**/
gint utils_get_setting_integer(GKeyFile *config, const gchar *section, const gchar *key,
const gint default_value)
{
gint tmp;
GError *error = NULL;
@ -956,7 +990,20 @@ gint utils_get_setting_integer(GKeyFile *config, const gchar *section, const gch
}
gboolean utils_get_setting_boolean(GKeyFile *config, const gchar *section, const gchar *key, const gboolean default_value)
/**
* Convenience function for g_key_file_get_boolean() to add a default value argument.
*
* @param config A GKeyFile object.
* @param section The group name to look in for the key.
* @param key The key to find.
* @param default_value The default value which will be returned when @c section or @c key
* don't exist.
*
* @return The value associated with c key as a boolean, or the given default value if the value
* could not be retrieved.
**/
gboolean utils_get_setting_boolean(GKeyFile *config, const gchar *section, const gchar *key,
const gboolean default_value)
{
gboolean tmp;
GError *error = NULL;
@ -973,7 +1020,20 @@ gboolean utils_get_setting_boolean(GKeyFile *config, const gchar *section, const
}
gchar *utils_get_setting_string(GKeyFile *config, const gchar *section, const gchar *key, const gchar *default_value)
/**
* Convenience function for g_key_file_get_string() to add a default value argument.
*
* @param config A GKeyFile object.
* @param section The group name to look in for the key.
* @param key The key to find.
* @param default_value The default value which will be returned when @c section or @c key
* don't exist.
*
* @return A newly allocated string, or the given default value if the value could not be
* retrieved.
**/
gchar *utils_get_setting_string(GKeyFile *config, const gchar *section, const gchar *key,
const gchar *default_value)
{
gchar *tmp;
GError *error = NULL;
@ -1086,8 +1146,8 @@ void utils_beep()
/* taken from busybox, thanks */
gchar *utils_make_human_readable_str(unsigned long long size, unsigned long block_size,
unsigned long display_unit)
gchar *utils_make_human_readable_str(unsigned long long size, gulong block_size,
gulong display_unit)
{
/* The code will adjust for additional (appended) units. */
static const gchar zero_and_units[] = { '0', 0, 'K', 'M', 'G', 'T' };
@ -1179,7 +1239,7 @@ gint utils_strtod(const gchar *source, gchar **end, gboolean with_route)
}
// Returns: new string with the current time formatted HH:MM:SS.
// Returns: newly allocated string with the current time formatted HH:MM:SS.
gchar *utils_get_current_time_string()
{
const time_t tp = time(NULL);
@ -1402,7 +1462,15 @@ gboolean utils_wrap_string(gchar *string, gint wrapstart)
}
/* Null-safe with fallback encoding conversion. */
/**
* Converts the given UTF-8 encoded string into locale encoding.
* On Windows platforms, it does nothing and instead it just returns a copy of the input string.
*
* @param utf8_text UTF-8 encoded text.
*
* @return The converted string in locale encoding, or a copy of the input string if conversion
* failed. Should be freed with g_free(). If @a utf8_text is @c NULL, @c NULL is returned.
**/
gchar *utils_get_locale_from_utf8(const gchar *utf8_text)
{
#ifdef G_OS_WIN32
@ -1422,7 +1490,15 @@ gchar *utils_get_locale_from_utf8(const gchar *utf8_text)
}
/* Null-safe with fallback encoding conversion. */
/**
* Converts the given string (in locale encoding) into UTF-8 encoding.
* On Windows platforms, it does nothing and instead it just returns a copy of the input string.
*
* @param locale_text Text in locale encoding.
*
* @return The converted string in UTF-8 encoding, or a copy of the input string if conversion
* failed. Should be freed with g_free(). If @a locale_text is @c NULL, @c NULL is returned.
**/
gchar *utils_get_utf8_from_locale(const gchar *locale_text)
{
#ifdef G_OS_WIN32
@ -1575,6 +1651,16 @@ g_mkdir_with_parents (const gchar *pathname,
#endif
/**
* Create a directory if it doesn't already exist.
* Create intermediate parent directories as needed, too.
*
* @param path The path of the directory to create, in locale encoding.
* @param create_parent_dirs Whether to create intermediate parent directories if necessary.
*
* @return 0 if the directory was successfully created, otherwise the @c errno of the
* failed operation is returned.
**/
gint utils_mkdir(const gchar *path, gboolean create_parent_dirs)
{
gint mode = 0700;
@ -1590,12 +1676,19 @@ gint utils_mkdir(const gchar *path, gboolean create_parent_dirs)
}
/* Gets a sorted list of files from the specified directory.
* Locale encoding is expected for path and used for the file list.
* The list and the data in the list should be freed after use.
* Returns: The list or NULL if no files found.
* length will point to the number of non-NULL data items in the list, unless NULL.
* error is the location for storing a possible error, or NULL. */
/**
* Gets a sorted list of files from the specified directory.
* Locale encoding is expected for path and used for the file list. The list and the data
* in the list should be freed after use.
*
* @param path The path of the directory to scan, in locale encoding.
* @param length The location to store the number of non-@a NULL data items in the list,
* unless @a NULL.
* @param error The is the location for storing a possible error, or @a NULL.
*
* @return A newly allocated list or @a NULL if no files found. The list and its data should be
* freed when no longer needed.
**/
GSList *utils_get_file_list(const gchar *path, guint *length, GError **error)
{
GSList *list = NULL;
@ -1648,10 +1741,18 @@ gboolean utils_str_has_upper(const gchar *str)
}
/* Replaces all occurrences of needle in str with replace.
* Currently this is not safe if replace matches needle.
* Returns: TRUE if needle was found. */
gboolean utils_string_replace_all(GString *str, const gchar *needle, const gchar *replace)
/**
* Replaces all occurrences of @c needle in @c haystack with @c replace.
* Currently this is not safe if @c replace matches @c needle, so @c needle and @c replace
* must not be equal.
*
* @param haystack The input string to operate on. This string is modified in place.
* @param needle The string which should be replaced.
* @param replace The replacement for @c needle.
*
* @return @a TRUE if @c needle was found, else @a FALSE.
**/
gboolean utils_string_replace_all(GString *haystack, const gchar *needle, const gchar *replace)
{
const gchar *c;
gssize pos = -1;
@ -1661,15 +1762,15 @@ gboolean utils_string_replace_all(GString *str, const gchar *needle, const gchar
while (1)
{
c = strstr(str->str, needle);
c = strstr(haystack->str, needle);
if (c == NULL)
break;
else
{
pos = c - str->str;
g_string_erase(str, pos, strlen(needle));
pos = c - haystack->str;
g_string_erase(haystack, pos, strlen(needle));
if (replace)
g_string_insert(str, pos, replace);
g_string_insert(haystack, pos, replace);
}
}
return (pos != -1);

54
src/utils.h
View File

@ -21,18 +21,24 @@
* $Id$
*/
/**
* @file: utils.h
* General utility functions, non-GTK related.
*/
#ifndef GEANY_UTILS_H
#define GEANY_UTILS_H 1
// Returns: TRUE if ptr points to a non-zero value.
/** Returns: TRUE if @a ptr points to a non-zero value. */
#define NZV(ptr) \
((ptr) && (ptr)[0])
/* Free's ptr (if not NULL), then assigns result to it.
* result can be an expression using the 'old' value of ptr.
* It prevents a memory leak compared with: ptr = func(ptr); */
#define setptr(ptr, result)\
/**
* Free's @a ptr (if not @c NULL), then assigns @a result to it.
* @a result can be an expression using the 'old' value of @a ptr.
* It prevents a memory leak compared with: @code ptr = func(ptr); @endcode
**/
#define setptr(ptr, result) \
{\
gpointer setptr_tmp = ptr;\
ptr = result;\
@ -42,7 +48,6 @@
void utils_start_browser(const gchar *uri);
/* taken from anjuta, to determine the EOL mode of the file */
gint utils_get_line_endings(gchar* buffer, glong size);
gboolean utils_isbrace(gchar c, gboolean include_angles);
@ -59,13 +64,10 @@ gchar *utils_find_open_xml_tag(const gchar sel[], gint size, gboolean check_tag)
gboolean utils_check_disk_status(gint idx, gboolean force);
//gchar *utils_get_current_tag(gint idx, gint direction);
gint utils_get_current_function(gint idx, const gchar **tagname);
/* returns the end-of-line character(s) length of the specified editor */
gint utils_get_eol_char_len(gint idx);
/* returns the end-of-line character(s) of the specified editor */
const gchar *utils_get_eol_char(gint idx);
gboolean utils_atob(const gchar *str);
@ -74,31 +76,22 @@ gboolean utils_is_absolute_path(const gchar *path);
gdouble utils_scale_round(gdouble val, gdouble factor);
/* (taken from libexo from os-cillation)
* NULL-safe string comparison. Returns TRUE if both a and b are
* NULL or if a and b refer to valid strings which are equal.
*/
gboolean utils_str_equal(const gchar *a, const gchar *b);
/* removes the extension from filename and return the result in
* a newly allocated string */
gchar *utils_remove_ext_from_filename(const gchar *filename);
gchar utils_brace_opposite(gchar ch);
gchar *utils_get_hostname();
gint utils_make_settings_dir();
gboolean utils_string_replace_all(GString *str, const gchar *needle, const gchar *replace);
gchar *utils_str_replace(gchar *haystack, const gchar *needle, const gchar *replacement);
gint utils_strpos(const gchar* haystack, const gchar * needle);
gchar *utils_get_date_time(const gchar *format, time_t *time_to_use);
gchar *utils_get_initials(gchar *name);
@ -121,15 +114,11 @@ gchar *utils_get_current_file_dir_utf8();
void utils_beep();
gchar *utils_make_human_readable_str(unsigned long long size, unsigned long block_size,
unsigned long display_unit);
gchar *utils_make_human_readable_str(unsigned long long size, gulong block_size,
gulong display_unit);
/* utils_strtod() converts a string containing a hex colour ("0x00ff00") into an integer.
* Basically, it is the same as strtod() would do, but it does not understand hex colour values,
* before ANSI-C99. With with_route set, it takes strings of the format "#00ff00". */
gint utils_strtod(const gchar *source, gchar **end, gboolean with_route);
// returned string must be freed.
gchar *utils_get_current_time_string();
GIOChannel *utils_set_up_io_channel(gint fd, GIOCondition cond, gboolean nblock,
@ -137,37 +126,20 @@ GIOChannel *utils_set_up_io_channel(gint fd, GIOCondition cond, gboolean nblock,
gchar **utils_read_file_in_array(const gchar *filename);
/* Contributed by Stefan Oltmanns, thanks.
* Replaces \\, \r, \n, \t and \uXXX by their real counterparts */
gboolean utils_str_replace_escape(gchar *string);
/* Wraps a string in place, replacing a space with a newline character.
* wrapstart is the minimum position to start wrapping or -1 for default */
gboolean utils_wrap_string(gchar *string, gint wrapstart);
/* Simple wrapper for g_locale_from_utf8; returns a copy of utf8_text on failure. */
gchar *utils_get_locale_from_utf8(const gchar *utf8_text);
/* Simple wrapper for g_locale_to_utf8; returns a copy of locale_text on failure. */
gchar *utils_get_utf8_from_locale(const gchar *locale_text);
/* Frees all passed pointers if they are *ALL* non-NULL.
* Do not use if any pointers may be NULL.
* The first argument is nothing special, it will also be freed.
* The list must be ended with NULL. */
void utils_free_pointers(gpointer first, ...) G_GNUC_NULL_TERMINATED;
/* Creates a string array deep copy of a series of non-NULL strings.
* The first argument is nothing special.
* The list must be ended with NULL.
* If first is NULL, NULL is returned. */
gchar **utils_strv_new(gchar *first, ...) G_GNUC_NULL_TERMINATED;
gint utils_mkdir(const gchar *path, gboolean create_parent_dirs);
/* Gets a sorted list of files in the specified directory. */
GSList *utils_get_file_list(const gchar *path, guint *length, GError **error);
gboolean utils_str_has_upper(const gchar *str);