USING: kernel system combinators alien alien.destructors alien.libraries alien.syntax alien.c-types ;
IN: bemenu.ffi

<< "bemenu" {
    { [ os unix? ] [ "libbemenu.so" ] }
} cond cdecl add-library >>

LIBRARY: bemenu

C-TYPE: bm_renderer
C-TYPE: bm_menu
C-TYPE: bm_item

! Init bemenu, loads up the renderers.
!
! You can force single renderer with BEMENU_RENDERER env variable,
! and directory containing renderers with BEMENU_RENDERERS env variable.
!
! @return true on success, false on failure.
FUNCTION-ALIAS: bemenu-init bool bm_init ( )

<PRIVATE
! Get list of available renderers.
!
! @param out_nmemb Reference to uint32_t where total count of returned renderers will be stored.
! @return Pointer to array of bm_renderer instances.
FUNCTION: bm_renderer** bm_get_renderers ( uint32_t *out_nmemb )

PRIVATE>

! 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.
FUNCTION-ALIAS: bemenu-version c-string bm_version ( )

<PRIVATE

ENUM: bm_priorty
    ! renderer runs in terminal
    BM_PRIO_TERMINAL
    ! renderer runs in GUI
    BM_PRIO_GUI ;


! Get name of the renderer.
!
! @param renderer bm_renderer instance.
! @return Null terminated C "string" to renderer's name.
FUNCTION: c-string bm_renderer_get_name ( bm_renderer* renderer )

! Get priorty of the renderer.
!
! @param renderer bm_renderer instance.
! @return bm_priorty enum value.
FUNCTION: bm_priorty bm_renderer_get_priorty ( bm_renderer* renderer )

PRIVATE>

ALIAS: bm-priorty bm_priorty

ENUM: bm_filter_mode
    BM_FILTER_MODE_DMENU
    BM_FILTER_MODE_DMENU_CASE_INSENSITIVE
    BM_FILTER_MODE_DMENU_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
    BM_RUN_RESULT_CUSTOM_1
    BM_RUN_RESULT_CUSTOM_2
    BM_RUN_RESULT_CUSTOM_3
    BM_RUN_RESULT_CUSTOM_4
    BM_RUN_RESULT_CUSTOM_5
    BM_RUN_RESULT_CUSTOM_6
    BM_RUN_RESULT_CUSTOM_7
    BM_RUN_RESULT_CUSTOM_8
    BM_RUN_RESULT_CUSTOM_9
    BM_RUN_RESULT_CUSTOM_10 ;

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_CUSTOM_1
    BM_KEY_CUSTOM_2
    BM_KEY_CUSTOM_3
    BM_KEY_CUSTOM_4
    BM_KEY_CUSTOM_5
    BM_KEY_CUSTOM_6
    BM_KEY_CUSTOM_7
    BM_KEY_CUSTOM_8
    BM_KEY_CUSTOM_9
    BM_KEY_CUSTOM_10
    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 ;

FUNCTION: bm_menu* bm_menu_new ( c-string renderer )
FUNCTION: void bm_menu_free ( bm_menu* menu )

DESTRUCTOR: bm_menu_free

FUNCTION: void bm_menu_free_items ( bm_menu* menu )

FUNCTION: bm_renderer* bm_menu_get_renderer ( bm_menu *menu )

! Set userdata pointer to bm_menu instance.
! Userdata will be carried unmodified by the instance.
!
! @param menu bm_menu instance where to set userdata pointer.
! @param userdata Pointer to userdata.
FUNCTION: void bm_menu_set_userdata ( bm_menu *menu, void *userdata )

! Get userdata pointer from bm_menu instance.
!
! @param menu bm_menu instance which userdata pointer to get.
! @return Pointer for unmodified userdata.
FUNCTION: void bm_menu_get_userdata ( bm_menu *menu )

! Set highlight prefix.
! This is shown on vertical list mode only.
!
! @param menu bm_menu instance where to set highlight prefix.
! @param prefix "string" to act as prefix for highlighted item. May be set f for none.
FUNCTION: void bm_menu_set_prefix ( bm_menu *menu, c-string prefix )

! Get highlight prefix.
!
! @param menu bm_menu instance where to get highlight prefix.
! @param Const pointer to current highlight prefix, may be f if empty.
FUNCTION: c-string bm_menu_get_prefix ( bm_menu *menu )

