<!DOCTYPE html>
<html lang="en">
<head>
<title>EuGTK README</title>
<link rel="stylesheet" href="style.css" type="text/css">
</head>
<body>
<heading>
<img src="../thumbnails/mongoose.png" alt="mongoose" />
<img src="../thumbnails/gtk-logo-rgb.gif" alt="gtk logo" height="100px" />
<a href="../screenshots/t.png" alt="t" title="t">
<figure style="border:solid thin black;">
<img src="../screenshots/t.png" title="t" alt="t" align="right" width="500px" /></a>
<figcaption>
<small><i> Pete Eberlein's WEE Euphoria editor</i></small>
</figcaption>
</figure>
<h2><hr />EuGTK 4.12.0<hr /></h2>
<h3>A cross-platform language binding for Euphoria and the GTK3 graphic user interface</h3>
<hr>
</heading>
<br clear="all" />
<nav>
<div class="hdr">Quick Links:</div>
<a href="#starting"><button>Getting Started</button></a>
<a href="#programming"><button>Writing your programs</button></a>
<a href="#errors"><button>Error messages</button></a>
<a href="#c"><button>Compare with C code</button></a>
<a href="#platforms"><button>Tested Platforms</button></a>
<a href="#features"><button>New Features</button></a>
<a href="#syntax"><button>New Syntax</button></a>
<a href="#plugins"><button>New Plugins</button></a>
<a href="#changes"><button>Recent Changes</button></a>
<a href="#broadway"><button>Broadway</button></a>
<a href="#bear"><button>BEAR</button></a>
<a href="#history"><button>History</button></a>
<a href="#legal"><button>Legal Disclaimer</button></a>
<div class="hdr">Other Files:</div>
<a href="HowItWorks.html"><button>How EuGTK Works</button></a>
<a href="guide_a.html"><button>Alphabetical Guide</button></a>
<a href="dialogs.html"><button>Built-in EuGTK Dialogs</button></a>
<a href="treeviews.html"><button>ListView/TreeView widgets</button></a>
<a href="pango_markup.html"><button>Markup</button></a>
<a href="printing.html"><button>Printing</button></a>
<a href="ServerHelp.html"><button>Web Server</button></a>
<a href="functions.html"><button>Quick Function List</button></a>
<a href="Glade.html"><button>Glade GUI Builder</button></a>
<a href="platforms.html"><button>Platforms</button></a>
<hr />
</nav>
<content>
<p><small>
This package should be up-to-date with GTK version 3.21.4.
Tested with GTK 3.18.9 on Linux Mint 18 Cinnamon 64-bit and
Gtk 3.10.8 on Mint 17.2 Rafaela 64-bit, as these are the most-popular
distros with the latest stable GTK 3 versions included.
Also, tested on Windows 7 64-bit with Gtk 3.20.2.
</small></p>
<div class="hr"><hr /></div>
<p>
<b>The Good News:</b><br />
GTK3 is better both in ease of use and in
the ability to produce attractive, modern program interfaces than any other GUI libraries
I've tried. GTK3, unlike most of the other GUI libraries, has functions
to handle touch screens.
</p>
<p>
<b>Linux</b> distros such as Ubuntu, Mint, Ultimate, Parsix, etc. come with GTK3
libraries already installed. If necessary, you can install GTK3 alongside GTK2 without
problems. Apt-get will do it for you.
Or, in your package manager, look for libgtk-3-0. If you can't get libgtk-3, then it
may be time
to think about updating your ancient Linux installation.
</p>
<p><b>In addition</b>, EuGTK 4.9.0 and up works with OS X™.
It also works on Windows™, but I cannot recommend this.
Windows has become entirely too awkward to use and maintain.
</p>
<p><small>
<b><i>(Once upon a time I succeeded in nailing some jelly to a tree.
That doesn't mean I'd consider jelly-nailing to be a good career choice.)</i></b></small>
</p>
<p>
The same EuGTK engine and sourcecode can be used
on any of the three platforms without change, except for possibly
missing icons on different platforms. You can supply your own icons
if appearance is important.
</p>
<p>
<b>More Good News:</b><br />
Compared to other programming language/GUI combinations,
EuGTK is very simple to set up and to use.
There is only one 'include' you must add to your programs, which is 'include GtkEngine.e'.
There are only a few files that need to be available when you write, test,
run or perhaps compile your program - GtkEngine.e and GtkEnums.e. Adding, when required,
GtkPrinter.e, etc...<br /><br />
No additional files are produced or needed other than the code you write and the standard
Euphoria library files. This makes project management simpler, and
if you want to ship EuGTK with your program, the required files only add about 350k to
the total package (74k if compressed!).
</p>
<p>
Also, EuGTK is easier to use because EuGTK adds some 'intelligence' that is missing from other
languages, (like C or Python), such as the ability to create images from a variety of sources without the
programmer having to call a different function for each source type. See <a href="HowItWorks.html#variants">variants</a>.
</p>
<p>
In addition, EuGTK is easy to keep up-to date with the latest versions of GTK
because all of EuGTK is written in Euphoria, so it can easily be edited by anyone,
with no re-compiling or other tricky steps involved.
</p>
<p>
You'll need the latest Euphoria 4 interpreter
from <a href="http://openeuphoria.org">OpenEuphoria.org</a>.
I use Euphoria 4.1.0 beta.
Plus, you'll <i>really</i> need the latest GTK docs! Get 'em from <a href="http://gtk.org">gtk.org</a>.
</p>
<p>
Just open the gzipped package <i><small>(I guess you've already done that)</small></i> and drag the 'demos' folder into your home folder.
All files are in the demos folder (and subfolders thereof).
Try them so you'll know what you can do
with GTK!
</p>
<p>
<b>Installation</b><br />
Later, you can put these files - GtkEngine.e, GtkEnums.e, GtkPrinter.e, etc. -
into the folder with your other Euphoria includes, or just add a one-line
eu.cfg file to any directory you wish to work in, pointing to the location
of these files. My Euphoria/include folder is /usr/local/share/euphoria/include.
Moving all the Gtk***.e files from the demos folder into there works.</p>
<div class="hint">
<img src="../thumbnails/hint.png" alt="hint" width="100px" align="left" float="right" />
<p>
Be sure to add this eu.cfg to your home directory as well, otherwise, eu programs will
not be able to find the necessary GtkEngine.e when you start a program
from your file manager (such as caja).
</p>
<p>
My eu.cfg reads:<br />
<tt>
~/demos
</tt>
</p>
</div>
<a name="starting" />
<h3><hr />Getting Started:<hr /></h3>
<p>
First, open an x-term, cd to the demos directory, and run a program:
$> eui test0
</p>
<a href="../screenshots/test0.png">
<img src="../screenshots/test0.png" align="left" float="right" />
</a>
<p>
<b><i>Running from an x-term is mandatory</i></b> while you are writing your
Euphoria/GTK programs, so that you can see error messages and crash reports,
but not necessary once you have your program working and debugged.
<div class="scrn"><tt><pre>************************************
Fatal Error: no libgtk-3.so.0 found!
************************************
</pre></tt></div>
<p>If you get the above error message, either you do not have
libgtk-3 installed (try apt-get or your package manager), or it has
been installed in an unexpected location. Check lines 66 thru 88 at the top of
GtkEngine.e and make changes as necessary.
</p>
<br />
<div class="urgent">
You may also get the above error if you are trying to run --
32-bit Euphoria on a computer with 64-bit libraries (or vice-versa) --
</div>
<p>
Now try as many of the test programs as you can, they will help you find incompatibilities (if any) with the
version of the GTK library you are using.
</p>
<p>
Running these test programs is also the best way to see what GTK offers for use in <i><u>your own</u></i> programs.
</p>
<p>Now, get busy!</p>
<br clear="all" />
<a name="programming" />
<h3><hr />WRITING PROGRAMS:<hr /></h3>
<p>If you haven't read <a href="HowItWorks.html">How it Works</a> yet, please do so now!
</p>
<p>
You can use any plain text editor to create your EuGTK programs. I use
either Pete Eberlein's great <a href="https://github.com/peberlein/WEE/">WEE</a> editor
(written in Euphoria), sometimes Pluma or <a href="http://www.geany.org">Geany</a>,
or the GtkSourceView widget,
which also works well, and could easily be expanded into a full-featured
programmer's editor.See <a href="../resources/README.html">Programmer's Resources</a>
for an overview.
</p>
<p>
The WEE editor (recommended!) automatically colorizes Euphoria source code, and moves the cursor to
the file/line where a syntax error occurs.
</p>
<div class="hint">
<img src="../thumbnails/hint.png" alt="hint" width="100px" align="left" float="right" />
<p>
For <b>WEE</b>:<br />Pop-up help for both Euphoria and GTK keywords is available by pressing the [F1] key. See
instructions <a href="#weemods">here</a>.
</p>
</div>
<p>
In the <a href="../resources/geany_syntax/README.html">~/demos/resources/geany_syntax</a> folder you will find
files to add Euphoria syntax highlighting to <a href="http://www.geany.org/">Geany</a>,
as well as an add-on program by Kenneth Rhodes which moves the Geany edit cursor to the error line in your Eu program.
</p>
<p>
In the <a href="../resources/gedit_syntax/README.html">~/demos/resources/gedit_syntax</a> folder you will find
files to add Euphoria syntax highlighting to Pluma, GEdit, GtkSourceView, the <a href="../BEAR.ex">BEAR</a>, etc.
</p>
<h3><hr />Visual (Drag & Drop) Program design:<hr /></h3>
<p>
It is also possible to use Glade to design your program layout.
You will need the latest version of Glade (3.16 or up). See the following programs
for demos: <a href="../glade/calendar.ex">calendar.ex</a> and
<a href="../glade/calendar.glade">calendar.glade</a>.
and <a href="../glade/clock.ex">clock.ex</a> and <a href="../glade/clock.glade">clock.glade</a>.
Also, please read <a href="guide_a.html#xml">XML/GtkBuilder</a>.
</p>
<p>
Before you start coding, please read <a href="HowItWorks.html">HowItWorks</a> to get an overview, then open <a href="guide_a.html">guide_a.html</a>
in your browser for links to demos showing how the various controls (a.k.a. widgets) are used.
</p>
<p>
<b><i>You'll also need the latest GTK 3.0 docs</i></b> (from <a href="http://gtk.org">gtk.org</a>), since there are perhaps
4x more methods available than I have used in the demos. Some of these methods
can be ignored, since there are easier-to-use equivalents in Euphoria itself.
</p>
<a name="errors" />
<h3><hr />Error Messages:<hr /></h3>
<p>There are three possible sources of error messages: Euphoria, GTK, and EuGTK.<br /><br />
Euphoria gives you the line number and description of the error, but these will <b><i>only</i></b> appear
in a console - there will not be a pop-up error dialog - since these come directly from the Euphoria
interpreter, before GTK is running! Spelling errors, undeclared variables, and such will appear here:
</p>
<div class="scrn" style="width:100%"><tt><pre><0074>:: Errors resolving the following references:
'GtkBufton' (text16.ex:39) has not been declared.
constant okbtn = create(GtkBufton,"gtk-ok","Foo")
^</pre></tt></div>
<p>
GTK errors, which also only appear when running from a console,
will sometimes display an enigmatic message that will take some
effort to understand. Best way to debug these errors is to comment out blocks of code, and then
uncomment one line of code at a time, and see which line triggers the error message. Then consult the GTK docs
to see what GTK is expecting vs. what you've written:
</p>
<div class="scrn" style="width:100%"><tt><pre>
(test174.ex:3126): Gtk-WARNING **: Can't set a parent on a toplevel widget
**
Gtk:ERROR: /build/buildd/gtk+3.0-3.4.2/./gtk/gtkcontainer.c:3292:
gtk_container_propogate_draw: assertion failed: (gtk_widget_get_parent(child) ==
GTK_WIDGET (container))
Aborted
</pre></tt></div>
<br clear="all" /><i>
Above is the type of error message GTK will present, in this case I was trying
to add a dialog to a window (dialogs are 'run', not added to containers).
</i><br />
<br />
EuGTK itself will (hopefully) display easy-to-understand messages like the one below.
Both warnings and fatal errors are displayed here, so if your program doesn't run,
or doesn't seem to run correctly, <u><b><i>run it from a terminal! </i></b></u>
(x-term, mate-terminal, etc... whatever you have)
</p>
<div class="scrn" style="width:100%"><tt><pre>Error: function Foo is not in scope
****** (make it global or link via call_back(routine_id())</pre></tt></div>
<table border="1px">
<tr><th><em>CAUTION!</em></th></tr>
<tr><td>
If you plan to <i><b>compile</b></i> your EuGTK program, please read
<a href="HowItWorks.html#caution">HowItWorks</a> to see the correct way to link
controls to your Euphoria functions!
</td>
</tr>
</table>
<p>
Another possible error occurs when you create a GTK widget with a version of libgtk-3 which
does not implement that widget. You have 3 choices in this event: use something else, create your own
custom object to simulate the new widget, or update your version of libgtk-3.
The last is often not possible, usually you will
find it easier to
update to a newer Linux distro which includes the latest libgtk-3 instead.
</p>
<div class="scrn" style="width:100%">
<tt><pre>Fatal Error: GtkMenuButton
************ not implemented in this GTK library version</pre></tt></div>
<p>When you use a recently-implemented GTK widget in a program you plan to distribute, it is a good idea to check the
libgtk version and if necessary present an error message. Use the <i>requires()</i> function for this. See <a href="../test193.ex"> test193</a>.
</p>
<p>
There are several other flags you can set to display debugging info. See
<a href="HowItWorks.html#debugging">Debugging section </a> of HowItWorks.html
</p>
<a name="features" />
<h3><hr />New Features<hr /></h3>
<b>Icons</b>
<p>
Starting with GTK version 3.10, the old GTK stock items are deprecated, and new programs
should not use them. Instead, use named icons. This is good, because the set of stock buttons
was limited, and some were missing altogether. There's a far wider variety of named icons to choose from - except on Windows™, where there are very few. This is a problem which can be avoided by packaging your own custom icons with your program.
</p>
<p>You can most easily see
all the available icons by running <a href="../examples/icons.ex">examples/icons.ex</a>. It now has a handy search feature, which is a great help
when choosing the buttons and menus for your nifty new programs!
</p>
<p>
However, using named icons means more work for the programmer, usually involving several lines of
code just to create each button. To solve this problem and make the transition to named icons easier,
this version of EuGTK adds a new, more flexible way to create GtkButtons.<br clear="all" />
</p>
<img src="../screenshots/buttons.png" alt="buttons" />
<p>
<pre><code> <b>Old Style:</b>
<em class="kw">constant</em> btn1 = <em class="gtk">create</em>(GtkButton,<em class="str">"gtk-edit"</em>,...)
<em>-- button caption and icon are pre-set, not easily changed,</em>
<em>-- but nice-looking and easy to use. This is the leftmost button above.</em>
<b>New Style:</b>
<em class="kw">constant</em> btn1 = <em class="gtk">create</em>(GtkButton,<em class="str">"text-editor#_Edit"</em>,...)
<em>-- this uses a named icon and your own label.
-- Run <a href="../examples/icons.ex">examples/icons.ex</a> to search for a suitable icon.
-- These themed icons should change appearance to match the
-- current theme the user selects.</em>
</code></pre>
</p>
<p>
Please note the new hashtag# syntax:
<pre><code><em class="kw">constant</em> btn1 = <em class="gtk">create</em>(GtkButton,{<em class="str">"gtk-edit#_Edit"</em>,...}
<em>-- changing the caption and hot-key as desired
-- icon name is first, caption second, separated by #.
-- Optional underscore prepends the hot-key in caption
-- this button is shown above, center</em>
<em class="kw">constant</em> btn1 = <em class="gtk">create</em>(GtkButton,<em class="str">"~/demos/thumbnails/4_rhombuses.gif#_Colors"</em>,...)
<em>-- You can set the button image from a file (even animated!),
-- so you can customize your program's appearance.
-- You can even have "check images" that change depending
-- upon their state! (see <a href="../test15.ex">test15</a>)</em>
</code></pre>
<hr>
<b>ImageMenuItems</b>
<a href="../screenshots/imagemenu.png">
<img src="../screenshots/imagemenu.png" alt="image menu" title="Image Menu" align="right" width="300" float="left" /></a>
<p>
Someone now <i>[only temporarily, I hope]</i> in charge of GTK decided that having images on buttons and menu items was a bad idea.
They cite some academic study which 'proved' that people are quicker at choosing the correct button out of an array of buttons if the buttons contain
nothing but boring text captions.
</p>
<p>
Did this same 'academic study' prove that traffic signs didn't need to be different colors and shapes? If not, why not?
</p>
<p>
So they're gone as of GTK3.14.
I guess they don't want people with dyslexia to use their computers.
</p>
<p>
If you don't like images, you don't have to use 'em, but if you do like them,
don't worry too much, I can outsmart them and put those images back. See, for example, <a href="../test25.ex">test25</a>.</p>
<hr>
<p><b>Interactive Debugger</b></p>
<p>
This change is actually a <i>good idea</i>. You can, starting with GTK3.14, enable a pop-up
GTK+ Inspector by adding one line of code just before the call to main():
<pre><code> <em class="gtk">show_all</em>(win)
<em class="gtk">set</em>(win,<em class="str">"interactive debugging"</em>,TRUE)
<em class="gtk">main</em>()
</pre></code>
</p>
<p>
This interactive debugger allows you to view the widget hierarchy and experiment with various settings
<i>while your program is running!</i> It also lists the applicable properties and signals for each selected widget.</p>
<hr />
<p><b>New Types</b><br /><br />
Gtk widget types have been added to EuGTK. You can now declare Euphoria objects as GTK types,
as follows:
<code><pre>
<em class="kw">function</em> Foo(<em class="gtk">Window</em> w, <em class="gtk">Button</em> b)
</pre></code>
As you can see, you just use the Gtk widget name, <i>sans</i> the 'Gtk' part.
It's generally <i>not</i> necessary nor even a good idea to use these.
They are provided mainly for use in the rare occasion where it is necessary to
register and "type cast" a Euphoria function parameter. Most objects passed as
function params already 'know' their type, as do all that are created as Eu
constants, objects, or atoms, so this is seldom necessary.
</p>
<hr />
<p><b>Settings</b><br /><br />
The ability to very easily save selected settings from one run to the next has been added in EuGTK 4.10.0.
This includes saving the state of active controls, such as spin buttons, check buttons, color buttons,
font buttons, etc. as well as saving specified properties of any GtkWidget, such as the preferred background color,
font, position and size of windows, etc., from run to run. You can do this without having to write lines of code to save, parse, and restore each setting. Just supply the name
of an .ini file and a list of control handles you wish to save/restore to the save_settings() or load_settings() functions.
</p>
<p>
Refer to <a href="../test153.ex">test153.ex</a>, <a href="../resources/test153.ini">test153.ini</a>,
<a href="../test173.ex">test173.ex</a>, <a href="../resources/test173.ini">test173.ini</a>,
<a href="../test201.ex">test201.ex</a>, and <a href="../resources/test201.ini">test201.ini</a> for some examples. Below is a sample
file, which can have any name and extension. (<i>.ini</i> works fine, and is familiar) Note that the file is plain text, so it's easily edited, and comments are preserved when it is updated.
</p><pre><em>----------------------------------------------------------------------------
-- Following items are 'persistent', only changed by editing this file:
----------------------------------------------------------------------------</em>
--!MainWindow.icon=<em class='green'>face-smile</em>
--!MainWindow.border width=<em class='orange'>20</em>
--!Label1.text=<em class='green'>Move, resize, change color, etc...</em>
--!ColorChooserButton.tooltip text=<em class='green'>Pick a color for the Main Window background</em>
--!Font Button.tooltip text=<em class='green'>Select font for calendar</em>
<em>------------------------------------------------------------
-- Items beginning with + are added via the settings:Add()
-- function called in your program code, as they are not a
-- default property as defined in GtkSettings.e
-- They can also be added by manually editing the ini file.
-- Items without the leading + sign are saved automatically,
-- by passing a list of names or handles of controls to
-- the settings:Save() function.
-- You may also save and restore widgets named data spaces
-- by settings:Add(ini,ctl,"data.name","value")
-- see MainWindow.data lines in blue below.
------------------------------------------------------------</em>
<em class='blue'>
+MainWindow.data.Foobar=<em class='green'>Baz!</em>
+MainWindow.data.Message=<em class='green'>Thanks a lot!</em></em>
+MainWindow.background=<em class='orange'>#FCE94F</em>
+MyCalendar.font=<em class='green'>TakaoPGothic Bold Italic 12</em>
ColorChooserButton.rgba=<em class='orange'>#FCE94F</em>
Font Button.font name=<em class='green'>TakaoPGothic Bold Italic 12</em>
MyCalendar.date=<em class='orange'>{2016,6,8}</em>
</pre>
</p>
<a name="syntax" />
<h3><hr />New Syntax<hr /></h3>
<p>
In order to make programming even easier, I've added a new way to set
properties at the time a widget is created. This doesn't replace the previous set(... functions, just
allows you to use a shorter method if you wish. It may be faster than
the old method, since it can avoid multiple lookups.
<pre><code><em class="kw">constant</em> win = <em class="gtk">create</em>(GtkWindow,{
{<em class="str">"title"</em>,<em class="str">"Simple Text Viewer"</em>},
{<em class="str">"default size"</em>,600,500},
{<em class="str">"position"</em>,GTK_WIN_POS_CENTER},
{<em class="str">"icon"</em>,<em class="str">"~/demos/thumbnails/mongoose.png"</em>},
{<em class="str">"connect"</em>,<em class="str">"destroy"</em>,<em class="str">"Quit"</em>}})
</code></pre></p>
<p>
In simple cases, an even easier-to-use syntax is possible using key/value pairs.
See screenshot at top of page.
<pre><code><em class="kw">constant</em> win = <em class="gtk">create</em>(GtkWindow,
<em class="str">"title=Hello world!,size=300x100,background=green,border=10"</em>)
</code></pre></p>
<p>You can freely mix these styles in your program, using whichever notation is the cleanest and clearest.
Because this last version uses Eu 4.0 key/value pairs, not all settings can be made this way. You can't, for
example, pass Eu variables or Gtk constants as part of the settings string, except for the constants TRUE, FALSE, HORIZONTAL, and VERTICAL,
which are specifically allowed.
</p
<a name="custom dialogs" />
<h3><hr />Custom Dialogs<hr /></h3>
<p>
EuGTK 4.11.0 has a Custom dialog which allows adding almost any widget(s) to an easy-to-use pop-up dialog,
with basically one line of code. See <a href="dialogs.html">dialogs.html</a> and <a href="../test87.ex">test87.ex</a> for details.
</p>
<a name="Plug and Socket" />
<h3><hr />Plug & Socket<hr /></h3>
<p>
A plug and socket demo (plug.ex, sock.ex) has been added, to
allow embedding widgets from one process into another process.
I haven't been able to dream up a real need to do this so far.
</p>
<small>
<p><i><em>To Do:</em> find a useful program that needs this!</i></p>
</small>
<a name="plugins" />
<h3><hr />Plugins<hr /></h3>
<p>
EuGTK 4.8.9 has a new 'plug-in' feature, added in order to
implement the GtkSourceView and WebKit widgets.
</p>
<hr />
<h4>SourceView</h4>
<figure style="float:right; border:solid thin black;" align="right">
<img src="../screenshots/test201.png" alt="SourceView" title="SourceView" width="400"/>
<figcaption> <small><i>New GtkSourceView plugin</i></small></figcaption>
</figure>
<p>
The SourceView widget offers automatic language recognition and syntax highlighting
for a huge number of programming languages (about 110, I think).
</p>
<p> I've put the SourceView functions into a plugin. This loads the additional required shared library and the links to the functions contained in that library.
You only need to include the <a href="../GtkSourceView.plugin">GtkSourceView.plugin</a> when you want to use this
editor widget.
</p>
<p>A set of syntax files for Euphoria 4.0 by Mario Steele can be found in /demos/resources/gedit-syntax.
Just copy them as instructed in the README.
</p>
<p> One reason for making this a plugin is that some installations don't automatically
include the GtkSourceView library. Making the sourceview code an integral part of GtkEngine.e would cause
problems if the sourceview library could not be found. A second reason; having it separate makes it easier for me to continue adding sourceview functions. Currently only a few are implemented, but it is useful nevertheless. I use it to edit these web pages and my demo programs. See <a href="../test201.ex">test201</a>).
</p>
<small>
<p><i><em>To Do:</em> implement code completion and search functions</i></p>
</small>
<hr />
<figure style="float:right; border:thin solid black;">
<img src="../screenshots/webkit_test.png" alt="Webkit" title="Webkit demo" align="right" width="400" />
<figcaption><small><i> Webkit demo</i></small></figcaption>
</figure>
<h4>WebKit</h4>
<p> EuGTK also includes a <a href="../GtkWebKit.plugin">WebKit plugin</a>,
which allows you to incorporate a web browser widget into your program.
You are free to implement - in Euphoria! - features that may
not even be available on Firefox™ or Chrome™!
</p>
<p>
The WebKit plugin includes a pop-up Web Inspector, similar to that in
Firefox™ and Chrome™.
</p>
<p>Like the SourceView, this plugin is still under development, but is quite usable already.
See <a href="../examples/webkit.ex">examples/webkit.ex</a>
</p>
<small>
<p><i><em>To Do:</em> implement security and script-running features</i></p>
</small>
<a name="broadway" />
<br clear="all" />
<h3><hr />Broadway Server<hr /></h3>
<a href="../screenshots/broadway.png">
<figure style="float:right; border:thin solid black;">
<img src="../screenshots/broadway.png" alt="Broadway" title="Broadway" align="right" width="400" />
<figcaption><small><i> EuGTK running on Broadway server in Firefox™ browser window</i></small></figcaption>
</figure>
</a>
<p>
With the latest versions of GTK, you can specify the Broadway server
(broadwayd) to run your EuGTK programs, and view them on
any connected device which has an up-to-date HTML5 web browser such as Firefox™. Neither Euphoria nor EuGTK are required on the client!
</p>
<p>
The Broadway server that comes with Mint 18 works GREAT!. Over 95% of the 200+ demos work
with Firefox 47.0, and most of those that fail could probably could be modified to work.
</p>
<p>I have had as many as 50 EuGTK programs running simultaneously in
a single Firefox browser window, while only using about 50% CPU.
</p>
<a name="bear" />
<h3><hr />BEAR<hr /></h3>
<figure style="float:right; border:thin solid black;">
<a href="../screenshots/Screenshot-12.png">
<img src="../screenshots/Screenshot-12.png" alt="bear" width="400px" align="right" title="Click for a larger view" />
</a>
<figcaption><small><i> The BEAR</i></small></figcaption>
</figure>
<p>
That's an acronym for a small program, a little over 800 lines of code, which took a couple of days
to write and test.
</p>
<p>Since it's written in Euphoria, the single source code file is only 21.5k in length,
<p>The BEAR has already been used extensively to edit these doc pages. If you look at the raw
html, you'll see how much cleaner
it is now than before :)
</p>
<p>Encorporating a full-fledged web browser widget similar to Firefox™, and a source-code
editor which can recognize and colorize over 100 programming languages, this allows me to
browse and edit html pages, and if those pages contain links to source code, display and
edit the source. If the source is Euphoria, you can also test run the program!
(Other languages could easily be added.)
</p>
<p>
The web browser panel has buttons to zoom in / out, and the editor panel
has selectable fonts, optional line numbers and the ability to make visible
"white space" characters, such as spaces and tabs.
</p>
<p>
When html pages are edited, the Web view is refreshed whenever the editor
Save button is clicked, so that changes are instantly visible.
</p>
<p>
Modified source code is saved to temp files for the test run.
Your BEAR preferences are stored in a hidden file:
<i>.bear.ini</i> located in your $HOME directory.
</p>
<p>The BEAR requires the latest versions of both libgtksourceview-3 and libwebkit2gtk-3.</p>
<a name="c" />
<h3><hr />Compared to C<hr /></h3>
<p>
Below is a simple "Hello World!" program written in C, taken from the GTK docs
(with comments removed). Following that is the same program written in EuGTK.
</p>
<table width="90%">
<thead>
<th>
C Code
</th>
</thead>
<tbody>
<tr>
<td>
<code><pre>
#include <gtk/gtk.h>
static void
print_hello (GtkWidget *widget,
gpointer data)
{
g_print ("Hello World\n");
}
static gboolean
on_delete_event (GtkWidget *widget,
GdkEvent *event,
gpointer data)
{
g_print ("delete event occurred\n");
return TRUE;
}
int
main (int argc,
char *argv[])
{
GtkWidget *window;
GtkWidget *button;
gtk_init (&argc, &argv);
window = gtk_window_new (GTK_WINDOW_TOPLEVEL);
gtk_window_set_title (GTK_WINDOW (window), "Hello");
g_signal_connect (window, "delete-event", G_CALLBACK (on_delete_event), NULL);
g_signal_connect (window, "destroy", G_CALLBACK (gtk_main_quit), NULL);
gtk_container_set_border_width (GTK_CONTAINER (window), 10);
button = gtk_button_new_with_label ("Hello World");
g_signal_connect (button, "clicked", G_CALLBACK (print_hello), NULL);
g_signal_connect_swapped (button, "clicked", G_CALLBACK (gtk_widget_destroy), window);
gtk_container_add (GTK_CONTAINER (window), button);
gtk_widget_show (button);
gtk_widget_show (window);
gtk_main ();
return 0;
}
</pre></code>
</td>
</tr>
<thead>
<th>Euphoria</th>
<thead>
<tbody>
<td>
<pre><em>-----------------------------------------------------------------
-- Purpose:
-- Show a window with a button; when the button is clicked,
-- print "Hello World" on the terminal, then exit.
---------------------------------------------------------------------</em>
<b>include</b> GtkEngine.e
<em class="kw">constant</em> window = <em class="gtk">create</em>(GtkWindow,
{<em class="str">"title"</em>,<em>"Hello"</em>},
{<em class="str">"border width"</em>,<em>10</em>},
{<em class="gtk">"connect"</em>,<em class="str">"destroy"</em>,<em>"Quit"</em>},
{<em class="gtk">"connect"</em>,<em class="str">"delete-event"</em>,<em>"on_delete_event"</em>}})
<em class="kw">constant</em> button = create(GtkButton,
{<em class="str">"label"</em>,<em>"Hello World"</em>},
{<em class="gtk">"connect"</em>,<em class="str">"clicked"</em>,<em>"print_hello"</em>},
{<em class="gtk">"connect"</em>,<em class="str">"clicked"</em>,<em>destroy</em>,window}})
<em class="gtk">add</em>(window,button)
<em class="gtk">show_all</em>(window)
<em class="gtk">main</em>()
<b>global<em class="kw"> function</em></b> print_hello()
<em class="kw">puts</em>(1,<em class="str">"Hello World\n"</em>)
<b>return</b> FALSE
<b><em class="kw">end function</em></b>
<b>global<em class="kw"> function</em></b> on_delete_event()
<em class="kw">puts</em>(1,<em class="str">"delete event occurred\n"</em>)
<b>return</b> FALSE
<b><em class="kw">end function</em></b>
</pre>
</td>
</tr>
</tbody>
</table>
<p>Now you know why C programmers grow bald at an earlier age than others.</p>
<p>
Even with this simple program, you can see the difference. As C programs grow larger,
they become increasingly littered with type-casts, pointer references, etc.,
while the Euphoria code remains shorter and much more readable.
</p>
<p>
For example, compare the following two equivalent lines of code:
<ul>
<li><em class="kw">gtk_window_</em>set_title <em class="kw">(GTK_WINDOW (</em> <i>window</i><em class="kw">)</em>, "Hello"); <em>/* C */</em></li>
<li><em class="gtk">set</em>(<i>window</i>,<em class="str">"title","Hello"</em>) <em>-- Euphoria </em></li>
</ul>
The code shown in blue is required because C is not object-oriented, so you must specify the correct routine to be
called, and must tell C what type of object the <i>window</i> variable is. EuGTK tracks objects as they are
created, so it knows which routine to call, and what type of object it is dealing with without
the programmer having to specify each time.
</p>
<p>
Or to put it another way, the C code is full of distracting 'noise', while Euphoria is cleaner and quieter. Other than that,
the program structure is in other respects pretty similar, so that you <i>can</i> port a C or Python program to Eu in many cases without
much difficulty. I've done just that for many of the test programs in this package.
</p>
<a name="changes"></a>
<h3><hr />Recent Changes<hr /></h3>
<p>
<em>4.11.5</em>: To make space for new openGL graphics, the seldom-used <b>Pango</b> text and <b>Cairo</b> drawing functions have been moved to their own include:
GtkCairo.e. If your program uses Cairo graphics or PangoFont calls, the only change needed in your source code is to include GtkCairo.e following GtkEngine.e. See <a href="../test60.ex">test60</a> for example.
</p>
<a name="weemods"></a>
<h3><hr />Wee Help Mod<hr /></h3>
<p>To add <b>[F1]</b> pop-up html help for
Gtk widgets, as well as Euphoria keywords,
make the change shown below to wee.exw:<pre><code>
<em class="kw"><b>global</b> procedure</em> context_help()
<em class="kw">sequence</em> text, decls, word, name_space, path
<em class="kw">integer</em> pos, junk
<em class="kw">object</em> help
text = get_edit_text()
pos = get_pos()
word = word_pos(text, pos)
<em class="kw">if length</em>(word) < 2 then
name_space = <em class="str">""</em>
word = <em class="str">""</em>
else
name_space = word[2]
word = word[1]
<em class="kw">end if</em>
<em>-- add the following 4 lines to add pop-up GTK help:</em>
<em class="kw">if match</em>("Gtk",word) = 1 <em class="kw">then</em>
ui_show_uri(<em class="str">"FILE://"</em> & <em class="kw">canonical_path(sprintf</em>(<em class="str">"~/gtk3/%s.html"</em>,{word})))
<em class="kw">return</em>
<em class="kw">end if</em>
<em>-- my GTK docs are in a gtk3 folder in my home directory
-- adjust as necessary for your setup.</em>
</code></pre>
</p>
<a name="platforms"></a>
<h3><hr />Tested Platforms:<hr /></h3>
<table class="testing" border="thin, black">
<thead>
<tr>
<th colspan="5"><em>Tested with</em></th>
</tr>
<tr class="subtitle">
<th>Euphoria</th>
<th>GTK</th>
<th>Distro</th>
<th>Arch</th>
<th>Platform</th>
</tr>
</thead>
<tbody>
<tr>
<td>4.0.4</td><td>3.0.8</td><td>Ultimated Edition 3.0</td><td>32-bit </td>
<td>AMD Athlon II X2 220 processor, 2800mhz, 4gig</td>
<tr>
<td>4.0.5</td><td>3.0.8</td><td>Ultimated Edition 3.0</td><td>32-bit </td>
<td>AMD Athlon 64x2 processor, 1000mhz, 873meg</td>
</tr>
<tr>
<td>4.0.5</td><td>3.2.0</td><td>Mint 12 <em>*</em></td><td>32-bit</td>
<td class="ba">Pentium M processor, 1500 mhz. 487 megs</td>
</tr>
<tr>
<td>4.1.0</td><td>3.0.8</td><td>Mint 11</td><td>32-bit</td>
<td class="ba">Pentium M processor 1.5ghz, 512meg</td>
</tr>
<tr>
<td>4.1.0</td><td>3.4.1</td><td>Luninux (Ubuntu 12.04)</td><td>64-bit </td>
<td rowspan="6" class="bb">AMD Athlon II X2 220 processor, 2800mhz, 4gig</td>
</tr>
<tr>
<td>4.1.0</td><td>3.4.2</td><td>Mint 13 <em> *</em></td><td>64-bit</td>
</tr>
<tr>
<td>4.1.0</td><td>3.6.0</td><td>Mint 14<em> * </em></td><td>64-bit</td>
</tr>
<tr>
<td>4.1.0</td><td>3.6.2</td><td>Manjaro xfce 0.8.3-x86-64 <em>*</em></td><td>64-bit</td>
</tr>
<tr>
<td>4.1.0</td><td>3.6.4</td><td>Mint 15 Mate <em>*</em></td><td>64-bit</td>
</tr>
<tr>
<td>4.1.0</td><td>3.8.4,</td><td>Mint 16 Cinnamon <em>*</em></td><td>64-bit</td>
</tr>
<tr>
<td class="note" colspan="4"><center>No longer testing on older platforms listed above.</center></td>
<td class="ba"><small>Above, 14-year-old laptops</small></td>
</tr>
<tr>
<td>4.1.0 rev. 4467,</td><td>3.10.6</td><td>Parsix 4.0 (Gloria) <em>*</em></td><td>64-bit</td>
<td rowspan="14" class="bc">Intel Core 2 Quad CPU 2.33 ghz 8 gig</td>
</tr>
<tr>
<td>4.1.0 rev. 5783</td><td>3.8.4</td><td>Mint 16 <em>*</em></td><td>64-bit</td>
</tr>
<tr>
<td>4.1.0</td><td>3.10.2</td><td>SalentOS (Ubuntu 14.04)<em> *</em></td><td>64-bit</td>
</tr>
<tr>
<td>4.1.0 rev. 6238</td><td>3.10.8</td><td>Mint 17 Cinnamon<em> *</em></td><td>64-bit</td>
</tr>
<tr>
<td>4.1.0</td><td>3.10.8</td><td>Mint 17 Mate <em>*</em></td><td>64-bit</td>
</tr>
<tr>
<td>4.1.0</td><td>3.14.7</td><td>Ubuntu Vivid 3.18.0-9-generic <em>*</em></td><td>64-bit</td>
</tr>
<tr>
<td>4.1.0</td><td>3.6.4</td><td><em>Windows 7</em></td><td>64-bit</td>
</tr>
<tr>
<td>4.1.0 b2</td><td>3.10.8</td><td>Mint 17 <em>*</em></td><td>64-bit</td>
</tr>
<tr>
<td>4.1.0 b2</td><td>3.14</td><td>Ubuntu Vivid</td><td>64-bit</td>
</tr>
<tr>
<td>4.1.0 development</td><td>3.16.6</td><td>Ubuntu MATE 15.10 <em>*</em></td><td>64-bit</td>
</tr>
<tr>
<td>4.1.0 rev. 6318</td><td>3.16.6</td><td>Mint 17 <em>*</em><small> works fine!</small></td><td>64-bit</td>
</tr>
<tr>
<td>4.1.0 rev. 6318</td><td>3.18.9</td><td>Ubuntu 16 <em>*</em><small> has a few bugs</small></td><td>64-bit</td>
</tr>
<tr>
<td>4.1.0 rev. 6318</td><td>3.18.9</td><td>Mint 18 <em>*</em></td><td>64-bit</td>
</tr>
<tr>
<td>4.1.0 rev. 6318</td><td>3.20.2</td><td>Windows™ 7</td><td>64-bit</td>
</tr>
<tr class="note">
<td colspan="2" style="border:none"></td>
<td><em><big><b>*</b></big></em> Best results</td>
<td colspan="2" style="border:none"></td>
</tr>
</table>
<a name="history" />
<table class="testing" border="thin, black">
<tr>
<th colspan="2"><em>History</em></th>
</tr>
<tr>
<td>EuGTK 4.6.7</td><td>Added GtkPrinter.e, an engine to handle most common printing tasks!</td>
</tr>
<tr>
<td>EuGTK 4.6.9</td><td>Modified Kenneth Rhodes' gneui.ex to parse ex.err and position Geany editor at error position.</li>
</tr>
<tr>
<td>EuGTK 4.7.0</td><td>Complete re-write to make the code cleaner and hopefully faster!
<tr>
<td>EuGTK 4.7.5</td><td>Major code cleanup, new features, improved documentation, more demos!</td>
</tr>
<tr>
<td>EuGTK 4.7.6</td><td>Updated GtkPrinter.e and documentation.</td>
</tr>
<tr>
<td>EuGTK 4.8.0</td><td>Update for new GTK versions and bug-fix</td>
</tr>
<tr>
<td>EuGTK 4.8.1</td><td>Changes and tests to work with GTK 3.10+</td>
</tr>
<tr>
<td>EuGTK 4.8.6</td><td>Improved ListView functions & documentation, new button and menu options.</td>
</tr>
<tr>
<td>EuGTK 4.8.7</td><td>Improved Glade compatibility, added new Glade demos.</td>
</tr>
<tr>
<td>EuGTK 4.8.9</td><td>Implemented Glade namespacing, new button images</td>
</tr>
<tr>
<td>EuGTK 4.9.0</td><td>Windows 7™, 64-bit tests run 85% successfully! OS X™ also reported to work.</td>
</tr>
<tr>
<td>EuGTK 4.9.5</td><td>Updated GtkSettings.e, added plugin capability.</td>
</tr>
<tr>
<td>EuGTK 4.9.8</td><td>Bug fixes, inproved Windows™ compatibility.</td>
</tr>
<tr>
<td>EuGTK 4.9.9</td><td>Broadway server - run EuGTK programs over network! No Euphoria or GTK required on clients!</td>
</tr>
<tr>
<td>EuGTK 4.10.0</td><td>Added convenient functions to save control values and states to a
config or ini type file.</td>
</tr>
<tr>
<td>EuGTK 4.10.1</td><td>Added demos of GtkSourceView and GtkWebKit plugins.</td>
</tr>
<tr>
<td>EuGTK 4.11.0</td><td>Updated demos and documentation. Tested new GTK 3.16 widgets and functions.</td>
</tr>
<tr>
<td>EuGTK 4.11.2</td><td>Added plug/socket demo, updated plug-ins, improved GtkPrinter, fixed some memory leaks.</td>
</tr>
<tr>
<td>EuGTK 4.11.4</td><td>Fixed most (hopefully, all) memory leaks, added SourceView functions.</td>
</tr>
<tr>
<td>EuGTK 4.11.5</td><td>Moved Cairo functions to a separate include; graphics will use GtkGLArea in the future.</td>
</tr>
<tr>
<td>EuGTK 4.11.6</td><td>Updated numerous programs & documentation, added new browser program and BEAR.ex</td>
</tr>
<tr>
<td>EuGTK 4.11.7</td><td>Improved httpd.ex and webserver.ex; colorized documentation sourcecode; debugged the BEAR :)</td>
</tr>
<tr>
<td>EuGTK 4.11.8</td><td>Improved httpd.ex, added GTK 3.21 functions</td>
</tr>
<tr>
<td>EuGTK 4.11.9</td><td>Debugged and tested on Windows 7™; about 80% working.</td>
</tr>
<tr>
<td>EuGTK 4.11.10</td><td>Windows™ debugging, improved stability of the BEAR.</td>
</tr>
<tr>
<td>EuGTK 4.11.11</td><td>Broadway server works with 90% of demos! (Mint 18); more stable BEAR!</td>
</tr>
<tr>
<td>EuGTK 4.12.0</td><td>95% of demos run on Windows 7,<br />added style chooser to SourceView editor.</td>
</tr>
<tr>
<a name="legal" />
<th colspan="2"><em>Disclaimer</em></th>
</tr>
<tr>
<td colspan="2"><small>With the many different options available, I cannot guarantee that everything
will work 'just fine' everywhere. <br />Different platforms, window managers,
themes, and unpredictable user-settings make this impossible.<br />
If you want to be sure your program will work
on a given computer, send me your program and the computer, I'll be glad to test it,
providing I can keep the computer afterward :)</small></td>
</tr>
</tbody>
</table>
</content>
<footer>
<div class="hint">
<img class="hint" src="../thumbnails/mongoose.png" alt="hint" align="left" float="right" />
<p>
This page edited by The <a href="../BEAR.ex">Bear</a>,
a web-page and programming editor
written in <a href="OpenEuphoria.org">Euphoria</a>.
</p>
<p>
Updated for EuGTK version 4.12.0, Sept 15, 2016<br />
All code © 2016 by Irv Mullins
</p>
</div>
</footer>
</body>
</html>
