bemenu/lib/bemenu.h

/**
 * @file bemenu.h
 *
 * Public API header.
 */

typedef struct _bmMenu bmMenu;
typedef struct _bmItem bmItem;

/**
 * @defgroup Library
 * @brief Library functions.
 *
 * Query library version, etc...
 */

/**
 * @defgroup Menu
 * @brief Menu container.
 *
 * Holds all the items, runs logic and gets rendered.
 */

/**
 * @defgroup Item
 * @brief Item container.
 *
 * Contains properties for visual representation of item.
 */

/**
 * @addtogroup Library
 * @{ */

/**
 * @name Library Version
 * @{ */

/**
 * Get version of the library in 'major.minor.patch' format.
 *
 * @see @link http://semver.org/ Semantic Versioning @endlink
 *
 * @return Null terminated C "string" to version string.
 */
const char* bmVersion(void);

/**  @} Library Version */

/**  @} Library */

/**
 * @addtogroup Menu
 * @{ */

/**
 * Draw mode constants for bmMenu instance draw mode.
 *
 * @link ::bmDrawMode BM_DRAW_MODE_LAST @endlink is provided for enumerating draw modes.
 * Instancing with it however provides exactly same functionality as BM_DRAW_MODE_NONE.
 */
typedef enum bmDrawMode {
    BM_DRAW_MODE_NONE,
    BM_DRAW_MODE_CURSES,
    BM_DRAW_MODE_LAST
} bmDrawMode;

/**
 * Filter mode constants for bmMenu instance filter mode.
 *
 * @link ::bmFilterMode BM_FILTER_MODE_LAST @endlink is provided for enumerating filter modes.
 * Using it as filter mode however provides exactly same functionality as BM_FILTER_MODE_DMENU.
 */
typedef enum bmFilterMode {
    BM_FILTER_MODE_DMENU,
    BM_FILTER_MODE_DMENU_CASE_INSENSITIVE,
    BM_FILTER_MODE_LAST
} bmFilterMode;

/**
 * Result constants from bmMenuRunWithKey function.
 *
 * - @link ::bmRunResult BM_RUN_RESULT_RUNNING @endlink means that menu is running and thus should be still renderer && ran.
 * - @link ::bmRunResult BM_RUN_RESULT_SELECTED @endlink means that menu was closed and items were selected.
 * - @link ::bmRunResult BM_RUN_RESULT_CANCEL @endlink means that menu was closed and selection was canceled.
 */
typedef enum bmRunResult {
    BM_RUN_RESULT_RUNNING,
    BM_RUN_RESULT_SELECTED,
    BM_RUN_RESULT_CANCEL,
} bmRunResult;

/**
 * Key constants.
 *
 * @link ::bmKey BM_KEY_LAST @endlink is provided for enumerating keys.
 */
typedef enum bmKey {
    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_ESCAPE,
    BM_KEY_RETURN,
    BM_KEY_SHIFT_RETURN,
    BM_KEY_CONTROL_RETURN,
    BM_KEY_UNICODE,
    BM_KEY_LAST
} bmKey;

/**
 * @name Menu Memory
 * @{ */

/**
 * Create new bmMenu instance.
 *
 * @param drawMode Render method to be used for this menu instance.
 * @return bmMenu for new menu instance, **NULL** if creation failed.
 */
bmMenu* bmMenuNew(bmDrawMode drawMode);

/**
 * Release bmMenu instance.
 *
 * @param menu bmMenu instance to be freed from memory.
 */
void bmMenuFree(bmMenu *menu);

/**
 * Release items inside bmMenu instance.
 *
 * @param menu bmMenu instance which items will be freed from memory.
 */
void bmMenuFreeItems(bmMenu *menu);

/**  @} Menu Memory */

/**
 * @name Menu Properties
 * @{ */

/**
 * Set userdata pointer to bmMenu instance.
 * Userdata will be carried unmodified by the instance.
 *
 * @param menu bmMenu instance where to set userdata pointer.
 * @param userdata Pointer to userdata.
 */
void bmMenuSetUserdata(bmMenu *menu, void *userdata);

/**
 * Get userdata pointer from bmMenu instance.
 *
 * @param menu bmMenu instance which userdata pointer to get.
 * @return Pointer for unmodified userdata.
 */
void* bmMenuGetUserdata(bmMenu *menu);

/**
 * Set filter text to bmMenu instance.
 *
 * @param menu bmMenu instance where to set filter.
 * @param filter Null terminated C "string" to act as filter.
 */
void bmMenuSetFilter(bmMenu *menu, const char *filter);