! Set filter text to bm_menu instance.
!
! The cursor will be automatically placed at the end of the new filter text.
!
! @param menu bm_menu instance where to set filter.
! @param filter Null terminated C "string" to act as filter. May be set **NULL** for none.
FUNCTION: void bm_menu_set_filter ( bm_menu *menu, c-string *filter )


! Get filter text from bm_menu instance.
!
! @param menu bm_menu instance where to get filter.
! @return Const pointer to current filter text, may be **NULL** if empty.
FUNCTION: c-string bm_menu_get_filter ( bm_menu *menu )


! Set active filter mode to bm_menu instance.
!
! @param menu bm_menu instance where to set filter mode.
! @param mode bm_filter_mode constant.
FUNCTION: void bm_menu_set_filter_mode ( bm_menu *menu, bm_filter_mode mode )


! Get active filter mode from bm_menu instance.
!
! @param menu bm_menu instance where to get filter mode.
! @return bm_filter_mode constant.
FUNCTION: bm_filter_mode bm_menu_get_filter_mode ( bm_menu *menu )


! Set amount of max vertical lines to be shown.
! Some renderers such as ncurses may ignore this when it does not make sense.
!
! @param menu bm_menu instance where to set max vertical line amount.
! @param lines 0 for single line layout, > 0 to show that many lines.
FUNCTION: void bm_menu_set_lines ( bm_menu *menu, uint32_t lines )


! Get amount of max vertical lines to be shown.
!
! @param menu bm_menu instance where to get max vertical line amount.
! @return uint32_t for max amount of vertical lines to be shown.
FUNCTION: uint32_t bm_menu_get_lines ( bm_menu *menu )


! Set selection wrapping on/off.
!
! @param menu bm_menu instance where to toggle selection wrapping.
! @param wrap true/false.
FUNCTION: void bm_menu_set_wrap ( bm_menu *menu, bool wrap )


! Get selection wrapping state.
!
! @param menu bm_menu instance where to get selection wrapping state.
! @return int for wrap state.
FUNCTION: bool bm_menu_get_wrap ( bm_menu *menu )


! Set title to bm_menu instance.
!
! @param menu bm_menu instance where to set title.
! @param title C "string" to set as title, can be **NULL** for empty title.
! @return true if set was succesful, false if out of memory.
FUNCTION: bool bm_menu_set_title ( bm_menu *menu, c-string title )


! Get title from bm_menu instance.
!
! @param menu bm_menu instance where to get title from.
! @return Pointer to null terminated C "string", can be **NULL** for empty title.
FUNCTION: c-string bm_menu_get_title ( bm_menu *menu )


! Set font description to bm_menu instance.
!
! @param menu bm_menu instance where to set font.
! @param font C "string" for a **pango style font description**, can be **NULL** for default (Terminus 9).
! @return true if set was succesful, false if out of memory.
FUNCTION: bool bm_menu_set_font ( bm_menu *menu, c-string font )


! Get font description from bm_menu instance.
!
! @param menu bm_menu instance where to get font description from.
! @return Pointer to null terminated C "string".
FUNCTION: c-string bm_menu_get_font ( bm_menu *menu )


! Set size of line in pixels.
! Some renderers such as ncurses may ignore this when it does not make sense.
!
! @param menu bm_menu instance where to set line height.
! @param line_height 0 for default line height, > 0 for that many pixels.
FUNCTION: void bm_menu_set_line_height ( bm_menu *menu, uint32_t line_height )


! Get size of line in pixels.
!
! @param menu bm_menu instance where to get line height.
! @return uint32_t for max amount of vertical lines to be shown.
FUNCTION: uint32_t bm_menu_get_line_height ( bm_menu *menu )


! Set a hexadecimal color for element.
!
! @param menu bm_menu instance where to set color.
! @param color bm_color type.
! @param hex Color in hexadecimal format starting with '#'.
! @return true if set was succesful, false if out of memory.
FUNCTION: bool bm_menu_set_color ( bm_menu *menu, bm_color color, c-string hex )


! Get hexadecimal color for element.
!
! @param menu bm_menu instance where to get color from.
! @param color bm_color type.
! @return Pointer to null terminated C "string".
FUNCTION: c-string bm_menu_get_color ( bm_menu *menu, bm_color color )


! Set scrollbar display mode.
!
! @param menu bm_menu instance to set scrollbar for.
! @param mode bm_scrollbar_mode constant.
FUNCTION: void bm_menu_set_scrollbar ( bm_menu *menu, bm_scrollbar_mode mode )


