/usr/share/GNUstep/Documentation/Developer/Gui/ProgrammingManual/AppKit/interfacefiles.html

<!DOCTYPE html PUBLIC "-//W3C//DTD HTML 4.01 Transitional//EN" "http://www.w3.org/TR/html4/loose.dtd">
<html>
<!-- (C) 2005-2006 Christopher Armstrong.

Permission is granted to copy, distribute and/or modify this document under the terms of the GNU Free Documentation License, Version 1.2, as published by the Free Software Foundation; with no Invariant Sections, no Front-Cover Texts, and no Back-Cover Texts. A copy of the license is included in the section entitled "GNU Free Documentation License".

This documentation is provided on an "AS IS" BASIS, WITHOUT WARRANTY
OF ANY KIND, EITHER EXPRESS OR IMPLIED, INCLUDING, BUT NOT LIMITED
TO, THE IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A
PARTICULAR PURPOSE. THE ENTIRE RISK AS TO THE QUALITY AND USEFULNESS
OF THE DOCUMENTATION IS WITH YOU (THE LICENSEE). IN NO EVENT WILL THE COPYRIGHT
HOLDERS BE LIABLE FOR DAMAGES, INCLUDING ANY DIRECT, INDIRECT,
SPECIAL, GENERAL, INCIDENTAL OR CONSEQUENTIAL DAMAGES ARISING OUT OF
THE USE OR INABILITY TO USE THIS DOCUMENTATION (INCLUDING BUT NOT
LIMITED TO LOSS OF DATA, USE, OR PROFITS; PROCUREMENT OF SUBSTITUTE
GOODS AND SERVICES; OR BUSINESS INTERUPTION) HOWEVER CAUSED, EVEN
IF ADVISED OF THE POSSIBILITY OF SUCH DAMAGE. -->
<!-- Created by GNU Texinfo 5.2, http://www.gnu.org/software/texinfo/ -->
<head>
<title>Using the GNUstep AppKit 0.1: interfacefiles</title>

<meta name="description" content="Using the GNUstep AppKit 0.1: interfacefiles">
<meta name="keywords" content="Using the GNUstep AppKit 0.1: interfacefiles">
<meta name="resource-type" content="document">
<meta name="distribution" content="global">
<meta name="Generator" content="makeinfo">
<meta http-equiv="Content-Type" content="text/html; charset=utf-8">
<link href="index.html#Top" rel="start" title="Top">
<link href="conceptindex.html#conceptindex" rel="index" title="conceptindex">
<link href="index.html#Top" rel="up" title="Top">
<link href="controls.html#controls" rel="next" title="controls">
<link href="applicationmakefiles.html#applicationmakefiles" rel="prev" title="applicationmakefiles">
<style type="text/css">
<!--
a.summary-letter {text-decoration: none}
blockquote.smallquotation {font-size: smaller}
div.display {margin-left: 3.2em}
div.example {margin-left: 3.2em}
div.indentedblock {margin-left: 3.2em}
div.lisp {margin-left: 3.2em}
div.smalldisplay {margin-left: 3.2em}
div.smallexample {margin-left: 3.2em}
div.smallindentedblock {margin-left: 3.2em; font-size: smaller}
div.smalllisp {margin-left: 3.2em}
kbd {font-style:oblique}
pre.display {font-family: inherit}
pre.format {font-family: inherit}
pre.menu-comment {font-family: serif}
pre.menu-preformatted {font-family: serif}
pre.smalldisplay {font-family: inherit; font-size: smaller}
pre.smallexample {font-size: smaller}
pre.smallformat {font-family: inherit; font-size: smaller}
pre.smalllisp {font-size: smaller}
span.nocodebreak {white-space:nowrap}
span.nolinebreak {white-space:nowrap}
span.roman {font-family:serif; font-weight:normal}
span.sansserif {font-family:sans-serif; font-weight:normal}
ul.no-bullet {list-style: none}
-->
</style>


</head>

<body lang="en" bgcolor="#FFFFFF" text="#000000" link="#0000FF" vlink="#800080" alink="#FF0000">
<a name="interfacefiles"></a>
<div class="header">
<p>
Next: <a href="controls.html#controls" accesskey="n" rel="next">controls</a>, Previous: <a href="applicationmakefiles.html#applicationmakefiles" accesskey="p" rel="prev">applicationmakefiles</a>, Up: <a href="index.html#Top" accesskey="u" rel="up">Top</a> &nbsp; [<a href="conceptindex.html#conceptindex" title="Index" rel="index">Index</a>]</p>
</div>
<hr>
<a name="Interface-Files-1"></a>
<h2 class="chapter">5 Interface Files</h2>

