Keywords: manual

Next: 2.3 The objects section Up: 2. The GNUstep Markup Previous: 2.1 The GNUstep Markup

Subsections

- 2.2.1 XML Header
- 2.2.2 The `<gsmarkup>` tag
- 2.2.3 Comments
- 2.2.4 Special Characters
- 2.2.5 `<objects>` and `<connectors>` sections

# 2.2 General overview of the main components

## 2.2.1 XML Header

A well formed gsmarkup file begins with the standard XML declaration,

    <?xml version="1.0"?>
    <!DOCTYPE gsmarkup>

While this declaration is not strictly necessary, it's pretty to have - it declares that the file is an XML version 1 file, and that the document type is `gsmarkup`.

## 2.2.2 The `<gsmarkup>` tag

The document begins with a `<gsmarkup>` tag, and ends with a `</gsmarkup>`. So, here is a skeleton gsmarkup file:

    <?xml version="1.0"?>
    <!DOCTYPE gsmarkup>
    <gsmarkup>
      <!-- the document goes here -->
    </gsmarkup>

(this `<gsmarkup>` tag is the equivalent of the `<html>` tag in HTML).

## 2.2.3 Comments

Comments can be inserted anywhere in the file inside a `<!- ->` tag. For example,

    <!-- This is a comment -->

Such comments are ignored by the parser.

## 2.2.4 Special Characters

A few characters are special XML characters. To insert these characters inside strings or free text in the file, you need to use the appropriate XML entities. The table 2.1 lists these important entities for easy reference.

Table 2.1: Special XML entities
Entity | Value
&amp; | `&`
&apos; | `'`
&gt; | `>`
&lt; | `<`
&quot; | `"`

For example, to insert `<` in the title of a button, you need to write it as `&lt;`.

## 2.2.5 `<objects>` and `<connectors>` sections

Inside the `<gsmarkup>` document tag, you can place objects and connectors section. An objects section is started by opening a `<objects>` tag, and ended by closing it. A connectors section is started by opening a `<connectors>` tag, and ended by closing it. You can use as many objects and connectors sections as you want, even if normally just one objects and one connectors sections are present. You can not nest objects and connectors sections. An objects section declares a list of objects which are to be created when the file is loaded into a running application. Typically, the list of objects might include windows (and all the widgets contained in the windows), menus, and other arbitrary objects, including objects of custom classes you have defined in your application. The connectors section declares a list of connectors; each connector represents a connection to establish between two objects - typically between an object residing in your application and one of the objects created when the file is loaded. As we will explain later on, connections between objects created when the file is loaded (and connections from an object within the file and an external object in your application) can be declared using a special syntax inside the objects section itself, so normally the connectors section is very short, and it is mostly provided for the special cases which can't be managed by the other syntax. Programs generating gsmarkup files are expected to put all connections in the objects section, except connections which can't be embedded there.

The difference between the two section types is important because the parser behaves differently inside an objects section and inside a connectors section.

To let you get a more practical feeling of the thing, here is a very simple gsmarkup file creating a button:

    <?xml version="1.0"?>
    <!DOCTYPE gsmarkup>
    <gsmarkup>

    <objects>

      <window title="Button Test" closable="NO" frameAutosaveName="main" >
        <button title="Click this button to quit" action="terminate:"/>
      </window>

    </objects>

    </gsmarkup>

We will explain the `window` and the `button` tags later on. Just notice that in this example, there is only an objects section in the file (which creates a window containing a button), and there is no connectors section.

If you want to run this file, save it as a `button.gsmarkup` file, then type at the command prompt

    openapp GSMarkupBrower.app button.gsmarkup

(of course you need to have installed Renaissance for this to work). You can normally load any file to see how it looks by using `GSMarkupBrowser.app` in this way.

Next: 2.3 The objects section Up: 2. The GNUstep Markup Previous: 2.1 The GNUstep Markup