     [file version.texi not included]

     START-INFO-DIR-ENTRY
     * Gorm::                      The GNUstep Graphical Object Relationship Modeler
     END-INFO-DIR-ENTRY

This file documents the features and implementation of the Gorm application.

Copyright (C) 1999,2000 Free Software Foundation, Inc.

Permission is granted to make and distribute verbatim copies of this manual provided the copyright notice and this permission notice are preserved on all copies.

Permission is granted to copy and distribute modified versions of this manual under the conditions for verbatim copying, provided also that the section entitled ``GNU Library General Public License'' is included exactly as in the original, and provided that the entire resulting derived work is distributed under the terms of a permission notice identical to this one.

Permission is granted to copy and distribute translations of this manual into another language, under the above conditions for modified versions, except that the section entitled ``GNU Library General Public License'' and this permission notice may be included in translations approved by the Free Software Foundation instead of in the original English.

Copying
*******

See the file COPYING.

Contributors to Gorm
********************

  * Gregory John Casamento <greg_casamento@yahoo.com> Is the current maintaner of Gorm.   Has implemented lots of new features and rewritten large portions of the existing code.

  * Richard Frith-Macdonald <richard@brainstorm.co.uk> wrote Gorm as part of the GNUstep project.

  * Pierre-Yves Rivaille <gnustep@rivaille.net> Is also a major contributor to the Gorm application.

Installing Gorm
***************

     [file install.texi not included]

News
****

     [file news.texi not included]

To Do
-----

  * Debug and stabilize existing code.

Overview
********

Gorm is an application for creating the user interface (and possibly entire applications) for a GNUstep application.  Initially a close clone of the old NeXTstep 3.3 Interface Builder application, I expect that Gorm will mutate beyond the capabilities of that app.

GNUstep is an object-oriented programming framework and a collection of tools developed for or using the GNUstep libraries.

You can find out more about GNUstep at http://www.gnustep.org

The basic idea behind Gorm is simple - it provides a graphical user interface with which to connect together objects from the GNUstep libraries (as well as custom-written objects) and set their attributes in an easy to use manner.

The collection of objects is then saved as a document which can either be re-loaded into Gorm for further editing, or can be loaded into a running GNUstep application in order to provide that application with a user interface or some subsystem.

Major features
--------------

  * Drag-and-drop creation of GUI elements from palettes.

  * Run-time loading of additional palettes that may be written using an API very similar to that of Apple/NeXTs interface Builder palette API.

  * Direct on-screen manipulation of GUI elements

  * Manipulation and examination of objects via inspectors.

  * Drag-and-drop creation of connections between objects.

  * Interactive test mode for interfaces/object-networks under development.

  * Saving data in a format loadable by GNUstep applications.

Usage
*****

Here is a description of the menu structure and what each menu does -

  * Info
     The Info menu item produces a submenu ...

       * Info Panel
          A panel giving very limited information about Gorm

       * Preferences (not implemented)
          A panel allowing you to set preferences about how Gorm operates

       * Help (not implemented)
          A panel providing general help on using Gorm

  * Document
     The Document menu item produces a submenu ...

       * Open
          This produces an open panel that lets you open a Gorm document. You use this if you want to use Gorm to edit an exisiting document.

       * New Application
          This creates a new application document within Gorm, you may then use the Palettes panel to drag new objects into the document.

       * New Module
          Contains a submenu, which also contains:

            * New Empty
               produces an empty document with only NSFirst and NSOwner.

            * New Inspector
               produces a document with NSOwner, NSFirst and a window which is the correct size for an Inspector.

            * New Palette
               produces a document which is like the one by New Inspector, but it's window is the right size for a Palette.

       * Save
          This saves the current document

       * Save As
          This saves the current document to a new file and changes the document name to match the new name on disk.

       * Save All
          This saves all documents currently being edited by Gorm.

       * Revert To Saved
          This removes all changes made to the document sunce the last save, or since the document was opened.

       * Test Interface
          This provides interactive testing of the active document.  To end testing, you need to select the quit menu item.

       * Miniaturize
          This miniaturises the active document (or whatever panel is currently key).

       * Close
          This closes the currenly active document.

       * Debug
          Prints some useful internal information.

       * Load Sound
          Loads a sound into the .gorm file.

       * Image
          Loads an image into the .gorm file.

  * Edit
     In addition to the usual Cut, Copy, Paste, Delete Select All, this menu also contains:

       * Group
          Which produces a submenu

            * In Splitview
               Groups views into an NSSplitView.   Gorm does this based on the relative positions of the views being grouped.  It determines the orientation and the order of th views and then groups them either vertically or horizontally in the order they appear on the screen.

            * In Box
               Simply groups all of the views into one NSBox.

            * In ScrollView
               Simply groups all of the views into one NSScrollView.

            * Ungroup
               Ungroups the contained views.

       * Set Name
          This allows the user to set a name for a given object in the Objects view in the main document window.

       * Disable Guideline
          This item toggles between Enable Guideline and Disable Guideline.  This allows the user to turn on or off the guides which appear when placing views in a window or view in Gorm.

  * Classes
     Contains menus for working with classes.

       * Create Subclass
          Creates a subclass of the currently selected class in the current document classes view.

       * Load Class
          Loads a class from a .h file into the current document.

       * Create Class Files
          Generates a .h and .m file from the currently selected class in the current document classes view.

       * Instantiate
          Creates an instance of the selected class in the current document classes view.

       * Add Outlet/Action
          Adds an outlet or an action depending on what is selected in the document classes view.  If the outlet icon is selected, it will add an outlet, if it the action icon is selected it will add an action.

       * Remove
          Removes the currently selected outlet, action or class.

  * Tools
     Contains the inspector and the palette menus

       * Inspector
          Shows the inspector

       * Palette
          Shows the palette

       * Load Palette
          Opens a file panel and allows the user to load a palette into Gorm.

  * Windows
     Shows currently open windows.

  * Services
     Shows currently available services.

  * Hide
     Hides the application.

  * Quit
     Quits the application.

