PhabReadWidgetFile

Arguments

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.

Example

This example, ex_PhabReadWidgetFile.g, is included in the product distribution.

#!/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 the test window:
 * QNX4-WidgetFiles/wgt/readtestfile.wgtw for QNX 4, and
 * QNX6-WidgetFiles/wgt/readtestfile.wgtw for QNX 6.
 */

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(string(_os_, "-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