Server : Apache/2.4.41 (Ubuntu) System : Linux absol.cf 5.4.0-198-generic #218-Ubuntu SMP Fri Sep 27 20:18:53 UTC 2024 x86_64 User : www-data ( 33) PHP Version : 7.4.33 Disable Function : pcntl_alarm,pcntl_fork,pcntl_waitpid,pcntl_wait,pcntl_wifexited,pcntl_wifstopped,pcntl_wifsignaled,pcntl_wifcontinued,pcntl_wexitstatus,pcntl_wtermsig,pcntl_wstopsig,pcntl_signal,pcntl_signal_get_handler,pcntl_signal_dispatch,pcntl_get_last_error,pcntl_strerror,pcntl_sigprocmask,pcntl_sigwaitinfo,pcntl_sigtimedwait,pcntl_exec,pcntl_getpriority,pcntl_setpriority,pcntl_async_signals,pcntl_unshare, Directory : /proc/self/root/usr/share/doc/renaissance-doc/html/manual/
Upload File :
Current File : //proc/self/root/usr/share/doc/renaissance-doc/html/manual/node19.html
<!DOCTYPE HTML PUBLIC "-//W3C//DTD HTML 3.2 Final//EN">
<!--Converted with LaTeX2HTML 2002-2-1 (1.71)
original version by: Nikos Drakos, CBLU, University of Leeds
* revised and updated by: Marcus Hennecke, Ross Moore, Herb Swan
* with significant contributions from:
Jens Lippmann, Marek Rouchal, Martin Wilck and others -->
<HTML>
<HEAD>
<TITLE>2.5 The GSMarkup NSBundle Additions API</TITLE>
<META NAME="description" CONTENT="2.5 The GSMarkup NSBundle Additions API">
<META NAME="keywords" CONTENT="manual">
<META NAME="resource-type" CONTENT="document">
<META NAME="distribution" CONTENT="global">
<META NAME="Generator" CONTENT="LaTeX2HTML v2002-2-1">
<META HTTP-EQUIV="Content-Style-Type" CONTENT="text/css">
<LINK REL="STYLESHEET" HREF="manual.css">
<LINK REL="next" HREF="node20.html">
<LINK REL="previous" HREF="node18.html">
<LINK REL="up" HREF="node14.html">
<LINK REL="next" HREF="node20.html">
</HEAD>
<BODY BGCOLOR="#FFFFFF" text="#000000" link="#0000FF" vlink="#4444FF" alink="#3388FF">
<B> Next: <A NAME="tex2html714"
HREF="node20.html">2.6 Integrating Renaissance in</A> </B>
<B>Up: <A NAME="tex2html710"
HREF="node14.html">2. The GNUstep Markup</A> </B>
<B> Previous: <A NAME="tex2html704"
HREF="node18.html">2.4 The connectors section</A> </B>
<BR> <P>
<!--End of Navigation Panel-->
<!--Table of Child-Links-->
<A NAME="CHILD_LINKS"><STRONG>Subsections</STRONG></A>
<UL>
<LI><A NAME="tex2html715"
HREF="node19.html#SECTION00351000000000000000">2.5.1 What is the NSBundle Additions API</A>
<LI><A NAME="tex2html716"
HREF="node19.html#SECTION00352000000000000000">2.5.2 A small tweak to get it to work on Microsoft Windows</A>
<LI><A NAME="tex2html717"
HREF="node19.html#SECTION00353000000000000000">2.5.3 Methods reference</A>
<UL>
<LI><A NAME="tex2html718"
HREF="node19.html#SECTION00353100000000000000">2.5.3.1 NSBundle methods</A>
<LI><A NAME="tex2html719"
HREF="node19.html#SECTION00353200000000000000">2.5.3.2 awakeFromGSMarkup informal protocol</A>
<LI><A NAME="tex2html720"
HREF="node19.html#SECTION00353300000000000000">2.5.3.3 GSMarkupTopLevelObjects informal protocol</A>
</UL>
<BR>
<LI><A NAME="tex2html721"
HREF="node19.html#SECTION00354000000000000000">2.5.4 Accessing the top-level objects</A>
<UL>
<LI><A NAME="tex2html722"
HREF="node19.html#SECTION00354100000000000000">2.5.4.1 Example: loading a single view from a gsmarkup file</A>
</UL></UL>
<!--End of Table of Child-Links-->
<HR>
<H1><A NAME="SECTION00350000000000000000">
2.5 The GSMarkup NSBundle Additions API</A>
</H1>
<P>
<H2><A NAME="SECTION00351000000000000000">
2.5.1 What is the NSBundle Additions API</A>
</H2>
The main API for loading GSMarkup files into a running application is via
the NSBundle GSMarkup Additions. These are a set of category methods of
NSBundle which allow you to load a gsmarkup file into a running
application, or to get a list of the localizable strings in a gsmarkup
file (this is useful for applications which allow you to manage gsmarkup
files). The methods are declared in
<PRE>
Renaissance/GSMarkupBundleAdditions.h
</PRE>
so you need to <TT>#include</TT> (or <TT>#import</TT>) that file to
use them. This file is automatically included by
<PRE>
Renaissance/Renaissance.h
</PRE>
so if you are including the general <TT>Renaissance.h</TT> header, the
methods are automatically available. Please note that the API mirrors
the existing NIB loading API which is traditionally found on OpenStep,
with a few additional facilities.
<P>
<H2><A NAME="SECTION00352000000000000000">
2.5.2 A small tweak to get it to work on Microsoft Windows</A>
</H2>
If you are only using the NSBundle Additions API, you can have a
problem on Microsoft Windows where you need to reference something
inside a library to get it linked in. The recommended workaround is
to add the following line (or a similar one) to your program
(typically in your main.m file):
<PRE>
int (*linkRenaissanceIn)(int, const char **) = GSMarkupApplicationMain;
</PRE>
This defines a (dummy) function pointer called
<TT>linkRenaissanceInt</TT>, and generates a reference to
<TT>GSMarkupApplicationMain</TT> which fixes the problem.
<P>
<H2><A NAME="SECTION00353000000000000000">
2.5.3 Methods reference</A>
</H2>
We now list each method, followed by the explanation of what the
method does.
<P>
<H3><A NAME="SECTION00353100000000000000">
2.5.3.1 NSBundle methods</A>
</H3>
The methods listed in this section are methods of NSBundle.
<PRE>
+ (BOOL) loadGSMarkupFile: (NSString *)fileName
externalNameTable: (NSDictionary *)context
withZone: (NSZone *)zone
localizableStringsTable: (NSString *)table
inBundle: (NSBundle *)localizableStringsTableBundle;
</PRE>
This method is the method which does the actual loading; other loading
methods end up calling this one to do the loading. This method loads
the file <TT>fileName</TT> (an absolute path) into the application.
If <TT>fileName</TT> is missing the <TT>.gsmarkup</TT> extension, it is
automatically appended. The file is read, and all the sections are
parsed, resulting in a list of objects and of connectors, and a name
table mapping id names to objects which have been decoded. The
objects are then asked to replace themselves with the corresponding
platform objects, and the name table is updated accordingly. While
replacing themselves with the platform objects, the objects also
translate the eventual text which might need to be translated by using
the localizable strings given as argument, which is found in the
bundle given as argument. Each type of objects knows which attributes
or which content requires translation and which don't. Then, the
<TT>context</TT> dictionary (which is supposed to contain a mapping of
strings - id names - to objects already existing in the application;
typically it contains at least the <TT>NSOwner</TT> object) is merged
into the name table loaded from the file (except the special key-value
pair with key <TT>NSTopLevelObjects</TT>, which is not added to the
name table, and it is used later on for another task). The
connections are finally established using the final name table. Last,
all platform objects which were decoded from the file, and the
<TT>NSOwner</TT> object, if it exists, are sent the
<TT>awakeFromGSMarkup</TT> method. The top-level objects so created are
not autoreleased - so unless they are released at some point, they
will never be deallocated. This is correct for example for windows,
which are normally released when the user closes them; it is also
correct for some custom objects (the main controller object in the
application), which are supposed to just exist for the whole lifetime
of the application. But there are cases in which you might need
access to the top-level objects, for example in order to release them.
When Renaissance has loaded the file, it performs a few task which
have the purpose of making the top-level objects available to the
application. It posts the notification
<PRE>
GSMarkupBundleDidLoadGSMarkupNotification
</PRE>
with the file owner as object, and a dictionary containing the key
<TT>NSTopLevelObjects</TT> with value an array containing all the
top-level objects as user info. If the file owner responds to the
method
<PRE>
- (void) bundleDidLoadGSMarkup: (NSNotification *)notification;
</PRE>
this method is automatically called with the notification as its
argument, so you don't need to register the file owner to receive the
notification. Finally, if the <TT>context</TT> dictionary contains a
key <TT>NSTopLevelObjects</TT>, with value a NSMutableArray, this
array is filled with the top-level objects created from the .gsmarkup
file when it is read (for more information on retrieving the top-level
objects, please refer to section <A HREF="#top-level-objects">2.5.4</A>).
<TT>zone</TT> is supposed to be the memory zone from which all objects
created when reading the file are allocated; but it is currently
ignored, so you can pass <TT>NULL</TT> to it. The strings table and
bundle arguments are used to translate the messages contained in the
objects; if table is nil, the path extension is removed from the
filename, and that is used as string table (so that localizable
strings for the gsmarkup file <TT>example.gsmarkup</TT> are by default
searched in the localizable strings file
<TT>example.strings</TT>). If bundle is nil, the main bundle is used.
The method returns <TT>YES</TT> if the file could be loaded, and
<TT>NO</TT> otherwise.
<P>
<PRE>
+ (BOOL) loadGSMarkupFile: (NSString *)fileName
externalNameTable: (NSDictionary *)context
withZone: (NSZone *)zone;
</PRE>
This method is a short form of the previous one; it simply calls it
with nil table and nil bundle, which means that the localizable
strings are translated using the strings table with the same name as
the .gsmarkup file (extension removed) in the main bundle.
<P>
<PRE>
- (BOOL) loadGSMarkupFile: (NSString *)fileName
externalNameTable: (NSDictionary *)context
withZone: (NSZone *)zone
localizableStringsTable: (NSString *)table;
</PRE>
This method loads the gsmarkup file with name <TT>fileName</TT> (NB: if
the <TT>fileName</TT> string does not have the extension .gsmarkup, it is
automatically added) from the receiver bundle. The method first
locates the file to load in the bundle, by searching as in the
following example:
<PRE>
bundle_path/Resources/Italian.lproj/fileName.gsmarkup
bundle_path/Resources/English.lproj/fileName.gsmarkup
bundle_path/Resources/fileName.gsmarkup
bundle_path/Italian.lproj/fileName.gsmarkup
bundle_path/English.lproj/fileName.gsmarkup
bundle_path/fileName.gsmarkup
</PRE>
assuming that <TT>Italian.lproj</TT> is the user's preferred language.
This algorithm differs from the standard bundle searching algorithm in
that localized resources are preferred to non-localized ones (we're
still all wondering why NSBundle does not have a standard method doing
this by default). Once the file has been located and its absolute
path on disk is known, the method finally calls the NSBundle method
<PRE>
+ loadGSMarkupFile:
externalNameTable:
withZone:
localizableStringsTable:
inBundle:
</PRE>
with the given table as table argument, and the receiver bundle as
bundle argument, to perform the actual loading.
<P>
<PRE>
- (BOOL) loadGSMarkupFile: (NSString *)fileName
externalNameTable: (NSDictionary *)context
withZone: (NSZone *)zone;
</PRE>
This is a short form of the previous method, which uses a nil
localizableStringsTable, which causes the localizable strings file
with the same name as the gsmarkup file (extension removed) to be used as
localizable strings table.
<P>
<PRE>
+ (BOOL) loadGSMarkupNamed: (NSString *)fileName
owner: (id)owner;
</PRE>
This method is the more straightforward API to load a gsmarkup file.
<TT>fileName</TT> should be a file name (including the .gsmarkup
extension or not) (not an absolute path, just a file name);
<TT>owner</TT> should be an object provided by the application. Both
must not be nil, otherwise the method immediately returns <TT>NO</TT>.
The method first builds a context dictionary containing a single
key-value pair, which maps the string <TT>NSOwner</TT> to the object
<TT>owner</TT>; then, it gets the owner bundle (if the owner object
belongs to a bundle), or the main bundle (if the owner object does not
belong to a bundle); finally, it invokes the method
<TT>-loadGSMarkupFile:externalNameTable:withZone:</TT> of that bundle to load
the gsmarkup file. It uses as zone the owner's zone (but this detail is
currently ignored). It returns the result of invoking that method.
Localizable strings are by default translated using a table with the
same name as the gsmarkup file (extension removed, so that the localizable
strings file for <TT>test.gsmarkup</TT> would be <TT>test.strings</TT>),
from the bundle in which the file is loaded.
<P>
<PRE>
+ (NSArray *) localizableStringsInGSMarkupFile: (NSString *)fileName;
</PRE>
This method parses the <TT>fileName</TT> file (which should be an
absolute path to a file on disk; if the <TT>fileName</TT> string does
not end with <TT>.gsmarkup</TT>, this extension is automatically added),
and it extracts the list of localizable strings in the file. Each tag
knows exactly which strings found in its attributes and contents are
localizable; the list of localizable strings is built using this
knowledge.
<P>
<H3><A NAME="SECTION00353200000000000000">
2.5.3.2 awakeFromGSMarkup informal protocol</A>
</H3>
This section contains a single method, which any object can implement
to perform additional setup after it has been created from a GSMarkup
file.
<PRE>
- (void) awakeFromGSMarkup
</PRE>
This method is called on the objects created from a GSMarkup file, and
on the file owner (<TT>NSOwner</TT>), if any, after all connections
(outlets etc) have been established. You can implement this method to
complete the setup of your objects.
<P>
<H3><A NAME="SECTION00353300000000000000">
2.5.3.3 GSMarkupTopLevelObjects informal protocol</A>
</H3>
This section contains a single method, which the file owner can implement
to receive a notification when the gsmarkup is loaded. The notification
will include an array containing all top-level objects which were loaded
from the gsmarkup file.
<PRE>
- (void) bundleDidLoadGSMarkup: (NSNotification *)aNotification;
</PRE>
<P>
<H2><A NAME="SECTION00354000000000000000"> </A><A NAME="top-level-objects"> </A>
<BR>
2.5.4 Accessing the top-level objects
</H2>
There are basically three ways of accessing the top-level objects created
from a gsmarkup file:
<OL>
<LI>Using one of the NSBundle methods which allow you to set
manually the <TT>context</TT> dictionary, and adding a
<TT>NSTopLevelObjects</TT> to the <TT>context</TT> dictionary, with
value a mutable array. After loading the gsmarkup, Renaissance will
store in that dictionary all the top-level objects which have been
created from the file. For example:
<PRE>
NSDictionary *table;
NSMutableArray *topLevelObjects = [NSMutableArray array];
table = [NSDictionary dictionaryWithObjectsAndKeys:
self, @"NSOwner",
topLevelObjects, @"NSTopLevelObjects",
nil];
[NSBundle loadGSMarkupFile: @"MyFile"
externalNameTable: table
withZone: [self zone]];
/* Now topLevelObjects contains the top-level objects which
* were created from the gsmarkup file. */
</PRE>
This method of accessing the top-level objects is similar as the
method which can be used with NSBundleAdditions, where an
undocumented Apple extension can be used to get the top-level
objects by adding a key <TT>NSTopLevelObjects</TT> with value a
mutable array to the <TT>context</TT> dictionary.
<P>
</LI>
<LI>Implementing a <TT>-bundleDidLoadGSMarkup:</TT> method in the
file owner, and retrieving the top-level objects from the
notification object. Example:
<PRE>
- (void) bundleDidLoadGSMarkup: (NSNotification *)aNotification
{
NSArray *topLevelObjects;
topLevelObjects = [[aNotification userInfo] objectForKey:
@"NSTopLevelObjects"];
/* Now topLevelObjects contains the top-level objects which
* were created from the gsmarkup file. */
}
</PRE>
There is no equivalent of this method in the traditional NIB loading
API.
<P>
</LI>
<LI>Registering some object to receive the notification
<PRE>
GSMarkupBundleDidLoadGSMarkup
</PRE>
This is more advanced and more rarely useful; there is no equivalent
of this method in the traditional NIB loading API.
</LI>
</OL>
<P>
<H3><A NAME="SECTION00354100000000000000">
2.5.4.1 Example: loading a single view from a gsmarkup file</A>
</H3>
In most cases, a gsmarkup file contains one or more <TT><window></TT>
or <TT><panel></TT> objects. They are automatically displayed when
the file is loaded and there is nothing you need to do.
<P>
In some other cases you may want your gsmarkup file to only contain a
single view tag (such as a <TT><vbox></TT>) that you then want to
programmatically add to an already existing window. In this case, you
need to access the top-level objects using one of the techniques
explained above. For example, your gsmarkup file could be:
<PRE>
<?xml version="1.0"?>
<!DOCTYPE gsmarkup>
<gsmarkup>
<objects>
<vbox>
<button title="Miniaturize" action="performMiniaturize:" />
<button title="Quit" action="terminate:" />
</vbox>
</objects>
</gsmarkup>
</PRE>
<P>
If you want to add the <TT><vbox></TT> from that file to an existing
window, you would load it using code such as
<PRE>
NSDictionary *table;
NSMutableArray *topLevelObjects = [NSMutableArray array];
NSView *vbox;
table = [NSDictionary dictionaryWithObjectsAndKeys:
self, @"NSOwner",
topLevelObjects, @"NSTopLevelObjects",
nil];
[NSBundle loadGSMarkupFile: @"MyFile"
externalNameTable: table
withZone: [self zone]];
vbox = [topLevelObjects objectAtIndex: 0];
/* Now you can do something with vbox, eg, adding it to a window. */
</PRE>
<P>
<HR><B> Next: <A NAME="tex2html714"
HREF="node20.html">2.6 Integrating Renaissance in</A> </B>
<B>Up: <A NAME="tex2html710"
HREF="node14.html">2. The GNUstep Markup</A> </B>
<B> Previous: <A NAME="tex2html704"
HREF="node18.html">2.4 The connectors section</A> </B>
<!--End of Navigation Panel-->
<ADDRESS>
2008-03-19
</ADDRESS>
</BODY>
</HTML>
Server : Apache/2.4.41 (Ubuntu)