/**
 * Get filter text from  bmMenu instance.
 *
 * @param menu bmMenu instance where to get filter.
 * @return Const pointer to current filter text, may be **NULL** if empty.
 */
const char* bmMenuGetFilter(bmMenu *menu);

/**
 * Set active filter mode to bmMenu instance.
 *
 * @param menu bmMenu instance where to set filter mode.
 * @param mode bmFilterMode constant.
 */
void bmMenuSetFilterMode(bmMenu *menu, bmFilterMode mode);

/**
 * Get active filter mode from bmMenu instance.
 *
 * @param menu bmMenu instance where to get filter mode.
 * @return bmFilterMode constant.
 */
bmFilterMode bmMenuGetFilterMode(const bmMenu *menu);

/**
 * Set selection wrapping on/off.
 *
 * @param menu bmMenu instance where to toggle selection wrapping.
 * @param int 1 == on, 0 == off.
 */
void bmMenuSetWrap(bmMenu *menu, int wrap);

/**
 * Get selection wrapping state.
 *
 * @param menu bmMenu instance where to get selection wrapping state.
 * @return int for wrap state.
 */
int bmMenuGetWrap(const bmMenu *menu);

/**
 * Set title to bmMenu instance.
 *
 * @param menu bmMenu instance where to set title.
 * @param title C "string" to set as title, can be **NULL** for empty title.
 */
int bmMenuSetTitle(bmMenu *menu, const char *title);

/**
 * Get title from bmMenu instance.
 *
 * @param menu bmMenu instance where to get title from.
 * @return Pointer to null terminated C "string", can be **NULL** for empty title.
 */
const char* bmMenuGetTitle(const bmMenu *menu);

/**  @} Properties */

/**
 * @name Menu Items
 * @{ */

/**
 * Add item to bmMenu instance at specific index.
 *
 * @param menu bmMenu instance where item will be added.
 * @param item bmItem instance to add.
 * @param index Index where item will be added.
 * @return 1 on successful add, 0 on failure.
 */
int bmMenuAddItemAt(bmMenu *menu, bmItem *item, unsigned int index);

/**
 * Add item to bmMenu instance.
 *
 * @param menu bmMenu instance where item will be added.
 * @param item bmItem instance to add.
 * @return 1 on successful add, 0 on failure.
 */
int bmMenuAddItem(bmMenu *menu, bmItem *item);

/**
 * Remove item from bmMenu instance at specific index.
 *
 * @warning The item won't be freed, use bmItemFree to do that.
 *
 * @param menu bmMenu instance from where item will be removed.
 * @param index Index of item to remove.
 * @return 1 on successful add, 0 on failure.
 */
int bmMenuRemoveItemAt(bmMenu *menu, unsigned int index);

/**
 * Remove item from bmMenu instance.
 *
 * @warning The item won't be freed, use bmItemFree to do that.
 *
 * @param menu bmMenu instance from where item will be removed.
 * @param item bmItem instance to remove.
 * @return 1 on successful add, 0 on failure.
 */
int bmMenuRemoveItem(bmMenu *menu, bmItem *item);

/**
 * Highlight item in menu by index.
 *
 * @param menu bmMenu instance from where to highlight item.
 * @param index Index of item to highlight.
 * @return 1 on successful highlight, 0 on failure.
 */
int bmMenuSetHighlightedIndex(bmMenu *menu, unsigned int index);

/**
 * Highlight item in menu.
 *
 * @param menu bmMenu instance from where to highlight item.
 * @param item bmItem instance to highlight.
 * @return 1 on successful highlight, 0 on failure.
 */
int bmMenuSetHighlighted(bmMenu *menu, bmItem *item);

/**
 * Get highlighted item from bmMenu instance.
 *
 * @warning The pointer returned by this function may be invalid after items change.
 *
 * @param menu bmMenu instance from where to get highlighted item.
 * @return Selected bmItem instance, **NULL** if none highlighted.
 */
bmItem* bmMenuGetHighlightedItem(const bmMenu *menu);

/**
 * Set selected items to bmMenu instance.
 *
 * @param menu bmMenu instance where items will be set.
 * @param items Array of bmItem pointers to set.
 * @param nmemb Total count of items in array.
 * @return 1 on successful set, 0 on failure.
 */
int bmMenuSetSelectedItems(bmMenu *menu, bmItem **items, unsigned int nmemb);

