NAME

X11::Wcl - Perl interface to the Widget Creation Library

SYNOPSIS

 use X11::Wcl;

DESCRIPTION

This module provides an interface to the Widget Creation Library. The Widget Creation Library is a C library that allows rapid prototyping of GUI interfaces using Xt-compatible toolkits. The module is a straightforward application of the SWIG interface generator, with very little custom-written code.

Look at the examples/ directory in the source code to see how to write a program using this module. A standard main routine is supplied by the package, the main difference from application to application being in the resource specifications and the callbacks.

STRUCTURE MEMBER FUNCTIONS

The module currently supplies object-oriented access to a number of X, Xt and Motif structures and constants. Several member functions have been provided for each structure to facilitate their manipulation in the SWIG environment.

CONSTRUCTORS

Special constructors were created for all wrapped structures provided by this module. Two different forms of object construction are supported.

•  C<$object = new StructureName;>
   C<$object = new StructureName(0);>
   C<$object = new StructureName(0, COUNT);>

  This form of constructor call creates a new object using calloc() that consists of a COUNT element array of the named structure type. If any arguments are omitted, an array size of 1 (a single struct) is assumed.

  The following code creates an array of 20 XrmOptionDescRec structures:

   $options = new XrmOptionDescRec(0, 20);

  The following code creates one XrmOptionDescRec structure:

   $options = new XrmOptionDescRec;

•  C<$object = new StructureName(INT);>
   C<$object = new StructureName(INT, COUNT);>

  This form of constructor call creates a new object that references memory that has already been allocated elsewhere. It is typically used in callback routines to convert the callback pointers passed to the callback routine into the appropriate type of PERL struct. INT is the memory address of the already allocated memory (existing C struct allocated by the X toolkit during a callback, for example). If COUNT is supplied, it is assumed that INT references an array of structs, and the struct at the provided index in the array is returned.

  The following code creates a CallbackStruct structure from the second argument passed to the routine:

   sub callback
   {
       my($widget, $arg1, $arg2, $arg3) = @_;
       $x = new CallbackStruct($arg2);
       print STDOUT $x->{field}, "\n";
       # etc.
   }

DESTRUCTOR

The destructor function for each structure knows how to destroy a structure when it is no longer needed. It takes into account the different kinds of construction that are possible.

ARRAY INDEXING

 $object->idx(INT);

This member function assumes that $object is actually an array of existing objects, and returns the object residing at the provided integer index.

Here is an example of how to initialize an array of 20 structures, using the idx() member function:

 # create array of 20 structures
 $options = new StructureName(0, 20);
 # now initialize them
 for ($i=0; $i<20; ++$i) {
     $x = $options->idx($i);
     $x->{field} = "value"
 }

CALLBACK FUNCTIONS

Callbacks invoked by the GUI interface are written in PERL. All PERL callback functions are passed four arguments when they are invoked:

1. The first argument is the widget associated with the callback, of type Widget.

2. The second argument is a string that contains the data appearing in the X resource specification that caused the callback to be invoked.

3. The third argument is an integer that is the address of the callback structure passed to the callback by the invoking widget. You normally will typecast this to the appropriate type so you can get to details about the event causing the callback.

4. The fourth argument is the PERL object that was passed (if any) when the callback routine was registered using X11::Wcl::WcRegisterCallback().

See the examples supplied with this module for details on what to do with callback function arguments.

GLOBAL FUNCTIONS

 WcRegisterCallback($app_context, $callback_name, $function, $arg)

The WcRegisterCallback() function is a wrapper function that works almost the same way as its namesake in the Widget Creation Library. It expects the first argument to be the application context, which it simply passes down to the C routine. The second argument is a string that provides the name of the callback routine as it appears in X resources. The third argument should be a PERL function reference. The final argument is optional, can be any PERL scalar or reference, and is passed to the callback when it is invoked.

 WcAddEditResSupportToShell($shell)

The WcAddEditResSupportToShell() function adds support for the editres protocol to the shell widget supplied as an argument. This allows easy examination of the widget tree using the editres program, among other things.

 preprocess($string)

This function performs preprocessing on the argument string and returns the result. The syntax is similar that of the C preprocessor, with #if, #else, and #endif being understood. The argument to #if is expected to be a PERL expression.

 MakeXt*Proc($perl_function_name)

One MakeXt*Proc() function is created for each Xt*Proc function pointer typedef found in the Xt header files when the X11::Wcl module is built. Each function takes the name of a PERL function as an argument, and returns a function pointer suitable for use with a Xt call that requires a function pointer of the associated type. No arguments are currently passed to the PERL function when it is invoked.

Because of the way this is implemented, you can only make a finite number of Xt*Proc PERL functions. The default as shipped is 25 max.

 mainloop(TAG => VALUE, ...)

This function implements a standard main loop for X11::Wcl applications. See the X11/Wcl.pm file for documentation on this function.

RESOURCE SPECIFICATION

The whole point of the Widget Creation Library is to make it possible to specify widget trees and widget resources using X resource files, without writing any C or C++ code. Read the Widget Creation Library documentation for details on the resources that control its operation, and the documentation on the Motif widgets for details on what they expect.

The Widget Creation Library was originally designed to use files to specify resource values. To fit better with PERL, a syntax extension was created to cause PERL variables to be used instead of files.

The usual syntax for a resource file specification is:

 *resourceFile: some_file_name

As a special case, when the file name begins with a dollar sign, resources are instead read from the named PERL variable. So, for example, the following resource specifies that variable "main::x" contains the resources to be used:

 *resourceFile: $main::x

The variable should hold a string that contains X resource specifications in the usual X resource syntax.

AUTHORS

 "David E. Smyth" (Widget Creation Library)
 "David M. Beazley" <dmb@asator.lanl.gov> (SWIG)
 "Joseph H. Buehler" <jhpb@sarto.gaithersburg.md.us> (X11::Wcl module)

SEE ALSO

 Widget Creation Library documentation.
 Motif toolkit documentation.
 SWIG documentation.
 examples supplied with this module.
 perl(1).

cpanm X11::Wcl

perl -MCPAN -e shell
install X11::Wcl