# Alphabetical Guide

<heading>

##

EuGTK 4.12.0

### Alphabetical guide to GTK widgets

</heading> Buttons below link to at least one example of each control:
For more exhaustive - not to mention exhausting! - documentation, see the GTK 3.0 docs
A

- AboutDialog test25, test28
    a pre-built pop-up dialog to display credits, license, etc...
- Accelerators test25, test80, test144
- Adjustment test82, test83, test154
- Alignment
    (deprecated, use 'align' and 'margin' properties instead)
- Animated gifs test10
    on buttons: test102
- AppChooserButton test123
    choose approprite app based on filetype
- AppChooserDialog test115
    as above, but as a pop-up dialog
- AppChooserWidget test124
  as above, but as a widget to add to your program window
- Arrows test93
    (deprecated as of GTK 3.14 - use icons instead)
- AspectFrame test140, test161
    a frame which maintains its relative proportions when resized
- Assistant test62
    a step-by-step guide for your users, helpful for program installation, setup, etc...
- Auto-scrolling text test130
    (implemented with a timer

B

- Background
    colors: test25
    images: test72 uses mystyle.css
    gradients see CSS below
    - linear: test158 uses mystyle3.css
    - radial: test157 uses mystyle2.css
- Browsing Cows test188
    a simple demo
- Builder Please read the Glade instructions
    Also, see note below
- Built-in EuGTK Dialogs See Dialogs
- Buttons ~ All: test19
  - stock: test39
  - toggle: test104
  - check: test104
  - switch: test15
  - default: test146
  - custom: test104
  - layout, alignment test29
- ButtonBox automatically arranges sets of buttons
  - test7
  - Using Icons test59
  - Margins and Layout test195
  - Layout and ChildSecondary test186

C

- Cairo graphics test60, test61, test65
- Calendar test31
    See Calendars
- CellRendererCombo test121
    drop-down selections in lists
- CellRendererPixbuf test35, test116
    display images in list rows
- CellRendererProgress test33
    display progress bars in list rows
- CellRendererSpin test148
    display numeric input in list rows
- CellRendererText test33, test96
    display text in list rows
- CellRendererToggle test35, test96
    display toggle or check buttons in list rows
- CheckButton test13, test15
- CheckMenuItem test54, test25
- Clipboard
  - paste image: test92
  - paste text: test91
  - monitoring the clipboard test90
- Colors see RGBA Colors
    see also CSS below
- ColorButton test59
    small button to select colors
- ColorChooserDialog test185
    pop-up dialog to select colors
- ColorChooserWidget test169
    widget to add to your window to select colors

- ComboBox test116
    choose from a drop-down list of options
- ComboBoxEntry test16.ex
    as above, but includes an input box so user can type in an unlisted item
- ComboBoxText test12
    as above, but easy-to-use for simple text options
- Control 'data' fields test22
    associative lists to pass data via control actions

- CSS see CSS note below
  - background images: test72
  - radial gradient: test157
  - linear gradient: test158
  - as inline data: test160
  - Animated images: test211
  - css backgrounds: test212
- Custom cursors test2
- Custom buttons test29, test104, test102 See also new features
- Custom dialogs test200
- Custom tooltips test64, test134

D

- Data Passing
    attaching data items to controls, see Data Passing
- Decorated property test110
    creates window without title-bar, etc. use with caution!
- delete-event (trapping) test114
- Default buttons test4, test13, test14
- Dialogs built-in dialogs, see: dialogs.html
- Display status test76
    (screen size, pointer location, etc.)
- Drawing with Cairo
  - complex demo with numerous examples: test60
  - graphics primitives: test61
  - shapes, borders and transparency: test65
  - text: test70

E

- Entry
  - single-line text entry widget: test7
  - selecting text: test146
  - with shared buffer: test57
  - with clickable icons: test174
- EntryCompletion test58
    show pop-down list of matching items
- Error dialog see dialogs.html
- EventBox
    trap events, add background colors to labels,etc..
- Expander test131
  show/hide subsidiary info

F

- FileChooserButton test120
    small button to pop up a file chooser
- FileChooserDialog test23, test25
    pop-up dialog to select a file
- FileChooserWidget test122
    to add to your window
- FileFilter test23, test25
    select only certain types of files to show in the Chooser
- Fixed don't use this! See note below
- FlowBox test202
    container that allows reflowing its children
    requires GTK3.12+
- Fonts test97, test133
    See also: fonts
- FontChooserDialog test136
    pop up to select a font
- FontSelectionDialog
    deprecated, do not use!
- FontButton test36, test59
    small button to add to your window to select a font
- FontChooserWidget test183
    widget to add to your window to select a font
- FontFilter test36
    use with font choosers
- Frames
  - styled with css test138
  - with image in place of title: test137
    See note below

G

- Glade for designing XML interfaces. See XML/Builder
  - Calendar.ex calendar.ex
  - Calendar.glade calendar.glade
  - Clock.ex clock.ex
  - Clock.glade clock.glade
- Grid test34, test37, test117
    handy for laying out widgets

H

- HeaderBar test196 requires GTK 3.10+
- HSV (deprecated - never did work - removed)

I

- Icons
  - viewing: examples/icons.ex
  - from stock: test141
  - named (themed) icons test71, examples/icons.ex, test147
  - adding to toggle and check buttons: test166
  - adding to window title bar
- IconView icons.ex
- Image
  - from files test2, test6, test23
  - from pixbuf test24, test59, test86

- Info dialog see dialogs.html
- InfoBar test26
    add to your window to present important messages
- Internet test53
    ways to detect network and internet connectivity
J

- Justify property for labels test11

K

- Keyboard Accelerators test144
    using alt-key or ctl-key combinations
- Keypress event processing - see examples/hangman

L

- Labels
  - with mnemonics (hot-keys): test79
  - with markup: test5
  - with url web link: test64, test103
- Layout test38
    specify exact x/y positioning - avoid when possible!
- LevelBar test187
    changes color based on value
    requires GTK 3.6+
- Links to web pages in labels: test103
- LinkButton test53
    button with web link
- Linking to Euphoria Functions test4
    See HowItWorks
    linking multiple functions: test108
- ListBox test196
    requires GTK 3.10+
- ListView
  New! simpler to use, please read ListView/TreeView
  - generic demo: test66
  - complete demo: test33
  - sorting: test48
  - with images: test35
  - editing cells: test96
- Locale test31
    customizing numbers and dates for your area

M

- Maps test179, test180, test84
    using Euphoria maps to pass data
- Menus test54, test23, test25
- MenuButton test193
    requires GTK 3.6+
- MenuToolButton test132
    tool button with a drop-down submenu
- Margins test94, test195
    widgets can have extra space added on left, right, top or bottom
- Markup test5, test133
    See also Pango Markup
- Menu test144
- MessageDialog test170
- Mouse
    position in window: `get(mouse,"position")`
    position on display: test75
    with custom cursor: test2

N

- Network test53, test103
    detection: test99
- Notebook test155
    with animated tab: test42
    with custom tabs: test129
- NumerableIcons (deprecated as of GTK3.14 - no substitute)
  - Arabic numerals: test77
  - Roman numerals: test78

O

- Opacity property test109, test209
    if window manager allows
- OS Info test0, test160
- Overlay test113
- Override Color
    use "color" in most instances
- Override Cursor test2
    use "cursor"
- Override Font
    use "font"

P

- Paned test46
    splits container into two, with adjustable slider between
- Pango see Pango Markup
- PangoCairoLayout test36, test70
- PangoFont test36, test70
- Paper sizes for printing see papersizes.txt
- Passing data attached to controls
  - Euphoria routine-id's: test106
  - Formatting strings: test107
  - Generic data using maps: test179, test180, test84
  - Generic data using key/value pairs: test181
- Passwords test69, test57, passwords.ex
- Pixbuf test23, test24, test35 test197
  test211
    The "spinning mushroom" demo from GTK
- PlacesSidebar test198
    requires GTK 3.10+
- Pointer
  - changing: test2
  - position on display: test75
  - position and size: test76
- Preview in file dialogs test23
- Printing test150, test190, test191
    Include GtkPrinter.e for an easy-to-use print engine! See printing for more info
- ProgressBar test17
    GtkEntry as progress test57

Q

- Question dialog see dialogs.html

R

- RadioButton test14, test67, test96
    for selecting one item in a group of buttons
- RadioMenuItem test54, test23, test25
    same, for menus
- RadioToolButton test175
    for selecting one from a group of tool buttons
- RecentChooser test125, test126
- RecentChooserDialog test73
    pop-up window for above
- RecentChooserMenu test25
    menu version of above
- RecentFilter test25 test125
    select what files are shown based on file types
- Resizing images test27, test86
    using GdkPixbuf
- Revealer test199
    fade in/out or slide left/right/up/down to show/hide items
    requires GTK 3.10+
- RGBA Colors see RGBA Colors
- Rich Text test59

S

- ScaleButton test55
    button which changes icons based on value
- Scale test9, test134
    for getting/setting numeric values
  - using an adjustment: test82
  - setting steps: test128
  - with fill level: test142
- SearchBar test167
    requires GTK 3.10+
- SearchEntry test192
    text entry field with search and clear icons
    requires GTK 3.6+
- Search function for ListView browser.ex
- Screen Dimensions test76
- ScrolledWindow test48
    container for long lists, large pix, etc
- Scrolling text demo test130
    auto-scroll some lengthy text
- Separator test139
    ~ a thin horizontal or vertical divider bar
- SeparatorMenuItem test54, test25
    ~ a horizontal divider for drop-down menus
- ShowUri() test120, test103
    build-in function which calls the registered handler app for most common files
- SizeGroup test94
    force all widgets in the group to be identical size
- SourceView test201 also, read SourceView
    view and edit source code in many languages
    (must install Euphoria syntax files from ~/demos/resources)
- SpinButton test8
    for numeric entry
- Spinner examples/task.ex
    round and round it goes....
- Stack test156, test168
    requires GTK 3.10+
- StatusIcon test101
    adds an icon to your screen's status bar, with optional tooltip
- Stock Items test39
    (deprecated as of GTK3.10 - use named icons instead)
    See README)