/**
 * Get selected items from bmMenu instance.
 *
 * @warning The pointer returned by this function may be invalid after selection or items change.
 *
 * @param menu bmMenu instance from where to get selected items.
 * @param outNmemb Reference to unsigned int where total count of returned items will be stored.
 * @return Pointer to array of bmItem pointers.
 */
bmItem** bmMenuGetSelectedItems(const bmMenu *menu, unsigned int *outNmemb);

/**
 * Set items to bmMenu instance.
 * Will replace all the old items on bmMenu instance.
 *
 * If items is **NULL**, or nmemb is zero, all items will be freed from the menu.
 *
 * @param menu bmMenu instance where items will be set.
 * @param items Array of bmItem pointers to set.
 * @param nmemb Total count of items in array.
 * @return 1 on successful set, 0 on failure.
 */
int bmMenuSetItems(bmMenu *menu, const bmItem **items, unsigned int nmemb);

/**
 * Get items from bmMenu instance.
 *
 * @warning The pointer returned by this function may be invalid after removing or adding new items.
 *
 * @param menu bmMenu instance from where to get items.
 * @param outNmemb Reference to unsigned int where total count of returned items will be stored.
 * @return Pointer to array of bmItem pointers.
 */
bmItem** bmMenuGetItems(const bmMenu *menu, unsigned int *outNmemb);

/**
 * Get filtered (displayed) items from bmMenu instance.
 *
 * @warning The pointer returned by this function _will_ be invalid when menu internally filters its list again.
 *          Do not store this pointer.
 *
 * @param menu bmMenu instance from where to get filtered items.
 * @param outNmemb Reference to unsigned int where total count of returned items will be stored.
 * @return Pointer to array of bmItem pointers.
 */
bmItem** bmMenuGetFilteredItems(const bmMenu *menu, unsigned int *outNmemb);

/**  @} Menu Items */

/**
 * @name Menu Logic
 * @{ */

/**
 * Render bmMenu instance using chosen draw method.
 *
 * @param menu bmMenu instance to be rendered.
 */
void bmMenuRender(const bmMenu *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.
 *
 * @param menu bmMenu instance which to filter.
 */
void bmMenuFilter(bmMenu *menu);

/**
 * Poll key and unicode from underlying UI toolkit.
 *
 * This function will block on @link ::bmDrawMode BM_DRAW_MODE_CURSES @endlink draw mode.
 *
 * @param menu bmMenu instance from which to poll.
 * @param outUnicode Reference to unsigned int.
 * @return bmKey for polled key.
 */
bmKey bmMenuGetKey(bmMenu *menu, unsigned int *outUnicode);

/**
 * Advances menu logic with key and unicode as input.
 *
 * @param menu bmMenu instance to be advanced.
 * @param key Key input that will advance menu logic.
 * @param unicode Unicode input that will advance menu logic.
 * @return bmRunResult for menu state.
 */
bmRunResult bmMenuRunWithKey(bmMenu *menu, bmKey key, unsigned int unicode);

/**  @} Menu Logic */

/**  @} Menu */

/**
 * @addtogroup Item
 * @{ */

/**
 * @name Item Memory
 * @{ */

/**
 * Allocate a new item.
 *
 * @param text Pointer to null terminated C "string", can be **NULL** for empty text.
 * @return bmItem for new item instance, **NULL** if creation failed.
 */
bmItem* bmItemNew(const char *text);

/**
 * Release bmItem instance.
 *
 * @param item bmItem instance to be freed from memory.
 */
void bmItemFree(bmItem *item);

/**  @} Item Memory */

/**
 * @name Item Properties
 * @{ */

/**
 * Set userdata pointer to bmItem instance.
 * Userdata will be carried unmodified by the instance.
 *
 * @param item bmItem instance where to set userdata pointer.
 * @param userdata Pointer to userdata.
 */
void bmItemSetUserdata(bmItem *item, void *userdata);

/**
 * Get userdata pointer from bmItem instance.
 *
 * @param item bmItem instance which userdata pointer to get.
 * @return Pointer for unmodified userdata.
 */
void* bmItemGetUserdata(bmItem *item);

/**
 * Set text to bmItem instance.
 *
 * @param item bmItem instance where to set text.
 * @param text C "string" to set as text, can be **NULL** for empty text.
 */
int bmItemSetText(bmItem *item, const char *text);

/**
 * Get text from bmItem instance.
 *
 * @param item bmItem instance where to get text from.
 * @return Pointer to null terminated C "string", can be **NULL** for empty text.
 */
const char* bmItemGetText(const bmItem *item);

/**  @} Item Properties */

/**  @} Item */

/* vim: set ts=8 sw=4 tw=0 :*/