<a name="index-interface-files_002c-definition"></a>
<p><em>Interface files</em> are used to store your applications graphical user interface. It&rsquo;s separation means that you can modify it more easily than other interface generation mechanisms, such as code generators, which generate code that makes it hard to modify the interface or requires you to rewrite your own code. The advantage of a separate interface file is that you can change the interface without having to recompile one bit of code (in most instances). 
</p>
<a name="index-nibs"></a>
<p>Interface files are often referred to as &quot;nib&quot; files.<a name="DOCF4" href="#FOOT4"><sup>4</sup></a> These are not the same as those appearing on NeXT and MacOS X systems, and are completely incompatible (tagged XML nib&rsquo;s may change this in future). This section is very important to understanding key concepts in the AppKit, especially with regards to manipulation of your user interface. It is strongly recommended you do not skip this section, and refer back to it if you do not understand anything, even if you don&rsquo;t intend to use Gorm (also not recommended).
</p>
<a name="Using-Gorm"></a>
<h3 class="section">5.1 Using Gorm</h3>
<a name="index-Gorm"></a>
<p>Gorm is the GNUstep application used to create interface files for applications. It uses a drag and drop interface to place the control&rsquo;s on your window form and menu. See the Gorm manual, currently posted on the <cite>GNUstep Wiki</cite> for further information on using Gorm for the creation of interfaces. This section is also relevant to those using Renaissance.
</p>
<a name="The-Palette"></a>
<h4 class="subsection">5.1.1 The Palette</h4>

<p>The palette contains pictures of various objects that you can drag and drop onto a window or a menu, including a window itself. These are the graphical objects that you may put onto your interface. They can be resized on the window itself by using the resize handles.
</p>
<p>The graphical elements you place on your window(s) using Gorm, including the window itself, come from the palette. When your nib file is loaded, all the graphical elements are instantiated by GNUstep and all connections are made (see outlets and actions below). You don&rsquo;t need to instantiate objects in code, unless you intend to draw them programatically and add them to your interface. This differs from many other toolkits, where you often need to make connections to your interface in code (e.g. Win32 resource files) as well as instantiate custom objects for them, e.g. in Gtk, you need to add object variables that refer to the objects in your interface such as windows and buttons. 
</p>
<p>In GNUstep, you need only draw your interface and make connections to objects using Gorm, and then provide reference variables in the classes you specify connections (outlets and actions) for.
</p>
<a name="The-Inspector"></a>
<h4 class="subsection">5.1.2 The Inspector</h4>

<p>The inspector contains four sections, which let you modify the properties of any object (including those appearing on your window, the windows themselves and objects in the Objects Pane) in four sections:
</p>
<dl compact="compact">
<dt><code>Attributes</code></dt>
<dd><p>This contains the attributes of the object you are modifying e.g. it&rsquo;s title, it&rsquo;s colour, tag items, etc. Note that fonts are modified using the Font Panel, which is opened in the menus, separately.
</p>
</dd>
<dt><code>Connections</code></dt>
<dd><p>Connections has three panes: the outlets, actions and object connections that you have made for this object (see see <a href="#Outlets-and-Actions">Outlets and Actions</a>).
</p>
</dd>
<dt><code>Size</code></dt>
<dd><p>Lets you modify the size using numbers, and the resizing data for this object (the springs at the bottom). See the Gorm manual for more details on this pane.
</p>
</dd>
<dt><code>Help</code></dt>
<dd><p>Help related to this object type. Still being completed.
</p>
</dd>
<dt><code>Custom class</code></dt>
<dd><p>Let&rsquo;s you set the class for this object manually (NOTE: this only appears for some objects where it is possible to set a custom class).
</p>
</dd>
</dl>

<a name="The-Objects-Pane"></a>
<h4 class="subsection">5.1.3 The Objects Pane</h4>

<p>This is a graphical display of your application&rsquo;s objects. They appear with a subtitled icon, and can be manipulated like the graphical objects on the window forms, as well as be connected to outlets and actions. 
</p>
<p>You can also instantiate subclasses (where necessary) to connect to other objects. The object&rsquo;s here may be representative (for example, NSOwner and NSFirst) or be instances of custom classes you create in your code.
</p>
<a name="The-Classes-Pane"></a>
<h4 class="subsection">5.1.4 The Classes Pane</h4>

<p>This permits you to subclass and add actions and outlets to classes that you want Gorm to link up at runtime. The GNUstep class hierachy is shown in this pane, allowing you to see the various views and helper classes (e.g. NSDocument/NSDocumentController, used for document based applications).
</p>
<p>In here, you can create subclasses of the classes specified, often <code>NSObject</code> and then add actions (methods) or outlets (instance variables) to them. What you do in here must be reflected in your own code at the time your nib file is loaded. As a result, Gorm can generate the appropriate header and source files for you, or you can create them yourself. However you do this, you must make sure any subclasses you create here can be found at runtime, and that they contain all the instance variables and methods that you specify as outlets and actions at the time that your code loads the nib file (often by calling <code>-loadNibNamed:</code> on the main bundle).
</p>
<a name="Outlets-and-Actions"></a><a name="Outlets-and-Actions_003a-Connecting-objects"></a>
<h4 class="subsection">5.1.5 Outlets and Actions: Connecting objects</h4>