- Stock Icons test141
    these are the replacements for stock items
- SVG images test27
    the best choice if images are to be resized
- Switch test15
    a simple on/off button

T

- Table deprecated. Use GtkGrid
- testall a EuGTK program which runs test programs 10 at a time.
- TextBuffer
  - inserting text: test177
  - shared: test57
  - multiple buffers: test112
- Text angle property test137
    rotate text in labels
- Text justification in labels test11
    justify multi-line text in labels; right, left, center
- TextTags test59
    creating named style tags which can be applied to text
- TextView test112, test25, test59
    see note below
- Themed Icons examples/icons.ex
    for a list of icons see themeicons.txt
- Timers test51, test52
    ~ call a function every x/1000 sec, or whenever computer is not otherwise busy
- Title property test2.ex
    text to appear on window titlebar
- TitleBar
    -- new in GTK 10+ (but not worth the effort right now, wait for improvements.)
- Titlebar icon test5
    see note below
- ToggleButton test15
- ToggleToolButton test176
- ToolButtons test118, test119, test132
- ToolBars
  - with stock icons: test119
  - with custom icons: test118
- ToolPalette test132
    ~ show/hide groups of toolbuttons
- Tooltips
  - text: test17
  - markup: test64
  - custom: test134, test127
  - in listviews: test96
