bundles/org.eclipse.platform.doc.isv/guide/swt_widgets.htm - platform/eclipse.platform.common - Git at Google

 <!DOCTYPE HTML PUBLIC "-//W3C//DTD HTML 4.0 Transitional//EN"><HTML>
 <HEAD>
 <META HTTP-EQUIV="Content-Type" CONTENT="text/html; charset=ISO-8859-1">
 <META HTTP-EQUIV="Content-Style-Type" CONTENT="text/css">

 <LINK REL="STYLESHEET" HREF="../book.css" CHARSET="ISO-8859-1" TYPE="text/css">
 <TITLE>
 Widgets
 </TITLE>

 <link rel="stylesheet" type="text/css" HREF="../book.css">
 </HEAD>
 <BODY BGCOLOR="#ffffff">
 <H2>
 Widgets</H2>
 <P >
 SWT includes many rich features, but a basic knowledge of the system's core -
 <em>widgets</em>, <em>layouts</em>, and <em>events </em>- is all that is needed to
 implement useful and robust applications.</P>

 <H3>
 Widget application structure</H3>
 <P >When you are contributing UI elements using platform workbench
 extensions,&nbsp; the mechanics of starting up SWT are handled for you by the
 workbench.</P>
 <P >If you are writing an SWT application from scratch outside of the
 workbench, you must understand more about SWT's application structure.</P>
 <P >
 A typical stand-alone SWT application has the following structure:</P>
 <ul>
   <li>

 Create a <strong><a href="../reference/api/org/eclipse/swt/widgets/Display.html">Display</a></strong>
 which represents an SWT session.</li>
   <li>

 Create one or more <strong><a href="../reference/api/org/eclipse/swt/widgets/Shell.html"> Shell</a></strong>s which
 serve as the main window(s) for the application.</li>
   <li>

 Create any other widgets that are needed inside the shell.</li>
   <li>

 Initialize the sizes and other necessary state for the widgets. Register listeners
 for widget events that need to be handled.</li>
   <li>

 Open the shell window.</li>
   <li>

 Run the event dispatching loop until an exit condition occurs, which is typically when
     the main shell window is closed by the user.</li>
   <li>

 Dispose the display.</li>
 </ul>
 <P >
 The following code snippet is adapted from the <strong> <a href="../samples/org.eclipse.swt.examples/doc-html/swt_helloworld_ex.html"> org.eclipse.swt.examples.helloworld.HelloWorld2</a></strong> application. Since the application only displays the string &quot;Hello World,&quot; it does not need to register for any widget events.</P>
 <font color='#4444CC'><pre>
    public static void main (String [] args) {
       Display display = new Display ();
       Shell shell = new Shell (display);
       Label label = new Label (shell, SWT.CENTER);
       label.setText (&quot;Hello_world&quot;);
       label.setBounds (shell.getClientArea ());
       shell.open ();
       while (!shell.isDisposed ()) {
          if (!display.readAndDispatch ()) display.sleep ();
       }
       display.dispose ();
    }
 </pre></font>

 <H4>
 Display</H4>
 <P >
 The <strong><a href="../reference/api/org/eclipse/swt/widgets/Display.html">Display</a></strong>
 represents the connection between SWT and the underlying platform's GUI system. Displays are primarily used to manage the platform event loop and
 control communication between the UI thread and other threads. (See
 <a HREF="swt_threading.htm" CLASS="XRef"> Threading issues for clients</a> for a complete discussion of UI threading issues.)</P>
 <P >
 For most applications you can follow the pattern that is used above. You must create a display before creating any windows, and you must dispose of the display when your shell is closed. You don't need to think about the display much more unless you are designing a multi-threaded application.</P>


 <H4>
 Shell</H4>
 <P >
 A <strong><a href="../reference/api/org/eclipse/swt/widgets/Shell.html">Shell</a></strong>
 is a&nbsp; &quot;window&quot; managed by the OS platform window manager. Top level shells are those that are created as a child of the display. These windows are the windows that users move, resize,
 minimize, and maximize while using the application. Secondary shells are those that are created as a child of another shell. These windows are typically used as dialog windows or other transient windows that only exist in the context of another window.</P>


 <H4>
 Parents and children</H4>
 <P >
 All widgets that are not top level shells must have a parent. Top level shells do not
 have a parent, but they are created in association with a particular <strong><a href="../reference/api/org/eclipse/swt/widgets/Display.html">Display</a></strong>.&nbsp;
 You can access this display using <strong>getDisplay()</strong>.&nbsp;
 All other widgets are created as descendants (direct or indirect) of top level shells.</P>
 <P >
 <strong><a href="../reference/api/org/eclipse/swt/widgets/Composite.html">
 Composite</a></strong> widgets are widgets that can have children.</P>
 <P >
 When you see an application window, you can think of it as a widget tree, or
 hierarchy, whose root is the shell. Depending on the complexity of the application, there may be a single child of the shell, several children, or nested layers of composites with children.</P>


 <H3>
 Widget life cycle</H3>
 <P >
 When your application creates a widget, SWT immediately creates the underlying platform widget. This eliminates the need for code that operates differently depending upon whether the underlying OS widget exists. It also allows a majority of the widget's data to be kept in the platform layer rather than replicating it in the toolkit. This means that the toolkit's concept of a widget lifecycle must conform to the rules of the underlying GUI system.</P>

 <H4>
 Widget creation</H4>
 <P >
 Most GUI platforms require you to specify a parent when you create a widget. Since SWT creates a platform widget as soon as you create a toolkit widget, the parent widget must be specified in the constructor for the widget.</P>


 <H4>
 Style bits</H4>
 <P >
 Some widget properties must be set in the OS at the time a widget is created and cannot be subsequently changed. For example, a list may be single or multi-selection, and may or may not have scroll bars. </P>
 <P >
 These properties, called <em>styles</em>, must be set in the constructor. All widget constructors take an
 <strong> int</strong> argument that specifies the bitwise <strong> OR</strong> of all desired styles. In some cases, a particular style is considered a hint, which means that it may not be available on all platforms, but will be gracefully ignored on platforms that do not support it.</P>
 <P >
 The style constants are located in the <strong><a href="../reference/api/org/eclipse/swt/SWT.html"> SWT</a></strong> class as public static fields. A list of applicable constants for each
 widget class is contained in the
 API Reference for <strong><a href="../reference/api/org/eclipse/swt/SWT.html">SWT</a></strong>. </P>


 <H4>
 Resource disposal</H4>
 <P >
 The OS platforms underneath SWT require explicit allocation and freeing of OS resources. In keeping with the SWT design philosophy of reflecting the platform application structure in the widget toolkit, SWT requires
 that you explicitly free any OS resources that you have allocated. In SWT, the <strong>Widget.dispose()
 </strong>method is used to free resources associated with a particular toolkit object.</P>
 <P >
 The rule of thumb is that if you create the object, you must dispose of it. Here are some specific ground rules that further explain this philosophy:</P>
 <ul>
   <li>

 If you create a widget or graphic object using a constructor, you must dispose of it manually when you are finished using it.</li>
   <li>

 If you get a widget or graphic object without using a constructor, you must not dispose of it manually since you did not allocate it.</li>
   <li>

 If you pass a reference to your widget or graphic object to another object, you must take care not to dispose of it while it is still being used.
 (Similar to the rule described in <a HREF="jface_resources.htm#jface_resources_patterns" CLASS="XRef">Plug-in patterns for using images</a>.)</li>
   <li>

 When the user closes a <a href="../reference/api/org/eclipse/swt/widgets/Shell.html"><strong>Shell</strong></a>, the shell and all of its
 child widgets are recursively disposed. In this case, you do not need to dispose of the widgets themselves. However, you must free any graphics resources allocated in conjunction with those widgets.</li>
   <li>

 If you create a graphic object for use during the lifetime of one of your widgets, you must dispose of the
 graphic object when the widget is disposed. This can be done by registering a dispose listener for your widget and freeing the
 graphic object when the <strong> dispose</strong> event is received.</p>
   </li>
 </ul>


     <p align="left" >
 There is one exception to these rules.&nbsp; Simple data objects, such as <strong><a href="../reference/api/org/eclipse/swt/graphics/Rectangle.html"> Rectangle</a></strong> and
 <strong><a href="../reference/api/org/eclipse/swt/graphics/Point.html">Point</a></strong>, do not use operating system resources. They do not have a
 <strong> dispose()</strong> method and you do not have to free them.&nbsp;
 If in doubt, check the javadoc for a particular class.</p>


     <p align="left" >
 See <a href="http://www.eclipse.org/articles/swt-design-2/swt-design-2.html">Managing
 operating resources</a> for further discussion of this topic.</p>


 <p><a href="../hglegal.htm"><img border="0" src="../ngibmcpy.gif" alt="Copyright IBM Corporation and others 2000, 2003." border="0" width="324" height="14"></a></p>


 </BODY>
 </HTML>
	<!DOCTYPE HTML PUBLIC "-//W3C//DTD HTML 4.0 Transitional//EN"><HTML>
	<HEAD>
	<META HTTP-EQUIV="Content-Type" CONTENT="text/html; charset=ISO-8859-1">
	<META HTTP-EQUIV="Content-Style-Type" CONTENT="text/css">

	<LINK REL="STYLESHEET" HREF="../book.css" CHARSET="ISO-8859-1" TYPE="text/css">
	<TITLE>
	Widgets
	</TITLE>

	<link rel="stylesheet" type="text/css" HREF="../book.css">
	</HEAD>
	<BODY BGCOLOR="#ffffff">
	<H2>
	Widgets</H2>
	<P >
	SWT includes many rich features, but a basic knowledge of the system's core -
	<em>widgets</em>, <em>layouts</em>, and <em>events </em>- is all that is needed to
	implement useful and robust applications.</P>

	<H3>
	Widget application structure</H3>
	<P >When you are contributing UI elements using platform workbench
	extensions,  the mechanics of starting up SWT are handled for you by the
	workbench.</P>
	<P >If you are writing an SWT application from scratch outside of the
	workbench, you must understand more about SWT's application structure.</P>
	<P >
	A typical stand-alone SWT application has the following structure:</P>
	<ul>
	<li>

	Create a <strong><a href="../reference/api/org/eclipse/swt/widgets/Display.html">Display</a></strong>
	which represents an SWT session.</li>
	<li>

	Create one or more <strong><a href="../reference/api/org/eclipse/swt/widgets/Shell.html"> Shell</a></strong>s which
	serve as the main window(s) for the application.</li>
	<li>

	Create any other widgets that are needed inside the shell.</li>
	<li>

	Initialize the sizes and other necessary state for the widgets. Register listeners
	for widget events that need to be handled.</li>
	<li>

	Open the shell window.</li>
	<li>

	Run the event dispatching loop until an exit condition occurs, which is typically when
	the main shell window is closed by the user.</li>
	<li>

	Dispose the display.</li>
	</ul>
	<P >
	The following code snippet is adapted from the <strong> <a href="../samples/org.eclipse.swt.examples/doc-html/swt_helloworld_ex.html"> org.eclipse.swt.examples.helloworld.HelloWorld2</a></strong> application. Since the application only displays the string "Hello World," it does not need to register for any widget events.</P>
	<font color='#4444CC'><pre>
	public static void main (String [] args) {
	Display display = new Display ();
	Shell shell = new Shell (display);
	Label label = new Label (shell, SWT.CENTER);
	label.setText ("Hello_world");
	label.setBounds (shell.getClientArea ());
	shell.open ();
	while (!shell.isDisposed ()) {
	if (!display.readAndDispatch ()) display.sleep ();
	}
	display.dispose ();
	}
	</pre></font>

	<H4>
	Display</H4>
	<P >
	The <strong><a href="../reference/api/org/eclipse/swt/widgets/Display.html">Display</a></strong>
	represents the connection between SWT and the underlying platform's GUI system. Displays are primarily used to manage the platform event loop and
	control communication between the UI thread and other threads. (See
	<a HREF="swt_threading.htm" CLASS="XRef"> Threading issues for clients</a> for a complete discussion of UI threading issues.)</P>
	<P >
	For most applications you can follow the pattern that is used above. You must create a display before creating any windows, and you must dispose of the display when your shell is closed. You don't need to think about the display much more unless you are designing a multi-threaded application.</P>


	<H4>
	Shell</H4>
	<P >
	A <strong><a href="../reference/api/org/eclipse/swt/widgets/Shell.html">Shell</a></strong>
	is a  "window" managed by the OS platform window manager. Top level shells are those that are created as a child of the display. These windows are the windows that users move, resize,
	minimize, and maximize while using the application. Secondary shells are those that are created as a child of another shell. These windows are typically used as dialog windows or other transient windows that only exist in the context of another window.</P>


	<H4>
	Parents and children</H4>
	<P >
	All widgets that are not top level shells must have a parent. Top level shells do not
	have a parent, but they are created in association with a particular <strong><a href="../reference/api/org/eclipse/swt/widgets/Display.html">Display</a></strong>.
	You can access this display using <strong>getDisplay()</strong>.
	All other widgets are created as descendants (direct or indirect) of top level shells.</P>
	<P >
	<strong><a href="../reference/api/org/eclipse/swt/widgets/Composite.html">
	Composite</a></strong> widgets are widgets that can have children.</P>
	<P >
	When you see an application window, you can think of it as a widget tree, or
	hierarchy, whose root is the shell. Depending on the complexity of the application, there may be a single child of the shell, several children, or nested layers of composites with children.</P>



	<H3>
	Widget life cycle</H3>
	<P >
	When your application creates a widget, SWT immediately creates the underlying platform widget. This eliminates the need for code that operates differently depending upon whether the underlying OS widget exists. It also allows a majority of the widget's data to be kept in the platform layer rather than replicating it in the toolkit. This means that the toolkit's concept of a widget lifecycle must conform to the rules of the underlying GUI system.</P>

	<H4>
	Widget creation</H4>
	<P >
	Most GUI platforms require you to specify a parent when you create a widget. Since SWT creates a platform widget as soon as you create a toolkit widget, the parent widget must be specified in the constructor for the widget.</P>


	<H4>
	Style bits</H4>
	<P >
	Some widget properties must be set in the OS at the time a widget is created and cannot be subsequently changed. For example, a list may be single or multi-selection, and may or may not have scroll bars. </P>
	<P >
	These properties, called <em>styles</em>, must be set in the constructor. All widget constructors take an
	<strong> int</strong> argument that specifies the bitwise <strong> OR</strong> of all desired styles. In some cases, a particular style is considered a hint, which means that it may not be available on all platforms, but will be gracefully ignored on platforms that do not support it.</P>
	<P >
	The style constants are located in the <strong><a href="../reference/api/org/eclipse/swt/SWT.html"> SWT</a></strong> class as public static fields. A list of applicable constants for each
	widget class is contained in the
	API Reference for <strong><a href="../reference/api/org/eclipse/swt/SWT.html">SWT</a></strong>. </P>


	<H4>
	Resource disposal</H4>
	<P >
	The OS platforms underneath SWT require explicit allocation and freeing of OS resources. In keeping with the SWT design philosophy of reflecting the platform application structure in the widget toolkit, SWT requires
	that you explicitly free any OS resources that you have allocated. In SWT, the <strong>Widget.dispose()
	</strong>method is used to free resources associated with a particular toolkit object.</P>
	<P >
	The rule of thumb is that if you create the object, you must dispose of it. Here are some specific ground rules that further explain this philosophy:</P>
	<ul>
	<li>

	If you create a widget or graphic object using a constructor, you must dispose of it manually when you are finished using it.</li>
	<li>

	If you get a widget or graphic object without using a constructor, you must not dispose of it manually since you did not allocate it.</li>
	<li>

	If you pass a reference to your widget or graphic object to another object, you must take care not to dispose of it while it is still being used.
	(Similar to the rule described in <a HREF="jface_resources.htm#jface_resources_patterns" CLASS="XRef">Plug-in patterns for using images</a>.)</li>
	<li>

	When the user closes a <a href="../reference/api/org/eclipse/swt/widgets/Shell.html"><strong>Shell</strong></a>, the shell and all of its
	child widgets are recursively disposed. In this case, you do not need to dispose of the widgets themselves. However, you must free any graphics resources allocated in conjunction with those widgets.</li>
	<li>

	If you create a graphic object for use during the lifetime of one of your widgets, you must dispose of the
	graphic object when the widget is disposed. This can be done by registering a dispose listener for your widget and freeing the
	graphic object when the <strong> dispose</strong> event is received.</p>
	</li>
	</ul>


	<p align="left" >
	There is one exception to these rules.  Simple data objects, such as <strong><a href="../reference/api/org/eclipse/swt/graphics/Rectangle.html"> Rectangle</a></strong> and
	<strong><a href="../reference/api/org/eclipse/swt/graphics/Point.html">Point</a></strong>, do not use operating system resources. They do not have a
	<strong> dispose()</strong> method and you do not have to free them.
	If in doubt, check the javadoc for a particular class.</p>


	<p align="left" >
	See <a href="http://www.eclipse.org/articles/swt-design-2/swt-design-2.html">Managing
	operating resources</a> for further discussion of this topic.</p>


	<p><a href="../hglegal.htm"><img border="0" src="../ngibmcpy.gif" alt="Copyright IBM Corporation and others 2000, 2003." border="0" width="324" height="14"></a></p>


	</BODY>
	</HTML>