278 lines
12 KiB
HTML
278 lines
12 KiB
HTML
|
|
<! DOCTYPE html>
|
|
|
|
<html lang="en">
|
|
|
|
<head>
|
|
<title>EuGTK Dialogs</title>
|
|
<link rel="stylesheet" href="style.css" type="text/css">
|
|
</head>
|
|
|
|
<body>
|
|
|
|
<header>
|
|
<img src="../thumbnails/gtk-logo-rgb.gif"><alt="GTK LOGO"></img>
|
|
<img src="../thumbnails/mongoose.png"><alt="mongoose"></img>
|
|
<img src="../thumbnails/gnome-run.png"alt="gnome-run" align="right" />
|
|
|
|
<h2><hr />EuGTK 4.12.0</h2>
|
|
<h3>Built-in Dialogs</h3><hr />
|
|
</header>
|
|
|
|
<nav>
|
|
<div class="hdr">Quick Links:</div>
|
|
<a href="#creating"><button>Creating</button></a>
|
|
<a href="#modal"><button>Modal Dialogs</button></a>
|
|
<a href="#nonmodal"><button>Non-modal Dialogs</button></a>
|
|
<br />
|
|
|
|
<div class="hdr">Other Files:</div>
|
|
<a href="README.html"><button>README</button></a>
|
|
<a href="HowItWorks.html"><button>How EuGTK Works</button></a>
|
|
<a href="guide_a.html"><button>Alphabetical guide</button></a>
|
|
<a href="printing.html"><button>Printing</button></a>
|
|
<a href="pango_markup.html"><button>Markup</button></a>
|
|
<a href="treeviews.html"><button>ListView/TreeView</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>
|
|
|
|
</nav>
|
|
|
|
<br />
|
|
|
|
<hr />
|
|
|
|
<table border="0">
|
|
<tr><th colspan="1">Built-in Dialogs</th></tr>
|
|
<tr>
|
|
<td rowspan="6">
|
|
|
|
<div class="hint">
|
|
<img class="hint" src="../thumbnails/hint.png" alt="hint" width="100px" align="left" float="right" />
|
|
<p><b>New:</b><br />
|
|
An easy-to-use Custom dialog, and <a href="#nonmodal">non-modal dialogs</a>!
|
|
</p>
|
|
</div>
|
|
|
|
<p>
|
|
There are five pre-built <a href="#modal">modal dialogs</a> 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.
|
|
</p>
|
|
<p>
|
|
Dialogs have a title, a <i>primary text</i> item, a <i>secondary text</i> item,
|
|
plus one or more buttons.
|
|
</p>
|
|
<p>
|
|
Note that each dialog has different default titles, icons and buttons.
|
|
The primary and secondary text however, must be supplied by the programmer.
|
|
</p>
|
|
<p>
|
|
Dialogs appearance and contents can be changed by exercising various options. See 8 below.
|
|
</p>
|
|
<p>
|
|
All defaults can be overridden when creating a dialog. The
|
|
parameters to the dialog are shown below. All are optional.<br />
|
|
<ol>
|
|
<li>Parent of the dialog
|
|
<dd>If you want the dialog to use the parent window's titlebar icon (and window theme allows), put the parent's handle here</dd></li>
|
|
|
|
<li>Title appearing on the titlebar
|
|
<dd>If omitted, title will be the type of dialog, e.g. Info, Error, Warning, or Question</dd></li>
|
|
|
|
<li>Primary text
|
|
<dd>Will be bold if there is secondary text, use markup if you wish</dd></li>
|
|
|
|
<li>Secondary text
|
|
<dd>Will be smaller than primary text, use markup if you wish</dd></li>
|
|
|
|
<li>Button set
|
|
<dd>Leave empty to use the default button set,</dd>
|
|
<dd>or use GTK_BUTTONS_ enums to change button set.</dd>
|
|
<dd>NULL (0) in this slot means don't use any buttons!</dd></li>
|
|
|
|
<li>Dialog icon
|
|
<dd>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.</dd>
|
|
<dd>NULL in this slot means don't use a dialog icon.</dd>
|
|
<dd>Leave empty to use default Info, Warn, Error, Question icons</dd></li>
|
|
|
|
<li>Titlebar Icon
|
|
<dd>Name of icon, this overrides icon set by dialog.</dd>
|
|
<dd>NULL here means use parent's icon.</dd>
|
|
<dd>Leave empty to use default Info, Warn, Error, Question icons</dd>
|
|
<dd><em>Note: some themes refuse to show an icon on the titlebar.</em></dd></li>
|
|
|
|
<hr />
|
|
|
|
<li>Modality
|
|
<dd>MODAL/NONMODAL</dd>
|
|
</li>
|
|
|
|
<li>Addon
|
|
<small><em>new in EuGTK 4.10</em></small>
|
|
<dd>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.</dd>
|
|
</li>
|
|
|
|
<li>X position
|
|
<small><em>new in EuGTK 4.11</em></small>
|
|
<dd>You can pass an x position for the dialog, following the addon option</dd>
|
|
</li>
|
|
<li>Y position
|
|
<small><em>new in EuGTK 4.11</em></small>
|
|
<dd>You can pass a y position for the dialog, following the X option</dd>
|
|
</li>
|
|
</ol>
|
|
</p>
|
|
</td>
|
|
</tr>
|
|
|
|
<tr>
|
|
<td><img src="../screenshots/info.png" alt="info dialog" title="Info dialog" /></td>
|
|
</tr>
|
|
|
|
<tr>
|
|
<td><img src="../screenshots/error.png" alt="error dialog" title="Error dialog" /></td>
|
|
</tr>
|
|
|
|
<tr>
|
|
<td><img src="../screenshots/warn.png" alt="warn dialog" title="Warn dialog" /></td>
|
|
</tr>
|
|
|
|
<tr>
|
|
<td><img src="../screenshots/question.png" alt="question dialog" title="Question dialog" /></td>
|
|
</tr>
|
|
|
|
<tr>
|
|
<td><img src="../screenshots/test92.png" alt="custom dialog"
|
|
title = "Custom dialog" width="300" align="right" /></td>
|
|
</tr>
|
|
|
|
</table>
|
|
|
|
<a name="creating" />
|
|
|
|
|
|
<h3><hr />Creating the dialogs<hr /></h3>
|
|
<p>
|
|
<ul>
|
|
<li><i>result</i> = <b>Info(</b><i><small> [parent]</small></i>,<i><small> [title]</small></i>, "Primary Text", "Secondary Text",<br /> <i><small>[button type], [dialog icon], [titlebar icon], [modal], [addon], [x pos], [y pos]</small></i><b>)</b></li>
|
|
<li><i>result</i> = <b>Error(</b><i><small> [parent]</small></i>,<i><small> [title]</small></i>, "Primary Text", "Secondary Text",<br /> <i><small>[button type], [dialog icon], [titlebar icon], [modal], [addon], [x pos], [y pos]</small></i><b>)</b></li>
|
|
<li><i>result</i> = <b>Warn(</b><i><small> [parent]</small></i>,<i><small> [title]</small></i>, "Primary Text", "Secondary Text",<br /> <i><small>[button type], [dialog icon], [titlebar icon], [modal], [addon], [x pos], [y pos]</small></i><b>)</b></li>
|
|
<li><i>result</i> = <b>Question(</b><i><small> [parent]</small></i>,<i><small> [title]</small></i>, "Primary Text", "Secondary Text",<br /> <i><small>[button type], [dialog icon], [titlebar icon], [modal], [addon], [x pos], [y pos]</small></i><b>)</b></li>
|
|
<li><i>result</i> = <b>Custom(</b><i><small> [parent]</small></i>,<i><small> [title]</small></i>, "Primary Text", "Secondary Text",<br /> <i><small>[button type], [dialog icon], [titlebar icon], [modal], [addon], [x pos], [y pos]</small></i><b>)</b></li>
|
|
</ul>
|
|
</p>
|
|
<p>
|
|
Primary and Secondary text can be marked up as desired. <i><small>[optional]</small></i> parameters can be left empty,
|
|
defaults will be used.
|
|
</p>
|
|
|
|
<a name="modal" />
|
|
|
|
<h3><hr />Modal Dialogs<hr /></h3>
|
|
<p>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:<br />
|
|
<ul>
|
|
<li>MB_ABORT (-4) when dialog is closed using the titlebar 'close' button <b>[X]</b></li>
|
|
<li>MB_OK (-5) when <b><u>O</u>K</b> button is clicked</li>
|
|
<li>MB_CANCEL (-6) when <b><u>C</u>ancel</b> button is clicked</li>
|
|
<li>MB_CLOSE (-7) when <b><u>C</u>lose</b> button is clicked</li>
|
|
<li>MB_YES (-8) when the <b><u>Y</u>es</b> button is clicked</li>
|
|
<li>MB_NO (-9) when the <b><u>N</u>o</b> button is clicked</li>
|
|
<li>MB_APPLY (-10)</li>
|
|
|
|
</ul>
|
|
</p>
|
|
|
|
<a name="nonmodal" />
|
|
|
|
|
|
<h3><hr />Non-modal dialogs<hr /></h3>
|
|
<p>
|
|
All the above built-in dialogs are by default <u>modal</u>, 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.
|
|
</p>
|
|
<p>
|
|
<i>Why,</i> you ask?
|
|
</p>
|
|
<p>
|
|
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.
|
|
</p>
|
|
|
|
<a name="nonmodal" />
|
|
|
|
<p>
|
|
A non-modal dialog needs to be able to trigger actions <i>before</i> 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.
|
|
</p>
|
|
<p>
|
|
To add buttons to a Custom dialog, use the following syntax:
|
|
<code><pre>
|
|
<em>-- for one button</em>
|
|
<em class="kw">object</em> btn = {{<em class="str">"gtk-ok"</em>,say,<em class="str">"OK"</em>}} <em>-- say is the call_back to your function Say(), and "OK" is text to send to the function.</em>
|
|
|
|
<em>-- or, for more than one</em>
|
|
<em class="kw">object</em> btns = {
|
|
{<em class="str">"gtk-ok"</em>,say,<em class="str">"OK"</em>},
|
|
{<em class="str">"gtk-cancel"</em>}, <em>-- any button not provided with a call_back will be used to cancel the dialog (regardless of what the button caption says)</em>
|
|
{<em class="str">"gtk-quit","Quit"</em>} <em>-- this does the obvious, killing the whole program, probably not something you'd want to do from a non-modal dialog!</em>
|
|
}
|
|
</pre></code></p>
|
|
|
|
Next, you put the btn or btns array as the 5<sup>th</sup> parameter passed to the dialog constructor:
|
|
<pre><code> <em class="gtk">Custom</em>(win,<em class="str">"Fonts Help","Instructions"</em>,help_text,<em class='blue'><u><b>btns</b></u></em>)
|
|
</code></pre>
|
|
</p>
|
|
|
|
<p>
|
|
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.
|
|
</p>
|
|
|
|
<p>
|
|
To add these to the dialog's content area, create the item and pass the handle of this item as the Addon (9<sup>th</sup>) parameter to the dialog.
|
|
If you need several, pack them into a container and pass the handle of the container. See <a href="../test200.ex">test200.ex</a>.
|
|
</p>
|
|
|
|
<p>
|
|
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.
|
|
</p>
|
|
|
|
<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="README.html#bear">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>
|