# Class GTKGladeXML

Instead of creating a program's user interface "by hand", this class uses libglade and libxml to load an interface description from a file and build it at runtime. Each GTKGladeXML object represents a single loaded user interface description file (i.e. an XML file created by the Glade interface builder). All signal connections defined in the XML file are automatically established when the file is loaded.

Interface files loaded through this class use an extended signal handler syntax (within Glade) that differs slightly from the standard syntax used for C function calls. However, you can still load all standard Glade files by directly calling the C functions in libglade (`glade_xml_new` etc.). In this case, you can create Objective-C wrapper objects using the `GTK_GET_OBJECT` macro.

### Class-Hierarchy:

        NSObject
          |
          +---GTK
    	    |
    	    +---GTKObject
    		  |
    		  +---GTKData
    			|
    			+---GTKGladeXML

## Class GTKGladeXML inherits from GTKData

Last modified: 19.1.2000 (GToolKit/GTKGladeXML.h)

## Static Variables

private static NSString *volatile gettext_domain
  default translation domain

## Method Index

- selecting the translation domain
  + (NSString *) defaultTranslationDomain
  + (void) setDefaultTranslationDomain:(NSString *) domain
- loading interface description files
  + gladeXMLFromFile:(NSString *) file rootObject:(NSString *) root nameTable:(NSDictionary *) context
  + gladeXMLFromFile:(NSString *) file rootObject:(NSString *) root owner:owner
  - initFromFile:(NSString *) file rootObject:(NSString *) root nameTable:(NSDictionary *) context
  - initFromFile:(NSString *) file rootObject:(NSString *) root owner:owner
- looking up specific widgets
  - (GTKWidget *) getWidget:(NSString *) name
  - (GTKWidget *) getWidgetByLongName:(NSString *) name
  - (BOOL) resolveReferences:(NSString *) name, ...

## Methods

+ (GtkType) getType

  Return the unique type id of this class.

  Overrides: + (GtkType) getType in GTKData

+ (void) setDefaultTranslationDomain:(NSString *) domain

  Set the default translation domain for all translatable strings in the XML files to domain (this requires GNU gettext). The initial translation domain is `nil`, i.e. the current text domain will be used.

+ (NSString *) defaultTranslationDomain

  Return the current default translation domain used by GladeXML (or `nil` if no translation domain has been set).

  See also: +setDefaultTranslationDomain:

+ gladeXMLFromFile:(NSString *) file rootObject:(NSString *) root owner:owner

  Create an autoreleased GTKGladeXML instance. It will read the given file and construct all objects stored inside the file (if root is `nil`) or just a subtree starting from the widget named root. This method is equivalent to the call:

       [... gladeXMLFromFile:file rootObject:root nameTable:
          [NSDictionary dictionaryWithObject:owner forKey:@"owner"]];

  See also: -initFromFile:rootObject:nameTable:

+ gladeXMLFromFile:(NSString *) file rootObject:(NSString *) root nameTable:(NSDictionary *) context

  Create an autoreleased GTKGladeXML instance. It will read the given file and construct all objects stored inside the file (if root is `nil`) or just a subtree starting from the widget named root. See below for a description of the context parameter and how it is used.

  See also: -initFromFile:rootObject:nameTable:

- initFromFile:(NSString *) file rootObject:(NSString *) root owner:owner

  Initialize a new GTKGladeXML instance. It will read the given file and construct all objects stored inside the file (if root is `nil`) or just a subtree starting from the widget named root. This method is equivalent to the call:

       [... initFromFile:file rootObject:root nameTable:
          [NSDictionary dictionaryWithObject:owner forKey:@"owner"]];

  See also: -initFromFile:rootObject:nameTable:

- initFromFile:(NSString *) file rootObject:(NSString *) root nameTable:(NSDictionary *) context

  Initialize a new GTKGladeXML instance. It will read the given file and construct all objects stored inside the file (if root is `nil`) or just a subtree starting from the widget named root. The context parameter contains an external name table of objects in your program that the loaded interface description may refer to in its signal connections.

  The Objective-C interface to libglade allows some extended features:

  - The signal handler is an Objective-C method selector, not a C function name. This is why you have to specify an additional parameter, the name of a target object.
  - The name of the target object can be entered in the "Object:" field (see the Properties window in Glade) if it refers to an object in the same XML file (e.g. another widget).
  - Alternatively, the signal handler can take the special form:

    "target_name method_selector user_data" (without the quotes)

    In this case, the target_name may refer to either an object in the XML file or an object from the external name table (the context argument described above). user_data is optional and can be missing.

  - A widget name of class_name::widget_name indicates that the given class should be used when restoring the object from the XML file. This class must exist in your program and it must be a subclass of the GTK class used in Glade.

  This method automatically retains all widgets at the root of the created widget hierarchy, typically windows, dialogs or popup-menus (take a look at the widget tree in Glade) or the object specified by root.

  Returns:
    If the file was successfully loaded, this method returns self, otherwise the receiver is released and `nil` is returned.

- (BOOL) resolveReferences:(NSString *) name, ...

  This method can resolve several widget references with a single method call, so it can be used to avoid repeated invocations of -getWidget: (see below). It may be called with any number of name/ref_pointer pairs, followed by a single `nil` argument to terminate the variable argument list. A ref_pointer is the address of a variable of type `id`, `GTKObject *`, etc. (in fact, any pointer will do) where the result can be stored.

  The method tries to look up (by name) each widget in turn and stores the corresponding reference (or `nil` if a widget with this name could not be found) in the address that the following argument points to. If the ref_pointer for a given name is `NULL`, no value will be assigned. It is typically used like this:

       GTKWindow *my_window;
       GTKButton *ok, *cancel;

       [... resolveReferences:@"window", &my_window, @"ok_button", &ok,
          @"cancel_button", &cancel, nil];

  Returns:
    `YES` if all references could be resolved, `NO` otherwise

  See also: -getWidget:

- (GTKWidget *) getWidget:(NSString *) name

  Return the widget in the XML file with the name name, or `nil` if no such object exists.

- (GTKWidget *) getWidgetByLongName:(NSString *) name

  Return the widget in the XML file with the long name (including all its parent widget names, separated by periods) name, or `nil` if no such object exists.

generated Wed Jan 19 1:31:42 2000 by Objcdoc