[maemo-commits] [maemo-commits] r14508 - in projects/haf/branches/hildon-help/gtk-doc: reference src
From: subversion at stage.maemo.org subversion at stage.maemo.orgDate: Thu Oct 18 18:11:17 EEST 2007
- Previous message: [maemo-commits] r14507 - projects/haf/tags
- Next message: [maemo-commits] r14509 - in projects/haf/tags: . gail
- Messages sorted by: [ date ] [ thread ] [ subject ] [ author ]
Author: schulhof
Date: 2007-10-18 18:11:15 +0300 (Thu, 18 Oct 2007)
New Revision: 14508
Modified:
projects/haf/branches/hildon-help/gtk-doc/reference/hildon-help-docs.sgml
projects/haf/branches/hildon-help/gtk-doc/reference/hildon-help-sections.txt
projects/haf/branches/hildon-help/gtk-doc/src/browser.c
projects/haf/branches/hildon-help/gtk-doc/src/contents.c
projects/haf/branches/hildon-help/gtk-doc/src/context.c
projects/haf/branches/hildon-help/gtk-doc/src/filter.c
projects/haf/branches/hildon-help/gtk-doc/src/hildon-help-private.h
projects/haf/branches/hildon-help/gtk-doc/src/hildon-help.h
projects/haf/branches/hildon-help/gtk-doc/src/osso-helplib.c
Log:
Cleaned up help topics.
Modified: projects/haf/branches/hildon-help/gtk-doc/reference/hildon-help-docs.sgml
===================================================================
--- projects/haf/branches/hildon-help/gtk-doc/reference/hildon-help-docs.sgml 2007-10-18 14:55:52 UTC (rev 14507)
+++ projects/haf/branches/hildon-help/gtk-doc/reference/hildon-help-docs.sgml 2007-10-18 15:11:15 UTC (rev 14508)
@@ -9,7 +9,6 @@
<chapter>
<title>hildon-help</title>
<xi:include href="xml/hildon-help-private.xml"/>
- <xi:include href="xml/internal.xml"/>
<xi:include href="xml/hildon-help.xml"/>
</chapter>
</book>
Modified: projects/haf/branches/hildon-help/gtk-doc/reference/hildon-help-sections.txt
===================================================================
--- projects/haf/branches/hildon-help/gtk-doc/reference/hildon-help-sections.txt 2007-10-18 14:55:52 UTC (rev 14507)
+++ projects/haf/branches/hildon-help/gtk-doc/reference/hildon-help-sections.txt 2007-10-18 15:11:15 UTC (rev 14508)
@@ -46,30 +46,6 @@
</SECTION>
<SECTION>
-<FILE>internal</FILE>
-fexists
-helplib_str_close
-helplib_str_title
-ossohelp_file2
-s_OssoHelpWalker
-contents
-filter
-title_from_key
-context
-graphic_tag
-filter_outf
-dialog_mode
-loc_getattr_count
-loc_getattr
-filter_characters_cb
-filter_startElement_cb
-filter_endElement_cb
-init_filter_html
-key_from_triplet
-system_dialog
-</SECTION>
-
-<SECTION>
<FILE>hildon-help</FILE>
hildon_help_show
hildon_help_dialog_help_enable
Modified: projects/haf/branches/hildon-help/gtk-doc/src/browser.c
===================================================================
--- projects/haf/branches/hildon-help/gtk-doc/src/browser.c 2007-10-18 14:55:52 UTC (rev 14507)
+++ projects/haf/branches/hildon-help/gtk-doc/src/browser.c 2007-10-18 15:11:15 UTC (rev 14508)
@@ -38,7 +38,7 @@
/*--===Function===-*/
-/**
+/*
Request for URL
@param html Lightweight HTML renderer/editor
@@ -77,7 +77,7 @@
return;
}
-/**
+/*
Go to URL
@param html Lightweight HTML renderer/editor
@@ -104,7 +104,7 @@
/*---===( Public functions )===---*/
-/**
+/*
Create a new GTK widget for the browser, and return it.
@param osso Application's OSSO handle
@@ -128,7 +128,7 @@
}
-/**
+/*
Cleanup of browser widget & engine.
@note This might be a simple Widget killing, but there may be
@@ -143,7 +143,7 @@
}
-/**
+/*
Change the shown HTML in the browser widget.
@param browser Widget from 'browser_new()'
@@ -207,7 +207,7 @@
}
-/**
+/*
Setting browser window's zoom level
@param level normal=100, 50=small, 150=large
@@ -220,7 +220,7 @@
return TRUE;
}
-/**
+/*
Asking GtkHTML to find (and highlight) a text
within the current HTML view.
@@ -253,7 +253,7 @@
}
-/**
+
Find out if text is selected in the browser socket.
@param browser returned by 'browser_new()'
@@ -281,7 +281,7 @@
}
-/**
+/*
Browser clipboard copy
@param browser returned by 'browser_new()'
@@ -296,7 +296,8 @@
}
-/**Moved this function from dialog.c to here
+/*
+ Moved this function from dialog.c to here
Renamed it from update_html() to libosso_update_html()
Converts a given help topic to HTML and feeds that to the browser.
@@ -333,7 +334,7 @@
}
-/**
+/*
Moves the focused link in the browser widget
@@ -385,7 +386,7 @@
}
-/**
+/*
Tells if the browser has the focus within its toplevel window
@return True if the browser has the focus
*/
Modified: projects/haf/branches/hildon-help/gtk-doc/src/contents.c
===================================================================
--- projects/haf/branches/hildon-help/gtk-doc/src/contents.c 2007-10-18 14:55:52 UTC (rev 14507)
+++ projects/haf/branches/hildon-help/gtk-doc/src/contents.c 2007-10-18 15:11:15 UTC (rev 14508)
@@ -40,7 +40,7 @@
/*---=== XML system ===---*/
-/**
+/*
Advance 'sub_branch' to next level, and return the 'f_count'
for this one.
@@ -101,7 +101,7 @@
};
static struct s_mydata d;
-/**
+/*
'startElement' XML callback
<p>
We're only curious about the <folder> and <topic> tags,
@@ -193,7 +193,7 @@
}
}
-/**
+/*
'endElement' XML callback
@param data ignored
@@ -248,7 +248,7 @@
}
}
-/**
+/*
'characters' XML callback
@param data ignored
@@ -276,7 +276,7 @@
}
}
-/**
+/*
'entity' XML callback
<p>
Handles '<', '>', ''', '"' and '&'
@@ -319,7 +319,7 @@
NULL, /*fatalError_cb*/
};
-/**
+/*
Check through a certain XML file's contents, listing how many
folders and/or topics exist on a certain sublevel.
@@ -359,7 +359,7 @@
/*---=== Big functions ===---*/
-/**
+/*
Try if a similar filename (with different suffix) exists.
@param path path
@@ -389,7 +389,7 @@
return g_file_test( buf, G_FILE_TEST_EXISTS );
}
-/**
+/*
Find the next topic/folder item in a list of contents
for a particular level.
@@ -537,7 +537,7 @@
}
-/**
+/*
HTML output of topic 'key' to 'outf'.
@param outf file to write to
@@ -589,7 +589,7 @@
return TRUE;
}
-/**
+/*
Find plain text title for folder or topic 'key_or_triplet'.
@param key_or_triplet Either contextUID triplet ("xxx_fname_zzz")
Modified: projects/haf/branches/hildon-help/gtk-doc/src/context.c
===================================================================
--- projects/haf/branches/hildon-help/gtk-doc/src/context.c 2007-10-18 14:55:52 UTC (rev 14507)
+++ projects/haf/branches/hildon-help/gtk-doc/src/context.c 2007-10-18 15:11:15 UTC (rev 14508)
@@ -126,7 +126,7 @@
};
-/**
+/*
Find the help key ("//fname/[../]nnn") for a certain triplet
("xxx_fname_zzz").
Modified: projects/haf/branches/hildon-help/gtk-doc/src/filter.c
===================================================================
--- projects/haf/branches/hildon-help/gtk-doc/src/filter.c 2007-10-18 14:55:52 UTC (rev 14507)
+++ projects/haf/branches/hildon-help/gtk-doc/src/filter.c 2007-10-18 15:11:15 UTC (rev 14508)
@@ -228,7 +228,7 @@
/*--- Filter help routines ---*/
-/**
+/*
Return number of XML attributes
@param attrs array of name/value -pairs, NULL terminated
@@ -244,7 +244,7 @@
return n;
}
-/**
+/*
Provide a particular attribute's value (by name)
@param attrs array of XML attribute name/value pairs,
@@ -271,7 +271,7 @@
/*--- Filter callbacks ---*/
-/**
+/*
'characters' XML callback (for filter mode)
@param data ignored
@@ -294,7 +294,7 @@
}
-/**
+/*
Tag start handling
@param name name of the tag
@@ -689,7 +689,7 @@
}
}
-/**
+/*
'startElement' XML callback
@param data ignored
@@ -725,7 +725,7 @@
}
-/**
+/*
Tag end handling
@param name tag name
@@ -903,7 +903,7 @@
return NULL; /* ignore any other endings */
}
-/**
+/*
'endElement' XML callback (for filter mode)
@param data ignored
@@ -932,7 +932,7 @@
}
}
-/**
+/*
Initialize the HTML output table, either from external file
(if exists) or from the built-in tables (same file, statically
#included at compilation).
@@ -972,7 +972,7 @@
*(html_keys[i].ref)= str;
}
-/**
+/*
Initialize the filter system
<p>
Checks if there is a 'htmltags.cfg' override of the compiled-in
Modified: projects/haf/branches/hildon-help/gtk-doc/src/hildon-help-private.h
===================================================================
--- projects/haf/branches/hildon-help/gtk-doc/src/hildon-help-private.h 2007-10-18 14:55:52 UTC (rev 14507)
+++ projects/haf/branches/hildon-help/gtk-doc/src/hildon-help-private.h 2007-10-18 15:11:15 UTC (rev 14508)
@@ -20,7 +20,7 @@
* 02110-1301 USA
*
*/
-/**
+/*
@file hildon-help-private.h
More services than 'hildon-help.h' offers. Also these are
@@ -168,7 +168,7 @@
#define strcat_safe_auto_max( buf, str, max ) strcat_safe_max( (buf), (str), sizeof(buf), (max) )
-/**
+/*
Listing help topics available on the system, globally or for a specific
branch (s.a. for a specific application) only.
Modified: projects/haf/branches/hildon-help/gtk-doc/src/hildon-help.h
===================================================================
--- projects/haf/branches/hildon-help/gtk-doc/src/hildon-help.h 2007-10-18 14:55:52 UTC (rev 14507)
+++ projects/haf/branches/hildon-help/gtk-doc/src/hildon-help.h 2007-10-18 15:11:15 UTC (rev 14508)
@@ -20,9 +20,13 @@
* 02110-1301 USA
*
*/
+
/**
- @file hildon-help.h
-*/
+ * SECTION:hildon-help
+ * @short_description: Hildon Help Functions
+ *
+ * Use these functions to invoke the help UI, or to add context-sensitive help to your %GtkDialog widgets.
+ */
#ifndef _HILDON_HELP_H_
#define _HILDON_HELP_H_
@@ -33,65 +37,56 @@
extern "C" {
#endif
-/*--- Public interface (for any applications) ---*/
-
enum {
HILDON_HELP_SHOW_DIALOG= 0x01,
HILDON_HELP_SHOW_JUSTASK= 0x02
};
/**
- Show Help topic or folder. This same function can be used either for
- Help dialogs (displaying a single topic _without links_ in the
- calling application's dialog box), or for launching Help Application,
- providing browsing, search and history functions, too.
- <p>
- Normally, applications would only use this to launch help topics, but
- it can be used for opening a folder view as well.
-
- @param osso OSSO context handle of the calling application, required
- for RPC/DBUS calls to HelpApp or Browser. Can be NULL for
- #OSSO_HELP_SHOW_JUSTASK.
-
- @param topic_id Help topic ID ("xxx_yyy_zzz")
-
- @param flags 0 for default (open Help Application)
- <br>+1 (#OSSOHELP_SHOW_DIALOG) for opening as system dialog,
- without navigation possibilities
- <br>+2 (#OSSOHELP_SHOW_JUSTASK) to check, whether a certain
- topic or folder is available on the system.
-
- @return #OSSO_OK All well, help found (and being displayed)
- <br>#OSSO_ERROR No help for such topic ID
- <br>#OSSO_RPC_ERROR Unable to contact HelpApp or Browser
- <br>#OSSO_INVALID Param not formally right (NULL, or bad ID
- format)
-*/
+ * hildon_help_show:
+ * @osso: OSSO context to use for RPC
+ * @topic_id: Help topic ID. This is a string of the form "foo_bar_baz"
+ * @flags: Whether to actually display the help topic
+ * (%HILDON_HELP_SHOW_DIALOG), or merely determine whether the
+ * topic is available (%HILDON_HELP_SHOW_JUSTASK)
+ *
+ * Show Help topic or folder. This same function can be used either for
+ * Help dialogs (displaying a single topic _without links_ in the
+ * calling application's dialog box), or for launching Help Application,
+ * providing browsing, search and history functions, too.
+ *
+ * Normally, applications would only use this to launch help topics, but
+ * it can be used for opening a folder view as well.
+ *
+ * Returns: %OSSO_OK All well, help found (and being displayed)
+ * %OSSO_ERROR No help for such topic ID
+ * %OSSO_RPC_ERROR Unable to contact HelpApp or Browser
+ * %OSSO_INVALID Incorrect parameters (NULL, or bad ID format)
+ */
osso_return_t hildon_help_show( osso_context_t *osso,
const gchar *topic_id,
guint flags );
/**
- Enable context specific help for a dialog.
- <p>
- Calling this function adds a '?' icon to the dialog's titlebar,
- allowing user to access the context specific help topic. All
- UI binding is done for you, one line is all it takes.
-
- @todo If the given help topic is not installed on the system,
- the '?' icon should be dimmed (insensitive); is there a
- way to do that?
-
- @note Do this call before 'gtk_widget_show_all()'; otherwise, the
- '?' icon won't show.
-
- @param dialog The GTK+ dialog to attach help to
- @param topic Help topic ID ("xxx_yyy_zzz") to show if the user
- presses the '?' icon
- @param osso OSSO context pointer of the calling application
-
- @return TRUE if the help topic existed, and '?' enabled
- <br>FALSE if the topic ID is not found in this system.
+ * hildon_help_dialog_help_enable:
+ * @dialog: %GtkDialog to enhance
+ * @topic: Help topic ID. This is a string of the form "foo_bar_baz"
+ * @osso: OSSO context to use for RPC
+ * Enable context specific help for a dialog.
+ *
+ * Calling this function adds a '?' icon to the dialog's titlebar,
+ * allowing user to access the context specific help topic. All
+ * UI binding is done for you, one line is all it takes.
+ *
+ * TODO: If the given help topic is not installed on the system,
+ * the '?' icon should be dimmed (insensitive); is there a
+ * way to do that?
+ *
+ * Note: Do this call before gtk_widget_show_all(). Otherwise, the
+ * '?' icon won't show up.
+ *
+ * Returns: %TRUE if the help topic exists, and '?' has been added,
+ * and %FALSE if the topic ID was not found on the system.
*/
gboolean hildon_help_dialog_help_enable( GtkDialog *dialog,
const gchar *topic,
Modified: projects/haf/branches/hildon-help/gtk-doc/src/osso-helplib.c
===================================================================
--- projects/haf/branches/hildon-help/gtk-doc/src/osso-helplib.c 2007-10-18 14:55:52 UTC (rev 14507)
+++ projects/haf/branches/hildon-help/gtk-doc/src/osso-helplib.c 2007-10-18 15:11:15 UTC (rev 14508)
@@ -141,7 +141,7 @@
}
-/**
+/*
* gtk_dialog_set_has_help:
* @dialog: The dialog for which help is to be enabled/disabled.
* @has_help: Whether the dialog is to have a "Help" button
@@ -178,7 +178,7 @@
static gboolean ossohelp_file2_private( const char *basename, int basename_len,
char *fn_buf, size_t fn_buflen, char *language ) ;
-/**
+/*
Returns the last character of a string, or '\0' if NULL/empty.
@param p text string (ASCII)
@@ -189,7 +189,7 @@
return (p && *p) ? (*(strchr(p,'\0') -1)) : '\0';
}
-/**
+/*
Safe string copying.
@param buf target buffer
@@ -211,7 +211,7 @@
return strncpy( buf, src, buflen-1 /*max charcount*/ );
}
-/**
+/*
Safe string concatenation. Like 'strcpy_safe_max()' but
concatenates to existing text in 'buf'.
@@ -274,7 +274,7 @@
/*---=== Local functions ===---*/
-/**
+/*
Return path to Help's XML material, some pictures and .css file
@return slash-terminated path (normally, "/usr/share/osso-help/")
@@ -288,7 +288,7 @@
return base;
}
-/**
+/*
Output BreadCrumb Trails HTML code
@param f file to output to
@@ -366,7 +366,7 @@
/*---=== Private API (for HelpUI, but not other apps) ===---*/
-/**
+/*
Returns the location of OSSO Help Sources (.xml/.gz files) in the system.
The value is based on 'OSSO_HELP_PATH' env.var. or "/usr/share/osso-help/"
(the default).
@@ -455,7 +455,7 @@
}
-/**
+/*
Returns the CSS2 stylesheet name to use for Help rendering.
@return base filename (normally "help-default.css")
@@ -471,7 +471,7 @@
return css;
}
-/**
+/*
Output help HTML, or BreadCrumb Trails.
Usage: 'f'==NULL only checks that a URL is valid (there is material for it).
@@ -538,7 +538,7 @@
}
-/**
+/*
Split the 'branch' to filename part (expanding it to real filename) and
'sub_branch' part ("a/[../][NN]"), returning that.
@@ -569,7 +569,7 @@
}
-/**
+/*
Provides the full filename to a help file, whose base part is known.
@param basename name s.a. "sketch" (middle part of triplets)
@@ -775,7 +775,7 @@
}
-/**
+/*
Getting a plain text title for either a folder or a topic.
*/
gboolean ossohelp_title( const char *key, char *buf, size_t bufsize )
- Previous message: [maemo-commits] r14507 - projects/haf/tags
- Next message: [maemo-commits] r14509 - in projects/haf/tags: . gail
- Messages sorted by: [ date ] [ thread ] [ subject ] [ author ]