<p>Gorm permits you to connect your graphical objects together using it&rsquo;s interface, to save you the trouble of connecting them at runtime using extra lines of code (and wondering where you should put them). We introduce two concepts here: <em>outlets</em> and <em>actions</em>. They form the basis of event handling and graphical object linkage when using Interface Files for your programme&rsquo;s interface in GNUstep. This outlet and action paradigm is incredibly important, as you will see, as it eliminates the need for subclassing objects of graphical elements (a.k.a widgets) for all but the most complex GUI applications. You don&rsquo;t even need to subclass NSWindow to create a window; you merely need to instantiate it, and that bit is taken care of by GNUstep anyway (unlike most other GUI toolkits, including the Win32 API, Gtk, Qt/KDE, and many others).
</p>
<p>The concept of <em>outlets and actions</em> is presented in many beginner tutorials to GNUstep and Cocoa. It is well recommended you follow one of these to get a better idea of how these things work. With practice, they become second nature in interface design, and are useful for thinking about how your interface will interact with your code, but still keeping a useful abstract distance between the two.
</p>
<a name="index-outlet"></a>
<p>An <em>outlet</em> is a property of an object, that can be used to store a reference to another object, which is usually some sort of graphical element (like a button or text box). You usually add outlets to your custom subclasses and then connect them to graphical elements on your window, so that you can directly manipulate them in your code. If you were to add an outlet to a class, it would appear in code under the data value declarations part of your class as an object reference. It takes the syntax:
</p><div class="smallexample">
<pre class="smallexample">id myOutlet;
</pre></div>
<p>(NOTE: <code>id</code> may also be <code>IBOutlet</code>, especially if generated by ProjectCenter. It seems not to matter.)
</p>
<p>For example, if you connect a button to the outlet of one of your objects, say and outlet called <code>myButton</code>, when that nib is instantiated, <code>myButton</code> will contain a reference to an <code>NSButton</code> object, namely the button object on your interface that is connected to that outlet.
</p>
<p>Another example is creating a main window for your user interface. You may decide later that you wish to customise this window in code, based on user interactions. It would be appropriate to add an outlet to a top level object so that you can access this instance of the window.
</p>
<p>You will often create a special subclass of <code>NSObject</code> named something like <var>AppController</var> or <code>ApplicationController</code> and instantiate it. You will then add outlets and actions to this so that you can centralise access to your programme&rsquo;s widgets. The default Application project type in ProjectCenter does this for you, and many tutorials will present outlets and actions to you like this.
</p>
<a name="index-action"></a>
<p>An <em>action</em> is a method or function of behaviour that a class may perform. For example, you can connect a button to an action listed in NSOwner, so that when the button is clicked, it will send a message to the NSOwner object that will perform the action you connected. Actions are listed as methods on objects, but they take the form:
</p><div class="smallexample">
<pre class="smallexample">- (void) myAction:(id)sender;
</pre></div>

<p>Hence they are instance methods, taking one parameter, which is a reference to the object that is connected to the action. You could connect any number of objects to action on one object, so that it could distinguish between it&rsquo;s caller&rsquo;s by checking the sender object with GNUstep&rsquo;s introspection/reflection features.
</p>
<p>For example, say that you create an action on one of your custom objects called <code>compute:</code>. If you then connect a button object to your custom object and set <code>compute:</code> as the action, when the button is clicked, it will call <code>compute:</code> on your custom object.
</p>
<p>In short, objects are connected to outlets or actions, but outlets or actions are not connected to each other. To connect an object to an outlet or an action, you first select the object, then hold down the first control key (usually the left <kbd><span class="key">Ctrl</span></kbd> key on your keyboard), and select (using the mouse) the object which contains the outlet or action you wish to connect to. In the Inspector window, you select the target outlet or action, and click <code>Connect</code>. The action or outlet on the latter object will be connected to the first object.
</p>
<a name="index-NSOwner"></a>
<a name="NSOwner_003a-Who-controls-your-interface_003f"></a>
<h4 class="subsection">5.1.6 NSOwner: Who controls your interface?</h4>

