Menu container. More...

Enumerations
enum	bm_filter_mode { BM_FILTER_MODE_DMENU, BM_FILTER_MODE_DMENU_CASE_INSENSITIVE, BM_FILTER_MODE_LAST }

enum	bm_scrollbar_mode { BM_SCROLLBAR_NONE, BM_SCROLLBAR_ALWAYS, BM_SCROLLBAR_AUTOHIDE, BM_SCROLLBAR_LAST }

enum	bm_run_result { BM_RUN_RESULT_RUNNING, BM_RUN_RESULT_SELECTED, BM_RUN_RESULT_CANCEL }

enum	bm_key { BM_KEY_NONE, BM_KEY_UP, BM_KEY_DOWN, BM_KEY_LEFT, BM_KEY_RIGHT, BM_KEY_HOME, BM_KEY_END, BM_KEY_PAGE_UP, BM_KEY_PAGE_DOWN, BM_KEY_SHIFT_PAGE_UP, BM_KEY_SHIFT_PAGE_DOWN, BM_KEY_BACKSPACE, BM_KEY_DELETE, BM_KEY_LINE_DELETE_LEFT, BM_KEY_LINE_DELETE_RIGHT, BM_KEY_WORD_DELETE, BM_KEY_TAB, BM_KEY_SHIFT_TAB, BM_KEY_ESCAPE, BM_KEY_RETURN, BM_KEY_SHIFT_RETURN, BM_KEY_CONTROL_RETURN, BM_KEY_UNICODE, BM_KEY_LAST }

enum	bm_color { BM_COLOR_TITLE_BG, BM_COLOR_TITLE_FG, BM_COLOR_FILTER_BG, BM_COLOR_FILTER_FG, BM_COLOR_ITEM_BG, BM_COLOR_ITEM_FG, BM_COLOR_HIGHLIGHTED_BG, BM_COLOR_HIGHLIGHTED_FG, BM_COLOR_SELECTED_BG, BM_COLOR_SELECTED_FG, BM_COLOR_SCROLLBAR_BG, BM_COLOR_SCROLLBAR_FG, BM_COLOR_LAST }

Menu Memory
struct bm_menu *	bm_menu_new (const char *renderer)

void	bm_menu_free (struct bm_menu *menu)

void	bm_menu_free_items (struct bm_menu *menu)

Menu Properties
void	bm_menu_set_userdata (struct bm_menu menu, void userdata)

void *	bm_menu_get_userdata (struct bm_menu *menu)

void	bm_menu_set_prefix (struct bm_menu menu, const char prefix)

const char *	bm_menu_get_prefix (struct bm_menu *menu)

void	bm_menu_set_filter (struct bm_menu menu, const char filter)

const char *	bm_menu_get_filter (struct bm_menu *menu)

void	bm_menu_set_filter_mode (struct bm_menu *menu, enum bm_filter_mode mode)

enum bm_filter_mode	bm_menu_get_filter_mode (const struct bm_menu *menu)

void	bm_menu_set_lines (struct bm_menu *menu, uint32_t lines)

uint32_t	bm_menu_get_lines (struct bm_menu *menu)

void	bm_menu_set_wrap (struct bm_menu *menu, bool wrap)

bool	bm_menu_get_wrap (const struct bm_menu *menu)

bool	bm_menu_set_title (struct bm_menu menu, const char title)

const char *	bm_menu_get_title (const struct bm_menu *menu)

bool	bm_menu_set_font (struct bm_menu menu, const char font)

const char *	bm_menu_get_font (const struct bm_menu *menu)

bool	bm_menu_set_color (struct bm_menu menu, enum bm_color color, const char hex)

const char *	bm_menu_get_color (const struct bm_menu *menu, enum bm_color color)

void	bm_menu_set_scrollbar (struct bm_menu *menu, enum bm_scrollbar_mode mode)

enum bm_scrollbar_mode	bm_menu_get_scrollbar (struct bm_menu *menu)

void	bm_menu_set_bottom (struct bm_menu *menu, bool bottom)

bool	bm_menu_get_bottom (struct bm_menu *menu)

