PhabAttachWidgets

Gamma/Photon: Using Gamma™ with the Photon microGUIŽ, Version 4.0
Prev |  | Next

# `PhabAttachWidgets`

`PhabAttachWidgets` -- assigns widgets to a class as instance variables.

## Syntax

    PhabAttachWidgets (class, filename)

## Arguments

`filename`

  The name of a widget file, including a pathname if necessary.

`class`

  The name of a class.

## Returns

A definition for the `.PhabInstantiate` method of the `class`, in Lisp syntax.

## Description

This function reads a widget file create in PhAB and constructs a template that can be used to create a window. Any named widget becomes an instance variable of the `class`, and can be accessed as such. This function is similar to `PhabLoad`, but it provides more flexibility, since it creates globally-defined class with instance variables corresponding to each widget, rather than having each widget be defined by a global variable. It can also be used to create multiple instances of a group of widgets within a single window, as explained below.

The class gets created with three class variables: `PhabInstantiate` (holds the `.PhabInstantiate` method explained below), `_phab_template` (location and other information on widgets in the widget hierarchy), and `_phab_template_file` (path and file name of the widget file).

There are three steps involved in using this function:

1. Create a class that the widgets will be assigned to.

2. Call the `PhabAttachWidgets` function with that class as a parameter.

3. Instantiate the widgets using the `.PhabInstantiate` method that gets created by the function.

### `The .PhabInstantiate method`

#### Syntax

    .PhabInstantiate(use_root)

#### Arguments

`use_root` | A flag that (set to `t` or `nil`) specifies whether the root widget (generally the main window) will be used.

#### Returns

The widget hierarchy on success, else `nil`.

#### Description

This method is required to instantiate the widgets attached by `PhabAttachWidgets`. You can call it at any time so long as you have an instance of a class that has been modified by `PhabAttachWidgets`. We suggest putting `.PhabInstantiate` in the constructor because it needs to be called even when constructing classes that are derived from your "Phab window" class.

## Example

These examples, `ex_PhabAttachWidgets.g` and `ex_PhabAttachWidgets2.g`, are included in the `gamma_ph_`#`_examples_1_QNX4.tgz` file available on the Cogent Web Site.

This example, `ex_PhabAttachWidgets.g`, sets the `use_root` parameter of `.PhabInstantiate` to `t` (true), which causes the widgets to appear in their original window.

    #!/usr/cogent/bin/phgamma

    /* This example creates a class, attaches widgets from a Phab
     * file to the class, and sets up a constructor for the class that
     * instantiates the widgets.  Then it demonstrates how the widgets
     * are now accessible as instance variables of the class. */

    PtInit(nil);
    require_lisp("PhabTemplate.lsp");

    /* Create the class.*/
    class DemoWindow
    {
      window;
    }

    /* Attach the widgets to the class. */
    PhabAttachWidgets (DemoWindow, "WidgetFiles/wgt/loadwindow.wgtw");

    /* Set up the constructor to instantiate the widgets inside the window. */
    method DemoWindow.constructor ()
    {
      .window = PhabRoot(.PhabInstantiate (t));
    }

    /* Create a new instance of the class and realize it. */
    load_win = new (DemoWindow);
    PtRealizeWidget (load_win.window);

    /* Change the text string and assign a callback to a button
     * by calling the widgets as instances of the load_win class.*/
    load_win.PtButtonTwo.text_string = "Exit";
    PtAttachCallback(load_win.PtButtonTwo, Pt_CB_ACTIVATE, #exit_program(-1));

    PtMainLoop();

This example, `ex_PhabAttachWidgets2.g`, sets the `use_root` parameter of `.PhabInstantiate` to `nil` (false), which gives you the freedom to put the widgets in any container, and/or to put multiple copies of them into the same containiner.

    #!/usr/cogent/bin/phgamma

    /* This example creates a class, attaches widgets from a Phab
     * file to the class, and sets up a constructor for the class that
     * instantiates the widgets.  Then it demonstrates how the widgets
     * are now accessible as instance variables of the class. */

    PtInit(nil);
    require_lisp("PhabTemplate.lsp");
    require_lisp("PhotonWidgets.lsp");

    /* Create the class.*/
    class DemoWidgets
    {
      widgets;
    }

    /* Attach the widgets to the class. */
    PhabAttachWidgets (DemoWidgets, "WidgetFiles/wgt/loadwindow.wgtw");

    /* Set up the constructor to instantiate the widgets, but not in a window. */
    method DemoWidgets.constructor ()
    {
      .widgets = PhabChildren(.PhabInstantiate (nil));
    }

    /* Create a window to hold instances of the class. */
    window = new(PtWindow);
    window.SetDim(500, 200);
    window.fill_color = 0xaaccdd;

    /* Create two instances of the class. */
    dwidgets1 = new (DemoWidgets);

    PtSetParentWidget(window);
    dwidgets2 = new (DemoWidgets);
    dwidgets2.MainPane.SetPos(260, 23);

    /* Change the text string and assign a callback to a button
     * by calling the widgets as instances of the DemoWidgets class.*/
    dwidgets1.PtButtonTwo.text_string = "Exit";
    PtAttachCallback(dwidgets1.PtButtonTwo, Pt_CB_ACTIVATE, #exit_program(-1));

    PtRealizeWidget (window);
    PtMainLoop();

## See Also

PhabLoad

Prev | Home | Next
PhAB Functions | Up | `PhabChildren`

Copyright 1995-2002 by Cogent Real-Time Systems, Inc.