GNUstepWiki - User contributions [en]

Talk:Installation on Windows

2007-02-28T02:05:31Z

Quineska: /* Installation quirks */

Are the *-bin.zip files needed? Are not the *-lib files sufficient?

[[User:Stefan Urbanek|Stefan Urbanek]] 16:06, 10 Mar 2005 (CET)

=== Installation quirks ===

I had to do:

configure CPPFLAGS=-I/C/GNUstep/msys/1.0/include LDFLAGS=-I/C/GNUstep/msys/1.0/lib

to get the gui build going.

Also, ffcall wouldn't compile, so it was necessary to copy one from an older GNUstep installation on windows. I will make a zip of this and put in on the GNUstep ftp site so that others don't run into the same issue.

Later, GJC

---

I don't think that the libiconv stuff is necessary anymore, at least not with modern source distributions of libxml2. Also, there should be a warning NOT to install libxslt, as it gets compiled as a static library and its symbols clobber *everything* inside a DLL (hence messing up gnustep-base). It needs to be fixed for mingw (I'm sure the authors would have if they ever used the configure script in MSYS).

== TODO ==

* outdated, pull in http://www.gnustep.org/resources/documentation/User/GNUstep/README.MinGW
OR
* delete or convince everyone of putting these kind of things on the wiki and not in some external file.

Installation on Windows

2007-02-08T05:39:22Z

Quineska: /* Download gnustep using SVN */

= Install Windows GNUstep Manually =

== Install MinGW ==
Download MinGW-3.2.0-rc-3 or later from http://sourceforge.net/projects/mingw Install it into

C:/xxx/msys/1.0/mingw