void	bm_menu_set_monitor (struct bm_menu *menu, uint32_t monitor)

uint32_t	bm_menu_get_monitor (struct bm_menu *menu)

void	bm_menu_grab_keyboard (struct bm_menu *menu, bool grab)

bool	bm_menu_is_keyboard_grabbed (struct bm_menu *menu)

Menu Items
bool	bm_menu_add_item_at (struct bm_menu menu, struct bm_item item, uint32_t index)

bool	bm_menu_add_item (struct bm_menu menu, struct bm_item item)

bool	bm_menu_remove_item_at (struct bm_menu *menu, uint32_t index)

bool	bm_menu_remove_item (struct bm_menu menu, struct bm_item item)

bool	bm_menu_set_highlighted_index (struct bm_menu *menu, uint32_t index)

bool	bm_menu_set_highlighted_item (struct bm_menu menu, struct bm_item item)

struct bm_item *	bm_menu_get_highlighted_item (const struct bm_menu *menu)

bool	bm_menu_set_selected_items (struct bm_menu menu, struct bm_item *items, uint32_t nmemb)

struct bm_item **	bm_menu_get_selected_items (const struct bm_menu menu, uint32_t out_nmemb)

bool	bm_menu_set_items (struct bm_menu menu, const struct bm_item *items, uint32_t nmemb)

struct bm_item **	bm_menu_get_items (const struct bm_menu menu, uint32_t out_nmemb)

struct bm_item **	bm_menu_get_filtered_items (const struct bm_menu menu, uint32_t out_nmemb)

Menu Logic
void	bm_menu_render (const struct bm_menu *menu)

void	bm_menu_filter (struct bm_menu *menu)

enum bm_key	bm_menu_poll_key (struct bm_menu menu, uint32_t out_unicode)

enum bm_run_result	bm_menu_run_with_key (struct bm_menu *menu, enum bm_key key, uint32_t unicode)

Detailed Description

Menu container.

Holds all the items, runs logic and gets rendered.

Renderer

Enumeration Type Documentation

enum bm_filter_mode

Filter mode constants for bm_menu instance filter mode.

BM_FILTER_MODE_LAST is provided for enumerating filter modes. Using it as filter mode however provides exactly same functionality as BM_FILTER_MODE_DMENU.

enum bm_scrollbar_mode

Scrollbar display mode constants for bm_menu instance scrollbar.

BM_SCROLLBAR_ALWAYS means that scrollbar is not displayed.
BM_SCROLLBAR_ALWAYS means that scrollbar is displayed always.
BM_SCROLLBAR_AUTOHIDE means that scrollbar is only displayed when there are more items than lines.

BM_SCROLLBAR_LAST is provided for enumerating scrollbar modes. Using it as scrollbar mode however provides exactly same functionality as BM_SCROLLBAR_NONE.

enum bm_run_result

Result constants from bm_menu_run_with_key function.

BM_RUN_RESULT_RUNNING means that menu is running and thus should be still renderer && ran.
BM_RUN_RESULT_SELECTED means that menu was closed and items were selected.
BM_RUN_RESULT_CANCEL means that menu was closed and selection was canceled.

enum bm_key

Key constants.

BM_KEY_LAST is provided for enumerating keys.

enum bm_color

Colorable element constants.

BM_COLOR_LAST is provided for enumerating colors.

Function Documentation

struct bm_menu* bm_menu_new ( const char * renderer )

Create new bm_menu instance.

If NULL is used as renderer, auto-detection will be used or the renderer with the name pointed by BEMENU_BACKEND env variable. It's good idea to use NULL, if you want user to have control over the renderer with this env variable.

Parameters

renderer Name of renderer to be used for this instance, pass NULL for auto-detection.

Returns: bm_menu for new menu instance, NULL if creation failed.

void bm_menu_free ( struct bm_menu * menu )

Release bm_menu instance.

Parameters

menu	bm_menu instance to be freed from memory.

void bm_menu_free_items ( struct bm_menu * menu )

Release items inside bm_menu instance.

Parameters

menu	bm_menu instance which items will be freed from memory.

