========================
    GTK-MUI Library
========================

$Id: README,v 1.7 2013/03/22 10:21:14 o1i Exp $

/*
 * This README is far from being complete.
 */

This library was the result of bounty #30 of the Team Aros:
"GTK+ 2.x wrapper to Zune/MUI (initial version)".

Until then, it was heavily improved (GLIB support added,
a lot of GTK widget code ca be reused for GTK-MUI widgets,
many more (basic) widgets added).

For the original wording of the bounty, see below.

====================================================
License
====================================================

GTK-MUI is published under the LGPL 
(http://www.gnu.org/licenses/lgpl.txt).

====================================================
How to use this library as a normal user (non-coder)
====================================================

You can use list library to port GTK programs to your preferred 
AmigaOS flavour. There is *no* use for this library, if you are 
not writing a program, sorry ;).

====================================================
Operating System Requirements
====================================================

This library is developed for AROS, Makefiles for MorphOS (itix) 
and AmigaOS4 (Andrea Palmatè) are provided AS THEY ARE and 
not supported by the author, as I own neither MorphOS nor AmigaOS4.
MorphOS and AmigaOS4 versions are really outdated ATM.

ATM the AROS library is a static link library for use with C programs.

====================================================
Known Bugs
====================================================

- There might be problems, if you pack a not
  yet shown widget into an already shown box.
  Normally you will not do this. It
  is recommended by the GTK docs, that you
  first instert all children, show them and
  then show the parent to avoid uneccessary
  redraws/shifts. In GTK-MUI it is worse,
  your application may hang.

====================================================
How to use this library as a programmer
====================================================

TBD

====================================================
How to implement a new (missing) widget
====================================================

Best way to start is, to search for an already existing widget, 
which has similiar functions as the missing one. Look how it 
is implemented and try to implement the missing one ;).

TBD.

====================================================
GTK-MUI internals
====================================================

TBD.

global structure mgtk (outdated):

struct _mgtk {
  APTR MuiApp;
    /* MUI application pointer */
  APTR MuiRoot;      
    /* MUI Root Window Object */
  APTR MuiRootStrip; 
    /* MUI Root Window Object Menu Strip*/
  APTR Group;        
    /* MUI Root Window Group Object */
  GSList *windows;   
    /* all GTK windows in a linked list */
  GtkWidget *grab;   
    /* the widget getting all keystrokes.. TODO */
  guint mgtk_signal_count;
    /* the next free number for a (custom) signal type */
  mgtk_SignalType *mgtk_signal;       
    /* All GTK (custom) signals  */
  GType mgtk_fundamental_count;
    /* the next free number for a (custom) widget type */
  mgtk_Fundamental *mgtk_fundamental; 
    /* All custom widget types  */
  GtkStyle *default_style;
    /* default GTK style for all widgets */
  guint white_black_optained;
  LONG white_pen;
  LONG black_pen;
  guint other_pens_optained;
  struct Screen   *screen;
  struct DrawInfo *dri;
  APTR             visualinfo;
    /* some pen/screen magic */
};


====================================================
Debugging the library
====================================================

The library can be built with debug output enabled or disabled. If you 
build it without -DDEBUG, then on AROS

