PhabReadWidgetFile

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

# `PhabReadWidgetFile`

`PhabReadWidgetFile` -- loads and accesses widget definitions.

## Syntax

    PhabReadWidgetFile (filename)
    PhabGetTop (definition)
    PhabGetRoot (tree)
    PhabGetChildren (tree)
    PhabGetLevel (root)
    PhabGetType (root)
    PhabGetName (root)
    PhabGetResources (root)

## Arguments

`filename`

  The name of the file to read (usually a .wgtw file), optionally including a path, written as a string.

`definition`

  A widget definition as returned by a call to `PhabReadWidgetFile`.

`tree`

  A widget definition tree.

`root`

  A widget definition root as returned by a call to `PhabGetRoot`.

## Returns

`PhabReadWidgetFile` returns a list of widget definitions, usually consisting of just one member, the first-level tree of widget definitions; or nil.

`PhabGetTop` returns the first tree of the widget definition hierarchy (which is usually the window and all the widgets it contains), or nil. This function effectively removes the outer parentheses of the definition list returned by `PhabReadWidgetFile`.

`PhabGetRoot` returns the definition of a widget without its children, or nil.

`PhabGetChildren` returns a list of the children of a widget definition tree, or nil.

The four remaining functions return the level, type, name, and resources of a widget, or nil.

## Description

These functions are all related. Their pupose is to read a .wgtw file and access various parts of the widget definition hierarchy. This allows you to easily duplicate and reuse widgets (with or without their children) for various applications, using `PhabCreateWidgets`.

To use these functions, you must load the `PhabTemplate.lsp` library with a call to `require_lisp("PhabTemplate.lsp")`. To find the `.wgtw` file, `PhabReadWidgetFile` first searches the current directory, and if unsuccessful, it searches the require path (see the `_require_path_` discussion in `require`).

A widget definition hierarchy has a regular structure, which is a nested hierarchy of lists. This allows easy access to any widget, using car, cdr, nth-car and nth-cdr. In fact, as you can see in the example, the `PhabGet`- functions are simply wrappers for combinations of `car` and `cdr`.

Table 1. Elements of a Widget Hierarchy

Element | Syntax | Description
--- | --- | ---
Definition | (tree) | A list with one member, which is the main tree of the entire widget hierarchy.
Tree | (root [tree]...) | A list containing one root and zero or more trees.
Root | (level type name resources) | The definition of a single widget, without its children, expressed as a list.
Children | ([tree]...) | A list of zero or more trees, without a root.
Level | integer | The level of the widget in the tree hierarchy.
Type | symbol | The type of widget.
Name | symbol | The name of the widget instance.
Resources | [((number . value)...)] | An association (assoc) list in which the first element of each pair is the photon resource number, and the second element is the value assigned to that resource.

## Example

This example, `ex_PhabReadWidgetFile.g`, is included in the `gamma_ph_`#`_examples_1_QNX4.tgz` file available on the Cogent Web Site.

    #!/usr/cogent/bin/phgamma

    /*
     * This example reads and prints a widget file locating each widget and
     * printing its level, type, and name on one line, followed by its resources.
     * The program reads a file name from the command line, using the argument
     * (cadr(argv)). Our test file is a window that contains one button and
     * two panes, each of which also contain buttons. If no name is entered as an
     * argument on the command line, the default is: WidgetFiles/wgt/readtestfile.wgtw.
     */

    PtInit(nil);

    /*
     * Define some PhabGet_ functions. (These are scheduled to be added as
     * library functions in the near future).
     */
    PhabGetTop = car;
    PhabGetRoot = car;
    PhabGetChildren = cdr;
    PhabGetLevel = car;
    PhabGetType = cadr;
    PhabGetName = caddr;
    function PhabGetResources (wgt)
    {
      caddr(cdr(wgt));
    }

    require_lisp("PhotonWidgets");
    require_lisp("PhabTemplate");

    /*
     * Read and print the complete widget file definition.
     */
    if (cadr(argv))
      defs = PhabReadWidgetFile(cadr(argv));
    else
      defs = PhabReadWidgetFile("WidgetFiles/wgt/readtestfile.wgtw");

    pretty_princ("The widget definition is:\n", defs, "\n\n");

    tree = PhabGetTop(defs);

    /*
     * Make a function that deconstructs the widget file definition,
     * extracting each widget definition in turn, and identifying
     * each part of each definition.
     */
    function print_tree(tree)
    {
      local root = PhabGetRoot(tree);
      local level = PhabGetLevel(root);
      local type = PhabGetType(root);
      local name = PhabGetName(root);
      local resources = PhabGetResources(root);

      princ("The ", name, " widget is type ", type, " at level ",
            level, ". \nIts resources are: \n");
      pretty_princ(resources, "\n");

      local children = PhabGetChildren(tree);
    	if (children)
    	{
    		pretty_princ("Its children are:\n", children, "\n\n");
    	}
    	else princ("It has no children.\n\n");

      with child in children do {
        print_tree(child);
      }
    }

    /*
     * Call the function, then create and realize the widgets as an illustration.
     */
    print_tree(tree);

    NewWindow = car(car(PhabCreateWidgets(defs, nil, nil)));
    NewWindow.SetPos(250,50);

    PtRealizeWidget(NewWindow);

    PtMainLoop();

