Merged in default (pull request #87)
Add more documentation
Approved-by: Gary Kramlich
--- a/gntbindable.h Thu Aug 29 19:52:37 2019 +0000
+++ b/gntbindable.h Thu Aug 29 22:36:04 2019 +0000
@@ -37,20 +37,32 @@
typedef struct _GntBindable GntBindable;
+ * @remaps: A table of key remaps from one key to another. + * @actions: A table of registered names to actions, added by + * gnt_bindable_class_register_action(). + * @bindings: A table of registered keys to actions, added by + * gnt_bindable_register_binding(). + * @help_window: A #GntWindow used for displaying key binding help. + * The class structure for #GntBindable. Note, while documented, the fields here - GHashTable *remaps; /* Key remaps */
- GHashTable *actions; /* name -> Action */
- GHashTable *bindings; /* key -> ActionParam */
GntBindable * help_window;
- void (*gnt_reserved2)(void);
- void (*gnt_reserved3)(void);
- void (*gnt_reserved4)(void);
@@ -62,10 +74,24 @@
const char * gnt_bindable_remap_keys(GntBindable *bindable, const char *text);
-typedef gboolean (*GntBindableActionCallback) (GntBindable *bindable, GList *params);
+ * GntBindableActionCallback: + * @bindable: A bindable object. + * @params: Parameters passed to gnt_bindable_class_register_action(). + * A callback for an action registered by gnt_bindable_class_register_action(). +typedef gboolean (*GntBindableActionCallback)(GntBindable *bindable, + * GntBindableActionCallbackNoParam: + * @bindable: A bindable object. + * A callback for an action with no parameters. typedef gboolean (*GntBindableActionCallbackNoParam)(GntBindable *bindable);
--- a/gntbox.h Thu Aug 29 19:52:37 2019 +0000
+++ b/gntbox.h Thu Aug 29 22:36:04 2019 +0000
@@ -61,15 +61,18 @@
+ * The class structure for #GntBox. - void (*gnt_reserved1)(void);
- void (*gnt_reserved2)(void);
- void (*gnt_reserved3)(void);
- void (*gnt_reserved4)(void);
@@ -83,19 +86,36 @@
G_DECLARE_DERIVABLE_TYPE(GntBox, gnt_box, GNT, BOX, GntWidget)
+ * @homogeneous: If %TRUE, all the widgets in it will have the same width. + * Create a new horizontal box. + * Returns: The new box. +#define gnt_hbox_new(homogeneous) gnt_box_new(homogeneous, FALSE) + * @homogeneous: If %TRUE, all the widgets in it will have the same height. + * Create a new vertical box. + * Returns: The new box. #define gnt_vbox_new(homogeneous) gnt_box_new(homogeneous, TRUE)
-#define gnt_hbox_new(homogeneous) gnt_box_new(homogeneous, FALSE)
- * @homogeneous: If %TRUE, all the widgets in it will have the same width (or
+ * @homogeneous: If %TRUE, all the widgets in it will have the same height (or * @vert: Whether the widgets in it should be stacked vertically (if %TRUE) or
* horizontally (if %FALSE).
- * Returns: The new GntBox.
+ * Returns: The new box. GntWidget *gnt_box_new(gboolean homogeneous, gboolean vert);
--- a/gntbutton.h Thu Aug 29 19:52:37 2019 +0000
+++ b/gntbutton.h Thu Aug 29 22:36:04 2019 +0000
@@ -37,15 +37,18 @@
#define GNT_TYPE_BUTTON gnt_button_get_type()
+ * The class structure for #GntButton. - void (*gnt_reserved1)(void);
- void (*gnt_reserved2)(void);
- void (*gnt_reserved3)(void);
- void (*gnt_reserved4)(void);
--- a/gntcheckbox.h Thu Aug 29 19:52:37 2019 +0000
+++ b/gntcheckbox.h Thu Aug 29 22:36:04 2019 +0000
@@ -25,7 +25,7 @@
* @section_id: libgnt-gntcheckbox
* @short_description: A widget that can be toggled
@@ -37,17 +37,22 @@
#define GNT_TYPE_CHECK_BOX gnt_check_box_get_type()
+ * @toggled: The class closure for the #GntCheckBox::toggled signal. + * The class structure for #GntCheckBox. - void (*gnt_reserved1)(void);
- void (*gnt_reserved2)(void);
- void (*gnt_reserved3)(void);
- void (*gnt_reserved4)(void);
--- a/gntentry.h Thu Aug 29 19:52:37 2019 +0000
+++ b/gntentry.h Thu Aug 29 22:36:04 2019 +0000
@@ -78,17 +78,22 @@
G_DECLARE_DERIVABLE_TYPE(GntEntry, gnt_entry, GNT, ENTRY, GntWidget)
+ * @text_changed: The class closure for the #GntEntry::text-changed signal. + * The class structure for #GntEntry. void (*text_changed)(GntEntry *entry);
- void (*gnt_reserved1)(void);
- void (*gnt_reserved2)(void);
- void (*gnt_reserved3)(void);
- void (*gnt_reserved4)(void);
--- a/gntfilesel.h Thu Aug 29 19:52:37 2019 +0000
+++ b/gntfilesel.h Thu Aug 29 22:36:04 2019 +0000
@@ -45,19 +45,25 @@
G_DECLARE_DERIVABLE_TYPE(GntFileSel, gnt_file_sel, GNT, FILE_SEL, GntWindow)
+ * @file_selected: The class closure for the #GntFileSel::file-selected signal. + * @cancelled: The class closure for the #GntFileSel::cancelled signal. + * The class structure for #GntFileSel. void (*file_selected)(GntFileSel *sel, const char *path,
void (*cancelled)(GntFileSel *sel);
- void (*gnt_reserved1)(void);
- void (*gnt_reserved2)(void);
- void (*gnt_reserved3)(void);
- void (*gnt_reserved4)(void);
--- a/gntline.h Thu Aug 29 19:52:37 2019 +0000
+++ b/gntline.h Thu Aug 29 22:36:04 2019 +0000
@@ -45,14 +45,30 @@
G_DECLARE_FINAL_TYPE(GntLine, gnt_line, GNT, LINE, GntWidget)
+ * Create new horizontal line. + * Returns: The newly created line. #define gnt_hline_new() gnt_line_new(FALSE)
+ * Create new vertical line. + * Returns: The newly created line. #define gnt_vline_new() gnt_line_new(TRUE)
- * @vertical: %TRUE if the line should be vertical, %FALSE for a horizontal line.
+ * @vertical: %TRUE if the line should be vertical, %FALSE for a horizontal
* Returns: The newly created line.
--- a/gntmenuitem.h Thu Aug 29 19:52:37 2019 +0000
+++ b/gntmenuitem.h Thu Aug 29 22:36:04 2019 +0000
@@ -39,17 +39,27 @@
#define GNT_TYPE_MENU_ITEM gnt_menuitem_get_type()
+ * @item: The menu item which was activated. + * @data: The user data specified in gnt_menuitem_set_callback(). + * A callback for when a menu item is activated. typedef void (*GntMenuItemCallback)(GntMenuItem *item, gpointer data);
+ * The class structure for #GntMenuItem. - void (*gnt_reserved1)(void);
- void (*gnt_reserved2)(void);
- void (*gnt_reserved3)(void);
- void (*gnt_reserved4)(void);
@@ -74,7 +84,7 @@
* gnt_menuitem_set_callback:
- * @callback: (scope call): The callback function.
+ * @callback: (scope async): The callback function. * @data: Data to send to the callback function.
* Set a callback function for a menuitem.
--- a/gntslider.h Thu Aug 29 19:52:37 2019 +0000
+++ b/gntslider.h Thu Aug 29 22:36:04 2019 +0000
@@ -46,31 +46,62 @@
G_DECLARE_DERIVABLE_TYPE(GntSlider, gnt_slider, GNT, SLIDER, GntWidget)
+ * @changed: The class closure for the #GntSlider::changed signal. + * The class structure for #GntSlider. void (*changed)(GntSlider *slider, int value);
- void (*gnt_reserved1)(void);
- void (*gnt_reserved2)(void);
- void (*gnt_reserved3)(void);
- void (*gnt_reserved4)(void);
+ * @max: The maximum value for the slider. + * @min: The minimum value for the slider. + * Create a new horizontal slider. + * Returns: The newly created slider. #define gnt_hslider_new(max, min) gnt_slider_new(FALSE, max, min)
+ * @max: The maximum value for the slider. + * @min: The minimum value for the slider. + * Create a new vertical slider. + * Returns: The newly created slider. #define gnt_vslider_new(max, min) gnt_slider_new(TRUE, max, min)
- * @orient: A vertical slider is created if %TRUE, otherwise the slider is horizontal.
- * @max: The maximum value for the slider
- * @min: The minimum value for the slider
+ * @orient: A vertical slider is created if %TRUE, otherwise the slider is + * @max: The maximum value for the slider. + * @min: The minimum value for the slider. - * Returns: The newly created slider
+ * Returns: The newly created slider. --- a/gnttree.h Thu Aug 29 19:52:37 2019 +0000
+++ b/gnttree.h Thu Aug 29 22:36:04 2019 +0000
@@ -50,21 +50,43 @@
G_DECLARE_DERIVABLE_TYPE(GntTree, gnt_tree, GNT, TREE, GntWidget)
+ * @selection_changed: The class closure for the #GntTree::selection-changed + * @toggled: The class closure for the #GntTree::toggled signal. + * The class structure for #GntTree. void (*selection_changed)(GntTreeRow *old, GntTreeRow * current);
void (*toggled)(GntTree *tree, gpointer key);
- void (*gnt_reserved1)(void);
- void (*gnt_reserved2)(void);
- void (*gnt_reserved3)(void);
- void (*gnt_reserved4)(void);
+ * @tree: The tree being searched. + * @key: The key of a row. + * @search: The search string. + * @current: The content of row in the search column. + * A custom tree search function. + * Returns: If %TRUE, the row should be displayed, otherwise it's not. +typedef gboolean (*GntTreeSearchFunc)(GntTree *tree, gpointer key, * Returns: The #GType for the #GntTreeRow boxed structure.
@@ -630,18 +652,13 @@
* gnt_tree_set_search_function:
- * @func: The custom search function. The search function is
- * sent the tree itself, the key of a row, the search
- * string and the content of row in the search column.
- * If the function returns %TRUE, the row is dislayed,
+ * @func: The custom search function. * Set a custom search function.
-void gnt_tree_set_search_function(GntTree *tree,
- gboolean (*func)(GntTree *tree, gpointer key, const char *search, const char *current));
+void gnt_tree_set_search_function(GntTree *tree, GntTreeSearchFunc func); * gnt_tree_get_parent_key:
--- a/gntutils.h Thu Aug 29 19:52:37 2019 +0000
+++ b/gntutils.h Thu Aug 29 22:36:04 2019 +0000
@@ -35,6 +35,13 @@
+ * @data: The data to be copied. + * A function used to duplicate some data in a hash table. See + * gnt_hash_table_duplicate(). typedef gpointer (*GntDuplicateFunc)(gconstpointer data);
--- a/gntwidget.h Thu Aug 29 19:52:37 2019 +0000
+++ b/gntwidget.h Thu Aug 29 22:36:04 2019 +0000
@@ -68,14 +68,37 @@
G_DECLARE_DERIVABLE_TYPE(GntWidget, gnt_widget, GNT, WIDGET, GntBindable)
+ * @map: The class closure for the #GntWidget::map signal. + * @show: This will call draw() and take focus (if it can take focus). + * @destroy: The class closure for the #GntWidget::destroy signal. + * @draw: The class closure for the #GntWidget::draw signal. This will draw the + * @hide: The class closure for the #GntWidget::hide signal. + * @expose: The class closure for the #GntWidget::expose signal. + * @gained_focus: The class closure for the #GntWidget::gained-focus signal. + * @lost_focus: The class closure for the #GntWidget::lost-focus signal. + * @size_request: The class closure for the #GntWidget::size-request signal. + * @confirm_size: The class closure for the #GntWidget::confirm-size signal. + * @size_changed: The class closure for the #GntWidget::size-changed signal. + * @set_position: The class closure for the #GntWidget::position-set signal. + * @key_pressed: The class closure for the #GntWidget::key-pressed signal. + * @activate: The class closure for the #GntWidget::activate signal. + * @clicked: The class closure for the #GntWidget::clicked signal. + * The class structure for #GntWidget. void (*map)(GntWidget *widget);
- void (*show)(GntWidget *widget); /* This will call draw() and take focus (if it can take focus) */
+ void (*show)(GntWidget *widget); void (*destroy)(GntWidget *widget);
- void (*draw)(GntWidget *widget); /* This will draw the widget */
+ void (*draw)(GntWidget *widget); void (*hide)(GntWidget *widget);
void (*expose)(GntWidget *widget, int x, int y, int width, int height);
void (*gained_focus)(GntWidget *widget);
@@ -90,10 +113,7 @@
gboolean (*clicked)(GntWidget *widget, GntMouseEvent event, int x, int y);
- void (*gnt_reserved1)(void);
- void (*gnt_reserved2)(void);
- void (*gnt_reserved3)(void);
- void (*gnt_reserved4)(void);
@@ -516,7 +536,7 @@
void gnt_widget_set_is_urgent(GntWidget *widget, gboolean urgent);
- * gnt_widget_get_urgent:
+ * gnt_widget_get_is_urgent: * Returns whether the widget has the URGENT hint set.
--- a/gntwindow.h Thu Aug 29 19:52:37 2019 +0000
+++ b/gntwindow.h Thu Aug 29 22:36:04 2019 +0000
@@ -52,15 +52,18 @@
GNT_WINDOW_MAXIMIZE_Y = 1 << 1,
+ * The class structure for #GntWindow. - void (*gnt_reserved1)(void);
- void (*gnt_reserved2)(void);
- void (*gnt_reserved3)(void);
- void (*gnt_reserved4)(void);
@@ -72,8 +75,27 @@
G_DECLARE_DERIVABLE_TYPE(GntWindow, gnt_window, GNT, WINDOW, GntBox)
+ * @homogeneous: %TRUE if the widgets inside the window should have the same + * Create a new window with widgets stacked horizontally. + * Returns: The newly created window. +#define gnt_hwindow_new(homogeneous) gnt_window_box_new(homogeneous, FALSE) + * @homogeneous: %TRUE if the widgets inside the window should have the same + * Create a new window with widgets stacked vertically. + * Returns: The newly created window. #define gnt_vwindow_new(homogeneous) gnt_window_box_new(homogeneous, TRUE)
-#define gnt_hwindow_new(homogeneous) gnt_window_box_new(homogeneous, FALSE)
--- a/gntwm.h Thu Aug 29 19:52:37 2019 +0000
+++ b/gntwm.h Thu Aug 29 22:36:04 2019 +0000
@@ -39,6 +39,16 @@
#define GNT_TYPE_WM gnt_wm_get_type()
+ * @me: The widget handled by this node. + * @window: The ncurses window that backs this node. + * @scroll: The scroll position of the node. + * @panel: The ncurses panel that backs this node. + * @ws: The workspace of this node. + * A node in the window management tree. @@ -58,61 +68,68 @@
G_DECLARE_DERIVABLE_TYPE(GntWM, gnt_wm, GNT, WM, GntBindable)
+ * @new_window: The class closure for the #GntWM::new-win signal. This is called + * when a new window is shown. + * @decorate_window: The class closure for the #GntWM::decorate-win signal. + * @close_window: The class closure for the #GntWM::close-win signal. This is + * called when a window is being closed. + * @window_resize_confirm: The class closure for the #GntWM::confirm-resize + * signal. The WM may want to confirm a size for a + * @window_resized: The class closure for the #GntWM::window-resized signal. + * @window_move_confirm: The class closure for the #GntWM::confirm-move signal. + * The WM may want to confirm the position of a window. + * @window_moved: The class closure for the #GntWM::window-moved signal. + * @window_update: The class closure for the #GntWM::window-update signal. This + * - the title of the window changes + * - the 'urgency' of the window changes + * @key_pressed: This should usually return %NULL if the keys were processed by + * the WM. If not, the WM can simply return the original string, + * which will be processed by the default WM. The custom WM can + * also return a different static string for the default WM to + * @mouse_clicked: The class closure for the #GntWM::mouse-clicked signal. + * @give_focus: The class closure for the #GntWM::give-focus signal. Whatever + * the WM wants to do when a window is given focus. + * @terminal_refresh: The class closure for the #GntWM::terminal-refresh signal. + * This is invoked whenever the terminal window is resized, + * or the screen session is attached to a new terminal. + * (i.e., from the SIGWINCH callback) + * The class structure for #GntWM. - /* This is called when a new window is shown */
- void (*new_window)(GntWM *wm, GntWidget *widget);
+ void (*new_window)(GntWM *wm, GntWidget *widget); void (*decorate_window)(GntWM *wm, GntWidget *win);
- /* This is called when a window is being closed */
gboolean (*close_window)(GntWM *wm, GntWidget *win);
- /* The WM may want to confirm a size for a window first */
gboolean (*window_resize_confirm)(GntWM *wm, GntWidget *win, int *w, int *h);
void (*window_resized)(GntWM *wm, GntNode *node);
- /* The WM may want to confirm the position of a window */
gboolean (*window_move_confirm)(GntWM *wm, GntWidget *win, int *x, int *y);
void (*window_moved)(GntWM *wm, GntNode *node);
- /* This gets called when:
- * - the title of the window changes
- * - the 'urgency' of the window changes
void (*window_update)(GntWM *wm, GntNode *node);
- /* This should usually return NULL if the keys were processed by the WM.
- * If not, the WM can simply return the original string, which will be
- * processed by the default WM. The custom WM can also return a different
- * static string for the default WM to process.
gboolean (*key_pressed)(GntWM *wm, const char *key);
gboolean (*mouse_clicked)(GntWM *wm, GntMouseEvent event, int x, int y, GntWidget *widget);
- /* Whatever the WM wants to do when a window is given focus */
void (*give_focus)(GntWM *wm, GntWidget *widget);
- /* List of windows. Although the WM can keep a list of its own for the windows,
- * it'd be better if there was a way to share between the 'core' and the WM.
- /*GList *(*window_list)();*/
- /* This is invoked whenever the terminal window is resized, or the
- * screen session is attached to a new terminal. (ie, from the
void (*terminal_refresh)(GntWM *wm);
--- a/gntws.h Thu Aug 29 19:52:37 2019 +0000
+++ b/gntws.h Thu Aug 29 22:36:04 2019 +0000
@@ -47,16 +47,22 @@
G_DECLARE_DERIVABLE_TYPE(GntWS, gnt_ws, GNT, WS, GntBindable)
+ * @draw_taskbar: This is never called? + * The class structure for #GntWS. void (*draw_taskbar)(GntWS *ws, gboolean reposition);