From z64 wiki
Revision as of 00:23, 28 May 2013 by Spinout (talk | contribs) (Library Description)
Jump to: navigation, search

sgui is a tiny library that aims to be a lightweight, simple, and easy to use graphical library, written in and for the C programming language. It is yet to be implemented in anything other than the demo application included with the library. TODO: infobox program etc


C99 or better, SDL, SDL-ttf, freetype2

Library Description

Include sgui.h


An sgui window and all it's glory are held in an sgui instance, a private structure of type SHandle. A SHandle is created by calling the function sgui_new_handle.
  SHandle* sgui_new_handle( int width, int height, char *window_title, char *window_icontitle );
    width is the desired width of the window, in pixels.
    height is the desired height of the window, in pixels.
    window_title is the title of the window.
    window_icontitle is the name which displays in the task bar/window list. Ignored on some operating systems.
On success, returns a pointer which you should use only as an argument to other sgui functions/macros. On failure, returns NULL, and in the case of a SDL or TTF initialization failure,

Once your window is set up, the gui is run by calling sgui_run
  sgui_status sgui_run( SHandle *s)</tt>     s is the instance of sgui you want to run.
Returns a variable of type sgui_status to indicate how things went.

A SHandle instance is destroyed by calling sgui_destroy_handle
This cleans up all memory that's been allocated for this SHandle instance. This function will only fail if given a pointer to something other than a SHandle.
  void sgui_destroy_handle( SHandle *s )
    s is the SHandle you wish to destroy.

Data Types

To make some sgui elements work, there are a few data types introduced with sgui.


A SList is a special kind of list. It is a variable-length "structlist":

typedef struct
    int len;
    int selected;
    unsigned flags;
    void *udata;
    SListValue stuff[1];

  len is the length of the list.
  selected is which element is currently selected. A negative value indicates no current selection.
  flags is a set of flags that defines what the list is. Currently, possible values are SLIST_SLIST and SLIST_STRING. These can be bitwise-or'd together, however, current elements only support 1-dimensional lists, meaning SLIST_SLIST is ignored.
  stuff is the list itself. Each element is:

typedef struct
    char *str;
    void *sub_list;
        void *udata;
        int value;
    void *__sgui_private_ptr;

  str is the element, as represented by a string. If this list is to be in a sgui_list or sgui_listbox, this string will be rendered in the list.
  sub_list is a pointer to another SList. This is currently ignored by all parts of sgui, however is planned for multi-dimensional/multidepth lists for use in (planned) treeview and grid elements.
  udata is a pointer of your liking, to whatever you choose. If you use udata do not use value. Although this element is in a union inside of a structure, it is an anonymous union and therefore the element can be accessed as so: example_slist.stuff[example_element].udata = ...
  value is an alternate to udata, and can be an integer of your liking.
  __sgui_private_ptr is used internally by sgui. Modification of this value results in undefined behavior.