! Return current scrollbar display mode.
!
! @param menu bm_menu instance where to get scrollbar display state from.
! @return bm_scrollbar_mode constant.
FUNCTION: bm_scrollbar_mode bm_menu_get_scrollbar ( bm_menu *menu )


! Display menu at bottom of the screen.
! This may be no-op on some renderers (curses, wayland)
!
! @param menu bm_menu instance to set bottom mode for.
! @param bottom true for bottom mode, false for top mode.
FUNCTION: void bm_menu_set_bottom ( bm_menu *menu, bool bottom )


! Is menu being displayed at bottom of the screen?
!
! @param menu bm_menu instance where to get bottom mode from.
! @return true if bottom mode, false otherwise.
FUNCTION: bool bm_menu_get_bottom ( bm_menu *menu )


! Display menu at monitor index.
! Indices start at 0, a value of -1 can be passed for the active monitor (default).
! If index is more than amount of monitors, the monitor with highest index will be selected.
!
! @param menu bm_menu instance to set monitor for.
! @param monitor Monitor index starting from 0, or -1 for the active monitor.
FUNCTION: void bm_menu_set_monitor ( bm_menu *menu, int32_t monitor )


! Display menu with monitor_name.
! Only works for Wayland.
!
! @param menu bm_menu instance to set monitor for.
! @param monitor_name Monitor name passed in.
FUNCTION: void bm_menu_set_monitor_name ( bm_menu *menu, c-string monitor_name )


! Return index for current monitor.
!
! @param menu bm_menu instance where to get current monitor from.
! @return Monitor index starting from 1.
FUNCTION: uint32_t bm_menu_get_monitor ( bm_menu *menu )


! Tell renderer to grab keyboard.
! This only works with x11 renderer.
!
! @param menu bm_menu instance to set grab for.
! @param grab true for grab, false for ungrab.
FUNCTION: void bm_menu_grab_keyboard ( bm_menu *menu, bool grab )


! Is keyboard grabbed for bm_menu?
!
! @param menu bm_menu instance where to check grab status from.
! @return true if grabbed, false if not.
FUNCTION: bool bm_menu_is_keyboard_grabbed ( bm_menu *menu )


! Tell the renderer to position the menu that it can overlap panels.
FUNCTION: void bm_menu_set_panel_overlap ( bm_menu *menu, bool overlap )


! Replace input with asterisks.
!
! @param menu bm_menu instance to set password mode for.
! @param password true for password mode, false for deafault behavior.
FUNCTION: void bm_menu_set_password ( bm_menu *menu, bool password )


! Is password mode activated and input hidden?
!
! @param menu bm_menu instance where to get password mode from.
! @return true if password mode, false otherwise.
FUNCTION: bool bm_menu_get_password ( bm_menu *menu )


! Properties

! @name Menu Items


! Add item to bm_menu instance at specific index.
!
! @param menu bm_menu instance where item will be added.
! @param item bm_item instance to add.
! @param index Index where item will be added.
! @return true on successful add, false on failure.
FUNCTION: bool bm_menu_add_item_at ( bm_menu *menu, bm_item *item, uint32_t index )


! Add item to bm_menu instance.
!
! @param menu bm_menu instance where item will be added.
! @param item bm_item instance to add.
! @return true on successful add, false on failure.
FUNCTION: bool bm_menu_add_item ( bm_menu *menu, bm_item *item )


! Remove item from bm_menu instance at specific index.
!
! @warning The item won't be freed, use bm_item_free to do that.
!
! @param menu bm_menu instance from where item will be removed.
! @param index Index of item to remove.
! @return true on successful add, false on failure.
FUNCTION: bool bm_menu_remove_item_at ( bm_menu *menu, uint32_t index )

! Remove item from bm_menu instance.
!
! @warning The item won't be freed, use bm_item_free to do that.
!
! @param menu bm_menu instance from where item will be removed.
! @param item bm_item instance to remove.
! @return true on successful add, false on failure.
FUNCTION: bool bm_menu_remove_item ( bm_menu *menu, bm_item *item )

! Highlight item in menu by index.
!
! @param menu bm_menu instance from where to highlight item.
! @param index Index of item to highlight.
! @return true on successful highlight, false on failure.
FUNCTION: bool bm_menu_set_highlighted_index ( bm_menu *menu, uint32_t index )

! Highlight item in menu.
!
! @param menu bm_menu instance from where to highlight item.
! @param item bm_item instance to highlight.
! @return true on successful highlight, false on failure.
FUNCTION: bool bm_menu_set_highlighted_item ( bm_menu *menu, bm_item *item )

