diff options
author | Dave Davenport <qball@gmpclient.org> | 2016-10-14 08:47:21 +0200 |
---|---|---|
committer | Dave Davenport <qball@gmpclient.org> | 2016-10-14 08:47:21 +0200 |
commit | b4c599f022feb69d5be7c27a3037c70c02c44790 (patch) | |
tree | fe0a1d674e402182e6c8ae7e6ada3767d837f466 | |
parent | cc496c38ee31cab226bbede60d3790afcf108b3d (diff) |
Add more documentation.
Current state: 61% coverage.
-rw-r--r-- | doc/rofi.doxy.in | 2 | ||||
-rw-r--r-- | include/dialogs/help-keys.h | 6 | ||||
-rw-r--r-- | include/helper.h | 41 | ||||
-rw-r--r-- | include/keyb.h | 6 | ||||
-rw-r--r-- | include/rofi.h | 8 | ||||
-rw-r--r-- | include/view-internal.h | 51 | ||||
-rw-r--r-- | include/view.h | 59 | ||||
-rw-r--r-- | include/widgets/box.h | 4 | ||||
-rw-r--r-- | include/widgets/separator.h | 4 | ||||
-rw-r--r-- | include/widgets/widget.h | 5 | ||||
-rw-r--r-- | include/xrmoptions.h | 16 | ||||
-rw-r--r-- | source/view.c | 2 |
12 files changed, 176 insertions, 28 deletions
diff --git a/doc/rofi.doxy.in b/doc/rofi.doxy.in index 9113f5b6..149407a4 100644 --- a/doc/rofi.doxy.in +++ b/doc/rofi.doxy.in @@ -1859,7 +1859,7 @@ MAN_LINKS = NO # captures the structure of the code including all documentation. # The default value is: NO. -GENERATE_XML = NO +GENERATE_XML = YES # The XML_OUTPUT tag is used to specify where the XML pages will be put. If a # relative path is entered the value of OUTPUT_DIRECTORY will be put in front of diff --git a/include/dialogs/help-keys.h b/include/dialogs/help-keys.h index c7934c55..b444a5be 100644 --- a/include/dialogs/help-keys.h +++ b/include/dialogs/help-keys.h @@ -4,8 +4,14 @@ /** * @defgroup HELPKEYSMode KeysHelp * @ingroup MODES + * + * Displays the different keybindings available in *rofi* + * * @{ */ +/** + * Internal handle to the help key mode + */ extern Mode help_keys_mode; /*@}*/ #endif // ROFI_DIALOG_HELPKEYS_H diff --git a/include/helper.h b/include/helper.h index 869b6a95..e1bf335d 100644 --- a/include/helper.h +++ b/include/helper.h @@ -30,9 +30,15 @@ int helper_parse_setup ( char * string, char ***output, int *length, ... ); * * Tokenize the string on spaces. * - * @returns a newly allocated 2 dimensional array of strings. + * @returns a newly allocated array of regex objest */ GRegex **tokenize ( const char *input, int case_sensitive ); + +/** + * @param tokens Array of regex objects + * + * Frees the array of regex expressions. + */ void tokenize_free ( GRegex ** tokens ); /** @@ -149,13 +155,46 @@ void cmd_set_arguments ( int argc, char **argv ); * @returns path */ char *rofi_expand_path ( const char *input ); + +/** + * @param needle The string to find match weight off + * @param haystack The string to match against + * + * UTF-8 aware levenshtein distance calculation + * + * @returns the levenshtein distance between needle and haystack + */ unsigned int levenshtein ( const char *needle, const char *haystack ); /** + * @param data the unvalidated character array holding possible UTF-8 data + * @param length the length of the data array + * * Convert string to valid utf-8, replacing invalid parts with replacement character. + * + * @returns the converted UTF-8 string */ char * rofi_force_utf8 ( gchar *data, ssize_t length ); + +/** + * @param data the array holding latin text + * @param length the length of the data array + * + * Converts latin to UTF-8. + * + * @return the UTF-8 representation of data + */ char * rofi_latin_to_utf8_strdup ( const char *input, gssize length ); + +/** + * @param tokens Array of regexes used for matching + * @param input The input string to find the matches on + * @param retv The Attribute list to update with matches + * + * Creates a set of pango attributes highlighting the matches found in the input string. + * + * @returns the updated retv list. + */ PangoAttrList *token_match_get_pango_attr ( GRegex **tokens, const char *input, PangoAttrList *retv ); /*@}*/ #endif // ROFI_HELPER_H diff --git a/include/keyb.h b/include/keyb.h index c122e4ed..1f23ffe8 100644 --- a/include/keyb.h +++ b/include/keyb.h @@ -7,6 +7,9 @@ * @{ */ +/** + * List of all possible actions that can be triggered by a keybinding. + */ typedef enum { /** Paste from primary clipboard */ @@ -105,6 +108,9 @@ void cleanup_abe ( void ); */ KeyBindingAction abe_find_action ( unsigned int mask, xkb_keysym_t key ); +/** + * Trigger keybinding on key release. + */ void abe_trigger_release ( void ); /*@}*/ diff --git a/include/rofi.h b/include/rofi.h index 5c830db3..f94a2ec9 100644 --- a/include/rofi.h +++ b/include/rofi.h @@ -36,6 +36,12 @@ unsigned int rofi_get_num_enabled_modi ( void ); */ const Mode * rofi_get_mode ( unsigned int index ); +/** + * @param code the code to return + * + * Return value are used for integrating dmenu rofi in scripts. + * This function sets the code that rofi will return on exit. + */ void rofi_set_return_code ( int code ); /** Reset terminal */ #define color_reset "\033[0m" @@ -46,6 +52,7 @@ void rofi_set_return_code ( int code ); /** Set terminal foreground text green */ #define color_green "\033[0;32m" +/** Appends instructions on how to report an error. */ #define ERROR_MSG( a ) a "\n" \ "If you suspect this is caused by a bug in rofi,\n" \ "please report the following information to rofi's github page:\n" \ @@ -54,6 +61,7 @@ void rofi_set_return_code ( int code ); " * Steps to reproduce\n" \ " * The version of rofi you are running\n\n" \ " <i>https://github.com/DaveDavenport/rofi/</i>" +/** Indicates if ERROR_MSG uses pango markup */ #define ERROR_MSG_MARKUP TRUE /*@}*/ #endif diff --git a/include/view-internal.h b/include/view-internal.h index 1145006e..34e333e5 100644 --- a/include/view-internal.h +++ b/include/view-internal.h @@ -17,63 +17,84 @@ struct RofiViewState { + /** #Mode bound to to this view. */ Mode *sw; - // Update/Refilter list. + /** Flag indicating if view needs to be refiltered. */ int refilter; - int rchanged; + /** Main #box widget holding different elements. */ box *main_box; - // Entries + /** #box widget packing the input bar widgets. */ box *input_bar; - separator *input_bar_separator; - + /** #textbox showing the prompt in the input bar. */ textbox *prompt; + /** #textbox with the user input in the input bar. */ textbox *text; + /** #textbox showing the state of the case sensitive and sortng. */ textbox *case_indicator; + /** #separator widget below the input bar. */ + separator *input_bar_separator; + /** #listview holding the displayed elements. */ listview *list_view; - // Small overlay. + /** #textbox widget showing the overlay. */ textbox *overlay; + /** Array with the levenshtein distance for each eleemnt. */ int *distance; + /** Array with the translation between the filtered and unfiltered list. */ unsigned int *line_map; - + /** number of (unfiltered) elements to show. */ unsigned int num_lines; - // Selected element. + /** number of (filtered) elements to show. */ unsigned int filtered_lines; - // Last offset in paginating. - unsigned int last_offset; + /** Previously called key action. */ KeyBindingAction prev_action; + /** Time previous key action was executed. */ xcb_timestamp_t last_button_press; + /** Indicate view should terminate */ int quit; + /** Indicate if we should absorb the key release */ int skip_absorb; - // Return state + /** The selected line (in the unfiltered list) */ unsigned int selected_line; + /** The return state of the view */ MenuReturn retv; + /** Calculated border width */ unsigned int border; + /** Monitor #workarea the view is displayed on */ workarea mon; - // Sidebar view + /** #box holding the different modi buttons */ box *sidebar_bar; + /** number of modi to display */ unsigned int num_modi; + /** Array of #textbox that act as buttons for switching modi */ textbox **modi; - + /** Settings of the menu */ MenuFlags menu_flags; + /** If mouse was within view previously */ int mouse_seen; - + /** Flag indicating if view needs to be reloaded. */ int reload; - // Handlers. + /** X11 event loop to be called for this view. */ void ( *x11_event_loop )( struct RofiViewState *state, xcb_generic_event_t *ev, xkb_stuff *xkb ); + /** The funciton to be called when finalizing this view */ void ( *finalize )( struct RofiViewState *state ); + /** Width of the view */ int width; + /** Height of the view */ int height; + /** X position of the view */ int x; + /** Y position of the view */ int y; + /** Regexs used for matching */ GRegex **tokens; }; /** @} */ diff --git a/include/view.h b/include/view.h index 93b04d8e..2fc7ec3a 100644 --- a/include/view.h +++ b/include/view.h @@ -141,8 +141,53 @@ void rofi_view_queue_redraw ( void ); */ void rofi_view_cleanup ( void ); +/** + * @param state The handle to the view + * + * Get the mode currently displayed by the view. + * + * @returns the mode currently displayed by the view + */ Mode * rofi_view_get_mode ( RofiViewState *state ); + +/** + * Unmap the current view. + */ +void rofi_view_hide ( void ); + +/** + * Indicate the current view needs to reload its data. + * This can only be done when *more* information is available. + * + * The reloading happens 'lazy', multiple calls might be handled at once. + */ +void rofi_view_reload ( void ); + +/** + * @param state The handle to the view + * @param mode The new mode to display + * + * Change the current view to show a different mode. + */ +void rofi_view_switch_mode ( RofiViewState *state, Mode *mode ); + +/** + * @param state The handle to the view + * @param text An UTF-8 encoded character array with the text to overlay. + * + * Overlays text over the current view. Passing NULL for text hides the overlay. + */ +void rofi_view_set_overlay ( RofiViewState *state, const char *text ); + +/** + * @param menu_flags The state of the new window. + * + * Creates the internal 'Cached' window that gets reused between views. + * @TODO: Internal call to view exposed. + */ +void __create_window ( MenuFlags menu_flags ); /** @} */ + /*** * @defgroup ViewThreadPool ViewThreadPool * @ingroup View @@ -152,16 +197,14 @@ Mode * rofi_view_get_mode ( RofiViewState *state ); * * @{ */ +/** + * Initialize the threadpool + */ void rofi_view_workers_initialize ( void ); -void rofi_view_workers_finalize ( void ); - -void __create_window ( MenuFlags menu_flags ); -void rofi_view_set_overlay ( RofiViewState *state, const char *text ); /** - * Unmap the window. + * Stop all threads and free the resources used by the threadpool */ -void rofi_view_hide ( void ); -void rofi_view_reload ( void ); -void rofi_view_switch_mode ( RofiViewState *state, Mode *mode ); +void rofi_view_workers_finalize ( void ); + /**@}*/ #endif diff --git a/include/widgets/box.h b/include/widgets/box.h index 208aa0f0..10d6a5a2 100644 --- a/include/widgets/box.h +++ b/include/widgets/box.h @@ -14,6 +14,10 @@ * * @{ */ + +/** + * Abstract handle to the box widget internal state. + */ typedef struct _box box; /** diff --git a/include/widgets/separator.h b/include/widgets/separator.h index a520cd59..393ae2e3 100644 --- a/include/widgets/separator.h +++ b/include/widgets/separator.h @@ -11,6 +11,10 @@ * * @{ */ + +/** + * Abstract handle to the separator widget internal state. + */ typedef struct _separator separator; /** diff --git a/include/widgets/widget.h b/include/widgets/widget.h index 31e92586..26e8e05f 100644 --- a/include/widgets/widget.h +++ b/include/widgets/widget.h @@ -15,6 +15,11 @@ * * @{ */ + +/** + * Abstract structure holding internal state of a widget. + * Structure is elaborated in widget-internal.h + */ typedef struct _widget widget; /** diff --git a/include/xrmoptions.h b/include/xrmoptions.h index 19e89ebc..489c91f3 100644 --- a/include/xrmoptions.h +++ b/include/xrmoptions.h @@ -35,13 +35,20 @@ * @{ */ -// This maps xresource options to config structure. +/** + * Type of the config options. + */ typedef enum { + /** Config option is string */ xrm_String = 0, + /** Config option is an unsigned number */ xrm_Number = 1, + /** Config option is a signed number */ xrm_SNumber = 2, + /** Config option is a boolean (true/false) value*/ xrm_Boolean = 3, + /** Config option is a character */ xrm_Char = 4 } XrmOptionType; @@ -136,6 +143,13 @@ void print_options ( void ); */ void print_help_msg ( const char *option, const char *type, const char*text, const char *def, int isatty ); +/** + * @param length the length of the returned array + * + * Creates an array with a strings describing each keybinding. + * + * @returns an array of string with length elements + */ char ** config_parser_return_display_help ( unsigned int *length ); /* @}*/ diff --git a/source/view.c b/source/view.c index 43080043..df691674 100644 --- a/source/view.c +++ b/source/view.c @@ -946,7 +946,6 @@ static void rofi_view_refilter ( RofiViewState *state ) } } state->refilter = FALSE; - state->rchanged = TRUE; TICK_N ( "Filter done" ); } /** @@ -1350,7 +1349,6 @@ RofiViewState *rofi_view_create ( Mode *sw, state->skip_absorb = FALSE; //We want to filter on the first run. state->refilter = TRUE; - state->rchanged = TRUE; state->border = config.padding + config.menu_bw; state->x11_event_loop = rofi_view_mainloop_iter; state->finalize = finalize; |