Implementation
**************

Notes on implementation
=======================

The IB documentation on how object selection is managed and how editors and inspectors are used is unclear ... so I've gone my own way.

1. When a document is loaded, the document object creates an editor attached to each top-level object in the user interface (NSMenu and NSWindow objects).

These editors must be aware of their edited objects being clicked upon, and clicking on one of these should cause the corresponding editor to become the active editor.

The active editor is responsible for handling selection of the edited object (and any objects below it in the object hierarchy).  Upon change of selection, the editor is responsible for sending an IBSelectionChangedNotification with the selection owner (normally the editor itsself) as the notification owner.

The main application watches for these notifications in order to keep track of who has the selection.

Connections
===========

The connection API is the same as that for IB, but with the extension that the document object must implement [-windowAndRect:forObject:] to return the window in which the object is being displayed, and the rectangle enclosing the object (in window base coordinates).

This information is needed by Gorm so that it can mark the connection.

The editors mananging the drag-and-drop operation for a connection must call [NSApp -displayConnectionBetween:and:] to tell Gorm to update its display.  This method sets the values currently returned by [NSApp -connectSource] and [NSApp -connectDestination].

Preferences
***********

The preferences panel contains a number of useful customizable options which can be used to modify the behavior of Gorm.

Some of these defaults can be safely modified from the command line by the user.

  * PreloadHeaders
     The user can define a set of headers to load when Gorm starts creation of a new .gorm file. This is useful when the user is building a framework or a set of interfaces for a large application.

  * ShowInspectors
     Controls whether the inspector shows when Gorm is started.

  * ShowPalettes
     Controls whether the palettes window shows when Gorm is started.

  * BackupFile
     Determines if the old .gorm is moved to .gorm~ when the modified version is saved.

Basic Concepts
**************

This chapter will explain some of the basic things you need to understand before starting work on a new application.

Getting Started
---------------

First you need to understand a few basic concepts.   Gorm's main window includes a few standard entries which must be explained before we can proceed.

They are:

  * NSOwner

  * NSFirst

  * NSFont

What is NSOwner?
================

NSOwner is the class which ``owns'' the interface.  This is, by default, NSApplication, but it can be any class you like.   You can change it by selecting NSOwner in the document window and going to the ``Custom Class'' inspector in the inspectors window.  From there, you should see all of the classes which the NSOwner can assume.   We'll discuss more about this later when we go over how to create a new application

What is NSFirst?
================

NSFirst is your interface to the responder chain.  NSFirst is representative of the current ``first responder'' in the application.  When you want a message, such as a changeFont: message, to go to the current first responder from, say, a menu, you connect the menu item to the NSFirst object in the document window.  By doing this, it means that whichever object has first responder status at that time in the application will become the reciever of the ``changeFont:'' message.

Responders
----------

A responder is any subclass of NSResponder.  This includes NSWindow, NSView and all of the NSControl subclasses.

The Responder Chain
-------------------

The responder chain is a sequence of objects which are called to determine where a message sent to the first responder will go.   A message invoked on the first responder will be invoked on the first object in the responder chain which responds to that message.

The object which this message will be called on is determined in the method [NSApplication targetForAction:].  The call sequence is as follows, it will only proceed to the next step in each case if the current step fails to respond to the message which was invoked:

  * The firstResponder of the keyWindow, if one exists.

  * Iterates through all responders by pulling each in the linked list of responders for the key window.

  * It then tries the keyWindow.

  * Then the keyWindow's delegate

  * if the application is document based it tries the document controller object for the key window.

  * then it tries the mainWindow's list of responders (as above)

  * the mainWindow's delegate

  * if the app is document based, it tries the document controller for the main window

  * and finally, it tries the NSApplication delegate.

If all of the options in this list are exhausted, it then gives up and returns nil for the object which is to respond.

What is NSFont
==============

NSFont represents the NSFontManager object for the application.  This object is a shared singleton.   This means that, for any given app, there should be only one instance of the object.   This object is generally added to the document window when another objec, such as a Font menu item, is added to the interface, which, in turn, requires that this object be added to the document.

Creating A New Application
**************************

If you have ProjectCenter, you need to open it and create an ``Application'' project.   Create it with the name ``FirstApp''.

First you need to start Gorm up.  You can either do this by doing gopen Gorm.app from a command line prompt, or you can invoke it from the Dock or from the workspace's file viewer.

You then need to select the Document menu, and then New Application.  This should produce a new document window, with a menu and an empty window.

Advanced Topics
***************

This section will cover some topics which won't be of general interest to most users.   The details in this section pertain to the internal workings of Gorm.

Gorm file format
================

The current Gorm file format is basically just a set of objects, encoded one after another in a continuous stream with some markers indicating when a new class starts or which class is encoded.

The Name Table
--------------

Each object in the .gorm file has a name assigned to it by the application.  This allows Gorm to refer to the objects by a name once they are loaded rather than an address.  Each name is associated with it's object in a dictionary which preserves the overall structure of the GUI which has been created.

The Custom Class Table
----------------------

This is only used when the user has associated a custom class with an existing instance in the gorm file.  If the user has, for instance, added an NSWindow to the gorm, he/she can use the custom class inspector to select a subclass of NSWindow to change to.   Upon saving the Gorm