! Get highlighted item from bm_menu instance.
!
! @warning The pointer returned by this function may be invalid after items change.
!
! @param menu bm_menu instance from where to get highlighted item.
! @return Selected bm_item instance, **NULL** if none highlighted.
FUNCTION: bm_item* bm_menu_get_highlighted_item ( bm_menu *menu )

! Set selected items to bm_menu instance.
!
! @param menu bm_menu instance where items will be set.
! @param items Array of bm_item pointers to set.
! @param nmemb Total count of items in array.
! @return true on successful set, false on failure.
FUNCTION: bool bm_menu_set_selected_items ( bm_menu *menu, bm_item **items, uint32_t nmemb )

! Get selected items from bm_menu instance.
!
! @warning The pointer returned by this function may be invalid after selection or items change.
!
! @param menu bm_menu instance from where to get selected items.
! @param out_nmemb Reference to uint32_t where total count of returned items will be stored.
! @return Pointer to array of bm_item pointers.
FUNCTION: bm_item** bm_menu_get_selected_items ( bm_menu *menu, uint32_t *out_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.
!
! @param menu bm_menu instance where items will be set.
! @param items Array of bm_item pointers to set.
! @param nmemb Total count of items in array.
! @return true on successful set, false on failure.
FUNCTION: bool bm_menu_set_items ( bm_menu *menu, bm_item **items, uint32_t nmemb )

! Get items from bm_menu instance.
!
! @warning The pointer returned by this function may be invalid after removing or adding new items.
!
! @param menu bm_menu instance from where to get items.
! @param out_nmemb Reference to uint32_t where total count of returned items will be stored.
! @return Pointer to array of bm_item pointers.
FUNCTION: bm_item** bm_menu_get_items ( 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.
!
! @param menu bm_menu instance from where to get filtered items.
! @param out_nmemb Reference to uint32_t where total count of returned items will be stored.
! @return Pointer to array of bm_item pointers.
FUNCTION: bm_item** bm_menu_get_filtered_items ( bm_menu *menu, uint32_t *out_nmemb )

! Menu Items

! @name Menu Logic

! Render bm_menu instance using chosen renderer.
!
! This function may block on **wayland** and **x11** renderer.
!
! @param menu bm_menu instance to be rendered.
FUNCTION: void bm_menu_render ( 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.
!
! @param menu bm_menu instance which to filter.
FUNCTION: void bm_menu_filter ( bm_menu *menu )


! Poll key and unicode from underlying UI toolkit.
!
! This function will block on **curses** renderer.
!
! @param menu bm_menu instance from which to poll.
! @param out_unicode Reference to uint32_t.
! @return bm_key for polled key.
FUNCTION: bm_key bm_menu_poll_key ( bm_menu *menu, uint32_t *out_unicode )

! Advances menu logic with key and unicode as input.
!
! @param menu bm_menu instance to be advanced.
! @param key Key input that will advance menu logic.
! @param unicode Unicode input that will advance menu logic.
! @return bm_run_result for menu state.
FUNCTION: bm_run_result bm_menu_run_with_key ( bm_menu *menu, bm_key key, uint32_t 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 bm_item for new item instance, **NULL** if creation failed.
FUNCTION: bm_item* bm_item_new ( c-string *text )


! Release bm_item instance.
!
! @param item bm_item instance to be freed from memory.
FUNCTION: void bm_item_free ( bm_item *item )

! Item Memory */

! @name Item Properties

! Set userdata pointer to bm_item instance.
! Userdata will be carried unmodified by the instance.
!
! @param item bm_item instance where to set userdata pointer.
! @param userdata Pointer to userdata.
FUNCTION: void bm_item_set_userdata ( bm_item *item, void *userdata )

! Get userdata pointer from bm_item instance.
!
! @param item bm_item instance which userdata pointer to get.
! @return Pointer for unmodified userdata.
FUNCTION: void* bm_item_get_userdata ( bm_item *item )

! Set text to bm_item instance.
!
! @param item bm_item instance where to set text.
! @param text C "string" to set as text, can be **NULL** for empty text.
! @return true if set was succesful, false if out of memory.
FUNCTION: bool bm_item_set_text ( bm_item *item, c-string text )

! Get text from bm_item instance.
!
! @param item bm_item instance where to get text from.
! @return Pointer to null terminated C "string", can be **NULL** for empty text.
FUNCTION: c-string bm_item_get_text ( bm_item *item )