void bm_menu_set_userdata	(	struct bm_menu *	menu,
		void *	userdata
	)

Set userdata pointer to bm_menu instance. Userdata will be carried unmodified by the instance.

Parameters

menu	bm_menu instance where to set userdata pointer.
userdata	Pointer to userdata.

void* bm_menu_get_userdata ( struct bm_menu * menu )

Get userdata pointer from bm_menu instance.

Parameters

menu	bm_menu instance which userdata pointer to get.

Returns: Pointer for unmodified userdata.

void bm_menu_set_prefix	(	struct bm_menu *	menu,
		const char *	prefix
	)

Set highlight prefix. This is shown on vertical list mode only.

Parameters

menu	bm_menu instance where to set highlight prefix.
prefix	Null terminated C "string" to act as prefix for highlighted item. May be set NULL for none.

const char* bm_menu_get_prefix ( struct bm_menu * menu )

Get highlight prefix.

Parameters

menu	bm_menu instance where to get highlight prefix.
Const	pointer to current highlight prefix, may be NULL if empty.

void bm_menu_set_filter	(	struct bm_menu *	menu,
		const char *	filter
	)

Set filter text to bm_menu instance.

Parameters

menu	bm_menu instance where to set filter.
filter	Null terminated C "string" to act as filter. May be set NULL for none.

const char* bm_menu_get_filter ( struct bm_menu * menu )

Get filter text from bm_menu instance.

Parameters

menu	bm_menu instance where to get filter.

Returns: Const pointer to current filter text, may be NULL if empty.

void bm_menu_set_filter_mode	(	struct bm_menu *	menu,
		enum bm_filter_mode	mode
	)

Set active filter mode to bm_menu instance.

Parameters

menu	bm_menu instance where to set filter mode.
mode	bm_filter_mode constant.

enum bm_filter_mode bm_menu_get_filter_mode ( const struct bm_menu * menu )

Get active filter mode from bm_menu instance.

Parameters

menu	bm_menu instance where to get filter mode.

Returns: bm_filter_mode constant.

void bm_menu_set_lines	(	struct bm_menu *	menu,
		uint32_t	lines
	)

Set amount of max vertical lines to be shown. Some renderers such as ncurses may ignore this when it does not make sense.

Parameters

menu	bm_menu instance where to set max vertical line amount.
lines	0 for single line layout, > 0 to show that many lines.

uint32_t bm_menu_get_lines ( struct bm_menu * menu )

Get amount of max vertical lines to be shown.

Parameters

menu	bm_menu instance where to get max vertical line amount.

Returns: uint32_t for max amount of vertical lines to be shown.

void bm_menu_set_wrap	(	struct bm_menu *	menu,
		bool	wrap
	)

Set selection wrapping on/off.

Parameters

menu	bm_menu instance where to toggle selection wrapping.
wrap	true/false.

bool bm_menu_get_wrap ( const struct bm_menu * menu )

Get selection wrapping state.

Parameters

menu	bm_menu instance where to get selection wrapping state.

Returns: int for wrap state.

bool bm_menu_set_title	(	struct bm_menu *	menu,
		const char *	title
	)

Set title to bm_menu instance.

Parameters

menu	bm_menu instance where to set title.
title	C "string" to set as title, can be NULL for empty title.

Returns: true if set was succesful, false if out of memory.

const char* bm_menu_get_title ( const struct bm_menu * menu )

Get title from bm_menu instance.

Parameters

menu	bm_menu instance where to get title from.

Returns: Pointer to null terminated C "string", can be NULL for empty title.

bool bm_menu_set_font	(	struct bm_menu *	menu,
		const char *	font
	)

Set font description to bm_menu instance.

Parameters

menu	bm_menu instance where to set font.
font	C "string" for a pango style font description, can be NULL for default (Terminus 9).

Returns: true if set was succesful, false if out of memory.

const char* bm_menu_get_font ( const struct bm_menu * menu )

Get font description from bm_menu instance.

Parameters

menu	bm_menu instance where to get font description from.

Returns: Pointer to null terminated C "string".

bool bm_menu_set_color	(	struct bm_menu *	menu,
		enum bm_color	color,
		const char *	hex
	)