Output:

        The widget definition is:
        (((1 PtWindow MyTestFile
             ((1005 . {PhPoint (x . 400) (y . 350)}) (2002 . 12632256)
              (2006 . 6316128) (18015 . Main Window) (1008 0 . -1)))
          ((2 PtButton MainWindowButton
              ((3011 . Press Main)
               (1007 . {PhPoint (x . 41) (y . 59)})
               (1005 . {PhPoint (x . 67) (y . 19)}))))
          ((2 PtPane PaneOne
              ((1005 . {PhPoint (x . 235) (y . 170)}) (1006 1280 . -1) (1001 . 1)
               (1007 . {PhPoint (x . 161) (y . 1)}) (2002 . 16768701)))
           ((3 PtButton PaneOneButtonA
               ((3011 . Press A)
        	(1007 . {PhPoint (x . 61) (y . 31)})
        	(1005 . {PhPoint (x . 48) (y . 19)}))))
           ((3 PtButton PaneOneButtonB
               ((3011 . Press B)
        	(1007 . {PhPoint (x . 62) (y . 79)})
        	(1005 . {PhPoint (x . 48) (y . 19)})))))
          ((2 PtPane PaneTwo
              ((1005 . {PhPoint (x . 235) (y . 170)}) (1006 1280 . -1) (1001 . 1)
               (1007 . {PhPoint (x . 161) (y . 176)}) (2002 . 16760286)))
           ((3 PtButton PaneTwoButtonC
               ((3011 . Press C)
        	(1007 . {PhPoint (x . 69) (y . 42)})
        	(1005 . {PhPoint (x . 48) (y . 19)})))))))

        The MyTestFile widget is type PtWindow at level 1.
        Its resources are:
        ((1005 . {PhPoint (x . 400) (y . 350)}) (2002 . 12632256) (2006 . 6316128)
         (18015 . Main Window) (1008 0 . -1))
        Its children are:
        (((2 PtButton MainWindowButton
             ((3011 . Press Main)
              (1007 . {PhPoint (x . 41) (y . 59)})
              (1005 . {PhPoint (x . 67) (y . 19)}))))
         ((2 PtPane PaneOne
             ((1005 . {PhPoint (x . 235) (y . 170)}) (1006 1280 . -1) (1001 . 1)
              (1007 . {PhPoint (x . 161) (y . 1)}) (2002 . 16768701)))
          ((3 PtButton PaneOneButtonA
              ((3011 . Press A)
               (1007 . {PhPoint (x . 61) (y . 31)})
               (1005 . {PhPoint (x . 48) (y . 19)}))))
          ((3 PtButton PaneOneButtonB
              ((3011 . Press B)
               (1007 . {PhPoint (x . 62) (y . 79)})
               (1005 . {PhPoint (x . 48) (y . 19)})))))
         ((2 PtPane PaneTwo
             ((1005 . {PhPoint (x . 235) (y . 170)}) (1006 1280 . -1) (1001 . 1)
              (1007 . {PhPoint (x . 161) (y . 176)}) (2002 . 16760286)))
          ((3 PtButton PaneTwoButtonC
              ((3011 . Press C)
               (1007 . {PhPoint (x . 69) (y . 42)})
               (1005 . {PhPoint (x . 48) (y . 19)}))))))

        The MainWindowButton widget is type PtButton at level 2.
        Its resources are:
        ((3011 . Press Main)
         (1007 . {PhPoint (x . 41) (y . 59)})
         (1005 . {PhPoint (x . 67) (y . 19)}))
        It has no children.

        The PaneOne widget is type PtPane at level 2.
        Its resources are:
        ((1005 . {PhPoint (x . 235) (y . 170)}) (1006 1280 . -1) (1001 . 1)
         (1007 . {PhPoint (x . 161) (y . 1)}) (2002 . 16768701))
        Its children are:
        (((3 PtButton PaneOneButtonA
             ((3011 . Press A)
              (1007 . {PhPoint (x . 61) (y . 31)})
              (1005 . {PhPoint (x . 48) (y . 19)}))))
         ((3 PtButton PaneOneButtonB
             ((3011 . Press B)
              (1007 . {PhPoint (x . 62) (y . 79)})
              (1005 . {PhPoint (x . 48) (y . 19)})))))

        The PaneOneButtonA widget is type PtButton at level 3.
        Its resources are:
        ((3011 . Press A)
         (1007 . {PhPoint (x . 61) (y . 31)})
         (1005 . {PhPoint (x . 48) (y . 19)}))
        It has no children.

        The PaneOneButtonB widget is type PtButton at level 3.
        Its resources are:
        ((3011 . Press B)
         (1007 . {PhPoint (x . 62) (y . 79)})
         (1005 . {PhPoint (x . 48) (y . 19)}))
        It has no children.

        The PaneTwo widget is type PtPane at level 2.
        Its resources are:
        ((1005 . {PhPoint (x . 235) (y . 170)}) (1006 1280 . -1) (1001 . 1)
         (1007 . {PhPoint (x . 161) (y . 176)}) (2002 . 16760286))
        Its children are:
        (((3 PtButton PaneTwoButtonC
             ((3011 . Press C)
              (1007 . {PhPoint (x . 69) (y . 42)})
              (1005 . {PhPoint (x . 48) (y . 19)})))))

        The PaneTwoButtonC widget is type PtButton at level 3.
        Its resources are:
        ((3011 . Press C)
         (1007 . {PhPoint (x . 69) (y . 42)})
         (1005 . {PhPoint (x . 48) (y . 19)}))
        It has no children.

## See Also

PhabCreateWidgets

Prev | Home | Next
`PhabReadWidget` | Up | `PhabReadWidgets`

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