summaryrefslogtreecommitdiffstats
path: root/doc/html/toplevel-example.html
blob: 7b0791999cf9ea808c2dd76c7bfc878eb478b840 (plain)
1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
62
63
64
65
66
67
68
69
70
71
72
73
74
75
76
77
78
79
80
81
82
83
84
85
86
87
88
89
90
91
92
93
94
95
96
97
98
99
100
101
102
103
104
105
106
107
108
109
110
111
112
113
114
115
116
117
118
119
120
121
122
123
124
125
126
127
128
129
130
131
132
133
134
135
136
137
138
139
140
141
142
143
144
145
146
147
148
149
150
151
152
153
154
155
156
157
158
159
160
161
162
163
164
165
166
167
168
169
170
171
172
173
174
175
176
177
178
179
180
181
182
183
184
185
186
187
188
189
190
191
192
193
194
195
196
197
198
199
200
201
202
203
204
205
206
207
208
209
210
211
212
213
214
215
216
217
218
219
220
221
222
223
224
225
226
227
228
229
230
231
232
233
234
235
236
237
238
239
<!DOCTYPE HTML PUBLIC "-//W3C//DTD HTML 4.0 Transitional//EN">
<!-- /home/espenr/tmp/qt-3.3.8-espenr-2499/qt-x11-free-3.3.8/examples/toplevel/toplevel.doc:1 -->
<html>
<head>
<meta http-equiv="Content-Type" content="text/html; charset=ISO-8859-1">
<title>Toplevel Widgets</title>
<style type="text/css"><!--
fn { margin-left: 1cm; text-indent: -1cm; }
a:link { color: #004faf; text-decoration: none }
a:visited { color: #672967; text-decoration: none }
body { background: #ffffff; color: black; }
--></style>
</head>
<body>

<table border="0" cellpadding="0" cellspacing="0" width="100%">
<tr bgcolor="#E5E5E5">
<td valign=center>
 <a href="index.html">
<font color="#004faf">Home</font></a>
 | <a href="classes.html">
<font color="#004faf">All&nbsp;Classes</font></a>
 | <a href="mainclasses.html">
<font color="#004faf">Main&nbsp;Classes</font></a>
 | <a href="annotated.html">
<font color="#004faf">Annotated</font></a>
 | <a href="groups.html">
<font color="#004faf">Grouped&nbsp;Classes</font></a>
 | <a href="functions.html">
<font color="#004faf">Functions</font></a>
</td>
<td align="right" valign="center"><img src="logo32.png" align="right" width="64" height="32" border="0"></td></tr></table><h1 align=center>Toplevel Widgets</h1>

   

<p> 
This example demonstrates the use of TQt's widget flags to provide
toplevel widgets with customized window decorations.
<p> It provides a graphical user interface for selecting different
options for widget decoration and behavior, and passes the
appropriate widget flags to the <a href="tqwidget.html">TQWidget</a> constructor.
<a href="tqwidget.html#reparent">TQWidget::reparent</a>() is used to change the widget flags at runtime.
<p> <b>Warning:</b> Note that the interpretation and functionality of the
widget flags depends on the window manager used when running the
application. Many window managers do not support every possible flag
combination.
<p> The user interface providing the different options was created using
<a href="designer-manual.html">TQt Designer</a>. The different
options are explained in the user interface through the use of
tooltips and What's This help. Load the <tt>options.ui</tt> file into 
<a href="designer-manual.html">TQt Designer</a> for more details.
<p> 

<pre>    #include &lt;<a href="qapplication-h.html">ntqapplication.h</a>&gt;
    #include "options.h"

    int main( int argc, char ** argv )
    {
        <a href="ntqapplication.html">TQApplication</a> a( argc, argv );
        OptionsDialog dlg;
        return dlg.exec();
    }
</pre>
<p> The main function creates and displays the dialog for the user 
interface. Note that this dialog is modal.
<p> The code relevant for this example is in the <tt>options.ui.h</tt> 
file.
<p> 

<pre>    void OptionsDialog::apply()
    {
        <a href="tqstringlist.html">TQStringList</a> flagList;
        bool wstyle = false;
        WFlags f = WDestructiveClose | WType_TopLevel | WStyle_Customize;
</pre>
<p> The <tt>apply()</tt> slot declares the <a href="ntqt.html#WidgetFlags">widget flag</a> variable <tt>f</tt>
and initializes it with the values
<ul>
<li> <tt>WDestructiveClose</tt> - the widget will be automatically 
destroyed when it is closed,
<li> <tt>WType_TopLevel</tt> - the widget will be top level even if it
has a parent widget, and
<li> <tt>WStyle_Customize</tt> - the flags override the default values
</ul>
Other flags are used depending on the options selected in the user
interface.
<p> <pre>        if ( bgBorder-&gt;isChecked() ) {
            if ( rbBorderNormal-&gt;isChecked() ) {
                f |= WStyle_NormalBorder;
                flagList += "WStyle_NormalBorder";
                wstyle = true;
            }
            else if ( rbBorderDialog-&gt;isChecked() ) {
                f |= WStyle_DialogBorder;
                flagList += "WStyle_DialogBorder";
                wstyle = true;
            }
</pre>The window gets a normal or dialog border depending on the selected
option.
<p> <pre>            if ( bgTitle-&gt;isChecked() ) {
                f |= WStyle_Title;
                flagList += "WStyle_Title";
                wstyle = true;
                if ( cbTitleSystem-&gt;isChecked() ) {
                    f |= WStyle_SysMenu;
                    flagList += "WStyle_SysMenu";
                }
                if ( cbTitleMinimize-&gt;isChecked() ) {
                    f |= WStyle_Minimize;
                    flagList += "WStyle_Minimize";
                }
                if ( cbTitleMaximize-&gt;isChecked() ) {
                    f |= WStyle_Maximize;
                    flagList += "WStyle_Maximize";
                }
                if ( cbTitleContext-&gt;isChecked() ) {
                    f |= WStyle_ContextHelp;
                    flagList += "WStyle_ContextHelp";
                }
            }
</pre>A titlebar with controls is provided if the appropriate options
have been checked.
<p> <pre>        } else {
            f |= WStyle_NoBorder;
            flagList += "WStyle_NoBorder";
            wstyle = true;
        }
</pre>If the window should not have a border it cannot have a titlebar.
Widgets that provide their own (e.g. themed) window decoration
should use this flag.
<p> <pre>        <a href="tqwidget.html">TQWidget</a> *parent = this;
        if ( cbBehaviorTaskbar-&gt;isChecked() ) {
            parent = 0;
            f |= WGroupLeader;
            flagList += "WGroupLeader";
        }
</pre>If a toplevel widget has a parent it will not have a taskbar
entry, and on most window managers it will always stay on
top of the parent widget. This is the standard behavior for 
dialog boxes, especially if they are modeless, and for other
secondary toplevel widgets.
<p> To provide a taskbar entry the widget must have no parent, 
in which case we need to use the <tt>WGroupLeader</tt> flag to 
prevent blocking through the modal main dialog. Applications 
that can have multiple toplevel windows open simultaneously 
should use this combination.
<p> <pre>        if ( cbBehaviorStays-&gt;isChecked() ) {
            f |= WStyle_StaysOnTop /*| WX11BypassWM*/;
            flagList += "WStyle_StaysOnTop";
            wstyle = true;
        }
</pre>A toplevel widget can stay on top of the whole desktop if the 
window manager supports this functionality. 
<a href="#footnote1"><sup>(1)</sup></a><a name="footnote-call1"></a> 
<p> Widgets that display important or realtime information (i.e. IRC
clients) might benefit from using that flag.
<p> <pre>        if ( cbBehaviorPopup-&gt;isChecked() ) {
            f |= WType_Popup;
            flagList += "WType_Popup";
        }
</pre>A popup widget is a short lived modal widget that closes
automatically. Popup menus are a typical example for such widgets.
<p> <pre>        if ( cbBehaviorModal-&gt;isChecked() ) {
            f |= WShowModal;
            flagList += "WShowModal";
        }
</pre>A modal widget blocks input to other toplevel widgets, unless 
those are in a different modal group (see <tt>WGroupLeader</tt>).
Dialogs are often modal, and the <a href="tqdialog.html">TQDialog</a> class provides an easy API
to create and display them without the need to explicitly use this
flag.
<p> <pre>        if ( cbBehaviorTool-&gt;isChecked() ) {
            f |= WStyle_Tool;
            flagList += "WStyle_Tool";
            wstyle = true;
        }

        if (wstyle)
    <a name="x2534"></a>        flagList.<a href="tqvaluelist.html#push_front">push_front</a>("WStyle_Customize");
</pre>A tool window will never have a task bar entry (even if it
has no parent widget), and often has a smaller window 
decoration. Tool windows are frequently used instead of 
modeless dialogs.
<p> <pre>        if ( !widget ) {
            widget = new <a href="ntqvbox.html">TQVBox</a>( parent, 0, f );
    <a name="x2530"></a>        widget-&gt;<a href="ntqframe.html#setMargin">setMargin</a>( 20 );
    <a name="x2533"></a>        <a href="tqlabel.html">TQLabel</a> *label = new <a href="tqlabel.html">TQLabel</a>(flagList.<a href="tqstringlist.html#join">join</a>("&amp;nbsp;| "), widget);
    <a name="x2532"></a>        label-&gt;<a href="tqlabel.html#setTextFormat">setTextFormat</a>(RichText);
    <a name="x2531"></a>        label-&gt;<a href="tqlabel.html#setAlignment">setAlignment</a>(WordBreak);
            <a href="tqpushbutton.html">TQPushButton</a> *okButton = new <a href="tqpushbutton.html">TQPushButton</a>( "Close", widget );
    <a name="x2535"></a>        connect( okButton, TQ_SIGNAL(<a href="ntqbutton.html#clicked">clicked</a>()), widget, TQ_SLOT(<a href="tqwidget.html#close">close</a>()) );
    <a name="x2537"></a>        widget-&gt;<a href="tqwidget.html#move">move</a>( pos() );
</pre>The widget is created if it has not been created yet, or if it was
closed (since we use the <tt>WDestructiveClose</tt> flag). Note that the
window is not visible yet.
<a href="#footnote2"><sup>(2)</sup></a><a name="footnote-call2"></a> 
<p> <pre>        } else {
    <a name="x2538"></a><a name="x2536"></a>        widget-&gt;<a href="tqwidget.html#reparent">reparent</a>( parent, f, widget-&gt;<a href="tqwidget.html#geometry">geometry</a>().topLeft(), FALSE);
        }
</pre>If the widget has already been created the reparent() function is
used to modify the widget's flags. The widget's geometry is not
changed, and the window is not shown again.
<p> <pre>    <a name="x2539"></a>    widget-&gt;<a href="tqwidget.html#setCaption">setCaption</a>( leCaption-&gt;text() );
    <a name="x2540"></a>    widget-&gt;<a href="tqwidget.html#setIcon">setIcon</a>( leIcon-&gt;text() );
    <a name="x2541"></a>    widget-&gt;<a href="tqwidget.html#setWindowOpacity">setWindowOpacity</a>(double(slTransparency-&gt;maxValue() - slTransparency-&gt;value()) / 100);

    <a name="x2542"></a>    widget-&gt;<a href="tqwidget.html#show">show</a>();
</pre>Finally the higher level properties such as the window's caption and
icon are set. The window transparency is set according to the slider
value. Note that this will only have effect on systems that support
this attribute for toplevel window.
<p> <pre>    }
</pre>Finally the window is shown with the new attributes.
<p> To build the example go to the toplevel directory
(<tt>TQTDIR/examples/toplevel</tt>) 
<a href="#footnote3"><sup>(3)</sup></a><a name="footnote-call3"></a> 
and run <tt>qmake</tt> to generate the makefile, then use the make tool to
build the library. 

<hr>
<ol> <li><a name="footnote1"></a>
Unfortunately some X11 window managers also require the <tt>WX11BypassWM</tt> flag to be set in addition; but some other X11 window
managers will have problems if this flag is set.  <a href="#footnote-call1">Back...</a> <li><a name="footnote2"></a>
The example uses <a href="ntqguardedptr.html">TQGuardedPtr</a> to make sure that the 
pointer is reset to zero when the widget object is destroyed 
due to the <tt>WDestructiveClose</tt> flag.  <a href="#footnote-call2">Back...</a> <li><a name="footnote3"></a>

We use <tt>TQTDIR</tt> to stand for the directory where TQt is installed.
 <a href="#footnote-call3">Back...</a></ol>
</hr><p>See also <a href="examples.html">Examples</a>.

<!-- eof -->
<p><address><hr><div align=center>
<table width=100% cellspacing=0 border=0><tr>
<td>Copyright &copy; 2007
<a href="troll.html">Trolltech</a><td align=center><a href="trademarks.html">Trademarks</a>
<td align=right><div align=right>TQt 3.3.8</div>
</table></div></address></body>
</html>