For more exhaustive - not to mention exhausting! - documentation,
see the GTK 3.0 docs
get(mouse,"position")
The GtkFixed widget lets you lay out things the Windows™ way, which is - no surprise - the wrong way.
Quote from the GTK docs:
"For most applications, you should not use this container! It keeps you from having to learn about the other GTK+ containers, but it results in broken applications. With GtkFixed, the following things will result in truncated text, overlapping widgets, and other display bugs:
In addition, the fixed widget can't properly be mirrored in right-to-left languages such as Hebrew and Arabic. i.e. normally GTK+ will flip the interface to put labels to the right of the thing they label, but it can't do that with GtkFixed. So your application will not be usable in right-to-left languages.
Finally, fixed positioning makes it kind of annoying to add/remove GUI elements, since you have to reposition all the other elements. This is a long-term maintenance problem for your application. "
This is good advice. If you choose to ignore it, you'll have to do a lot of extra work, only to find that users are upset that your programs don't work as they expect well-behaved Linux programs to work.
Window Icons are the small icons that appear on the titlebar (see mongoose at far left), but where
these appear, and whether they appear at all, depends upon the theme in use. If you don't see
these in the demos, try changing your window theme.
Icons can be made from .jpg, .png, .gif, etc... files, gtk-stock items, or named icons from your current theme. Run test39 to see stock items, and examples/icons.ex to view and enumerate available theme icons in themeicons.txt.
There are several ways to modify fonts. For text controls, such as labels:
set(ctl,"font","Courier 12") -- set font and size
set(ctl,"font","36") -- sets size only, keep user's font preference
set(ctl,"font","italic") -- italicises user's preferred font. Try also 'bold', 'bold italic', etc.
You can specify several possible fonts. Gtk will use the first one it finds on the computer, so put your choice as the first on the list. If you want to specify a point size, put it last on the list (not separated with a comma!)
set(ctl,"font","Century Schoolbook L, Serif, Purisa, Bitstream Charter")
set(ctl,"font","Purisa, Courier, Sans 18") -- first valid font will be shown in 18pt
set(ctl,"markup","This is some <b>marked-up</b> <i>text</i>") -- styling text using a subset of HTML markup set(ctl,"markup","<span font='Sans 24' color='red'>Hello</span>") -- selecting font style and size using markupSee Pango Markup for details on the available markup attributes.
In certain situations where you need more control, such as fonts with drop shadows, you might consider using CSS to change fonts. The CSS can be loaded either from a standard *.css file, or inline in your program. Example: test72 and mystyle.css
The GTK docs have some detailed info on css options.
When writing a program which uses a GtkFontButton, GtkFontChooser or GtkFontDialog, you will probably want to have some control over which fonts are shown in the list of available fonts. You can do this by writing a simple filter function to examine the font names and/or font face names, and returning TRUE if that font should be shown in the dialog, or FALSE if not.
Then set the font button or font dialog filter function to your filter routine:
set(btn,"filter func",_("MyFontFilter"))
See test201 for an example.
In the transition to using CSS to control GTK widget appearance, some of the frame attributes have been lost, meaning that the style settings (raised, sunken, etc) don't have any effect. Therefore, if the exact appearance is important, you may have to use both the old-style settings plus the new CSS styling below.
Support for styling GTK apps with css is improving. You can create some interesting effects, such as creating decorative backgrounds, rounded corners on buttons and frames, and 'animated' buttons which change color when mouse passes over or clicks them.
See test138 and test157 for examples.
New in EuGTK4.11.2 you can load css directly in-line, without using a separate .css file. See test160.
An alternative to css in some cases can be to use an ini file to control colors and styles of specific widgets. See test153 and test173.
EuGTK has greatly simplified GTK color managment. You can specify colors in various ways - as hex values: #FF0000, quoted hex: "#FF0000", as Red/Green/Blue strings: "rgb(255,0,0)" or "rgba(255,0,0,0.5)" if you want to set alpha transparency.
The best way, however, is by name. The names used are the xcolor names. See xcolors.txt. Case doesn't matter.
For normal GTK widgets, you can set foreground color, which generally applies to labels, fonts, etc. and background color, which applies to windows, etc., but not labels, which have a transparent background. Setting the background color for a container such as a GtkBox does nothing, as these containers have a transparent background, but setting the box's foreground color will affect any labels added to the box.
You can determine what will happen by examining the 'properties' of a given widget, as well as the widget's ancestor properties - or, you can do this the easy way: just set a color and see what happens.
Generally, 'color' can be used as a more-logical synonym for 'foreground' when setting widget colors. Widget colors may also change depending upon the widget's 'state': mouse-over, pressed, selected, insensitive etc. To set these state colors, use 'override color' and 'override background color'. Whether or not these work depends entirely on the window manager preferences.
When you are drawing with Cairo, you have several ways to choose a drawing color:
GTK has a GtkBuilder object which can parse XML markup to create your user interface. This means you can use Glade to build the interface 'visually', rather than coding it by hand. You should try to update Glade so that it knows about the latest GTK3 objects. Glade 3.16.1 seems to work ok, older versions, not so much.
The latest versions of EuGTK (4.9.0 and up) have improved functions for working with Glade, including namespacing which works in a manner similar to Euphoria's namespacing, and access to Glade objects by name (in string form) rather than via pointer.
See EuGTK and Glade and Glade examples in ~/demos/glade.
Images can be created from almost any graphic file format: .jpg, .png,
.tiff, .gif, .xpm.... etc. simply by specifying the filename:
constant img = create(GtkImage,"~/demos/thumbnails/mongoose.png")
-- canonical_path() is automatically called to correct the filepath
Sometimes this is not what you want.
If you need to re-use an image without having to reload it repeatedly,
or if you need to change its size, then you should load the image into
memory as a pixbuf, and create your image(s) from that pixbuf (which can be re-used).
constant pix = create(GdkPixbuf,"~/demos/thumbnails/mongoose.png")
-- note that this call is to GdkPixbuf, not GtkPixbuf!
constant img = create(GtkImage,pix)
Notes: When calling create(GdkPixbuf,...)
In addition, images can be created from GtkStock items (deprecated),
or from named icons.
When using named icons, you can specify a size for the icon, either as one of
the GTK_ICON_SIZE enums, or in pixels, or omit the size altogether:
constant oops = create(GtkImage,"face-surprise",GTK_ICON_SIZE_DIALOG) -- see GTK_ICON_SIZE_ enums
constant oops = create(GtkImage,"face-surprise",128) -- width in pixels
constant oops = create(GtkImage,"face-surprise") -- 'natural' size
You cannot (AFAIK) load named icons into GdkPixbufs. If you need to do this, convert the icon into a .png or .jpg, using a graphic program such as the Gimp.
In EuGTK 4.10.0+, there's a simple utility to convert .xpm image files into Euphoria includes. When imported as a normal include.e file, the image(s) become part of the source code, and are bound into the executable, so you can distribute a bound, shrouded, or compiled program without having to also distribute a number of related image files. See ~/demos/examples/xpm_include_test.ex
Quote from the GTK docs:
"GTK+ has an extremely powerful framework for multiline text editing."
With power comes complexity, because it has to deal with multi-byte characters, different text directions, input methods, fonts, etc... See test59.
The good news; it does work, and for most purposes, it will not be necessary to delve into the arcane commands too deeply. After all, you are not likely to write a full-fledged rich-text editor in Euphoria, since there are dozens of these things already freely available.
Beginning with EuGTK 4.10.0, there's a GtkSourceView plugin which can be added to EuGTK. This will allow your program to view/edit syntax-colored source code for over 100 different programming languages.
Only the most important parts of the SourceView widget have been 'wrapped' so far, but the control is already quite usable. I even use it for editing these html pages. Additional features, such as auto-completion, searching, etc. will be added as time permits.
Also, there's a plug-in for LibWebKit, which adds a web browser 'widget' to EuGTK. This includes a pop-up 'inspector', which works very nicely.