JustUI/include/justui/jlist.h

103 lines
3.1 KiB
C
Raw Normal View History

//---
// JustUI.jlist: List widget with arbitrary, selectable children
//---
#ifndef _J_JLIST
#define _J_JLIST
#include <justui/defs.h>
#include <justui/jwidget.h>
typedef enum {
/* Selected item is indicated by inverting its rendered area */
JLIST_SELECTION_INVERT = 0,
/* Selected item is indicated by applying a background color */
JLIST_SELECTION_BACKGROUND = 1,
} jlist_selection_style;
typedef struct {
/* Delegate widget */
jwidget *delegate;
/* Whether item can be selected */
bool selectable;
/* Whether item can be triggered */
bool triggerable;
/* The following fields are only applicable if there is no delegate. */
/* Item's natural with and height, in pixels */
int16_t natural_width, natural_height;
} jlist_item_info;
struct jlist;
typedef void (*jlist_item_info_function)(struct jlist *list, int index,
jlist_item_info *info);
typedef void (*jlist_item_paint_function)(int x, int y, int w, int h,
struct jlist *list, int index, bool selected);
/* jlist: List widget with arbitrary, selectable children
This widget is used to make lists of selectable elements. The elements are
backed by a model which is essentially associating an index in the list to
some piece of user data.
Elements can either be manually-rendered like jpainted, or be delegated to
full widgets (eg. for editing in a list).
In terms of layout, jlist is a raw vertical list of all of its items, with
no spacing. Generally it is desirable to put it in a jframe to make it
scroll; otherwise, it has rather unpredictable dimensions. */
typedef struct jlist {
jwidget widget;
/* Number of items */
int item_count;
/* Per-widget information */
jlist_item_info *items;
/* Item information and paint functions */
jlist_item_info_function info_function;
jlist_item_paint_function paint_function;
/* Currently selected item, -1 if none */
int cursor;
} jlist;
/* Events */
extern uint16_t JLIST_ITEM_TRIGGERED;
extern uint16_t JLIST_SELECTION_MOVED;
extern uint16_t JLIST_MODEL_UPDATED;
/* jlist_create(): Create a new (empty) jlist. */
jlist *jlist_create(void *parent, jlist_item_info_function info_function,
jlist_item_paint_function paint_function);
/* jlist_update_model(): Update jlists's information about the model
The new model size is passed as parameter. The model is refreshed by
repeatedly calling the info function. */
void jlist_update_model(jlist *l, int item_count);
/* jlist_clear(): Remove all items */
void jlist_clear(jlist *l);
/* jlist_select(): Move selection to a selectable item */
void jlist_select(jlist *l, int item);
/* jlist_selected_item(): Get currently selected item (-1 if none) */
int jlist_selected_item(jlist *l);
/* jlist_selected_region(): Get the currently selected region of the widget
The region is returned as a jrect within the widget's coordinates. This is
useful when the list is inside a frame, to scroll the frame to a suitable
position after the list's selection moved. See jscrolledlist.
The returned region is undefined if there is no selected item. */
jrect jlist_selected_region(jlist *l);
#endif /* _J_JLIST */