Difference between revisions of "Sgui"

From z64 wiki
Jump to: navigation, search
(Library Description)
(Library Description)
Line 33: Line 33:
 
}
 
}
 
SList;</pre>
 
SList;</pre>
&nbsp;&nbsp;<tt>len</tt> is the length of the list.
+
&nbsp;&nbsp;<tt>len</tt> is the length of the list.<br>
&nbsp;&nbsp;<tt>selected</tt> is which element is currently selected. A negative value indicates no current selection.
+
&nbsp;&nbsp;<tt>selected</tt> is which element is currently selected. A negative value indicates no current selection.<br>
&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>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.<br>
 
&nbsp;&nbsp;<tt>stuff</tt> is the list itself. Each element is:
 
&nbsp;&nbsp;<tt>stuff</tt> is the list itself. Each element is:
 
<pre>typedef struct
 
<pre>typedef struct
Line 48: Line 48:
 
     void *__sgui_private_ptr;
 
     void *__sgui_private_ptr;
 
}
 
}
SListValue;</pre><br>
+
SListValue;</pre>
 
&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>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>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.<br>
 
&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>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>
+
&nbsp;&nbsp;<tt>value</tt> is an alternate to <tt>udata</tt>, and can be an integer of your liking.<br>
 +
&nbsp;&nbsp;<tt>__sgui_private_ptr</tt> is used internally by sgui. Modification of this value results in undefined behavior.
 
====SObjectProperties====
 
====SObjectProperties====
 
====sgui_properties====
 
====sgui_properties====

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