API Index

• void convey_app_display ( cvyappwindow )
• cvylayout convey_app_get_layout ( cvyappwindow )
• cvyappwindow convey_app_new ( int*, char**, const char*, unsigned, unsigned )
• cvywidget convey_button_new ( cvylayout, convey_callback_func, cvydata, const char* )
• cvywidget convey_checkbox_new ( cvylayout, convey_callback_func, cvydata, const char* )
• void convey_combobox_add ( cvywidget, const char* )
• void convey_combobox_clear ( cvywidget )
• cvywidget convey_combobox_new ( cvylayout, convey_callback_func, cvydata, const char* )
• void convey_filedialog_display ( cvywidget, convey_callback_func, cvydata )
• cvywidget convey_label_new ( cvylayout, const char* )
• void convey_label_set ( cvywidget, const char* )
• cvylayout convey_layout_new ( cvylayout, unsigned char )
• void convey_listbox_add ( cvywidget, const char* )
• void convey_listbox_clear ( cvywidget )
• cvywidget convey_listbox_new ( cvylayout, convey_callback_func, cvydata, const char*, unsigned )
• cvywidget convey_opendialog_new ( cvyappwindow, const char*, const char* )
• void convey_popup_display ( cvywidget, const char* )
• void convey_progressbar_adjust ( cvywidget, int )
• void convey_progressbar_new ( cvylayout )
• cvywidget convey_radiogroup_new ( cvylayout, convey_callback_func, cvydata, unsigned char, ... )
• cvywidget convey_savedialog_new ( cvyappwindow, const char*, const char* )
• char* convey_textfield_get ( cvywidget )
• void convey_textfield_new ( cvylayout, const char* )
• void convey_widget_remove ( cvywidget )

Functions

convey_app_new

The main convey initialisation function. This should be called before any other convey functions.

Arguments
int* argc	Pointer the argc argument from the program's main function.
const char** argv	The argv argument from the program's main function.
const char* title	The program's window title.
unsigned width	The desired width of the main window.
unsigned height	The desired height of the main window.
Returns
cvyappwindow	The newly created application window.

convey_app_display

Starts the main application loop. This should be the last convey function called when initialising, after creating the initial interface elements.

Arguments
cvyappwindow application	The handle returned from convey_app_new.
Returns
void

convey_app_get_layout

Returns the default layout associated with the main application window.

Arguments
cvyappwindow application	The handle returned from convey_app_new.
Returns
cvylayout	The layout associated with the application window.

convey_layout_new

Creates a linear layout widget that positions any child widgets in either a vertical or horizontal array. Can be nested to allow for fairly complex layouts.

Arguments
cvylayout parent	The layout which this layout will be created within.
unsigned char vertical	A boolean value specifying the direction of the layout. True for a vertical layout, false for horizontal.
Returns
cvylayout	The newly created layout.

convey_label_new

Creates a text label.

Arguments
cvylayout parent	The layout which this widget will be created within.
const char* text	The text of the label.
Returns
cvywidget	The newly created widget.

convey_button_new

Creates a text push button.

Arguments
cvylayout parent	The layout which this widget will be created within.
convey_callback_func callback_function	A function to be called when the button is pressed.
cvydata user_data	Application specific data to pass to the callback function.
const char* text	The text of the button.
Returns
cvywidget	The newly created widget.

convey_radiogroup_new

Creates a mutually-exclusive group of radio buttons.

Arguments
cvylayout parent	The layout which this widget will be created within.
convey_callback_func callback_function	A function to be called when one of the radio buttons is selected. The third argument to the callback will contain the label of the radio button selected.
cvydata user_data	Application specific data to pass to the callback function.
unsigned char vertical	A boolean value specifying the direction of the layout. True for a vertical layout, false for horizontal.
...	Variable length list of const strings giving the labels for each radio button. The last argument in the list should be a NULL pointer.
Returns
cvywidget	The newly created widget.

convey_checkbox_new

Creates a checkbox with a text label.

Arguments
cvylayout parent	The layout which this widget will be created within.
convey_callback_func callback_function	A function to be called when the checkbox is selected.
cvydata user_data	Application specific data to pass to the callback function.
const char* text	The text for the checkbox label.
Returns
cvywidget	The newly created widget.

convey_progressbar_new

Creates a graphical bar that can be updated to show the progress of a task or tasks. It is set to display a percentage, from 0 - 100.

Arguments
cvylayout parent	The layout which this widget will be created within.
Returns
cvywidget	The newly created widget.

