Difference between revisions of "Sgui"

From z64 wiki
Jump to: navigation, search
(Library Description)
(Instance)
 
Line 14: Line 14:
 
On success, returns a pointer which you should use only as an argument to other sgui functions/macros. On failure, returns <tt>NULL</tt>, and in the case of a SDL or TTF initialization failure, <br><br>
 
On success, returns a pointer which you should use only as an argument to other sgui functions/macros. On failure, returns <tt>NULL</tt>, and in the case of a SDL or TTF initialization failure, <br><br>
 
Once your window is set up, the gui is run by calling <tt>sgui_run</tt><br>
 
Once your window is set up, the gui is run by calling <tt>sgui_run</tt><br>
&nbsp;&nbsp;<tt>sgui_status</tt> sgui_run( SHandle *s)</tt>
+
&nbsp;&nbsp;<tt>sgui_status sgui_run( SHandle *s)</tt><br>
 
&nbsp;&nbsp;&nbsp;&nbsp;<tt>s</tt> is the instance of sgui you want to run.<br>
 
&nbsp;&nbsp;&nbsp;&nbsp;<tt>s</tt> is the instance of sgui you want to run.<br>
 
Returns a variable of type <tt>[[sgui#sgui_status|sgui_status]]</tt> to indicate how things went.<br><br>
 
Returns a variable of type <tt>[[sgui#sgui_status|sgui_status]]</tt> to indicate how things went.<br><br>
Line 20: Line 20:
 
&nbsp;&nbsp;<tt>void sgui_destroy_handle( SHandle *s )</tt><br>
 
&nbsp;&nbsp;<tt>void sgui_destroy_handle( SHandle *s )</tt><br>
 
&nbsp;&nbsp;&nbsp;&nbsp;<tt>s</tt> is the SHandle you wish to destroy.<br><br>
 
&nbsp;&nbsp;&nbsp;&nbsp;<tt>s</tt> is the SHandle you wish to destroy.<br><br>
 +
 
===Data Types===
 
===Data Types===
 
To make some sgui elements work, there are a few data types introduced with sgui.
 
To make some sgui elements work, there are a few data types introduced with sgui.

Latest revision as of 00:28, 28 May 2013

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

Prequisites

C99 or better, SDL, SDL-ttf, freetype2

Library Description

Include sgui.h

Instance

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)
    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.

SList

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];
}
SList;

  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;
    union
    {
        void *udata;
        int value;
    };
    void *__sgui_private_ptr;
}
SListValue;

  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.

SObjectProperties

sgui_properties

Fonts

Elements

sgui_button

sgui_textbox

sgui_checkbox

sgui_list

sgui_listbox

sgui_label

sgui_pixelfield