- TreeView test33, test63
    generic container for List and Tree Views

U,V

- Unicode test111
- URI test85
    clickable links in labels
- Versions test0
    display versions of EuGTK, GTK, and Euphoria
- VolumeButton test56

W

- Warning dialog see dialogs.html
- Window (any of the demo programs!)
    decorated: test110 use with great care!
    opacity: test109 must be running a compositing window manager!
- Window Size test65
- Window Title
    if you don't enter one, default is the program filename

X

- Xcolors see Colors below, and xcolors.txt
- XML for building user-interfaces see XML/GtkBuilder below
- XPM images as include files;
    see examples/xpm_to_eu_include.ex

##

Notes:

### GtkFixed

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:

- Themes, which may change widget sizes.
- Fonts other than the one you used to write the app will of course change the size of widgets containing text; keep in mind that users may use a larger font because of difficulty reading the default, or they may be using Windows or the framebuffer port of GTK+, where different fonts are available.
- Translation of text into other languages changes its size. Also, display of non-English text will use a different font in many cases.

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.

### Icons

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.

### Fonts

There are several ways to modify fonts. For text controls, such as labels:

##### For the entire control:

        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

##### Or, you may mark up portions of the text:

       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 markup

See Pango Markup for details on the available markup attributes.
For other controls, such as buttons, the appearance is determined by the chosen window theme, and the programmer has few options: either go along with the user's choice, or design a custom button.

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.

### Font Choosers

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.

### Frames

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.

### CSS

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.

### Colors

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.

##### Gtk Widget Colors

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.

##### Cairo Colors

When you are drawing with Cairo, you have several ways to choose a drawing color:

1. set(cr,"color","red") -- easy
2. set(cr,"color",#FF0000) -- hex value
3. set(cr,"color","#FF0000") -- quoted hex value
4. set(cr,"source rgb",1,0,0) -- to conform to the Cairo way. values are r,g,b in range 0=>1.0
5. set(cr,"source rgba",1,0,0,0.5) -- the Cairo way to set color and alpha. ranges are 0=>1.0

Note that you cannot use the "rgb(255,0,0)" or"rgba(255,0,0,1)" formats which work for widgets when defining colors for Cairo.

### XML/GtkBuilder

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

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

This will create an image 'widget' which can be used exactly once, and it will be created at the same size as the original image in the file.

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,...)

1. If the above create() line contains only a filename
     a pixbuf is returned at the natural size of the image file
2. If one number follows the filename
     the image will be scaled to that width (original height x width ratio is retained)
3. If two numbers follow the filename, (height x width)
     the image will be stretched to those dimensions, predictably with ugly results, unless you retained the h/w ration when figuring the new dimensions!
4. If three numbers follow the filename, the third must be 1 or 0 ~ a.k.a. TRUE or FALSE
     if TRUE, then the original h x w ration will be maintained, and the image will be scaled to either h or w, whichever is smaller.
     if FALSE, then results will be the same as in line (3) above

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

### TextView

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.

### SourceView Plugin

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.

- GtkSourceView.plugin
    The plugin itself
- test201
    Eu program to demonstrate plugin

### WebKit Plugin

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.

- GtkWebKit.plugin
    The plugin itself
- examples/webkit.ex
    Eu program to demonstrate plugin