diff options
author | Dave Davenport <qball@gmpclient.org> | 2016-10-14 16:46:54 +0200 |
---|---|---|
committer | Dave Davenport <qball@gmpclient.org> | 2016-10-14 16:46:54 +0200 |
commit | ce341f68851e1170e231fc25cc8183183a2da99b (patch) | |
tree | 9eba2ba8f0354e55734c281f276d1c62a84380d6 /include | |
parent | b4c599f022feb69d5be7c27a3037c70c02c44790 (diff) |
Document more headers.
Diffstat (limited to 'include')
-rw-r--r-- | include/dialogs/combi.h | 9 | ||||
-rw-r--r-- | include/dialogs/dmenu.h | 3 | ||||
-rw-r--r-- | include/dialogs/drun.h | 1 | ||||
-rw-r--r-- | include/dialogs/help-keys.h | 4 | ||||
-rw-r--r-- | include/dialogs/run.h | 1 | ||||
-rw-r--r-- | include/dialogs/ssh.h | 4 | ||||
-rw-r--r-- | include/helper.h | 4 | ||||
-rw-r--r-- | include/rofi.h | 8 | ||||
-rw-r--r-- | include/view.h | 6 | ||||
-rw-r--r-- | include/widgets/textbox.h | 79 | ||||
-rw-r--r-- | include/widgets/widget.h | 1 | ||||
-rw-r--r-- | include/x11-helper.h | 146 | ||||
-rw-r--r-- | include/xrmoptions.h | 2 |
13 files changed, 229 insertions, 39 deletions
diff --git a/include/dialogs/combi.h b/include/dialogs/combi.h index a3082c4a..f4259ec0 100644 --- a/include/dialogs/combi.h +++ b/include/dialogs/combi.h @@ -5,9 +5,18 @@ * @defgroup COBIMode Combi * @ingroup MODES * + * Dialog that can combine multiple #Mode into one view. + * + * This mode uses the following options from the #config object: + * * #Settings::combi_modi + * + * It creates the following option: + * * Settings::display_combi + * * @{ */ +/** #Mode object representing the combi dialog. */ extern Mode combi_mode; /*@}*/ diff --git a/include/dialogs/dmenu.h b/include/dialogs/dmenu.h index a495fe44..d25ef529 100644 --- a/include/dialogs/dmenu.h +++ b/include/dialogs/dmenu.h @@ -15,6 +15,9 @@ */ int dmenu_switcher_dialog ( void ); +/** + * Print dmenu mode commandline options to stdout, for use in help menu. + */ void print_dmenu_options ( void ); /*@}*/ diff --git a/include/dialogs/drun.h b/include/dialogs/drun.h index ac3ef1b0..8296e7a3 100644 --- a/include/dialogs/drun.h +++ b/include/dialogs/drun.h @@ -8,6 +8,7 @@ */ #include <config.h> #ifdef ENABLE_DRUN +/** #Mode object representing the desktop menu run dialog. */ extern Mode drun_mode; #endif // ENABLE_DRUN /*@}*/ diff --git a/include/dialogs/help-keys.h b/include/dialogs/help-keys.h index b444a5be..fff00397 100644 --- a/include/dialogs/help-keys.h +++ b/include/dialogs/help-keys.h @@ -10,8 +10,8 @@ * @{ */ /** - * Internal handle to the help key mode - */ + * #Mode object representing the help key mode view + */ extern Mode help_keys_mode; /*@}*/ #endif // ROFI_DIALOG_HELPKEYS_H diff --git a/include/dialogs/run.h b/include/dialogs/run.h index 4a4d9674..e325a934 100644 --- a/include/dialogs/run.h +++ b/include/dialogs/run.h @@ -12,6 +12,7 @@ * * @{ */ +/** #Mode object representing the run dialog. */ extern Mode run_mode; /*@}*/ diff --git a/include/dialogs/ssh.h b/include/dialogs/ssh.h index d55e2db0..63eac16f 100644 --- a/include/dialogs/ssh.h +++ b/include/dialogs/ssh.h @@ -17,9 +17,7 @@ * @{ */ -/** - * SSH Mode object. - */ +/** #Mode object representing the ssh dialog. */ extern Mode ssh_mode; /*@}*/ #endif // ROFI_DIALOG_SSH_H diff --git a/include/helper.h b/include/helper.h index e1bf335d..65354269 100644 --- a/include/helper.h +++ b/include/helper.h @@ -35,7 +35,7 @@ int helper_parse_setup ( char * string, char ***output, int *length, ... ); GRegex **tokenize ( const char *input, int case_sensitive ); /** - * @param tokens Array of regex objects + * @param tokens Array of regex objects * * Frees the array of regex expressions. */ @@ -177,7 +177,7 @@ unsigned int levenshtein ( const char *needle, const char *haystack ); char * rofi_force_utf8 ( gchar *data, ssize_t length ); /** - * @param data the array holding latin text + * @param data the array holding latin text * @param length the length of the data array * * Converts latin to UTF-8. diff --git a/include/rofi.h b/include/rofi.h index f94a2ec9..8bd8e960 100644 --- a/include/rofi.h +++ b/include/rofi.h @@ -44,13 +44,13 @@ const Mode * rofi_get_mode ( unsigned int index ); */ void rofi_set_return_code ( int code ); /** Reset terminal */ -#define color_reset "\033[0m" +#define color_reset "\033[0m" /** Set terminal text bold */ -#define color_bold "\033[1m" +#define color_bold "\033[1m" /** Set terminal text italic */ -#define color_italic "\033[2m" +#define color_italic "\033[2m" /** Set terminal foreground text green */ -#define color_green "\033[0;32m" +#define color_green "\033[0;32m" /** Appends instructions on how to report an error. */ #define ERROR_MSG( a ) a "\n" \ diff --git a/include/view.h b/include/view.h index 2fc7ec3a..c7b9e574 100644 --- a/include/view.h +++ b/include/view.h @@ -158,7 +158,7 @@ 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 ); @@ -166,7 +166,7 @@ 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 ); @@ -174,7 +174,7 @@ 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 ); diff --git a/include/widgets/textbox.h b/include/widgets/textbox.h index 48d6e875..15de87dc 100644 --- a/include/widgets/textbox.h +++ b/include/widgets/textbox.h @@ -17,6 +17,10 @@ * * @{ */ +/** + * Internal structure of a textbox widget. + * @TODO make this internal to textbox + */ typedef struct { widget widget; @@ -37,6 +41,9 @@ typedef struct guint blink_timeout; } textbox; +/** + * Flags for configuring textbox behaviour and looks during creation. + */ typedef enum { TB_AUTOHEIGHT = 1 << 0, @@ -50,25 +57,46 @@ typedef enum TB_PASSWORD = 1 << 22, TB_INDICATOR = 1 << 23, } TextboxFlags; - +/** + * Flags indicating current state of the textbox. + */ typedef enum { - // Render font normally + /** Normal */ NORMAL = 0, + /** Text in box is urgent. */ URGENT = 1, + /** Text in box is active. */ ACTIVE = 2, + /** Text in box is selected. */ SELECTED = 4, + /** Text in box has pango markup. */ MARKUP = 8, - // Alternating row. + /** Text is on an alternate row */ ALT = 16, - // Render font highlighted (inverted colors.) + /** Render font highlighted (inverted colors.) */ HIGHLIGHT = 32, - + /** Mask for alternate and highlighted */ FMOD_MASK = ( ALT | HIGHLIGHT ), + /** Mask of bits indicating state */ STATE_MASK = ~( SELECTED | MARKUP | ALT | HIGHLIGHT ) } TextBoxFontType; +/** + * @param flags #TextboxFlags indicating the type of textbox. + * @param x horizontal positon of textbox + * @param y vertical position of textbox + * @param w width of textbox + * @param h height of textbox + * @param tbft #TextBoxFontType current state of textbox. + * @param text intial text to display. + * + * Create a new textbox widget. + * + * free with #widget_free + * @returns a new #textbox + */ textbox* textbox_create ( TextboxFlags flags, short x, short y, short w, short h, TextBoxFontType tbft, @@ -89,6 +117,14 @@ void textbox_font ( textbox *tb, TextBoxFontType tbft ); */ void textbox_text ( textbox *tb, const char *text ); +/** + * @param tb Handle to the textbox + * @param action the #KeyBindingAction to execute on textbox + * + * Execute an action on the textbox. + * + * @return TRUE if action was taken. + */ int textbox_keybinding ( textbox *tb, KeyBindingAction action ); /** * @param tb Handle to the textbox @@ -208,11 +244,44 @@ void textbox_cursor_inc ( textbox *tb ); */ void textbox_delete ( textbox *tb, int pos, int dlen ); +/** + * @param tb Handle to the textbox + * @param x The new horizontal position to place with textbox + * @param y The new vertical position to place with textbox + * @param w The new width of the textbox + * @param h The new height of the textbox + * + * Move and resize the textbox. + * @TODO remove for #widget_resize and #widget_move + */ void textbox_moveresize ( textbox *tb, int x, int y, int w, int h ); +/** + * Get the (estimated) with of a character, can be used to calculate window width. + * + * @returns the estimated width of a character. + */ int textbox_get_estimated_char_height ( void ); +/** + * @param p The new default PangoContext + * + * Set the default pango context (with font description) for all textboxes. + */ void textbox_set_pango_context ( PangoContext *p ); +/** + * @param tb Handle to the textbox + * @param list New pango attributes + * + * Sets #list as active pango attributes. + */ void textbox_set_pango_attributes ( textbox *tb, PangoAttrList *list ); +/** + * @param tb Handle to the textbox + * + * Get the list of currently active pango attributes. + * + * @returns the pango attributes + */ PangoAttrList *textbox_get_pango_attributes ( textbox *tb ); /** diff --git a/include/widgets/widget.h b/include/widgets/widget.h index 26e8e05f..8edc3de5 100644 --- a/include/widgets/widget.h +++ b/include/widgets/widget.h @@ -141,7 +141,6 @@ gboolean widget_need_redraw ( widget *wid ); */ gboolean widget_clicked ( widget *wid, xcb_button_press_event_t *xbe ); - /** * @param wid The widget handle * @param cb The widget click callback diff --git a/include/x11-helper.h b/include/x11-helper.h index aa3f6095..e07b2eb5 100644 --- a/include/x11-helper.h +++ b/include/x11-helper.h @@ -23,15 +23,22 @@ */ char* window_get_text_prop ( xcb_window_t w, xcb_atom_t atom ); -void window_set_atom_prop ( xcb_window_t w, xcb_atom_t prop, xcb_atom_t *atoms, int count ); - /** - * xcb_window_t info. + * @param w The xcb_window_t to set property on + * @param prop Atom of the property to change + * @param atoms List of atoms to change the property too + * @param count The length of the #atoms list. + * + * Set property on window. */ +void window_set_atom_prop ( xcb_window_t w, xcb_atom_t prop, xcb_atom_t *atoms, int count ); + +/** For getting the atoms in an enum */ #define ATOM_ENUM( x ) x +/** Get the atoms as strings. */ #define ATOM_CHAR( x ) # x -// usable space on a monitor +/** Atoms we want to pre-load */ #define EWMH_ATOMS( X ) \ X ( _NET_WM_WINDOW_OPACITY ), \ X ( I3_SOCKET_PATH ), \ @@ -42,53 +49,93 @@ void window_set_atom_prop ( xcb_window_t w, xcb_atom_t prop, xcb_atom_t *atoms, X ( _MOTIF_WM_HINTS ), \ X ( ESETROOT_PMAP_ID ) +/** enumeration of the atoms. */ enum { EWMH_ATOMS ( ATOM_ENUM ), NUM_NETATOMS }; - +/** atoms as string */ extern const char *netatom_names[]; +/** atoms */ extern xcb_atom_t netatoms[NUM_NETATOMS]; +/** + * Enumerator describing the different modifier keys. + */ enum { + /** Shift key */ X11MOD_SHIFT, + /** Control Key */ X11MOD_CONTROL, + /** Alt key */ X11MOD_ALT, + /** Meta key */ X11MOD_META, + /** Super (window) key */ X11MOD_SUPER, + /** Hyper key */ X11MOD_HYPER, + /** Any modifier */ X11MOD_ANY, + /** Number of modifier keys */ NUM_X11MOD }; +/** + * Structure describing a workarea/monitor. + */ typedef struct _workarea { + /** numeric monitor id. */ int monitor_id; + /** if monitor is set as primary monitor. */ int primary; - int x, y, w, h; + /** Horizontal location (in pixels) of the monitor. */ + int x; + /** Vertical location (in pixels) of the monitor. */ + int y; + /** Width of the monitor. */ + int w; + /** Height of the monitor */ + int h; + /** Output name of the monitor, e.g. eDP1 or VGA-1 */ char *name; + /** Pointer to next monitor */ struct _workarea *next; } workarea; -int monitor_active ( workarea *mon ); -// find the dimensions of the monitor displaying point x,y -void monitor_dimensions ( int x, int y, workarea *mon ); -// Find the dimensions of the monitor specified by user. -int monitor_get_dimension ( int monitor_id, workarea *mon ); -int monitor_get_smallest_size ( void ); +/** + * @param mon workarea to be filled in. + * + * Fills in #mon with the information about the monitor rofi should show on. + * + * @returns TRUE if monitor is found, FALSE if no monitor could be detected. + */ +int monitor_active ( workarea *mon ); /** - * Release keyboard. + * Release keyboard grab on root window. */ void release_keyboard ( void ); +/** + * Release pointer grab on root window. + */ void release_pointer ( void ); /** * @param w xcb_window_t we want to grab keyboard on. * - * Grab keyboard and mouse. + * Grab keyboard. * * @return 1 when keyboard is grabbed, 0 not. */ int take_keyboard ( xcb_window_t w ); + +/** + * @param w xcb_window_t we want to grab mouse on. + * + * Grab mouse. + * + * @return 1 when mouse is grabbed, 0 not. + */ int take_pointer ( xcb_window_t w ); /** @@ -98,6 +145,13 @@ int take_pointer ( xcb_window_t w ); */ unsigned int x11_canonalize_mask ( unsigned int mask ); +/** + * @param xkb the xkb structure. + * + * Calculates the mask of all active modifier keys. + * + * @returns the mask describing all active modifier keys. + */ unsigned int x11_get_current_mask ( xkb_stuff *xkb ); /** @@ -126,10 +180,21 @@ void x11_set_window_opacity ( xcb_window_t box, unsigned int opacity ); */ void x11_setup ( xkb_stuff *xkb ); -extern xcb_depth_t *depth; +/** + * Depth of visual + */ +extern xcb_depth_t *depth; +/** + * Visual to use for creating window + */ extern xcb_visualtype_t *visual; -extern xcb_colormap_t map; -extern xcb_depth_t *root_depth; +/** + * Color map to use for creating window + */ +extern xcb_colormap_t map; +/** + * Depth of root window. + */ extern xcb_visualtype_t *root_visual; /** * This function tries to create a 32bit TrueColor colormap. @@ -137,9 +202,19 @@ extern xcb_visualtype_t *root_visual; */ void x11_create_visual_and_colormap ( void ); +/** + * Structure describing a cairo color. + */ typedef struct { - double red, green, blue, alpha; + /** red channel */ + double red; + /** green channel */ + double green; + /** blue channel */ + double blue; + /** alpha channel */ + double alpha; } Color; /** @@ -149,10 +224,32 @@ typedef struct */ Color color_get ( const char *const name ); +/** + * @param d cairo drawing context to set color on + * + * Set cairo drawing context source color to the background color. + */ void color_background ( cairo_t *d ); + +/** + * @param d cairo drawing context to set color on + * + * Set cairo drawing context source color to the border color. + */ void color_border ( cairo_t *d ); +/** + * @param d cairo drawing context to set color on + * + * Set cairo drawing context source color to the separator color. + */ void color_separator ( cairo_t *d ); +/** + * @param d cairo drawing context to set color on. + * @param col The color to set. + * + * Sets col as cairo source color. + */ void x11_helper_set_cairo_rgba ( cairo_t *d, Color col ); /** @@ -167,7 +264,20 @@ cairo_surface_t * x11_helper_get_bg_surface ( void ); * Used for positioning rofi. */ void x11_build_monitor_layout ( void ); + +/** + * Dump the monitor layout to stdout. + */ void x11_dump_monitor_layout ( void ); + +/** + * @param mask the mask to check for key + * @param key the key to check in mask + * + * Check if key is in the modifier mask. + * + * @returns TRUE if key is in the modifier mask + */ int x11_modifier_active ( unsigned int mask, int key ); /** diff --git a/include/xrmoptions.h b/include/xrmoptions.h index 489c91f3..f0c8e3ac 100644 --- a/include/xrmoptions.h +++ b/include/xrmoptions.h @@ -36,7 +36,7 @@ */ /** - * Type of the config options. + * Type of the config options. */ typedef enum { |