NAME

QtCore4 - Perl bindings for the QtCore version 4 library

SYNOPSIS

use QtCore4;
use QtGui4;
my $app = Qt::Application(\@ARGV);
my $button = Qt::PushButton( 'Hello, World!', undef);
$button->show();
exit $app->exit();

DESCRIPTION

This module provides a Perl interface to the QtCore version 4 library.

EXPORTS

Each of the exported subroutines is prototyped.

qApp

Returns a reference to the Qt::CoreApplication/Qt::Application object. This mimics Qt's global qApp variable.

SIGNAL, SLOT

Used to format arguments to be passed to Qt::Object::connect().

emit

This subroutine is actually syntactic sugar. It is used to signify that the following subroutine call is activating a signal.

CAST REF,CLASSNAME

Serves a similar function to bless(), but takes care of Qt's specific quirks.

INTRODUCTION

This module provides bindings to the QtCore module of the Qt library from Perl. There are separate Perl modules for each Qt module, including QtGui, QtNetwork, QtXml, and QtTest. This document applies to all Qt4 and KDE4 modules.

The module has been designed to work like writing Qt applications in C++. However, a few things have been renamed. Everything is in the Qt:: namespace. This means that the first 'Q' in the Qt class name has been replaced with Qt::. So QWidget becomes Qt::Widget, QListView becomes Qt::ListView, etc. Also, for classes that use public data members, like QStyleOption and its subclasses, a set<PropertyName> method is defined to assign to those variables. For instance, QStyleOption has a 'version' property. To assign to it, call $option->setVersion( $value );

CONSTRUCTOR SYNTAX

A Qt object is constructed by calling a function called Qt::<ClassName>(), not Qt::<ClassName>->new(). For instance, to make a QApplication, call Qt::Application( \@ARGV );

SUBCLASSING

To create a subclass of a Qt class, declare a package, and then declare that package's base class by using QtCore4::isa and passing it an argument. Multiple inheritance is not supported. This package must implement a subroutine called NEW. The NEW method is the constructor for that class. The first argument to this method will be the name of the class being constructed, followed by the arguments passed to the constructor (just like in normal object-oriented Perl). The first thing that this method should do is call $class->SUPER::NEW(). This call constructs that parent's base class, and also sets the special this() value. You don't need to return anything from NEW(), PerlQt will return the value of this() to the caller, regardless of what is returned from NEW(). Any package that wants to use your subclass should explicitly 'use' it, even if the two packages are defined in the same file.

This is a stub of a class called 'MyWidget', that subclasses Qt::Widget: package MyWidget; use QtCore4; use QtCore4::isa qw( Qt::Widget );

sub NEW {
    my ( $class, $parent ) = @_;
    $class->SUPER::NEW( $parent );
}

package main;
use QtCore4;
use MyWidget;

my $app = Qt::Application(\@ARGV);
my $widget = MyWidget();
$widget->show();
exit $app->exec();

THE this() VALUE

In a subclass, you don't get a reference to $self. Instead, you use 'this'. Not '$this', just 'this'. In reality, it is a prototyped subroutine that returns a hash reference, but you should use it any place you would use $self. Since it is a hash reference, you can create hash keys and assign to them just like you would any other hashref.

REIMPLEMENTING C++ FUNCTIONS

To reimplement a C++ function in Perl, just declare a subroutine with the same name. Since that instance of the class can already get a reference to itself by calling 'this', it is not passed in as the first argument. If the C++ function takes 2 arguments, @_ will contain 2 items.

ABSTRACT CLASSES

You can subclass from an abstract class, but you must ensure that you implement all pure virtual methods. If a pure virtual function is called, and is not implemented, PerlQt will die with an error message telling you which function needs to be implemented.

PERL-SPECIFIC DOCUMENTATION

The following is a list of Perl-specific implementation details, broken up by class.

Global methods to all classes

getPointer

This method is used to retrieve an object's numeric memory location. It is defined in the Qt::base class, which all Qt objects inherit.

Currently, none of the classes that provided by this binding implement a method called getPointer(). But if one did, calling $object->getPointer() would not end up calling this method. To force this method to be called, you can call $object->Qt::base::getPointer().

Qt::Object

Qt::Object::findChildren()

Returns: An array reference of Qt::Objects

Args: $type: A string containing the Perl type name $name: The Qt::Object name to search for.

Description: Returns all children of this object with the given $name that inherit from type $type, or an empty list if there are no such objects. Omitting the $name argument causes all object names to be matched. The search is performed recursively. $type should be the Perl name for the type, not the C++ one (i.e. 'Qt::Object', not 'QObject').

Qt::Variant

According to the Qt documentation:

Because QVariant is part of the QtCore library, it cannot provide
conversion functions to data types defined in QtGui, such as QColor,
QImage, and QPixmap.  In other words, there is no toColor() function.
Instead, you can use the QVariant::value() or the qVariantValue() template
function.

PerlQt4 implements this functionality by supplying 2 functions, Qt::qVariantValue() and Qt::qVariantFromValue(). These two functions, in addition to handling the QtGui types, can also handle Perl hash references and array references. To accomplish this, 2 metatypes have been declared, called 'HV*' and 'AV*'.

Qt::qVariantValue()

Returns: An object of type $typename, or undef if the conversion cannot be made.

Args: $variant: A Qt::Variant object. $typename: The name of the type of data you want out of the Qt::Variant. This parameter is optional if the variant contains a Perl hash or array ref.

Description: Equivalent to Qt's qVariantValue() function. It is often easier to call value() on the Qt::Variant object, and let PerlQt return the correct type based on the Qt::Variant's type.

Qt::qVariantFromValue()

Returns: A Qt::Variant object containing a copy of the given value on success, undef on failure.

Args: $value: The value to place into the Qt::Variant.

Description: Equivalent to Qt's qVariantFromValue() function. If $value is a hash or array ref, and is not a PerlQt object, the resulting Qt::Variant will have it's typeName set to 'HV*' or 'AV*', respectively.

Qt::Variant::value()

Returns: The data contained within a Qt::Variant

Description: PerlQt reimplements this function to make it easier to all data types out of a variant (i.e. it is not limited to returning types from the QtCore module).

EXAMPLES

This module ships with a large number of examples. These examples have been directly translated to Perl from the C++ examples that ship with the Qt library. They can be accessed in the examples/ directory in the source tree.

SEE ALSO

The existing Qt documentation is very complete. Use it for your reference.

Get the project's current version at http://code.google.com/p/perlqt4/

AUTHOR

Chris Burel, <chrisburel@gmail.com>

COPYRIGHT AND LICENSE

Copyright (C) 2008-2010 by Chris Burel

Based on PerlQt3, Copyright (C) 2002, Ashley Winters <jahqueel@yahoo.com> Copyright (C) 2003, Germain Garand <germain@ebooksfrance.org>

Also based on QtRuby, Copyright (C) 2003-2004, Richard Dale

This library is free software; you can redistribute it and/or modify it under the same terms as Perl itself, either Perl version 5.8.8 or, at your option, any later version of Perl 5 you may have available.

cpanm Qt::base

perl -MCPAN -e shell
install Qt::base