(where /xxx/ is the top-level path you want to use, I use Nicola/GNUstep so I install it into C:/Nicola/GNUstep/msys/1.0/mingw) (earlier versions of MinGW won't work)

== Install msys ==

Download MSYS-1.0.10 or later from the same site. Install it into C:/xxx/msys/1.0
The postinstall script should ask you for the mingw location, then detect it and be happy that it's there and all is setup properly.

== Install msys developer toolkit ==

Download msysDTK-1.0.1 or later from the same site. Install it into

C:/xxx/msys/1.0

Now your MSYS/MinGW system should be setup! Go around and make sure you know how to use the Unix-like shell. Log into it and work in it.

== Download gnustep using SVN ==

In windows, go to
Start -> All Programs -> mingw -> MSYS ->Msys
The MINGW32 window appears.

Type the following:
mkdir install
cd install
svn co svn://svn.gna.org/svn/gnustep/modules/core

This will download the core GNUstep libraries (make, base, gui and back). You will need to have a copy of SVN installed somewhere on your system.

Alternatively, you could download the GNUstep Startup package the main site http://www.gnustep.org. It contains a copy of the core libraries as well (and can be used to automate the installation of an SVN copy as well).

== Install GNUstep make ==

cd gnustep/core/make
./configure --prefix=/C/xxx/GNUstep
make
make install

== Setup your GNUstep environment ==

(you will need to do the same every time you start up your MSYS shell to do development)

. /C/xxx/GNUstep/System/Library/Makefiles/GNUstep.sh

Also, set HOMEPATH, HOMEDRIVE and HOME ... add the following lines to your ~/.profile:

export HOMEDRIVE=C:
export HOMEPATH=/home/Nicola
export HOME=/C/xxx/msys/1.0/home/Nicola
. /C/xxx/GNUstep/System/Library/Makefiles/GNUstep.sh

(obviously replacing 'Nicola' with your Login name) (not sure if this setting of HOMEDRIVE etc is really required, will investigate)

== Install the ObjC runtime ==

Actually, recent versions of gcc (3.2+) have a working libobjc on Windows. Nevertheless this step is necessary (at least on Windows 2000) unless you want some strange errors concerning NSAutoreleasePool etc.

First make sure to delete the old libobjc files

find /C/xxx/GNUstep/ -iname "libobjc*" -exec rm -i {} \;

Then cd to dev-libs/libobjc in your cvs checkout directory and install it.
cd ~/install/gnustep/dev-libs/libobjc
make
make install

== Reinstall GNUstep make (with ObjC this time) ==

go in core/make and reconfigure/recompile again so that gnustep-objc is detected:
cd ~/install/gnustep/core/make
make distclean
./configure
make
make install

gnustep-make should have detected your custom libobjc.

== Install ffcall ==

Download ffcall from the GNUstep website into c:/xxx/msys/1.0/home/Nicola/install
or from here: ftp://ftp.santafe.edu/pub/gnu/ffcall-1.10.tar.gz,
and type:

cd ~/install
tar -zxvf ffcall-1.10.tar.gz
cd ffcall-1.10
./configure --prefix=$GNUSTEP_SYSTEM_ROOT
A windows prompt will appear stating that conftest.exe has encountered a problem and needs to close.

Click the [Don't Send] button.

A second windows prompt will appear stating that conftest.exe has encountered a problem and needs to close.

Click the [Don't Send] button.

A third windows prompt will appear stating that conftest.exe has encountered a problem and needs to close.

Click the [Don't Send] button.

After much output, the following will be displayed:

configure: creating ./config.status
config.status: creating Makefile
config.status: creating config.h

Type the following:

make
make install

Note: The configure script of ffcall-1.10 is broken for Windows 2000. You have to apply a patch: http://lists.gnu.org/archive/html/discuss-gnustep/2005-03/msg00258.html

Alternatively, a zip containing a precompiled copy of ffcall-1.9 is availabe here: ftp://ftp.gnustep.org/pub/gnustep/binaries/windows/mingw-libs/ffcall-1.9-gnustep.zip

Unzip it into $GNUSTEP_SYSTEM_ROOT/Library.

== Install additional libs ==

Download the following packages:

[http://sourceforge.net/project/showfiles.php?group_id=23617&package_id=73290 Download libintl]

libintl-0.11.5-2-bin.zip
libintl-0.11.5-2-lib.zip

[http://sourceforge.net/project/showfiles.php?group_id=23617&package_id=17090 Download libiconv]

libiconv-1.8.1-bin.zip
libiconv-1.8.1-lib.zip

[http://sourceforge.net/project/showfiles.php?group_id=23617&package_id=16861 Download zlib]

zlib-1.2.2-bin.zip
zlib-1.2.2-lib.zip

from http://gnuwin32.sourceforge.net, and install them. To install them, simply unzip them into

/C/xxx/msys/1.0/mingw.

== Install XML support ==

You will have to make some changes to libiconv for libxml to work properly.

cd /mingw/lib
mkdir backup-libiconv
mv libiconv.la backup-libiconv
mv libiconv.lib backup-libiconv
dlltool -D libiconv-2.dll -C -l libiconvlib --export-all-symbols -A ../bin/libiconv-2.dll

If there are no errors:

rm -r backup-libiconv

I had to compile libiconv from source for this to work (the binaries didn't work with my computer for some reason, and I'm not sure if it normally works.)

Download the latest version of libxml from [[ftp://xmlsoft.org/libxml2/]].

cd libxml2-...
vim include/libxml/xmlexports.h

There is a chunk of code in this file you will have to change.

Search for:

Windows platform with GNU compiler

in the code. Replace the code below it up to the comment about Cygwin:

#if defined(_WIN32) && defined(__MINGW32__)
#undef XMLPUBFUN
#undef XMLPUBVAR
#undef XMLCALL
#if !defined(LIBXML_STATIC)
#define XMLPUBFUN __declspec(dllexport)
#define XMLPUBVAR __declspec(dllexport) extern
#else
#define XMLPUBFUN
#if !defined(LIBXML_STATIC)
#define XMLPUBVAR __declspec(dllimport) extern
#else
#define XMLPUBVAR extern
#endif
#endif
#define XMLCALL __cdecl
#if !defined _REENTRANT
#define _REENTRANT
#endif
#endif

Save the file, then quit. Then compile normally.

./configure
make
make install

I never installed to the end with this method (halfway through I just decided to use the installer) but it worked well for me.

== Install GNUstep base ==

go in gnustep-base, and type

cd ~/install/gnustep/core/base
./configure
make
make install

If you didn't install libxml,

./configure --disable-xml
make
make install

== Install additional GUI libs ==

for the gui, download and install the following packages:

[http://sourceforge.net/project/showfiles.php?group_id=23617&package_id=16348&release_id=218220 Download jpeg]

jpeg-6b-3-bin.zip
jpeg-6b-3-dep.zip
jpeg-6b-3-lib.zip

[http://sourceforge.net/project/showfiles.php?group_id=23617&package_id=16351 Download tiff]

tiff-3.7.1-bin.zip
tiff-3.7.1-dep.zip
tiff-3.7.1-lib.zip

[http://sourceforge.net/project/showfiles.php?group_id=23617&package_id=16183 Download libpng]

libpng-1.2.8-bin.zip
libpng-1.2.8-dep.zip
libpng-1.2.8-lib.zip

The process is always the same: download the zip file from the gnuwin32 website, then unzip them into

/C/xxx/msys/1.0/mingw.

== Install GNUstep gui ==

Type the following:
cd ~/install/gnustep/core/gui
./configure
make
make install

== Install GNUstep back ==

go in back, and type:

./configure
make
make install

== Check the installation ==

go in a simple gui application (examples/gui a very good starting point), compile and run it. :-)

''based on a mail from Nicola Pero''

= GNUstep .exe installer using Nullsoft's [http://nsis.sourceforge.net/Main_Page NSIS] =

== install instruction ==
There are three versions of exe installer for gnustep.

* Download [ftp://ftp.gnustep.org/pub/gnustep/binaries/windows gnustep NSIS installer ].
** select copy the binaries.

* Download and compile gnustep examples tar ball.

* "openapp GSTest.app" will bring up a screen with GNUstep interface.

= GNUstep MSI installer created by [http://wix.sourceforge.net/ WiX] =

There are three sub packages
* user : To minimize the footprint of gnustep system on Windows machines.
* developer : include WiX,gcc and package sources.
* gnustep applications : include a broad suite of GNUstep applications.
== Install GNUstep MSI installer ==
* Download the msi from here.
* answer following questions.
* Test the installation.
== Prepare your gnustep win32 development environment ==
=== List of depended software ===
* WiX Win32 MSI package creation tool.
** candle.exe
<pre>
C:\tmp>candle
Microsoft (R) Windows Installer Xml Compiler version 2.0.4221.0
Copyright (C) Microsoft Corporation 2003. All rights reserved.

usage: candle.exe [-?] [-nologo] [-out outputFile] sourceFile [sourceFile ...]

-d<name>=<value> define a parameter for the preprocessor
-p<file> preprocess to a file (or stdout if no file supplied)
-I<dir> add to include search path
-nologo skip printing candle logo information
-out specify output file (default: write to current directory)
-pedantic:<level> pedantic checks (levels: easy, heroic, legendary)

<snip>

For more information see: http://wix.sourceforge.net

C:\tmp>
</pre>

** light.exe
<pre>
C:\tmp>light
Microsoft (R) Windows Installer Xml Linker version 2.0.4221.0
Copyright (C) Microsoft Corporation 2003. All rights reserved.

usage: light.exe [-?] [-b basePath] [-nologo] [-out outputFile] objectFile [o
jectFile ...]

-ai allow identical rows, identical rows will be treated as a warning
-au (experimental) allow unresolved references, will not create a val
d output
-b base path to locate all files (default: current directory)
-cc path to cache built cabinets (will not be deleted after linking)

<snip>

For more information see: http://wix.sourceforge.net

C:\tmp>
</pre>
* makefile for nmake.
* gcc win32 compiler from MingW.

=== Checkout gnustep.wxs ===
=== overview of gnustep.wxs ===

Installation on Windows

2007-02-08T05:08:37Z

Quineska: Changed to downloading GNUstep with SVN

= Install Windows GNUstep Manually =

== Install MinGW ==
Download MinGW-3.2.0-rc-3 or later from http://sourceforge.net/projects/mingw Install it into

C:/xxx/msys/1.0/mingw

(where /xxx/ is the top-level path you want to use, I use Nicola/GNUstep so I install it into C:/Nicola/GNUstep/msys/1.0/mingw) (earlier versions of MinGW won't work)

== Install msys ==

Download MSYS-1.0.10 or later from the same site. Install it into C:/xxx/msys/1.0
The postinstall script should ask you for the mingw location, then detect it and be happy that it's there and all is setup properly.

== Install msys developer toolkit ==

Download msysDTK-1.0.1 or later from the same site. Install it into

C:/xxx/msys/1.0

Now your MSYS/MinGW system should be setup! Go around and make sure you know how to use the Unix-like shell. Log into it and work in it.

== Download gnustep using SVN ==

In windows, go to
Start -> All Programs -> mingw -> MSYS ->Msys
The MINGW32 window appears.

Type the following:
mkdir install
cd install
svn co svn://svn.gna.org/svn/gnustep/devmodules/core

This will download the core GNUstep libraries (make, base, gui and back). You will need to have a copy of SVN installed somewhere on your system.

Alternatively, you could download the GNUstep Startup package the main site http://www.gnustep.org. It contains a copy of the core libraries as well (and can be used to automate the installation of an SVN copy as well).

== Install GNUstep make ==

cd gnustep/core/make
./configure --prefix=/C/xxx/GNUstep
make
make install

== Setup your GNUstep environment ==

(you will need to do the same every time you start up your MSYS shell to do development)

. /C/xxx/GNUstep/System/Library/Makefiles/GNUstep.sh

Also, set HOMEPATH, HOMEDRIVE and HOME ... add the following lines to your ~/.profile:

export HOMEDRIVE=C:
export HOMEPATH=/home/Nicola
export HOME=/C/xxx/msys/1.0/home/Nicola
. /C/xxx/GNUstep/System/Library/Makefiles/GNUstep.sh

(obviously replacing 'Nicola' with your Login name) (not sure if this setting of HOMEDRIVE etc is really required, will investigate)

== Install the ObjC runtime ==

Actually, recent versions of gcc (3.2+) have a working libobjc on Windows. Nevertheless this step is necessary (at least on Windows 2000) unless you want some strange errors concerning NSAutoreleasePool etc.

First make sure to delete the old libobjc files

find /C/xxx/GNUstep/ -iname "libobjc*" -exec rm -i {} \;

Then cd to dev-libs/libobjc in your cvs checkout directory and install it.
cd ~/install/gnustep/dev-libs/libobjc
make
make install

== Reinstall GNUstep make (with ObjC this time) ==

go in core/make and reconfigure/recompile again so that gnustep-objc is detected:
cd ~/install/gnustep/core/make
make distclean
./configure
make
make install

gnustep-make should have detected your custom libobjc.

== Install ffcall ==

Download ffcall from the GNUstep website into c:/xxx/msys/1.0/home/Nicola/install
or from here: ftp://ftp.santafe.edu/pub/gnu/ffcall-1.10.tar.gz,
and type:

cd ~/install
tar -zxvf ffcall-1.10.tar.gz
cd ffcall-1.10
./configure --prefix=$GNUSTEP_SYSTEM_ROOT
A windows prompt will appear stating that conftest.exe has encountered a problem and needs to close.

Click the [Don't Send] button.

A second windows prompt will appear stating that conftest.exe has encountered a problem and needs to close.

Click the [Don't Send] button.

A third windows prompt will appear stating that conftest.exe has encountered a problem and needs to close.

Click the [Don't Send] button.

After much output, the following will be displayed:

configure: creating ./config.status
config.status: creating Makefile
config.status: creating config.h

Type the following:

make
make install

Note: The configure script of ffcall-1.10 is broken for Windows 2000. You have to apply a patch: http://lists.gnu.org/archive/html/discuss-gnustep/2005-03/msg00258.html

Alternatively, a zip containing a precompiled copy of ffcall-1.9 is availabe here: ftp://ftp.gnustep.org/pub/gnustep/binaries/windows/mingw-libs/ffcall-1.9-gnustep.zip

Unzip it into $GNUSTEP_SYSTEM_ROOT/Library.

== Install additional libs ==

Download the following packages:

[http://sourceforge.net/project/showfiles.php?group_id=23617&package_id=73290 Download libintl]

libintl-0.11.5-2-bin.zip
libintl-0.11.5-2-lib.zip

[http://sourceforge.net/project/showfiles.php?group_id=23617&package_id=17090 Download libiconv]

libiconv-1.8.1-bin.zip
libiconv-1.8.1-lib.zip

[http://sourceforge.net/project/showfiles.php?group_id=23617&package_id=16861 Download zlib]

zlib-1.2.2-bin.zip
zlib-1.2.2-lib.zip

from http://gnuwin32.sourceforge.net, and install them. To install them, simply unzip them into

/C/xxx/msys/1.0/mingw.

== Install XML support ==

You will have to make some changes to libiconv for libxml to work properly.

cd /mingw/lib
mkdir backup-libiconv
mv libiconv.la backup-libiconv
mv libiconv.lib backup-libiconv
dlltool -D libiconv-2.dll -C -l libiconvlib --export-all-symbols -A ../bin/libiconv-2.dll

If there are no errors:

rm -r backup-libiconv

I had to compile libiconv from source for this to work (the binaries didn't work with my computer for some reason, and I'm not sure if it normally works.)

Download the latest version of libxml from [[ftp://xmlsoft.org/libxml2/]].

cd libxml2-...
vim include/libxml/xmlexports.h

There is a chunk of code in this file you will have to change.

Search for:

Windows platform with GNU compiler

in the code. Replace the code below it up to the comment about Cygwin:

#if defined(_WIN32) && defined(__MINGW32__)
#undef XMLPUBFUN
#undef XMLPUBVAR
#undef XMLCALL
#if !defined(LIBXML_STATIC)
#define XMLPUBFUN __declspec(dllexport)
#define XMLPUBVAR __declspec(dllexport) extern
#else
#define XMLPUBFUN
#if !defined(LIBXML_STATIC)
#define XMLPUBVAR __declspec(dllimport) extern
#else
#define XMLPUBVAR extern
#endif
#endif
#define XMLCALL __cdecl
#if !defined _REENTRANT
#define _REENTRANT
#endif
#endif

Save the file, then quit. Then compile normally.

./configure
make
make install

I never installed to the end with this method (halfway through I just decided to use the installer) but it worked well for me.

== Install GNUstep base ==

go in gnustep-base, and type

cd ~/install/gnustep/core/base
./configure
make
make install

If you didn't install libxml,

./configure --disable-xml
make
make install

== Install additional GUI libs ==

for the gui, download and install the following packages:

[http://sourceforge.net/project/showfiles.php?group_id=23617&package_id=16348&release_id=218220 Download jpeg]

jpeg-6b-3-bin.zip
jpeg-6b-3-dep.zip
jpeg-6b-3-lib.zip

[http://sourceforge.net/project/showfiles.php?group_id=23617&package_id=16351 Download tiff]

tiff-3.7.1-bin.zip
tiff-3.7.1-dep.zip
tiff-3.7.1-lib.zip

[http://sourceforge.net/project/showfiles.php?group_id=23617&package_id=16183 Download libpng]

libpng-1.2.8-bin.zip
libpng-1.2.8-dep.zip
libpng-1.2.8-lib.zip

The process is always the same: download the zip file from the gnuwin32 website, then unzip them into

/C/xxx/msys/1.0/mingw.

== Install GNUstep gui ==

Type the following:
cd ~/install/gnustep/core/gui
./configure
make
make install

== Install GNUstep back ==

go in back, and type:

./configure
make
make install

== Check the installation ==

go in a simple gui application (examples/gui a very good starting point), compile and run it. :-)

''based on a mail from Nicola Pero''

= GNUstep .exe installer using Nullsoft's [http://nsis.sourceforge.net/Main_Page NSIS] =

== install instruction ==
There are three versions of exe installer for gnustep.

* Download [ftp://ftp.gnustep.org/pub/gnustep/binaries/windows gnustep NSIS installer ].
** select copy the binaries.

* Download and compile gnustep examples tar ball.

* "openapp GSTest.app" will bring up a screen with GNUstep interface.

= GNUstep MSI installer created by [http://wix.sourceforge.net/ WiX] =

There are three sub packages
* user : To minimize the footprint of gnustep system on Windows machines.
* developer : include WiX,gcc and package sources.
* gnustep applications : include a broad suite of GNUstep applications.
== Install GNUstep MSI installer ==
* Download the msi from here.
* answer following questions.
* Test the installation.
== Prepare your gnustep win32 development environment ==
=== List of depended software ===
* WiX Win32 MSI package creation tool.
** candle.exe
<pre>
C:\tmp>candle
Microsoft (R) Windows Installer Xml Compiler version 2.0.4221.0
Copyright (C) Microsoft Corporation 2003. All rights reserved.

usage: candle.exe [-?] [-nologo] [-out outputFile] sourceFile [sourceFile ...]

-d<name>=<value> define a parameter for the preprocessor
-p<file> preprocess to a file (or stdout if no file supplied)
-I<dir> add to include search path
-nologo skip printing candle logo information
-out specify output file (default: write to current directory)
-pedantic:<level> pedantic checks (levels: easy, heroic, legendary)

<snip>

For more information see: http://wix.sourceforge.net

C:\tmp>
</pre>

** light.exe
<pre>
C:\tmp>light
Microsoft (R) Windows Installer Xml Linker version 2.0.4221.0
Copyright (C) Microsoft Corporation 2003. All rights reserved.

usage: light.exe [-?] [-b basePath] [-nologo] [-out outputFile] objectFile [o
jectFile ...]

-ai allow identical rows, identical rows will be treated as a warning
-au (experimental) allow unresolved references, will not create a val
d output
-b base path to locate all files (default: current directory)
-cc path to cache built cabinets (will not be deleted after linking)

<snip>

For more information see: http://wix.sourceforge.net

C:\tmp>
</pre>
* makefile for nmake.
* gcc win32 compiler from MingW.

=== Checkout gnustep.wxs ===
=== overview of gnustep.wxs ===

Creating document based applications

2005-11-28T00:39:16Z

Quineska: /* Application Interface File */

Note: First version; subject to further revisions and changes.
--[[User:Quineska|ChrisArmstrong]] 07:09, 7 Jul 2005 (CEST)

== Introduction ==

[[OpenStep]] can provide your application a document-based model. It helps to simplify the process of creating such applications. [[GNUstep]] implements this as well; this document aims to provide an overview of what is required in the creation and design of such an application.

It is assumed you are familiar with GNUstep, and have some understanding as how to create [[Gorm]]'s interface files (often referred to as nib's), as well as some understanding of how they work.

Importantly, such applications have certain components that are required, and should be considered as part of their design. When programming, classes that will be used as part of the [[AppKit]] are:

==== NSDocument ====

This class is central to the OpenStep document based model. These application's declare a new instance of a subclass of NSDocument for each “document” that is opened. You will subclass NSDocument to implement this.

Each instance of your NSDocument subclass may have one or more windows associated with it. These are used as an interface for loading and saving a representation of your document type. Each window will have an “NSWindowController” instance associated with it, where NSDocument maintains a list of these.

==== NSDocumentController ====

This class acts a controller. It maintains a list of documents (instances of your NSDocument subclass) and is responsible for loading and instantiating new documents. It is usually not necessary to implement a subclass of this, but often it may be useful to implement special functionality (especially related to opening and creating documents at an application level).

==== NSWindowController ====

As mentioned above, NSWindowController instances are individually associated with one NSWindow instance, in such a way that a document maintains a list of window controllers that are reponsible for rendering the views associated with a document.

You will most likely not have to subclass NSWindowController. Instead, you associate a nib file (the Gorm output) with the subclass of NSDocument, and NSDocumentController will load this nib file for each document that is created or loaded.

For example, a text based application that is used for the editing of plain text files, may subclass NSDocument with a TextDocument class. Each instance of this class would have an NSWindowController instance associated with it, which in turn manages a window instance that is instantiated from a nib file. The NSDocumentController instance, as managed and instantiated by GNUstep, would be responsible for loading and saving documents in your application. It even prompts the user to save their documents when they try to quit the application.

== File Components ==

In building your application you will need to create a number of special files. From scratch, the following should be a rough guide to getting it working. These include the Makefile, your application's property list and the interface files.

=== The Makefile ===

For this type of application, no special makefile is needed: it just has to be a normal application. Project Builder should be able to spit out the required makefile and Gorm files that are needed for a generic application. I believe it is also capable of providing support for document-based applications. Otherwise use the following as a template:

'''GNUmakefile'''

include $(GNUSTEP_MAKEFILES)/common.make 
APP_NAME = DocumentApp 
DocumentApp_OBJC_FILES = 
MyDocument.m 
main.m 
DocumentApp_RESOURCES = \ 
Resources/Info-gnustep.plist \ 
Resources/DocumentApp.gorm \ 
Resources/MyDocument.gorm 
-include GNUmakefile.preamble 
include $(GNUSTEP_MAKEFILES)/application.make 
-include GNUmakefile.postamble 

For more information as to customising this file, as well as setting up compiler options for third party libraries and includes, see the GNUstep makefile manual.

===The application dictionary===

For those that have edited this file in their project before, it is a dictionary with various values entered. For our purposes, we need an array within the main dictionary, called "NSTypes". This is a array of unnamed dictionaries, with one dictionary for each type.

I have provided an example for this file below. ProjectBuilder creates one as well. Please note that "TextEdit" does exist as an example application from NEXT I think, and again on MacOS X but I have constructed a much simpler version, used only for plain text files.

Taking a look at the single dictionary entry in the NSTypes array, the following key-value pairs are needed:
* '''NSDocumentClass:''' This is (string) the subclass name you use in your code, the "objective-c name" of your document subclass. This is used by NSDocumentController's default implementation to create instances of your document type.
* '''NSName:''' The generic file type (string). This is completely arbitrary, and can be anything you like. For the purpose of conventions, it may be more appropriate not to use the "NS" or "GS" prefix (the latter of which I not sure), and instead use either your own, or no prefix at all.
* '''NSHumanReadableName:''' The human readable name of your document type (string)? TODO: explain where this is used.
* '''NSUnixExtensions:''' An array of strings, each containing a file extension connected to this document type on "unix" platforms. TODO: explain how "unix" is interpreted by GNUstep.
* '''NSDOSExtensions:''' An array of strings, each containing a file extenstion connected to this document type on "DOS" platforms (could be loosely interpreted as any MS platforms GNUstep runs on, i.e. Windows 2000/XP).
* '''NSRole:''' A string, either "Viewer" or "Editor", depending on how your document operates on this file type.
* '''NSIcon:''' A icon name associated with this document type. TODO: Investigate how this works.

'''Info-gnustep.plist'''
{
ApplicationDescription = "A simple text editor for GNUstep.";
ApplicationName = TextEdit;
ApplicationRelease = 0.10;
Authors = ( "Christopher Armstrong" );
Copyright = "Copyright (C) 2005 Christopher Armstrong";
CopyrightDescription = "Released under GPL.";
FullVersionID = 0.10;
NSExecutable = TextEdit;
NSMainNibFile = TextEdit.gorm;
NSPrincipalClass = NSApplication;
NSRole = Application;
NSTypes = (
{
NSDocumentClass = "TextDocument";
NSName = "GSTextDocumentType";
NSHumanReadableName = "Text Document";
NSUnixExtensions = ( "txt", "" );
NSDOSExtensions = ( "txt" );
NSRole = Editor;
}
);
}

For more information on property list files, consult [[Property Lists]].

=== Interface files ===

Two interface files are needed: one for your main application, and another that will be instantiated with each instance of your document subclass. These both should be listed as resources in your makefile, (as shown the GNUmakefile example above). It may be helpful to name the document nib file after your class.

==== Application Interface File ====

The application one should just be a menu (though it could be more if necessary). When constructing it, take the following into account:

* '''Use an "Application" template''': Use a standard Gorm template for an Application.
* '''Delete the NSWindow instance''': In the "Objects" pane, remove the NSWindow instance by going File->Delete (unless you need a main window, which is beyond the scope of this document).
* '''Set NSOwner's class to "NSDocumentController"''': This is the custom class option of NSOwner in the property inspector. This ensures that the openDocument:, newDocument: messages, as sent to NSFirst, get picked up by NSDocumentController. Do not instantiate it (I believe you can't anyway).
* '''[Optional] Subclass NSDocumentController''':If you intend to subclass NSDocumentController, subclass it in the Classes pane. To make sure that this class is instantiated and used, make sure you instantiate it in Gorm or in your main.m file, and then set NSOwner to be of your custom subclass type.
* '''Add a "Document" menu''': Drag a Document menu from the palette onto your main menu. This already has the proper outlet and action linkage for each relevant message to be directed to NSFirst. Generic messages (such as openDocument:, not associated with any document instance) are forwarded to the shared instance of NSDocumentController (see it's reference documentation). When a document is active, more specific messages (such as close: or saveDocument:) are forwarded to the relevant document instance of your NSDocument subclass.
* '''[Optional] Add other menus''': Add any appropriate menus such as "Info" and "Format" which may be relevant to your application.

==== Document Interface File(s) ====

The document interface file is a window containing the view(s) required for the implementation of one instance of your document type. For example, in the case of a TextDocument type, a window instance with a NSTextView drawn on it is used for each document window. This interface file is instantiated every time a person creates a new document (the newDocument: message is sent to NSDocumentController) or opens an existing document (openDocument:).

You will need to:
* '''Subclass NSDocument''' with your document type in Gorm. This is done in a couple of ways, see [[Gorm_Manual#Custom_classes|custom classes]]. It is up to you whether or not you let Gorm generate the class files, but make sure you add the appropriate outlets to your class in the source files (otherwise, I think your your program may segfault).
* '''Set NSOwner:''' Set your subclass as NSOwner's Custom class using the Property Inspector. ''DO NOT INSTANTIATE IT.''

Another thing that you may want to consider is custom outlets. If you place certain views or controls on your window (including the window itself), you may want to refer to them directly in your code, e.g. the NSTextView in our TextEdit example is accessed directly, so that we can save it's contents to a file. To enable this, we add outlets to our class (see [[Gorm_Manual#Custom_classes|custom classes]]). We then connect NSOwner to the appropriate controls/views, and select the outlets in the Connections Property Inspector (see [[Gorm_Manual#Editing_the_interface|editing the interface]]).

== Code ==

Various things need to be done at a code level, to ensure that your NSDocument subclass is properly instantiated. This section aims to tell you what is necessary.

=== NSDocument subclass ===

When creating your subclass, you may have chosen to have Gorm create the class files. If not, you should create two files for your subclass: a header (.h) file and an implementation file (.m). The header file should take the following layout (we're using the TextEdit example again):

#ifndef TEXTDOCUMENT_H
#define TEXTDOCUMENT_H 
#include <AppKit/AppKit.h> 
@class NSDocument; 
/* The document type string, as specified in the property list [[#The_application_dictionary|NSTypes array]] */ 
NSString * GSTextDocumentType = "GSTextDocumentType";
@interface TextDocument : NSDocument
{
@protected
/* Outlets we added in our Gorm nib file */
id * textView;
}
/* Basic methods used for loading and saving document data (respectively). */
- (BOOL) loadDataRepresentation:(NSData*)representation ofType:(NSString*)type;
- (NSData*) dataRepresentationOfType: (NSString*)type; 
/* Information and events handling of GUI related changes */
- (NSString*) windowNibName;
- (void) windowControllerDidLoadNib:(NSWindowController*)windowController; 
@end 

Firstly, take note that we inherit from NSDocument. As a result, we need to override some methods for a basic (but working) implementation.

==== loadDataRepresentation:ofType: and dataRepresentationOfType: ====

The methods, loadDataRepresent:ofType: and dataRepresentationOfType: are used by NSDocumentController to load and save our files. The first method is called when the user trys to open a document (NSDocumentController gets the file name and copies it's data using an open panel). The method is passed the raw data in this file, as well as a string representing its type. It is important to note that this type string is the same one used in your property list. It is used by NSDocumentController to tell you what type it thinks you should open the data with. If this is not possible, or if there is an error trying to parse the data, your method returns FALSE/NO. Otherwise, you should store a local, meaningful representation of the data, which you can insert into your document window a little later (and return TRUE/YES).

For example, in terms of the TextEdit example:
- (BOOL) loadDataRepresentation:(NSData*) representation ofType:(NSString*)type
{
/*Check type information */
if ([representation equalTo:GSTextDocumentType]==NO)
return NO;
/* Clean out our old representation if it still exists */
if (fileContents) RELEASE(fileContents); 
/* Allocate room for the new data, and try to initialise a string with it. */
self->fileContents = [NSString alloc];
fileContents = [fileContents initWithBytes: [representation bytes]
length: [representation length]
encoding: NSASCIIStringEncoding]; 
/* If this can't be done, return NO */
if (!fileContents)
return NO; 
/* Otherwise, set our TextView to the string data. */
[self->textView setString: fileContents];
return YES;
}

If this is not sufficient, or if your program can open the data in a more efficient manner, it may be worth looking into overriding -initWithContentsOfFile:ofType: and -initWithContentsOfURL:ofType:. Again, see the GUI manual for more details.

dataRepresentationOfType: is used to save the data. Your method is expected to return an instance of NSData that contains what should be saved to a file, for the type specified. Again, the ''type'' variable should be checked to ensure that you can write data of that type. Return nil if the file cannot be saved as that type.

For example:

- (NSData*) dataRepresentationOfType:(NSString*)type
{
if ([type equalTo:GSTextDocumentType]==NO)
return nil; 
NSData stringData = [[textView string] dataUsingEncoding:NSASCIIStringEncoding];
return stringData;
}

If a more sophisticated save implementation is needed, consult the documentation for information on the writeTo* methods.

==== windowNibName ====

This method must be overriden to return the a string of the name of your nib file (without the file extension). More complex implementations will use other methods to load the interface files. TODO: information on what methods need to be overriden.

==== windowControllerDidLoadNib: ====

Use this method to add code that should be run as soon as ''windowController'' has been initialised. Your document may have many window controllers; each window controller taking possession of one window.

In the TextEdit example, this method is used to copy the ''fileContents'' variable to the text view. It otherwise initialises the document window.

Also note that you can override windowControllerWillLoadNib: to perform pre-interface loading initialisation.

==== makeWindowControllers ====

This is an optional method to override, which must be used if you have multiple window controllers per document. It is responsible for creating each window controller from it's interface file and then adding it to the document. Use the addWindowController: method.

==== Other considerations ====

* You need a way to notify NSDocument that your document has changed, so that NSDocumentController can enable the menu item to allow saving. This is done by a call to the updateChangeCount: method. For example, the TextDocument class adds itself as a delegate to the textView, for any notification of changes. It then calls updateChangeCount: in the delegate's method.

* You may also wish to add a close: method (not the close method already in NSDocument, see below) to respond to the menu item permitting your document to close. This could perform cleanup operations before a call to [self close] is made e.g.

- (void) close:(id)sender /* Note this is not the method found in NSDocument (they differ by a parameter) */
{
[self close];
}

=== NSDocumentController ===

This class can optionally be subclassed, to implement some specific functionality. For example, programs handling multiple document types may override newDocument: to create a window so that the user can select which document type to create.

You should use separate implementation files and add the .m file to GNUmakefile.

=== NSWindowController ===

This class can also be optionally subclassed, to implement functionality specific to a window controller for a document type. You may need to override makeWindowControllers: in the NSDocument subclass in order to make sure your specific window controller is instantiated.

You should use separate implemenation files and add the .m file to GNUmakefile.

== Optional Additions ==

=== Custom NSDocumentController and NSWindowController implementations ===

See [[#NSWindowController|NSWindowController]] and [[#NSDocumentController|NSDocumentController]].

----

[[Category:Development]]

Platform compatibility

2005-11-22T07:47:42Z

Quineska: /* MingW */ Added "Installation on Windows" Link

'''Note''': Anyone know how to convert [http://www.gnustep.org/resources/documentation/User/GNUstep/gnustep-howto_toc.html Platform Compatibility HowTO] source into wiki language, so we can work on others' effort?

Following are procedures for installing GNUstep on different Operating Systems. 

=== AIX ===
''To be provided.''

----

=== BSD ===

==== Darwin-based Systems ====
''To be provided.''

===== Intel =====
''To be provided.''

===== PowerPC =====
''To be provided.''

==== FreeBSD-based Systems ====

===== DesktopBSD =====
[http://desktopbsd.sourceforge.net/ DesktopBSD] joins the ranks of PC-BSD and FreeSBIE as a desktop-ready version of FreeBSD. However, their desktop is based on [http://www.kde.org KDE].

===== DragonFly =====
[http://www.dragonflybsd.org/main/ DragonFly] is an operating system and environment designed to be the logical continuation of the [[Platform_compatibility#FreeBSD|FreeBSD]]-4.x OS series.

I have mostly ported GNUstep to DragonFly, I just need to submit patches now for both GNUstep and DragonFly. To know more, you can contact me. ''[[user:Qmathe | Quentin Mathé]]''

===== FreeBSD =====
You can install GNUstep via ''/usr/ports/devel/gnustep''. However, not all required dependencies are installed.

If you install the following in advance, you should be fine: ''[http://www.freshports.org/x11-wm/windowmaker/ wmaker], [http://www.freshports.org/textproc/libxml2/ libxml2], [http://www.freshports.org/textproc/libxslt/ libxslt], [http://www.freshports.org/math/libgmp4/ libgmp4], [http://www.freshports.org/graphics/libart_lgpl2/ libart_lgpl2], [http://www.freshports.org/audio/libaudiofile/ libaudiofile], [http://www.freshports.org/audio/portaudio/ portaudio], [http://www.freshports.org/devel/ffcall ffcall], [http://www.freshports.org/graphics/glitz/ glitz]''

''[http://www.freshports.org/print/cups/ CUPS]'' is used for printing functionality. OTOH, it is a good idea to go for [http://www.freshports.org/net/samba/ Samba] directly, which also includes CUPS.
Additionally, you may also want to install ''[http://www.freshports.org/net/mDNSResponder/ mDNSResponder]''.

'''Note''':
There is a bug in libkvm that '''requires''' a mounted ''/proc''. Until this bug is fixed, make sure you have an entry for ''/proc'' in your ''/etc/fstab'':

proc /proc procfs rw 0 0

References:
[http://www.freebsd.org/cgi/ports.cgi?query=gnustep&stype=all FreeBSD GNUstep ports],
[http://www.freshports.org/search.php?query=gnustep&search=go&num=10&stype=name&method=match&deleted=excludedeleted&start=1&casesensitivity=caseinsensitive Freshports GNUstep]

===== FreeBSD-Kernel w/ GNU userland =====
It was reported that this runs GNUstep as well. For more details see the topic of
the IRC channel #gnu-kbsd on irc.gnu.org

===== FreeSBIE =====
[http://www.freesbie.org/ FreeSBIE] is a Live-CD Version of FreeBSD.

===== PicoBSD =====
[http://people.freebsd.org/~picobsd/picobsd.html PicoBSD] is a one floppy version of [[Platform_compatibility#FreeBSD|FreeBSD]] 3.0-current. You won't be able to use it as a platform for GNUstep.

===== PC-BSD =====
[http://www.pcbsd.org/ PC-BSD] has as its goals to be an easy to install and use desktop OS, which is built on the [[Platform_compatibility#FreeBSD|FreeBSD]] operating system.

==== Mac OS X ====
''To be provided.''

==== NetBSD ====
Installing GNUstep from pkgsrc is really straight-forward for NetBSD if you're using a recent pkgsrc distribution. NetBSD/i386 has no known problems right now, however there are reports of crashout problems for gdomap on NetBSD/sparc which may be related to ffi/ffcall issues.

In terms of pre-requisites, ensure you've got a working X11 environment on your system and preferrably are using WindowMaker as your window manager.

'''Build instructions'''

To install GNUstep, you need to cd to your pkgsrc tree and then cd to the right package directory, on my system:

cd /usr/pkgsrc

then go to the package you wish to install, for example:

cd meta-pkgs/gnustep

and issue the command:

make install

This command will download source code and whatever dependencies and compile and install them. The version of the meta-packages I used (released with NetBSD 2.0 and called gnustep-1.10.0nb2) installs the following GNUstep components as parts of the meta-package:

* gnustep-make-1.10.0
* gnustep-base-1.10.1
* gnustep-ssl-1.10.1
* gnustep-gui-0.9.4
* gnustep-back-0.9.4
* gnustep-examples-1.0.0
* ImageViewer-0.6.3
* Pantomime-1.1.2
* Addresses-0.4.6
* GNUMail-1.1.2
* Gorm-0.8.0
* ProjectCenter-0.4.0
* GWLib-0.6.5
* Renaissance-0.8.0
* gworkspace-0.6.5

A number of dependency packages are also installed.

This may be overkill - if you don't need all the applications etc, you can install the packages individually.

==== OpenBSD ====
''To be provided.''

----

=== GNU/Hurd ===
GNUstep also runs on GNU/Hurd on the GNUMach kernel.

----

=== HP/UX ===
* GNUstep-core-1.0, please see http://en.wikibooks.org/wiki/CPAM_with_TWW/References_Manual#GNUstep_and_CPAM. look for the gnustep-core-1.0.sb and gnustep-core-1.0.pb file for building and packaging information.

----

=== Irix ===
''To be provided.''

----

=== Linux ===

==== Debian ====
Since Debian "Sarge" you can just say

apt-get install x-window-system-core wmaker gnustep gnustep-devel gnustep-games

to get GNUstep, X11 and Window Maker installed.

But what happen if you are on Debian stable (3.0) release ?

Here is an answer from gnustep irc channel:
<pre>
<fsmunoz> change every occurence of "stable" for "testing"
<fsmunoz> remove the security.debian.org line
<fsmunoz> do apt-get update
<fsmunoz> apt-get dist-upgrade
<fsmunoz> repeat this last one until nothing gets installed or removed.
<fsmunoz> the, replace "testing" with "unstable"
<fsmunoz> then, apt-get update
<fsmunoz> apt-get dist-upgrade
<fsmunoz> repeat, repeat.
<fsmunoz> done
</pre>

The above was a general guide to upgrade from Debian stable to unstable, not exactly the best way to install GNUstep packages. If one doesn't want to upgrade it is possible to simply add the unstable apt lines to the sources.list and specify the distribution when installing the packages, e.g.
<pre>
# apt-get install -t unstable gnumail.app
</pre>

This will probably upgrade some other packages to satisfy dependencies, but will have a much small impact on the system since only the packages on which GNUstep depends will be upgraded.

Yet another way is to add tarzeau's repository (powerpc and source); he packages a huge ammount of GNUstep packages. Just add this to your sources.list:
<pre>
deb http://www.linuks.mine.nu/debian/ ./
deb-src http://www.linuks.mine.nu/debian/ ./
</pre>

This repository contains packages made in unstable, so it's possible that the dependencies only are satisfied in unstable systems.

==== RedHat ====
''To be provided.''

===== Advance Server 3.0 =====
* GNUstep-core-1.0, please see http://en.wikibooks.org/wiki/CPAM_with_TWW#GNUstep_and_TWW_HPMS. look for the gnustep-core-1.0.sb and gnustep-core-1.0.pb file for building and packaging information.

===== FC 3 =====
''To be provided.''

==== Slackware ====
''To be provided.''

==== SuSE ====
''To be provided.''

----

=== Solaris ===

==== Intel ====
''To be provided.''

==== Sparc ====

* http://www.linuks.mine.nu/gnustep/solaris is one of package sources to create solaris packages for GNUstep.
* GNUstep-core-1.0, please see http://en.wikibooks.org/wiki/CPAM_with_TWW#GNUstep_and_TWW_HPMS. look for the gnustep-core-1.0.sb and gnustep-core-1.0.pb file for building and packaging information.

----

=== Windows ===

==== Cygwin ====
''To be provided.''

==== MingW ====

See [[Installation on Windows]] for details on MingW setup. Also look at precompiled binary installer, available from GNUstep's ftp site.

==== SFU ====
Microsfot's Service For Unix.

----

=== Others ===

==== LiveCD for Intel ====
Current version is 0.9.4.2

Find the instructions to install and the CD itself [http://livecd.gnustep.org/ here]

==== Linksys NSLU2 ====
* First thing need to happen is to gnerate a gcc cross compiler with objc enabled.
Current nslu2 supported gcc only has c and c++ enabled when building the crosstool-native package.

* check out unslung source using follow command.

cvs -z3 -d:pserver:anonymous@cvs.sourceforge.net:/cvsroot/nslu co unslung

* add in objc as language need to be enabled.
<pre>
perl -pi -e 's!^GCC_LANGUAGES=.*!GCC_LANGUAGES="c,c++,objc"!' toolchain/crosstool/nslu2-cross335.sh
perl -pi -e 's!^GCC_LANGUAGES=.*!GCC_LANGUAGES="c,c++,objc"!' sources/crosstool-native/nslu2-native335.sh
</pre>
** Compile cross-compiler for arm cpu using gcc compiler on debian 3.1 linux.

<pre>
tjyang@debian:~/unslung$ pwd
/home/tjyang/unslung
tjyang@debian:~/unslung$ rm toolchain/crosstool/.configured
tjyang@debian:~/unslung$ rm toolchain/crosstool/.built
tjyang@debian:~/unslung$ unset LD_LIBRARY_PATH
tjyang@debian:~/unslung$make toolchain
</pre>

* A arm gcc with objective-C enabled.
<pre>
/export/home/tjyang/slug/unslung/toolchain/armv5b-softfloat-linux/gcc-3.3.5-glibc-2.2.5/bin/armv5b-softfloat-linux-gcc -v

Reading specs from /export/home/tjyang/slug/unslung/toolchain/armv5b-softfloat-linux/gcc-3.3.5-glibc-2.2.5/lib/gcc-lib/armv5b-softfloat-linux/3.3.5/specs
Configured with: /export/home/tjyang/slug/unslung/toolchain/crosstool/build/armv5b-softfloat-linux/gcc-3.3.5-glibc-2.2.5/gcc-3.3.5/configure --target=armv5b-softfloat-linux --host=i686-host_pc-linux-gnu --prefix=/export/home/tjyang/slug/unslung/toolchain/armv5b-softfloat-linux/gcc-3.3.5-glibc-2.2.5 --with-float=soft --with-cpu=xscale --enable-cxx-flags=-mcpu=xscale --with-headers=/export/home/tjyang/slug/unslung/toolchain/armv5b-softfloat-linux/gcc-3.3.5-glibc-2.2.5/armv5b-softfloat-linux/include --with-local-prefix=/export/home/tjyang/slug/unslung/toolchain/armv5b-softfloat-linux/gcc-3.3.5-glibc-2.2.5/armv5b-softfloat-linux --disable-nls --enable-threads=posix --enable-symvers=gnu --enable-__cxa_atexit --enable-languages=c,c++,objc --enable-shared --enable-c99 --enable-long-long
Thread model: posix
gcc version 3.3.5
[tjyang@dual unslung]$
</pre>
** A simple test of objc on host linux machine.
<pre>
[tjyang@dual bin]$ pwd
/home/tjyang/slug/unslung/toolchain/armv5b-softfloat-linux/gcc-3.3.5-glibc-2.2.5/armv5b-softfloat-linux/bin
[tjyang@dual bin]$
[tjyang@dual bin]$ cat helloworld.m
#include <stdio.h>

int main(void)
{
printf("Hello World\n");
}
[tjyang@dual bin]$ ./gcc helloworld.m -lobjc -o helloworld
[tjyang@dual bin]$ file helloworld
hellow: ELF 32-bit MSB executable, ARM, version 1 (ARM), for GNU/Linux 2.4.3, dynamically linked (uses shared libs), not stripped
[tjyang@dual bin]$ uname -a
Linux dual 2.4.21-9.ELsmp #1 SMP Thu Jan 8 17:08:56 EST 2004 i686 i686 i386 GNU/Linux
[tjyang@dual bin]$
</pre>
** Second step is to use this cross-compiler which generate binaries code for armb cpu to compile a native compiler. This complier can only be run on native machine nslu2 not on Intel linux.
<pre>
[tjyang@dual unslung]$ make crosstool-native;make crosstool-native-ipk
[tjyang@dual unslung]$ ls -lrt builds/*.ipk
-rw-rw-r-- 1 tjyang tjyang 5569523 Feb 17 13:32 builds/crosstool-native-bin_0.28-rc37-3_armeb.ipk
-rw-rw-r-- 1 tjyang tjyang 12677163 Feb 17 13:33 builds/crosstool-native-lib_0.28-rc37-3_armeb.ipk
-rw-rw-r-- 1 tjyang tjyang 1722660 Feb 17 13:33 builds/crosstool-native-inc_0.28-rc37-3_armeb.ipk
-rw-rw-r-- 1 tjyang tjyang 7049858 Feb 17 13:34 builds/crosstool-native-arch-bin_0.28-rc37-3_armeb.ipk
-rw-rw-r-- 1 tjyang tjyang 9032668 Feb 17 13:34 builds/crosstool-native-arch-lib_0.28-rc37-3_armeb.ipk
-rw-rw-r-- 1 tjyang tjyang 7483945 Feb 17 13:35 builds/crosstool-native-arch-inc_0.28-rc37-3_armeb.ipk
-rw-rw-r-- 1 tjyang tjyang 1058 Feb 17 13:35 builds/crosstool-native_0.28-rc37-3_armeb.ipk

[tjyang@dual unslung]$ cp /export/home/tjyang/slug/unslung/builds/*.ipk /disk76/nslu2/tmp/
[tjyang@dual unslung]$

login into your nslu2, cd to where the ipk packages are.
run following commands.
bash-2.05b# for i in *.ipk
> do
> ipkg -force-overwrite install $i
> done
Upgrading crosstool-native-arch-bin on root from 0.28-rc37-3 to 0.28-rc37-5...
Configuring crosstool-native-arch-bin
Upgrading crosstool-native-arch-inc on root from 0.28-rc37-3 to 0.28-rc37-5...
Configuring crosstool-native-arch-inc
Upgrading crosstool-native-arch-lib on root from 0.28-rc37-3 to 0.28-rc37-5...
Configuring crosstool-native-arch-lib
Upgrading crosstool-native-bin on root from 0.28-rc37-3 to 0.28-rc37-5...
Configuring crosstool-native-bin
Upgrading crosstool-native-inc on root from 0.28-rc37-3 to 0.28-rc37-5...
Configuring crosstool-native-inc
Upgrading crosstool-native-lib on root from 0.28-rc37-3 to 0.28-rc37-5...
Configuring crosstool-native-lib
Upgrading crosstool-native on root from 0.28-rc37-3 to 0.28-rc37-5...
Configuring crosstool-native
bash-2.05b# date
Sat Feb 19 01:04:07 CST 2005
bash-2.05b#

</pre>
** try to compile helloworld.m objective-C file and run the helloworld binary on nslu2.
<pre>

bash-2.05b# gcc helloworld.m -lobjc -o helloworld
bash-2.05b# file helloworld
helloworld: ELF 32-bit MSB executable, ARM, version 1 (ARM), for GNU/Linux 2.4.3, dynamically linked (uses shared libs), not stripped
bash-2.05b# ./helloworld
./helloworld: error while loading shared libraries: libobjc.so.1: cannot open shared object file: No such file or directory
bash-2.05b#

libobjc.so.1 is in /opt/armeb/armv5b-softfloat-linux/lib, this path need to be in LD_LIBRARY_PATH.

bash-2.05b# ./helloworld
Hello World
bash-2.05b# uname -a
Linux LKG7BFA96 2.4.22-xfs #1 Sat Jan 1 21:34:54 HST 2005 armv5b unknown unknown GNU/Linux
bash-2.05b# date
Thu Feb 17 11:35:19 CST 2005
bash-2.05b# cat compile.sh
/opt/armeb/armv5b-softfloat-linux/bin/gcc helloworld.m -o helloworld -lobjc
bash-2.05b# cat /etc/profile
PATH=/opt/bin:/share/hdd/data/public/nslu2/tjyang/unslung/staging/bin:${PATH}
TERM=xterm
export LD_LIBRARY_PATH=/opt/lib:/lib:/opt/armeb/armv5b-softfloat-linux/lib
export PATH TERM
bash-2.05b#

</pre>

* Using Objective-C enalbed gcc to compile gnustep-core,gnustep-* software.
** more strong testing is needed. please add instructon below if you know how to run objective-c's testsuite in crosstool.

References: http://lists.gnu.org/archive/html/discuss-gnustep/2005-02/msg00124.html

Protocol

2005-11-22T07:43:08Z

Quineska: formatting error

A protocol is a declaration of a group of methods not associated with any particular class.

== Formal Protocol ==

Formal Protocols are used to define the [[Interface]] for a set of methods, but not the implementation or any data members.

This is useful for defining an interface which objects will need to conform to in order to take advantage of some service or other.

Example:

@protocol MyFormalProtocol

-(void) someMethod;
-(id) someOtherMethod;

@end

== Informal Protocol ==

Informal Protocols are constructs that allow you to share a common [[Interface]] between two classes without them having to inherit from any specific object (the notable exception being NSObject).

They are generally made with a category on NSObject that has no implementation associated with it.

Example:

@interface NSObject (MyInformalProtocol)

- (id) someMethod;
- (void) anotherMethod;

@end

== Implementing Protocols ==

Formal and informal protocols take slightly different implementation paths. For formal protocols, you enclose the protocol name in less than/greater than signs e.g.:

@interface MyClass <MyFormalProtocol>

/* Methods in protocol */

-(void) someMethod;
-(id) someOtherMethod;

/* Your methods */

@end

With informal protocols, you place the protocol name in brackets after your class name, both in the interface and implemenation i.e.:

@interface MyClass (MyInformalProtocol)

and

@implementation MyClass (MyInformalProtocol)

Although the interface declaration is optional.

Protocol

2005-11-22T07:41:38Z

Quineska: Added implementation examples

A protocol is a declaration of a group of methods not associated with any particular class.

== Formal Protocol ==

Formal Protocols are used to define the [[Interface]] for a set of methods, but not the implementation or any data members.

This is useful for defining an interface which objects will need to conform to in order to take advantage of some service or other.

Example:

@protocol MyFormalProtocol

-(void) someMethod;
-(id) someOtherMethod;

@end

== Informal Protocol ==

Informal Protocols are constructs that allow you to share a common [[Interface]] between two classes without them having to inherit from any specific object (the notable exception being NSObject).

They are generally made with a category on NSObject that has no implementation associated with it.

Example:

@interface NSObject (MyInformalProtocol)

- (id) someMethod;
- (void) anotherMethod;

@end

== Implementing Protocols ==

Formal and informal protocols take slightly different implementation paths. For formal protocols, you enclose the protocol name in less than/greater than signs e.g.:

@interface MyClass <MyFormalProtocol>

/* Methods in protocol */
-(void) someMethod;
-(id) someOtherMethod;

/* Your methods */

@end

With informal protocols, you place the protocol name in brackets after your class name, both in the interface and implemenation i.e.:

@interface MyClass (MyInformalProtocol)

and

@implementation MyClass(MyInformalProtocol)

Although the interface declaration is optional.

Archiving

2005-11-22T06:40:39Z

Quineska: Added page with NSCoding details

== Allowing objects to be archived ==

To permit an object be archived (also known as serialised) it's class needs to implement the NSCoding protocol. This protocol exposes two methods: -encoderWithCoder and -initWithCoder:. By implementing these methods, your object can be serialised/deserialised as well as sent over GNUstep's Distributed objects mechanism.

See the reference manual for more details.

Foundation

2005-11-22T06:35:33Z

Quineska: Added gnustep-base reference

The GNUstep base library (aka gnustep-base) contains a powerful set of non-graphical [[Objective-C]] classes that can readily be used in your programs. At present there are approximately 70 different classes available, including classes to handle [[NSStrng|strings]] and [[NSArray|arrays]], [[NSDate|dates]] and times, [[NSConnection|distributed objects]], URLs and file systems (to name but a few).

Features:

* [[Strings]]
* [[Collections]] (arrays, sets, dictionaries) and enumerators
* [[File management]]
* [[Archiving|object archiving]]
* advanced calendar [[Date|date]] manipulation
* [[Distributed Objects]] and inter-process communication
* [[URL]] handling
* [[Notifications]] (and distributed notifications)
* easy [[Threading|multi-threading]]
* [[Timer]]s
* [[Lock]]s
* [[Exception handling]]

== Classes ==

[[NSArray]]

[[Category:Frameworks]]

NSString

2005-11-22T06:34:58Z

Quineska:

Strings in GNUstep use the NSString class in gnustep-base. See the reference manual for gnustep-base for more details about NSString.

== Constant Strings ==

As you can create static instances of char* plain C, you can create strings in GNUstep that automatically flatten out to be static instances of NSString. This is done by preceding the quoted string by an "at" symbol ('@'). For example:

NSString * myString = @"This is an example of a string.";
NSLog(myString);

myString is now an NSString object, and can have methods called on it like any other string.

== Getting a C String ==

You can convert an NSString object to a plain C string using the cString method. For example:

NSString* newString = @"This is a test string.";
char* theString = [newString cString];

NSString

2005-11-22T06:31:48Z

Quineska: Added some details to encourage additions

Strings in GNUstep use the NSString class in gnustep-base. See the reference manual for gnustep-base for more details about NSString.

== Constant Strings ==

As in plain C, you can create strings in GNUstep that automatically flatten out to be static instances of NSString. This is done by preceding the quoted string by an "at" symbol ('@'). For example:

NSString * myString = @"This is an example of a string.";
NSLog(myString);

Document based applications

2005-11-22T06:27:44Z

Quineska: Filled out page a bit more with some better details

Document based applications are those that are primarily concerned with user documents, allowing multiple (context-sensitive) document windows and a consistent mechanism for file loading and saving. GNUstep provides a model and associated services, for the rapid development of applications following this paradigm.

Document based applications in GNUstep use NSDocument and NSDocumentController to support and coordinate this behaviour. Below are some articles describing how you can add this functionality to your program, and the role these classes in play in gnustep-gui.

[[NSDocument]]

[[Creating document based applications]]

[[Category:Development]]

Talk:Window Maker

2005-11-22T06:21:19Z

Quineska:

I was going to add:

"This said, questions specifically regarding Window Maker should be directed towards the developers of Window Maker (GNUstep and Window Maker collaborate, but they are separate projects). "

so we don't keep getting Window Maker specific questions. What do people think?

Class variable

2005-11-22T03:33:13Z

Quineska:

The Objective-C dialect which is implemented by the GNU Compiler Collection (gcc) does not explicitly support the concept, widely used in some other object-oriented languages, of class variables.

Class variables are shared values or properties of a specific class. This is useful when encapsulating more complex class and instance behaviour which requires the class to keep track, say of numbers of instances created or other more complex behaviours.

A way of implementing class variables is to declare static variables in the class's [[Implementation]] section, and define class accessor methods if the values need to be changed externally. Note that these statics are not true class variables and will not be inherited by subclasses, and will not be visible outside of the source file's scope.

One can make use of the +initialize method to have class variables initialised when their class is loaded into the runtime.

Compare with the concept of an [[Instance variable]].

Objective-C

2005-09-22T02:59:40Z

Quineska: Linked language to use in GNUstep

Objective-C consists of a set of object-oriented extensions to the C language, featuring things like dynamic binding and a powerful runtime system. That makes Objective-C a superset of C. It is the main programming language used to program with GNUstep.

Objective-C was created by [http://virtualschool.edu/cox/ Brad Cox].

Some resources:
# [http://www.objc.info Objective-C portal]
# Apple Site: [http://developer.apple.com/documentation/Cocoa/Conceptual/ObjectiveC/ The Objective-C Programming Language]
# [http://www.toodarkpark.org/computers/objc/ Object-Oriented Programming and the Objective-C Language]
# [http://www.faqs.org/faqs/computer-lang/Objective-C/faq/ Objective-C FAQ]

Property Lists

2005-09-18T08:50:15Z

Quineska: Spelling errors, grammatical errors, removed TODO's

NOTE: this document is still a work in progress. No responsibility is accepted for any problems arising from inaccuracies.

== Introduction ==

Property lists are used throughout GNUstep to store defaults, program settings, application meta information, and so on. MacOS X has begun to use XML based property lists, but GNUstep uses the classic property list format. Support in GNUstep for XML property lists is still limited on some platforms (namely Windows); this situation should improve in the future as libxml platform build issues are resolved within GNUstep.

A property list is a logical tree of arrays, dictionaries, strings and numbers. The arrays and dictionaries may contain other arrays and dictionaries as data elements, and structures may become quite rich and expressive when representing complex data relationships.

== Dictionary ==

A dictionary is a list of key-value pairs, where each item in the list has a name associated with it (key) and another type (value), which could be another dictionary, an array or often a string. It programmatically corresponds to NSDictionary/NSMutableDictionary. They take the following syntax:

{
KeyName1 = Value1;
AnotherKeyName = "Value2";
Something = ( "ArrayItem1", "ArrayItem2", "ArrayItem3" );
Key4 = 0.10;
KeyFive = { Dictionary2Key1 = "Something"; AnotherKey = "Somethingelse"; };
}

As can be seen, each key-value pair is separated by a semi-colon. Within the pair, the key is seperated from the value with an "equals" (=) sign. The key name is arbitrary, and not put in inverted commas (""). Shown above are: an unknown type (could be some sort of string - TODO), a string, an array, a number and another dictionary (respectively).

== Array ==

An array is a list of values, each of the same type (often arrays or dictionaries). Programmatically, it uses NSArray/NSMutableArray. It takes a syntax similar to the following:

( Value1, Value2, Value3, Value4 ) 
or 
(
Value1,
Value2,
Value3,
Value4
)

Each value is seperated by commas. By the technical definition of an array, each value is of the same "type".

== Programming ==

GNUstep permits such property list files (normally having a .plist extension) to be loaded and subsequently used in your applications or tools. FoundationKit - in GNUstep's case gnustep-base - classes NSDictionary and NSArray are used as representations of the property list data structures. Check the base API documentation for more information on working with these types programmatically.

NSString can be used to turn property lists in string form (either read from a file or constructed programmatically) into an equivalent data structure in memory. Again, see the API documentation for NSString (particularly the -propertyList method).

== Other tips ==

* Property lists are much like C programming, where newlines and spaces and tabs are not so important to parsing, but syntax elements like braces, semilcolons and operators are.
* Some examples of property lists may include:
** ~/GNUstep/System/Defaults/.GNUstepDefaults (this is your defaults file for all installed GNUstep software; be careful when editing this file manually)

[[Category:Development]]

NSView

2005-08-31T22:10:09Z

Quineska: Fixed link

NSView is an [[AppKit]] class. It's role as a superclass is to provide most of the core functionality and services that specific GUI classes (such as NSButton or NSMenuView) use to display/render and handle events.

== Code chunks ==

=== Dragging objects ===

''Note: following code can be somehow optimised by adding small 0.01s delay or something like that. If someone knows how to, please write it here.''

Implement the '''mouseDown:''' method:

- (void)mouseDown:(NSEvent *)event
{
NSPoint oldPoint;
NSEvent *presentEvent;
NSEventType eventType = [event type];
unsigned int eventMask = NSLeftMouseDownMask | NSLeftMouseUpMask
| NSLeftMouseDraggedMask;
NSPoint point;
float dx,dy;
NSPoint location;

point = [self convertPoint:[event locationInWindow] fromView:nil];

oldPoint = point;

do
{
while (event && eventType != NSLeftMouseUp)
{
presentEvent = event;
event = [NSApp nextEventMatchingMask: eventMask
untilDate: [NSDate distantPast]
inMode: NSEventTrackingRunLoopMode
dequeue: YES];
eventType = [event type];
}

point = [self convertPoint: [presentEvent locationInWindow]
fromView: nil];

dx = point.x - oldPoint.x;
dy = point.y - oldPoint.y;

[self scrollRectToVisible:frame];

Add code here:

//
// here move the dragged thing by: dx, dy
// ....

Then finish the loop:

[self setNeedsDisplay:YES];

oldPoint = point;

if (eventType == NSLeftMouseUp)
{
break;
}

event = [NSApp nextEventMatchingMask: eventMask
untilDate: nil
inMode: NSEventTrackingRunLoopMode
dequeue: YES];
eventType = [event type];

} while (eventType != NSLeftMouseUp);

[self setNeedsDisplay:YES];
}

NSView

2005-08-31T22:07:14Z

Quineska:

NSView is an [AppKit] class. It's role as a superclass is to provide most of the core functionality and services that specific GUI classes (such as NSButton or NSMenuView) use to display/render and handle events.

== Code chunks ==

=== Dragging objects ===

''Note: following code can be somehow optimised by adding small 0.01s delay or something like that. If someone knows how to, please write it here.''

Implement the '''mouseDown:''' method:

- (void)mouseDown:(NSEvent *)event
{
NSPoint oldPoint;
NSEvent *presentEvent;
NSEventType eventType = [event type];
unsigned int eventMask = NSLeftMouseDownMask | NSLeftMouseUpMask
| NSLeftMouseDraggedMask;
NSPoint point;
float dx,dy;
NSPoint location;

point = [self convertPoint:[event locationInWindow] fromView:nil];

oldPoint = point;

do
{
while (event && eventType != NSLeftMouseUp)
{
presentEvent = event;
event = [NSApp nextEventMatchingMask: eventMask
untilDate: [NSDate distantPast]
inMode: NSEventTrackingRunLoopMode
dequeue: YES];
eventType = [event type];
}

point = [self convertPoint: [presentEvent locationInWindow]
fromView: nil];

dx = point.x - oldPoint.x;
dy = point.y - oldPoint.y;

[self scrollRectToVisible:frame];

Add code here:

//
// here move the dragged thing by: dx, dy
// ....

Then finish the loop:

[self setNeedsDisplay:YES];

oldPoint = point;

if (eventType == NSLeftMouseUp)
{
break;
}

event = [NSApp nextEventMatchingMask: eventMask
untilDate: nil
inMode: NSEventTrackingRunLoopMode
dequeue: YES];
eventType = [event type];

} while (eventType != NSLeftMouseUp);

[self setNeedsDisplay:YES];
}

Talk:Main Page

2005-08-21T02:30:23Z

Quineska: DESPAM

Can example be provided about "production environment in serveral organization" ? this will clear the doubt of people on GNUstep stability.

added ([[User:Stefan Urbanek|Stefan Urbanek]] 10:08, 17 Feb 2005 (CET))

Thank you ([[User:TJ Yang ]])

Internationalisation in the Users section is probably misnamed and misspelled for this site.

For the user their issue is normally Localisation, but even this isn't necessarily clear. I would argue for terminology like "Configuring language, script and input methods" or even something as formal as "National language configuration".

Internationalisation is a word most often used to describe the process of modifying ''code'' to ''support'' varied text encodings, number formats, currencies and so on and is a developer topic. Localisation is a word used most consistently for ''translation or conversion'' of an application interface and documentation into ''specific'' human languages, date and number formats etc and is probably a developer or volunteer topic.

Even though my personally-preferred spelling in English is the Commonwealth variant, the most wide-spread spelling for Internationalization and Localization are the American-style 'z' spellings. Let's make it easier for people to find what they are looking for in search engines. When a user is trying to find out how to localise their script input and national language preferences, what terms are they going to search for? The link and page should be somehow connected to that.

([[User:Comrade]])

== A question concerning non-ASCII input in GNUstep applications ==

Hello folks!
I tried to use GNUstep applications for my day-to-day tasks but I couldn't make them accept any text input except ASCII characters. When I switch to Russian, all applications refuse input. Is this the right way they should work now? As I know, there isn't any problems with Russian input in the original OpenStep environment. I use XKB and ru_RU.KOI8-R locale. Maybe it's necessary to use ru_RU.UTF8 or you know any other workarounds? All non-GNUstep applications work perfectly.

likely the important thing is to set the GNUSTEP_STRING_ENCODING environment variable to NSKOI8RStringEncoding. There is an [[http://www.gnustep.org/resources/documentation/User/Gui/LanguageSetup.html Asian language support]] page on the gnustep website, that also contains information that could be useful for other languages.

--[[User:Serge RU|Serge RU]] 04:48, 11 May 2005 (CEST)
Thank you, it works :) I also had to make some font assignments not covered in "Asian language support" document (Preferences.app let me find out about them and fix menu font, etc.), but the direction was right.

Creating document based applications

2005-07-29T02:53:39Z

Quineska: /* Document Interface File(s) */ - Added better subclassing information/Fixed typo

Note: First version; subject to further revisions and changes.
--[[User:Quineska|ChrisArmstrong]] 07:09, 7 Jul 2005 (CEST)

== Introduction ==

OpenStep can provide your application a document-based model. It helps to simplify the process of creating such applications. GNUstep implements this as well; this document aims to provide an overview of what is required in the creation and design of such an application.

It is assumed you are familiar with GNUstep, and have some understanding as how to create Gorm's interface files (often referred to as nib's), as well as some understanding of how they work.

Importantly, such applications have certain components that are required, and should be considered as part of their design. When programming, classes that will be used as part of the AppKit are:

==== NSDocument ====

This class is central to the OpenStep document based model. These application's declare a new instance of a subclass of NSDocument for each “document” that is opened. You will subclass NSDocument to implement this.

Each instance of your NSDocument subclass may have one or more windows associated with it. These are used as an interface for loading and saving a representation of your document type. Each window will have an “NSWindowController” instance associated with it, where NSDocument maintains a list of these.

==== NSDocumentController ====

This class acts a controller. It maintains a list of documents (instances of your NSDocument subclass) and is responsible for loading and instantiating new documents. It is usually not necessary to implement a subclass of this, but often it may be useful to implement special functionality (especially related to opening and creating documents at an application level).

==== NSWindowController ====

As mentioned above, NSWindowController instances are individually associated with one NSWindow instance, in such a way that a document maintains a list of window controllers that are reponsible for rendering the views associated with a document.

You will most likely not have to subclass NSWindowController. Instead, you associate a nib file (the Gorm output) with the subclass of NSDocument, and NSDocumentController will load this nib file for each document that is created or loaded.

For example, a text based application that is used for the editing of plain text files, may subclass NSDocument with a TextDocument class. Each instance of this class would have an NSWindowController instance associated with it, which in turn manages a window instance that is instantiated from a nib file. The NSDocumentController instance, as managed and instantiated by GNUstep, would be responsible for loading and saving documents in your application. It even prompts the user to save their documents when they try to quit the application.

== File Components ==

In building your application you will need to create a number of special files. From scratch, the following should be a rough guide to getting it working. These include the Makefile, your application's property list and the interface files.

=== The Makefile ===

For this type of application, no special makefile is needed: it just has to be a normal application. Project Builder should be able to spit out the required makefile and Gorm files that are needed for a generic application. I believe it is also capable of providing support for document-based applications. Otherwise use the following as a template:

'''GNUmakefile'''

include $(GNUSTEP_MAKEFILES)/common.make 
APP_NAME = DocumentApp 
DocumentApp_OBJC_FILES = 
MyDocument.m 
main.m 
DocumentApp_RESOURCES = \ 
Resources/Info-gnustep.plist \ 
Resources/DocumentApp.gorm \ 
Resources/MyDocument.gorm 
-include GNUmakefile.preamble 
include $(GNUSTEP_MAKEFILES)/application.make 
-include GNUmakefile.postamble 

For more information as to customising this file, as well as setting up compiler options for third party libraries and includes, see the GNUstep makefile manual.

===The application dictionary===

For those that have edited this file in their project before, it is a dictionary with various values entered. For our purposes, we need an array within the main dictionary, called "NSTypes". This is a array of unnamed dictionaries, with one dictionary for each type.

I have provided an example for this file below. ProjectBuilder creates one as well. Please note that "TextEdit" does exist as an example application from NEXT I think, and again on MacOS X but I have constructed a much simpler version, used only for plain text files.

Taking a look at the single dictionary entry in the NSTypes array, the following key-value pairs are needed:
* '''NSDocumentClass:''' This is (string) the subclass name you use in your code, the "objective-c name" of your document subclass. This is used by NSDocumentController's default implementation to create instances of your document type.
* '''NSName:''' The generic file type (string). This is completely arbitrary, and can be anything you like. For the purpose of conventions, it may be more appropriate not to use the "NS" or "GS" prefix (the latter of which I not sure), and instead use either your own, or no prefix at all.
* '''NSHumanReadableName:''' The human readable name of your document type (string)? TODO: explain where this is used.
* '''NSUnixExtensions:''' An array of strings, each containing a file extension connected to this document type on "unix" platforms. TODO: explain how "unix" is interpreted by GNUstep.
* '''NSDOSExtensions:''' An array of strings, each containing a file extenstion connected to this document type on "DOS" platforms (could be loosely interpreted as any MS platforms GNUstep runs on, i.e. Windows 2000/XP).
* '''NSRole:''' A string, either "Viewer" or "Editor", depending on how your document operates on this file type.
* '''NSIcon:''' A icon name associated with this document type. TODO: Investigate how this works.

'''Info-gnustep.plist'''
{
ApplicationDescription = "A simple text editor for GNUstep.";
ApplicationName = TextEdit;
ApplicationRelease = 0.10;
Authors = ( "Christopher Armstrong" );
Copyright = "Copyright (C) 2005 Christopher Armstrong";
CopyrightDescription = "Released under GPL.";
FullVersionID = 0.10;
NSExecutable = TextEdit;
NSMainNibFile = TextEdit.gorm;
NSPrincipalClass = NSApplication;
NSRole = Application;
NSTypes = (
{
NSDocumentClass = "TextDocument";
NSName = "GSTextDocumentType";
NSHumanReadableName = "Text Document";
NSUnixExtensions = ( "txt", "" );
NSDOSExtensions = ( "txt" );
NSRole = Editor;
}
);
}

For more information on property list files, consult [[Property Lists]].

=== Interface files ===

Two interface files are needed: one for your main application, and another that will be instantiated with each instance of your document subclass. These both should be listed as resources in your makefile, (as shown the GNUmakefile example above). It may be helpful to name the document nib file after your class.

==== Application Interface File ====

The application one should just be a menu (though it could be more if necessary). When constructing it, take the following into account:

* Use a standard Gorm template for an Application.
* Delete the window instance in the "Objects" pane (unless you need a main window, which is beyond the scope of this document).
* Set NSOwner's class to "NSDocumentController". This is the custom class option of NSOwner in the property inspector. This ensures that the openDocument:, newDocument: messages, as sent to NSFirst, get picked up by NSDocumentController. Do not instantiate it (I believe you can't anyway).
* If you intend to subclass NSDocumentController, subclass it in the Classes pane. To make sure that this class is instantiated and used, make sure you instantiate it in Gorm or in your main.m file, and set NSOwner to be your subclass.
* Drag a Document menu from the palette onto your main menu. This already has the proper outlet and action linkage for each relevant message to be directed to NSFirst. Generic messages (such as openDocument:, not associated with any document instance) are forwarded to the shared instance of NSDocumentController (see it's reference documentation). When a document is active, more specific messages (such as close: or saveDocument:) are forwarded to the relevant document instance of your NSDocument subclass.
* Add any appropriate menus such as "Info" and "Format" which may be relevant to your application.

==== Document Interface File(s) ====

The document interface file is a window containing the view(s) required for the implementation of one instance of your document type. For example, in the case of a TextDocument type, a window instance with a NSTextView drawn on it is used for each document window. This interface file is instantiated every time a person creates a new document (the newDocument: message is sent to NSDocumentController) or opens an existing document (openDocument:).

You will need to:
* '''Subclass NSDocument''' with your document type in Gorm. This is done in a couple of ways, see [[Gorm_Manual#Custom_classes|custom classes]]. It is up to you whether or not you let Gorm generate the class files, but make sure you add the appropriate outlets to your class in the source files (otherwise, I think your your program may segfault).
* '''Set NSOwner:''' Set your subclass as NSOwner's Custom class using the Property Inspector. ''DO NOT INSTANTIATE IT.''

Another thing that you may want to consider is custom outlets. If you place certain views or controls on your window (including the window itself), you may want to refer to them directly in your code, e.g. the NSTextView in our TextEdit example is accessed directly, so that we can save it's contents to a file. To enable this, we add outlets to our class (see [[Gorm_Manual#Custom_classes|custom classes]]). We then connect NSOwner to the appropriate controls/views, and select the outlets in the Connections Property Inspector (see [[Gorm_Manual#Editing_the_interface|editing the interface]]).

== Code ==

Various things need to be done at a code level, to ensure that your NSDocument subclass is properly instantiated. This section aims to tell you what is necessary.

=== NSDocument subclass ===

When creating your subclass, you may have chosen to have Gorm create the class files. If not, you should create two files for your subclass: a header (.h) file and an implementation file (.m). The header file should take the following layout (we're using the TextEdit example again):

#ifndef TEXTDOCUMENT_H
#define TEXTDOCUMENT_H 
#include <AppKit/AppKit.h> 
@class NSDocument; 
/* The document type string, as specified in the property list [[#The_application_dictionary|NSTypes array]] */ 
NSString * GSTextDocumentType = "GSTextDocumentType";
@interface TextDocument : NSDocument
{
@protected
/* Outlets we added in our Gorm nib file */
id * textView;
}
/* Basic methods used for loading and saving document data (respectively). */
- (BOOL) loadDataRepresentation:(NSData*)representation ofType:(NSString*)type;
- (NSData*) dataRepresentationOfType: (NSString*)type; 
/* Information and events handling of GUI related changes */
- (NSString*) windowNibName;
- (void) windowControllerDidLoadNib:(NSWindowController*)windowController; 
@end 

Firstly, take note that we inherit from NSDocument. As a result, we need to override some methods for a basic (but working) implementation.

==== loadDataRepresentation:ofType: and dataRepresentationOfType: ====

The methods, loadDataRepresent:ofType: and dataRepresentationOfType: are used by NSDocumentController to load and save our files. The first method is called when the user trys to open a document (NSDocumentController gets the file name and copies it's data using an open panel). The method is passed the raw data in this file, as well as a string representing its type. It is important to note that this type string is the same one used in your property list. It is used by NSDocumentController to tell you what type it thinks you should open the data with. If this is not possible, or if there is an error trying to parse the data, your method returns FALSE/NO. Otherwise, you should store a local, meaningful representation of the data, which you can insert into your document window a little later (and return TRUE/YES).

For example, in terms of the TextEdit example:
- (BOOL) loadDataRepresentation:(NSData*) representation ofType:(NSString*)type
{
/*Check type information */
if ([representation equalTo:GSTextDocumentType]==NO)
return NO;
/* Clean out our old representation if it still exists */
if (fileContents) RELEASE(fileContents); 
/* Allocate room for the new data, and try to initialise a string with it. */
self->fileContents = [NSString alloc];
fileContents = [fileContents initWithBytes: [representation bytes]
length: [representation length]
encoding: NSASCIIStringEncoding]; 
/* If this can't be done, return NO */
if (!fileContents)
return NO; 
/* Otherwise, set our TextView to the string data. */
[self->textView setString: fileContents];
return YES;
}

If this is not sufficient, or if your program can open the data in a more efficient manner, it may be worth looking into overriding -initWithContentsOfFile:ofType: and -initWithContentsOfURL:ofType:. Again, see the GUI manual for more details.

dataRepresentationOfType: is used to save the data. Your method is expected to return an instance of NSData that contains what should be saved to a file, for the type specified. Again, the ''type'' variable should be checked to ensure that you can write data of that type. Return nil if the file cannot be saved as that type.

For example:

- (NSData*) dataRepresentationOfType:(NSString*)type
{
if ([type equalTo:GSTextDocumentType]==NO)
return nil; 
NSData stringData = [[textView string] dataUsingEncoding:NSASCIIStringEncoding];
return stringData;
}

If a more sophisticated save implementation is needed, consult the documentation for information on the writeTo* methods.

==== windowNibName ====

This method must be overriden to return the a string of the name of your nib file (without the file extension). More complex implementations will use other methods to load the interface files. TODO: information on what methods need to be overriden.

==== windowControllerDidLoadNib: ====

Use this method to add code that should be run as soon as ''windowController'' has been initialised. Your document may have many window controllers; each window controller taking possession of one window.

In the TextEdit example, this method is used to copy the ''fileContents'' variable to the text view. It otherwise initialises the document window.

Also note that you can override windowControllerWillLoadNib: to perform pre-interface loading initialisation.

==== makeWindowControllers ====

This is an optional method to override, which must be used if you have multiple window controllers per document. It is responsible for creating each window controller from it's interface file and then adding it to the document. Use the addWindowController: method.

==== Other considerations ====

* You need a way to notify NSDocument that your document has changed, so that NSDocumentController can enable the menu item to allow saving. This is done by a call to the updateChangeCount: method. For example, the TextDocument class adds itself as a delegate to the textView, for any notification of changes. It then calls updateChangeCount: in the delegate's method.

* You may also wish to add a close: method (not the close method already in NSDocument, see below) to respond to the menu item permitting your document to close. This could perform cleanup operations before a call to [self close] is made e.g.

- (void) close:(id)sender /* Note this is not the method found in NSDocument (they differ by a parameter) */
{
[self close];
}

=== NSDocumentController ===

This class can optionally be subclassed, to implement some specific functionality. For example, programs handling multiple document types may override newDocument: to create a window so that the user can select which document type to create.

You should use separate implementation files and add the .m file to GNUmakefile.

=== NSWindowController ===

This class can also be optionally subclassed, to implement functionality specific to a window controller for a document type. You may need to override makeWindowControllers: in the NSDocument subclass in order to make sure your specific window controller is instantiated.

You should use separate implemenation files and add the .m file to GNUmakefile.

== Optional Additions ==

=== Custom NSDocumentController and NSWindowController implementations ===

See [[#NSWindowController|NSWindowController]] and [[#NSDocumentController|NSDocumentController]].

----

[[Category:Development]]

Creating document based applications

2005-07-29T02:50:12Z

Quineska: /* Code */

Note: First version; subject to further revisions and changes.
--[[User:Quineska|ChrisArmstrong]] 07:09, 7 Jul 2005 (CEST)

== Introduction ==

OpenStep can provide your application a document-based model. It helps to simplify the process of creating such applications. GNUstep implements this as well; this document aims to provide an overview of what is required in the creation and design of such an application.

It is assumed you are familiar with GNUstep, and have some understanding as how to create Gorm's interface files (often referred to as nib's), as well as some understanding of how they work.

Importantly, such applications have certain components that are required, and should be considered as part of their design. When programming, classes that will be used as part of the AppKit are:

==== NSDocument ====

This class is central to the OpenStep document based model. These application's declare a new instance of a subclass of NSDocument for each “document” that is opened. You will subclass NSDocument to implement this.

Each instance of your NSDocument subclass may have one or more windows associated with it. These are used as an interface for loading and saving a representation of your document type. Each window will have an “NSWindowController” instance associated with it, where NSDocument maintains a list of these.

==== NSDocumentController ====

This class acts a controller. It maintains a list of documents (instances of your NSDocument subclass) and is responsible for loading and instantiating new documents. It is usually not necessary to implement a subclass of this, but often it may be useful to implement special functionality (especially related to opening and creating documents at an application level).

==== NSWindowController ====

As mentioned above, NSWindowController instances are individually associated with one NSWindow instance, in such a way that a document maintains a list of window controllers that are reponsible for rendering the views associated with a document.

You will most likely not have to subclass NSWindowController. Instead, you associate a nib file (the Gorm output) with the subclass of NSDocument, and NSDocumentController will load this nib file for each document that is created or loaded.

For example, a text based application that is used for the editing of plain text files, may subclass NSDocument with a TextDocument class. Each instance of this class would have an NSWindowController instance associated with it, which in turn manages a window instance that is instantiated from a nib file. The NSDocumentController instance, as managed and instantiated by GNUstep, would be responsible for loading and saving documents in your application. It even prompts the user to save their documents when they try to quit the application.

== File Components ==

In building your application you will need to create a number of special files. From scratch, the following should be a rough guide to getting it working. These include the Makefile, your application's property list and the interface files.

=== The Makefile ===

For this type of application, no special makefile is needed: it just has to be a normal application. Project Builder should be able to spit out the required makefile and Gorm files that are needed for a generic application. I believe it is also capable of providing support for document-based applications. Otherwise use the following as a template:

'''GNUmakefile'''

include $(GNUSTEP_MAKEFILES)/common.make 
APP_NAME = DocumentApp 
DocumentApp_OBJC_FILES = 
MyDocument.m 
main.m 
DocumentApp_RESOURCES = \ 
Resources/Info-gnustep.plist \ 
Resources/DocumentApp.gorm \ 
Resources/MyDocument.gorm 
-include GNUmakefile.preamble 
include $(GNUSTEP_MAKEFILES)/application.make 
-include GNUmakefile.postamble 

For more information as to customising this file, as well as setting up compiler options for third party libraries and includes, see the GNUstep makefile manual.

===The application dictionary===

For those that have edited this file in their project before, it is a dictionary with various values entered. For our purposes, we need an array within the main dictionary, called "NSTypes". This is a array of unnamed dictionaries, with one dictionary for each type.

I have provided an example for this file below. ProjectBuilder creates one as well. Please note that "TextEdit" does exist as an example application from NEXT I think, and again on MacOS X but I have constructed a much simpler version, used only for plain text files.

Taking a look at the single dictionary entry in the NSTypes array, the following key-value pairs are needed:
* '''NSDocumentClass:''' This is (string) the subclass name you use in your code, the "objective-c name" of your document subclass. This is used by NSDocumentController's default implementation to create instances of your document type.
* '''NSName:''' The generic file type (string). This is completely arbitrary, and can be anything you like. For the purpose of conventions, it may be more appropriate not to use the "NS" or "GS" prefix (the latter of which I not sure), and instead use either your own, or no prefix at all.
* '''NSHumanReadableName:''' The human readable name of your document type (string)? TODO: explain where this is used.
* '''NSUnixExtensions:''' An array of strings, each containing a file extension connected to this document type on "unix" platforms. TODO: explain how "unix" is interpreted by GNUstep.
* '''NSDOSExtensions:''' An array of strings, each containing a file extenstion connected to this document type on "DOS" platforms (could be loosely interpreted as any MS platforms GNUstep runs on, i.e. Windows 2000/XP).
* '''NSRole:''' A string, either "Viewer" or "Editor", depending on how your document operates on this file type.
* '''NSIcon:''' A icon name associated with this document type. TODO: Investigate how this works.

'''Info-gnustep.plist'''
{
ApplicationDescription = "A simple text editor for GNUstep.";
ApplicationName = TextEdit;
ApplicationRelease = 0.10;
Authors = ( "Christopher Armstrong" );
Copyright = "Copyright (C) 2005 Christopher Armstrong";
CopyrightDescription = "Released under GPL.";
FullVersionID = 0.10;
NSExecutable = TextEdit;
NSMainNibFile = TextEdit.gorm;
NSPrincipalClass = NSApplication;
NSRole = Application;
NSTypes = (
{
NSDocumentClass = "TextDocument";
NSName = "GSTextDocumentType";
NSHumanReadableName = "Text Document";
NSUnixExtensions = ( "txt", "" );
NSDOSExtensions = ( "txt" );
NSRole = Editor;
}
);
}

For more information on property list files, consult [[Property Lists]].

=== Interface files ===

Two interface files are needed: one for your main application, and another that will be instantiated with each instance of your document subclass. These both should be listed as resources in your makefile, (as shown the GNUmakefile example above). It may be helpful to name the document nib file after your class.

==== Application Interface File ====

The application one should just be a menu (though it could be more if necessary). When constructing it, take the following into account:

* Use a standard Gorm template for an Application.
* Delete the window instance in the "Objects" pane (unless you need a main window, which is beyond the scope of this document).
* Set NSOwner's class to "NSDocumentController". This is the custom class option of NSOwner in the property inspector. This ensures that the openDocument:, newDocument: messages, as sent to NSFirst, get picked up by NSDocumentController. Do not instantiate it (I believe you can't anyway).
* If you intend to subclass NSDocumentController, subclass it in the Classes pane. To make sure that this class is instantiated and used, make sure you instantiate it in Gorm or in your main.m file, and set NSOwner to be your subclass.
* Drag a Document menu from the palette onto your main menu. This already has the proper outlet and action linkage for each relevant message to be directed to NSFirst. Generic messages (such as openDocument:, not associated with any document instance) are forwarded to the shared instance of NSDocumentController (see it's reference documentation). When a document is active, more specific messages (such as close: or saveDocument:) are forwarded to the relevant document instance of your NSDocument subclass.
* Add any appropriate menus such as "Info" and "Format" which may be relevant to your application.

==== Document Interface File(s) ====

The document interface file is a window containing the view(s) required for the implementation of one instance of your document type. For example, in the case of a TextDocument type, a window instance with a NSTextView drawn on it is used for each document window. This interface file is instantiated every time a person creates a new document (the newDocument: message goes to NSDocumentController) or opens an existing document (openDocument:).

You will need to:
* '''Subclass NSDocument''' with your document type in Gorm. This is done in a couple of ways, see [[Gorm_Manual#Custom_classes|custom classes]].
* '''Set NSOwner:''' Set your subclass as NSOwner's Custom class using the Property Inspector). DO NOT INSTANTIATE IT.

Another thing that you may want to consider is custom outlets. If you place certain views or controls on your window (including the window itself), you may want to refer to them directly in your code, e.g. the NSTextView in our TextEdit example is accessed directly, so that we can save it's contents to a file. To enable this, we add outlets to our class (see [[Gorm_Manual#Custom_classes|custom classes]]). We then connect NSOwner to the appropriate controls/views, and select the outlets in the Connections Property Inspector (see [[Gorm_Manual#Editing_the_interface|editing the interface]]).

== Code ==

Various things need to be done at a code level, to ensure that your NSDocument subclass is properly instantiated. This section aims to tell you what is necessary.

=== NSDocument subclass ===

When creating your subclass, you may have chosen to have Gorm create the class files. If not, you should create two files for your subclass: a header (.h) file and an implementation file (.m). The header file should take the following layout (we're using the TextEdit example again):

#ifndef TEXTDOCUMENT_H
#define TEXTDOCUMENT_H 
#include <AppKit/AppKit.h> 
@class NSDocument; 
/* The document type string, as specified in the property list [[#The_application_dictionary|NSTypes array]] */ 
NSString * GSTextDocumentType = "GSTextDocumentType";
@interface TextDocument : NSDocument
{
@protected
/* Outlets we added in our Gorm nib file */
id * textView;
}
/* Basic methods used for loading and saving document data (respectively). */
- (BOOL) loadDataRepresentation:(NSData*)representation ofType:(NSString*)type;
- (NSData*) dataRepresentationOfType: (NSString*)type; 
/* Information and events handling of GUI related changes */
- (NSString*) windowNibName;
- (void) windowControllerDidLoadNib:(NSWindowController*)windowController; 
@end 

Firstly, take note that we inherit from NSDocument. As a result, we need to override some methods for a basic (but working) implementation.

==== loadDataRepresentation:ofType: and dataRepresentationOfType: ====

The methods, loadDataRepresent:ofType: and dataRepresentationOfType: are used by NSDocumentController to load and save our files. The first method is called when the user trys to open a document (NSDocumentController gets the file name and copies it's data using an open panel). The method is passed the raw data in this file, as well as a string representing its type. It is important to note that this type string is the same one used in your property list. It is used by NSDocumentController to tell you what type it thinks you should open the data with. If this is not possible, or if there is an error trying to parse the data, your method returns FALSE/NO. Otherwise, you should store a local, meaningful representation of the data, which you can insert into your document window a little later (and return TRUE/YES).

For example, in terms of the TextEdit example:
- (BOOL) loadDataRepresentation:(NSData*) representation ofType:(NSString*)type
{
/*Check type information */
if ([representation equalTo:GSTextDocumentType]==NO)
return NO;
/* Clean out our old representation if it still exists */
if (fileContents) RELEASE(fileContents); 
/* Allocate room for the new data, and try to initialise a string with it. */
self->fileContents = [NSString alloc];
fileContents = [fileContents initWithBytes: [representation bytes]
length: [representation length]
encoding: NSASCIIStringEncoding]; 
/* If this can't be done, return NO */
if (!fileContents)
return NO; 
/* Otherwise, set our TextView to the string data. */
[self->textView setString: fileContents];
return YES;
}

If this is not sufficient, or if your program can open the data in a more efficient manner, it may be worth looking into overriding -initWithContentsOfFile:ofType: and -initWithContentsOfURL:ofType:. Again, see the GUI manual for more details.

dataRepresentationOfType: is used to save the data. Your method is expected to return an instance of NSData that contains what should be saved to a file, for the type specified. Again, the ''type'' variable should be checked to ensure that you can write data of that type. Return nil if the file cannot be saved as that type.

For example:

- (NSData*) dataRepresentationOfType:(NSString*)type
{
if ([type equalTo:GSTextDocumentType]==NO)
return nil; 
NSData stringData = [[textView string] dataUsingEncoding:NSASCIIStringEncoding];
return stringData;
}

If a more sophisticated save implementation is needed, consult the documentation for information on the writeTo* methods.

==== windowNibName ====

This method must be overriden to return the a string of the name of your nib file (without the file extension). More complex implementations will use other methods to load the interface files. TODO: information on what methods need to be overriden.

==== windowControllerDidLoadNib: ====

Use this method to add code that should be run as soon as ''windowController'' has been initialised. Your document may have many window controllers; each window controller taking possession of one window.

In the TextEdit example, this method is used to copy the ''fileContents'' variable to the text view. It otherwise initialises the document window.

Also note that you can override windowControllerWillLoadNib: to perform pre-interface loading initialisation.

==== makeWindowControllers ====

This is an optional method to override, which must be used if you have multiple window controllers per document. It is responsible for creating each window controller from it's interface file and then adding it to the document. Use the addWindowController: method.

==== Other considerations ====

* You need a way to notify NSDocument that your document has changed, so that NSDocumentController can enable the menu item to allow saving. This is done by a call to the updateChangeCount: method. For example, the TextDocument class adds itself as a delegate to the textView, for any notification of changes. It then calls updateChangeCount: in the delegate's method.

* You may also wish to add a close: method (not the close method already in NSDocument, see below) to respond to the menu item permitting your document to close. This could perform cleanup operations before a call to [self close] is made e.g.

- (void) close:(id)sender /* Note this is not the method found in NSDocument (they differ by a parameter) */
{
[self close];
}

=== NSDocumentController ===

This class can optionally be subclassed, to implement some specific functionality. For example, programs handling multiple document types may override newDocument: to create a window so that the user can select which document type to create.

You should use separate implementation files and add the .m file to GNUmakefile.

=== NSWindowController ===

This class can also be optionally subclassed, to implement functionality specific to a window controller for a document type. You may need to override makeWindowControllers: in the NSDocument subclass in order to make sure your specific window controller is instantiated.

You should use separate implemenation files and add the .m file to GNUmakefile.

== Optional Additions ==

=== Custom NSDocumentController and NSWindowController implementations ===

See [[#NSWindowController|NSWindowController]] and [[#NSDocumentController|NSDocumentController]].

----

[[Category:Development]]

Application wish list

2005-07-27T03:08:54Z

Quineska: /* Printer.app */

What applications do you want for GNUstep? Add below:
(Please check [All GNUstep Applications] before adding)

Old NeXTSTEP/OPENSTEP apps: http://www.levenez.com/NeXTSTEP/meApps.html

__Frontend for different platform to www.granddictionnaire.com__

-------------------------------

== Keyboard switcher application ==

== Web browser ==

Seems to be a popular request :).

* Could [http://www.mozilla.org/projects/camino/ Camino] (formerly known as Chimera) be the one (after backporting)?
* [http://www.apple.com/safari/ Apple's Safari] web browser uses KHTML and KJS software from the KDE open source project, updated and re-released [http://developer.apple.com/darwin/projects/webcore/index.html here], but needs Objective-C++ support in GCC.
-- Hasan --

* I could port [http://ibn.com/~hdiwan/orchidWeb.html OrchidWeb] to GNUStep. I'd just need enough examples on developing the views from code to {do it.
Apparently, camino is written in Objective-C++, which GCC can't compile (although Apple is supposed to have contibuted the patch). Until gcc can compile mixed obj-c and c++, it can't be ported. There is a thread about this at [http://linuxfr.org/2003/03/10/11647.html] (it's in french).
* This seems very close... Stefan has began porting [http://mac.wms-network.de/gnustep/WebCore/blog/ Webcore to GNUstep]. Still some way to go, but a great breaktrough. This seems to be the most probable answer to the web browser request.

== Project Management app ==

Something like [http://mrproject.codefactory.se/screenshots.php MrProject]. It has to be simple, not overbloated as MS Project.

== Google.app ==

* Complete with ApplicationServices
* WebBrowser integration
* Using proper NS* classes for HTML retrieval
* Ability to select which Google server (www.google.ca, www.google.co.jp)
* Google News, Google Groups, Google Images too.

== DMG.app? ==

* Installer/extractor/viewer for DMG images.
* Create DMG packages
* Useful for OSX source packages

''Note:'' The DMG format is Apple proprietary and undocumented. Basically, DMG support is only available under OSX and its unlikely to change.

== Blender ==

Blender has recently (since October 2002) gone GPL. Consisting of porting the Blender GUI/WM abstract library GHOST, using NSOpenGLContext, or a CoreGraphics implementation one day. Objective-C++ might be needed for implementing GHOST, but probably can be worked around easily enough. There is an OSX port, probably using CoreGraphics.

[http://www.blender.org/ Blender Foundation Homepage]

Most of Blender is written in C++ doesn't seem to use CoreGraphics but Apple's GL.

== CSS/html editor ==

A cool html/css editor - emphasis on the css structural side.

Object oriented properties application to CSS element definitions, and insert those properties into HTML in web pages. Don't worry about WYSIWIG - that's what web browsers are for, displaying web pages. Just make a object-oriented CSS/HTML editor.

Maybe port [http://www.w3.org/People/Berners-Lee/WorldWideWeb.html Nexus] for that?

== OmniGraffle clone ==

(I don't really know what this is, but people have said they want one. Someone please add a description! :)

This is for diagram, UML ....
I 'm thinking to write it. But not *right now*.
It will have probably a Gorm-feel

[http://www.omnigroup.com/applications/omnigraffle/ OmniGraffle] was a clone of Lighthouse Design's Diagram.app, which was a re-working of the NeXT Developer Example Sketch.app, adding rubber-banding / angular connection lines.

== OmniOutliner clone ==

This is a really cool app which can be used for anything. Mostly i think it is used to organise your minds while being creative (some kind of knowledge manager).

The inspiration for this was Jayson Adams' Millennium Software's NoteBook.app, which lives again as the (commercial) program [http://www.aquaminds.com/ NoteTaker].

== A text editor ==

A simple text editor that can read and write plain or rich text, including both simple word processing functionality (nothing too splashy, like frames) and optional programming features (like syntax highlighting -- not just coloring; controllable tabs; tab v. space indentation, multiple language support). Programming features could be provided by a bundle, but it would be good to for the app to be designed with that bundle in mind.

This editor which is to guarantee me world domination includes a split view where the other pane locates and displays the corresponding end-tag/start-tag when programming.

Ink is not that editor. :)

[http://www.softpanorama.org/Editors/index.shtml Softpanorama] seems to give a good overview of editors

''We have to distinguish between a text editor as programming tool (CodeEditor.app) and a text editor as a word processor (WordProcessor.app?). '' They are two different approaches to text editing and text processing.

Source code editing view and associated inspector panels and preferences should be provided as a framework, so the SourceView should be reused in other apps. CodeEditor should be only some default wrapper for that framework.

WordProcessor.app sould be an application that extends NSText system. (With easy-to-use paragraph style editing)

How about interfacing with [http://www.scintilla.org Scintilla]?
-- Hasan --

== A simple DTP application ==

A simple frame-based application for desktop publishing. Something like [http://www.calamus.net/ Calamus] ([http://www.calamus.net/man/index_us.htm here] is the documentation of tools and modules). Nothing fancy, just application that can lay out frames, control text flow, use paragraph styles and master pages.

I'd rather see TeXView.app come back myself.... I think it's far more feasible (doing a decent page layout app is _hard_ just as Donald E. Knuth). Perhaps better still would be to take advantage of LyX's ``GUI-independence'' and provide a GNUstep front-end for it, http://www.lyx.org .

No, nothing like LyX or TeX. I have in mind a ''visual'' page layout editing tool with features as described above (similar to PageMaker). LyX and TeX are a bit different approaches and should be alternatives to Frame based DTP application.

- Stefan

I think a heavy-weight drawing package w/ page layout features would be a better solution here (this is the workflow I'm using on my NeXT Cube now), then it could be tied into an XML-based workflow in a fashion like to Apple's new Keynote, perhaps in a fashion like to Pages-by-Pages. To describe my workflow a bit---I now use Altsys Virtuoso on my NeXT Cube w/ Omega (Unicode-aware TeX variant) for most of my page layout. IME, if a document gets too large to manage w/ Altsys Virtuoso, it might as well go into TeX... Not that I'd mind seeing a replacement for PasteUp.app, I just think that a drawing program is more immediately important / useful.

For simple DTP utility, I'd dearly love to see a re-creation of [http://members.aol.com/willadams/gnustep/apps/type/touchtype.html TouchType.app]

- William

Maybe you should take a look at [http://www.texmacs.org/ TeXmacs]. Looks promising and is in great need of a GNUstep frontend.

- david.

Interesting. I'd seen TeXMacs mentioned on comp.text.tex quite often, but hadn't realized it had gotten as far as it had. Interesting counterpoint to LyX.
- William

One really interesting thing would be to have a fame class which would useful enough so it could be used to put together a simple DTP Application but which would be flexible enough that it could be available to any application - the text control is a standard control for windows managers like MS Windows or Gnome. If there were an equivalent "flowing graphic control", you'd have a powerful building block indeed (note that in MS windows, the text control is actually poor enough that no credible application can built around besides notepad).
Also, for a programming text editor, scintilla is great. One thing to consider is that for DTP/HTML editor, what you would want would be a *superset* of the scintilla interface. It would be great to add all the different features in such a way that you didn't have interfaces duplicating each other's functionalities.

-- JosephSolbrig

== Painting app (photoshop) ==

Bitmap drawing app.

Think Photoshop, not [http://www.gimp.org/ The Gimp].

In fact, forget that. Something new.

Something usable - can do Photoshop, but easy to learn. The Gimp can nearly do photoshop, but who can use it?

It would be great if it consisted of two parts - a very small very useful image viewer/manager (eg gqview) and the actual editor plugin (the big part). So installing image-core would give a very small useful app, then adding image-edit would make it into photoshop.

When opening an image file eg by clicking on it or running image-core thefile.jpg then only the core apps should start, so it starts real quick. If i right-click and choose edit or something .. THEN the other stuff is pulled in.

Or whatever. Just an idea. But makes development path cool. Could also have a vector plugin, or whatever.

Maybe we should wait, when (if?) Gimp gets '[http://gegl.org/ gegl]'ed.
then having a decent photoshop like app would be as simple as writing a gui for the gegl foundation.
+ gives us a nice featureset + plugins!

Maliwan project is aiming to achieve the same goal of GEGL. Right now GEGL isn't even half complete but we can still reimplement it base on GEGL's design. lastlife is waiting for you in irc if you want to discuss the idea. Maliwan is planned to be the heart of the BluTulip which is the actual application.

== Calendar ==

check SKYRIX libs (Opengroupware).
http://www.opengroupware.org/cvsweb/cvsweb.cgi/OpenGroupware.org/SOPE/skyrix-core/NGiCal/

== CVS app ==

Port CVL

== Task management app ==

Chronographer (lobbying by ludovic) + libical
or
~TaskManager (lobbying by Fabien) + libical

Check SKYRIX libs (Opengroupware)

== ICQ ==

and other instant messengers.
check http://freshmeat.net/projects/fireapp/

== DatabaseModeller.app ==

See [[DBModeler]], currently a work in progress.

== Database management ==

A desktop software (Like [http://www.flex.ro/pgaccess/ PgAccess] for example) to manage database. This program could use the GDL2 (Gnustep Database Library). It could be a good exercice and demonstration of this very good library.

== Video conferencing software ==

There's [http://www.gnomemeeting.org/ Gnomemeeting] (excellent piece of software), but I don't like Gnome too much (all those dependencies).

Update: Gnomemeeting 0.9.6 is supposed to work without Gnome libs (limited functionality).

== CronniX - A cron front end ==

http://www.koch-schmidt.de/cronnix/

That won't be easily portable, as different OSs use a different cron setup. Eg. BSD has (and uses) both, /etc/crontab __and__ /var/cron/tabs/<username> ...

== PfaEdit - A font editor ==

(This is now called FontForge)

http://pfaedit.sourceforge.net

Actually, Cenon (see above) is able to do some limited font editing. Not to knock pfaedit, I use it a lot and think it's a way cool program. Wonder if the two could be merged somehow.

== GuileServices / StepTalk Services ==

On NeXTSTEP there was an application (service?) called [TickleServices|http://www.doubleu.com/TickleServices.html] that allowed you to write your own services in the Tcl language. Something along these lines, but using guile/steptalk would be a nice addition to gnustep.

== Printer.app ==

An application/framework for managing printers, printer properties and print queues. (CUPS frontend?) (NOTE: To an extent, GNUstep already has CUPS support, and has number of builtin classes and panels for managing printers and printer settings. They may just need to be extended a little for different uses and environments.)

== DivX/XViD/DVD/VCD Player ==

I see that there was at least an attempt to port mplayer at one point but it seems to be dead. Maybe VLC (http://www.videolan.org/) which does have an OSX version, could be ported.

== Abiword (Word Processor) ==

A port of the Cocoa version of [AbiWord|http://www.abisource.com] would be great, considering a word processor is a pretty vital application, and that Abiword is a pretty good one.

== Spreadsheet ==

A spreadsheet application would be great for GNUstep. A clone of Lotus Improv or Lighthouse Design's Parasheet would be a nice thing for GNUstep to have.

== Pixen (Pixel Art Tool) ==

[Pixen|http://www.opensword.org] is a decent, open source pixel art tool and there aren't alot of free or professional programs like it. There is also a compliment tool by the same guys for mapping called Reptile.

We're working on a GNUstep port now, in fact.

== Growl! (Global notification system) ==

[http://growl.info/ Growl!] uses distributed notification center to display a graphic message on screen. Every application can send messages to it, for example, when new emails arrive, buddies sign in the instant messager, a task end, etc. It is very easy to implement.

== Digital Librarian-like ==

I would really, really like a Digital Librarian for GNUstep. Basically, imagine an application that manage your documents the same way iTunes manage your music or iPhoto your photos... (to take well-known OSX apps as example ;-)

It would provide 1) automatic management of the documents by projects/ideas/whatever metadata 2) index your documents to let you search quickly in it 3) handles bibliography
As a postgrad student I have a LOT of articles in PDF/PS/DVI/html on my hard drive, and such an application would be really nice to help managing that.

A Digital Librarian screenshot: http://www.levenez.com/NeXTSTEP/Librarian.jpg
A screenshot of Vertex Librarian, a similar program for NeXTSTEP: http://www.levenez.com/NeXTSTEP/VertexLibrarian.jpg

== nib2gmodel/nib2gorm without OPENSTEP/MacOSX ==

I want;but I heard it is so hard to implementation. :-(

== iTunes/Rhythmbox clone ==

It would be nice to see a music or video player with real music/media management like [http://www.gnome.org/projects/rhythmbox/ Rhythmbox] or [http://www.apple.com/itunes/ iTunes]. iTunes has started to support management of movies and videoclips, so maybe media management is the way to go?

Creating document based applications

2005-07-09T02:18:37Z

Quineska: Spelling errors, grammatical fixes

Note: First version; subject to further revisions and changes.
--[[User:Quineska|ChrisArmstrong]] 07:09, 7 Jul 2005 (CEST)

== Introduction ==

OpenStep can provide your application a document-based model. It helps to simplify the process of creating such applications. GNUstep implements this as well; this document aims to provide an overview of what is required in the creation and design of such an application.

It is assumed you are familiar with GNUstep, and have some understanding as how to create Gorm's interface files (often referred to as nib's), as well as some understanding of how they work.

Importantly, such applications have certain components that are required, and should be considered as part of their design. When programming, classes that will be used as part of the AppKit are:

==== NSDocument ====

This class is central to the OpenStep document based model. These application's declare a new instance of a subclass of NSDocument for each “document” that is opened. You will subclass NSDocument to implement this.

Each instance of your NSDocument subclass may have one or more windows associated with it. These are used as an interface for loading and saving a representation of your document type. Each window will have an “NSWindowController” instance associated with it, where NSDocument maintains a list of these.

==== NSDocumentController ====

This class acts a controller. It maintains a list of documents (instances of your NSDocument subclass) and is responsible for loading and instantiating new documents. It is usually not necessary to implement a subclass of this, but often it may be useful to implement special functionality (especially related to opening and creating documents at an application level).

==== NSWindowController ====

As mentioned above, NSWindowController instances are individually associated with one NSWindow instance, in such a way that a document maintains a list of window controllers that are reponsible for rendering the views associated with a document.

You will most likely not have to subclass NSWindowController. Instead, you associate a nib file (the Gorm output) with the subclass of NSDocument, and NSDocumentController will load this nib file for each document that is created or loaded.

For example, a text based application that is used for the editing of plain text files, may subclass NSDocument with a TextDocument class. Each instance of this class would have an NSWindowController instance associated with it, which in turn manages a window instance that is instantiated from a nib file. The NSDocumentController instance, as managed and instantiated by GNUstep, would be responsible for loading and saving documents in your application. It even prompts the user to save their documents when they try to quit the application.

== File Components ==

In building your application you will need to create a number of special files. From scratch, the following should be a rough guide to getting it working. These include the Makefile, your application's property list and the interface files.

=== The Makefile ===

For this type of application, no special makefile is needed: it just has to be a normal application. Project Builder should be able to spit out the required makefile and Gorm files that are needed for a generic application. I believe it is also capable of providing support for document-based applications. Otherwise use the following as a template:

'''GNUmakefile'''

include $(GNUSTEP_MAKEFILES)/common.make 
APP_NAME = DocumentApp 
DocumentApp_OBJC_FILES = 
MyDocument.m 
main.m 
DocumentApp_RESOURCES = \ 
Resources/Info-gnustep.plist \ 
Resources/DocumentApp.gorm \ 
Resources/MyDocument.gorm 
-include GNUmakefile.preamble 
include $(GNUSTEP_MAKEFILES)/application.make 
-include GNUmakefile.postamble 

For more information as to customising this file, as well as setting up compiler options for third party libraries and includes, see the GNUstep makefile manual.

===The application dictionary===

For those that have edited this file in their project before, it is a dictionary with various values entered. For our purposes, we need an array within the main dictionary, called "NSTypes". This is a array of unnamed dictionaries, with one dictionary for each type.

I have provided an example for this file below. ProjectBuilder creates one as well. Please note that "TextEdit" does exist as an example application from NEXT I think, and again on MacOS X but I have constructed a much simpler version, used only for plain text files.

Taking a look at the single dictionary entry in the NSTypes array, the following key-value pairs are needed:
* '''NSDocumentClass:''' This is (string) the subclass name you use in your code, the "objective-c name" of your document subclass. This is used by NSDocumentController's default implementation to create instances of your document type.
* '''NSName:''' The generic file type (string). This is completely arbitrary, and can be anything you like. For the purpose of conventions, it may be more appropriate not to use the "NS" or "GS" prefix (the latter of which I not sure), and instead use either your own, or no prefix at all.
* '''NSHumanReadableName:''' The human readable name of your document type (string)? TODO: explain where this is used.
* '''NSUnixExtensions:''' An array of strings, each containing a file extension connected to this document type on "unix" platforms. TODO: explain how "unix" is interpreted by GNUstep.
* '''NSDOSExtensions:''' An array of strings, each containing a file extenstion connected to this document type on "DOS" platforms (could be loosely interpreted as any MS platforms GNUstep runs on, i.e. Windows 2000/XP).
* '''NSRole:''' A string, either "Viewer" or "Editor", depending on how your document operates on this file type.
* '''NSIcon:''' A icon name associated with this document type. TODO: Investigate how this works.

'''Info-gnustep.plist'''
{
ApplicationDescription = "A simple text editor for GNUstep.";
ApplicationName = TextEdit;
ApplicationRelease = 0.10;
Authors = ( "Christopher Armstrong" );
Copyright = "Copyright (C) 2005 Christopher Armstrong";
CopyrightDescription = "Released under GPL.";
FullVersionID = 0.10;
NSExecutable = TextEdit;
NSMainNibFile = TextEdit.gorm;
NSPrincipalClass = NSApplication;
NSRole = Application;
NSTypes = (
{
NSDocumentClass = "TextDocument";
NSName = "GSTextDocumentType";
NSHumanReadableName = "Text Document";
NSUnixExtensions = ( "txt", "" );
NSDOSExtensions = ( "txt" );
NSRole = Editor;
}
);
}

For more information on property list files, consult [[Property Lists]].

=== Interface files ===

Two interface files are needed: one for your main application, and another that will be instantiated with each instance of your document subclass. These both should be listed as resources in your makefile, (as shown the GNUmakefile example above). It may be helpful to name the document nib file after your class.

==== Application Interface File ====

The application one should just be a menu (though it could be more if necessary). When constructing it, take the following into account:

* Use a standard Gorm template for an Application.
* Delete the window instance in the "Objects" pane (unless you need a main window, which is beyond the scope of this document).
* Set NSOwner's class to "NSDocumentController". This is the custom class option of NSOwner in the property inspector. This ensures that the openDocument:, newDocument: messages, as sent to NSFirst, get picked up by NSDocumentController. Do not instantiate it (I believe you can't anyway).
* If you intend to subclass NSDocumentController, subclass it in the Classes pane. To make sure that this class is instantiated and used, make sure you instantiate it in Gorm or in your main.m file, and set NSOwner to be your subclass.
* Drag a Document menu from the palette onto your main menu. This already has the proper outlet and action linkage for each relevant message to be directed to NSFirst. Generic messages (such as openDocument:, not associated with any document instance) are forwarded to the shared instance of NSDocumentController (see it's reference documentation). When a document is active, more specific messages (such as close: or saveDocument:) are forwarded to the relevant document instance of your NSDocument subclass.
* Add any appropriate menus such as "Info" and "Format" which may be relevant to your application.

==== Document Interface File(s) ====

The document interface file is a window containing the view(s) required for the implementation of one instance of your document type. For example, in the case of a TextDocument type, a window instance with a NSTextView drawn on it is used for each document window. This interface file is instantiated every time a person creates a new document (the newDocument: message goes to NSDocumentController) or opens an existing document (openDocument:).

You will need to:
* '''Subclass NSDocument''' with your document type in Gorm. This is done in a couple of ways, see [[Gorm_Manual#Custom_classes|custom classes]].
* '''Set NSOwner:''' Set your subclass as NSOwner's Custom class using the Property Inspector). DO NOT INSTANTIATE IT.

Another thing that you may want to consider is custom outlets. If you place certain views or controls on your window (including the window itself), you may want to refer to them directly in your code, e.g. the NSTextView in our TextEdit example is accessed directly, so that we can save it's contents to a file. To enable this, we add outlets to our class (see [[Gorm_Manual#Custom_classes|custom classes]]). We then connect NSOwner to the appropriate controls/views, and select the outlets in the Connections Property Inspector (see [[Gorm_Manual#Editing_the_interface|editing the interface]]).

== Code ==

Various things need to be done at a code level, to ensure that your NSDocument subclass is properly instantiated. This section aims to tell you what is necessary.

=== NSDocument subclass ===

When creating your subclass, you may have chosen to have Gorm create the class files. If not, you should create two files for your subclass: a header (.h) file and an implementation file (.m). The header file should take the following layout (we're using the TextEdit example again):

#ifndef TEXTDOCUMENT_H
#define TEXTDOCUMENT_H 
#include <AppKit/AppKit.h> 
@class NSDocument; 
/* The document type string, as specified in the property list [[#The_application_dictionary|NSTypes array]] */ 
NSString * GSTextDocumentType = "GSTextDocumentType";
@interface TextDocument : NSDocument
{
@protected
/* Outlets we added in our Gorm nib file */
id * textView;
}
/* Basic methods used for loading and saving document data (respectively). */
- (BOOL) loadDataRepresentation:(NSData*)representation ofType:(NSString*)type;
- (NSData*) dataRepresentationOfType: (NSString*)type; 
/* Information and events handling of GUI related changes */
- (NSString*) windowNibName;
- (void) windowControllerDidLoadNib:(NSWindowController*)windowController; 
@end 

Firstly, take note that we inherit from NSDocument. As a result, we need to override some methods for a basic (but working) implementation.

==== loadDataRepresentation:ofType: and dataRepresentationOfType: ====

The methods, loadDataRepresent:ofType: and dataRepresentationOfType: are used by NSDocumentController to load and save our files. The first method is called when the user trys to open a document (NSDocumentController gets the file name and copies it's data using an open panel). The method is passed the raw data in this file, as well as a string representing its type. It is important to note that this type string is the same one used in your property list. It is used by NSDocumentController to tell you what type it thinks you should open the data with. If this is not possible, or if there is an error trying to parse the data, your method returns FALSE/NO. Otherwise, you should store a local, meaningful representation of the data, which you can insert into your document window a little later (and return TRUE/YES).

For example, in terms of the TextEdit example:
- (BOOL) loadDataRepresentation:(NSData*) representation ofType:(NSString*)type
{
/*Check type information */
if ([representation equalTo:GSTextDocumentType]==NO)
return NO;
/* Clean out our old representation if it still exists */
if (fileContents) RELEASE(fileContents); 
/* Allocate room for the new data, and try to initialise a string with it. */
self->fileContents = [NSString alloc];
fileContents = [fileContents initWithBytes: [representation bytes]
length: [representation length]
encoding: NSASCIIStringEncoding]; 
/* If this can't be done, return NO */
if (!fileContents)
return NO; 
/* Otherwise, set our TextView to the string data. */
[self->textView setString: fileContents];
return YES;
}

If this is not sufficient, or if your program can open the data in a more efficient manner, it may be worth looking into overriding -initWithContentsOfFile:ofType: and -initWithContentsOfURL:ofType:. Again, see the GUI manual for more details.

dataRepresentationOfType: is used to save the data. Your method is expected to return an instance of NSData that contains what should be saved to a file, for the type specified. Again, the ''type'' variable should be checked to ensure that you can write data of that type. Return nil if the file cannot be saved as that type.

For example:

- (NSData*) dataRepresentationOfType:(NSString*)type
{
if ([type equalTo:GSTextDocumentType]==NO)
return nil; 
NSData stringData = [[textView string] dataUsingEncoding:NSASCIIStringEncoding];
return stringData;
}

If a more sophisticated save implementation is needed, consult the documentation for information on the writeTo* methods.

==== windowNibName ====

This method must be overriden to return the a string of the name of your nib file (without the file extension). More complex implementations will use other methods to load the interface files. TODO: information on what methods need to be overriden.

==== windowControllerDidLoadNib: ====

Use this method to add code that should be run as soon as ''windowController'' has been initialised. Your document may have many window controllers; each window controller taking possession of one window.

In the TextEdit example, this method is used to copy the ''fileContents'' variable to the text view. It otherwise initialises the document window.

Also note that you can override windowControllerWillLoadNib: to perform pre-interface loading initialisation.

==== makeWindowControllers ====

This is an optional method override, which must be used if you have multiple window controllers per document. It is responsible for creating each window controller from it's interface file and then adding it to the document. Use the addWindowController: method.

==== Other considerations ====

* You need a way to notify NSDocument that your document has changed, so that NSDocumentController can enable the menu item to allow saving. This is done by a call to the updateChangeCount: method. For example, the TextDocument class adds itself as a delegate to the textView, for any notification of changes. It then calls updateChangeCount: in the delegate's method.

* You may also wish to add a close: method (not the close method already in NSDocument, see below) to respond to the menu item permitting your document to close. This could perform cleanup operations before a call to [self close] is made e.g.

- (void) close:(id)sender /* Note this is not the method found in NSDocument (they differ by a parameter) */
{
[self close];
}

=== NSDocumentController ===

This class can optionally be subclassed, to implement some specific functionality. For example, programs handling multiple document types may override newDocument: to create a window so that the user can select which document type to create.

You should use separate implementation files and add the .m file to GNUmakefile.

=== NSWindowController ===

This class can also be optionally subclassed, to implement functionality specific to a window controller for a document type. You may need to override makeWindowControllers: in the NSDocument subclass in order to make sure your specific window controller is instantiated.

You should use separate implemenation files and add the .m file to GNUmakefile.

== Optional Additions ==

=== Custom NSDocumentController and NSWindowController implementations ===

See [[#NSWindowController|NSWindowController]] and [[#NSDocumentController|NSDocumentController]].

----

[[Category:Development]]

Creating document based applications

2005-07-09T02:08:00Z

Quineska: Spelling errors, grammatical fixes

Note: First version; subject to further revisions and changes.
--[[User:Quineska|ChrisArmstrong]] 07:09, 7 Jul 2005 (CEST)

== Introduction ==

OpenStep can provide your application a document-based model. It helps to simplify the process of creating such applications. GNUstep implements this as well; this document aims to provide an overview of what is required in the creation and design of such an application.

It is assumed you are familiar with GNUstep, and have some understanding as how to create Gorm's interface files (often referred to as nib's), as well as some understanding of how they work.

Importantly, such applications have certain components that are required, and should be considered as part of their design. When programming, classes that will be used as part of the AppKit are:

==== NSDocument ====

This class is central to the OpenStep document based model. These application's declare a new instance of a subclass of NSDocument for each “document” that is opened. You will subclass NSDocument to implement this.

Each instance of your NSDocument subclass may have one or more windows associated with it. These are used as an interface for loading and saving a representation of your document type. Each window will have an “NSWindowController” instance associated with it, where NSDocument maintains a list of these.

==== NSDocumentController ====

This class acts a controller. It maintains a list of documents (instances of your NSDocument subclass) and is responsible for loading and instantiating new documents. It is usually not necessary to implement a subclass of this, but often it may be useful to implement special functionality (especially related to opening and creating documents at an application level).

==== NSWindowController ====

As mentioned above, NSWindowController instances are individually associated with one NSWindow instance, in such a way that a document maintains a list of window controllers that are reponsible for rendering the views associated with a document.

You will most likely not have to subclass NSWindowController. Instead, you associate a nib file (the Gorm output) with the subclass of NSDocument, and NSDocumentController will load this nib file for each document that is created or loaded.

For example, a text based application that is used for the editing of plain text files, may subclass NSDocument with a TextDocument class. Each instance of this class would have an NSWindowController instance associated with it, which in turn manages a window instance that is instantiated from a nib file. The NSDocumentController instance, as managed and instantiated by GNUstep, would be responsible for loading and saving documents in your application. It even prompts the user to save their documents when they try to quit the application.

== File Components ==

In building your application you will need to create a number of special files. From scratch, the following should be a rough guide to getting it working. These include the Makefile, your application's property list and the interface files.

=== The Makefile ===

For this type of application, no special makefile is needed: it just has to be a normal application. Project Builder should be able to spit out the required makefile and Gorm files that are needed for a generic application. I believe it is also capable of providing support for document-based applications. Otherwise use the following as a template:

'''GNUmakefile'''

include $(GNUSTEP_MAKEFILES)/common.make 
APP_NAME = DocumentApp 
DocumentApp_OBJC_FILES = 
MyDocument.m 
main.m 
DocumentApp_RESOURCES = \ 
Resources/Info-gnustep.plist \ 
Resources/DocumentApp.gorm \ 
Resources/MyDocument.gorm 
-include GNUmakefile.preamble 
include $(GNUSTEP_MAKEFILES)/application.make 
-include GNUmakefile.postamble 

For more information as to customising this file, as well as setting up compiler options for third party libraries and includes, see the GNUstep makefile manual.

===The application dictionary===

For those that have edited this file in their project before, it is a dictionary with various values entered. For our purposes, we need an array within the main dictionary, called "NSTypes". This is a array of unnamed dictionaries, with one dictionary for each type.

I have provided an example for this file below. ProjectBuilder creates one as well. Please note that "TextEdit" does exist as an example application from NEXT I think, and again on MacOS X but I have constructed a much simpler version, used only for plain text files.

Taking a look at the single dictionary entry in the NSTypes array, the following key-value pairs are needed:
* '''NSDocumentClass:''' This is (string) the subclass name you use in your code, the "objective-c name" of your document subclass. This is used by NSDocumentController's default implementation to create instances of your document type.
* '''NSName:''' The generic file type (string). This is completely arbitrary, and can be anything you like. For the purpose of conventions, it may be more appropriate not to use the "NS" or "GS" prefix (the latter of which I not sure), and instead use either your own, or no prefix at all.
* '''NSHumanReadableName:''' The human readable name of your document type (string)? TODO: explain where this is used.
* '''NSUnixExtensions:''' An array of strings, each containing a file extension connected to this document type on "unix" platforms. TODO: explain how "unix" is interpreted by GNUstep.
* '''NSDOSExtensions:''' An array of strings, each containing a file extenstion connected to this document type on "DOS" platforms (could be loosely interpreted as any MS platforms GNUstep runs on, i.e. Windows 2000/XP).
* '''NSRole:''' A string, either "Viewer" or "Editor", depending on how your document operates on this file type.
* '''NSIcon:''' A icon name associated with this document type. TODO: Investigate how this works.

'''Info-gnustep.plist'''
{
ApplicationDescription = "A simple text editor for GNUstep.";
ApplicationName = TextEdit;
ApplicationRelease = 0.10;
Authors = ( "Christopher Armstrong" );
Copyright = "Copyright (C) 2005 Christopher Armstrong";
CopyrightDescription = "Released under GPL.";
FullVersionID = 0.10;
NSExecutable = TextEdit;
NSMainNibFile = TextEdit.gorm;
NSPrincipalClass = NSApplication;
NSRole = Application;
NSTypes = (
{
NSDocumentClass = "TextDocument";
NSName = "GSTextDocumentType";
NSHumanReadableName = "Text Document";
NSUnixExtensions = ( "txt", "" );
NSDOSExtensions = ( "txt" );
NSRole = Editor;
}
);
}

For more information on property list files, consult [[Property Lists]].

=== Interface files ===

Two interface files are needed: one for your main application, and another that will be instantiated with each instance of your document subclass. These both should be listed as resources in your makefile, (as shown the GNUmakefile example above). It may be helpful to name the document nib file after your class.

==== Application Interface File ====

The application one should just be a menu (though it could be more if necessary). When constructing it, take the following into account:

* Use a standard Gorm template for an Application.
* Delete the window instance in the "Objects" pane (unless you need a main window, in which case I don't know how to operate).
* Set NSOwner's class to "NSDocumentController" (this is the custom class option of NSOwner in the property inspector). This ensures openDocument, newDocument, etc. messages, as sent to NSFirst, get picked up by NSDocumentController. Do not instantiate it (I believe you can't anyway).
* If you intend to subclass NSDocumentController, subclass it in the Classes pane. To make sure that this class is instantiated and used, make sure you instantiate it in Gorm or in your main.m file, and set NSOwner to be your subclass.
* Drag a Document menu from the palette onto your main menu. This already has the proper linkage for each relevant message for a document setup to be directed to NSFirst. In the case of generic messages (such as openDocument:, not associated with any document instance), these are forwarded to the shared instance of NSDocumentController (see it's reference documentation). When a document is active, more specific messages (such as close: or saveDocument:) are forwarded to the relevant document instance of your NSDocument subclass.
* Add any appropriate menus such as "Info" and "Format" which may be relevant to your application.

==== Document Interface File(s) ====

The document interface file is (generically) a window containing the view(s) required for the implementation of one instance of your document type. For example, in the case of a TextDocument type, a window instance with a NSTextView drawn on it is used for each open window. This nib file is instantiated every time a person creates a new document (the newDocument: message goes to NSDocumentController) or opens an existing document (openDocument:).

You will need to:
* '''Subclass NSDocument''' with your document type in Gorm (this is done in a couple of ways, see [[Gorm_Manual#Custom_classes|custom classes]]).
* '''Set NSOwner:''' Set your subclass as NSOwner's Custom class (done using the Property inspector). DO NOT INSTANTIATE IT.

Another thing that you may want to consider is custom outlets. If you place certain views or controls on your window (including the window itself), you may want to refer to them directly in yout code, e.g. the NSTextView in our TextEdit example is accessed directly, so that we can save it's contents to a file. To enable this, we add outlets to our class (see [[Gorm_Manual#Custom_classes|custom classes]]). We then connected NSOwner to the appropriate controls/views, and selected the outlets in the Connections property inspector (see [[Gorm_Manual#Editing_the_interface|editing the interface]]).

== Code ==

Various things need to be done at a code level, to ensure that your NSDocument subclass is properly instantiated. This section aims to tell you what is necessary.

=== NSDocument subclass ===

When creating your subclass, you may have chosen to have Gorm create the class files. If not, you should create two files for your subclass: a header (.h) file and an implementation file (.m). The header file should take the following layout (we're using the TextEdit example again):

#ifndef TEXTDOCUMENT_H
#define TEXTDOCUMENT_H 
#include <AppKit/AppKit.h> 
@class NSDocument; 
/* The document type string, as specified in the property list [[#The_application_dictionary|NSTypes array]] */ 
NSString * GSTextDocumentType = "GSTextDocumentType";
@interface TextDocument : NSDocument
{
@protected
/* Outlets we added in our Gorm nib file */
id * textView;
}
/* Basic methods used for loading and saving document data (respectively). */
- (BOOL) loadDataRepresentation:(NSData*)representation ofType:(NSString*)type;
- (NSData*) dataRepresentationOfType: (NSString*)type; 
/* Information and events handling of GUI related changes */
- (NSString*) windowNibName;
- (void) windowControllerDidLoadNib:(NSWindowController*)windowController; 
@end 

Firstly, take note that we inherit from NSDocument. As a result, we need to override some methods for a basic (but working) implementation.

==== loadDataRepresentation:ofType: and dataRepresentationOfType: ====

The methods, loadDataRepresent:ofType: and dataRepresentationOfType: are used by NSDocumentController to load and save our files. The first method is called when the user trys to open a document (NSDocumentController gets the file name and copies it's data using an open panel). The method is passed the raw data in this file, as well as a string representing its type. It is important to note that this type string is the same one used in your property list. It is used by NSDocumentController to tell you what type it thinks you should open the data with. If this is not possible, or if there is an error trying to parse the data, your method returns FALSE/NO. Otherwise, you should store a local, meaningful representation of the data, which you can insert into your document window a little later (and return YES).

For example, in terms of the TextEdit example:
- (BOOL) loadDataRepresentation:(NSData*) representation ofType:(NSString*)type
{
/*Check type information */
if ([representation equalTo:GSTextDocumentType]==NO)
return NO;
/* Clean out our old representation if it still exists */
if (fileContents) RELEASE(fileContents); 
/* Allocate room for the new data, and try to initialise a string with it. */
self->fileContents = [NSString alloc];
fileContents = [fileContents initWithBytes: [representation bytes]
length: [representation length]
encoding: NSASCIIStringEncoding]; 
/* If this can't be done, return NO */
if (!fileContents)
return NO; 
/* Otherwise, set our TextView to the string data. */
[self->textView setString: fileContents];
return YES;
}

If this is not suffice, or if your program can open the data in a more efficient manner, it may be worth looking into overriding -initWithContentsOfFile:ofType: and -initWithContentsOfURL:ofType: (see the GUI manual for more details).

dataRepresentationOfType: is used to save the data. Your method is expected to return an instance of NSData that contains what should be saved to a file, for the type specified. Again, the ''type'' variable should be checked to ensure that you can write data of that type. Return nil if the file cannot be saved as that type.

For example:

- (NSData*) dataRepresentationOfType:(NSString*)type
{
if ([type equalTo:GSTextDocumentType]==NO)
return nil; 
NSData stringData = [[textView string] dataUsingEncoding:NSASCIIStringEncoding];
return stringData;
}

If a more sophisticated save implementation is needed, consult the documentation for information on the writeTo methods.

==== windowNibName ====

This method must be overriden to return the a string of the name of your nib file (without the file extention). More complex implementations will use other methods to load the interface files. TODO: information on what methods need to be overriden.

==== windowControllerDidLoadNib: ====

Use this method to add code that should be run as soon as ''windowController'' has been initialised. Your document may have many window controllers; each window controller taking possession of one window.

In the TextEdit example, this method is used to copy the fileContents object ivar to the text view. It otherwise initialises the document window.

Also note that you can override windowControllerWillLoadNib: to perform pre-nib loading initialisation.

==== makeWindowControllers ====

This is an optional method override, which must be used if you have multiple window controllers per document. It is responsible for creating each window controller from it's nib and then adding it to the document. Use the addWindowController: method.

==== Other considerations ====

* You need a way to notify NSDocument that your document has changed, so that NSDocumentController can enable the menu item to allow saving. This is done by a call to the updateChangeCount: method. For example, the TextDocument class adds itself as a delegate to the textView, for any notification of changes. It then calls updateChangeCount: in the delegate's method.

* You may also wish to add a close: method (not the close method already in NSDocument, see below) to respond to the menu item permitting your document to close. This could perform cleanup operations before a call to [super close] is called e.g.

- (void) close:(id)sender /* Note this is not the method found in NSDocument (they differ by a parameter) */
{
[self close];
}

=== NSDocumentController ===

This class can optionally be subclassed, to implement some specific functionality. For example, programs handling multiple document types may override newDocument: to create a window so that the user can select which document type to create.

You should use separate implementation files and add the .m file to GNUmakefile.

=== NSWindowController ===

This class can also be optionally subclassed, to implement functionality specific to a window controller for a document type. You may need to override makeWindowControllers: in the NSDocument subclass in order to make sure your specific window controller is instantiated.

You should use separate implemenatino files and add the .m file to GNUmakefile.

== Optional Additions ==

=== Custom NSDocumentController and NSWindowController implementations ===

See [[#NSWindowController|NSWindowController]] and [[#NSDocumentController|NSDocumentController]].

----

[[Category:Development]]

Creating document based applications

2005-07-09T02:03:41Z

Quineska: Spelling errors, grammatical fixes

Note: First version; subject to further revisions and changes.
--[[User:Quineska|ChrisArmstrong]] 07:09, 7 Jul 2005 (CEST)

== Introduction ==

OpenStep can provide your application a document-based model. It helps to simplify the process of creating such applications. GNUstep implements this as well; this document aims to provide an overview of what is required in the creation and design of such an application.

It is assumed you are familiar with GNUstep, and have some understanding as how to create Gorm's interface files (often referred to as nib's), as well as some understanding of how they work.

Importantly, such applications have certain components that are required, and should be considered as part of their design. When programming, classes that will be used as part of the AppKit are:

==== NSDocument ====

This class is central to the OpenStep document based model. These application's declare a new instance of a subclass of NSDocument for each “document” that is opened. You will subclass NSDocument to implement this.

Each instance of your NSDocument subclass may have one or more windows associated with it. These are used as an interface for loading and saving a representation of your document type. Each window will have an “NSWindowController” instance associated with it, where NSDocument maintains a list of these.

==== NSDocumentController ====

This class acts a controller. It maintains a list of documents (instances of your NSDocument subclass) and is responsible for loading and instantiating new documents. It is usually not necessary to implement a subclass of this, but often it may be useful to implement special functionality (especially related to opening and creating documents at an application level).

==== NSWindowController ====

As mentioned above, NSWindowController instances are individually associated with one NSWindow instance, in such a way that a document maintains a list of window controllers that are reponsible for rendering the views associated with a document.

You will most likely not have to subclass NSWindowController. Instead, you associate a nib file (the Gorm output) with the subclass of NSDocument, and NSDocumentController will load this nib file for each document that is created or loaded.

For example, a text based application that is used for the editing of plain text files, may subclass NSDocument with a TextDocument class. Each instance of this class would have an NSWindowController instance associated with it, which in turn manages a window instance that is instantiated from a nib file. The NSDocumentController instance, as managed and instantiated by GNUstep, would be responsible for loading and saving documents in your application. It even prompts the user to save their documents when they try to quit the application.

== File Components ==

In building your application you will need to create a number of special files. From scratch, the following should be a rough guide to getting it working. These include the Makefile, your application's property list and the interface files.

=== The Makefile ===

For this type of application, no special makefile is needed: it just has to be a normal application. Project Builder should be able to spit out the required makefile and Gorm files that are needed for a generic application. I believe it is also capable of providing support for document-based applications. Otherwise use the following as a template:

'''GNUmakefile'''

include $(GNUSTEP_MAKEFILES)/common.make 
APP_NAME = DocumentApp 
DocumentApp_OBJC_FILES = 
MyDocument.m 
main.m 
DocumentApp_RESOURCES = \ 
Resources/Info-gnustep.plist \ 
Resources/DocumentApp.gorm \ 
Resources/MyDocument.gorm 
-include GNUmakefile.preamble 
include $(GNUSTEP_MAKEFILES)/application.make 
-include GNUmakefile.postamble 

For more information as to customising this file, as well as setting up compiler options for third party libraries and includes, see the GNUstep makefile manual.

===The application dictionary===

For those that have edited this file in their project before, it is a dictionary with various values entered. For our purposes, we need an array within the main dictionary, called "NSTypes". This is a array of unnamed dictionaries, with one dictionary for each type.

An entire example of this file, for a "theoretical" TextEdit application (please note that such an application does exist as an example application from Next I think, and again on MacOS X but I have constructed a much simpler version, used only for plain text files).

Taking a look at the single dictionary entry in the NSTypes array, the following key-value pairs are needed:
* '''NSDocumentClass:''' This is (string) the subclass name you use in your code, the "objective-c name" of your document subclass. This is used by NSDocumentController's default implementation to create instances of your document type.
* '''NSName:''' The generic file type (string). This is completely arbitrary, and can be anything you like. For the purpose of conventions, it may be more appropriate not to use the "NS" or "GS" prefix (the latter of which I not sure), and instead use either your own, or no prefix at all.
* '''NSHumanReadableName:''' The human readable name of your document type (string)? TODO: explain where this is used.
* '''NSUnixExtensions:''' An array of strings, each containing a file extension connected to this document type on "unix" platforms. TODO: explain how "unix" is interpreted by GNUstep.
* '''NSDOSExtensions:''' An array of strings, each containing a file extenstion connected to this document type on "DOS" platforms (could be loosely interpreted as any MS platforms GNUstep runs on, i.e. Windows 2000/XP).
* '''NSRole:''' A string, either "Viewer" or "Editor", depending on how your document operates on this file type.
* '''NSIcon:''' A icon name associated with this document type. TODO: Investigate how this works.

'''Info-gnustep.plist'''
{
ApplicationDescription = "A simple text editor for GNUstep.";
ApplicationName = TextEdit;
ApplicationRelease = 0.10;
Authors = ( "Christopher Armstrong" );
Copyright = "Copyright (C) 2005 Christopher Armstrong";
CopyrightDescription = "Released under GPL.";
FullVersionID = 0.10;
NSExecutable = TextEdit;
NSMainNibFile = TextEdit.gorm;
NSPrincipalClass = NSApplication;
NSRole = Application;
NSTypes = (
{
NSDocumentClass = "TextDocument";
NSName = "GSTextDocumentType";
NSHumanReadableName = "Text Document";
NSUnixExtensions = ( "txt", "" );
NSDOSExtensions = ( "txt" );
NSRole = Editor;
}
);
}

For more information on property list files, consult [[Property Lists]].

=== Interface files ===

Two interface files are needed: one for your main application, and another that will be instantiated with each instance of your document subclass. These both should be listed as resources in your makefile, (as shown the GNUmakefile example above). It may be helpful to name the document nib file after your class.

==== Application Interface File ====

The application one should just be a menu (though it could be more if necessary). When constructing it, take the following into account:

* Use a standard Gorm template for an Application.
* Delete the window instance in the "Objects" pane (unless you need a main window, in which case I don't know how to operate).
* Set NSOwner's class to "NSDocumentController" (this is the custom class option of NSOwner in the property inspector). This ensures openDocument, newDocument, etc. messages, as sent to NSFirst, get picked up by NSDocumentController. Do not instantiate it (I believe you can't anyway).
* If you intend to subclass NSDocumentController, subclass it in the Classes pane. To make sure that this class is instantiated and used, make sure you instantiate it in Gorm or in your main.m file, and set NSOwner to be your subclass.
* Drag a Document menu from the palette onto your main menu. This already has the proper linkage for each relevant message for a document setup to be directed to NSFirst. In the case of generic messages (such as openDocument:, not associated with any document instance), these are forwarded to the shared instance of NSDocumentController (see it's reference documentation). When a document is active, more specific messages (such as close: or saveDocument:) are forwarded to the relevant document instance of your NSDocument subclass.
* Add any appropriate menus such as "Info" and "Format" which may be relevant to your application.

==== Document Interface File(s) ====

The document interface file is (generically) a window containing the view(s) required for the implementation of one instance of your document type. For example, in the case of a TextDocument type, a window instance with a NSTextView drawn on it is used for each open window. This nib file is instantiated every time a person creates a new document (the newDocument: message goes to NSDocumentController) or opens an existing document (openDocument:).

You will need to:
* '''Subclass NSDocument''' with your document type in Gorm (this is done in a couple of ways, see [[Gorm_Manual#Custom_classes|custom classes]]).
* '''Set NSOwner:''' Set your subclass as NSOwner's Custom class (done using the Property inspector). DO NOT INSTANTIATE IT.

Another thing that you may want to consider is custom outlets. If you place certain views or controls on your window (including the window itself), you may want to refer to them directly in yout code, e.g. the NSTextView in our TextEdit example is accessed directly, so that we can save it's contents to a file. To enable this, we add outlets to our class (see [[Gorm_Manual#Custom_classes|custom classes]]). We then connected NSOwner to the appropriate controls/views, and selected the outlets in the Connections property inspector (see [[Gorm_Manual#Editing_the_interface|editing the interface]]).

== Code ==

Various things need to be done at a code level, to ensure that your NSDocument subclass is properly instantiated. This section aims to tell you what is necessary.

=== NSDocument subclass ===

When creating your subclass, you may have chosen to have Gorm create the class files. If not, you should create two files for your subclass: a header (.h) file and an implementation file (.m). The header file should take the following layout (we're using the TextEdit example again):

#ifndef TEXTDOCUMENT_H
#define TEXTDOCUMENT_H 
#include <AppKit/AppKit.h> 
@class NSDocument; 
/* The document type string, as specified in the property list [[#The_application_dictionary|NSTypes array]] */ 
NSString * GSTextDocumentType = "GSTextDocumentType";
@interface TextDocument : NSDocument
{
@protected
/* Outlets we added in our Gorm nib file */
id * textView;
}
/* Basic methods used for loading and saving document data (respectively). */
- (BOOL) loadDataRepresentation:(NSData*)representation ofType:(NSString*)type;
- (NSData*) dataRepresentationOfType: (NSString*)type; 
/* Information and events handling of GUI related changes */
- (NSString*) windowNibName;
- (void) windowControllerDidLoadNib:(NSWindowController*)windowController; 
@end 

Firstly, take note that we inherit from NSDocument. As a result, we need to override some methods for a basic (but working) implementation.

==== loadDataRepresentation:ofType: and dataRepresentationOfType: ====

The methods, loadDataRepresent:ofType: and dataRepresentationOfType: are used by NSDocumentController to load and save our files. The first method is called when the user trys to open a document (NSDocumentController gets the file name and copies it's data using an open panel). The method is passed the raw data in this file, as well as a string representing its type. It is important to note that this type string is the same one used in your property list. It is used by NSDocumentController to tell you what type it thinks you should open the data with. If this is not possible, or if there is an error trying to parse the data, your method returns FALSE/NO. Otherwise, you should store a local, meaningful representation of the data, which you can insert into your document window a little later (and return YES).

For example, in terms of the TextEdit example:
- (BOOL) loadDataRepresentation:(NSData*) representation ofType:(NSString*)type
{
/*Check type information */
if ([representation equalTo:GSTextDocumentType]==NO)
return NO;
/* Clean out our old representation if it still exists */
if (fileContents) RELEASE(fileContents); 
/* Allocate room for the new data, and try to initialise a string with it. */
self->fileContents = [NSString alloc];
fileContents = [fileContents initWithBytes: [representation bytes]
length: [representation length]
encoding: NSASCIIStringEncoding]; 
/* If this can't be done, return NO */
if (!fileContents)
return NO; 
/* Otherwise, set our TextView to the string data. */
[self->textView setString: fileContents];
return YES;
}

If this is not suffice, or if your program can open the data in a more efficient manner, it may be worth looking into overriding -initWithContentsOfFile:ofType: and -initWithContentsOfURL:ofType: (see the GUI manual for more details).

dataRepresentationOfType: is used to save the data. Your method is expected to return an instance of NSData that contains what should be saved to a file, for the type specified. Again, the ''type'' variable should be checked to ensure that you can write data of that type. Return nil if the file cannot be saved as that type.

For example:

- (NSData*) dataRepresentationOfType:(NSString*)type
{
if ([type equalTo:GSTextDocumentType]==NO)
return nil; 
NSData stringData = [[textView string] dataUsingEncoding:NSASCIIStringEncoding];
return stringData;
}

If a more sophisticated save implementation is needed, consult the documentation for information on the writeTo methods.

==== windowNibName ====

This method must be overriden to return the a string of the name of your nib file (without the file extention). More complex implementations will use other methods to load the interface files. TODO: information on what methods need to be overriden.

==== windowControllerDidLoadNib: ====

Use this method to add code that should be run as soon as ''windowController'' has been initialised. Your document may have many window controllers; each window controller taking possession of one window.

In the TextEdit example, this method is used to copy the fileContents object ivar to the text view. It otherwise initialises the document window.

Also note that you can override windowControllerWillLoadNib: to perform pre-nib loading initialisation.

==== makeWindowControllers ====

This is an optional method override, which must be used if you have multiple window controllers per document. It is responsible for creating each window controller from it's nib and then adding it to the document. Use the addWindowController: method.

==== Other considerations ====

* You need a way to notify NSDocument that your document has changed, so that NSDocumentController can enable the menu item to allow saving. This is done by a call to the updateChangeCount: method. For example, the TextDocument class adds itself as a delegate to the textView, for any notification of changes. It then calls updateChangeCount: in the delegate's method.

* You may also wish to add a close: method (not the close method already in NSDocument, see below) to respond to the menu item permitting your document to close. This could perform cleanup operations before a call to [super close] is called e.g.

- (void) close:(id)sender /* Note this is not the method found in NSDocument (they differ by a parameter) */
{
[self close];
}

=== NSDocumentController ===

This class can optionally be subclassed, to implement some specific functionality. For example, programs handling multiple document types may override newDocument: to create a window so that the user can select which document type to create.

You should use separate implementation files and add the .m file to GNUmakefile.

=== NSWindowController ===

This class can also be optionally subclassed, to implement functionality specific to a window controller for a document type. You may need to override makeWindowControllers: in the NSDocument subclass in order to make sure your specific window controller is instantiated.

You should use separate implemenatino files and add the .m file to GNUmakefile.

== Optional Additions ==

=== Custom NSDocumentController and NSWindowController implementations ===

See [[#NSWindowController|NSWindowController]] and [[#NSDocumentController|NSDocumentController]].

----

[[Category:Development]]

NSTableView

2005-07-09T01:59:42Z

Quineska:

NSTableView is located within the AppKit (gnustep-gui library) and is used to display tables. It uses a delegate model for getting it's data i.e. you give it an object that provides it with the data it should display.

== Code chunks ==

=== Autosize row height according to font ===

Following code autosizes the row height according to the size of data cell font:

- (void)autosizeRowHeight
{
NSTableColumn *col = [[self tableColumns] objectAtIndex:0];
NSFont *font;

font = [[col dataCell] font];

[self setRowHeight:[font maximumAdvancement].height];
}

Use the method in a category of NSTableView.

NSTableView

2005-07-09T01:59:18Z

Quineska:

NSTableView is located within the AppKit (gnustep-gui library) and is used to create display tables. It uses a delegate model for getting it's data i.e. you give it an object that provides it with the data it should display.

== Code chunks ==

=== Autosize row height according to font ===

Following code autosizes the row height according to the size of data cell font:

- (void)autosizeRowHeight
{
NSTableColumn *col = [[self tableColumns] objectAtIndex:0];
NSFont *font;

font = [[col dataCell] font];

[self setRowHeight:[font maximumAdvancement].height];
}

Use the method in a category of NSTableView.

Language support

2005-07-09T01:56:48Z

Quineska: Changed example to code (for distinction)

You can set your preference of language using the [[defaults]] command. It takes a list of languages, with the most left one being the most preferred. The list should contain at least one preferred language, otherwise GNUstep defaults to English.

Here is an example where the user prefers Turkish, then Dutch, then English.

defaults write NSGlobalDomain NSLanguages "(Turkish, Dutch, English)"

----
See also: [[NSDefaults]]

Framework wish list

2005-07-09T01:55:57Z

Quineska: Added framwork loading idea

I would like to see a testsuite and API diffs for Openstep, Gnustep and different Cocoa-Versions.

--

It would be good to see a better framework handling mechanism than what we have now. Currently on unix platforms, framework libraries are symbolically linked against in the System/Library/Libraries directory, making them unmoveable and difficult to uninstall (at least, without package managers). On windows, they copied into this directory.

I think it's possible to create an application loader that inserts these directories into the linker's path (on linux at least, simply adding them to LD_LIBRARY_PATH in the environment the program runs in). I was looking at implementing this an application loader (similar to openapp, but in Objective-C with gnustep-base). Preliminary tests would seem to show that this is at least possible on Linux. I believe a similiar solution is feasible on Windows (sticking them into the PATH variable). Does anyone think a solution like this is useful on other Unix platforms? Any better solutions? --[[User:Quineska|ChrisArmstrong]] 03:55, 9 Jul 2005 (CEST)

Property Lists

2005-07-07T05:25:45Z

Quineska: Added more information/tips, shortened warning

NOTE: this document is still a work in progress. No responsibility is accepted for any problems arising from inaccuracies.

== Introduction ==

Property lists are used throughout GNUstep to store defaults, program settings, application meta information, etc. MacOS X uses XML based property lists, but GNUstep uses another property list implementation also (TODO: history of this style of property list). Support for XML property lists is still wanting on some platforms; this situation should improve in the future.

They are composed of a "tree of arrays and dictionary's, which may be embedded inside each other for several layers. TODO: limits of embedding array/dictionaries inside each other.

== Dictionary ==

A dictionary is a list of key-value pairs, where each item in the list has a name associated with it (key) and another type (value), which could be another dictionary, an array or often a string. It programmatically corresponds to NSDictionary/NSMutableDictionary. They take the following syntax:

{
KeyName1 = Value1;
AnotherKeyName = "Value2";
Something = ( "ArrayItem1", "ArrayItem2", "ArrayItem3" );
Key4 = 0.10;
KeyFive = { Dictionary2Key1 = "Something"; AnotherKey = "Somethingelse"; };
}

As can be seen, each key-value pair is seperated by a semi-colon. Within the pair, the key is seperated from the value with an "equals" (=) sign. The key name is arbitrary, and not put in inverted commas (""). Shown above are: an unknown type (could be some sort of string - TODO), a string, an array, a number and another dictionary (respectively).

== Array ==

An array is a list of values, each of the same type (often arrays or dictionaries). Programmatically, it uses NSArray/NSMutableArray. It takes a syntax similar to the following:

( Value1, Value2, Value3, Value4 ) 
or 
(
Value1,
Value2,
Value3,
Value4
)

Each value is seperated by commas. By the technical definition of an array, each value is of the same type (but I believe GNUstep permits different types TODO: check this).

== Programming ==

GNUstep permits such property list files (denoted with a .plist extenstion) to be loaded and subsequently used in your applications or tools. NSDictionary and NSArray are used as representations of the above in the Foundation library (gnustep-base). Check the base API documentation for more information on working with these types programmatically.

Also, NSString can be used to turn property lists in string form to an equivalent programmatic tree. Again, see the API documentation for NSString (particularly propertyList method).

== Other tips ==

* Property lists are much like C programming, where newlines and spaces and tabs are not so important to parsing.
* Some examples of property lists may include:
** ~/GNUstep/System/Defaults/.GNUstepDefaults (this is your defaults file for software; be careful when editing)

[[Category:Development]]

Property Lists

2005-07-07T05:16:32Z

Quineska: Added better Array example.

NOTE: '''If anything below is dead wrong, please fix immediately. It is a work in progress. I am constructing this based on my experience with GNUstep, NOT any reference documentation that may exist. I don't warrant it fit for any purpose whatsoever, nor shall I take any responsibility for any issues or losses or problems etc that may arise from its use. (Christopher Armstrong, --[[User:Quineska|ChrisArmstrong]] 08:38, 6 Jul 2005 (CEST))'''

== Introduction ==

Property lists are used throughout GNUstep to store defaults, program settings, application meta information, etc. MacOS X uses XML based property lists, but GNUstep uses another property list implementation also (TODO: history of this style of property list).

They are composed of a "tree of arrays and dictionary's, which may be embedded inside each other for several layers. TODO: limits of embedding array/dictionaries inside each other.

== Dictionary ==

A dictionary is a list of key-value pairs, where each item in the list has a name associated with it (key) and another type (value), which could be another dictionary, an array or often a string. It programmatically corresponds to NSDictionary/NSMutableDictionary. They take the following syntax:

{
KeyName1 = Value1;
AnotherKeyName = "Value2";
Something = ( "ArrayItem1", "ArrayItem2", "ArrayItem3" );
Key4 = 0.10;
KeyFive = { Dictionary2Key1 = "Something"; AnotherKey = "Somethingelse"; };
}

As can be seen, each key-value pair is seperated by a semi-colon. Within the pair, the key is seperated from the value with an "equals" (=) sign. The key name is arbitrary, and not put in inverted commas (""). Shown above are a (unknown type, could be some sort of string - TODO), a string, an array, a number and another dictionary (respectively).

== Array ==

An array is a list of values, each of the same type (often arrays or dictionaries). Programmatically, it uses NSArray/NSMutableArray. It takes a syntax similar to the following:

( Value1, Value2, Value3, Value4 ) 
or 
(
Value1,
Value2,
Value3,
Value4
)

Each value is seperated by commas. By the technical definition of an array, each value is of the same type (but I believe GNUstep permits different types TODO: check this).

== Programming ==

GNUstep permits such property list files (denoted with a .plist extenstion) to be loaded and subsequently used in your applications or tools. NSDictionary and NSArray are used as representations of the above in the Foundation library (gnustep-base).

[[Category:Development]]

Developer Guides

2005-07-07T05:15:17Z

Quineska: Fixed link

== Coding for portability ==

Writing code that will compile and then run on different platforms can be surprisingly easy. [[Writing portable code]] describes some straight-forward steps to take to make your program easy to port to new platforms.

== Document based application design ==

One of the most common use-patterns of applications on modern platforms is that of document-based applications - applications which can have several active user-controlled contexts.

Some familar examples might be a word processor where the user may have multiple document windows concurrently, or a web browser which allows a user to have a number of different browser windows open at the same time.

[[Document based applications]] provides information and tips on how to code this style of application.

== Using property lists ==

A regular issue that programmers face is storing structured configuration information, and reading it back. GNUstep has a standard mechanism that can be used for this task, amongst others: [[Property Lists]].

Talk:Creating document based applications

2005-07-07T05:13:30Z

Quineska: Discussion added

Feel free to make corrections, fix grammatical/spelling anomalies, add extra information, etc. This is a first revision, so corrections are likely needed. --[[User:Quineska|ChrisArmstrong]] 07:13, 7 Jul 2005 (CEST)

Creating document based applications

2005-07-07T05:10:56Z

Quineska: /* The Makefile */

Note: First version; subject to further revisions and changes.
--[[User:Quineska|ChrisArmstrong]] 07:09, 7 Jul 2005 (CEST)

== Introduction ==

OpenStep can provide your application a document-based model. It helps to simplify the process of creating such applications. GNUstep is compatible with this paridgm as well; this document aims to provide an overview of what is required in the creation and design of such an application.

It is assumed you are familiar with GNUstep, and have some understanding as how to create Gorm's nib files, as well as some understanding of how they work.

Importantly, such applications have certain components that are required, and should be considered as part of their design. At a programmatic level, classes that will be used as part of the AppKit are:

==== NSDocument ====

This class is central to the OpenStep document based model. Such an application declares a new instance of a subclass of NSDocument for each “document” that is opened. It will be necessary to subclass NSDocument to implement this.

Each instance of your NSDocument subclass may have one or more windows associated with it. These are used as an interface for loading and saving a representation of your document type. Each window will have an “NSWindowController” instance associated with it, where NSDocument maintains a list of these.

==== NSDocumentController ====

This class acts a controller. It maintains a list of documents (instances of your NSDocument subclass) and is responsible for loading and instantiating new documents. It is usually not necessary to implement a subclass of this, but often it may be useful to implement special functionality (especially related to open documents as a whole).

==== NSWindowController ====

As mentioned above, NSWindowController instances are individually associated with one NSWindow instance, in such a way that a document maintains a list of window controllers that are reponsible for rendering the views associated with a document.

You will most likely not have to subclass NSWindowController. Instead, you associate a nib file (the Gorm output) with the subclass of NSDocument, and NSDocumentController will load this nib file for each document that is created or loaded.

For example, a text based application that is used for the editing of plain text files, may subclass NSDocument with a TextDocument class. Each instance of this class would have an NSWindowController instance associated with it, which in turn manages a window instance that is instantiated from a nib file. The NSDocumentController instance, as managed and instatiated by GNUstep, would be responsible for loading and saving documents in your application. It even prompts the user to save their documents when they try to quit the application.

== File Components ==

In building your application you will need to create a number of special files. From scratch, the following should be a rough guide to getting it working. These include the Makefile, your application's property list and the interface files.

=== The Makefile ===

For this type of application, no special makefile is needed: it just has to be a normal application. Project Builder should be able to spit out the required makefile and Gorm files that are needed for a generic application. I believe it is also capable of providing support for document-based applications. Otherwise use the following as a template:

'''GNUmakefile'''

include $(GNUSTEP_MAKEFILES)/common.make 
APP_NAME = DocumentApp 
DocumentApp_OBJC_FILES = 
MyDocument.m 
main.m 
DocumentApp_RESOURCES = \ 
Resources/Info-gnustep.plist \ 
Resources/DocumentApp.gorm \ 
Resources/MyDocument.gorm 
-include GNUmakefile.preamble 
include $(GNUSTEP_MAKEFILES)/application.make 
-include GNUmakefile.postamble 

For more information as to customising this file, as well as setting up compiler options for third party libraries and includes, see the GNUstep makefile manual.

===The application dictionary===

For those that have edited this file in their project before, it is a dictionary with various values entered. For our purposes, we need an array within the main dictionary, called "NSTypes". This is a array of unnamed dictionaries, with one dictionary for each type.

An entire example of this file, for a "theoretical" TextEdit application (please note that such an application does exist as an example application from Next I think, and again on MacOS X but I have constructed a much simpler version, used only for plain text files).

Taking a look at the single dictionary entry in the NSTypes array, the following key-value pairs are needed:
* '''NSDocumentClass:''' This is (string) the subclass name you use in your code, the "objective-c name" of your document subclass. This is used by NSDocumentController's default implementation to create instances of your document type.
* '''NSName:''' The generic file type (string). This is completely arbitrary, and can be anything you like. For the purpose of conventions, it may be more appropriate not to use the "NS" or "GS" prefix (the latter of which I not sure), and instead use either your own, or no prefix at all.
* '''NSHumanReadableName:''' The human readable name of your document type (string)? TODO: explain where this is used.
* '''NSUnixExtensions:''' An array of strings, each containing a file extension connected to this document type on "unix" platforms. TODO: explain how "unix" is interpreted by GNUstep.
* '''NSDOSExtensions:''' An array of strings, each containing a file extenstion connected to this document type on "DOS" platforms (could be loosely interpreted as any MS platforms GNUstep runs on, i.e. Windows 2000/XP).
* '''NSRole:''' A string, either "Viewer" or "Editor", depending on how your document operates on this file type.
* '''NSIcon:''' A icon name associated with this document type. TODO: Investigate how this works.

'''Info-gnustep.plist'''
{
ApplicationDescription = "A simple text editor for GNUstep.";
ApplicationName = TextEdit;
ApplicationRelease = 0.10;
Authors = ( "Christopher Armstrong" );
Copyright = "Copyright (C) 2005 Christopher Armstrong";
CopyrightDescription = "Released under GPL.";
FullVersionID = 0.10;
NSExecutable = TextEdit;
NSMainNibFile = TextEdit.gorm;
NSPrincipalClass = NSApplication;
NSRole = Application;
NSTypes = (
{
NSDocumentClass = "TextDocument";
NSName = "GSTextDocumentType";
NSHumanReadableName = "Text Document";
NSUnixExtensions = ( "txt", "" );
NSDOSExtensions = ( "txt" );
NSRole = Editor;
}
);
}

For more information on property list files, consult [[Property Lists]].

=== Interface files ===

Two interface files are needed: one for your main application, and another that will be instantiated with each instance of your document subclass. These both should be listed as resources in your makefile, (as shown the GNUmakefile example above). It may be helpful to name the document nib file after your class.

==== Application Interface File ====

The application one should just be a menu (though it could be more if necessary). When constructing it, take the following into account:

* Use a standard Gorm template for an Application.
* Delete the window instance in the "Objects" pane (unless you need a main window, in which case I don't know how to operate).
* Set NSOwner's class to "NSDocumentController" (this is the custom class option of NSOwner in the property inspector). This ensures openDocument, newDocument, etc. messages, as sent to NSFirst, get picked up by NSDocumentController. Do not instantiate it (I believe you can't anyway).
* If you intend to subclass NSDocumentController, subclass it in the Classes pane. To make sure that this class is instantiated and used, make sure you instantiate it in Gorm or in your main.m file, and set NSOwner to be your subclass.
* Drag a Document menu from the palette onto your main menu. This already has the proper linkage for each relevant message for a document setup to be directed to NSFirst. In the case of generic messages (such as openDocument:, not associated with any document instance), these are forwarded to the shared instance of NSDocumentController (see it's reference documentation). When a document is active, more specific messages (such as close: or saveDocument:) are forwarded to the relevant document instance of your NSDocument subclass.
* Add any appropriate menus such as "Info" and "Format" which may be relevant to your application.

==== Document Interface File(s) ====

The document interface file is (generically) a window containing the view(s) required for the implementation of one instance of your document type. For example, in the case of a TextDocument type, a window instance with a NSTextView drawn on it is used for each open window. This nib file is instantiated every time a person creates a new document (the newDocument: message goes to NSDocumentController) or opens an existing document (openDocument:).

You will need to:
* '''Subclass NSDocument''' with your document type in Gorm (this is done in a couple of ways, see [[Gorm_Manual#Custom_classes|custom classes]]).
* '''Set NSOwner:''' Set your subclass as NSOwner's Custom class (done using the Property inspector). DO NOT INSTANTIATE IT.

Another thing that you may want to consider is custom outlets. If you place certain views or controls on your window (including the window itself), you may want to refer to them directly in yout code, e.g. the NSTextView in our TextEdit example is accessed directly, so that we can save it's contents to a file. To enable this, we add outlets to our class (see [[Gorm_Manual#Custom_classes|custom classes]]). We then connected NSOwner to the appropriate controls/views, and selected the outlets in the Connections property inspector (see [[Gorm_Manual#Editing_the_interface|editing the interface]]).

== Code ==

Various things need to be done at a code level, to ensure that your NSDocument subclass is properly instantiated. This section aims to tell you what is necessary.

=== NSDocument subclass ===

When creating your subclass, you may have chosen to have Gorm create the class files. If not, you should create two files for your subclass: a header (.h) file and an implementation file (.m). The header file should take the following layout (we're using the TextEdit example again):

#ifndef TEXTDOCUMENT_H
#define TEXTDOCUMENT_H 
#include <AppKit/AppKit.h> 
@class NSDocument; 
/* The document type string, as specified in the property list [[#The_application_dictionary|NSTypes array]] */ 
NSString * GSTextDocumentType = "GSTextDocumentType";
@interface TextDocument : NSDocument
{
@protected
/* Outlets we added in our Gorm nib file */
id * textView;
}
/* Basic methods used for loading and saving document data (respectively). */
- (BOOL) loadDataRepresentation:(NSData*)representation ofType:(NSString*)type;
- (NSData*) dataRepresentationOfType: (NSString*)type; 
/* Information and events handling of GUI related changes */
- (NSString*) windowNibName;
- (void) windowControllerDidLoadNib:(NSWindowController*)windowController; 
@end 

Firstly, take note that we inherit from NSDocument. As a result, we need to override some methods for a basic (but working) implementation.

==== loadDataRepresentation:ofType: and dataRepresentationOfType: ====

The methods, loadDataRepresent:ofType: and dataRepresentationOfType: are used by NSDocumentController to load and save our files. The first method is called when the user trys to open a document (NSDocumentController gets the file name and copies it's data using an open panel). The method is passed the raw data in this file, as well as a string representing its type. It is important to note that this type string is the same one used in your property list. It is used by NSDocumentController to tell you what type it thinks you should open the data with. If this is not possible, or if there is an error trying to parse the data, your method returns FALSE/NO. Otherwise, you should store a local, meaningful representation of the data, which you can insert into your document window a little later (and return YES).

For example, in terms of the TextEdit example:
- (BOOL) loadDataRepresentation:(NSData*) representation ofType:(NSString*)type
{
/*Check type information */
if ([representation equalTo:GSTextDocumentType]==NO)
return NO;
/* Clean out our old representation if it still exists */
if (fileContents) RELEASE(fileContents); 
/* Allocate room for the new data, and try to initialise a string with it. */
self->fileContents = [NSString alloc];
fileContents = [fileContents initWithBytes: [representation bytes]
length: [representation length]
encoding: NSASCIIStringEncoding]; 
/* If this can't be done, return NO */
if (!fileContents)
return NO; 
/* Otherwise, set our TextView to the string data. */
[self->textView setString: fileContents];
return YES;
}

If this is not suffice, or if your program can open the data in a more efficient manner, it may be worth looking into overriding -initWithContentsOfFile:ofType: and -initWithContentsOfURL:ofType: (see the GUI manual for more details).

dataRepresentationOfType: is used to save the data. Your method is expected to return an instance of NSData that contains what should be saved to a file, for the type specified. Again, the ''type'' variable should be checked to ensure that you can write data of that type. Return nil if the file cannot be saved as that type.

For example:

- (NSData*) dataRepresentationOfType:(NSString*)type
{
if ([type equalTo:GSTextDocumentType]==NO)
return nil; 
NSData stringData = [[textView string] dataUsingEncoding:NSASCIIStringEncoding];
return stringData;
}

If a more sophisticated save implementation is needed, consult the documentation for information on the writeTo methods.

==== windowNibName ====

This method must be overriden to return the a string of the name of your nib file (without the file extention). More complex implementations will use other methods to load the interface files. TODO: information on what methods need to be overriden.

==== windowControllerDidLoadNib: ====

Use this method to add code that should be run as soon as ''windowController'' has been initialised. Your document may have many window controllers; each window controller taking possession of one window.

In the TextEdit example, this method is used to copy the fileContents object ivar to the text view. It otherwise initialises the document window.

Also note that you can override windowControllerWillLoadNib: to perform pre-nib loading initialisation.

==== makeWindowControllers ====

This is an optional method override, which must be used if you have multiple window controllers per document. It is responsible for creating each window controller from it's nib and then adding it to the document. Use the addWindowController: method.

==== Other considerations ====

* You need a way to notify NSDocument that your document has changed, so that NSDocumentController can enable the menu item to allow saving. This is done by a call to the updateChangeCount: method. For example, the TextDocument class adds itself as a delegate to the textView, for any notification of changes. It then calls updateChangeCount: in the delegate's method.

* You may also wish to add a close: method (not the close method already in NSDocument, see below) to respond to the menu item permitting your document to close. This could perform cleanup operations before a call to [super close] is called e.g.

- (void) close:(id)sender /* Note this is not the method found in NSDocument (they differ by a parameter) */
{
[self close];
}

=== NSDocumentController ===

This class can optionally be subclassed, to implement some specific functionality. For example, programs handling multiple document types may override newDocument: to create a window so that the user can select which document type to create.

You should use separate implementation files and add the .m file to GNUmakefile.

=== NSWindowController ===

This class can also be optionally subclassed, to implement functionality specific to a window controller for a document type. You may need to override makeWindowControllers: in the NSDocument subclass in order to make sure your specific window controller is instantiated.

You should use separate implemenatino files and add the .m file to GNUmakefile.

== Optional Additions ==

=== Custom NSDocumentController and NSWindowController implementations ===

See [[#NSWindowController|NSWindowController]] and [[#NSDocumentController|NSDocumentController]].

----

[[Category:Development]]

Creating document based applications

2005-07-07T05:09:19Z

Quineska: First revision complete

Note: First version; subject to further revisions and changes.
--[[User:Quineska|ChrisArmstrong]] 07:09, 7 Jul 2005 (CEST)

== Introduction ==

OpenStep can provide your application a document-based model. It helps to simplify the process of creating such applications. GNUstep is compatible with this paridgm as well; this document aims to provide an overview of what is required in the creation and design of such an application.

It is assumed you are familiar with GNUstep, and have some understanding as how to create Gorm's nib files, as well as some understanding of how they work.

Importantly, such applications have certain components that are required, and should be considered as part of their design. At a programmatic level, classes that will be used as part of the AppKit are:

==== NSDocument ====

This class is central to the OpenStep document based model. Such an application declares a new instance of a subclass of NSDocument for each “document” that is opened. It will be necessary to subclass NSDocument to implement this.

Each instance of your NSDocument subclass may have one or more windows associated with it. These are used as an interface for loading and saving a representation of your document type. Each window will have an “NSWindowController” instance associated with it, where NSDocument maintains a list of these.

==== NSDocumentController ====

This class acts a controller. It maintains a list of documents (instances of your NSDocument subclass) and is responsible for loading and instantiating new documents. It is usually not necessary to implement a subclass of this, but often it may be useful to implement special functionality (especially related to open documents as a whole).

==== NSWindowController ====

As mentioned above, NSWindowController instances are individually associated with one NSWindow instance, in such a way that a document maintains a list of window controllers that are reponsible for rendering the views associated with a document.

You will most likely not have to subclass NSWindowController. Instead, you associate a nib file (the Gorm output) with the subclass of NSDocument, and NSDocumentController will load this nib file for each document that is created or loaded.

For example, a text based application that is used for the editing of plain text files, may subclass NSDocument with a TextDocument class. Each instance of this class would have an NSWindowController instance associated with it, which in turn manages a window instance that is instantiated from a nib file. The NSDocumentController instance, as managed and instatiated by GNUstep, would be responsible for loading and saving documents in your application. It even prompts the user to save their documents when they try to quit the application.

== File Components ==

In building your application you will need to create a number of special files. From scratch, the following should be a rough guide to getting it working. These include the Makefile, your application's property list and the interface files.

=== The Makefile ===

For this type of application, no special makefile is needed: it just has to be a normal application. Project Builder should be able to spit out the required makefile and Gorm files that are needed for a generic application. Otherwise use the following as a template:

'''GNUmakefile'''

include $(GNUSTEP_MAKEFILES)/common.make 
APP_NAME = DocumentApp 
DocumentApp_OBJC_FILES = 
MyDocument.m 
main.m 
DocumentApp_RESOURCES = \ 
Resources/Info-gnustep.plist \ 
Resources/DocumentApp.gorm \ 
Resources/MyDocument.gorm 
-include GNUmakefile.preamble 
include $(GNUSTEP_MAKEFILES)/application.make 
-include GNUmakefile.postamble 

For more information as to customising this file, as well as setting up compiler options for third party libraries and includes, see the GNUstep makefile manual.

===The application dictionary===

For those that have edited this file in their project before, it is a dictionary with various values entered. For our purposes, we need an array within the main dictionary, called "NSTypes". This is a array of unnamed dictionaries, with one dictionary for each type.

An entire example of this file, for a "theoretical" TextEdit application (please note that such an application does exist as an example application from Next I think, and again on MacOS X but I have constructed a much simpler version, used only for plain text files).

Taking a look at the single dictionary entry in the NSTypes array, the following key-value pairs are needed:
* '''NSDocumentClass:''' This is (string) the subclass name you use in your code, the "objective-c name" of your document subclass. This is used by NSDocumentController's default implementation to create instances of your document type.
* '''NSName:''' The generic file type (string). This is completely arbitrary, and can be anything you like. For the purpose of conventions, it may be more appropriate not to use the "NS" or "GS" prefix (the latter of which I not sure), and instead use either your own, or no prefix at all.
* '''NSHumanReadableName:''' The human readable name of your document type (string)? TODO: explain where this is used.
* '''NSUnixExtensions:''' An array of strings, each containing a file extension connected to this document type on "unix" platforms. TODO: explain how "unix" is interpreted by GNUstep.
* '''NSDOSExtensions:''' An array of strings, each containing a file extenstion connected to this document type on "DOS" platforms (could be loosely interpreted as any MS platforms GNUstep runs on, i.e. Windows 2000/XP).
* '''NSRole:''' A string, either "Viewer" or "Editor", depending on how your document operates on this file type.
* '''NSIcon:''' A icon name associated with this document type. TODO: Investigate how this works.

'''Info-gnustep.plist'''
{
ApplicationDescription = "A simple text editor for GNUstep.";
ApplicationName = TextEdit;
ApplicationRelease = 0.10;
Authors = ( "Christopher Armstrong" );
Copyright = "Copyright (C) 2005 Christopher Armstrong";
CopyrightDescription = "Released under GPL.";
FullVersionID = 0.10;
NSExecutable = TextEdit;
NSMainNibFile = TextEdit.gorm;
NSPrincipalClass = NSApplication;
NSRole = Application;
NSTypes = (
{
NSDocumentClass = "TextDocument";
NSName = "GSTextDocumentType";
NSHumanReadableName = "Text Document";
NSUnixExtensions = ( "txt", "" );
NSDOSExtensions = ( "txt" );
NSRole = Editor;
}
);
}

For more information on property list files, consult [[Property Lists]].

=== Interface files ===

Two interface files are needed: one for your main application, and another that will be instantiated with each instance of your document subclass. These both should be listed as resources in your makefile, (as shown the GNUmakefile example above). It may be helpful to name the document nib file after your class.

==== Application Interface File ====

The application one should just be a menu (though it could be more if necessary). When constructing it, take the following into account:

* Use a standard Gorm template for an Application.
* Delete the window instance in the "Objects" pane (unless you need a main window, in which case I don't know how to operate).
* Set NSOwner's class to "NSDocumentController" (this is the custom class option of NSOwner in the property inspector). This ensures openDocument, newDocument, etc. messages, as sent to NSFirst, get picked up by NSDocumentController. Do not instantiate it (I believe you can't anyway).
* If you intend to subclass NSDocumentController, subclass it in the Classes pane. To make sure that this class is instantiated and used, make sure you instantiate it in Gorm or in your main.m file, and set NSOwner to be your subclass.
* Drag a Document menu from the palette onto your main menu. This already has the proper linkage for each relevant message for a document setup to be directed to NSFirst. In the case of generic messages (such as openDocument:, not associated with any document instance), these are forwarded to the shared instance of NSDocumentController (see it's reference documentation). When a document is active, more specific messages (such as close: or saveDocument:) are forwarded to the relevant document instance of your NSDocument subclass.
* Add any appropriate menus such as "Info" and "Format" which may be relevant to your application.

==== Document Interface File(s) ====

The document interface file is (generically) a window containing the view(s) required for the implementation of one instance of your document type. For example, in the case of a TextDocument type, a window instance with a NSTextView drawn on it is used for each open window. This nib file is instantiated every time a person creates a new document (the newDocument: message goes to NSDocumentController) or opens an existing document (openDocument:).

You will need to:
* '''Subclass NSDocument''' with your document type in Gorm (this is done in a couple of ways, see [[Gorm_Manual#Custom_classes|custom classes]]).
* '''Set NSOwner:''' Set your subclass as NSOwner's Custom class (done using the Property inspector). DO NOT INSTANTIATE IT.

Another thing that you may want to consider is custom outlets. If you place certain views or controls on your window (including the window itself), you may want to refer to them directly in yout code, e.g. the NSTextView in our TextEdit example is accessed directly, so that we can save it's contents to a file. To enable this, we add outlets to our class (see [[Gorm_Manual#Custom_classes|custom classes]]). We then connected NSOwner to the appropriate controls/views, and selected the outlets in the Connections property inspector (see [[Gorm_Manual#Editing_the_interface|editing the interface]]).

== Code ==

Various things need to be done at a code level, to ensure that your NSDocument subclass is properly instantiated. This section aims to tell you what is necessary.

=== NSDocument subclass ===

When creating your subclass, you may have chosen to have Gorm create the class files. If not, you should create two files for your subclass: a header (.h) file and an implementation file (.m). The header file should take the following layout (we're using the TextEdit example again):

#ifndef TEXTDOCUMENT_H
#define TEXTDOCUMENT_H 
#include <AppKit/AppKit.h> 
@class NSDocument; 
/* The document type string, as specified in the property list [[#The_application_dictionary|NSTypes array]] */ 
NSString * GSTextDocumentType = "GSTextDocumentType";
@interface TextDocument : NSDocument
{
@protected
/* Outlets we added in our Gorm nib file */
id * textView;
}
/* Basic methods used for loading and saving document data (respectively). */
- (BOOL) loadDataRepresentation:(NSData*)representation ofType:(NSString*)type;
- (NSData*) dataRepresentationOfType: (NSString*)type; 
/* Information and events handling of GUI related changes */
- (NSString*) windowNibName;
- (void) windowControllerDidLoadNib:(NSWindowController*)windowController; 
@end 

Firstly, take note that we inherit from NSDocument. As a result, we need to override some methods for a basic (but working) implementation.

==== loadDataRepresentation:ofType: and dataRepresentationOfType: ====

The methods, loadDataRepresent:ofType: and dataRepresentationOfType: are used by NSDocumentController to load and save our files. The first method is called when the user trys to open a document (NSDocumentController gets the file name and copies it's data using an open panel). The method is passed the raw data in this file, as well as a string representing its type. It is important to note that this type string is the same one used in your property list. It is used by NSDocumentController to tell you what type it thinks you should open the data with. If this is not possible, or if there is an error trying to parse the data, your method returns FALSE/NO. Otherwise, you should store a local, meaningful representation of the data, which you can insert into your document window a little later (and return YES).

For example, in terms of the TextEdit example:
- (BOOL) loadDataRepresentation:(NSData*) representation ofType:(NSString*)type
{
/*Check type information */
if ([representation equalTo:GSTextDocumentType]==NO)
return NO;
/* Clean out our old representation if it still exists */
if (fileContents) RELEASE(fileContents); 
/* Allocate room for the new data, and try to initialise a string with it. */
self->fileContents = [NSString alloc];
fileContents = [fileContents initWithBytes: [representation bytes]
length: [representation length]
encoding: NSASCIIStringEncoding]; 
/* If this can't be done, return NO */
if (!fileContents)
return NO; 
/* Otherwise, set our TextView to the string data. */
[self->textView setString: fileContents];
return YES;
}

If this is not suffice, or if your program can open the data in a more efficient manner, it may be worth looking into overriding -initWithContentsOfFile:ofType: and -initWithContentsOfURL:ofType: (see the GUI manual for more details).

dataRepresentationOfType: is used to save the data. Your method is expected to return an instance of NSData that contains what should be saved to a file, for the type specified. Again, the ''type'' variable should be checked to ensure that you can write data of that type. Return nil if the file cannot be saved as that type.

For example:

- (NSData*) dataRepresentationOfType:(NSString*)type
{
if ([type equalTo:GSTextDocumentType]==NO)
return nil; 
NSData stringData = [[textView string] dataUsingEncoding:NSASCIIStringEncoding];
return stringData;
}

If a more sophisticated save implementation is needed, consult the documentation for information on the writeTo methods.

==== windowNibName ====

This method must be overriden to return the a string of the name of your nib file (without the file extention). More complex implementations will use other methods to load the interface files. TODO: information on what methods need to be overriden.

==== windowControllerDidLoadNib: ====

Use this method to add code that should be run as soon as ''windowController'' has been initialised. Your document may have many window controllers; each window controller taking possession of one window.

In the TextEdit example, this method is used to copy the fileContents object ivar to the text view. It otherwise initialises the document window.

Also note that you can override windowControllerWillLoadNib: to perform pre-nib loading initialisation.

==== makeWindowControllers ====

This is an optional method override, which must be used if you have multiple window controllers per document. It is responsible for creating each window controller from it's nib and then adding it to the document. Use the addWindowController: method.

==== Other considerations ====

* You need a way to notify NSDocument that your document has changed, so that NSDocumentController can enable the menu item to allow saving. This is done by a call to the updateChangeCount: method. For example, the TextDocument class adds itself as a delegate to the textView, for any notification of changes. It then calls updateChangeCount: in the delegate's method.

* You may also wish to add a close: method (not the close method already in NSDocument, see below) to respond to the menu item permitting your document to close. This could perform cleanup operations before a call to [super close] is called e.g.

- (void) close:(id)sender /* Note this is not the method found in NSDocument (they differ by a parameter) */
{
[self close];
}

=== NSDocumentController ===

This class can optionally be subclassed, to implement some specific functionality. For example, programs handling multiple document types may override newDocument: to create a window so that the user can select which document type to create.

You should use separate implementation files and add the .m file to GNUmakefile.

=== NSWindowController ===

This class can also be optionally subclassed, to implement functionality specific to a window controller for a document type. You may need to override makeWindowControllers: in the NSDocument subclass in order to make sure your specific window controller is instantiated.

You should use separate implemenatino files and add the .m file to GNUmakefile.

== Optional Additions ==

=== Custom NSDocumentController and NSWindowController implementations ===

See [[#NSWindowController|NSWindowController]] and [[#NSDocumentController|NSDocumentController]].

----

[[Category:Development]]

Creating document based applications

2005-07-07T04:39:13Z

Quineska: /* loadDataRepresentation:ofType: and dataRepresentationOfType: */

Note: this is a work in progress. Please bear with me as I add further information.
--[[User:Quineska|ChrisArmstrong]] 08:33, 5 Jul 2005 (CEST)

== Introduction ==

OpenStep can provide your application a document-based model. It helps to simplify the process of creating such applications. GNUstep is compatible with this paridgm as well; this document aims to provide an overview of what is required in the creation and design of such an application.

It is assumed you are familiar with GNUstep, and have some understanding as how to create Gorm's nib files, as well as some understanding of how they work.

Importantly, such applications have certain components that are required, and should be considered as part of their design. At a programmatic level, classes that will be used as part of the AppKit are:

==== NSDocument ====

This class is central to the OpenStep document based model. Such an application declares a new instance of a subclass of NSDocument for each “document” that is opened. It will be necessary to subclass NSDocument to implement this.

Each instance of your NSDocument subclass may have one or more windows associated with it. These are used as an interface for loading and saving a representation of your document type. Each window will have an “NSWindowController” instance associated with it, where NSDocument maintains a list of these.

==== NSDocumentController ====

This class acts a controller. It maintains a list of documents (instances of your NSDocument subclass) and is responsible for loading and instantiating new documents. It is usually not necessary to implement a subclass of this, but often it may be useful to implement special functionality (especially related to open documents as a whole).

==== NSWindowController ====

As mentioned above, NSWindowController instances are individually associated with one NSWindow instance, in such a way that a document maintains a list of window controllers that are reponsible for rendering the views associated with a document.

You will most likely not have to subclass NSWindowController. Instead, you associate a nib file (the Gorm output) with the subclass of NSDocument, and NSDocumentController will load this nib file for each document that is created or loaded.

For example, a text based application that is used for the editing of plain text files, may subclass NSDocument with a TextDocument class. Each instance of this class would have an NSWindowController instance associated with it, which in turn manages a window instance that is instantiated from a nib file. The NSDocumentController instance, as managed and instatiated by GNUstep, would be responsible for loading and saving documents in your application. It even prompts the user to save their documents when they try to quit the application.

== File Components ==

In building your application you will need to create a number of special files. From scratch, the following should be a rough guide to getting it working. These include the Makefile, your application's property list and the interface files.

=== The Makefile ===

For this type of application, no special makefile is needed: it just has to be a normal application. Project Builder should be able to spit out the required makefile and Gorm files that are needed for a generic application. Otherwise use the following as a template:

'''GNUmakefile'''

include $(GNUSTEP_MAKEFILES)/common.make 
APP_NAME = DocumentApp 
DocumentApp_OBJC_FILES = 
MyDocument.m 
main.m 
DocumentApp_RESOURCES = \ 
Resources/Info-gnustep.plist \ 
Resources/DocumentApp.gorm \ 
Resources/MyDocument.gorm 
-include GNUmakefile.preamble 
include $(GNUSTEP_MAKEFILES)/application.make 
-include GNUmakefile.postamble 

For more information as to customising this file, as well as setting up compiler options for third party libraries and includes, see the GNUstep makefile manual.

=== The application dictionary - Info-gnustep.plist ===

For those that have edited this file in their project before, it is a dictionary with various values entered. For our purposes, we need an array within the main dictionary, called "NSTypes". This is a array of unnamed dictionaries, with one dictionary for each type.

An entire example of this file, for a "theoretical" TextEdit application (please note that such an application does exist as an example application from Next I think, and again on MacOS X but I have constructed a much simpler version, used only for plain text files).

Taking a look at the single dictionary entry in the NSTypes array, the following key-value pairs are needed:
* '''NSDocumentClass:''' This is (string) the subclass name you use in your code, the "objective-c name" of your document subclass. This is used by NSDocumentController's default implementation to create instances of your document type.
* '''NSName:''' The generic file type (string). This is completely arbitrary, and can be anything you like. For the purpose of conventions, it may be more appropriate not to use the "NS" or "GS" prefix (the latter of which I not sure), and instead use either your own, or no prefix at all.
* '''NSHumanReadableName:''' The human readable name of your document type (string)? TODO: explain where this is used.
* '''NSUnixExtensions:''' An array of strings, each containing a file extension connected to this document type on "unix" platforms. TODO: explain how "unix" is interpreted by GNUstep.
* '''NSDOSExtensions:''' An array of strings, each containing a file extenstion connected to this document type on "DOS" platforms (could be loosely interpreted as any MS platforms GNUstep runs on, i.e. Windows 2000/XP).
* '''NSRole:''' A string, either "Viewer" or "Editor", depending on how your document operates on this file type.
* '''NSIcon:''' A icon name associated with this document type. TODO: Investigate how this works.

'''Info-gnustep.plist'''
{
ApplicationDescription = "A simple text editor for GNUstep.";
ApplicationName = TextEdit;
ApplicationRelease = 0.10;
Authors = ( "Christopher Armstrong <quineska@gamebox.net" );
Copyright = "Copyright (C) 2005 Christopher Armstrong";
CopyrightDescription = "Released under GPL.";
FullVersionID = 0.10;
NSExecutable = TextEdit;
NSMainNibFile = TextEdit.gorm;
NSPrincipalClass = NSApplication;
NSRole = Application;
NSTypes = (
{
NSDocumentClass = "TextDocument";
NSName = "GSTextDocumentType";
NSHumanReadableName = "Text Document";
NSUnixExtensions = ( "txt", "" );
NSDOSExtensions = ( "txt" );
NSRole = Editor;
}
);
}

For more information on property list files, consult [[Property Lists]].

=== Interface file ===

Two interface files are needed: one for your main application, and another that will be instantiated with each instance of your document subclass. These both should be listed as resources in your makefile, (as shown the GNUmakefile example above). It may be helpful to name the document nib file after your class.

==== Application Interface File ====

The application one should just be a menu (though it could be more if necessary). When constructing it, take the following into account:

* Use a standard Gorm template for an Application.
* Delete the window instance in the "Objects" pane (unless you need a main window, in which case I don't know how to operate).
* Set NSOwner's class to "NSDocumentController" (this is the custom class option of NSOwner in the property inspector). This ensures openDocument, newDocument, etc. messages, as sent to NSFirst, get picked up by NSDocumentController. Do not instantiate it (I believe you can't anyway).
* If you intend to subclass NSDocumentController, subclass it in the Classes pane. To make sure that this class is instantiated and used, make sure you instantiate it in Gorm or in your main.m file, and set NSOwner to be your subclass.
* Drag a Document menu from the palette onto your main menu. This already has the proper linkage for each relevant message for a document setup to be directed to NSFirst. In the case of generic messages (such as openDocument:, not associated with any document instance), these are forwarded to the shared instance of NSDocumentController (see it's reference documentation). When a document is active, more specific messages (such as close: or saveDocument:) are forwarded to the relevant document instance of your NSDocument subclass.
* Add any appropriate menus such as "Info" and "Format" which may be relevant to your application.

==== Document Interface File ====

The document interface file is (generically) a window containing the view(s) required for the implementation of one instance of your document type. For example, in the case of a TextDocument type, a window instance with a NSTextView drawn on it is used for each open window. This nib file is instantiated every time a person creates a new document (the newDocument: message goes to NSDocumentController) or opens an existing document (openDocument:).

You will need to:
* '''Subclass NSDocument''' with your document type in Gorm (this is done in a couple of ways, see [[Gorm_Manual#Custom_classes|custom classes]]).
* '''Set NSOwner:''' Set your subclass as NSOwner's Custom class (done using the Property inspector). DO NOT INSTANTIATE IT.

Another thing that you may want to consider is custom outlets. If you place certain views or controls on your window (including the window itself), you may want to refer to them directly in yout code, e.g. the NSTextView in our TextEdit example is accessed directly, so that we can save it's contents to a file. To enable this, we add outlets to our class (see [[Gorm_Manual#Custom_classes|custom classes]]). We then connected NSOwner to the appropriate controls/views, and selected the outlets in the Connections property inspector (see [[Gorm_Manual#Editing_the_interface|editing the interface]]).

== Code ==

Various things need to be done at a code level, to ensure that your NSDocument subclass is properly instantiated. This section aims to tell you what is necessary.

=== NSDocument subclass ===

When creating your subclass, you may have chosen to have Gorm create the class files. If not, you should create two files for your subclass: a header (.h) file and an implementation file (.m). The header file should take the following layout (we're using the TextEdit example again):

#ifndef TEXTDOCUMENT_H
#define TEXTDOCUMENT_H 
#include <AppKit/AppKit.h> 
@class NSDocument; 
@interface TextDocument : NSDocument
{
@protected
/* Outlets we added in our Gorm nib file */
id * textView;
}
/* Basic methods used for loading and saving document data (respectively). */
- (BOOL) loadDataRepresentation:(NSData*)representation ofType:(NSString*)type;
- (NSData*) dataRepresentationOfType: (NSString*)type; 
/* Information and events handling of GUI related changes */
- (NSString*) windowNibName;
- (void) windowControllerDidLoadNib:(NSWindowController*)windowController; 
@end 

Firstly, take note that we inherit from NSDocument. As a result, we need to override some methods for a basic (but working) implementation.

==== loadDataRepresentation:ofType: and dataRepresentationOfType: ====

The methods, loadDataRepresent:ofType: and dataRepresentationOfType: are used by NSDocumentController to load and save our files. The first method is called when the user trys to open a document (NSDocumentController gets the file name and copies it's data using an open panel). The method is passed the raw data in this file, as well as a string representing its type. It is important to note that this type string is the same one used in your property list. It is used by NSDocumentController to tell you what type it thinks you should open the data with. If this is not possible, or if there is an error trying to parse the data, your method returns FALSE/NO. Otherwise, you should store a local, meaningful representation of the data, which you can insert into your document window a little later (and return YES).

For example, in terms of the TextEdit example:
- (BOOL) loadDataRepresentation:(NSData*) representation ofType:(NSString*)type
{
/*Check type information */
if ([representation equalTo:GSTextDocumentType]==NO)
return NO;
/* Clean out our old representation if it still exists */
if (fileContents) RELEASE(fileContents); 
/* Allocate room for the new data, and try to initialise a string with it. */
self->fileContents = [NSString alloc];
fileContents = [fileContents initWithBytes: [representation bytes]
length: [representation length]
encoding: NSASCIIStringEncoding]; 
/* If this can't be done, return NO */
if (!fileContents)
return NO; 
/* Otherwise, set our TextView to the string data. */
[self->textView setString: fileContents];
return YES;
}

If this is not suffice, or if your program can open the data in a more efficient manner, it may be worth looking into overriding -initWithContentsOfFile:ofType: and -initWithContentsOfURL:ofType: (see the GUI manual for more details).

dataRepresentationOfType: is used to save the data. Your method is expected to return an instance of NSData that contains what should be saved to a file, for the type specified. Again, the ''type'' variable should be checked to ensure that you can write data of that type. Return nil if the file cannot be saved as that type.

For example:

- (NSData*) dataRepresentationOfType:(NSString*)type
{
if ([type equalTo:GSTextDocumentType]==NO)
return nil; 
NSData stringData = [[textView string] dataUsingEncoding:NSASCIIStringEncoding];
return stringData;
}

If a more sophisticated save implementation is needed, consult the documentation for information on the writeTo methods.

==== windowNibName ====

This method must be overriden to return the name of your nib file. More complex implementations will use other methods to load the interface files. TODO: information on what methods need to be overriden.

[[Category:Development]]

Creating document based applications

2005-07-07T01:15:09Z

Quineska: /* windowNibName */

Note: this is a work in progress. Please bear with me as I add further information.
--[[User:Quineska|ChrisArmstrong]] 08:33, 5 Jul 2005 (CEST)

== Introduction ==

OpenStep can provide your application a document-based model. It helps to simplify the process of creating such applications. GNUstep is compatible with this paridgm as well; this document aims to provide an overview of what is required in the creation and design of such an application.

It is assumed you are familiar with GNUstep, and have some understanding as how to create Gorm's nib files, as well as some understanding of how they work.

Importantly, such applications have certain components that are required, and should be considered as part of their design. At a programmatic level, classes that will be used as part of the AppKit are:

==== NSDocument ====

This class is central to the OpenStep document based model. Such an application declares a new instance of a subclass of NSDocument for each “document” that is opened. It will be necessary to subclass NSDocument to implement this.

Each instance of your NSDocument subclass may have one or more windows associated with it. These are used as an interface for loading and saving a representation of your document type. Each window will have an “NSWindowController” instance associated with it, where NSDocument maintains a list of these.

==== NSDocumentController ====

This class acts a controller. It maintains a list of documents (instances of your NSDocument subclass) and is responsible for loading and instantiating new documents. It is usually not necessary to implement a subclass of this, but often it may be useful to implement special functionality (especially related to open documents as a whole).

==== NSWindowController ====

As mentioned above, NSWindowController instances are individually associated with one NSWindow instance, in such a way that a document maintains a list of window controllers that are reponsible for rendering the views associated with a document.

You will most likely not have to subclass NSWindowController. Instead, you associate a nib file (the Gorm output) with the subclass of NSDocument, and NSDocumentController will load this nib file for each document that is created or loaded.

For example, a text based application that is used for the editing of plain text files, may subclass NSDocument with a TextDocument class. Each instance of this class would have an NSWindowController instance associated with it, which in turn manages a window instance that is instantiated from a nib file. The NSDocumentController instance, as managed and instatiated by GNUstep, would be responsible for loading and saving documents in your application. It even prompts the user to save their documents when they try to quit the application.

== File Components ==

In building your application you will need to create a number of special files. From scratch, the following should be a rough guide to getting it working. These include the Makefile, your application's property list and the interface files.

=== The Makefile ===

For this type of application, no special makefile is needed: it just has to be a normal application. Project Builder should be able to spit out the required makefile and Gorm files that are needed for a generic application. Otherwise use the following as a template:

'''GNUmakefile'''

include $(GNUSTEP_MAKEFILES)/common.make 
APP_NAME = DocumentApp 
DocumentApp_OBJC_FILES = 
MyDocument.m 
main.m 
DocumentApp_RESOURCES = \ 
Resources/Info-gnustep.plist \ 
Resources/DocumentApp.gorm \ 
Resources/MyDocument.gorm 
-include GNUmakefile.preamble 
include $(GNUSTEP_MAKEFILES)/application.make 
-include GNUmakefile.postamble 

For more information as to customising this file, as well as setting up compiler options for third party libraries and includes, see the GNUstep makefile manual.

=== The application dictionary - Info-gnustep.plist ===

For those that have edited this file in their project before, it is a dictionary with various values entered. For our purposes, we need an array within the main dictionary, called "NSTypes". This is a array of unnamed dictionaries, with one dictionary for each type.

An entire example of this file, for a "theoretical" TextEdit application (please note that such an application does exist as an example application from Next I think, and again on MacOS X but I have constructed a much simpler version, used only for plain text files).

Taking a look at the single dictionary entry in the NSTypes array, the following key-value pairs are needed:
* '''NSDocumentClass:''' This is (string) the subclass name you use in your code, the "objective-c name" of your document subclass. This is used by NSDocumentController's default implementation to create instances of your document type.
* '''NSName:''' The generic file type (string). This is completely arbitrary, and can be anything you like. For the purpose of conventions, it may be more appropriate not to use the "NS" or "GS" prefix (the latter of which I not sure), and instead use either your own, or no prefix at all.
* '''NSHumanReadableName:''' The human readable name of your document type (string)? TODO: explain where this is used.
* '''NSUnixExtensions:''' An array of strings, each containing a file extension connected to this document type on "unix" platforms. TODO: explain how "unix" is interpreted by GNUstep.
* '''NSDOSExtensions:''' An array of strings, each containing a file extenstion connected to this document type on "DOS" platforms (could be loosely interpreted as any MS platforms GNUstep runs on, i.e. Windows 2000/XP).
* '''NSRole:''' A string, either "Viewer" or "Editor", depending on how your document operates on this file type.
* '''NSIcon:''' A icon name associated with this document type. TODO: Investigate how this works.

'''Info-gnustep.plist'''
{
ApplicationDescription = "A simple text editor for GNUstep.";
ApplicationName = TextEdit;
ApplicationRelease = 0.10;
Authors = ( "Christopher Armstrong <quineska@gamebox.net" );
Copyright = "Copyright (C) 2005 Christopher Armstrong";
CopyrightDescription = "Released under GPL.";
FullVersionID = 0.10;
NSExecutable = TextEdit;
NSMainNibFile = TextEdit.gorm;
NSPrincipalClass = NSApplication;
NSRole = Application;
NSTypes = (
{
NSDocumentClass = "TextDocument";
NSName = "GSTextDocumentType";
NSHumanReadableName = "Text Document";
NSUnixExtensions = ( "txt", "" );
NSDOSExtensions = ( "txt" );
NSRole = Editor;
}
);
}

For more information on property list files, consult [[Property Lists]].

=== Interface file ===

Two interface files are needed: one for your main application, and another that will be instantiated with each instance of your document subclass. These both should be listed as resources in your makefile, (as shown the GNUmakefile example above). It may be helpful to name the document nib file after your class.

==== Application Interface File ====

The application one should just be a menu (though it could be more if necessary). When constructing it, take the following into account:

* Use a standard Gorm template for an Application.
* Delete the window instance in the "Objects" pane (unless you need a main window, in which case I don't know how to operate).
* Set NSOwner's class to "NSDocumentController" (this is the custom class option of NSOwner in the property inspector). This ensures openDocument, newDocument, etc. messages, as sent to NSFirst, get picked up by NSDocumentController. Do not instantiate it (I believe you can't anyway).
* If you intend to subclass NSDocumentController, subclass it in the Classes pane. To make sure that this class is instantiated and used, make sure you instantiate it in Gorm or in your main.m file, and set NSOwner to be your subclass.
* Drag a Document menu from the palette onto your main menu. This already has the proper linkage for each relevant message for a document setup to be directed to NSFirst. In the case of generic messages (such as openDocument:, not associated with any document instance), these are forwarded to the shared instance of NSDocumentController (see it's reference documentation). When a document is active, more specific messages (such as close: or saveDocument:) are forwarded to the relevant document instance of your NSDocument subclass.
* Add any appropriate menus such as "Info" and "Format" which may be relevant to your application.

==== Document Interface File ====

The document interface file is (generically) a window containing the view(s) required for the implementation of one instance of your document type. For example, in the case of a TextDocument type, a window instance with a NSTextView drawn on it is used for each open window. This nib file is instantiated every time a person creates a new document (the newDocument: message goes to NSDocumentController) or opens an existing document (openDocument:).

You will need to:
* '''Subclass NSDocument''' with your document type in Gorm (this is done in a couple of ways, see [[Gorm_Manual#Custom_classes|custom classes]]).
* '''Set NSOwner:''' Set your subclass as NSOwner's Custom class (done using the Property inspector). DO NOT INSTANTIATE IT.

Another thing that you may want to consider is custom outlets. If you place certain views or controls on your window (including the window itself), you may want to refer to them directly in yout code, e.g. the NSTextView in our TextEdit example is accessed directly, so that we can save it's contents to a file. To enable this, we add outlets to our class (see [[Gorm_Manual#Custom_classes|custom classes]]). We then connected NSOwner to the appropriate controls/views, and selected the outlets in the Connections property inspector (see [[Gorm_Manual#Editing_the_interface|editing the interface]]).

== Code ==

Various things need to be done at a code level, to ensure that your NSDocument subclass is properly instantiated. This section aims to tell you what is necessary.

=== NSDocument subclass ===

When creating your subclass, you may have chosen to have Gorm create the class files. If not, you should create two files for your subclass: a header (.h) file and an implementation file (.m). The header file should take the following layout (we're using the TextEdit example again):

#ifndef TEXTDOCUMENT_H
#define TEXTDOCUMENT_H 
#include <AppKit/AppKit.h> 
@class NSDocument; 
@interface TextDocument : NSDocument
{
@protected
/* Outlets we added in our Gorm nib file */
id * textView;
}
/* Basic methods used for loading and saving document data (respectively). */
- (BOOL) loadDataRepresentation:(NSData*)representation ofType:(NSString*)type;
- (NSData*) dataRepresentationOfType: (NSString*)type; 
/* Information and events handling of GUI related changes */
- (NSString*) windowNibName;
- (void) windowControllerDidLoadNib:(NSWindowController*)windowController; 
@end 

Firstly, take note that we inherit from NSDocument. As a result, we need to override some methods for a basic (but working) implementation.

==== loadDataRepresentation:ofType: and dataRepresentationOfType: ====

The methods, loadDataRepresent:ofType: and dataRepresentationOfType: are used by NSDocumentController to load and save our files. The first method is called when the user trys to open a document (NSDocumentController gets the file name and copies it's data using an open panel). The method is passed the raw data in this file, as well as a string representing its type. It is important to note that this type string is the same one used in your property list. It is used by NSDocumentController to tell you what type it thinks you should open the data with. If this is not possible, or if there is an error trying to parse the data, your method returns FALSE/NO. Otherwise, you should store a local, meaningful representation of the data, which you can insert into your document window a little later (and return YES).

For example, in terms of the TextEdit example:
- (BOOL) loadDataRepresentation:(NSData*) representation ofType:(NSString*)type
{
/* Clean out our old representation if it still exists */
if (fileContents) RELEASE(fileContents); 
/* Allocate room for the new data, and try to initialise a string with it. */
self->fileContents = [NSString alloc];
fileContents = [fileContents initWithBytes: [representation bytes]
length: [representation length]
encoding: NSASCIIStringEncoding]; 
/* If this can't be done, return NO */
if (!fileContents)
return NO; 
/* Otherwise, set our TextView to the string data. */
[self->textView setString: fileContents];
return YES;
}

If this is not suffice, or if your program can open the data in a more efficient manner, it may be worth looking into overriding -initWithContentsOfFile:ofType: and -initWithContentsOfURL:ofType: (see the GUI manual for more details).

==== windowNibName ====

This method must be overriden to return the name of your nib file. More complex implementations will use other methods to load the interface files. TODO: information on what methods need to be overriden.

[[Category:Development]]

Creating document based applications

2005-07-07T01:14:45Z

Quineska: Added Code section (plus info) and completed file components section

Note: this is a work in progress. Please bear with me as I add further information.
--[[User:Quineska|ChrisArmstrong]] 08:33, 5 Jul 2005 (CEST)

== Introduction ==

OpenStep can provide your application a document-based model. It helps to simplify the process of creating such applications. GNUstep is compatible with this paridgm as well; this document aims to provide an overview of what is required in the creation and design of such an application.

It is assumed you are familiar with GNUstep, and have some understanding as how to create Gorm's nib files, as well as some understanding of how they work.

Importantly, such applications have certain components that are required, and should be considered as part of their design. At a programmatic level, classes that will be used as part of the AppKit are:

==== NSDocument ====

This class is central to the OpenStep document based model. Such an application declares a new instance of a subclass of NSDocument for each “document” that is opened. It will be necessary to subclass NSDocument to implement this.

Each instance of your NSDocument subclass may have one or more windows associated with it. These are used as an interface for loading and saving a representation of your document type. Each window will have an “NSWindowController” instance associated with it, where NSDocument maintains a list of these.

==== NSDocumentController ====

This class acts a controller. It maintains a list of documents (instances of your NSDocument subclass) and is responsible for loading and instantiating new documents. It is usually not necessary to implement a subclass of this, but often it may be useful to implement special functionality (especially related to open documents as a whole).

==== NSWindowController ====

As mentioned above, NSWindowController instances are individually associated with one NSWindow instance, in such a way that a document maintains a list of window controllers that are reponsible for rendering the views associated with a document.

You will most likely not have to subclass NSWindowController. Instead, you associate a nib file (the Gorm output) with the subclass of NSDocument, and NSDocumentController will load this nib file for each document that is created or loaded.

For example, a text based application that is used for the editing of plain text files, may subclass NSDocument with a TextDocument class. Each instance of this class would have an NSWindowController instance associated with it, which in turn manages a window instance that is instantiated from a nib file. The NSDocumentController instance, as managed and instatiated by GNUstep, would be responsible for loading and saving documents in your application. It even prompts the user to save their documents when they try to quit the application.

== File Components ==

In building your application you will need to create a number of special files. From scratch, the following should be a rough guide to getting it working. These include the Makefile, your application's property list and the interface files.

=== The Makefile ===

For this type of application, no special makefile is needed: it just has to be a normal application. Project Builder should be able to spit out the required makefile and Gorm files that are needed for a generic application. Otherwise use the following as a template:

'''GNUmakefile'''

include $(GNUSTEP_MAKEFILES)/common.make 
APP_NAME = DocumentApp 
DocumentApp_OBJC_FILES = 
MyDocument.m 
main.m 
DocumentApp_RESOURCES = \ 
Resources/Info-gnustep.plist \ 
Resources/DocumentApp.gorm \ 
Resources/MyDocument.gorm 
-include GNUmakefile.preamble 
include $(GNUSTEP_MAKEFILES)/application.make 
-include GNUmakefile.postamble 

For more information as to customising this file, as well as setting up compiler options for third party libraries and includes, see the GNUstep makefile manual.

=== The application dictionary - Info-gnustep.plist ===

For those that have edited this file in their project before, it is a dictionary with various values entered. For our purposes, we need an array within the main dictionary, called "NSTypes". This is a array of unnamed dictionaries, with one dictionary for each type.

An entire example of this file, for a "theoretical" TextEdit application (please note that such an application does exist as an example application from Next I think, and again on MacOS X but I have constructed a much simpler version, used only for plain text files).

Taking a look at the single dictionary entry in the NSTypes array, the following key-value pairs are needed:
* '''NSDocumentClass:''' This is (string) the subclass name you use in your code, the "objective-c name" of your document subclass. This is used by NSDocumentController's default implementation to create instances of your document type.
* '''NSName:''' The generic file type (string). This is completely arbitrary, and can be anything you like. For the purpose of conventions, it may be more appropriate not to use the "NS" or "GS" prefix (the latter of which I not sure), and instead use either your own, or no prefix at all.
* '''NSHumanReadableName:''' The human readable name of your document type (string)? TODO: explain where this is used.
* '''NSUnixExtensions:''' An array of strings, each containing a file extension connected to this document type on "unix" platforms. TODO: explain how "unix" is interpreted by GNUstep.
* '''NSDOSExtensions:''' An array of strings, each containing a file extenstion connected to this document type on "DOS" platforms (could be loosely interpreted as any MS platforms GNUstep runs on, i.e. Windows 2000/XP).
* '''NSRole:''' A string, either "Viewer" or "Editor", depending on how your document operates on this file type.
* '''NSIcon:''' A icon name associated with this document type. TODO: Investigate how this works.

'''Info-gnustep.plist'''
{
ApplicationDescription = "A simple text editor for GNUstep.";
ApplicationName = TextEdit;
ApplicationRelease = 0.10;
Authors = ( "Christopher Armstrong <quineska@gamebox.net" );
Copyright = "Copyright (C) 2005 Christopher Armstrong";
CopyrightDescription = "Released under GPL.";
FullVersionID = 0.10;
NSExecutable = TextEdit;
NSMainNibFile = TextEdit.gorm;
NSPrincipalClass = NSApplication;
NSRole = Application;
NSTypes = (
{
NSDocumentClass = "TextDocument";
NSName = "GSTextDocumentType";
NSHumanReadableName = "Text Document";
NSUnixExtensions = ( "txt", "" );
NSDOSExtensions = ( "txt" );
NSRole = Editor;
}
);
}

For more information on property list files, consult [[Property Lists]].

=== Interface file ===

Two interface files are needed: one for your main application, and another that will be instantiated with each instance of your document subclass. These both should be listed as resources in your makefile, (as shown the GNUmakefile example above). It may be helpful to name the document nib file after your class.

==== Application Interface File ====

The application one should just be a menu (though it could be more if necessary). When constructing it, take the following into account:

* Use a standard Gorm template for an Application.
* Delete the window instance in the "Objects" pane (unless you need a main window, in which case I don't know how to operate).
* Set NSOwner's class to "NSDocumentController" (this is the custom class option of NSOwner in the property inspector). This ensures openDocument, newDocument, etc. messages, as sent to NSFirst, get picked up by NSDocumentController. Do not instantiate it (I believe you can't anyway).
* If you intend to subclass NSDocumentController, subclass it in the Classes pane. To make sure that this class is instantiated and used, make sure you instantiate it in Gorm or in your main.m file, and set NSOwner to be your subclass.
* Drag a Document menu from the palette onto your main menu. This already has the proper linkage for each relevant message for a document setup to be directed to NSFirst. In the case of generic messages (such as openDocument:, not associated with any document instance), these are forwarded to the shared instance of NSDocumentController (see it's reference documentation). When a document is active, more specific messages (such as close: or saveDocument:) are forwarded to the relevant document instance of your NSDocument subclass.
* Add any appropriate menus such as "Info" and "Format" which may be relevant to your application.

==== Document Interface File ====

The document interface file is (generically) a window containing the view(s) required for the implementation of one instance of your document type. For example, in the case of a TextDocument type, a window instance with a NSTextView drawn on it is used for each open window. This nib file is instantiated every time a person creates a new document (the newDocument: message goes to NSDocumentController) or opens an existing document (openDocument:).

You will need to:
* '''Subclass NSDocument''' with your document type in Gorm (this is done in a couple of ways, see [[Gorm_Manual#Custom_classes|custom classes]]).
* '''Set NSOwner:''' Set your subclass as NSOwner's Custom class (done using the Property inspector). DO NOT INSTANTIATE IT.

Another thing that you may want to consider is custom outlets. If you place certain views or controls on your window (including the window itself), you may want to refer to them directly in yout code, e.g. the NSTextView in our TextEdit example is accessed directly, so that we can save it's contents to a file. To enable this, we add outlets to our class (see [[Gorm_Manual#Custom_classes|custom classes]]). We then connected NSOwner to the appropriate controls/views, and selected the outlets in the Connections property inspector (see [[Gorm_Manual#Editing_the_interface|editing the interface]]).

== Code ==

Various things need to be done at a code level, to ensure that your NSDocument subclass is properly instantiated. This section aims to tell you what is necessary.

=== NSDocument subclass ===

When creating your subclass, you may have chosen to have Gorm create the class files. If not, you should create two files for your subclass: a header (.h) file and an implementation file (.m). The header file should take the following layout (we're using the TextEdit example again):

#ifndef TEXTDOCUMENT_H
#define TEXTDOCUMENT_H 
#include <AppKit/AppKit.h> 
@class NSDocument; 
@interface TextDocument : NSDocument
{
@protected
/* Outlets we added in our Gorm nib file */
id * textView;
}
/* Basic methods used for loading and saving document data (respectively). */
- (BOOL) loadDataRepresentation:(NSData*)representation ofType:(NSString*)type;
- (NSData*) dataRepresentationOfType: (NSString*)type; 
/* Information and events handling of GUI related changes */
- (NSString*) windowNibName;
- (void) windowControllerDidLoadNib:(NSWindowController*)windowController; 
@end 

Firstly, take note that we inherit from NSDocument. As a result, we need to override some methods for a basic (but working) implementation.

==== loadDataRepresentation:ofType: and dataRepresentationOfType: ====

The methods, loadDataRepresent:ofType: and dataRepresentationOfType: are used by NSDocumentController to load and save our files. The first method is called when the user trys to open a document (NSDocumentController gets the file name and copies it's data using an open panel). The method is passed the raw data in this file, as well as a string representing its type. It is important to note that this type string is the same one used in your property list. It is used by NSDocumentController to tell you what type it thinks you should open the data with. If this is not possible, or if there is an error trying to parse the data, your method returns FALSE/NO. Otherwise, you should store a local, meaningful representation of the data, which you can insert into your document window a little later (and return YES).

For example, in terms of the TextEdit example:
- (BOOL) loadDataRepresentation:(NSData*) representation ofType:(NSString*)type
{
/* Clean out our old representation if it still exists */
if (fileContents) RELEASE(fileContents); 
/* Allocate room for the new data, and try to initialise a string with it. */
self->fileContents = [NSString alloc];
fileContents = [fileContents initWithBytes: [representation bytes]
length: [representation length]
encoding: NSASCIIStringEncoding]; 
/* If this can't be done, return NO */
if (!fileContents)
return NO; 
/* Otherwise, set our TextView to the string data. */
[self->textView setString: fileContents];
return YES;
}

If this is not suffice, or if your program can open the data in a more efficient manner, it may be worth looking into overriding -initWithContentsOfFile:ofType: and -initWithContentsOfURL:ofType: (see the GUI manual for more details).

==== windowNibName ====

This method must be overriden to return the name of your nib files. More complex implementations will use other methods to load the interface files. TODO: information on what methods need to be overriden.

[[Category:Development]]

Creating document based applications

2005-07-07T00:43:31Z

Quineska: /* Document Interface File */

Note: this is a work in progress. Please bear with me as I add further information.
--[[User:Quineska|ChrisArmstrong]] 08:33, 5 Jul 2005 (CEST)

== Introduction ==

OpenStep can provide your application a document-based model. It helps to simplify the process of creating such applications. GNUstep is compatible with this paridgm as well; this document aims to provide an overview of what is required in the creation and design of such an application.

It is assumed you are familiar with GNUstep, and have some understanding as how to create Gorm's nib files, as well as some understanding of how they work.

Importantly, such applications have certain components that are required, and should be considered as part of their design. At a programmatic level, classes that will be used as part of the AppKit are:

==== NSDocument ====

This class is central to the OpenStep document based model. Such an application declares a new instance of a subclass of NSDocument for each “document” that is opened. It will be necessary to subclass NSDocument to implement this.

Each instance of your NSDocument subclass may have one or more windows associated with it. These are used as an interface for loading and saving a representation of your document type. Each window will have an “NSWindowController” instance associated with it, where NSDocument maintains a list of these.

==== NSDocumentController ====

This class acts a controller. It maintains a list of documents (instances of your NSDocument subclass) and is responsible for loading and instantiating new documents. It is usually not necessary to implement a subclass of this, but often it may be useful to implement special functionality (especially related to open documents as a whole).

==== NSWindowController ====

As mentioned above, NSWindowController instances are individually associated with one NSWindow instance, in such a way that a document maintains a list of window controllers that are reponsible for rendering the views associated with a document.

You will most likely not have to subclass NSWindowController. Instead, you associate a nib file (the Gorm output) with the subclass of NSDocument, and NSDocumentController will load this nib file for each document that is created or loaded.

For example, a text based application that is used for the editing of plain text files, may subclass NSDocument with a TextDocument class. Each instance of this class would have an NSWindowController instance associated with it, which in turn manages a window instance that is instantiated from a nib file. The NSDocumentController instance, as managed and instatiated by GNUstep, would be responsible for loading and saving documents in your application. It even prompts the user to save their documents when they try to quit the application.

== Components ==

In building your application you will need to create a number of components. From scratch, the following should be a rough guide to getting it working.

=== The Makefile ===

For this type of application, no special makefile is needed: it just has to be a normal application. Project Builder should be able to spit out the required makefile and Gorm files that are needed for a generic application. Otherwise use the following as a template:

'''GNUmakefile'''

include $(GNUSTEP_MAKEFILES)/common.make 
APP_NAME = DocumentApp 
DocumentApp_OBJC_FILES = 
MyDocument.m 
main.m 
DocumentApp_RESOURCES = \ 
Resources/Info-gnustep.plist \ 
Resources/DocumentApp.gorm \ 
Resources/MyDocument.gorm 
-include GNUmakefile.preamble 
include $(GNUSTEP_MAKEFILES)/application.make 
-include GNUmakefile.postamble 

For more information as to customising this file, as well as setting up compiler options for third party libraries and includes, see the GNUstep makefile manual.

=== The application dictionary - Info-gnustep.plist ===

For those that have edited this file in their project before, it is a dictionary with various values entered. For our purposes, we need an array within the main dictionary, called "NSTypes". This is a array of unnamed dictionaries, with one dictionary for each type.

An entire example of this file, for a "theoretical" TextEdit application (please note that such an application does exist as an example application from Next I think, and again on MacOS X but I have constructed a much simpler version, used only for plain text files).

Taking a look at the single dictionary entry in the NSTypes array, the following key-value pairs are needed:
* '''NSDocumentClass:''' This is (string) the subclass name you use in your code, the "objective-c name" of your document subclass. This is used by NSDocumentController's default implementation to create instances of your document type.
* '''NSName:''' The generic file type (string). This is completely arbitrary, and can be anything you like. For the purpose of conventions, it may be more appropriate not to use the "NS" or "GS" prefix (the latter of which I not sure), and instead use either your own, or no prefix at all.
* '''NSHumanReadableName:''' The human readable name of your document type (string)? TODO: explain where this is used.
* '''NSUnixExtensions:''' An array of strings, each containing a file extension connected to this document type on "unix" platforms. TODO: explain how "unix" is interpreted by GNUstep.
* '''NSDOSExtensions:''' An array of strings, each containing a file extenstion connected to this document type on "DOS" platforms (could be loosely interpreted as any MS platforms GNUstep runs on, i.e. Windows 2000/XP).
* '''NSRole:''' A string, either "Viewer" or "Editor", depending on how your document operates on this file type.
* '''NSIcon:''' A icon name associated with this document type. TODO: Investigate how this works.

'''Info-gnustep.plist'''
{
ApplicationDescription = "A simple text editor for GNUstep.";
ApplicationName = TextEdit;
ApplicationRelease = 0.10;
Authors = ( "Christopher Armstrong <quineska@gamebox.net" );
Copyright = "Copyright (C) 2005 Christopher Armstrong";
CopyrightDescription = "Released under GPL.";
FullVersionID = 0.10;
NSExecutable = TextEdit;
NSMainNibFile = TextEdit.gorm;
NSPrincipalClass = NSApplication;
NSRole = Application;
NSTypes = (
{
NSDocumentClass = "TextDocument";
NSName = "GSTextDocumentType";
NSHumanReadableName = "Text Document";
NSUnixExtensions = ( "txt", "" );
NSDOSExtensions = ( "txt" );
NSRole = Editor;
}
);
}

For more information on property list files, consult [[Property Lists]].

=== Interface file ===

Two interface files are needed: one for your main application, and another that will be instantiated with each instance of your document subclass. These both should be listed as resources in your makefile, (as shown the GNUmakefile example above). It may be helpful to name the document nib file after your class.

==== Application Interface File ====

The application one should just be a menu (though it could be more if necessary). When constructing it, take the following into account:

* Use a standard Gorm template for an Application.
* Delete the window instance in the "Objects" pane (unless you need a main window, in which case I don't know how to operate).
* Set NSOwner's class to "NSDocumentController" (this is the custom class option of NSOwner in the property inspector). This ensures openDocument, newDocument, etc. messages, as sent to NSFirst, get picked up by NSDocumentController. Do not instantiate it (I believe you can't anyway).
* If you intend to subclass NSDocumentController, subclass it in the Classes pane. To make sure that this class is instantiated and used, make sure you instantiate it in Gorm or in your main.m file, and set NSOwner to be your subclass.
* Drag a Document menu from the palette onto your main menu. This already has the proper linkage for each relevant message for a document setup to be directed to NSFirst. In the case of generic messages (such as openDocument:, not associated with any document instance), these are forwarded to the shared instance of NSDocumentController (see it's reference documentation). When a document is active, more specific messages (such as close: or saveDocument:) are forwarded to the relevant document instance of your NSDocument subclass.
* Add any appropriate menus such as "Info" and "Format" which may be relevant to your application.

==== Document Interface File ====

The document interface file is (generically) a window containing the view(s) required for the implementation of one instance of your document type. For example, in the case of a TextDocument type, a window instance with a NSTextView drawn on it is used for each open window. This nib file is instantiated every time a person creates a new document (the newDocument: message goes to NSDocumentController) or opens an existing document (openDocument:).

You will need to:
* '''Subclass NSDocument''' with your document type in Gorm (this is done in a couple of ways, see [[Gorm_Manual#Custom_classes|custom classes]]).
* '''Set NSOwner:''' Set your subclass as NSOwner's Custom class (done using the Property inspector). DO NOT INSTANTIATE IT.

Another thing that you may want to consider is custom outlets. If you place certain views or controls on your window (including the window itself), you may want to refer to them directly in yout code, e.g. the NSTextView in our TextEdit example is accessed directly, so that we can save it's contents to a file. To enable this, we add outlets to our class (see [[Gorm_Manual#Custom_classes|custom classes]]). We then connected NSOwner to the appropriate controls/views, and selected the outlets in the Connections property inspector (see [[Gorm_Manual#Editing_the_interface|editing the interface]]).

[[Category:Development]]

Creating document based applications

2005-07-07T00:25:21Z

Quineska: /* Application Interface File */

Property Lists

2005-07-06T06:55:04Z

Quineska: Spelling correction

NOTE: '''If anything below is dead wrong, please fix immediately. It is a work in progress. I am constructing this based on my experience with GNUstep, NOT any reference documentation that may exist. I don't warrant it fit for any purpose whatsoever, nor shall I take any responsibility for any issues or losses or problems etc that may arise from its use. (Christopher Armstrong, --[[User:Quineska|ChrisArmstrong]] 08:38, 6 Jul 2005 (CEST))'''

== Introduction ==

Property lists are used throughout GNUstep to store defaults, program settings, application meta information, etc. MacOS X uses XML based property lists, but GNUstep uses another property list implementation also (TODO: history of this style of property list).

They are composed of a "tree of arrays and dictionary's, which may be embedded inside each other for several layers. TODO: limits of embedding array/dictionaries inside each other.

== Dictionary ==

A dictionary is a list of key-value pairs, where each item in the list has a name associated with it (key) and another type (value), which could be another dictionary, an array or often a string. It programmatically corresponds to NSDictionary/NSMutableDictionary. They take the following syntax:

{
KeyName1 = Value1;
AnotherKeyName = "Value2";
Something = ( "ArrayItem1", "ArrayItem2", "ArrayItem3" );
Key4 = 0.10;
KeyFive = { Dictionary2Key1 = "Something"; AnotherKey = "Somethingelse"; };
}

As can be seen, each key-value pair is seperated by a semi-colon. Within the pair, the key is seperated from the value with an "equals" (=) sign. The key name is arbitrary, and not put in inverted commas (""). Shown above are a (unknown type, could be some sort of string - TODO), a string, an array, a number and another dictionary (respectively).

== Array ==

An array is a list of values, each of the same type (often arrays or dictionaries). Programmatically, it uses NSArray/NSMutableArray. It takes a syntax similar to the following:

( Value1, Value2, Value3, Value4 )

Each value is seperated by commas. By the technical definition of an array, each value is of the same type (but I believe GNUstep permits different types).

== Programming ==

GNUstep permits such property list files (denoted with a .plist extenstion) to be loaded and subsequently used in your applications or tools. NSDictionary and NSArray are used as representations of the above in the Foundation library (gnustep-base).

Creating document based applications

2005-07-06T06:52:55Z

Quineska: Added more info, namely related to Property List, Gorm files, etc.

Property Lists

2005-07-06T06:38:42Z

Quineska:

NOTE: '''If anything below is dead wrong, please fix immediately. It is a work in progress. I am constructing this based on my experience with GNUstep, NOT any reference documentation that may exist. I don't warrant it fit for any purpose whatsoever, nor shall I take any responsibility for any issues or losses or problems etc that may arise from its use. (Christopher Armstrong, --[[User:Quineska|ChrisArmstrong]] 08:38, 6 Jul 2005 (CEST))'''

== Introduction ==

Property lists are used throughout GNUstep to store defaults, program settings, application meta information, etc. MacOS X uses XML based property lists, but GNUstep uses another property list implementation also (TODO: history of this style of property list).

They are composed of a "tree of arrays and dictionary's, which may be embedded inside each other for several layers. TODO: limits of embedding array/dictionaries inside each other.

== Dictionary ==

A dictionary is a list of key-value pairs, where each item in the list has a name associated with it (key) and another type (value), which could be another dictionary, an array or often a string. It programmatically corresponds to NSDictionary/NSMutableDictionary. They take the following syntax:

{
KeyName1 = Value1;
AnotherKeyName = "Value2";
Something = ( "ArrayItem1", "ArrayItem2", "ArrayItem3" );
Key4 = 0.10;
KeyFive = { Dictionary2Key1 = "Something"; AnotherKey = "Somethingelse"; };
}

As can be seen, each key-value pair is seperated by a semi-colon. Within the pair, the key is seperated from the value with an "equals" (=) sign. The key name is arbitrary, and not put in inverted commas (""). Shown above are a (unknown type, could be some sort of string - TODO), a string, an array, a number and another dictionary (respectively).

== Array ==

An array is a list of values, each of the same type (often arrays or dictionaries). Programmatically, it uses NSArray/NSMutableArray. It takes a syntax similar to the following:

( Value1, Value2, Value3, Value4 )

Each value is seperated by commas. By the technical definition of an array, each value is of the same type (but I belive GNUstep permits different types).

== Programming ==

GNUstep permits such property list files (denoted with a .plist extenstion) to be loaded and subsequently used in your applications or tools. NSDictionary and NSArray are used as representations of the above in the Foundation library (gnustep-base).

Property Lists

2005-07-06T06:38:14Z

Quineska:

NOTE: If anything below is dead wrong, please fix immediately. It is a work in progress. I am constructing this based on my experience with GNUstep, NOT any reference documentation that may exist. I don't warrant it fit for any purpose whatsoever, nor shall I take any responsibility for any issues or losses or problems etc that may arise from its use. (Christopher Armstrong, --[[User:Quineska|ChrisArmstrong]] 08:38, 6 Jul 2005 (CEST))

== Introduction ==

Property lists are used throughout GNUstep to store defaults, program settings, application meta information, etc. MacOS X uses XML based property lists, but GNUstep uses another property list implementation also (TODO: history of this style of property list).

They are composed of a "tree of arrays and dictionary's, which may be embedded inside each other for several layers. TODO: limits of embedding array/dictionaries inside each other.

== Dictionary ==

A dictionary is a list of key-value pairs, where each item in the list has a name associated with it (key) and another type (value), which could be another dictionary, an array or often a string. It programmatically corresponds to NSDictionary/NSMutableDictionary. They take the following syntax:

{
KeyName1 = Value1;
AnotherKeyName = "Value2";
Something = ( "ArrayItem1", "ArrayItem2", "ArrayItem3" );
Key4 = 0.10;
KeyFive = { Dictionary2Key1 = "Something"; AnotherKey = "Somethingelse"; };
}

As can be seen, each key-value pair is seperated by a semi-colon. Within the pair, the key is seperated from the value with an "equals" (=) sign. The key name is arbitrary, and not put in inverted commas (""). Shown above are a (unknown type, could be some sort of string - TODO), a string, an array, a number and another dictionary (respectively).

== Array ==

An array is a list of values, each of the same type (often arrays or dictionaries). Programmatically, it uses NSArray/NSMutableArray. It takes a syntax similar to the following:

( Value1, Value2, Value3, Value4 )

Each value is seperated by commas. By the technical definition of an array, each value is of the same type (but I belive GNUstep permits different types).

== Programming ==

GNUstep permits such property list files (denoted with a .plist extenstion) to be loaded and subsequently used in your applications or tools. NSDictionary and NSArray are used as representations of the above in the Foundation library (gnustep-base).

Creating document based applications

2005-07-06T06:19:55Z

Quineska:

Creating document based applications

2005-07-06T06:17:19Z

Quineska:

Creating document based applications

2005-07-06T06:05:04Z

Quineska:

Talk:Developer Guides

2005-07-06T05:53:21Z

Quineska:

Thanks for helping me put this into some context. I'm sorta new to wiki's. --[[User:Quineska|ChrisArmstrong]] 07:53, 6 Jul 2005 (CEST)

Creating document based applications

2005-07-05T06:42:28Z

Quineska:

Note: this is a work in progress. Please bear with me as I add further information.
--[[User:Quineska|ChrisArmstrong]] 08:33, 5 Jul 2005 (CEST)

Introduction

OpenStep can provide your application a document-based model. It helps to simplify the process of creating such applications. GNUstep is compatible with this paridgm as well; this document aims to provide an overview of what is required in the creation and design of such an application.

It is assumed you are familiar with GNUstep, and have some understanding as how to create Gorm's nib files, as well as some understanding of how they work.

Importantly, such applications have certain components that are required, and should be considered as part of their design. At a programmatic level, classes that will be used as part of the AppKit are:

NSDocument

This class is central to the OpenStep document based model. Such an application declares a new instance of a subclass of NSDocument for each “document” that is opened. It will be necessary to subclass NSDocument to implement this.

Each instance of your NSDocument subclass may have one or more windows associated with it. These are used as an interface for loading and saving a representation of your document type. Each window will have an “NSWindowController” instance associated with it, where NSDocument maintains a list of these.

NSDocumentController

This class acts a controller. It maintains a list of documents (instances of your NSDocument subclass) and is responsible for loading and instantiating new documents. It is usually not necessary to implement a subclass of this, but often it may be useful to implement special functionality (especially related to open documents as a whole).

NSWindowController

As mentioned above, NSWindowController instances are individually associated with one NSWindow instance, in such a way that a document maintains a list of window controllers that are reponsible for rendering the views associated with a document.

You will most likely not have to subclass NSWindowController. Instead, you associate a nib file (the Gorm output) with the subclass of NSDocument, and NSDocumentController will load this nib file for each document that is created or loaded.

For example, a text based application that is used for the editing of plain text files, may subclass NSDocument with a TextDocument class. Each instance of this class would have an NSWindowController instance associated with it, which in turn manages a window instance that is instantiated from a nib file. The NSDocumentController instance, as managed and instatiated by GNUstep, would be responsible for loading and saving documents in your application. It even prompts the user to save their documents when they try to quit the application.

Components

In building your application you will need to create a number of components. From scratch, the following should be a rough guide to getting it working.
The Makefile

For this type of application, no special makefile is needed: it just has to be a normal application. Project Builder should be able to spit out the required makefile and Gorm files that are needed for a generic application. Otherwise use the following as a template:

GNUmakefile:

include $(GNUSTEP_MAKEFILES)/common.make 
APP_NAME = DocumentApp 
DocumentApp_OBJC_FILES = 
MyDocument.m 
main.m 
DocumentApp_RESOURCES = \ 
Resources/Info-gnustep.plist \ 
Resources/DocumentApp.gorm \ 
Resources/MyDocument.gorm 
-include GNUmakefile.preamble 
include $(GNUSTEP_MAKEFILES)/application.make 
-include GNUmakefile.postamble 

For more information as to customising this file, as well as setting up compiler options for third party libraries and includes, see the GNUstep makefile manual.

Creating document based applications

2005-07-05T06:34:33Z

Quineska: Fixed formating of example GNUmakefile

Note: this is a work in progress. Please bear with me as I add further information.
--[[User:Quineska|ChrisArmstrong]] 08:33, 5 Jul 2005 (CEST)

Introduction

OpenStep can provide your application a document-based model. It helps to simplify the process of creating such applications. GNUstep is compatible with this paridgm as well; this document aims to provide an overview of what is required in the creation and design of such an application.

It is assumed you are familiar with GNUstep, and have some understanding as how to create Gorm's nib files, as well as some understanding of how they work.

Importantly, such applications have certain components that are required, and should be considered as part of their design. At a programmatic level, classes that will be used as part of the AppKit are:

NSDocument

This class is central to the OpenStep document based model. Such an application declares a new instance of a subclass of NSDocument for each “document” that is opened. It will be necessary to subclass NSDocument to implement this.

Each instance of your NSDocument subclass may have one or more windows associated with it. These are used as an interface for loading and saving a representation of your document type. Each window will have an “NSWindowController” instance associated with it, where NSDocument maintains a list of these.

NSDocumentController

This class acts a controller. It maintains a list of documents (instances of your NSDocument subclass) and is responsible for loading and instantiating new documents. It is usually not necessary to implement a subclass of this, but often it may be useful to implement special functionality (especially related to open documents as a whole).

NSWindowController

As mentioned above, NSWindowController instances are individually associated with one NSWindow instance, in such a way that a document maintains a list of window controllers that are reponsible for rendering the views associated with a document.

You will most likely not have to subclass NSWindowController. Instead, you associate a nib file (the Gorm output) with the subclass of NSDocument, and NSDocumentController will load this nib file for each document that is created or loaded.

For example, a text based application that is used for the editing of plain text files, may subclass NSDocument with a TextDocument class. Each instance of this class would have an NSWindowController instance associated with it, which in turn manages a window instance that is instantiated from a nib file. The NSDocumentController instance, as managed and instatiated by GNUstep, would be responsible for loading and saving documents in your application. It even prompts the user to save their documents when they try to quit the application.

Components

In building your application you will need to create a number of components. From scratch, the following should be a rough guide to getting it working.
The Makefile

For this type of application, no special makefile is needed: it just has to be a normal application. Project Builder should be able to spit out the required makefile and Gorm files that are needed for a generic application. Otherwise use the following as a template:

<nowiki>
GNUmakefile:

include $(GNUSTEP_MAKEFILES)/common.make

APP_NAME = DocumentApp

DocumentApp_OBJC_FILES = \
MyDocument.m \
main.m

DocumentApp_RESOURCES = \
Resources/Info-gnustep.plist \
Resources/DocumentApp.gorm \
Resources/MyDocument.gorm

-include GNUmakefile.preamble
include $(GNUSTEP_MAKEFILES)/application.make
-include GNUmakefile.postamble

</nowiki>
For more information as to customising this file, as well as setting up compiler options for third party libraries and includes, see the GNUstep makefile manual.