<p><em>NSOwner</em> will appear as an object in the Objects Pane. You will notice that the only property you can set is it&rsquo;s class. NSOwner is an object, decided upon at runtime by your code, that will &quot;own&quot; this instance of your interface. You can instantiate interfaces more than once upon runtime, each time associating an instance with a different object.
</p>
<p>You can set NSOwner to be a custom class, with your outlets and actions, and then connect NSOwner to other objects or graphical elements or methods in your interface. 
</p>
<p>For example, you may create a custom subclass of NSObject called <code>MyController</code>. You may then give it a number of outlets, including one called <code>window</code>. You could set NSOwner to be of your subclass type, then connect <code>window</code> to the NSWindow object in the Object&rsquo;s pane. Upon runtime, whatever <code>MyController</code> object you set as NSOwner would have the associated NSWindow instance appear in it&rsquo;s <code>window</code> instance data value.
</p>
<a name="index-NSFirst"></a>
<a name="NSFirst"></a>
<h4 class="subsection">5.1.7 NSFirst</h4>

<a name="index-first-responder"></a>
<p>NSFirst is an abstract object, and may refer to any number of different graphical elements during the lifetime of your programme. It is what&rsquo;s known as the <em>first responder</em>, the object that is connected in such a way to receive event&rsquo;s first. The first responder may change depending on user interaction with a window, e.g. selecting an object in your window may cause it to become the first responder. 
</p>
<p>What you can do is connect outlets and actions to the first responder, and depending on whether the object that is set as <code>NSFirst</code>, the use may be able to perform that action. 
</p>
<p>For example, you may connect a menu item to call the <code>print:</code> action on the NSFirst object. GNUstep will automatically grey out this menu item if the object set as the first responder (decided by the user&rsquo;s currently selected object) is not able to respond to this action. If another object is to be later set as the first responder, and is able to respond to this action, GNUstep will automatically make the menu item available again. This way, you don&rsquo;t have to handle instances where the first responder object cannot respond to your method. GNUstep sets this all up using Objective-C&rsquo;s introspection features, by checking whether your object responds to the method corresponding to the action.
</p>
<a name="Loading-and-Instantiating-Interface-Files"></a>
<h3 class="section">5.2 Loading and Instantiating Interface Files</h3>

<a name="index-NSNib"></a>
<p>Once you&rsquo;ve created your interfaces files, you will want to instantiate them and display them. This is relatively simple in code, and merely requires you deal with the <var>NSNib</var> class. If your application contains only one interface file, it is possible to avoid this step altogether, and set the main interface nib as a property in your application&rsquo;s property list, as well as including it as a resource in your application&rsquo;s makefile.
</p>
<p>Otherwise, if you would like to instantiate it manually, especially if you have multiple interface files, you first create an NSNib object using the name of your interface file, and then instantiate it with a reference to your NSOwner object.
</p>
<div class="example">
<pre class="example">id myOwner;
NSNib* myNib;
NSArray* topLevelObjects;

// Assign myOwner to an object of the class that you set as NSOwner.

myNib = [[NSNib alloc] initWithNibNamed:@&quot;MyNibFile&quot; bundle:nil];
[myNib instantiateNibWithOwner:myOwner topLevelObjects:&amp;topLevelObjects];
</pre></div>

<a name="index-interface-files_002c-top-level-objects"></a>
<p>In this case, we first create the <code>NSNib</code> object <code>myNib</code> with a interface file called <samp>MyNibFile</samp>. We pass <code>nil</code> to the bundle parameter to indicate the main bundle; you can otherwise specify another bundle you may have already loaded into your programme. The <code>topLevelObjects:</code> parameter refers to the objects that appear in the Objects pane in Gorm. You can use Objective-C&rsquo;s reflection features to identify them.
</p>
<p>The nib is then instantiated with myOwner as the NSOwner object (you have to create this beforehand) and is passed a pointer to an <code>NSArray</code> reference so that you can receive the top level objects in your interface file. See the NSNib documenation in the AppKit reference manual for more details. There is simpler methods calls available for instantiating nib&rsquo;s as well under <code>NSBundle</code> (see the <cite>GNUstep GUI Reference Manual</cite>.
</p>
<div class="footnote">
<hr>
<h4 class="footnotes-heading">Footnotes</h4>

<h3><a name="FOOT4" href="#DOCF4">(4)</a></h3>
<p>This is a throwback to the origin&rsquo;s of the GNUstep framework, where it&rsquo;s API specification (OpenStep) was based on NeXTStep, which used &quot;nib&quot; files (NeXT Inteface Builder) to store interfaces.</p>
</div>
<hr>
<div class="header">
<p>
Next: <a href="controls.html#controls" accesskey="n" rel="next">controls</a>, Previous: <a href="applicationmakefiles.html#applicationmakefiles" accesskey="p" rel="prev">applicationmakefiles</a>, Up: <a href="index.html#Top" accesskey="u" rel="up">Top</a> &nbsp; [<a href="conceptindex.html#conceptindex" title="Index" rel="index">Index</a>]</p>
</div>



</body>
</html>
gnustep-gui-doc 0.24.0-3 / usr / share / GNUstep / Documentation / Developer / Gui / ProgrammingManual / AppKit / interfacefiles.html