DebOut  : won't print any output
WarnOut : print to D(bug 
ErrOut  : error requester

with -DDEBUG

DebOut  : print to D(bug 
WarnOut : print to DebOut and STDOUT
ErrOut  : print to DebOut, STDOUT and display a requester

DebOut might give wrong values, when you print floating point values.

====================================================
Useful links
====================================================
Home of GTK:
http://www.gtk.org/ 

Home of GTK-MUI:
http://sourceforge.net/projects/gtk-mui/ 

GTK function overview:
http://www.gtk.org/api/2.6/gtk/ix01.html

GTK+ 2.0 Tutorial:
http://www.gtk.org/tutorial/index.html

GLIB signals:
http://developer.gnome.org/doc/API/2.0/gobject/gobject-Signals.html


====================================================
Team AROS Bounty description
====================================================

Objectives:

1. Create a wrapper for GTK+ 2.x to Zune/MUI.
2. A minimum documentation is required on which calls port to which, 
   and any appropriate comments on how the two systems interact.
3. When writing the source code, the future possibility should be 
   kept in mind to use it with the appropriate #Defines for all 
   of the Amiga operating systems.
4. Since a wrapper allows to emulate GTK step by step, no complete 
   wrapper is required yet. For this bounty, a basic version containing 
   the functions mentioned below will be sufficient. 
   To fulfill this initial bounty, the following GTK functions need 
   to be wrapped to Zune/MUI: 
     gtk_adjustment_changed
     gtk_adjustment_new
     gtk_arrow_new
     gtk_box_pack_start
     gtk_button_new
     gtk_button_new_with_label
     gtk_check_button_new_with_label
     gtk_container_add
     gtk_container_set_border_width
     gtk_entry_get_text
     gtk_entry_new
     gtk_entry_set_text
     gtk_file_selection_get_filename
     gtk_file_selection_new
     gtk_file_selection_set_filename
     gtk_fixed_new
     gtk_frame_new
     gtk_handle_box_new
     gtk_hbox_new
     gtk_hscrollbar_new
     gtk_hseparator_new
     gtk_label_new
     gtk_main
     gtk_main_quit
     gtk_menu_bar_new
     gtk_menu_item_new
     gtk_menu_item_new_with_label
     gtk_menu_item_set_submenu
     gtk_menu_new
     gtk_menu_shell_append
     gtk_notebook_new
     gtk_object_unref
     gtk_paint_arrow
     gtk_paint_box
     gtk_paint_check
     gtk_paint_extension
     gtk_paint_flat_box
     gtk_paint_focus
     gtk_paint_option
     gtk_paint_shadow
     gtk_paint_slider
     gtk_progress_bar_new
     gtk_radio_button_group
     gtk_radio_button_new_with_label
     gtk_range_get_adjustment
     gtk_rc_get_style_by_paths
     gtk_signal_connect
     gtk_signal_connect_object
     gtk_spin_button_get_value_as_float
     gtk_spin_button_new
     gtk_spin_button_set_wrap
     gtk_style_apply_default_background
     gtk_style_attach
     gtk_table_attach
     gtk_table_new
     gtk_table_set_col_spacings
     gtk_table_set_row_spacings
     gtk_toggle_button_set_active
     gtk_toolbar_new
     gtk_tooltips_force_window
     gtk_tooltips_new
     gtk_vbox_new
     gtk_vscrollbar_new
     gtk_widget_destroy
     gtk_widget_grab_default
     gtk_widget_realize
     gtk_widget_set_rc_style
     gtk_widget_set_sensitive
     gtk_widget_set_state
     gtk_widget_set_usize
     gtk_widget_show
     gtk_widget_show_all
     gtk_widget_style_get
     gtk_window_new
     gtk_window_set_modal
     gtk_window_set_title
     gtk_window_set_transient_for


====================================================
Thanks to
====================================================

- Senex and all other donators of this bounty, this shows a 
    programmer, that his work is appreciated
- Ilkka Lehtoranta (itix) for:
    working on the library a few days
    showing me how to write custom classes
    the table and root class
    MorphOS port (although not current at the moment)
  The hours you helped this project have been very important, the 
  current quality would have been impossible without you.
- Andrea Palmatè for:
    Amiga OS4 port
    telling me how bad my includes are ;)
- Adam Olivier for:
    initial AROS port help
- Stefan Haubenthal for:
    sending me some smaller patches
    trying to build this mess on his machine
- Miloslav Martinka
    GtkStatusBar is his work.

Oliver Brunner (o1i), gtk-mui "at" oliver-brunner.de