Set a hexadecimal color for element.

Parameters

menu	bm_menu instance where to set color.
color	bm_color type.
hex	Color in hexadecimal format starting with '#'.

Returns: true if set was succesful, false if out of memory.

const char* bm_menu_get_color	(	const struct bm_menu *	menu,
		enum bm_color	color
	)

Get hexadecimal color for element.

Parameters

menu	bm_menu instance where to get color from.
color	bm_color type.

Returns: Pointer to null terminated C "string".

void bm_menu_set_scrollbar	(	struct bm_menu *	menu,
		enum bm_scrollbar_mode	mode
	)

Set scrollbar display mode.

Parameters

menu	bm_menu instance to set scrollbar for.
mode	bm_scrollbar_mode constant.

enum bm_scrollbar_mode bm_menu_get_scrollbar ( struct bm_menu * menu )

Return current scrollbar display mode.

Parameters

menu	bm_menu instance where to get scrollbar display state from.

Returns: bm_scrollbar_mode constant.

void bm_menu_set_bottom	(	struct bm_menu *	menu,
		bool	bottom
	)

Display menu at bottom of the screen. This may be no-op on some renderers (curses, wayland)

Parameters

menu	bm_menu instance to set bottom mode for.
bottom	true for bottom mode, false for top mode.

bool bm_menu_get_bottom ( struct bm_menu * menu )

Is menu being displayed at bottom of the screen?

Parameters

menu	bm_menu instance where to get bottom mode from.

Returns: true if bottom mode, false otherwise.

void bm_menu_set_monitor	(	struct bm_menu *	menu,
		uint32_t	monitor
	)

Display menu at monitor index. Indices start from 1, pass 0 for active monitor (default). If index is more than amount of monitors, the monitor with highest index will be selected.

Parameters

menu	bm_menu instance to set monitor for.
monitor	Monitor index starting from 1.

uint32_t bm_menu_get_monitor ( struct bm_menu * menu )

Return index for current monitor.

Parameters

menu	bm_menu instance where to get current monitor from.

Returns: Monitor index starting from 1.

void bm_menu_grab_keyboard	(	struct bm_menu *	menu,
		bool	grab
	)

Tell renderer to grab keyboard. This only works with x11 renderer.

Parameters

menu	bm_menu instance to set grab for.
grab	true for grab, false for ungrab.

bool bm_menu_is_keyboard_grabbed ( struct bm_menu * menu )

Is keyboard grabbed for bm_menu?

Parameters

menu	bm_menu instance where to check grab status from.

Returns: true if grabbed, false if not.

bool bm_menu_add_item_at	(	struct bm_menu *	menu,
		struct bm_item *	item,
		uint32_t	index
	)

Add item to bm_menu instance at specific index.

Parameters

menu	bm_menu instance where item will be added.
item	bm_item instance to add.
index	Index where item will be added.

Returns: true on successful add, false on failure.

bool bm_menu_add_item	(	struct bm_menu *	menu,
		struct bm_item *	item
	)

Add item to bm_menu instance.

Parameters

menu	bm_menu instance where item will be added.
item	bm_item instance to add.

Returns: true on successful add, false on failure.

bool bm_menu_remove_item_at	(	struct bm_menu *	menu,
		uint32_t	index
	)

Remove item from bm_menu instance at specific index.

Warning: The item won't be freed, use bm_item_free to do that.

Parameters

menu	bm_menu instance from where item will be removed.
index	Index of item to remove.

Returns: true on successful add, false on failure.

bool bm_menu_remove_item	(	struct bm_menu *	menu,
		struct bm_item *	item
	)

Remove item from bm_menu instance.

Warning: The item won't be freed, use bm_item_free to do that.

Parameters

menu	bm_menu instance from where item will be removed.
item	bm_item instance to remove.

Returns: true on successful add, false on failure.

bool bm_menu_set_highlighted_index	(	struct bm_menu *	menu,
		uint32_t	index
	)

Highlight item in menu by index.

Parameters

menu	bm_menu instance from where to highlight item.
index	Index of item to highlight.

Returns: true on successful highlight, false on failure.

