The Perl Toolchain Summit needs more sponsors. If your company depends on Perl, please support this very important event.

NAME

ZConf::GUI - A GUI backend chooser.

VERSION

Version 1.1.0

SYNOPSIS

    use ZConf::GUI;

    my $zg = ZConf::GUI->new();
    ...

METHODS

new

This initiates it.

One arguement is taken.

If this errors, it errors permanently.

hash args

zconf

A already initialized ZConf object.

    my $zg=ZConf::GUI->new({ zconf=>$zconf });
    if($zg->{error}){
        print "Error!\n";
    }

getAppendOthers

This gets the value for 'appendOthers'.

    my $appendOthers=$zg->getAppendOthers;
    if($zg->{error}){
        print "Error!\n";
    }

getPreferred

This gets the preferred for a module.

    my @prefs=$zg->getPreferred('ZConf::Runner');
    if($zg->{error}){
        print "Error!\n";
    }

getSet

This gets what the current set is.

    my $set=$zg->getSet;
    if($zg->{error}){
        print "Error!\n";
    }

getUseX

This fetches if X should be used or not for a module.

    $zcgui->getUseX('ZConf::Runner');
    if($zcgui->{error}){
        print "Error!";
    }

hasPreferred

This checks to make sure a module has any prefences or not. The returned value is a perl bolean value.

    my $returned=$zg->hasPreferred("ZConf::BGSet");

init

This initializes it or a new set.

If the specified set already exists, it will be reset.

One arguement is required and it is the name of the set. If it is not defined, ZConf will use the default one.

    #creates a new set named foo
    $zcw->init('foo');
    if($zg->{error}){
        print "Error!\n";
    }

    #creates a new set with ZConf choosing it's name
    $zg->init();
    if($zg->{error}){
        print "Error!\n";
    }

listAvailable

This is the available GUI modules for a module.

    my @available=$zg->listAvailable('ZConf::Runner');

listModules

This lists configured modules.

    my @modules=$zg->listModules;
    if($zg->{error}){
        print "Error!\n";
    }

listSets

This lists the available sets.

    my @sets=$zg->listSets;
    if($zg->{error}){
        print "Error!";
    }

readSet

This reads a specific set. If the set specified is undef, the default set is read.

    #read the default set
    $zg->readSet();
    if($zg->{error}){
        print "Error!\n";
    }

    #read the set 'someSet'
    $zg->readSet('someSet');
    if($zg->{error}){
        print "Error!\n";
    }

rmPreferred

This removes a the preferences for a module.

    $zg->rmPreferred('ZConf::BGSet');
    if($zg->{error}){
        print "Error:".$self->{error}.":".$self->{errorString};
    }

setAppendOthers

This sets the value for append others.

Only one value is accepted and that is a boolean value.

    $zg->setAppendOthers($boolean);
    if($zg->{error}){
        print "Error!\n";
    }

setPreferred

This sets the preferred GUI back ends. The first arguement is the module. The second is a array reference of the prefences.

    my @prefs=('GUI', 'Curses');
    #set it for ZConf::BGSet
    my $zg->setPreferred('ZConf::BGSet', \@prefs);

setUseX

This determines if X should be used or not. This only affects terminal related modules that respect this.

    $zcgui->setUseX('ZConf::Runner', '1');
    if($zcgui->{error}){
        print "Error!";
    }

termAvailable

This checks to see if a terminal is available. It checks if $ENV{TERM} is set or not. If this is not set, it was most likely not ran from with a terminal.

    if($zg->termAvailable){
        print "a terminal is available";
    }else{
        print "no terminal is available";
    }

Xavailable

This checks if X is available. This is checked for by trying to run '/bin/sh -c \'xhost 2> /dev/null > /dev/null\'' and is assumed if a non-zero exit code is returned then it failed and thus X is not available.

There is no reason to ever check $zcr->{error} with this as this function will not set it. It just returns a boolean value.

    if($zg->Xavailable()){
        print "X is available\n";
    }

useX

This checks to see if a terminal interface should try to use X or not by trying to spawn a X terminal.

This calls getUseX and if it is true, it calls Xavailable and returns it's value.

    my $useX=$zcgui->useX('ZConf::Runner');

which

This chooses which should be used. This returns all available backends in order of preference.

    my @choosen=$zg->which('ZConf::BGSet');
    if($zg->{error}){
        print "Error!";
    }

    print 'The primary preferred module is "'.$choosen[0].'"';

ERROR CODES/FLAGS HANDLING

This module Error::Helper for error handling.

1, zconf

ZConf error. Check $self->{zconf}->error.

2, missingArg

No module specified.

3, missingArg

No preferences specified.

4, colon

A preference matched /:/.

5, noPrefs

No preferences for the listed module.

6, lmFailed

'list_modules' failed.

7, modDNE

The specified module does not exist.

8, missingArg

No value for what to set appendOthers to specified.

9, notBoolean

The value specified for appendOthers is not boolean.

ZConf Keys

These are stored in config 'gui'.

Each preference is stored as a string for a module. Each preference is seperated as by ':'. The order of the preferred go from favorite to least favorite.

default

This is the default to use if nothing is setup for a module. The default value is 'GTK:Curses'.

appendOthers

If this is set to true, "1", when which is called, all the others will be appended after the list of available preferred ones.

If this is not defined, it will default to true.

modules/*

This contains the a list of preferences for a module.

The module name is converted to a ZConf variable name by replacing '::' with '/'.

useX/*

This is if a cuses module should use X or not. If it is true, it will pass

If if is not defined, it is set to true.

The module name is converted to a ZConf variable name by replacing '::' with '/'.

USING ZConf::GUI

A backend is considered to be any thing directly under <module>::GUI. How to call it or etc is directly up to the calling module though.

Any module using this, should have it's widgets and dialogs use a single hash for all it's arguements. This is currently not a requirement, but will be in future versions for future automated calling.

suggested methods

app

This initiates a application. If it is called, it is not expected to return.

hasApp

This quaries a module to check to see if it has a app.

dialogs

This returns a array of dialogs that can be called. These interupt execution till returned.

windows

This is a list of windows that can be created. These should return immediately after creating the window.

AUTHOR

Zane C. Bowers, <vvelox at vvelox.net>

BUGS

Please report any bugs or feature requests to bug-zconf-gui at rt.cpan.org, or through the web interface at http://rt.cpan.org/NoAuth/ReportBug.html?Queue=ZConf-GUI. I will be notified, and then you'll automatically be notified of progress on your bug as I make changes.

SUPPORT

You can find documentation for this module with the perldoc command.

    perldoc ZConf::GUI

You can also look for information at:

ACKNOWLEDGEMENTS

COPYRIGHT & LICENSE

Copyright 2009 Zane C. Bowers, all rights reserved.

This program is free software; you can redistribute it and/or modify it under the same terms as Perl itself.