# EuGTK Dialogs

Built-in Dialogs

New:
An easy-to-use Custom dialog, and non-modal dialogs!

There are five pre-built modal dialogs in EuGTK, which you can use in your own programs to save time and typing, while making your program code much easier to read and maintain. They require only one line of code, whereas using GTK's Dialogs or MessageDialogs can require many lines of code. There's also a non-modal dialog.

Dialogs have a title, a primary text item, a secondary text item, plus one or more buttons.

Note that each dialog has different default titles, icons and buttons. The primary and secondary text however, must be supplied by the programmer.

Dialogs appearance and contents can be changed by exercising various options. See 8 below.

All defaults can be overridden when creating a dialog. The parameters to the dialog are shown below. All are optional.

1. Parent of the dialog
     If you want the dialog to use the parent window's titlebar icon (and window theme allows), put the parent's handle here
2. Title appearing on the titlebar
     If omitted, title will be the type of dialog, e.g. Info, Error, Warning, or Question
3. Primary text
     Will be bold if there is secondary text, use markup if you wish
4. Secondary text
     Will be smaller than primary text, use markup if you wish
5. Button set
     Leave empty to use the default button set,
     or use GTK_BUTTONS_ enums to change button set.
     NULL (0) in this slot means don't use any buttons!
6. Dialog icon
     A GtkImage, GdkPixbuf, path to an image file, or name of stock or theme icon, will override the default dialog icon with a custom image.
     NULL in this slot means don't use a dialog icon.
     Leave empty to use default Info, Warn, Error, Question icons
7. Titlebar Icon
     Name of icon, this overrides icon set by dialog.
     NULL here means use parent's icon.
     Leave empty to use default Info, Warn, Error, Question icons
     Note: some themes refuse to show an icon on the titlebar.

8. Modality
     MODAL/NONMODAL
9. Addon new in EuGTK 4.10
     You can pass the handle to a widget here, and the widget will be added to the dialog. The widget can, of course, be a container which may contain several items. See example on the right, which adds a GtkTextView widget to the standard Info dialog.
10. X position new in EuGTK 4.11
      You can pass an x position for the dialog, following the addon option
11. Y position new in EuGTK 4.11
      You can pass a y position for the dialog, following the X option

###

Creating the dialogs

- result = Info( [parent], [title], "Primary Text", "Secondary Text",
  [button type], [dialog icon], [titlebar icon], [modal], [addon], [x pos], [y pos])
- result = Error( [parent], [title], "Primary Text", "Secondary Text",
  [button type], [dialog icon], [titlebar icon], [modal], [addon], [x pos], [y pos])
- result = Warn( [parent], [title], "Primary Text", "Secondary Text",
  [button type], [dialog icon], [titlebar icon], [modal], [addon], [x pos], [y pos])
- result = Question( [parent], [title], "Primary Text", "Secondary Text",
  [button type], [dialog icon], [titlebar icon], [modal], [addon], [x pos], [y pos])
- result = Custom( [parent], [title], "Primary Text", "Secondary Text",
  [button type], [dialog icon], [titlebar icon], [modal], [addon], [x pos], [y pos])

Primary and Secondary text can be marked up as desired. [optional] parameters can be left empty, defaults will be used.

###

Modal Dialogs

Modal dialogs lock you out of doing other things until you reply to them, then return various values when dismissed via button clicks or the titlebar 'close' button. These values are:

- MB_ABORT (-4) when dialog is closed using the titlebar 'close' button [X]
- MB_OK (-5) when OK button is clicked
- MB_CANCEL (-6) when Cancel button is clicked
- MB_CLOSE (-7) when Close button is clicked
- MB_YES (-8) when the Yes button is clicked
- MB_NO (-9) when the No button is clicked
- MB_APPLY (-10)

###

Non-modal dialogs

All the above built-in dialogs are by default modal, in that they capture the program focus until they are dismissed. This is probably appropriate for most notification purposes. For places where you need non-modal dialogs which you can leave on the screen while you work on other windows in the same program, you'll have to do this a different way.

Why, you ask?

Because the reason for leaving dialogs on the screen is so they can they interact with your code, perhaps changing items in other windows in response to changes in dialog options. I can't predict what those options and connections might be, so I can't provide a ready-to-use dialog. You might start with a basic GtkDialog, and build one up yourself, but this can be a lot of work, so I've added a pre-built Custom dialog with options.

A non-modal dialog needs to be able to trigger actions before closing, since it can remain on the screen for as long as the user wants. Therefore, the dialog's buttons must be connected to user-written functions prior to adding them to the dialog.

To add buttons to a Custom dialog, use the following syntax: ``

     -- for one button
    object btn  = {{"gtk-ok",say,"OK"}} -- say is the call_back to your function Say(), and "OK" is text to send to the function.

     -- or, for more than one
    object btns = {
    	{"gtk-ok",say,"OK"},
    	{"gtk-cancel"}, -- any button not provided with a call_back will be used to cancel the dialog  (regardless of what the button caption says)
    	{"gtk-quit","Quit"} -- this does the obvious, killing the whole program, probably not something you'd want to do from a non-modal dialog!
    }

Next, you put the btn or btns array as the 5th parameter passed to the dialog constructor:

    	Custom(win,"Fonts Help","Instructions",help_text,btns)

Most often, you will want to add some control(s) other than buttons to a non-modal dialog, for example, one or more color chooser buttons, or a font chooser, etc., or perhaps some scrolling text or an image. These would look out of place if they were added to the button area of a dialog.

To add these to the dialog's content area, create the item and pass the handle of this item as the Addon (9th) parameter to the dialog. If you need several, pack them into a container and pass the handle of the container. See test200.ex.

It is best to limit the use of non-modal dialogs, since they tend to clutter up the screen. If you're using lots of these, you are most likely doing something wrong. Menu options, sidebars, or moveable panes are often better substitutes.