bool bm_menu_set_highlighted_item	(	struct bm_menu *	menu,
		struct bm_item *	item
	)

Highlight item in menu.

Parameters

menu	bm_menu instance from where to highlight item.
item	bm_item instance to highlight.

Returns: true on successful highlight, false on failure.

struct bm_item* bm_menu_get_highlighted_item ( const struct bm_menu * menu )

Get highlighted item from bm_menu instance.

Warning: The pointer returned by this function may be invalid after items change.

Parameters

menu	bm_menu instance from where to get highlighted item.

Returns: Selected bm_item instance, NULL if none highlighted.

bool bm_menu_set_selected_items	(	struct bm_menu *	menu,
		struct bm_item **	items,
		uint32_t	nmemb
	)

Set selected items to bm_menu instance.

Parameters

menu	bm_menu instance where items will be set.
items	Array of bm_item pointers to set.
nmemb	Total count of items in array.

Returns: true on successful set, false on failure.

struct bm_item** bm_menu_get_selected_items	(	const struct bm_menu *	menu,
		uint32_t *	out_nmemb
	)

Get selected items from bm_menu instance.

Warning: The pointer returned by this function may be invalid after selection or items change.

Parameters

menu	bm_menu instance from where to get selected items.
out_nmemb	Reference to uint32_t where total count of returned items will be stored.

Returns: Pointer to array of bm_item pointers.

bool bm_menu_set_items	(	struct bm_menu *	menu,
		const struct bm_item **	items,
		uint32_t	nmemb
	)

Set items to bm_menu instance. Will replace all the old items on bm_menu instance.

If items is NULL, or nmemb is zero, all items will be freed from the menu.

Parameters

menu	bm_menu instance where items will be set.
items	Array of bm_item pointers to set.
nmemb	Total count of items in array.

Returns: true on successful set, false on failure.

struct bm_item** bm_menu_get_items	(	const struct bm_menu *	menu,
		uint32_t *	out_nmemb
	)

Get items from bm_menu instance.

Warning: The pointer returned by this function may be invalid after removing or adding new items.

Parameters

menu	bm_menu instance from where to get items.
out_nmemb	Reference to uint32_t where total count of returned items will be stored.

Returns: Pointer to array of bm_item pointers.

struct bm_item** bm_menu_get_filtered_items	(	const struct bm_menu *	menu,
		uint32_t *	out_nmemb
	)

Get filtered (displayed) items from bm_menu instance.

Warning: The pointer returned by this function will be invalid when menu internally filters its list again. Do not store this pointer.

Parameters

menu	bm_menu instance from where to get filtered items.
out_nmemb	Reference to uint32_t where total count of returned items will be stored.

Returns: Pointer to array of bm_item pointers.

void bm_menu_render ( const struct bm_menu * menu )

Render bm_menu instance using chosen renderer.

This function may block on wayland and x11 renderer.

Parameters

menu	bm_menu instance to be rendered.

void bm_menu_filter ( struct bm_menu * menu )

Trigger filtering of menu manually. This is useful when adding new items and want to dynamically see them filtered.

Do note that filtering might be heavy, so you should only call it after batch manipulation of items. Not after manipulation of each single item.

Parameters

menu	bm_menu instance which to filter.

enum bm_key bm_menu_poll_key	(	struct bm_menu *	menu,
		uint32_t *	out_unicode
	)

Poll key and unicode from underlying UI toolkit.

This function will block on curses renderer.

Parameters

menu	bm_menu instance from which to poll.
out_unicode	Reference to uint32_t.

Returns: bm_key for polled key.

enum bm_run_result bm_menu_run_with_key	(	struct bm_menu *	menu,
		enum bm_key	key,
		uint32_t	unicode
	)

Advances menu logic with key and unicode as input.

Parameters

menu	bm_menu instance to be advanced.
key	Key input that will advance menu logic.
unicode	Unicode input that will advance menu logic.

Returns: bm_run_result for menu state.

Enumerations

Menu Memory

Menu Properties

Menu Items

Menu Logic

Detailed Description

Enumeration Type Documentation

Function Documentation