The purpose of the Preference Window generator

GTK+ is a very powerful and good library for creating all kinds of windows with buttons, textentries and so on. However, for the applet's preference window the functionallity is abit too much. You need to write alot of code just to have a check box. So the purpose of this preference window generator is to generate a nicely formated preference window based upon the applets wishes based upon just a few lines of code.

The idea is to fill a structure with the type of entries that you need for your applet and tell the library at start-up that it should generate a preference window based upon the given settings.


typedef enum {
    GAI_END             = 0x00,
    GAI_CHECKBUTTON     = 0x01,
    GAI_TEXTENTRY       = 0x02,
    GAI_TEXT            = 0x03,
    GAI_FRAME		= 0x04,
    GAI_RADIOBUTTON     = 0x05,
    GAI_SPINBUTTON      = 0x06,
    GAI_COLORSELECTOR   = 0x07,
    GAI_HLINE           = 0x08,
    GAI_FILESELECTOR    = 0x09,
    GAI_NOTEBOOK	= 0x0A,
    GAI_OPTIONMENU      = 0x0B,
    GAI_PASSWORDENTRY   = 0x0C,
    GAI_SPINBUTTON_FLOAT = 0x0D,
    GAI_COMBO           = 0x0E,
    GAI_ALL_LEFT        = 0x0F,
    GAI_ALL_CENTER      = 0x10,
    GAI_ALL_RIGHT       = 0x11,
    GAI_FRAME_R		= 0x12,
    GAI_FRAME_E		= 0x13,
    GAI_NOTEBOOK_E	= 0x14,
    GAI_BUTTON_TEXT     = 0x15,
    GAI_BUTTON_STOCK    = 0x16,
    GAI_BUTTON_IMAGE    = 0x17,

    /* Flags */
    GAI_LEFT            = 0x40<<0,
    GAI_RIGHT		= 0x40<<1,
    GAI_CENTER		= 0x40<<2,
    GAI_NO_TEXT_MARKUP	= 0x40<<3

} GaiPrefTypes;

Structures

GaiPI

typedef struct {
    GaiPrefTypes type;
    void *name;
    void *default_val;
    void *result_val;
    void *extra;
} GaiPI;

This structure is the core structure of the preference window. Each item that shall be added to the preference window is configured via a GaiPI entry.

GaiSS

/* Gai Spinbutton Settings */
typedef struct {
    int min;
    int max;
    int step;
} GaiSS;

GaiSSF

/* Gai Spinbutton Settings - Float*/
typedef struct {
    float min;
    float max;
    float step;
    int decimals;
} GaiSSF;

GaiColor

typedef struct {
    unsigned char r, g, b, alpha;
} GaiColor;

This stucture is used for transfering colour information. GdkColor could not be used since it lacks of alpha channel information.


Base


GAI_END

{GAI_END}
Marks the end of the preference window structure. Must be the very last entry of a preference window structure.

GAI_CHECKBUTTON


{GAI_CHECKBUTTON, label, default, result}
Adds a checkbutton to the preference window. The default and the result value can either be TRUE or FALSE.
char *label : The label of the check button.
int *default :Pointer to where the default value is stored.
Returns :
int *result :Pointer to where the result shall be stored.
GAI assumes that the int where the result value shall be stored is already allocated. GAI will just write the result there, if the pointer is not NULL.

GAI_TEXTENTRY


{GAI_TEXTENTRY, label, default, result}
Adds a textentry to the preference window.
char *label :The label of the text entry.
char **default :Double pointer to where the default text entry is stored.
Returns :
char **result :Double pointer to where the result shall be stored.
If the last pointer of the result double pointer is NULL, a new buffer is allocated, while if it points to something g_free will be used on that data, and later new buffer will be allocated. This hinter the preference window generator to leak memory when the preferences window is started many times.

GAI_TEXT


{GAI_TEXT, label}
Shows a line of text.
char *label :The text that shall be displayed.

GAI_FRAME


{GAI_FRAME, label}
This command starts a new frame. It means that all following commands until a GAI_FRAME_E is found will be added into it. Several deep levels of frames is accepted.
char *label :The name of the frame.

GAI_RADIOBUTTON


{GAI_RADIOBUTTON, names, default, result}
char ***names :.
int *default :.
Returns :
int *result :.

GAI_SPINBUTTON


{GAI_SPINBUTTON}

GAI_COLORSELECTOR

{GAI_COLORSELECTOR}

GAI_HLINE


{GAI_HLINE}

GAI_FILESELECTOR

{GAI_FILESELECTOR}

GAI_NOTEBOOK


{GAI_NOTEBOOK}

GAI_OPTIONMENU


{GAI_OPTIONMENU}

GAI_PASSWORDENTRY

{GAI_PASSWORDENTRY}

GAI_SPINBUTTON_FLOAT


{GAI_SPINBUTTON_FLOAT}

GAI_COMBO


{GAI_COMBO}

GAI_ALL_LEFT

{GAI_ALL_LEFT}

GAI_ALL_CENTER

{GAI_ALL_CENTER}

GAI_ALL_RIGHT

{GAI_ALL_RIGHT}

GAI_FRAME_R

{GAI_FRAME_R}

GAI_FRAME_E

{GAI_FRAME_E}

GAI_NOTEBOOK_E

{GAI_NOTEBOOK_E}

GAI_BUTTON_TEXT


{GAI_BUTTON_TEXT}

GAI_BUTTON_STOCK


{GAI_BUTTON_STOCK}

GAI_BUTTON_IMAGE


{GAI_BUTTON_IMAGE}

Flags

GAI_LEFT

{|GAI_LEFT}

GAI_RIGHT

{|GAI_RIGHT}

GAI_CENTER

{|GAI_CENTER}

GAI_NO_TEXT_MARKUP

{|GAI_NO_TEXT_MARKUP}

gai_init2()

int            gai_init2                           (GaiApplet* applet_info, 
                                                    int *argc, 
                                                    char ***argv);

This will replace gai_init in GAI version 0.6.0 and later. gai_init2 provides more information than gai_init in order to make it possible to automatically generate an About box. Together with the current template configure and Makefile scripts most of the information there will be used to generate the GaiApplet* structure. Otherwise gai_init2 does about the same thing as gai_init.

*applet_info :A struct with information about the applet. If you use the GAI template scripts, this information is provided in config.h that is generated by the configure script.
*argc :Pointer to the argc provided to the main function.
***argv :Pointer to the **argv provided to the main function.
Returns :0 if everything went well.

Errors in this document? Need help? Then mail me, Jonas Aaberg, cja@gmx.net.