EasyGTK

Manual v1.2

Introduction

Copyright

This manual and the EasyGTK library are (C) 1999 Patrick Lambert and are available under the LGPL license.

History

I made EasyGTK because I realized that my GTK programming was mostly cut and paste of older functions I had made.

EasyGTK has 2 goals. First to make learning quicker and easier, to provide GTK programming to more people, and second to enable programmers to write code in fewer lines. A typical EasyGTK function will do what 5 or even 10 lines of GTK code would do.
 

Installation

Downloading

EasyGTK is a Unix C library and is provided as source code. To compile it, you need a Linux or Unix box with the GNU C compiler, GNU make and GTK 1.2 installed.

You can download EasyGTK from one of these locations:

  • http://www.linsupport.com
  • http://metalab.unc.edu
  • http://mirrors.darkelf.net

    • Compiling

    Before compiling, you need to run the configure script. This will try to find if your system has the required libraries. If you have IMLIB, then the right compilation options will be added to the Makefile. If you don't need image support, I suggest you compile without the graphical libraries: configure -Magick -Imlib.

    Note that this version now comes with support for GNOME, which will be included in the compile if it is detected. This also means you have to add the GNOME libraries in your own program if you use EasyGTK with support for the GNOME system. To compile without that support, add -gnome to the configure line.

    Once the configure step is done, type make to compile EasyGTK. If this fails, you may need to edit the Makefile yourself.

    Compiling programs using EasyGTK

    To compile a program with EasyGTK you simply need to compile it like you would with normal GTK libraries, plus the EasyGTK static library. Here is an example, if EasyGTK was compiled without any extra library:

    gcc `gtk-config --cflags` -o myprogram myprogram.c `gtk-config --libs` libeasygtk.a

    Note that you also need to include the IMLIB or ImageMagick libraries if you compiled EasyGTK with the default settings:

    gcc `gtk-config --cflags` -I/usr/X11R6/include/X11/magick -I/usr/local/include/magick -o myprogram myprogram.c `gtk-config --libs` -lgdk_imlib `imlib-config --libs` -I/usr/include/glib libeasygtk.a -L/usr/local/lib -lMagick -ltiff -ljpeg
     

    Functions

    Some basic concepts

    A widget is any graphical element. You need to first create a window, on which you attach a vertical or horizontal box. Then you attach other widgets to the box. The variables 'parent' are always supposed to be boxes. Boxes can be attached to other boxes to create complex placement.

    GtkWidget *e_window_create(gchar *title, gint size_x, gint size_y, gint position_x, gint position_y, GtkSignalFunc window_destroy);

    This function allows you to create a new window. The window_destroy argument must be a function name that you create in your application and that will be called when the user closes that window.

    void e_set_size(GtkWidget *widget, gint size_x, gint size_y);

    This function will set the size of a widget.

    GtkWidget *e_box_create(GtkWidget *parent, gint placement, gint border);

    This will create a box. Boxes are used to put widgets in. The parent must be an other box or a window. The placement must be E_VERTICAL for a vertical box or E_HORIZONTAL for an horizontal box. The border argument specifies how many pixels should be betwen the window borders and the widgets in the box.

    void e_box_add(GtkWidget *parent, GtkWidget *widget, gint placement, gint fill);

    This function will pack any widget into a box. The placement must be E_LEFT for normal placement or E_RIGHT to justify the widget on the right. The fill argument must be TRUE if you want the widget to expand to the window, or FALSE if you want a small, fixed widget.

    GtkWidget *e_box_fixed(GtkWidget *parent, gint placement, gint border);

    This will create a fixed box. Boxes are used to put widgets in. The parent must be an other box or a window. The placement must be E_VERTICAL for a vertical box or E_HORIZONTAL for an horizontal box. The border argument specifies how many pixels should be betwen the window borders and the widgets in the box.

    GtkWidget *e_text_create(GtkWidget *parent, gint editable, gchar *initial_text, GtkSignalFunc text_changed);

    This will create a text area where text can be inserted. If editable is TRUE then the user will be able to insert text in the area. The text_changed function will be called when the user inserts something. Note that for any signal functions you can put E_NO_FUNC if you don't wish to handle that event.

    void e_text_insert(GtkWidget *textarea, gchar *text);

    This will insert text into a textarea.

    void e_text_insert_file(GtkWidget *textarea, gchar *filename);

    Inserts filename's content into textarea.

    gint e_text_find(GtkWidget *textarea, gchar *string);

    This function will find the position of string in the textarea, focus on it, and return the position number.

    gchar *e_text_get(GtkWidget *textarea);

    This will return whatever text is in the textarea.

    void e_text_delete(GtkWidget *textarea);

    This will delete all of the text in the textarea.

    GtkWidget *e_label_create(GtkWidget *parent, gchar *text);

    This will create a label with the specified text in it.

    GtkWidget *e_entry_create(GtkWidget *parent, gchar *initial_text);

    This will create an entry box where user can put a line of text in.

    gchar *e_entry_get(GtkWidget *entry);

    This will return the text which was entered by the user.

    GtkWidget *e_button_create(GtkWidget *parent, gchar *text, GtkSignalFunc button_click);

    This will create a button. When the user clicks on it, the function in the argument button_click will be called.

    GtkWidget *e_button_fixed(GtkWidget *parent, gchar *text, GtkSignalFunc button_click);

    This will create a non resizable button. When the window grows, the button will stay the same size.

    GtkWidget *e_combo_create(GtkWidget *parent, gchar *initial_text, gchar *combo_list[], gint num, GtkSignalFunc item_selected);

    This will create a combo box, which is a drop down list of items, with the items in combo_list. combo_list must contain num items. The function in item_selected will be called when the user selects an item.

    gchar *e_combo_get(GtkWidget *combo);

    This returns the item selected.

    GtkWidget *e_list_create(GtkWidget *parent, gint cols, GtkSignalFunc item_selected);

    This iwll create a list with a number of columns specified in cols.

    void e_list_setup(GtkWidget *list, gint col, gchar *title, gint width);

    This will setup the column specified in col, setting the title and the width for that column.

    gchar *e_list_get();

    This will return the selected line.

    void e_list_remove(GtkWidget *list);

    This will remove the selected row

    void e_list_insert(GtkWidget *list, gchar *text[]);

    This will insert text into the list. Note that the array must have the same size as the number of columns in the list.

    GtkWidget *e_buttonbox_create(GtkWidget *parent, gint orientation, gchar *button1_text, gchar *button2_text, GtkSignalFunc button1_click, GtkSignalFunc button2_click);

    This will create a box with 2 buttons in it. The orientation should be E_END, E_SPREAD or E_DEFAULT.

    GtkWidget *e_buttonbox_unlim(GtkWidget *parent, gint orientation, guint num_buttons, ...);

    This will create a box with num_buttons in it. ... parameters are as follows:

    button1_text, button1_click, button2_text, button2_click, buttonN_text, buttonN_click, ...

    For example: e_buttonbox_unlim(parent, E_SPREAD, 3, "Yes", E_NO_FUNC, "No", E_NO_FUNC, "Cancel", E_NO_FUNC);

    GSList *e_radiobuttons_create(GtkWidget *parent, gchar *items[], gint num);

    This function will create a set of radiobuttons. The items argument should be an array of what must go in the radiobuttons, and num the number of radiobuttons. Note that due to how this is currently implemented, you should only use one set of radiobuttons at a time.

    gint e_radiobuttons_get();

    This will return the last radiobutton selected.

    void e_radiobuttons_setdefault(gint choice);

    This will set the default radiobutton.

    GtkWidget *e_checkbutton_create(GtkWidget *parent, gchar *text, gint default_state, GtkSignalFunc button_checked);

    This will create a checkbutton with text on it. It will be checked by default if default_state is TRUE. button_checked will be called when the user clicks on it.

    gint e_checkbutton_get(GtkWidget *checkbutton);

    This will return the state of the checkbutton.

    GtkWidget *e_notebook_create(GtkWidget *parent, gint placement);

    This will create an empty notebook with the labels at placement. The placement argument must be E_TOP, E_BOTTOM, E_LEFT or E_RIGHT.

    GtkWidget *e_notebook_new_page(GtkWidget *notebook, gchar *title, gchar *description);

    This will make a new page. You can then add other widgets to it.

    GtkWidget *e_show_message(gchar *title, gchar *message, GtkSignalFunc window_destroy);

    This function will show a message in a box on the screen.

    GtkWidget *e_show_textbox(gchar *title, gchar *initext, GtkSignalFunc window_close);

    This function will show a text in a textbox, with a close button.

    GtkWidget *e_browse_create(gchar *title, GtkSignalFunc ok_clicked, GtkSignalFunc cancel_clicked);

    This will show a browse window where the user can select a file. If the user closes the window or clicks on cancel, cancel_clicked will be called.

    gchar *e_browse_get(GtkWidget *browse);

    This will get the selected filename from a browse window.

    GtkWidget *e_font_create(GtkWidget *parent, gchar *title, GtkSignalFunc ok_clicked, GtkSignalFunc cancel_clicked);

    This will create a font selection window. The user can then select a font.

    gchar *e_font_get(GtkWidget *fs);

    This will return the selected font from the font window fs.

    GtkWidget *e_scrolled_create(GtkWidget *parent);

    This will create a scrolled window where you can add other widgets.

    GtkWidget *e_toolbar_create(GtkWidget *parent, int orientation);

    This will make a new toolbar and add it to parent. The orientation must be E_HORIZONTAL or E_VERTICAL.

    void e_toolbar_insert(GtkWidget *toolbar, gchar *name, gchar *description, GtkWidget *icon, GtkSignalFunc button_clicked);

    This will add a new button on the toolbar, with name, description and icon. If you don't want one of those 3 items, use NULL. The icon can be made with e_icon_create or e_pixmap_create. When the button is clicked, button_clicked's function will be called.

    GtkWidget *e_image_create(GtkWidget *parent, gchar *filename);

    THIS FUNCTION REQUIRES IMLIB

    With this function you can show an image on parent. The image can be anything that imlib supports, including xpm, jpeg, gif and png.

    GtkWidget *e_image_scaled(GtkWidget *parent, gchar *filename, gint size_x, gint size_y);

    THIS FUNCTION REQUIRES IMLIB

    With this function you can show an image on parent. The image will be scaled down to size_x and size_y, and can be anything that imlib supports, including xpm, jpeg, gif and png.

    GdkWindow *e_image_window(gchar *filename);

    THIS FUNCTION REQUIRES IMLIB

    This function will create a window with the image in filename in it. The window will be resized to fit the image. The image can be anything that imlib supports, including xpm, jpeg, gif and png.

    GdkImlibImage *e_image_get();

    THIS FUNCTION REQUIRES IMLIB

    This function returns image data from the last loaded image to use with advanced imlib functions.

    GtkWidget *e_menu_create(GtkWidget *parent);

    This will create a new menu bar. It will be attached to parent.

    GtkWidget *e_menu_insert_menu(GtkWidget *menubar, gchar *name, gint justify);

    This will make a new menu on the menu bar, with the name in variable name. The justify variable should be E_LEFT for a normal menu, or E_RIGHT for a menu in the far right.

    GtkWidget *e_menu_insert_item(GtkWidget *menu, gchar *name, GtkSignalFunc item_clicked);

    This will make a new entry in menu called name.

    GtkWidget *e_menu_insert_line(GtkWidget *menu);

    This function inserts a blank line in a menu.

    GtkWidget *e_icon_create(GtkWidget *window, gchar *filename);

    This will create an icon out of an xpm file.

    gchar *e_lrange(gchar *input_string, gint starting_at);

    This will return every word from input_string after the word starting_at. A word is separated by spaces.

    gchar *e_lindex(gchar *input_string, gint word_number);

    This will return the word from input_string at word_number. Words are separated by spaces.

    gchar *e_lindex_delim(gchar *input_string, gint word_number, gchar *delim);

    This will return the word from input_string at word_number. Words are separated by delim.

    gchar *e_config_fetch(gchar *filename, gchar *key);

    This will read filename which must be created with e_config_insert functions, look for key, and return the associated data.

    gint e_config_insert(gchar *filename, gchar *key, gchar *data);

    This will insert in the filename configuration file key with its associated data.

    gint e_config_update(gchar *filename, gchar *key, gchar *data);

    This will edit filename and change key and put the new data in place. If the key doesn't exist, it will try to add it. Note that filename must exist prior to use.

    GtkWidget *e_tree_create(GtkWidget *parent);

    This function will create a root tree and put it on parent.

    GtkWidget *e_tree_insert_subtree(GtkWidget *tree, gchar *name);

    This will make a subtree with the label name and add it to tree. Note that tree can be also a subtree.

    GtkWidget *e_tree_insert_item(GtkWidget *tree, gchar *name, GtkSignalFunc item_clicked);

    This will add a label to a tree or subtree and will call item_clicked when clicked on it.

    gchar *e_tree_get();

    This function will return the last selected item on a tree.

    gint e_image_convert(gchar *infile, gchar *outfile);

    THIS FUNCTION REQUIRES IMAGEMAGICK

    This function will convert an image file into an other format. Files can be GIFs, JPEGs, PNGs or any other format that ImageMagick supports.

    void e_image_display(gchar *filename);

    THIS FUNCTION REQUIRES IMAGEMAGICK

    This function will display filename in its own window, by ImageMagick. I suggest you use IMlib if at all possible since it gives you more control over your image.

    GtkWidget *e_pixmap_create(char *xpm_data[], GdkWindow *window);

    This will create a pixmap from an included .xpm file. Example:

    #include <my_file.xpm>
    ...
    my_pix = e_pixmap_create(my_file_xpm, window->window);

    GtkWidget *e_button_create_with_pixmap(GtkWidget *parent, GtkWidget *icon, GtkSignalFunc button_clicked);

    This function will create a button with a pixmap on it. It will put no label, only pixmap. When clicked, the button will call button_clicked. Icon can be createdwith e_icon_create or e_pixmap_create().

    GtkWidget *e_event_create(GtkWidget *parent, gint size_x, gint size_y, GtkSignalFunc area_clicked);

    This function will create an event box with the specified size, and rulers. When the area is clicked on, area_clicked will be called. Due to the way this is implemented, only one event box should be used at a time.

    gint e_event_get_x();

    This returns the X position of the latest click on an event box.

    gint e_event_get_y();

    This returns the Y position of the latest click on an event box.

    GtkWidget *e_query_create(gchar *title, gchar *message, GtkSignalFunc ok_clicked, GtkSignalFunc cancel_clicked);

    This function will create a query box with the specified message and an entry box, and 2 buttons.

    gchar *e_query_get(GtkWidget *query);

    This will return the entry from the specified query box.

    E_Wizard *e_wizard_create(gchar *title, GtkWidget *icon, gchar *text, gint entry_box, GtkSignalFunc prev_button, GtkSignalFunc next_button, GtkSignalFunc cancel_button);

    This will create a wizard like window with an icon, a text box and, if entry_box is TRUE, an entry box.

    void e_editor_create(E_Editor *editor);

    This will create a simple editor.
     

    What the future holds

    Version 1.1x

    The goals for version 1.1 of EasyGTK will be to improve on the current functions, add new GTK, IMLIB and ImageMagick functions.

    Version 2.0

    Version 2.0 is still far ahead, but it may be interesting to convert EasyGTK into EasyGUI which could also create QT or Motif code.