convey_listbox_new

Creates a single-column text listbox.

Arguments
cvylayout parent	The layout which this widget will be created within.
convey_callback_func callback_function	A function to be called when one of the list elements is selected. The third argument to the callback function will contain the text of the selected element.
cvydata user_data	Application specific data to pass to the callback function.
const char* title	The text to use as the heading of the listbox.
unsigned size	The visible size of the listbox. It can contain more, but only this number will be visible at any one time.
Returns
cvywidget	The newly created widget.

convey_combobox_new

Creates a single-line text box that can display a list of options to pick from.

Arguments
cvylayout parent	The layout which this widget will be created within.
convey_callback_func callback_function	A function to be called when one of the list elements is selected. The third argument to the callback function will contain the text of the selected element.
cvydata user_data	Application specific data to pass to the callback function.
const char* title	The text to use as the heading of the combobox.
Returns
cvywidget	The newly created widget.

convey_textfield_new

Creates a single-line text box that the user can type input into. The entered text can be retrieved with convey_textfield_get. This will also create a text label next to the input box to describe the contents.

Arguments
cvylayout parent	The layout which this widget will be created within.
const char* title	The text to use for the label.
Returns
cvywidget	The newly created widget.

convey_opendialog_new

Creates a file-selection dialog box for opening an existing file. Use convey_filedialog_display to actually show the dialog.

Arguments
cvywidget parent	The parent for this widget - usually a layout widget.
const char* message	A message describing the purpose of the dialog box to the user.
const char* path	The directory the dialog starts in.
Returns
cvywidget	The newly created widget.

convey_savedialog_new

Creates a file-selection dialog box for saving a new file. Use convey_filedialog_display to actually show the dialog.

Arguments
cvywidget parent	The parent for this widget - usually a layout widget.
const char* message	A message describing the purpose of the dialog box to the user.
const char* path	The directory the dialog starts in.
Returns
cvywidget	The newly created widget.

convey_filedialog_display

Displays a file selection dialog widget that had been created previously.

Arguments
cvywidget dialog	The file dialog widget to display.
convey_callback_func callback_function	A function to be called when a file has been chosen. The third argument to the callback function will contain the path and filename of the selected file.
cvydata user_data	Application specific data to pass to the callback function.
Returns
void

convey_popup_display

Displays a simple messagebox with a message and an okay button.

Arguments
cvywidget window	The main application widget that this dialog is associated with.
const char* message	The message to show on the popup dialog.
Returns
void

convey_widget_remove

Undisplays and destroys an existing widget.

Arguments
cvywidget widget	The widget to destroy.
Returns
void

convey_listbox_add

Adds a list item to an already created listbox.

Arguments
cvywidget listbox	The listbox widget to add the item to.
const char* item	The item to add.
Returns
void

convey_listbox_clear

Removes all items from an existing listbox widget.

Arguments
cvywidget listbox	The listbox widget to empty.
Returns
void

convey_combobox_add

Adds an item to an already created combobox.

Arguments
cvywidget combobox	The combobox widget to add the item to.
const char* item	The item to add.
Returns
void

convey_combobox_clear

Removes all items from an existing combobox widget.

Arguments
cvywidget listbox	The combobox widget to empty.
Returns
void

convey_label_set

Changes the text of an existing label widget.

Arguments
cvywidget label	The label widget to change the text of.
const char* text	The new text for the label.
Returns
void

convey_progressbar_adjust

Increments a progress bar display.

Arguments
cvywidget progressbar	The progressbar widget to advance.
int delta	The amount to adjust the progress bar by, in percent of the total.
Returns
void

convey_textfield_get

Retrieves the currently entered text from a textfield.

Arguments
cvywidget textfield	The textfield to retrieve the text from.
Returns
char*	The current text in the textfield, or an empty string if there is no text in the input area.

Types

Pointer to the main application (or dialog) window. Will have an associated cvywidget that references the actual display element; this can be fetched with convey_app_get_widget.

Pointer to a widget in whatever underlying display library is being used. The main data structure that libconvey manipulates.

A container used to arrange other widgets in a linear array, either vertically or horizontally. All widgets must be assigned to a valid layout when created.

Pointer to generic data often used by the underlying windowing functions, especially by callbacks.

The function prototype for functions receiving events from interactive widgets. It returns void, and takes three arguments:

cvywidget from

The widget that triggered the event.

cvydata client_data

User-defined data associated with the callback.

cvydata call_data

Data associated with the event, eg. the selected element from a listbox.