Difference between revisions of "Sgui"

From z64 wiki
Jump to: navigation, search
(skeleton for sgui documentation page)
 
(Library Description)
Line 1: Line 1:
 
{{lowercase title}}
 
{{lowercase title}}
 
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
 
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==
 
==Library Description==
 +
Include sgui.h
 
===Instance===
 
===Instance===
 +
An sgui window and all it's glory are held in an sgui instance, a private structure of type <tt>SHandle</tt>. A <tt>SHandle</tt> is created by calling the function <tt>sgui_new_handle</tt>.<br>
 +
&nbsp;&nbsp;<tt>SHandle* sgui_new_handle( int width, int height, char *window_title, char *window_icontitle );</tt><br>
 +
&nbsp;&nbsp;&nbsp;&nbsp;<tt>width</tt> is the desired width of the window, in pixels.<br>
 +
&nbsp;&nbsp;&nbsp;&nbsp;<tt>height</tt> is the desired height of the window, in pixels.<br>
 +
&nbsp;&nbsp;&nbsp;&nbsp;<tt>window_title</tt> is the title of the window.<br>
 +
&nbsp;&nbsp;&nbsp;&nbsp;<tt>window_icontitle</tt> is the name which displays in the task bar/window list. Ignored on some operating systems.<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>
 +
&nbsp;&nbsp;<tt>sgui_status</tt> sgui_run( SHandle *s)</tt>
 +
&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>
 +
A SHandle instance is destroyed by calling <tt>sgui_destroy_handle</tt><br> This cleans up all memory that's been allocated for this <tt>SHandle</tt> instance. This function will only fail if given a pointer to something other than a <tt>SHandle</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>
 
===Data Types===
 
===Data Types===
 +
To make some sgui elements work, there are a few data types introduced with sgui.
 
====SList====
 
====SList====
 +
A <tt>SList</tt> is a special kind of list. It is a variable-length "structlist":
 +
<pre>typedef struct
 +
{
 +
    int len;
 +
    int selected;
 +
    unsigned flags;
 +
    void *udata;
 +
    SListValue stuff[1];
 +
}
 +
SList;</pre>
 +
&nbsp;&nbsp;<tt>len</tt> is the length of the list.
 +
&nbsp;&nbsp;<tt>selected</tt> is which element is currently selected. A negative value indicates no current selection.
 +
&nbsp;&nbsp;<tt>flags</tt> is a set of flags that defines what the list is. Currently, possible values are <tt>SLIST_SLIST</tt> and <tt>SLIST_STRING</tt>. These can be bitwise-or'd together, however, current elements only support 1-dimensional lists, meaning SLIST_SLIST is ignored.
 +
&nbsp;&nbsp;<tt>stuff</tt> is the list itself. Each element is:
 +
<pre>typedef struct
 +
{
 +
    char *str;
 +
    void *sub_list;
 +
    union
 +
    {
 +
        void *udata;
 +
        int value;
 +
    };
 +
    void *__sgui_private_ptr;
 +
}
 +
SListValue;</pre><br>
 +
&nbsp;&nbsp;<tt>str</tt> is the element, as represented by a string. If this list is to be in a <tt>[[sgui#sgui_list|sgui_list]]</tt> or <tt>[[sgui#sgui_listbox|sgui_listbox]]</tt>, this string will be rendered in the list.<br>
 +
&nbsp;&nbsp;<tt>sub_list</tt> is a pointer to another <tt>SList</tt>. 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.
 +
&nbsp;&nbsp;<tt>udata</tt> is a pointer of your liking, to whatever you choose. '''If you use <tt>udata</tt> do not use <tt>value</tt>'''. 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: <tt>example_slist.stuff[example_element].udata = ...</tt><br>
 +
&nbsp;&nbsp;<tt>value</tt>
 
====SObjectProperties====
 
====SObjectProperties====
 
====sgui_properties====
 
====sgui_properties====

Revision as of 00:25, 24 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)</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.

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

SObjectProperties

sgui_properties

Fonts

Elements

sgui_button

sgui_textbox

sgui_checkbox

sgui_list

sgui_listbox

sgui_label

sgui_pixelfield